# 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 →](/core-dev-bootcamp/module03bis/transactor-architecture.md) *** #### 🔄 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` [Explore Processing Pipeline →](/core-dev-bootcamp/module03bis/processing-pipeline.md) *** #### 📊 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` [Explore TER Result Codes →](/core-dev-bootcamp/module03bis/ter-result-codes.md) *** #### 💾 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 →](/core-dev-bootcamp/module03bis/state-modification.md) *** #### 💰 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 →](/core-dev-bootcamp/module03bis/fee-sequence-handling.md) *** ## 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 →](/core-dev-bootcamp/module03bis/case-study-checkcreate.md) *** ### Homework This module includes practical exercises to reinforce your understanding: * [**Homework 1: Trace a Payment Transaction**](/core-dev-bootcamp/module03bis/homework1.md) - 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**](/core-dev-bootcamp/module03bis/homework2.md) - 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**](/core-dev-bootcamp/module03bis/homework3.md) - 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. [Submit Feedback →](https://docs.google.com/forms/d/e/1FAIpQLSe7qIbqepUKGVJxmWFHv0rs1zsBAzk8G6y5-bfz0Yd5rqW_5A/viewform) *** ### Navigation ➡️ **Next Module**: Cryptography I: [Blockchain Security and Cryptographic Foundations →](/core-dev-bootcamp/module04.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xrpl-commons.org/core-dev-bootcamp/module03bis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.