Transactors: Understanding the Lifecycle of a Transaction
Module Overview
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.
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.
What You Will Learn
By completing this module, you will be able to:
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
Explore the Topics
This module is organized into two parts: Theory covering the generic transactor architecture and processing model, and Case Studies providing detailed walkthroughs of specific transaction implementations.
Part I: Theory
🏗️ Transactor Architecture
The foundation of transaction processing in rippled
Explore the layered design of rippled's transaction engine and how each component 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.
Key Topics: Transactor base class, inheritance hierarchy, ApplyContext, transaction type registration
Codebase: src/xrpld/app/tx/detail/Transactor.h, src/xrpld/app/tx/detail/Transactor.cpp
Explore Transactor Architecture →
🔄 Processing Pipeline
The four-phase transaction validation model
Understand the processing pipeline that reveals the four distinct phases—preflight, preclaim, doApply, and finalization—each with specific responsibilities and failure modes. Learn when each phase executes, what information it can access, and how errors propagate through the system.
Key Topics: Preflight validation, preclaim checks, doApply execution, result finalization, error propagation
Codebase: src/xrpld/app/tx/detail/applySteps.cpp, src/xrpld/app/tx/detail/apply.cpp
📊 TER Result Codes
The language of transaction outcomes
Result codes (TER) communicate success, failure, and retry conditions, guiding both the consensus process and client applications. Master the complete taxonomy of result codes and understand what each category means for transaction processing and application behavior.
Key Topics: tesSUCCESS, tec* codes, tef* codes, tem* codes, ter* codes, fee claiming
Codebase: src/libxrpl/protocol/TER.cpp, include/xrpl/protocol/TER.h
💾 State Modification Patterns
Atomic ledger updates through views
Ledger state interaction demonstrates how transactions read from and write to SLE (Serialized Ledger Entry) objects through views, ensuring atomic and reversible modifications. Learn the patterns that guarantee ledger integrity even when transactions fail mid-execution.
Key Topics: OpenView, ApplyView, SLE objects, keylets, atomic commits, rollbacks
Codebase: src/libxrpl/ledger/View.cpp, src/libxrpl/ledger/ApplyView.cpp
Explore State Modification Patterns →
💰 Fee and Sequence Handling
Economic controls and ordering guarantees
Understand the mechanisms that ensure transactions are properly ordered and that network resources are appropriately compensated. Learn how fees are calculated, validated, and consumed, and how sequence numbers prevent replay attacks and ensure transaction ordering.
Key Topics: Base fees, fee escalation, sequence numbers, tickets, account reserves
Codebase: src/xrpld/app/tx/detail/Transactor.cpp, src/xrpld/app/misc/detail/TxQ.cpp
Explore Fee and Sequence Handling →
Part II: Case Studies
✅ Case Study: CheckCreate Transactor
A complete walkthrough of a transaction implementation
Follow the CheckCreate transaction through the complete processing pipeline, from preflight validation through final state modification. This case study demonstrates all the best practices for implementing a transactor: flag validation, field validation, ledger state checks, freeze checks, reserve management, directory management, and ledger entry creation.
Key Topics: Feature checks, flag validation, amount validation, destination checks, trustline freeze checks, expiration validation, reserve checks, SLE creation, directory insertion, owner count adjustment
Codebase: src/xrpld/app/tx/detail/CreateCheck.cpp, src/xrpld/app/tx/detail/CreateCheck.h
Explore CheckCreate Case Study →
Homework
This module includes practical exercises to reinforce your understanding:
Homework 1: Trace a Payment Transaction - Use logging and debugging to trace a Payment transaction through all four phases and document the state changes at each step.
Homework 2: Implement a Custom Validation Check - Add a custom preflight or preclaim check to an existing transactor and verify it works correctly with unit tests.
Homework 3: Analyze TER Code Paths - Map out the conditions that lead to different TER codes for the Payment transactor and create a decision tree.
Questions
If you have any questions about the homework or would like us to review your work, feel free to contact us.
Navigation
➡️ Next Module: Cryptography I: Blockchain Security and Cryptographic Foundations →
Last updated