Transactions on the XRP Ledger

Overview

In the last module you saw that almost everything the XRPL does (payments, tokens, trades, NFTs) is reachable as a native transaction type. A transaction is the only way to change the ledger: nothing moves, mints, or settles without one. This module explains that idea in detail: what a transaction actually contains, how it's checked, and where it ends up.

By the end you'll know the anatomy of a transaction, how transaction types and flags combine into features, the three-phase lifecycle every transaction runs through, why transactions are ordered the way they are, and what a single ledger version holds.

What is a transaction?

On any blockchain, a transaction is a signed instruction that moves the ledger from its current state to a new one, and it is the only way a new state can be produced. Sending a payment, minting an NFT, and placing an offer on the exchange are all transactions. Each transaction has a type, which defines the scope of the change: what it may create or modify, and which fields it edits. Transactions are applied one at a time, so every node computes the same next state and the ledger stays consistent. On the XRPL these types are native to the protocol, one for each operation, as the next sections explain in detail.

The anatomy of a transaction

Content by Chris Dangerfield, licensed under CC BY-SA 4.0

Every transaction, whatever it does, is built the same way: a set of common fields that all transactions share, plus additional fields determined by its transaction type.

A few common fields show up on everything you'll send:

• Account: the address initiating the transaction, the one whose signature authorizes it.
• TransactionType: what kind of operation this is (Payment, OfferCreate, and so on), which decides the additional fields.
• Fee: a small amount of XRP destroyed as the cost of the transaction; it is not paid to anyone, it simply deters spam.
• Sequence: a per-account counter that orders your transactions and stops the same one from being applied twice.

The additional fields are the specifics: a Payment needs a destination and an amount, an OfferCreate needs the two assets to trade. Same envelope, different payload.

Transaction types are the building blocks of features

A transaction type is one specific operation with its own purpose and its own schema of fields. It's the smallest unit of change on the ledger, and most real features are built by combining several of them.

Take the life of an NFT. There's no single "sell an NFT" instruction; instead you compose the flow from smaller types:

• NFTokenMint: create the NFT on the ledger.
• NFTokenCreateOffer: list it for sale at a price.
• NFTokenAcceptOffer: complete the transfer to the buyer.

That's the pattern across the protocol: escrows, trust lines, and offers are each assembled from a handful of purpose-built transaction types rather than one catch-all command.

Flags: changing behaviour without new types

Sometimes you don't need a whole new transaction type to change what a transaction does: you just need to flip a switch. Flags are exactly that: options that modify a transaction's behaviour, and because each is a single bit, you can combine several at once.

NFTokenMint, for instance, carries flags that shape the NFT it creates:

• tfTransferable: whether the NFT can change hands later; with it off, the token is non-transferable.
• tfBurnable: whether the issuer is allowed to burn it after minting.

Flags keep the protocol lean: one transaction type can cover many variations of an operation, instead of a separate type for every combination.

The transaction lifecycle

Before a transaction is allowed to touch the ledger, it runs through three phases. The order matters: each does more than the one before, so obviously bad transactions are rejected early and cheaply.

• Preflight: local, semantic validation. Are the required fields present, the data types correct, the values sensible? This needs nothing but the transaction itself.
• Preclaim: contextual validation with read-only access to the current ledger state. Does the account exist, does it hold enough XRP for the fee and reserve, are the prerequisites for this operation met?
• DoApply: the phase that actually modifies the ledger: it updates balances, creates or changes objects, and triggers whatever the transaction was for.

The three-phase transaction lifecycle: preflight for local semantic checks, preclaim for contextual read-only checks against ledger state, and doApply which modifies the ledger.

Only a transaction that clears preflight and preclaim reaches DoApply, and only DoApply can change anything: a clean split between "is this valid?" and "make it happen".

How transactions are ordered

When a ledger closes, every validator has to apply its transactions in some order, and they must all pick the same order, or they'd compute different results. The XRPL solves this with a deterministic canonical order.

Rather than ordering by arrival time (which every server sees slightly differently), it sorts by a key derived from the account combined with the parent ledger's hash, then by each account's Sequence, then by the transaction ID. The parent hash is the clever part: it changes every ledger, is identical for all validators, and is unknown at the moment you submit.

The result is an order that is fair and unpredictable (nobody can buy priority or reliably front-run someone else) while staying perfectly deterministic, so every honest validator reconstructs the exact same sequence.

Canonical ordering derives an ordering key from the account and the parent ledger hash, then the account sequence, then the transaction ID, making order fair, unpredictable, and deterministic.

What's inside a ledger

Content by Chris Dangerfield, licensed under CC BY-SA 4.0

Those ordered transactions are applied to produce a new ledger version, the "block" of the XRP Ledger. Each one has four parts:

• Header: the ledger's sequence number, its own hash, the parent ledger's hash, the close time, and flags.
• State map: the current state of everything, from accounts and trust lines to NFTs and escrows.
• Transactions map: the set of transactions applied in this ledger.
• Rules and fees: the network settings in force, including the current fee and reserve.

A ledger version holds a header, a state map of all current objects, a transactions map of applied transactions, and the network rules and fees, chained to the previous ledger by its parent hash.

Because each header records the parent hash, every ledger points back to the one before it, chaining them together the way blocks do on other chains, an unbroken, tamper-evident history.

You now know what a transaction is and how it's checked, ordered, and stored. Time to stop reading about them and write some: next you'll go on-chain, building and submitting real transactions in code.

A quick wrap-up

Content by Chris Dangerfield, licensed under CC BY-SA 4.0

In short, this module covered:

• A transaction is the only way to change the ledger. Every one shares the common fields (Account, TransactionType, Fee, Sequence) plus additional fields set by its type.
• Features are assembled from purpose-built transaction types, and flags adjust a transaction's behaviour without needing new types.
• Every transaction runs through three phases: preflight (local checks), preclaim (read-only checks against ledger state), and doApply, the only phase that modifies the ledger.
• Transactions are applied in a deterministic canonical order derived from the parent ledger's hash, which keeps ordering fair and front-running hard.
• A ledger version holds a header, the state map, the transactions map, and the network rules, chained to its parent by hash.