Transactors
Understanding the lifecycle of a transaction
Transactions are the fundamental mechanism through which the XRP Ledger evolves. Every payment, every offer, every trust line modification—each begins as a transaction that must be validated, authorized, and applied to the shared ledger state. Without a deep understanding of how transactions flow through the system, building reliable XRPL applications or contributing to the protocol itself becomes guesswork.
Module overview
This module dissects how rippled processes transactions from the moment they arrive until they permanently alter ledger state. You'll follow a transaction through its complete journey: initial syntax validation, signature verification, ledger-state preconditions, and the atomic application of changes. Along the way, you'll understand the safeguards that prevent invalid or malicious transactions from corrupting the ledger. The core objective is to give you a complete mental model of transaction processing so that you can confidently implement new transaction types, debug validation failures, and reason about how state changes propagate through the XRPL.
In this module
Understanding the Transactor Architecture
You'll explore the layered design of rippled's transaction engine, examining how each processing phase contributes to the safety and correctness of ledger modifications.
The Transactor base class establishes the common interface and shared logic that all transaction types inherit, providing consistent fee handling, sequence number management, and result code propagation.
The processing pipeline reveals the four distinct phases—preflight, preclaim, doApply, and finalization—each with specific responsibilities and failure modes.
Ledger state interaction demonstrates how transactions read from and write to SLE (Serialized Ledger Entry) objects through views, ensuring atomic and reversible modifications.
Result codes (TER) communicate success, failure, and retry conditions, guiding both the consensus process and client applications.
Through hands-on exercises, you'll trace transactions end-to-end, implement validation logic, and understand how the engine rolls back partial changes when errors occur. You'll learn to navigate the transactor codebase, interpret result codes, and understand the patterns that ensure ledger integrity even under adversarial conditions.
This practical foundation is essential for anyone looking to implement custom transaction types, audit existing transaction logic, or contribute directly to the rippled codebase.
Learning objectives
Processing Pipeline
Master the four-phase model—preflight (context-free validation), preclaim (ledger-state checks), doApply (state modification), and result finalization.
Transactor Hierarchy
Navigate the base Transactor class and understand how specific transaction types like Payment, OfferCreate, and TrustSet extend it.
Fee and Sequence Handling
Understand how transaction fees are consumed, sequence numbers are enforced, and account reserves are validated.
TER Result Codes
Decode the taxonomy of result codes—tesSUCCESS, tec* (claimed cost failures), tef* (local failures), tem* (malformed), and ter* (retry).
State Modification Patterns
Learn how transactions interact with ledger objects through views, enabling atomic commits and rollbacks.
Codebase Navigation
Locate key transactor components in src/xrpld/app/tx/ and understand their interactions within the engine.
