title | description | keywords | sidebar_position | ||||
---|---|---|---|---|---|---|---|
Payment |
Information about native token payments on an external chain. |
|
5 |
import StandardAddressHash from "./_standard_address_hash.mdx"; import StandardPaymentReference from "./_standard_payment_reference.mdx"; import TransactionSuccessStatus from "./_transaction_success_status.mdx"; import Finality from "./_finality.mdx";
Information about a transaction on an external chain that is classified as a native currency payment. Each supported blockchain specifies how a payment transaction should be formatted to be provable using this attestation type. These provable payments mimic traditional banking transactions where entity A sends a native currency to entity B, with an optional payment reference.
Network Type | Supported Chains |
---|---|
Mainnet | BTC (Bitcoin), DOGE (Dogecoin), XRP (XRP Ledger) |
Testnet | testBTC (Bitcoin Testnet v3), testDOGE , testXRP |
Field | Solidity Type | Description |
---|---|---|
transactionId |
bytes32 |
Unique ID of the payment transaction. |
inUtxo |
uint256 |
For UTXO-based chains, this is the index of the transaction input associated with the source address. Set to 0 for non-UTXO chains. |
utxo |
uint256 |
For UTXO-based chains, this is the index of the transaction output associated with the receiving address. Set to 0 for non-UTXO chains. |
Field | Solidity Type | Description |
---|---|---|
blockNumber |
uint64 |
The block number in which the transaction is included. |
blockTimestamp |
uint64 |
The timestamp of the block containing the transaction. |
sourceAddressHash |
bytes32 |
Standardized address hash of the source address. |
sourceAddressesRoot |
bytes32 |
The root of the Merkle tree of the source addresses. |
receivingAddressHash |
bytes32 |
Standardized address hash of the receiving address. Returns a zero 32-byte string if the transaction status is not successful. |
intendedReceivingAddressHash |
bytes32 |
Standardized address hash of the intended receiving address if the transaction failed. |
spentAmount |
int256 |
Amount (in minimal units) spent by the source address. |
intendedSpentAmount |
int256 |
Intended amount (in minimal units) to be spent by the source address, relevant if the transaction status is unsuccessful. |
receivedAmount |
int256 |
Amount (in minimal units) received by the receiving address. |
intendedReceivedAmount |
int256 |
Intended amount (in minimal units) to be received by the receiving address if the transaction failed. |
standardPaymentReference |
bytes32 |
Standard payment reference. |
oneToOne |
bool |
Indicates if the transaction involves only one source and one receiver. |
status |
uint8 |
Transaction success status. |
:::warning[Standard Payment Reference]
If a transaction has no standardPaymentReference
, it is set to default value, thus, zero value reference should be used with caution.
:::
- The transaction identified by
transactionId
is fetched from the relevant blockchain node or indexer. - If the transaction cannot be retrieved or is in a block with insufficient confirmations, the attestation request is rejected.
- Once the transaction data is fetched, a payment summary is computed according to the chain-specific rules.
- If the payment summary is successfully generated, the response is populated using this data.
- If the summary cannot be computed, the attestation request is rejected.
- The fields
blockNumber
andblockTimestamp
are extracted from the block data if they are not directly available in the transaction data.- For Bitcoin and Dogecoin, the
blockTimestamp
is derived from the mediantime of the block. - For XRPL, the
blockTimestamp
is derived from the close time of the ledger, converted to UNIX time.
- For Bitcoin and Dogecoin, the
:::note[Lowest used timestamp]
For the lowestUsedTimestamp
parameter, the blockTimestamp
of the transaction is used.
:::
A payment summary consolidates all relevant data about a transaction that represents a payment. This is particularly focused on payments between one source account (address) and one target account.
- UTXO Blockchains (e.g., BTC, DOGE): Payments can aggregate inputs from multiple addresses and distribute them to multiple outputs. The summary here is computed based on specified input and output indices that identify addresses of interest.
- XRPL: Supports various transaction types, but a payment summary is only fully calculated for transactions of type
Payment
.
The summary includes the fields detailed in the table below. The interpretation of certain fields may vary based on the blockchain. Chain-specific explanations are provided in the sections that follow.
Field | Description |
---|---|
transactionId |
The unique identifier of the transaction. |
transactionStatus |
The success status of the transaction. |
standardPaymentReference |
A reference defined in the standard payment reference. |
oneToOne |
Indicates if the transaction involves a single sender and a single receiver. |
sourceAddress |
The originating address involved in the transaction. |
sourceAddressesRoot |
The root of the Merkle tree of the source addresses. |
spentAmount |
The total amount spent by the source address. |
intendedSourceAmount |
The expected amount intended to be sent from the source address. |
receivingAddress |
The target address receiving the payment. |
intendedReceivingAddress |
The expected target address intended to receive the payment. |
receivedAmount |
The actual amount received by the receiving address. |
intendedReceivingAmount |
The expected amount intended to be received. |
:::note
- Standard Address Hashes: Standard address hashes can be derived from addresses.
- If
transactionStatus
is notSUCCESS
, thereceivingAddress
is set to an empty string, and its hash defaults to a zeroed 32-byte string. - Standard Addresses Root is the root of the Merkle tree build on double keccak256 hashes of the all source addresses of the transaction.
:::
The payment summary for Bitcoin and Dogecoin is derived using specified indices for a transaction input and output.
- If the specified input or output does not exist, or lacks an address (e.g., outputs using
OP_RETURN
), no summary is generated. - Coinbase transactions are not summarized.
- For Bitcoin, all transaction details are retrieved using the
getrawtransaction
endpoint (verbosity 2) andgetblock
. This requires a Bitcoin node version ≥ 25.0. - For Dogecoin, since
getrawtransaction
with verbosity 2 is not supported, alternative methods must be used to access input transaction data.
Field | Description |
---|---|
transactionId |
The transaction ID (txid ). For SegWit transactions, this differs from hash . |
oneToOne |
true if only sourceAddress is present in inputs, and outputs include only receivingAddress , sourceAddress (for change), or OP_RETURN . |
sourceAddress |
Address of the specified input. |
spentAmount |
Total value of all inputs with sourceAddress minus total value of all outputs to sourceAddress . |
intendedSourceAmount |
Same as spentAmount . |
receivingAddress |
Address of the specified output. |
intendedReceivingAddress |
Always matches receivingAddress . |
receivedAmount |
Total value of outputs to receivingAddress minus total value of inputs from receivingAddress . |
intendedReceivingAmount |
Same as receivedAmount . |
The payment summary on XRPL is applicable only for transactions of type Payment
.
- Only
Payment
transactions are summarized; other transaction types are ignored. - A successful payment has exactly one sender and at most one receiver. If unsuccessful, no receiver is recorded.
- Transaction details are obtained via the
tx
method. - Changes made by the transaction are recorded in the
meta
field (ormetaData
if fetched via theledger
method) underAffectedNodes
. Balance changes are found withinModifiedNodes
, by comparingFinalFields
andPreviousFields
.
Field | Description |
---|---|
transactionId |
Transaction hash found in the hash field. |
oneToOne |
Always true , as each Payment transaction has exactly one sender and at most one receiver. |
sourceAddress |
Address that sent the payment, reducing its balance. |
spentAmount |
Amount by which sourceAddress 's balance was reduced. |
intendedSourceAmount |
Calculated as Amount + Fee . If transactionStatus is SUCCESS , it matches spentAmount . |
receivingAddress |
Address that received the payment. If unsuccessful, this is an empty string. |
intendedReceivingAddress |
Address specified in the Destination field. |
receivedAmount |
Amount by which the receivingAddress 's balance was increased. Can be zero if the transaction failed. |
intendedReceivingAmount |
Expected increase in intendedReceivingAddress 's balance if successful. Found in the Amount field. Matches spentAmount if successful. |
For the complete interface definition, see IPayment
.