Introduction to XRP Transactions
XRP, the digital asset native to the XRP Ledger, is designed for fast and efficient transactions. Understanding its technical underpinnings is crucial for developers and advanced users. This guide breaks down the structure, parameters, and processes involved in a typical XRP transaction.
Prerequisites for XRP Transactions
Before initiating any transaction on the XRP Ledger, several key requirements must be met.
- The base unit for XRP is 1,000,000 drops. All transaction amounts and fees are specified in drops.
- A minimum transaction amount of 0.01 XRP is enforced. Attempting to send less will result in a local signing failure.
- New XRP addresses require a reserve of 20 XRP to be activated before they can transact.
- After any transaction, an address's balance must remain above the 20 XRP minimum reserve. If a transaction would reduce the balance below this threshold, it will be rejected by the network.
Structural Anatomy of an XRP Transaction
XRP transactions are structured using a Tag-Value (TV) format, where each field is defined by a type and a key.
Field Type Definitions
The protocol defines specific types for different kinds of data within a transaction.
#define XRP_FIELD_TYPE_INT16 @"1"
#define XRP_FIELD_TYPE_INT32 @"2"
#define XRP_FIELD_TYPE_AMOUNT @"6"
#define XRP_FIELD_TYPE_VL @"7"
#define XRP_FIELD_TYPE_ACCOUNT @"8"Common Transaction Field Encodings
For a standard Payment transaction, the key field encodings within the transaction domain are as follows:
@"account": @{@"type": XRP_FIELD_TYPE_ACCOUNT, @"key": @(1)},
@"type": @{@"type": XRP_FIELD_TYPE_INT16, @"key": @(2)},
@"flags": @{@"type": XRP_FIELD_TYPE_INT32, @"key": @(2)},
@"sequence": @{@"type": XRP_FIELD_TYPE_INT32, @"key": @(4)},
@"amount": @{@"type": XRP_FIELD_TYPE_AMOUNT, @"key": @(1)},
@"fee": @{@"type": XRP_FIELD_TYPE_AMOUNT, @"key": @(8)},
@"signingPubKey": @{@"type": XRP_FIELD_TYPE_VL, @"key": @(3)},
@"txnSignature": @{@"type": XRP_FIELD_TYPE_VL, @"key": @(4)},
@"destination": @{@"type": XRP_FIELD_TYPE_ACCOUNT, @"key": @(3)},
@"lastLedgerSequence": @{@"type": XRP_FIELD_TYPE_INT32, @"key": @(27)}Calculating the Tag Value
The final tag for each field is computed by combining its type and key. The following Objective-C code snippet demonstrates this calculation.
- (void)write_typeWithTransactionData:(NSMutableData *)transaction sourceDicr:(NSDictionary *)sourceDicr
{
if ([sourceDicr[@"key"] intValue] <= 0xf) {
int mark = ([sourceDicr[@"type"] intValue] << 4) | [sourceDicr[@"key"] intValue];
[transaction appendInt8:mark];
}else{
[transaction appendInt8:[sourceDicr[@"type"] intValue] << 4];
[transaction appendInt8:[sourceDicr[@"key"] intValue]];
}
}Key Transaction Parameters Explained
Beyond the standard fields, one parameter is critical for managing transaction certainty.
The LastLedgerSequence Parameter
LastLedgerSequence is an optional but highly recommended parameter for all transactions.
- Its primary purpose is to prevent a transaction from remaining in an unconfirmed state indefinitely, which can happen if the fee is set too low.
- This field specifies the maximum ledger index in which the transaction can be included. If the network reaches this ledger height without confirming the transaction, the transaction is effectively canceled, and the sender can safely re-attempt the transfer.
- The value should be set to the current ledger index plus a buffer (e.g., 1000). This means the transaction must be confirmed within the next 1000 ledgers; otherwise, it fails predictably, providing clarity to the user.
A Practical Transaction Example
Let's deconstruct a real-world transaction scenario to see these principles in action.
Transaction Scenario:
- Transaction Type: Payment
- Sending Address: rfXSBUpv9Yr41q5qFGRo9LJi1Jbe1wNEFe
- Receiving Address: rHXKdQhjXUtotW3yaofmu3YyuSZ2FXfxFC
- Fee: 0.01 XRP
- Amount: 0.01 XRP
- Memo: "" (Empty string)
Raw Unsigned Transaction Data (Hex):5354580012000022800000002400000007201b0000000b614000000000002710684000000000002710732103e7dfa41a3e7f626c5c0d1a2d8c0b1ac3baf6039bef1d1996993dc8f9dc816d3c811447923fc967fed6a696ec0cd3e2ae852901a9e8698314b53e0a778749318b634d1ed7c25667bb2b2412a3
Deconstructing the Transaction Data
Parsing the hexadecimal data reveals the individual components of the transaction.
53545800 // Signature preamble marker
12 // TransactionType tag (Payment)
0000 // TransactionType value
22 // Flags tag
80000000 // Flags value (2147483648 in hex)
24 // Sequence tag
00000007 // Sequence value
20 // LastLedgerSequence type segment
1b // LastLedgerSequence key
026F2922 // LastLedgerSequence value (latest ledger + buffer)
61 // Fee tag
4000000000002710 // Fee value
68 // Amount tag
4000000000002710 // Amount value
73 // PublicKey tag
21 // PublicKey length
03e7dfa41a3e7f626c5c0d1a2d8c0b1ac3baf6039bef1d1996993dc8f9dc816d3c // PublicKey
81 // Account tag
14 // Account length
47923fc967fed6a696ec0cd3e2ae852901a9e869 // Account (PublicKey Hash160)
83 // Destination tag
14 // Destination length
b53e0a778749318b634d1ed7c25667bb2b2412a3 // Destination (PublicKey Hash160)Broadcasting the Transaction to the Network
Once signed, the transaction is broadcast to the XRP Ledger network for inclusion in a ledger.
The Signed Transaction Blob
The final, signed transaction ready for broadcast is a longer hex string that includes the signature.
12000022800000002400000007201B026F2922614000000000002710684000000000002710732103E7DFA41A3E7F626C5C0D1A2D8C0B1AC3BAF6039BEF1D1996993DC8F9DC816D3C744630440220725C375C8332302013F3E3B29C668400FB799A8D8315CFBF8C7E09BD2000FA3902207800E6E06E1A5719B3B0970C10C49FCFDEBFFEB3067209BB0B5619E5DBFBC8A2811447923FC967FED6A696EC0CD3E2AE852901A9E8698314B53E0A778749318B634D1ED7C25667BB2B2412A3
Parsing the Signed Transaction
The broadcast blob includes the original fields plus the crucial signature data.
(The parsed structure is similar to the unsigned version but includes a 74 Signing Info tag followed by the length and data of the cryptographic signature, which validates the transaction.)
Network Response Scenarios
The network responds with a result object indicating success or failure.
Success Response:
A tesSUCCESS result code indicates the transaction was accepted and applied to the ledger. The response includes the transaction's hash (its unique ID) and a full JSON representation of the validated transaction.
Failure Response:
Failures can occur for various reasons. A tefMAX_LEDGER error indicates the LastLedgerSequence was exceeded before the transaction was confirmed. Other common errors include tefALREADY (transaction duplicate) or tefPAST_SEQ (sequence number too low). 👉 Explore more strategies for handling failed transactions.
Frequently Asked Questions
What is the minimum amount of XRP I can send?
The absolute minimum transaction amount is 0.01 XRP. This is a network rule to prevent spam and ensure efficient ledger operation. Transactions for less than this amount will fail during the signing process.
Why does a new XRP address require a 20 XRP reserve?
The reserve is a security feature of the XRP Ledger. It prevents malicious actors from generating millions of empty accounts and spamming the network, thereby protecting the integrity and performance of the ledger for all users.
What happens if my transaction fails because of a low fee?
If your fee is too low, validators will prioritize other transactions. If you included a LastLedgerSequence parameter, the transaction will eventually be canceled after that sequence is passed, allowing you to re-submit it with a higher fee.
How does the LastLedgerSequence parameter improve reliability?
It provides transaction finality. Without it, a transaction with a low fee could remain in a pending state indefinitely, creating uncertainty. This parameter sets a hard deadline, ensuring you get a definitive success or failure outcome within a known timeframe.
What is the difference between 'tef', 'tem', and 'ter' result codes?Tef (transaction failed) errors occur after submission but before consensus. Tem (transaction error malformed) means the transaction was invalid and not processed. Ter (transaction error retry) indicates a temporary failure, suggesting you should try again later.
Can I add a memo to an XRP transaction?
Yes, the XRP Ledger supports adding memos to transactions for additional information like payment references or exchange order IDs. This is done using the Memos field in the transaction structure, which was left empty in our example.