1 of 100

Trainings

Welcome

This is the home of the XRPL Commons technical trainings. This space aims to showcase all content related to training on the XRPL.

Available resources

The following links are the key tools in your journey on the XRP ledger.

Ecosystem map: https://map.xrpl-commons.org

Block explorer: https://testnet.xrpl.org

Faucets: https://xrpl.org/resources/dev-tools/xrp-faucets/

Transactions references: https://xrpl.org/docs/references/protocol/transactions/types/

Training live sync: https://trainings.xrpl.at/training (password is training-april-2024)

XRPL Basics

In this section we will cover some of the primary functionality of the XRPL ledger.

Getting Started

Start here :)

First, you will want to set up your coding environment.

Any JavaScript editor will work, and feel free to use your own Node environment to follow along with JavaScript. Most of the code we will use can be run client side as well.

For a hassle-free setup, use Replit (). Accounts are free. Create a new Replit with the TypeScript defaults, or use the Node defaults if you prefer to avoid TypeScript.

If you use another language, you can follow along with your own script, but you will need the appropriate SDK, which may differ from xrpl.js.

You will often need to refer to the main API documentation for transactions here: https://xrpl.org/docs/references/protocol/transactions/types/

Reading and subscribing to Transactions

In this session, we'll demonstrate how to coordinate using the XRPL.

The XRPL is a public ledger, meaning that when you write on-chain, anyone can read it. In this session, we will demonstrate how to subscribe to events as they happen on-chain.

First, we will create a pair of accounts:

Check the logs to find the seed for both accounts. We will use these later to reuse the accounts deterministically.

Creating a payment transaction

Here is how to generate a payment transaction between the two accounts.

Insert the seeds from the previous section in the top section.

Reading transactions

One way to retrieve transactions for a given account is to create a request for transactions. Here is an example

Listening for transactions

Finally, we will demonstrate how to listen for transactions affecting a given account to catch all transactions.

You could use this to build a notification bot that alerts you when any activity occurs in your account.

You can subscribe to an account, to trigger on each transaction for instance. This is how you would listen to a specific account.

Non Fungible Tokens

In this session, we will learn how to create digital art using Non-Fungible Tokens (NFTs) with their metadata and specific attributes.

Start coding

Create a new file or edit index.ts

Running this to ensure everything works should log a few things to the console. If you are running this from your node environment, don't forget to runnpm i xrpl to add it to your project.

Token Issuance and Liquidity

This session will cover token issuance and providing liquidity for your tokens using the automatic market maker built in to the XRPL

Creating Accounts

Before we get into the heart of the matter, lets setup a few wallets.

Creating wallets

Let's add some wallet creation logic. We might as well create two wallets for some fun.

At this point, we should have two wallets with balances of 100 XRP.

We will save these in a more convenient way to reuse them as we progress through this tutorial.

Collect the seed values from the logs for both accounts, and let's create wallets from those seeds from now on. We'll need an issuer and a receiver so here we go:

First, we set the seed in the code

Issuing Tokens

In this section we will create fungible tokens or IOUs and transfert them between accounts.

Creating tokens

Dealing with token codes

Token codes can be three letters or a padded hex string. Here is a convenience function to enable codes longer than three letters. This needs to be done to work with our training app, so you will want to include this in your code. This could easily be done via an import for instance, or placed in the index.ts file directly.

Creating an AMM Pool

Now we will create an AMM Pool to provide some liquidity for our new token.

Create an AMM Pool

Now that the receiver has tokens, we can use the receiver's account to create an AMM. Note that this is the usual architecture where the issuer account solely issues the token, and other proprietary accounts hold the token and can create liquidity.

For this example, we will use pools that have XRP as one side.

Here is the createAMM.ts file:

The final main function index.ts should now look like this:

Cyphered Chat on XRPL

Send encrypted messages over XRPL

This session will explore how to use the memo field present on every transaction on the XRP Ledger to send encrypted messages, effectively creating a chat engine.

While nothing is encrypted forever, we propose this activity to explore the basic principles of cryptography and using the memo field.

Set up

Description of key libraries

To build our encrypted messaging system, we'll be using these key JavaScript libraries:

xrpl: The official XRPL client library to interact with the XRP Ledger
tweetnacl: For encryption/decryption operations using the NaCl cryptographic library

Set up Keys

First, we need to get the public key of the person we want to chat with. To do so, we can go on the block explorer and look at the transactions the address has sent. From there, by looking at the raw transaction data, we can find their public key. Once we have their public key, we can use it to encrypt messages that only they can decrypt.

Then we need to set up our wallet to cypher the message and send the tx

Cypher the message

Now that we have their public key, we can encrypt our secret message. Remember our "outside-in" principle: we use THEIR public (outside) key to encrypt the message, which ensures that only THEIR private (inside) key can decrypt it. The message gets transformed into a scrambled format that is completely unreadable to anyone who might intercept it - only the owner of the matching private key can convert it back to the original text. Each encrypted message is unique, even if you encrypt the same text multiple times, adding an extra layer of security.

import tweetnacl from 'tweetnacl';
import { Buffer } from "buffer";
import { Wallet } from "xrpl";
import {
  edwardsToMontgomeryPub,
  edwardsToMontgomeryPriv,
} from "@noble/curves/ed25519";

const { box, randomBytes } = tweetnacl;

/**
 * Encrypts a message using X25519 (Montgomery curve) for Diffie-Hellman key exchange
 *
 * @param message - Plain text message to encrypt
 * @param recipientPublicKey - Recipient's Ed25519 public key (hex encoded)
 * @param senderSecretKey - Sender's Ed25519 private key (hex encoded)
 * @returns JSON string containing base64 encoded encrypted message and nonce
 *
 * Steps:
 * 1. Convert hex keys to byte arrays
 * 2. Generate random nonce for uniqueness
 * 3. Convert message to bytes
 * 4. Convert Ed25519 keys to X25519 (Montgomery) format for encryption
 * 5. Encrypt using NaCl box with converted keys
 * 6. Return encrypted message and nonce as base64 JSON
 */
export function encryptMessage(
  message: string,
  recipientPublicKey: string,
  senderSecretKey: string,
): string {
  const pubKeyBytes = Buffer.from(recipientPublicKey.slice(2), "hex");
  const secretKeyBytes = Buffer.from(senderSecretKey.slice(2), "hex");

  const nonce = randomBytes(box.nonceLength);
  const messageUint8 = Buffer.from(message);

  const pubKeyCurve = edwardsToMontgomeryPub(pubKeyBytes);
  const privKeyCurve = edwardsToMontgomeryPriv(secretKeyBytes);

  const encryptedMessage = box(messageUint8, nonce, pubKeyCurve, privKeyCurve);

  return JSON.stringify({
    encrypted: Buffer.from(encryptedMessage).toString("base64"),
    nonce: Buffer.from(nonce).toString("base64"),
  });
}

function main() {
  const recipientPublicKey ="Recipient pubkey goes here";
  const myWallet = Wallet.fromSeed("your seed goes here");

  const cypheredMessage = encryptMessage(
    "Hello World",
    recipientPublicKey,
    myWallet.privateKey,
  );
  console.log(cypheredMessage);
}

main();

Set up the memo & send the tx

Now that we have our encrypted message, we can send it through the XRPL network. We'll create a transaction with a minimal amount (1 drop) and include our encrypted message in the transaction's memo field. The memo field is perfect for this as it can store arbitrary data, making it an ideal place for our encrypted message. Once the transaction is validated, our secret message will be securely stored on the blockchain - visible to everyone but readable only by the intended recipient who holds the matching private key.

Get the message and decypher it

When you receive a 1-drop transaction, it might contain a hidden message for you. By checking the raw transaction data in your block explorer and looking at the memo field, you can find an encrypted message. You'll see a scrambled string of characters - this is your encrypted message. Since this message was encrypted using your public (outside) key, only your private (inside) key can decrypt it. By copying this encrypted text and using your private key, you can transform this unreadable data back into the original message that was meant for your eyes only.

import tweetnacl from 'tweetnacl';
import { Wallet } from "xrpl";
import {
  edwardsToMontgomeryPub,
  edwardsToMontgomeryPriv,
} from "@noble/curves/ed25519";

const { box } = tweetnacl;

export function decryptMessage(
  messageWithNonce: string,
  recipientPublicKey: string,
  senderSecretKey: string,
): string {
  const pubKeyBytes = Buffer.from(recipientPublicKey.slice(2), "hex");
  const secretKeyBytes = Buffer.from(senderSecretKey.slice(2), "hex");

  const pubKeyCurve = edwardsToMontgomeryPub(pubKeyBytes);
  const privKeyCurve = edwardsToMontgomeryPriv(secretKeyBytes);
  console.log(messageWithNonce)
  const { encrypted, nonce } = JSON.parse(messageWithNonce);
  const messageBytes = Buffer.from(encrypted,"base64");
  const nonceBytes = Buffer.from(nonce,"base64");
  const decryptedMessage = box.open(
    messageBytes,
    nonceBytes,
    pubKeyCurve,
    privKeyCurve,
  );
  if (!decryptedMessage) {
    throw new Error("Failed to decrypt message");
  }
  return new TextDecoder().decode(decryptedMessage);
}

function main() {
  const cypherMessage =
    "Your cypher message goes here";
  const senderPubKey =
    "The sender public key goes here";
  const mySeed = "your seed goes here";

  const myPrivateKey = Wallet.fromSeed(mySeed).privateKey;
  const clearMessage = decryptMessage(
    Buffer.from(cypherMessage, "hex").toString(),
    senderPubKey,
    myPrivateKey,
  );

  console.log("==============CLEAR MESSAGE==============");
  console.log(clearMessage);
  
    console.log("all done");
}
main();

EVM Sidechain

This workshop will walk you through deploying a smart contract and building a full app on the XRPL EVM sidechain

EVM workshop Jan 2024

Documentation:

Connecting Metamask

Connect Metamask

https://opensource.ripple.com/docs/evm-sidechain/connect-metamask-to-xrpl-evm-sidechain/

EVM Network for Metamask

Field

Value

Bridging Assets

How to get XRP on the EVM sidechain

Bridge Funds

You will need to use the bridge tool to fund the EVM sidechain account

On the lefthand side select the Faucet.

On the righthand side connect the wallet you created with Metamask.

Use this document to share wallet info:

That's it!

Remix

How to compile, deploy and interact with a solidity smart contract on chain

Remix is an open-source, web-based integrated development environment (IDE) for writing, compiling, deploying, and debugging Solidity smart contracts on the Ethereum blockchain. It provides a user-friendly interface with tools for testing, debugging, and interacting with smart contracts directly from the browser.

Open Remix at https://remix.etherium.org

Deploying your first smart contract

By default you can find the HelloWorld.sol contract in the file explorer under contracts.

Compile it using the third tab.

You can deploy it using the fourth tab. You will need to select the injected provider environment and make sure your metamask is connected to the right network and account.

Deploy the contract, it should open a window for signature (notice the fees in XRP).

Once deployed successfully you can interact with it by scrolling down tab 4.

Creating other contracts

Create the following contract in remix, give it the name counter.sol

Compile the new contract using the third tab.

Deploy the contract using the fourth tab.

You can now interact with the counter smart contract:

send a transaction to increment it, this will trigger a transaction to sign in Metamask
read the current value (notice how this is free)

To go further you can explore the behind the simple banking contract we deploy in the banking app.

Banking App

In this workshop we will learn how to create a Fullstack app using hardhat

Clone repo

First off we will clone the repo or import it into replit depending on your configuration.

https://github.com/XRPL-Commons/evm-banking-kryptoshpere-2024

From the root directory, run npm ito install common dependencies.

Deploy the banking smart contract

Navigate to the lending-contract folder and follow the instructions in the readme to deploy the contract:

install dependencies with npm i
add your private key to the .env file
fix the hardhat config
review the contract ()

You can verify your contract has been deployed using the XRPL EVM Explorer

Run the Frontend

Navigate to the lending-frontend folder and follow the instructions in the readme to run the front end:

install dependencies with npm i
run the frontend with npm run dev and notice the Connect Wallet button does not work

We need to set up the web 3 context, to do this navigate to the .shared folder and fix the web3-context.ts file, your web app should now look like this.

connect your account (the same EVM account you deployed the contract to)
try to deposit
fix the deposit function
try to withdraw

Congratulations, you have just completed a full stack app using the XRPL EVM Sidechain.

Core Dev Bootcamp

The XRPL Core Dev Bootcamp – Online Edition is a program designed for intermediate to advanced C++ developers looking to deepen their skills in the core of the XRP Ledger. This digital edition lets

Compilation Process & Generating Binary

Building Rippled from Source

Introduction

Local Development & Testing

Running Rippled in Standalone Mode

Introduction

Homeworks

Homework 1: Rippled Node Setup and Mainnet Synchronization

Objective

Configure and launch Rippled on the XRPL mainnet

Homeworks

Homework 1: Transaction Flow Analysis

Objective

This homework reinforces your understanding of the Rippled architecture, transaction processing, and codebase navigation. You will perform hands-on exploration of the codebase and analyze transaction

Format: Written report (PDF or Markdown) with screenshots/code snippets

Homework 2: Transactor Code Exploration

Objective

Explore the Payment transactor implementation in the Rippled codebase.

Format: Written report (PDF or Markdown) with screenshots/code snippets

Homework 3: Logging and Debugging

← Back to Rippled II Overview

Objective

Configure logging and analyze Rippled's internal behavior.

Format: Written report (PDF or Markdown) with screenshots/code snippets

Requirements

Enable Detailed Logging
- Enable trace-level logging for the Transaction partition
- Submit a transaction
- Capture the relevant log output

Deliverable

A report containing:

Commands used to enable logging
Log excerpts (formatted properly)
Analysis of 5 log messages with explanations

Homework 4: Architecture Diagram

Objective

Deepen your understanding of Rippled by exploring additional transaction types, customizing log filtering for targeted analysis, and visualizing the Transactor framework with a detailed flowchart.

Format: Written report (PDF or Markdown) with screenshots/code snippets

Appendices

Random Number Generation

Appendices

Homeworks

Message Relaying

← Back to Protocol Extensions and Quantum Signatures

Introduction

Efficient message propagation is essential for a decentralized ledger. Transactions must reach validators quickly, proposals must spread to enable consensus, and validations must propagate to finalize ledgers. The overlay network's message relaying system ensures information flows efficiently while preventing network overload through intelligent squelching.

This lesson explores how messages propagate through the network and how Rippled optimizes this process to handle high-throughput scenarios.

OverlayImpl::relay

OverlayImpl::relay(protocol::TMProposeSet& m, uint256 const& uid, PublicKey const& validator) ():

Calls app_.getHashRouter().shouldRelay(uid) to determine if the proposal should be relayed.
If not, returns an empty set.
If yes:
- Creates a shared pointer to a Message object containing the proposal.

Slot::update and Squelch Mechanism

Slot::update ():

Tracks peer activity for a validator, incrementing message counts and considering peers for selection.
When enough peers reach the message threshold, randomly selects a subset to be "Selected" and squelches the rest (temporarily mutes them).
Squelched peers are unsquelched after expiration.
Handles all state transitions, logging, and squelch/unsquelch notifications via the SquelchHandler interface.

OverlayImpl::unsquelch ():

Looks up the peer by short ID.
If found, constructs a TMSquelch message with squelch=false for the validator.
Sends the message to the peer, instructing it to stop squelching messages from the validator.

Appendices

Homeworks

Multi-Signature

In this session, we will work with multiple signatures

Introduction

MultiSignature (or MultiSig) on the XRPL allows multiple users to collectively authorize transactions from a shared account. This ensures enhanced security and reduces risks associated with a single point of control. Think of it like a group-controlled vault where multiple stakeholders must approve access.

MultiSign Explained

1. Configuration and Setup

MultiSignature starts with a shared account on the XRPL. This account is configured with specific rules, defining how many and which signers are required for transaction approval. Each signer is assigned a "weight," reflecting their influence in the decision-making process.

2. Establishing a Quorum

The quorum is the minimum number of signers required to authorize a transaction. For example, a quorum of three means at least three pre-approved parties must sign off for the transaction to proceed.

3. Transaction Authorization

When a transaction is initiated, it must receive the necessary number of approvals as specified in the MultiSignature configuration. For instance, if the quorum requires two out of three signers, the transaction will execute only after two parties provide their signatures.

4. Enhanced Security Features

MultiSignature ensures that even if one signer's private key is compromised, unauthorized transactions cannot occur without meeting the quorum. This reduces risks associated with fraud or hacking.

5. Customizable Flexibility

MultiSignature is highly adaptable, allowing configurations to be updated over time. For example, fewer signers can be required for everyday transactions, but unanimous approval might be enforced for high-value transfers.

Why MultiSignature Stands Out

1. Distributed Control and Governance

MultiSignature decentralizes decision-making power by requiring consensus from multiple signers. This ensures no single individual has complete control, making it ideal for businesses, joint ventures, and collaborative setups.

2. Enhanced Security Against Threats

By requiring multiple approvals, MultiSignature significantly reduces the risk of unauthorized transactions, even if one key is compromised. This layered security is a robust defense against hacking and fraud.

3. Fostering Trust in Shared Transactions

MultiSignature enhances trust in shared financial operations by ensuring transparency and consensus among all parties involved.

4. Risk Mitigation for Organizations

MultiSignature mitigates risks such as insider threats and key compromises by spreading responsibility across multiple signers.

5. Customizable for Your Needs

Configurations can be tailored to operational requirements, such as setting different approval thresholds for routine versus high-value transactions.

What are we going to do

Wallet Initialization Create wallets for the main account and the signers using their seeds.
Setting Up the Signer List Configure the signer list with their respective weights and set the quorum.
Submitting the SignerListSet Transaction Send the signer list configuration to the XRPL.
Creating the Payment Transaction Define the payment transaction that will be multi-signed.

Setup

Accounts

For this example you need a total of four accounts:

One main account
Three signers

The signers do not require funds but must enable the master key.

SignerQuorum: The minimum weight sum required for valid transactions.
SignerEntries: A list with at least one member and no more than 32 members.

Create Wallets

Generate Wallets instead

Alternatively you can create Wallets dynamically:

Create and Set the Signer List

With the accounts we just created we want to configure our signerlist and submit this to the ledger, we do this by creating a .

Creating a Transaction

For creating transactions in a multi-sign environment, you have two options: either use or a . Tickets are used to reserve sequence numbers. Since MultiSign transactions are asynchronous, the sequence number the transactions have been based on might be outdated. In this example, we do not use Tickets.

Create Transaction

In this example, we prepare a simple payment transaction to be later signed using MultiSignature. The transaction sends 1 XRP (in drops) from the main account to a specified destination address.

Prepare the transaction

The fee and Sequence needs to be set in advance. The calculation for it goes as follows: (Base Fee + (Incremental Fee × Number of Signers)). We can use for this, 3 is the number of signers.

Signing the Transaction

Each signer will the same Transaction

Combine the signatures

all signatures for one final Transaction

Submit

the multi-signed transaction

Key Points to Remember

Signer Weights and Quorum
- The sum of the signer weights must meet or exceed the SignerQuorum for a transaction to be valid.
- In the example, Signer 1 has a weight of 2, while Signers 2 and 3 have a weight of 1 each.

With MultiSignature, you can ensure robust security and reliable transaction governance on the XRPL.

The Four Pillars of Security

← Back to Cryptography I: Blockchain Security and Cryptographic Foundations

Introduction

Before we dive into code, we need to understand what cryptography actually promises us. In rippled, every cryptographic operation serves one or more of four fundamental guarantees. These aren't abstract concepts—they're concrete properties that protect billions of dollars in value and enable a decentralized financial system to function without trusted intermediaries.

The Cryptographic Promise

When you interact with the XRP Ledger, cryptography provides four essential security properties. Understanding these properties—what they mean, why they matter, and how they're achieved—is foundational to everything else in this module.

1. Confidentiality

Confidentiality means that sensitive information remains hidden from those who shouldn't see it.

In XRPL Context

When two rippled nodes establish a connection, their communication is encrypted so that eavesdroppers on the network can't read their messages. The SSL/TLS layer provides this guarantee, ensuring that even though the internet is fundamentally public, peer-to-peer conversations remain private.

How It Works

Rippled uses TLS 1.2 or higher with carefully selected cipher suites that provide forward secrecy—even if a node's long-term key is compromised later, past communications remain protected.

Why It Matters

Without confidentiality:

Attackers could monitor which transactions nodes are sharing
Network topology could be mapped by observing communication patterns
Strategic information about ledger state could leak to adversaries

2. Integrity

Integrity ensures that data hasn't been tampered with. A single flipped bit could change "send 1 XRP" to "send 100 XRP"—or worse, redirect funds to a different account entirely.

In XRPL Context

When you receive a transaction, you need to know that every byte is exactly as the sender intended. Hash functions provide this guarantee by creating unique fingerprints of data that change completely if even a single bit is modified.

How It Works

The SHA-512-Half hash function used throughout XRPL ensures that:

You can't find two different transactions with the same ID (collision resistance)
You can't create a transaction that produces a specific ID (preimage resistance)
Changing even one bit produces a completely different hash (avalanche effect)

Why It Matters

Without integrity:

Transactions could be modified in transit
Malicious nodes could alter payment amounts
The entire concept of "this transaction" becomes meaningless

Real-World Example

The hash changes so dramatically that any modification is immediately detectable.

3. Authenticity

Authenticity proves the identity of the sender. When a transaction claims to come from a particular account, cryptographic signatures prove that the holder of that account's private key actually created it.

In XRPL Context

Every transaction on XRPL must be signed with the private key corresponding to the sending account. Without this signature, the transaction is rejected. The signature is mathematical proof that only someone with the secret key could have created it.

How It Works

The mathematical relationship between public and secret keys ensures:

Only the secret key holder can create a valid signature
Anyone with the public key can verify the signature
The signature proves authorization for this specific transaction

Why It Matters

Without authenticity:

Anyone could claim to be anyone
Funds could be stolen by impersonating account owners
The entire concept of ownership would collapse

Attack Scenario (Prevented)

Without the victim's secret key, it's computationally infeasible to create a valid signature. The attacker would need to solve the discrete logarithm problem—which would take longer than the age of the universe with all of humanity's computing power.

4. Non-Repudiation

Non-repudiation means that once you've signed something, you can't later deny you signed it. The mathematics of digital signatures make this guarantee absolute: if your private key created a signature, there's no ambiguity, no room for doubt.

In XRPL Context

This property is crucial for a financial system where disputes might arise and proof of authorization is essential. If you signed a payment, that signature is irrefutable proof that you authorized it.

How It Works

Digital signatures create an undeniable link between:

The signer (proved by possession of the secret key)
The message (what was signed)
The time (when it was signed, via timestamps or ledger sequence)

Why It Matters

Without non-repudiation:

Senders could deny authorizing payments after they complete
Dispute resolution would be impossible
Legal accountability for transactions wouldn't exist
Financial systems couldn't function reliably

Real-World Scenario

How These Pillars Work Together

These four properties aren't independent—they work together to create a complete security system:

Example: A Complete Transaction

Let's see all four pillars in action:

Mathematical Foundations

The four pillars rest on hard mathematical problems:

For Authenticity and Non-Repudiation: The Discrete Logarithm Problem

This asymmetry enables public-key cryptography. You can freely share your public key, and no one can derive your secret key from it.

For Integrity: Collision Resistance

This one-way property makes hashes perfect for integrity checking.

For Confidentiality: Symmetric Key Security

TLS negotiates shared secret keys that both parties know but attackers don't.

Trust Model

These four pillars enable a trust model where:

You don't have to trust:

Network operators
Node operators
Other validators
Anyone else

You only have to trust:

Mathematics (that the cryptographic problems are actually hard)
Your ability to protect your own secret keys
The open-source implementation (which you can audit)

This is the fundamental shift blockchain enables: from institutional trust to mathematical trust.

Security in Depth

Rippled doesn't rely on one cryptographic technique—it uses multiple layers:

Even if one layer has a vulnerability, others provide protection.

Practical Implications

Understanding these four pillars helps you:

When reading code:

Recognize which security property a function provides
Understand why certain checks are performed
Identify what would break if a step is skipped

When writing code:

Choose appropriate cryptographic primitives
Implement proper error handling
Avoid introducing vulnerabilities

When debugging:

Identify which security property is failing
Trace the cryptographic operation responsible
Understand what went wrong and why

Summary

The four pillars of cryptographic security are:

Confidentiality - Keep secrets secret (via encryption)
Integrity - Detect tampering (via hashing)
Authenticity - Prove identity (via signatures)
Non-repudiation - Prove authorization (via signatures)

These properties work together to create a system where trust is mathematical rather than institutional. In the chapters ahead, you'll see exactly how rippled implements these properties through specific cryptographic algorithms and careful coding practices.

RPC Handler Architecture

Understanding the Foundation of Rippled's RPC System

← Back to Understanding XRPL(d) RPC Architecture

Introduction

The RPC (Remote Procedure Call) system is the primary interface through which external applications, wallets, and services interact with a Rippled node. Understanding its architecture is fundamental to building custom handlers that integrate seamlessly with the XRP Ledger.

Rippled's RPC architecture supports multiple transport protocols—JSON-RPC over HTTP, JSON-RPC over WebSocket, and gRPC—all converging on a unified handler dispatch system. This design ensures consistency, maintainability, and extensibility across different client types.

In this section, you'll learn how handlers are registered, discovered, and invoked within the Rippled codebase.

Core Architecture Components

The RPC system consists of several key components that work together to process requests:

1. Central Handler Table

The handler table is a centralized registry that maps RPC command names to their corresponding handler functions.

Location: src/xrpld/rpc/detail/Handlers.cpp

Key characteristics:

Command Name: Case-sensitive string identifier (e.g., "account_info")
Handler Function: Pointer to the actual implementation function
Required Role: Minimum permission level needed to execute the command

2. Handler Information Structure

Each handler is described by a HandlerInfo structure containing metadata:

Purpose:

Enables versioning for backward compatibility
Specifies permission requirements before execution
Defines runtime conditions (e.g., must have synced ledger)

3. Handler Function Signature

All RPC handlers follow a standardized function signature:

Components:

Return Type: Json::Value — The JSON response object
Parameter: RPC::JsonContext& — Contains request data, ledger access, and configuration

This consistency allows the dispatcher to invoke any handler uniformly.

4. JsonContext Object

The JsonContext provides handlers with everything needed to process a request:

Key capabilities:

Ledger Access: Query account states, transactions, and metadata
Network Information: Node status, peer connections, consensus state
Resource Management: Track API usage and enforce limits
Authentication: Know the caller's permission level

Handler Registration Process

Handlers are registered at compile time through static initialization:

Step 1: Define the Handler Function

Step 2: Add to Handler Table

Step 3: Declare in Header (Optional)

Handler Discovery and Dispatch

When a client sends an RPC request, the system follows this flow:

1. Request Reception

The server receives a JSON-RPC request via HTTP, WebSocket, or gRPC:

2. Command Lookup

The dispatcher searches the handler table:

3. Permission Check

Before invoking the handler, the system verifies the caller's role:

4. Condition Validation

The system ensures required conditions are met:

5. Handler Invocation

Finally, the handler is executed:

6. Response Serialization

The result is wrapped in a JSON-RPC response envelope and returned to the client.

Handler Capability Flags

Handlers can declare various capability requirements:

Flag

Meaning

Example Use Case

Example:

This ensures the handler cannot execute unless both conditions are satisfied.

Multi-Transport Support

Rippled's RPC system abstracts away transport details, allowing handlers to work across:

HTTP (JSON-RPC)

WebSocket (JSON-RPC)

gRPC (Protocol Buffers)

Handler Transparency: The same handler function serves all three transports—the dispatcher handles protocol-specific details.

Versioning and Compatibility

Rippled supports API versioning to maintain backward compatibility:

Clients can specify the API version in their requests:

If no version is specified, the system uses the default (version 1) implementation.

Real-World Example: AccountInfo Handler

Let's examine the registration of the widely-used account_info handler:

Registration (Handlers.cpp):

Analysis:

Command: "account_info"
Function: doAccountInfo (defined in src/xrpld/rpc/handlers/AccountInfo.cpp)
Role: USER — Available to authenticated users (not just admins)

This registration tells Rippled:

Accept requests with method: "account_info"
Ensure the caller has at least USER-level permissions
Verify a current ledger is available
Invoke doAccountInfo() with the request context

Conclusion

The RPC handler architecture provides a clean, extensible foundation for Rippled's API layer. Through centralized registration in a handler table, uniform function signatures, and automatic permission enforcement, the system ensures consistency across hundreds of commands while remaining easy to extend. The separation between transport protocols and handler logic means the same implementation serves HTTP, WebSocket, and gRPC clients transparently. Understanding this architecture is essential for navigating the codebase, debugging RPC issues, and preparing to implement custom handlers.

Multi-Purpose Tokens

Learn how to create and manage Multi-Purpose Tokens (MPT) on the XRP Ledger.

Multi-Purpose Tokens (MPT) are a recent amendment to the XRP Ledger, enhancing the token system by allowing tokens to serve multiple functions beyond just being a medium of exchange. This amendment introduces new capabilities for token issuers and holders.

Use Cases

Stablecoins: Create stablecoins with features like freezing and clawback.
Utility Tokens: Design tokens with specific utility functions.
Security Tokens: Implement security tokens with transfer restrictions.
Community Credit: Track debts and credits between known parties.

MPToken Flags

Each flag is a power of 2, allowing them to be combined using bitwise operations. The total value is the sum of all enabled flags.

Flag

Value

Description

Common Flag Combinations:

Basic: canTransfer (32)
Secure: canLock + canClawback + canTransfer (98)
Regulated: canLock + canClawback + canTransfer + requireAuth (102)

Getting Started: Creating the Main Structure of Your Script

Create a new file or edit index.ts:

Understanding MPTokenIssuanceID

The mpt_issuance_id is a unique identifier generated when an MPToken is created via MPTokenIssuanceCreate. This ID is:

Automatically generated by the XRPL network upon successful token creation
Globally unique across all MPTokens on the ledger
Required for all subsequent operations (payments, clawbacks, authorization)

To obtain the MPTokenIssuanceID:

Submit an MPTokenIssuanceCreate transaction
Retrieve the ID from the transaction result: result.meta?.mpt_issuance_id
Store this ID for future operations with your token

Alternative ways to find the MPTokenIssuanceID:

From Explorer: You can find the ID on the XRPL explorer (https://devnet.xrpl.org/) by searching with the transaction hash or the creator's address
Query by Issuer: Use the account_lines API method with the issuer's address to find all tokens issued by that account

The relationship between issuer, token properties, and ID:

Issuer: The account that created the token (unchangeable)
Token Properties: Metadata, flags, and rules defined at creation
MPTokenIssuanceID: The unique identifier linking all operations to this specific token issuance

Technical Specifications

Uses decimal (base-10) math with 15 digits of precision
Can express values from 1.0 × 10^-81 to 9999999999999999 × 10^80
Supports transfer fees that are automatically deducted
Allows issuers to define tick sizes for exchange rates

Destroying MPTokens

The MPTokenIssuanceDestroy transaction allows an issuer to permanently destroy an MPToken issuance. This is useful for:

Retiring deprecated or unused tokens
Removing tokens that were created in error
Regulatory compliance and token lifecycle management

Requirements

Only the original issuer can destroy the MPToken issuance
All tokens must be owned by the issuer (transferred back) before destruction
The MPTokenIssuanceID must be valid and reference an existing issuance

Example Transaction

Freezing MPToken Issuance

The MPTokenIssuanceSet transaction allows an issuer to modify the state of an MPToken issuance, including freezing/unfreezing transfers. This is useful for:

Temporarily halting transfers during maintenance or upgrades
Responding to security incidents
Complying with regulatory requirements
Managing token lifecycle events

Requirements

Only the original issuer can modify the issuance settings
The MPTokenIssuanceID must be valid and reference an existing issuance
Appropriate flags must be set during issuance to enable freezing

Example Transaction

Authorizing MPToken Holders

The MPTokenAuthorize transaction enables fine-grained control over who can hold and transfer Multi-Purpose Tokens (MPTs) on the XRPL. This mechanism supports compliance, prevents unsolicited token spam, and allows issuers to manage token distribution effectively.

Features

Authorize a Holder: Permit a specific account to receive and hold a designated MPT
Revoke Authorization: Remove a holder's permission, effectively locking their MPT balance
Self-Unauthorize: Allow a holder to voluntarily relinquish their MPT holdings (requires zero balance)
Global Locking: Restrict all transfers of a particular MPT issuance

Requirements

Only the original issuer can authorize/revoke holders
The MPTokenIssuanceID must be valid and reference an existing issuance
Authorization flags must be enabled during issuance
Holder accounts must be valid XRPL addresses

Example Transaction

Transaction Type modifications

The introduction of Multi-Purpose Tokens (MPT) on the XRP Ledger has brought significant changes to existing transaction types, especially Payment and Clawback. These transactions now support MPTokens, allowing you to transfer or recover tokens issued under the new amendment.

Changes introduced:

Payment: The Payment transaction can now transfer MPTokens by using the Amount field as an object containing the issuance identifier (mpt_issuance_id) and the amount to transfer. Example:
Clawback: The Clawback transaction allows the issuer to recover MPTokens from a specific account, also using the adapted Amount field for MPTokens. Example:

Putting It All Together

Let's create a complete example that demonstrates all the MPToken features by simulating a real-world scenario: issuing company shares to investors. In this example, we'll:

Create a company share token with regulatory controls
Authorize investors to receive shares
Distribute shares to investors
Demonstrate compliance controls (locking and clawback)

You can check every transaction hash on : https://devnet.xrpl.org/

Resources

Appendix : RFCs and Standards Reference

Introduction

This appendix provides references to the cryptographic standards, RFCs, and specifications that XRPL's cryptography is built upon. Understanding these standards helps you understand why rippled makes certain design choices.

Cryptographic Algorithms

Ed25519 Digital Signatures

RFC 8032 - Edwards-Curve Digital Signature Algorithm (EdDSA)

URL:
Published: January 2017
Status: Proposed Standard

What it defines:

EdDSA signature scheme using Edwards curves
Ed25519: EdDSA with Curve25519
Ed448: EdDSA with Ed448-Goldilocks
Test vectors and implementation guidelines

Key parameters (Ed25519):

Curve: Curve25519 (Edwards form)
Hash function: SHA-512
Public key size: 32 bytes
Signature size: 64 bytes

Why XRPL uses it:

Fast signature verification (~5x faster than ECDSA)
Simple implementation
No signature malleability
Modern design with security proofs

secp256k1 Elliptic Curve

SEC 2: Recommended Elliptic Curve Domain Parameters

Publisher: Standards for Efficient Cryptography Group (SECG)
URL:
Version: 2.0, January 2010

What it defines:

Elliptic curve parameters for secp256k1
Curve equation: y² = x³ + 7 (mod p)
Prime field size p and generator point G
Compression/decompression of public keys

Key parameters (secp256k1):

Why XRPL uses it:

Ecosystem compatibility
Well-tested (used since 2009)
Supported by many libraries and tools

ECDSA Signatures

FIPS 186-4 - Digital Signature Standard (DSS)

Publisher: NIST
URL:
Published: July 2013

What it defines:

ECDSA signature algorithm
Key generation procedures
Signature generation and verification
Approved curves (including secp256k1)

Deterministic ECDSA Nonces

RFC 6979 - Deterministic Usage of DSA and ECDSA

URL:
Published: August 2013
Status: Informational

What it defines:

Deterministic nonce generation for ECDSA
Eliminates need for secure random number generation during signing
Prevents nonce reuse vulnerabilities

Algorithm:

Why XRPL uses it:

Prevents catastrophic nonce reuse
Makes signing deterministic (same message = same signature)
No dependency on RNG quality during signing

Hash Functions

SHA-2 Family

FIPS 180-4 - Secure Hash Standard (SHS)

Publisher: NIST
URL:
Published: August 2015

What it defines:

SHA-256: 256-bit hash (32 bytes)
SHA-512: 512-bit hash (64 bytes)
Padding and iteration schemes
Test vectors

XRPL usage:

SHA-512-Half: First 32 bytes of SHA-512
SHA-256: Used in Base58Check checksums
Both used in RIPESHA double hash

Why SHA-512-Half:

Faster on 64-bit CPUs than SHA-256
Same output size (256 bits)
Same security level

RIPEMD-160

Original Paper: "RIPEMD-160: A Strengthened Version of RIPEMD"

Authors: Dobbertin, Bosselaers, Preneel
Published: 1996
Hash size: 160 bits (20 bytes)

XRPL usage:

Second stage of RIPESHA hash
Used in address generation

Algorithm:

Key Derivation

PBKDF2

RFC 2898 - PKCS #5: Password-Based Cryptography Specification

URL:
Published: September 2000
Status: Informational

What it defines:

Password-Based Key Derivation Function 2
Iterated hashing to slow brute-force
Salt for uniqueness

Note: XRPL doesn't use PBKDF2 for key derivation (uses sha512Half of seed), but it's relevant for password-based seed derivation in wallets.

Encoding

Base58

No formal RFC, but based on:

Design by Satoshi Nakamoto
Excludes similar-looking characters (0, O, I, l)
Used widely in blockchain systems

Alphabet:

XRPL implementation:

Base58Check with 4-byte SHA-256(SHA-256()) checksum
Type prefix byte determines first character
Compatible with other blockchain systems

Base64

RFC 4648 - The Base16, Base32, and Base64 Data Encodings

URL:
Published: October 2006
Status: Proposed Standard

XRPL usage:

Used in peer handshake (Session-Signature header)
Not used for addresses (uses Base58Check instead)

Transport Security

TLS 1.2

RFC 5246 - The Transport Layer Security (TLS) Protocol Version 1.2

URL:
Published: August 2008
Status: Proposed Standard

What it defines:

Handshake protocol
Record protocol
Cipher suites
Certificate verification

XRPL usage:

Peer-to-peer communication
WebSocket connections
RPC endpoints

TLS 1.3

RFC 8446 - The Transport Layer Security (TLS) Protocol Version 1.3

URL:
Published: August 2018
Status: Proposed Standard

Improvements over TLS 1.2:

Faster handshake
Forward secrecy by default
Simplified cipher suite negotiation

DER Encoding

ITU-T X.690 - ASN.1 encoding rules

Publisher: ITU-T
Published: 2015

What it defines:

Distinguished Encoding Rules (DER)
Used for secp256k1 signature encoding
Canonical binary format

Structure:

Random Number Generation

NIST SP 800-90A - Recommendation for Random Number Generation

Publisher: NIST
URL:
Published: June 2015

What it defines:

Deterministic Random Bit Generators (DRBGs)
CTR_DRBG, HASH_DRBG, HMAC_DRBG
Entropy requirements
Testing procedures

XRPL usage:

Relies on OpenSSL's RAND_bytes
OpenSSL implements NIST-approved DRBGs

Mnemonic Words

RFC 1751 - A Convention for Human-Readable 128-bit Keys

URL:
Published: December 1994
Status: Informational

What it defines:

Encoding 128-bit keys as English words
2048-word dictionary
Checksum embedded in last word

XRPL usage:

Optional seed encoding format
Alternative to Base58 for seeds
Easier to write down/speak

Example:

Cryptographic Best Practices

NIST SP 800-57 - Recommendation for Key Management

Publisher: NIST
URL:
Published: May 2020

What it defines:

Key length recommendations
Algorithm lifetime
Key usage guidance
Security strength equivalences

Security Levels:

XRPL compliance:

256-bit secret keys (ECC)
256-bit hashes (SHA-512-Half)
~128-bit security level for Ed25519
~128-bit security level for secp256k1

Implementation Libraries

OpenSSL

Website: License: Apache License 2.0

What rippled uses:

Random number generation (RAND_bytes)
Hash functions (SHA-256, SHA-512, RIPEMD-160)
SSL/TLS implementation
Some low-level crypto primitives

secp256k1

Repository: License: MIT

What rippled uses:

secp256k1 curve operations
ECDSA signing and verification
Public key derivation
Signature parsing/serialization

ed25519-donna

Repository: License: Public Domain

What rippled uses:

Ed25519 signing and verification
Public key derivation
Fast implementation

Standard Bodies

IETF: Internet Engineering Task Force (RFCs)
NIST: National Institute of Standards and Technology
ISO: International Organization for Standardization
SECG: Standards for Efficient Cryptography Group

Summary

Key standards for XRPL cryptography:

RFC 8032: Ed25519 signatures
RFC 6979: Deterministic ECDSA nonces
FIPS 180-4: SHA-2 hash functions
SEC 2: secp256k1 curve parameters

Understanding these standards helps you:

Know why algorithms were chosen
Verify implementations are correct
Stay current with best practices
Contribute improvements

Connection Lifecycle

← Back to Protocol Extensions and Quantum Signatures

Introduction

A peer connection in the XRP Ledger overlay network goes through a well-defined lifecycle: discovery, establishment, activation, maintenance, and termination. Understanding this lifecycle is crucial for debugging connectivity issues, optimizing network performance, and implementing new networking features.

Each phase involves careful coordination between multiple subsystems, resource management decisions, and thread-safe state transitions. This lesson traces the complete journey of a peer connection through the codebase.

Lifecycle Phases

The connection lifecycle consists of five distinct phases:

Discovery Phase

Before a connection can be established, nodes must discover potential peers. The PeerFinder subsystem manages peer discovery and slot allocation.

Discovery sources include:

Fixed Peers: Configured in rippled.cfg under [ips_fixed], these are always-connect peers that the node prioritizes.

Bootstrap Peers: Initial peers used when joining the network for the first time, typically well-known, reliable nodes.

Peer Exchange: Active peers share their known endpoints, enabling organic discovery of new nodes.

Establishment Phase

When OverlayImpl decides to connect to a peer, it creates a ConnectAttempt object that manages the asynchronous connection process:

The ConnectAttempt::run() method initiates an asynchronous TCP connection:

Using shared_from_this() ensures the ConnectAttempt object remains alive until the asynchronous operation completes, even if other references are released.

Handshake Phase

Once the TCP connection succeeds, the handshake phase begins. This involves TLS negotiation followed by protocol-level handshaking.

For outbound connections, ConnectAttempt::processResponse handles the handshake:

For inbound connections, PeerImp::doAccept handles the server side of the handshake:

Activation Phase

Once the handshake completes successfully, the peer becomes active. The OverlayImpl::activate method registers the peer in the overlay's tracking structures:

The add_active method handles the full registration process:

After activation, PeerImp::doProtocolStart begins the message exchange:

Maintenance Phase

During normal operation, peers exchange messages continuously. The maintenance phase involves:

Message Processing: Reading incoming messages and dispatching to appropriate handlers.

Health Monitoring: Tracking response times, message rates, and connection quality.

Resource Management: Ensuring fair bandwidth allocation and detecting abuse.

Termination Phase

Connections may terminate for various reasons: network errors, protocol violations, resource limits, or graceful shutdown. Proper cleanup is essential to prevent resource leaks.

The PeerImp destructor handles final cleanup:

The overlay updates its state when a peer disconnects:

Resource Management Throughout the Lifecycle

Every phase involves resource management decisions:

Discovery: PeerFinder limits the number of endpoints tracked to prevent memory exhaustion.

Establishment: Resource Manager checks if the endpoint has a good reputation before allowing connection.

Activation: Slots are finite resources allocated by PeerFinder based on configuration.

Maintenance: Bandwidth and message rates are monitored, with misbehaving peers penalized.

Termination: All allocated resources must be released to prevent leaks.

Thread Safety Considerations

The connection lifecycle involves multiple threads:

IO Threads: Handle asynchronous network operations.

Job Queue Threads: Process completed operations and state transitions.

Application Threads: May query peer state or initiate connections.

Conclusion

The connection lifecycle is a carefully orchestrated sequence of phases, each with specific responsibilities and resource management requirements. Understanding this lifecycle enables you to debug connectivity issues, optimize network performance, and safely implement new networking features.

Request and Response Flow

Tracing a Request Through Rippled's RPC Pipeline

← Back to Understanding XRPL(d) RPC Architecture

Introduction

Understanding the complete lifecycle of an RPC request—from the moment it arrives at the server to when the response is sent back to the client—is essential for building robust custom handlers. This knowledge helps you anticipate edge cases, implement proper error handling, and optimize performance.

In this section, we'll trace the journey of a request through Rippled's RPC system, examining each stage of processing and the components involved.

The Complete Request Journey

Let's break down each stage in detail.

Stage 1: Request Reception

HTTP Entry Point

For HTTP requests, the entry point is the HTTP server configured in rippled.cfg:

Source Location: src/xrpld/rpc/detail/RPCCall.cpp

The HTTP server receives the raw request:

WebSocket Entry Point

For WebSocket connections, clients establish a persistent connection:

Source Location: src/xrpld/rpc/detail/RPCHandler.cpp

WebSocket messages use a slightly different format:

gRPC Entry Point

For gRPC, requests arrive as Protocol Buffer messages:

Source Location: src/xrpld/app/main/GRPCServer.cpp

Stage 2: Request Parsing

The raw request is parsed into a structured format.

JSON Parsing

Field Extraction

The parser extracts key fields:

Protocol Normalization

Different transports use different formats, which are normalized:

HTTP/WebSocket:

method or command field
params array or direct parameters

gRPC:

Protobuf message fields
Converted to JSON internally

Stage 3: Role Determination

Before processing the request, the system determines the caller's role based on the connection:

IP-Based Role Assignment

Source Location: src/xrpld/core/detail/Role.cpp

Role Hierarchy

Role descriptions:

FORBID: Blacklisted client (blocked)
GUEST: Unauthenticated public access (limited commands)
USER: Authenticated client (most read operations)
IDENTIFIED: Trusted gateway (write operations)

Configuration Example

Stage 4: Handler Lookup

The dispatcher searches the handler table for the requested command:

Version Matching

If API versioning is in use:

Stage 5: Permission Verification

The system checks if the caller has sufficient permissions:

Example: A GUEST client attempting to call submit (requires USER role) would be rejected here.

Stage 6: Condition Validation

Handlers may require specific runtime conditions:

Ledger Availability Check

Network Connectivity Check

Closed Ledger Check

Stage 7: Context Construction

A JsonContext object is built with all necessary information:

Context provides:

Request parameters (params)
Application services (app)
Resource tracking (consumer)

Stage 8: Resource Charging

The system tracks API usage to prevent abuse:

Resource limits are configured per client and prevent DoS attacks.

Stage 9: Handler Invocation

The handler function is called with the constructed context:

Error handling: Any uncaught exceptions are converted to rpcINTERNAL errors.

Stage 10: Response Construction

Success Response

For successful requests:

Error Response

For failed requests:

Stage 11: Response Serialization

The JSON response is serialized back to the client's format:

HTTP Response

WebSocket Response

gRPC Response

Stage 12: Response Delivery

The response is sent back to the client over the same transport:

HTTP: Single request-response cycle completes
WebSocket: Response is pushed to the persistent connection
gRPC: Streamed response or unary response returned

Timing and Performance

Each stage has associated latency:

Stage

Typical Time

Notes

Total typical latency: 5-105 ms

Error Handling at Each Stage

Different errors can occur at each stage:

Parsing Errors

Lookup Errors

Permission Errors

Condition Errors

Handler Errors

Real-World Example: Tracing an account_info Request

Let's trace a complete request:

1. Client Request

2. Reception (HTTP)

3. Parsing

4. Role Determination

5. Handler Lookup

6. Permission Check

7. Condition Check

8. Context Construction

9. Handler Invocation

10. Response

Conclusion

The RPC request-response flow demonstrates Rippled's carefully orchestrated pipeline for handling API calls. From initial reception across multiple transport protocols, through parsing, role determination, permission checks, and condition validation, to handler invocation and response formatting—each stage serves a specific purpose. This multi-stage design enables early rejection of invalid requests, consistent error handling, proper resource management, and transport-agnostic processing. Mastering this flow is crucial for debugging RPC issues and understanding how custom handlers integrate into the system.

SHAMap Architecture and Node Hierarchy

← Back to SHAMap and NodeStore: Data Persistence and State Management

Introduction

Now that you understand the mathematical foundations of Merkle-Patricia tries, let's explore how XRPL actually implements them in the SHAMap data structure.

The SHAMap is responsible for:

Maintaining account and transaction state in a cryptographically-verified Merkle tree
Computing root hashes that represent entire ledger state
Enabling efficient navigation through key-based lookups
Supporting snapshots and immutability for historical ledgers
Providing proof generation for trustless state verification

This chapter covers the architectural overview and node types. Later chapters dive into specific algorithms for navigation, hashing, and synchronization.

Core Design Principles

The SHAMap architecture achieves three critical properties:

1. Cryptographic Integrity

Every change to data propagates through hashes up to the root:

This ensures that no data can be modified undetected. Changing even one bit in an account's balance changes the root hash.

2. Efficient Navigation

The Patricia trie structure uses account identifiers as navigation guides:

No binary search needed. The path is directly encoded in the key.

3. Optimized Synchronization

Hash-based comparison eliminates unnecessary data transfer:

This allows new nodes to synchronize full ledgers from peers in minutes.

The SHAMap Instance

A SHAMap instance represents a complete tree of ledger state:

Core Data:

Key Properties:

Root Node: Always an inner node, never a leaf (even if only one account, still has inner structure)
Depth: Exactly 64 levels (256-bit keys ÷ 4 bits per level)
Navigation Determinism: Any key uniquely determines its path from root to leaf

Node Hierarchy

The SHAMap consists of three conceptual layers:

Layer 1: Root

Always present
Always an inner node
Contains the root hash representing entire tree
Can have up to 16 children (one for each hex digit 0-F)

Layer 2: Internal Structure

Inner nodes serve as branch points
Each can have 0-16 children
Store only hashes of children, not actual data
No data items in inner nodes

Layer 3: Leaf Nodes

Terminal nodes containing actual data items
Types: Account state, Transaction, Transaction+Metadata
All leaves in a SHAMap tree are homogeneous (same type)

Inner Nodes

Inner nodes form the branching structure:

Structure:

Key Characteristics:

Do not store data items directly - Only hashing information
Maintain cryptographic commitments through child hashes
Variable occupancy - Not all 16 children present
Support both serialization formats - Compressed and full

Serialization Formats:

Inner nodes support two wire formats:

Compressed Format (used when most slots are empty):

Saves space by omitting empty branches.

Full Format (used when most slots are occupied):

Simpler structure despite larger size.

Format Selection Algorithm:

XRPL automatically chooses format based on branch count:

Leaf Nodes

Leaf nodes store the actual blockchain data:

Base Properties:

SHAMapItem Structure:

Leaf Node Specializations:

Three distinct leaf node types exist, each with unique hashing:

1. Account State Leaves (hotACCOUNT_NODE)

Store account information
Include balances, settings, owned objects, trust lines
Type prefix during hashing prevents collision with other types
Updated when transactions affect accounts

2. Transaction Leaves (hotTRANSACTION_NODE)

Store transaction data
Do not include execution metadata
Immutable once added to ledger
Enable verification of transaction history

3. Transaction+Metadata Leaves (hotTRANSACTION_LEDGER_ENTRY)

Store transactions with execution metadata
Include results (success/failure, ledger entries modified)
Complete information for replaying or auditing
Support full transaction reconstruction

Why Multiple Types?

Ensures that moving data between leaves would be immediately detected as invalid.

SHAMapNodeID: Node Identification

Every node in the tree is uniquely identified by its position:

Components:

Path Encoding:

The path is encoded as 4-bit chunks (nibbles) in a uint256:

Key Operations:

getChildNodeID(branch) - Compute child position:

selectBranch(nodeID, key) - Determine which branch to follow:

This deterministic navigation ensures every key has exactly one path through the tree.

State Management

SHAMaps exist in different states reflecting their role in the system:

Immutable State

Represents a finalized, historical ledger
Nodes cannot be modified
Multiple readers can access simultaneously
Critical limitation: cannot be trimmed (nodes loaded stay in memory)

Mutable State

Represents work-in-progress ledger state
Nodes can be modified through copy-on-write
Safe mutations without affecting other SHAMap instances
Single writer (typically), multiple readers possible

Synching State

Transitional state during network synchronization
Allows incremental tree construction
Transitions to Immutable or Modifying when complete
Used when receiving missing nodes from peers

State Transitions:

Copy-on-Write Mechanism

The copy-on-write system enables safe node sharing and snapshots:

Principle:

Nodes are shared between SHAMaps using shared pointers. When a mutable SHAMap needs to modify a shared node, it creates a copy:

Node Sharing Rules:

Benefits:

Efficient Snapshots: New SHAMap instances share unmodified subtrees
Safe Concurrent Access: Modifications don't affect other instances
Memory Efficiency: Identical subtrees stored once

Integration with NodeStore

SHAMap is designed for in-memory operation, but nodes can be persisted:

Persistent Nodes:

Some nodes are marked as "backed" - they exist in NodeStore:

Canonicalization:

Ensures nodes are unique in memory:

This enables:

Safe node sharing across multiple SHAMap instances
Fast equality checking (compare pointers, not content)
Memory efficiency (identical nodes stored once)

Summary

Key Architectural Elements:

SHAMap Instance: Complete tree representing one ledger version
Inner Nodes: Branching structure with 0-16 children, storing hashes
Leaf Nodes: Terminal nodes containing account or transaction data
SHAMapNodeID: Identifies node position through depth and path

Design Properties:

Perfect balance: All leaves at approximately same depth (log_16 of account count)
Deterministic navigation: Key uniquely determines path
Immutable persistence: Historical ledgers safe from modification
Efficient sharing: Snapshots require minimal additional memory

In the next chapter, we'll explore how nodes are navigated, hashes are computed, and the tree structure is maintained.

Key Generation Pipeline

← Back to Cryptography I: Blockchain Security and Cryptographic Foundations

Introduction

Now that we understand where randomness comes from, let's explore how rippled transforms that randomness into cryptographic keys. This chapter traces the complete key generation pipeline—from random bytes to secret keys, from secret keys to public keys, and from public keys to account addresses.

We'll examine both random key generation (for new accounts) and deterministic key generation (for wallet recovery), and understand why rippled supports two different cryptographic algorithms.

The Two Paths to Key Generation

Rippled supports two approaches to key generation:

Random Key Generation

The Simple Case: `randomSecretKey()`

Step-by-step breakdown:

Allocate buffer: Create 32-byte buffer on stack
Fill with randomness: Use crypto_prng() to fill with random bytes
Construct SecretKey: Wrap bytes in SecretKey object

Why 32 Bytes?

Security level:

128-bit security requires 2^128 operations to break
256 bits provides 2^256 operations (overkill, but standard)
Quantum computers reduce security by half (2^256 → 2^128)
So 256 bits ensures long-term security even against quantum attacks

Generating a Complete Key Pair

Deterministic Key Generation from Seeds

What is a Seed?

A seed is a compact representation (typically 16 bytes) from which many keys can be derived:

Why seeds matter:

Backup: Remember one seed → recover all keys
Portability: Move keys between wallets
Hierarchy: Generate multiple accounts from one seed

Generating Keys from Seeds: The Interface

Ed25519: Simple Derivation

Why this works:

SHA-512-Half is a one-way function
Same seed always produces same secret key
Different seeds produce uncorrelated secret keys
No special validation needed (all 32-byte values are valid ed25519 keys)

Secp256k1: Complex Derivation

Why more complex?

Not all 32-byte values are valid secp256k1 secret keys. The value must be:

Greater than 0
Less than the curve order (a large prime number)

The Generator Class

Deriving the Root Key

Why this loop?

The probability that a random 256-bit value is >= CURVE_ORDER is approximately 1 in 2^128. This is so unlikely that we almost never need a second try, but the code handles it correctly.

Incrementing ordinal: If the first hash isn't valid, we increment the ordinal and try again. This ensures:

Deterministic behavior (same seed always produces same result)
Eventually finds a valid key (extremely high probability on first try)
No bias in the resulting key distribution

Public Key Derivation

For Secp256k1

Compressed vs Uncompressed:

Why compress?

Saves 32 bytes per public key
Given X, only two possible Y values exist
Prefix bit tells us which one

For Ed25519

Simpler than secp256k1:

No compression needed (Ed25519 public keys are naturally 32 bytes)
No serialization complexity
Just prepend type marker (0xED)

Account ID Generation

Once we have a public key, we derive the account ID:

RIPESHA: Double Hashing

The pipeline:

Why double hash?

Defense in depth: If one hash is broken, the other provides protection
Compactness: 20 bytes is shorter than 32 bytes
Quantum resistance: Even if quantum computers break elliptic curve crypto, they can't reverse the hash to get the public key

Address Encoding

The final step is encoding the account ID as a human-readable address:

Result:

We'll explore Base58Check encoding in detail in Chapter 7.

Complete Key Generation Examples

Example 1: Random Ed25519 Key

Example 2: Deterministic Secp256k1 Key

Example 3: Multiple Accounts from One Seed

Key Type Detection

Public Key Type Detection

Automatic Algorithm Selection

The secp256k1 Context

Security Considerations

Secret Key Storage

Key Validation

Seed Protection

Performance Characteristics

Key Generation Speed

Caching Considerations

Summary

Key generation in rippled involves:

Randomness: Cryptographically secure random bytes from crypto_prng()
Secret keys: 32 bytes of random or deterministically-derived data
Public keys: Derived via one-way function
Account IDs: Double hash (SHA-256 + RIPEMD-160) of public keys

Two algorithms:

secp256k1 – complex, validated, widely used
ed25519 – simpler, faster, preferred

Two approaches:

Random: Maximum security, requires backup of each key
Deterministic: One seed recovers many keys, convenient for wallets

In the next chapter, we'll see how these keys are used to create and verify digital signatures—the mathematical proof of authorization.

Consensus Engine: XRP Ledger Consensus Protocol

← Back to Rippled II Overview

Introduction

The Consensus Engine is the heart of the XRP Ledger's ability to reach agreement on transaction sets and ledger state without requiring proof-of-work mining or proof-of-stake validation. Understanding the consensus mechanism is crucial for anyone working on the core protocol, as it's what makes the XRP Ledger both fast (3-5 second confirmation times) and secure (Byzantine fault tolerant).

Unlike blockchain systems that require computational work to achieve consensus, the XRP Ledger uses a consensus protocol where a network of independent validators exchanges proposals and votes to agree on which transactions to include in the next ledger. This approach enables the network to process transactions quickly while maintaining strong security guarantees.

Consensus Protocol Overview

What is Consensus?

Consensus is the process by which a distributed network of nodes agrees on a single shared state. In the context of the XRP Ledger, this means agreeing on:

Which transactions to include in the next ledger
The order of those transactions (deterministic ordering)
The resulting ledger state after applying all transactions

Without consensus, different nodes might have different views of the ledger, leading to double-spending and inconsistencies.

Why Not Proof-of-Work?

Traditional blockchains like Bitcoin use proof-of-work (PoW):

Miners compete to solve cryptographic puzzles
Winner proposes the next block
Requires massive computational resources
Block confirmation takes ~10 minutes (Bitcoin) or ~15 seconds (Ethereum)

XRP Ledger's approach is different:

No mining or computational puzzles
Validators vote on transaction sets
Consensus achieved in rounds lasting 3-5 seconds
Energy efficient (no wasted computation)

Byzantine Fault Tolerance

The XRP Ledger consensus protocol is Byzantine Fault Tolerant (BFT), meaning it can tolerate some validators being:

Offline or unreachable
Malicious (trying to disrupt consensus)
Byzantine (behaving arbitrarily or incorrectly)

Key Property: As long as >80% of trusted validators are honest and online, consensus will be reached correctly.

Security Model:

Validators and UNL

Validators are nodes that participate in the XRP Ledger consensus process, validating transactions and agreeing on the state of the ledger. Each validator proposes and votes on ledger updates during consensus rounds.

A Unique Node List (UNL) is a trusted set of validators chosen by a participant. By relying on their UNL, a node can efficiently reach consensus while protecting against faulty or malicious validators. Proper UNL selection is crucial for network security, decentralization, and ledger reliability.

What is a Validator?

A validator is a rippled server configured to participate in consensus by:

Proposing transaction sets
Voting on other validators' proposals
Signing validated ledgers

Not all rippled servers are validators. Most servers are:

Tracking servers: Follow the network and process transactions but don't participate in consensus
Stock servers: Serve API requests but don't store full history

To become a validator, a server needs:

A validator key pair (generated with validator-keys tool)
Configuration in rippled.cfg to enable validation
To be trusted by other validators (added to their UNLs)

Unique Node List (UNL)

Each validator maintains a Unique Node List (UNL)—a list of validators it trusts to be honest and not collude.

Key Concepts:

Personal Choice: Each validator operator chooses their own UNL based on their trust relationships.

Overlap Required: For the network to reach consensus, there must be sufficient overlap between validators' UNLs. The protocol requires >90% overlap to ensure agreement.

Default UNL: Most operators use the default UNL provided by the XRP Ledger Foundation, which is regularly updated and reviewed.

Dynamic Updates: UNLs can be updated over time as validators join or leave the network.

UNL Configuration

In validators.txt:

Validator List Management

The validator list can be automatically fetched from trusted sources:

This allows dynamic updates without manual configuration changes.

Consensus Rounds

Round Structure

Consensus operates in discrete rounds, each typically lasting 3-5 seconds. Each round attempts to agree on the next ledger.

Round Phases:

Phase 1: Open Phase

Duration: Variable (typically 20-50 seconds, but can be shorter)

Purpose: Collect transactions for the next ledger

What Happens:

Transactions arrive from clients and peers
Transactions are validated and added to the open ledger
Each validator builds its own transaction set
Open ledger is tentatively applied (provides immediate feedback)

Key Point: The open ledger is not final—it shows what might be in the next ledger, but consensus hasn't been reached yet.

Phase 2: Establish Phase (Consensus Rounds)

Duration: 2-4 seconds (multiple sub-rounds with 50% increase each time)

Purpose: Validators exchange proposals and converge on a common transaction set

Process:

Initial Proposal

Each validator creates a proposal containing:

Hash of their proposed transaction set
Their validator signature
Previous ledger hash
Proposed close time

Proposal Exchange

Validators broadcast proposals to the network using tmPROPOSE_LEDGER messages.

Agreement Threshold

Validators track which transactions appear in proposals from their UNL:

80% agreement: Transaction is considered "likely to be included"
50% agreement: Transaction is "disputed"
<50% agreement: Transaction is "unlikely to be included"

Iterative Refinement

Multiple rounds of proposals:

Round 1 (Initial): Each validator proposes their transaction set

Round 2 (50% threshold): Validators update proposals, including only transactions with >50% support

Round 3+ (Increasing threshold): Threshold increases each round, converging toward agreement

Avalanche Effect

Once enough validators converge on the same set, others quickly follow (avalanche effect), achieving rapid consensus.

Phase 3: Accepted Phase

Duration: Instant (threshold is reached)

Purpose: Consensus is reached, transaction set is accepted

Trigger: When a validator sees >80% of its UNL agreeing on the same transaction set

What Happens:

The agreed-upon transaction set becomes the "accepted" set
Ledger is closed with this transaction set
Validators compute the resulting ledger hash
Consensus round ends

Phase 4: Validated Phase

Duration: 1-2 seconds

Purpose: Validators sign and broadcast validations

What Happens:

Each validator applies the agreed transaction set
Computes the resulting ledger hash
Creates a validation message
Signs and broadcasts the validation

Validation Message (tmVALIDATION):

Validation Collection:

Nodes collect validations from validators
When >80% of trusted validators validate the same ledger hash, it's considered fully validated
The ledger becomes immutable and part of the permanent ledger history

Consensus Round Timeline

Total time from consensus start to validation: ~10 seconds Total time from transaction submission to confirmation: ~15-60 seconds (depending on when submitted during open phase)

Transaction Ordering and Determinism

Why Ordering Matters

For all validators to reach the same ledger state, they must apply transactions in exactly the same order. Different orders can produce different results:

Example:

Canonical Ordering

The XRP Ledger uses canonical ordering to ensure determinism:

Primary Sort: By account (lexicographic order of account IDs)

Secondary Sort: By transaction sequence number (nonce)

This ensures:

All transactions from the same account are processed in sequence order
Transactions from different accounts are processed in a deterministic order
All validators apply transactions identically

Transaction Set Hash

The transaction set is represented by a hash:

This hash is what validators include in their proposals—a compact representation of the entire transaction set.

Dispute Resolution

What is a Dispute?

A dispute occurs when validators initially disagree about which transactions should be included in the next ledger. This is normal and expected—validators may have different views due to:

Network latency (different arrival times)
Transaction validity questions
Different open ledger states

Resolution Process

Disputes are resolved through the iterative consensus rounds:

Round 1: Initial Disagreement

Round 2: Converge on High-Agreement TXs

Validators drop transactions with <50% support:

Round 3: Further Convergence

As threshold increases to 80%, validators must drop disputed transactions:

Deferred Transactions

Transactions that don't reach consensus are not lost:

They remain in the open ledger
They'll be included in the next consensus round
They're only dropped if they become invalid

Byzantine Validators

If a validator behaves maliciously:

Their proposals are signed, so misbehavior is detectable
Other validators ignore proposals that don't follow protocol rules
Byzantine validators cannot force consensus on invalid states (requires >80% support)
Operators can remove misbehaving validators from their UNL

Ledger Close Process

Close Triggers

A ledger close is triggered when:

Timer-based: Minimum time has elapsed (typically 2-10 seconds)

Transaction threshold: Sufficient transactions have accumulated

Consensus readiness: Validators are ready to reach agreement

Close Time Agreement

Validators must also agree on the close time of the ledger:

Why it matters: Some transactions are time-dependent (escrows, offers with expiration)

Process:

Each validator proposes a close time
Consensus includes the close time in proposals
Final close time is the median of proposed times (Byzantine fault tolerant)

Close Time Resolution:

Rounded to nearest 10 seconds for efficiency
Prevents clock skew from causing issues

Post-Consensus Application

After consensus is reached:

Step 1: Apply agreed transaction set

Step 2: Compute ledger hash

Step 3: Create and broadcast validation

Step 4: Collect validations

Codebase Deep Dive

Key Files and Directories

Consensus Core:

src/ripple/consensus/Consensus.h - Main consensus engine interface
src/ripple/consensus/ConsensusProposal.h - Proposal structure
src/ripple/consensus/Validations.h - Validation tracking

Consensus Implementation:

src/ripple/app/consensus/RCLConsensus.h - XRP Ledger-specific consensus
src/ripple/app/consensus/RCLValidations.cpp - Validation handling

Network Messages:

src/ripple/overlay/impl/ProtocolMessage.h - tmPROPOSE_LEDGER, tmVALIDATION

Configuration:

validators.txt - UNL configuration
rippled.cfg - Validator key configuration

Key Classes

Consensus Class

RCLConsensus (Ripple Consensus Ledger)

XRP Ledger-specific consensus implementation:

Finding Consensus Start

Search for ledger close triggers:

Tracing Proposal Handling

Follow proposal processing:

Understanding Validation

Follow validation creation and verification:

Hands-On Exercise

Exercise: Observe and Analyze a Consensus Round

Objective: Watch a complete consensus round and understand the proposal exchange process.

Part 1: Setup Multi-Validator Environment

This is advanced—requires multiple validators. For learning, we'll use logs from a single validator.

Step 1: Enable detailed consensus logging

Edit rippled.cfg:

Step 2: Start rippled

Step 3: Watch the logs

Part 2: Identify Consensus Phases

From the logs, identify:

Open Phase Start:

Consensus Round Start:

Proposals Received:

Agreement Tracking:

Consensus Reached:

Validation Created:

Validation Received:

Ledger Fully Validated:

Part 3: Timing Analysis

Measure the duration of each phase:

Open Phase Duration: Time between "open ledger started" and "Starting consensus round"
Consensus Duration: Time from "Starting consensus round" to "Consensus reached"
Validation Duration: Time from "Consensus reached" to "fully validated"

Create a timeline:

Part 4: Analysis Questions

Answer these based on your observations:

How many consensus rounds occurred?
- Count from logs
What was the average consensus time?
- Measure multiple rounds

Part 5: Compare to Whitepaper

Read the XRP Ledger Consensus Protocol whitepaper and compare:

Does the observed behavior match the description?
Are the timing estimates accurate?
How does the network handle disputes?

Key Takeaways

Core Concepts

✅ Byzantine Fault Tolerance: Network can tolerate up to 20% faulty validators while maintaining security

✅ UNL-Based Trust: Each validator chooses which other validators to trust, creating a trust graph

✅ Iterative Consensus: Multiple rounds of proposals converge on an agreed transaction set

✅ Fast Finality: 3-5 second consensus rounds enable quick transaction confirmation

✅ No Mining: Consensus achieved through voting, not computational work

✅ Deterministic Ordering: Canonical transaction ordering ensures all validators reach identical state

✅ Dispute Resolution: Disagreements resolved by dropping disputed transactions to next round

Security Properties

✅ Safety: No conflicting ledgers validated (no forks in normal operation)

✅ Liveness: Network makes progress as long as >80% of UNL is honest and responsive

✅ Censorship Resistance: No single entity can block valid transactions

✅ Sybil Resistance: Trust relationships (UNL) prevent fake validator attacks

Development Skills

✅ Codebase Location: Consensus implementation in src/ripple/consensus/ and src/ripple/app/consensus/

✅ Proposal Format: Understand ConsensusProposal structure and tmPROPOSE_LEDGER messages

✅ Validation Format: Understand STValidation structure and tmVALIDATION messages

✅ Debugging: Use consensus logs to trace round progression and identify issues

Common Misconceptions

Misconception 1: "Validators mine like Bitcoin"

False: Validators don't perform computational work. They simply vote on which transactions to include.

Misconception 2: "Ripple controls consensus"

False: Any organization can run validators, and each validator operator independently chooses their UNL. While many operators use the recommended UNL from the XRP Ledger Foundation, they're free to customize it.

Misconception 3: "All servers participate in consensus"

False: Most rippled servers are tracking servers that follow consensus but don't vote. Only configured validators participate.

Misconception 4: "Consensus can be blocked by one entity"

False: As long as >80% of a validator's UNL is operational and honest, consensus proceeds normally.

Misconception 5: "XRP Ledger has forked"

False: The XRP Ledger has never had a fork (competing chains). The consensus protocol prevents this by design.

Additional Resources

Official Documentation

XRP Ledger Dev Portal:
Consensus Protocol:
Run a Validator:

Academic Papers

Original Consensus Whitepaper: David Schwartz, Noah Youngs, Arthur Britto
Analysis of the XRP Ledger Consensus Protocol: Brad Chase, Ethan MacBrough
Cobalt: BFT Governance in Open Networks: Ethan MacBrough

Codebase References

src/ripple/consensus/ - Generic consensus framework
src/ripple/app/consensus/ - XRP Ledger-specific implementation
src/ripple/app/ledger/ConsensusTransSetSF.cpp - Transaction set management

- How consensus messages are propagated
- How consensus integrates with other components
- How transactions flow through consensus

Application Layer: Central Orchestration and Coordination

← Back to Rippled II Overview

Introduction

The Application layer is the heart of Rippled's architecture—the central orchestrator that initializes, coordinates, and manages all subsystems. Understanding the Application layer is essential for grasping how Rippled operates as a cohesive system, where consensus, networking, transaction processing, and ledger management all work together seamlessly.

At its core, the Application class acts as a dependency injection container and service locator, providing every component access to the resources it needs while maintaining clean separation of concerns. Whether you're debugging a startup issue, optimizing system performance, or implementing a new feature, you'll inevitably interact with the Application layer.

The Application Class Architecture

Design Philosophy

The Application class follows several key design principles that make Rippled maintainable and extensible:

Single Point of Coordination: Instead of components directly creating and managing their dependencies, everything flows through the Application. This centralization makes it easy to understand system initialization and component relationships.

Dependency Injection: Components receive their dependencies through constructor parameters rather than creating them internally. This makes testing easier and dependencies explicit.

Interface-Based Design: The Application class implements the Application interface, allowing for different implementations (production, test, mock) without changing dependent code.

Lifetime Management: The Application controls the creation, initialization, and destruction of all major subsystems, ensuring proper startup/shutdown sequences.

Application Interface

The Application interface is defined in src/ripple/app/main/Application.h:

ApplicationImp Implementation

The concrete implementation ApplicationImp is in src/ripple/app/main/ApplicationImp.cpp. This class:

Implements all interface methods
Owns all major subsystem objects
Manages initialization order
Coordinates shutdown

Key Member Variables:

Initialization and Lifecycle

Startup Sequence

Understanding the startup sequence is crucial for debugging initialization issues and understanding component dependencies.

Phase 1: Configuration Loading

What Happens:

Parse rippled.cfg configuration file
Load validator list configuration
Set up logging configuration
Validate configuration parameters

Configuration Sections:

[server] - Server ports and interfaces
[node_db] - NodeStore database configuration
[node_size] - Performance tuning parameters

Phase 2: Application Construction

Constructor Sequence (ApplicationImp::ApplicationImp()):

Phase 3: Setup

What Happens (ApplicationImp::setup()):

Phase 4: Run

Main Event Loop (ApplicationImp::run()):

What Runs:

Job queue processes queued work
Overlay network handles peer connections
Consensus engine processes rounds
NetworkOPs coordinates operations

All work happens in background threads managed by various subsystems. The main thread simply waits for a shutdown signal.

Phase 5: Shutdown

Graceful Shutdown (ApplicationImp::signalStop()):

Shutdown Order: Components are stopped in reverse order of their creation to ensure dependencies are still available when each component shuts down.

Complete Lifecycle Diagram

Subsystem Coordination

The Service Locator Pattern

The Application acts as a service locator, allowing any component to access any other component through the app reference:

Major Subsystems

LedgerMaster

Purpose: Manages the chain of validated ledgers and coordinates ledger progression.

Key Responsibilities:

Track current validated ledger
Build candidate ledgers for consensus
Synchronize ledger history
Maintain ledger cache

Access: app.getLedgerMaster()

Important Methods:

NetworkOPs

Purpose: Coordinates network operations and transaction processing.

Key Responsibilities:

Process submitted transactions
Manage transaction queue
Coordinate consensus participation
Track network state

Access: app.getOPs()

Important Methods:

Overlay

Purpose: Manages peer-to-peer networking layer.

Key Responsibilities:

Peer discovery and connection
Message routing
Network topology maintenance
Bandwidth management

Access: app.overlay()

Important Methods:

TxQ (Transaction Queue)

Purpose: Manages transaction queuing when network is busy.

Key Responsibilities:

Queue transactions during high load
Fee-based prioritization
Account-based queuing limits
Transaction expiration

Access: app.getTxQ()

Important Methods:

NodeStore

Purpose: Persistent storage for ledger data.

Key Responsibilities:

Store ledger state nodes
Provide efficient retrieval
Cache frequently accessed data
Support different backend databases (RocksDB, NuDB)

Access: app.getNodeStore()

Important Methods:

RelationalDatabase

Purpose: SQL database for indexed data and historical queries.

Key Responsibilities:

Store transaction metadata
Maintain account transaction history
Support RPC queries (account_tx, tx)
Ledger header storage

Access: app.getRelationalDatabase()

Database Types:

SQLite (default, embedded)
PostgreSQL (production deployments)

Validations

Purpose: Manages validator signatures on ledger closes.

Key Responsibilities:

Collect validations from validators
Track validator key rotations (manifests)
Determine ledger validation quorum
Publish validation stream

Access: app.getValidations()

Important Methods:

Job Queue System

Purpose and Design

The job queue is Rippled's work scheduling system. Instead of each subsystem creating its own threads, work is submitted as jobs to a centralized queue processed by a thread pool. This provides:

Centralized thread management: Easier to control thread count and CPU usage
Priority-based scheduling: Critical jobs processed before low-priority ones
Visibility: Easy to monitor what work is queued
Deadlock prevention: Structured concurrency patterns

Job Types

Jobs are categorized by type, which determines priority:

Submitting Jobs

Components submit work to the job queue:

Job Priority and Scheduling

Priority Levels:

Critical: Consensus, validations (must not be delayed)
High: Transaction processing, ledger advancement
Medium: RPC requests, client operations
Low: Maintenance, administrative tasks

Scheduling Algorithm:

Jobs sorted by priority and submission time
Worker threads pick highest priority job
Long-running jobs can be split into chunks
System monitors queue depth and adjusts behavior

Job Queue Configuration

In rippled.cfg:

Thread count is also influenced by CPU core count:

Configuration Management

Configuration File Structure

The rippled.cfg file controls all aspects of server behavior. The Application loads and provides access to this configuration.

Example Configuration

Accessing Configuration

Components access configuration through the Application:

Runtime Configuration

Some settings can be adjusted at runtime via RPC:

Component Interaction Patterns

Pattern 1: Direct Method Calls

Most common pattern—components call each other's methods:

Pattern 2: Job Queue for Asynchronous Work

For work that should not block the caller:

Pattern 3: Event Publication

Components publish events that others subscribe to:

Pattern 4: Callback Registration

Components register callbacks for specific events:

Codebase Deep Dive

Key Files and Directories

Application Core:

src/ripple/app/main/Application.h - Application interface
src/ripple/app/main/ApplicationImp.h - Implementation header
src/ripple/app/main/ApplicationImp.cpp - Implementation

Job Queue:

src/ripple/core/JobQueue.h - Job queue interface
src/ripple/core/impl/JobQueue.cpp - Implementation
src/ripple/core/Job.h - Job definition

Configuration:

src/ripple/core/Config.h - Config class
src/ripple/core/ConfigSections.h - Section definitions

Subsystem Implementations:

src/ripple/app/ledger/LedgerMaster.h
src/ripple/app/misc/NetworkOPs.h
src/ripple/overlay/Overlay.h

Finding Application Creation

Start in main.cpp:

Tracing Component Access

Follow how components access each other:

Understanding Job Submission

Find job submissions:

Example:

Hands-On Exercise

Exercise: Trace Application Startup and Analyze Job Queue

Objective: Understand the application initialization sequence and monitor job queue activity.

Part 1: Code Exploration

Step 1: Navigate to application source

Step 2: Read the main entry point

Open main.cpp and trace:

Command-line argument parsing
Configuration loading
Application creation
Setup call

Step 3: Follow ApplicationImp construction

Open ApplicationImp.cpp and identify:

The order subsystems are created (constructor)
Dependencies between components
What happens in setup()
What happens in run()

Questions to Answer:

Why is NodeStore created before LedgerMaster?
What does LedgerMaster need from Application?
Which components are created first and why?

Part 2: Monitor Job Queue Activity

Step 1: Enable detailed job queue logging

Edit rippled.cfg:

Step 2: Start rippled in standalone mode

Step 3: Watch the startup logs

Observe jobs during startup:

What job types execute first?
How many worker threads are created?
What's the initial job queue depth?

Step 4: Submit transactions and observe

Watch the logs for:

jtTRANSACTION jobs being queued
Job processing time
Queue depth changes

Step 5: Manually close a ledger

Observe jobs related to ledger close:

jtADVANCE - Advance to next ledger
jtPUBLEDGER - Publish ledger
jtUPDATE_PF - Update path finding

Part 3: Add Custom Logging

Step 1: Modify ApplicationImp.cpp

Add logging to track component initialization:

Step 2: Recompile

Step 3: Run and observe

You should see your custom log messages showing component creation order.

Analysis Questions

Answer these based on your exploration:

What's the first subsystem created?
- Why does it need to be first?
How does the job queue decide which job to process next?
- What factors influence priority?

Key Takeaways

Core Concepts

✅ Central Orchestration: Application class coordinates all subsystems and manages their lifecycle

✅ Dependency Injection: Components receive dependencies through Application reference, not by creating them

✅ Service Locator: Application provides access to all major services (getLedgerMaster(), overlay(), etc.)

✅ Initialization Order: Subsystems are created in dependency order during construction

✅ Job Queue: Centralized work scheduling with priority-based execution

✅ Configuration: All server behavior controlled through rippled.cfg

Development Skills

✅ Codebase Location: Application implementation in src/ripple/app/main/

✅ Adding Components: Create in constructor, expose through interface method

✅ Job Submission: Use app.getJobQueue().addJob() for asynchronous work

✅ Debugging Startup: Add logging in ApplicationImp constructor to trace initialization

✅ Configuration Access: Use app.config() to read configuration values

Common Patterns and Best Practices

Pattern 1: Accessing Subsystems

Always access subsystems through the Application:

Pattern 2: Asynchronous Work

Use job queue for work that shouldn't block:

Pattern 3: Lifecycle Management

Let Application manage component lifetime:

Additional Resources

Official Documentation

XRP Ledger Dev Portal:
Rippled Setup:
Configuration Reference:

Codebase References

src/ripple/app/main/ - Application layer implementation
src/ripple/core/JobQueue.h - Job queue system
src/ripple/core/Config.h - Configuration management

- How transactions are processed
- How consensus integrates with Application
- Finding your way around the code

Overlay Network: Peer-to-Peer Networking Layer

← Back to Rippled II Overview

Introduction

The Overlay Network is Rippled's peer-to-peer networking layer that enables distributed nodes to discover each other, establish connections, and communicate efficiently. Without the overlay network, the XRP Ledger would be a collection of isolated servers—the overlay network is what transforms individual nodes into a cohesive, decentralized system.

Understanding the overlay network is essential for debugging connectivity issues, optimizing network performance, and ensuring your node participates effectively in the XRP Ledger network. Whether you're running a validator, a stock server, or developing network enhancements, deep knowledge of the overlay network is crucial.

Network Topology and Architecture

Mesh Network Design

The XRP Ledger uses a mesh topology where nodes maintain direct connections with multiple peers. This differs from:

Star topology: Central hub (single point of failure)
Ring topology: Sequential connections (vulnerable to breaks)
Tree topology: Hierarchical structure (root node critical)

Mesh Advantages:

No single point of failure: Network remains operational if individual nodes fail
Multiple communication paths: Messages can route around failed nodes
Scalability: Network can grow organically as nodes join
Resilience: Network topology self-heals as nodes enter and exit

Network Layers

The overlay network sits between the application logic and the transport layer, abstracting away the complexities of peer-to-peer communication.

Connection Types

Rippled maintains three types of peer connections:

1. Outbound Connections

Definition: Connections initiated by your node to other peers

Characteristics:

Your node acts as client
You choose which peers to connect to
Configurable connection limits
Active connection management

Configuration:

2. Inbound Connections

Definition: Connections initiated by other nodes to your server

Characteristics:

Your node acts as server
Must listen on public interface
Accept connections from unknown peers
Subject to connection limits

Configuration:

3. Fixed Connections

Definition: Persistent connections to trusted peers

Characteristics:

High priority, always maintained
Automatically reconnect if disconnected
Bypass some connection limits
Ideal for validators and cluster peers

Configuration:

Target Connection Count

Rippled aims to maintain a target number of active peer connections:

Default Targets (based on node_size):

Connection Distribution:

Approximately 50% outbound connections
Approximately 50% inbound connections
Fixed connections count toward total
System adjusts dynamically to maintain target

Peer Discovery Mechanisms

1. Configured Peer Lists

The most basic discovery method—manually configured peers:

[ips] Section: Peers to connect to automatically

[ips_fixed] Section: High-priority persistent connections

Advantages:

Reliable, known peers
Administrative control
Suitable for private networks

Disadvantages:

Manual maintenance required
Limited to configured peers
Doesn't scale automatically

2. DNS Seeds

DNS-based peer discovery for bootstrap:

How It Works:

Node queries DNS for peer addresses
DNS returns A records (IP addresses)
Node connects to returned addresses
Learns about additional peers through gossip

Configuration:

DNS Resolution Example:

Advantages:

Easy bootstrap for new nodes
Dynamic peer lists
Load balancing via DNS

Disadvantages:

Requires DNS infrastructure
Vulnerable to DNS attacks
Single point of failure for initial connection

3. Peer Gossip Protocol

Peers share information about other peers they know:

Message Type: Endpoint announcements (part of peer protocol)

Process:

Peer A connects to Peer B
Peer B shares list of other known peers
Peer A considers these peers for connection
Peer A may connect to some of the suggested peers

Gossip Information Includes:

Peer IP addresses
Peer public keys
Last seen time
Connection quality hints

Advantages:

Network self-organizes
No central directory needed
Discovers new peers automatically
Network grows organically

Disadvantages:

Potential for malicious peer injection
Network topology influenced by gossip patterns
Initial bootstrapping still needed

4. Peer Crawler

Some nodes run peer crawlers to discover and monitor network topology:

What Crawlers Do:

Connect to known peers
Request peer lists
Recursively discover more peers
Map network topology

Public Peer Lists:

Various community-maintained lists
Used by new nodes to bootstrap
Updated regularly

Connection Establishment and Handshake

Connection Lifecycle

Detailed Handshake Process

Step 1: TCP Connection

Standard TCP three-way handshake:

Configuration:

Step 2: TLS Handshake (Optional but Recommended)

If TLS is configured, encrypted channel is established:

Benefits of TLS:

Encrypted communication (privacy)
Peer authentication (security)
Protection against eavesdropping
Man-in-the-middle prevention

Step 3: Protocol Handshake

Rippled-specific handshake exchanges capabilities:

Hello Message (from initiator):

Response (from receiver):

Handshake Validation:

Compatibility Check:

Step 4: Connection Acceptance/Rejection

After handshake validation:

If Compatible:

Connection moves to Active state
Add to peer list
Begin normal message exchange
Log successful connection

If Incompatible:

Send rejection message with reason
Close connection gracefully
Log rejection reason
May add to temporary ban list

Rejection Reasons:

Connection Management

Connection Limits

Rippled enforces various connection limits:

Per-IP Limits

Total Connection Limits

Based on node_size configuration:

Formula: target + (target / 2)

Fixed Peer Priority

Fixed peers bypass some limits:

Connection Quality Assessment

Rippled continuously monitors peer quality:

Metrics Tracked

Latency: Response time to ping messages

Message Rate: Messages per second

Error Rate: Protocol errors, malformed messages

Uptime: Connection duration

Quality Scoring

Peers are scored based on metrics:

Score Usage:

Low-scoring peers may be disconnected
High-scoring peers prioritized for reconnection
Informs peer selection decisions

Connection Pruning

When connection limits are reached, low-quality peers are pruned:

Reconnection Logic

After disconnection, Rippled may attempt to reconnect:

Exponential Backoff:

Fixed Peer Priority:

Message Routing and Broadcasting

Message Types

Different message types require different routing strategies:

Critical Messages (Broadcast to All)

Validations (tmVALIDATION):

Must reach all validators
Broadcast to all peers immediately
Critical for consensus

Consensus Proposals (tmPROPOSE_LEDGER):

Must reach all validators
Time-sensitive
Broadcast widely

Broadcast Pattern:

Transactions (Selective Relay)

Transaction Messages (tmTRANSACTION):

Should reach all nodes eventually
Don't need immediate broadcast to all
Use intelligent relay

Relay Logic:

Request/Response (Unicast)

Ledger Data Requests (tmGET_LEDGER):

Directed to specific peer
Response goes back to requester
No broadcasting needed

Unicast Pattern:

Squelch Algorithm

Squelch prevents message echo loops:

Problem:

Solution:

Recent Message Cache:

Time-based expiration (e.g., 30 seconds)
Size-based limits (e.g., 10,000 entries)
LRU eviction policy

Message Priority Queues

Outbound messages are queued with priority:

Benefits:

Critical messages sent first
Prevents head-of-line blocking
Better network utilization

Network Health and Monitoring

Health Metrics

Connectivity Metrics

Active Peers: Current peer count

Target vs Actual: Comparison to target

Connection Distribution:

Network Quality Metrics

Average Latency:

Message Rate:

Validator Connectivity:

RPC Monitoring Commands

peers Command

Get current peer list:

Response:

peer_reservations Command

View reserved peer slots:

connect Command

Manually connect to peer:

Logging and Diagnostics

Enable detailed overlay logging:

Log Messages to Monitor:

Codebase Deep Dive

Key Files and Directories

Overlay Core:

src/ripple/overlay/Overlay.h - Main overlay interface
src/ripple/overlay/impl/OverlayImpl.h - Implementation header
src/ripple/overlay/impl/OverlayImpl.cpp - Core implementation

Peer Management:

src/ripple/overlay/Peer.h - Peer interface
src/ripple/overlay/impl/PeerImp.h - Peer implementation
src/ripple/overlay/impl/PeerImp.cpp - Peer logic

Connection Handling:

src/ripple/overlay/impl/ConnectAttempt.h - Outbound connections
src/ripple/overlay/impl/InboundHandoff.h - Inbound connections

Message Processing:

src/ripple/overlay/impl/ProtocolMessage.h - Message definitions
src/ripple/overlay/impl/Message.cpp - Message handling

Key Classes

Overlay Class

PeerImp Class

Finding Connection Logic

Search for connection establishment:

Tracing Message Flow

Follow message from receipt to processing:

Hands-On Exercise

Exercise: Monitor and Analyze Network Topology

Objective: Understand your node's position in the network and analyze peer connections.

Part 1: Initial Network State

Step 1: Get current peer list

Step 2: Analyze the output

Count:

Total peers
Outbound vs inbound connections
Peer versions
Geographic distribution (if known)

Questions:

Do you have the target number of peers?
Is the outbound/inbound ratio balanced?
Are you connected to validators in your UNL?

Part 2: Connection Quality Analysis

Step 1: Enable overlay logging

Step 2: Monitor for 5 minutes

Step 3: Identify patterns

Look for:

Average peer latency
Connection failures
Disconnection reasons
Reconnection attempts

Part 3: Connectivity Test

Step 1: Manually connect to a peer

Step 2: Verify connection

Step 3: Observe handshake in logs

Part 4: Network Health Check

Step 1: Check peer count over time

Step 2: Monitor connection churn

Step 3: Assess stability

Calculate:

Connection churn rate (disconnections per hour)
Average peer lifetime
Reconnection frequency

Part 5: Peer Quality Distribution

Step 1: Extract peer metrics

From peers output, record for each peer:

Latency
Uptime
Complete ledgers range

Step 2: Create distribution charts

Latency distribution:

Step 3: Identify issues

Are any peers consistently high-latency?
Do any peers have incomplete ledger history?
Are there peers with low uptime?

Analysis Questions

Answer these based on your observations:

What's your average peer latency?
- Is it acceptable (<200ms)?
How stable are your connections?
- High churn may indicate network issues

Key Takeaways

Core Concepts

✅ Mesh Topology: Decentralized network with no single point of failure

✅ Three Connection Types: Outbound, inbound, and fixed connections serve different purposes

✅ Multi-Mechanism Discovery: DNS seeds, configured peers, and gossip protocol enable robust peer discovery

✅ Connection Quality: Continuous monitoring and scoring of peer quality

✅ Intelligent Routing: Message-specific routing strategies optimize network efficiency

✅ Squelch Algorithm: Prevents message loops and duplicate processing

✅ Priority Queuing: Ensures critical messages are transmitted first

Network Health

✅ Target Peer Count: Based on node_size configuration

✅ Balanced Connections: ~50% outbound, ~50% inbound

✅ Quality Metrics: Latency, message rate, error rate, uptime

✅ Connection Pruning: Low-quality peers replaced with better alternatives

✅ Fixed Peer Priority: Critical connections maintained aggressively

Development Skills

✅ Codebase Location: Overlay implementation in src/ripple/overlay/

✅ Configuration: Understanding [ips], [ips_fixed], [port_peer] sections

✅ Monitoring: Using RPC commands and logs to assess network health

✅ Debugging: Tracing connection issues and message flow

Common Issues and Solutions

Issue 1: Low Peer Count

Symptoms: Active peers consistently below target

Possible Causes:

Firewall blocking inbound connections
ISP blocking port
Poor peer quality (all disconnect quickly)

Solutions:

Issue 2: High Latency Peers

Symptoms: Average latency >200ms

Possible Causes:

Geographic distance to peers
Network congestion
Poor quality peers

Solutions:

Issue 3: Frequent Disconnections

Symptoms: High connection churn rate

Possible Causes:

Network instability
Protocol incompatibility
Being saturated by other peers

Solutions:

Issue 4: No Validator Connections

Symptoms: Not connected to any UNL validators

Possible Causes:

Validators are unreachable
Validators' connection slots full
Network configuration issues

Solutions:

Additional Resources

Official Documentation

XRP Ledger Dev Portal:
Peer Protocol:
Server Configuration:

Codebase References

src/ripple/overlay/ - Overlay network implementation
src/ripple/overlay/impl/PeerImp.cpp - Peer connection handling
src/ripple/overlay/impl/OverlayImpl.cpp - Core overlay logic

- Protocol message formats and communication
- How consensus uses overlay network
- How overlay integrates with application

Transaction Lifecycle: Complete Transaction Journey

← Back to Rippled II Overview

Introduction

Understanding the complete lifecycle of a transaction—from the moment it's created to its final inclusion in a validated ledger—is crucial for developing applications on the XRP Ledger, debugging transaction issues, and optimizing transaction processing. Every transaction follows a well-defined path through multiple validation stages, consensus rounds, and finalization steps.

This deep dive traces the entire journey of a transaction, explaining each phase, the checks performed, the state transitions, and how to monitor and query transaction status at every step. Whether you're building a wallet, an exchange integration, or contributing to the core protocol, mastering the transaction lifecycle is essential.

Transaction Lifecycle Overview

Complete Journey Diagram

Typical Timeline

Fast Path (ideal conditions):

Slow Path (transaction arrives late in open phase):

Phase 1: Transaction Creation

Transaction Structure

Before submission, a transaction must be properly constructed:

Required Fields

Universal Fields (all transaction types):

TransactionType - Type of transaction (Payment, OfferCreate, etc.)
Account - Source account (sender)
Fee - Transaction fee in drops (1 XRP = 1,000,000 drops)

Optional but Recommended:

LastLedgerSequence - Expiration ledger (transaction invalid after this)
SourceTag / DestinationTag - Integer tags for routing/identification
Memos - Arbitrary data attached to transaction

Transaction Signing

Single Signature:

Multi-Signature:

Transaction Hash

The transaction hash (ID) is calculated from the signed transaction:

Important: The hash is deterministic—the same signed transaction always produces the same hash.

Phase 2: Transaction Submission

Submission Methods

Method 1: RPC Submit

Submit via JSON-RPC:

Response:

Method 2: WebSocket Submit

Real-time submission with streaming updates:

Method 3: Peer Network Submission

Transactions submitted to one node propagate to all nodes:

Even if submitted to a non-validator, the transaction reaches validators through peer-to-peer propagation.

Submission Response

Immediate response indicates initial validation result:

Success Codes:

tesSUCCESS - Transaction applied to open ledger
terQUEUED - Transaction queued (network busy)

Temporary Failure (can retry):

terPRE_SEQ - Sequence too high, earlier tx needed
tefPAST_SEQ - Sequence too low (already used)

Permanent Failure (don't retry):

temMALFORMED - Malformed transaction
temBAD_FEE - Invalid fee
temBAD_SIGNATURE - Invalid signature

Phase 3: Initial Validation

Preflight Checks

Before accessing ledger state, static validation occurs:

Checks Performed:

✓ Cryptographic signature valid
✓ Transaction format correct
✓ Required fields present
✓ Fee sufficient

Why Preflight Matters: Catches obvious errors before expensive ledger state access.

Phase 4: Preclaim Validation

Ledger State Checks

Read-only validation against current ledger state:

Checks Performed:

✓ Source account exists
✓ Sequence number correct
✓ Sufficient balance (including fee)
✓ Destination account requirements met

Phase 5: Open Ledger Application

Tentative Application

Transaction is tentatively applied to provide immediate feedback:

Open Ledger Characteristics:

Not Final: Open ledger is tentative, changes frequently
No Consensus: Local view only, other nodes may differ
Immediate Feedback: Clients get instant response
Can Change: Transaction may be removed or re-ordered

Why It Matters:

Users get immediate confirmation
Wallets can show pending transactions
Applications can provide real-time updates

Phase 6: Network Propagation

Transaction Broadcasting

Once applied to open ledger, transaction broadcasts to peers:

Propagation Speed:

Local network: < 100ms
Global network: 200-500ms
All nodes receive transaction within 1 second

Deduplication:

Nodes track recently seen transactions
Duplicate transactions not re-processed
Prevents network flooding

Phase 7: Consensus Round

Transaction Set Building

As ledger close approaches, validators build transaction sets:

Consensus Process

Validators exchange proposals and converge:

Round 1: Initial proposals

Round 2: Converge on high-agreement transactions

Transaction Inclusion Criteria:

80% of UNL must agree to include
Transaction must still be valid
Must not have expired (LastLedgerSequence)

Phase 8: Canonical Application

Deterministic Execution

After consensus, transactions are applied in canonical order:

DoApply Execution:

Result Codes:

tesSUCCESS - Transaction succeeded
tecUNFUNDED - Failed but fee charged
tecNO_TARGET - Failed but fee charged

Important: Even failed transactions (tec codes) consume the fee and advance the sequence number.

Phase 9: Ledger Closure

Closing the Ledger

After all transactions are applied:

Ledger Hash Calculation:

Phase 10: Validation Phase

Creating Validations

Validators sign the closed ledger:

Broadcasting Validations

Collecting Validations

Phase 11: Fully Validated

Finalization

When quorum is reached, ledger becomes fully validated:

Characteristics of Validated Ledger:

Immutable: Cannot be changed
Permanent: Part of ledger history forever
Canonical: All nodes have identical copy
Final: Transactions cannot be reversed

Transaction Status Querying

Methods to Check Transaction Status

Method 1: tx RPC

Query by transaction hash:

Response:

Key Fields:

validated: true = in validated ledger, false = pending
meta.TransactionResult: Final result code
ledger_index: Which ledger contains transaction

Method 2: account_tx RPC

Query all transactions for an account:

Lists transactions in reverse chronological order.

Method 3: WebSocket Subscriptions

Real-time transaction monitoring:

Subscription Types:

accounts - Transactions affecting specific accounts
transactions - All transactions network-wide
ledger - Ledger close events

Transaction Metadata

Metadata Structure

Metadata records the effects of a transaction:

AffectedNodes Types:

CreatedNode - New ledger object created
ModifiedNode - Existing object modified
DeletedNode - Object deleted

Key Metadata Fields:

TransactionIndex - Position in ledger
TransactionResult - Final result code
delivered_amount - Actual amount delivered (for partial payments)

Transaction Expiration

LastLedgerSequence

Transactions can specify an expiration:

Behavior:

If not included by ledger 75234567, transaction becomes invalid
Prevents transactions from being stuck indefinitely
Recommended: Set to current ledger + 4

Checking Expiration:

Hands-On Exercise

Exercise: Track a Transaction Through Its Complete Lifecycle

Objective: Submit a transaction and observe it at each phase of the lifecycle.

Part 1: Prepare and Submit

Step 1: Create and fund test accounts

Step 2: Prepare transaction with monitoring

Step 3: Submit and record time

Part 2: Monitor Progress

Step 4: Subscribe to transaction

Step 5: Poll for status

Part 3: Analyze Results

Step 6: Examine metadata

Analysis Questions

Answer these based on your observations:

How long did each phase take?
- Submission to initial result: ___ ms
- Initial result to validated: ___ ms
- Total time: ___ ms

Key Takeaways

Core Concepts

✅ 11-Phase Journey: Transactions go through creation, submission, validation, consensus, application, and finalization

✅ Multiple Validation Stages: Preflight (static), Preclaim (state-based), DoApply (execution)

✅ Open Ledger Preview: Tentative application provides immediate feedback before consensus

✅ Consensus Inclusion: Validators must agree (>80%) to include transaction

✅ Canonical Order: Deterministic ordering ensures all nodes reach identical state

✅ Immutable Finality: Once validated, transactions cannot be reversed

✅ Metadata Records Effects: Complete record of all ledger modifications

Timing Expectations

✅ Fast Path: ~7 seconds submission to validation

✅ Slow Path: ~30 seconds if submitted late in open phase

✅ Network Propagation: <1 second to reach all nodes

✅ Consensus Round: 3-5 seconds

Development Skills

✅ Transaction Construction: Proper signing and field selection

✅ Status Monitoring: Using tx, account_tx, and subscriptions

✅ Error Handling: Understanding result codes (tem/tef/ter/tec/tes)

✅ Expiration Management: Setting LastLedgerSequence appropriately

✅ Metadata Analysis: Understanding transaction effects

Common Issues and Solutions

Issue 1: Transaction Stuck Pending

Symptoms: Transaction not validating after 30+ seconds

Possible Causes:

Insufficient fee (transaction queued)
Network congestion
Sequence gap (earlier transaction missing)

Solutions:

Issue 2: tefPAST_SEQ Error

Symptoms: Sequence number already used

Cause: Sequence out of sync or transaction already processed

Solution:

Issue 3: Transaction Not Found

Symptoms: tx command returns "txnNotFound"

Possible Causes:

Transaction not yet in validated ledger
Transaction expired (LastLedgerSequence)
Transaction rejected during validation

Solution:

Issue 4: tecUNFUNDED_PAYMENT

Symptoms: Transaction failed with fee charged

Cause: Insufficient balance between submission and execution

Prevention:

Additional Resources

Official Documentation

XRP Ledger Dev Portal:
Transaction Types:
Transaction Results:

Codebase References

src/ripple/app/tx/impl/Transactor.cpp - Transaction processing
src/ripple/app/misc/NetworkOPs.cpp - Network operations and transaction handling
src/ripple/app/ledger/OpenLedger.cpp - Open ledger management

- How transactions are validated and executed
- How transactions are included in consensus
- How transactions are propagated across the network

Trainings

Welcome

Available resources

Further reading

XRPL Basics

Getting Started

Reading and subscribing to Transactions

Creating a payment transaction

Reading transactions

Listening for transactions

Non Fungible Tokens

Start coding

Token Issuance and Liquidity

Creating Accounts

Creating wallets

Issuing Tokens

Creating tokens

Dealing with token codes

Creating an AMM Pool

Create an AMM Pool

Cyphered Chat on XRPL

Set up

Set up Keys

Cypher the message

Set up the memo & send the tx

Get the message and decypher it

EVM Sidechain

EVM workshop Jan 2024

Documentation:

Connecting Metamask

Connect Metamask

EVM Network for Metamask

Bridging Assets

Bridge Funds

Remix

Deploying your first smart contract

Creating other contracts

Banking App

Clone repo

Deploy the banking smart contract

Run the Frontend

Core Dev Bootcamp

Compilation Process & Generating Binary

Building Rippled from Source

Introduction

Local Development & Testing

Running Rippled in Standalone Mode

Introduction

Homeworks

Homework 1: Rippled Node Setup and Mainnet Synchronization

Objective

Homeworks

Homework 1: Transaction Flow Analysis

Objective

Homework 2: Transactor Code Exploration

Objective

Homework 3: Logging and Debugging

Objective

Requirements

Deliverable

Homework 4: Architecture Diagram

Objective

Appendices

Random Number Generation

Appendices

Homeworks

Message Relaying

Introduction

OverlayImpl::relay

Slot::update and Squelch Mechanism

Appendices

Homeworks

Welcome

Available resources

Further reading

Getting Started

Creating Accounts

Creating wallets

Homework 4: Architecture Diagram

Objective