Skip to content

Commit 72f546a

Browse files
fasskofassko
authored
feat(docs): introduce XRPL payment attestation types and interfaces (#1353)
1 parent 31e41ce commit 72f546a

5 files changed

Lines changed: 590 additions & 3 deletions

File tree

‎docs/fdc/3-attestation-types.mdx‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,31 @@ sidebar_position: 3
66
---
77

88
import DocCardList from "@theme/DocCardList";
9+
import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
910

10-
**FDC Attestations** provide cryptographic proofs for data originating outside Flare's EVM state. They enable smart contracts to verify external data trustlessly. For example, FDC attestations can validate:
11+
**FDC Attestations** provide cryptographic proofs for data originating outside Flare's EVM state.
12+
They enable smart contracts to verify external data trustlessly.
13+
For example, FDC attestations can validate:
1114

1215
- **Non-Payment Verification:** Confirm whether a payment **has not been made** on a UTXO chains like Bitcoin or Dogecoin.
1316
- **Event Log Authentication:** Verify event logs generated by transactions on EVM-compatible blockchains.
1417

15-
FDC currently supports the following six attestation types:
18+
export const AttestationTypeLists = () => {
19+
const items = useCurrentSidebarCategory().items;
20+
const isXrp = (item) =>
21+
/\/xrp-payment(-nonexistence)?$/.test(item.docId ?? item.href ?? "");
22+
const general = items.filter((item) => !isXrp(item));
23+
const xrp = items.filter(isXrp);
24+
return (
25+
<>
26+
<h2>General attestation types</h2>
27+
<DocCardList items={general} />
28+
<h2>XRPL specific attestation types</h2>
29+
<DocCardList items={xrp} />
30+
</>
31+
);
32+
};
1633

17-
<DocCardList />
34+
FDC currently supports the following attestation types:
35+
36+
<AttestationTypeLists />

‎docs/fdc/attestation-types/xrp-payment-nonexistence.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: XRPPaymentNonexistence
3+
description: An XRP payment matching memo data and/or destination tag was not made by the deadline.
4+
keywords: [fdc, oracle, flare-data-connector, flare-network, xrpl]
5+
sidebar_position: 9
6+
---
7+
8+
Assertion that **no** XRP Ledger `Payment` transaction matching the specified destination, amount, memo, and/or destination tag was confirmed in the given block range.
9+
10+
`XRPPaymentNonexistence` differs from the chain-agnostic [`ReferencedPaymentNonexistence`](/fdc/attestation-types/referenced-payment-nonexistence.mdx) in how the payment is matched: instead of a [standard payment reference](/fdc/attestation-types/referenced-payment-nonexistence.mdx#standard-payment-reference), matches use the **hash of the first Memo's `MemoData`** and/or the **`DestinationTag`** — the two fields XRPL applications natively use to correlate payments.
11+
This makes it suited for invoicing flows where payers identify themselves via a destination tag, as well as for memo-based protocols.
12+
13+
## Supported chains
14+
15+
| Network Type | Supported Chains |
16+
| ------------ | ------------------------ |
17+
| **Mainnet** | `XRP` (XRP Ledger) |
18+
| **Testnet** | `testXRP` (XRPL Testnet) |
19+
20+
## Request
21+
22+
| Field | Solidity Type | Description |
23+
| ------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| `minimalBlockNumber` | `uint64` | The starting ledger of the search range (inclusive). |
25+
| `deadlineBlockNumber` | `uint64` | The ledger to be included as the end of the search range. |
26+
| `deadlineTimestamp` | `uint64` | The timestamp to be included as the end of the search range. |
27+
| `destinationAddressHash` | `bytes32` | The [standard address hash](/fdc/attestation-types/payment.mdx#standard-address-hash) of the expected receiver. |
28+
| `amount` | `uint256` | The required payment amount in drops. |
29+
| `checkFirstMemoData` | `bool` | If `true`, the first Memo's `MemoData` hash must match `firstMemoDataHash` for a transaction to be considered a match. |
30+
| `firstMemoDataHash` | `bytes32` | The [standard hash](/fdc/attestation-types/payment.mdx#standard-address-hash) of the expected first Memo's `MemoData`. Considered only when `checkFirstMemoData` is `true`. |
31+
| `checkDestinationTag` | `bool` | If `true`, the transaction's `DestinationTag` must equal `destinationTag` for a transaction to be considered a match. |
32+
| `destinationTag` | `uint256` | The expected destination tag. Considered only when `checkDestinationTag` is `true`. XRPL only supports `uint32` values. |
33+
| `proofOwner` | `address` | Address authorized to use the proof, where applicable. The verifier lower-cases this value. |
34+
35+
:::warning[At least one match field is required]
36+
37+
At least one of `checkFirstMemoData` or `checkDestinationTag` must be `true`.
38+
If both are `false`, the request would match any sufficiently-sized payment to the destination, which is rarely intended.
39+
40+
:::
41+
42+
## Response
43+
44+
| Field | Solidity Type | Description |
45+
| ----------------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
46+
| `minimalBlockTimestamp` | `uint64` | The timestamp of the ledger at `minimalBlockNumber`. |
47+
| `firstOverflowBlockNumber` | `uint64` | The first ledger with both `blockNumber > deadlineBlockNumber` and `timestamp > deadlineTimestamp`. |
48+
| `firstOverflowBlockTimestamp` | `uint64` | The timestamp of `firstOverflowBlockNumber`. |
49+
50+
The search range covers ledgers from `minimalBlockNumber` (inclusive) to `firstOverflowBlockNumber` (exclusive).
51+
52+
## Verification process
53+
54+
1. **Range validation**: If `minimalBlockNumber` or `deadlineBlockNumber` is negative or unreasonably large, the request is rejected.
55+
If `firstOverflowBlock` cannot be determined or lacks the required [confirmations](#finality), the request is rejected.
56+
If `minimalBlockNumber >= firstOverflowBlockNumber`, the request is rejected.
57+
2. **Visibility**: If the verifier does not have a complete view of the search range, the request is rejected.
58+
3. **Match scan**: A transaction is considered a **match** (and would invalidate the nonexistence claim) when **all** of the following hold:
59+
- The transaction is of type `Payment` and has a successful payment summary with one sender and one receiver.
60+
- The receiver's [standard address hash](/fdc/attestation-types/payment.mdx#standard-address-hash) equals `destinationAddressHash`.
61+
- The intended receiving amount is **greater than or equal to** `amount`.
62+
- The transaction did not fail with `SENDER_FAILURE` (so `SUCCESS` and `RECEIVER_FAILURE` outcomes both qualify, mirroring [`ReferencedPaymentNonexistence`](/fdc/attestation-types/referenced-payment-nonexistence.mdx#account-based-chains-xrpl) on XRPL).
63+
- If `checkFirstMemoData` is `true`: the standard hash of the first Memo's `MemoData` (or the standard hash of an empty value when no memo is present) equals `firstMemoDataHash`.
64+
- If `checkDestinationTag` is `true`: the transaction has a destination tag, and it equals `destinationTag`.
65+
4. **Confirmation**: The request is confirmed if **no** transaction in the search range matches all applicable criteria.
66+
67+
:::note[Lowest used timestamp]
68+
69+
For the `lowestUsedTimestamp` parameter, the value of `minimalBlockTimestamp` is used.
70+
71+
:::
72+
73+
## Finality
74+
75+
XRPL ledgers must reach the required confirmation depth before the search range can be considered complete.
76+
77+
| Chain | `chainId` | Confirmations required | Confirmation time |
78+
| ----- | --------- | ---------------------- | ----------------- |
79+
| XRPL | 3 | 3 | ≈12 seconds |
80+
81+
## Contract Interface
82+
83+
For the complete interface definition, see [`IXRPPaymentNonexistence`](/fdc/reference/IXRPPaymentNonexistence.mdx).

‎docs/fdc/attestation-types/xrp-payment.mdx‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: XRPPayment
3+
description: Information about an XRP Ledger payment, including memo data and destination tag.
4+
keywords: [fdc, oracle, flare-data-connector, flare-network, xrpl]
5+
sidebar_position: 8
6+
---
7+
8+
import TransactionSuccessStatus from "./_transaction_success_status.mdx";
9+
10+
Information about a `Payment` transaction on the **XRP Ledger** transferring native XRP from a source address to a receiving address.
11+
12+
Unlike the chain-agnostic [`Payment`](/fdc/attestation-types/payment.mdx) attestation type, `XRPPayment` exposes XRPL-specific fields directly in the response: the source `r`-address (XRPL addresses) as a string, raw bytes of the first Memo's `MemoData`, and the destination tag.
13+
This avoids the need for off-chain helpers when a consumer contract needs to act on these fields.
14+
15+
## Supported chains
16+
17+
| Network Type | Supported Chains |
18+
| ------------ | ------------------------ |
19+
| **Mainnet** | `XRP` (XRP Ledger) |
20+
| **Testnet** | `testXRP` (XRPL Testnet) |
21+
22+
## Request
23+
24+
| Field | Solidity Type | Description |
25+
| --------------- | ------------- | ------------------------------------------------------------------------------------------- |
26+
| `transactionId` | `bytes32` | ID of the payment transaction. |
27+
| `proofOwner` | `address` | Address authorized to use the proof, where applicable. The verifier lower-cases this value. |
28+
29+
## Response
30+
31+
| Field | Solidity Type | Description |
32+
| ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
33+
| `blockNumber` | `uint64` | Number of the ledger in which the transaction is included. |
34+
| `blockTimestamp` | `uint64` | The timestamp of the ledger, derived from `close_time` converted to UNIX time. |
35+
| `sourceAddress` | `string` | The XRPL `r`-address of the source. |
36+
| `sourceAddressHash` | `bytes32` | [Standard address hash](#standard-address-hash) of the source address. |
37+
| `receivingAddressHash` | `bytes32` | Standard address hash of the receiving address. Zero `bytes32` if `status` is not success. |
38+
| `intendedReceivingAddressHash` | `bytes32` | Standard address hash of the intended receiving address (the `Destination` field). Relevant when the transaction failed. |
39+
| `spentAmount` | `int256` | Amount in drops actually spent by the source address. |
40+
| `intendedSpentAmount` | `int256` | Amount in drops the source intended to spend (`Amount + Fee`). Relevant when the transaction failed. |
41+
| `receivedAmount` | `int256` | Amount in drops received by the receiving address. |
42+
| `intendedReceivedAmount` | `int256` | Amount in drops the receiving address would have received had the transaction succeeded. |
43+
| `hasMemoData` | `bool` | `true` if the transaction has a `MemoData` field. |
44+
| `firstMemoData` | `bytes` | Raw bytes of the `MemoData` field of the **first** Memo. Empty when `hasMemoData` is false. |
45+
| `hasDestinationTag` | `bool` | `true` if the transaction has a destination tag. |
46+
| `destinationTag` | `uint256` | Destination tag of the transaction. `0` when `hasDestinationTag` is false. XRPL currently only supports `uint32` destination tags. |
47+
| `status` | `uint8` | [Transaction success status](#transaction-success-status). |
48+
49+
:::note[Differences from `Payment`]
50+
51+
`XRPPayment` is XRPL only and replaces the `inUtxo` / `utxo` request fields with `proofOwner`.
52+
The response drops `standardPaymentReference`, `oneToOne`, and `sourceAddressesRoot` (always implied for XRPL Payment transactions) and adds `sourceAddress`, `hasMemoData`, `firstMemoData`, `hasDestinationTag`, and `destinationTag`.
53+
54+
:::
55+
56+
## Verification process
57+
58+
1. The transaction identified by `transactionId` is fetched from an XRPL node or indexer via the [`tx`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/transaction-methods/tx) method.
59+
2. If the transaction cannot be retrieved, or its ledger lacks the required [confirmations](#finality), the request is rejected.
60+
3. A [payment summary](/fdc/attestation-types/payment.mdx#payment-summary) is computed for the transaction.
61+
- Only XRPL transactions of type `Payment` produce a summary; other types are rejected.
62+
- A successful payment has exactly one sender and at most one receiver.
63+
Multi-output payments are rejected.
64+
4. `blockNumber` and `blockTimestamp` are extracted from the ledger if not present in the transaction data.
65+
`blockTimestamp` is the ledger `close_time` converted to UNIX time.
66+
5. The first Memo's `MemoData` (if any) and the `DestinationTag` (if any) are surfaced unchanged in the response.
67+
68+
:::note[Lowest used timestamp]
69+
70+
For the `lowestUsedTimestamp` parameter, the `blockTimestamp` of the transaction is used.
71+
72+
:::
73+
74+
## Transaction success status
75+
76+
<TransactionSuccessStatus />
77+
78+
## Standard address hash
79+
80+
The **standard address hash** is the `keccak256` hash of the XRPL standard address as a string:
81+
82+
```solidity
83+
keccak256(standardAddress)
84+
```
85+
86+
XRPL `r`-addresses are case-sensitive, so the address has a single canonical form (no lower-casing applied).
87+
88+
**Example:**
89+
90+
| Chain | Standard Address | Standard Address Hash |
91+
| ----- | ------------------------------------ | -------------------------------------------------------------------- |
92+
| XRPL | `rDsbeomae4FXwgQTJp9Rs64Qg9vDiTCdBv` | `0xa491aed10a1920ca31a85ff29e4bc410705d37d4dc9e690d4d500bcedfd8078f` |
93+
94+
## Finality
95+
96+
XRPL ledgers must reach the required confirmation depth before the transaction can be proven.
97+
98+
| Chain | `chainId` | Confirmations required | Confirmation time |
99+
| ----- | --------- | ---------------------- | ----------------- |
100+
| XRPL | 3 | 3 | ≈12 seconds |
101+
102+
## Contract Interface
103+
104+
For the complete interface definition, see [`IXRPPayment`](/fdc/reference/IXRPPayment.mdx).

0 commit comments

Comments
 (0)