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

Client → Transport Layer → Parser → Validator → Auth → Dispatcher → Handler → Response Builder → Client

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:

[port_rpc_admin_local]
port = 5005
ip = 127.0.0.1
admin = 127.0.0.1
protocol = http

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

The HTTP server receives the raw request:

POST / HTTP/1.1
Host: localhost:5005
Content-Type: application/json

{
    "method": "account_info",
    "params": [{
        "account": "rN7n7otQDd6FczFgLdlqtyMVrn3NnrcVXs",
        "ledger_index": "validated"
    }]
}

WebSocket Entry Point

For WebSocket connections, clients establish a persistent connection:

[port_ws_admin_local]
port = 6006
ip = 127.0.0.1
admin = 127.0.0.1
protocol = ws

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

WebSocket messages use a slightly different format:

{
    "id": 1,
    "command": "account_info",
    "account": "rN7n7otQDd6FczFgLdlqtyMVrn3NnrcVXs",
    "ledger_index": "validated"
}

gRPC Entry Point

For gRPC, requests arrive as Protocol Buffer messages:

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

message GetAccountInfoRequest {
    string account = 1;
    LedgerSpecifier ledger = 2;
}

---

Stage 2: Request Parsing

The raw request is parsed into a structured format.

JSON Parsing

// Parse the JSON body
Json::Value request;
Json::Reader reader;

if (!reader.parse(requestBody, request)) {
    return rpcError(rpcINVALID_PARAMS, "Unable to parse JSON");
}

Field Extraction

The parser extracts key fields:

std::string method = request["method"].asString();
Json::Value params = request["params"];
unsigned int apiVersion = request.get("api_version", 1).asUInt();

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
requestRole(
    Role const& required,
    Port const& port,
    Json::Value const& params,
    beast::IP::Endpoint const& remoteIp,
    std::string_view user)
{
    if (isAdmin(port, params, remoteIp.address()))
        return Role::ADMIN;

    if (required == Role::ADMIN)
        return Role::FORBID;

    if (ipAllowed(
            remoteIp.address(),
            port.secure_gateway_nets_v4,
            port.secure_gateway_nets_v6))
    {
        if (user.size())
            return Role::IDENTIFIED;
        return Role::PROXY;
    }

    return Role::GUEST;
}

Role Hierarchy

FORBID < GUEST < USER < IDENTIFIED < ADMIN

Role descriptions:

• FORBID: Blacklisted client (blocked)

• GUEST: Unauthenticated public access (limited commands)

• USER: Authenticated client (most read operations)

• IDENTIFIED: Trusted gateway (write operations)

• ADMIN: Full administrative access (all commands)

Configuration Example

[rpc_admin]
admin = 127.0.0.1, ::1

[secure_gateway]
ip = 192.168.1.100

---

Stage 4: Handler Lookup

The dispatcher searches the handler table for the requested command:

// Look up the handler
auto const it = handlerTable.find(method);

if (it == handlerTable.end()) {
    return rpcError(rpcUNKNOWN_COMMAND, "Unknown method");
}

HandlerInfo const& handlerInfo = it->second;

Version Matching

If API versioning is in use:

if (apiVersion < handlerInfo.version_min ||
    apiVersion > handlerInfo.version_max)
{
    return rpcError(rpcINVALID_API_VERSION);
}

---

Stage 5: Permission Verification

The system checks if the caller has sufficient permissions:

if (context.role < handlerInfo.role) {
    return rpcError(rpcNO_PERMISSION,
        "You don't have permission for this command");
}

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

if (handlerInfo.condition & RPC::NEEDS_CURRENT_LEDGER) {
    if (!context.ledgerMaster.haveLedger()) {
        return rpcError(rpcNO_CURRENT,
            "Current ledger is not available");
    }
}

Network Connectivity Check

if (handlerInfo.condition & RPC::NEEDS_NETWORK_CONNECTION) {
    if (context.netOps.getOperatingMode() < NetworkOPs::omSYNCING) {
        return rpcError(rpcNO_NETWORK,
            "Not connected to network");
    }
}

Closed Ledger Check

if (handlerInfo.condition & RPC::NEEDS_CLOSED_LEDGER) {
    if (!context.ledgerMaster.getValidatedLedger()) {
        return rpcError(rpcNO_CLOSED,
            "No validated ledger available");
    }
}

---

Stage 7: Context Construction

A JsonContext object is built with all necessary information:

RPC::JsonContext context {
    .params = params,
    .app = app,
    .consumer = consumer,
    .role = role,
    .ledger = ledger,
    .netOps = app.getOPs(),
    .ledgerMaster = app.getLedgerMaster(),
    .apiVersion = apiVersion
};

Context provides:

• Request parameters (params)

• Application services (app)

• Resource tracking (consumer)

• Permission level (role)

• Ledger access (ledger, ledgerMaster)

• Network operations (netOps)

---

Stage 8: Resource Charging

The system tracks API usage to prevent abuse:

// Charge the client for this request
context.consumer.charge(Resource::feeReferenceRPC);

// Check if client has exceeded limits
if (context.consumer.isUnlimited() == false &&
    context.consumer.balance() <= 0)
{
    return rpcError(rpcSLOW_DOWN,
        "You are making requests too frequently");
}

Resource limits are configured per client and prevent DoS attacks.

---

Stage 9: Handler Invocation

The handler function is called with the constructed context:

Json::Value result;

try {
    result = handlerInfo.handler(context);
} catch (std::exception const& ex) {
    return rpcError(rpcINTERNAL, ex.what());
}

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

---

Stage 10: Response Construction

Success Response

For successful requests:

{
    "result": {
        "status": "success",
        "account_data": {
            "Account": "rN7n7otQDd6FczFgLdlqtyMVrn3NnrcVXs",
            "Balance": "1000000000",
            ...
        },
        "ledger_index": 12345
    }
}

Error Response

For failed requests:

{
    "result": {
        "error": "actNotFound",
        "error_code": 19,
        "error_message": "Account not found.",
        "status": "error",
        "request": {
            "command": "account_info",
            "account": "rInvalidAccount"
        }
    }
}

---

Stage 11: Response Serialization

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

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": { ... }
}

WebSocket Response

{
    "id": 1,
    "status": "success",
    "type": "response",
    "result": { ... }
}

gRPC Response

GetAccountInfoResponse {
    account_data: { ... }
}

---

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
Reception	< 1 ms	Network overhead
Parsing	< 1 ms	JSON parsing
Lookup	< 0.1 ms	Hash table lookup
Permission Check	< 0.1 ms	Simple comparison
Condition Check	< 1 ms	Ledger availability
Handler Execution	1-100 ms	Varies by handler
Serialization	< 1 ms	JSON encoding
Delivery	< 1 ms	Network overhead

Total typical latency: 5-105 ms

---

Error Handling at Each Stage

Different errors can occur at each stage:

Parsing Errors

rpcINVALID_PARAMS  // Malformed JSON
rpcBAD_SYNTAX      // Invalid structure

Lookup Errors

rpcUNKNOWN_COMMAND // Command not found
rpcINVALID_API_VERSION // Version mismatch

Permission Errors

rpcNO_PERMISSION   // Insufficient role
rpcFORBIDDEN       // Blacklisted client

Condition Errors

rpcNO_CURRENT      // No current ledger
rpcNO_NETWORK      // Not connected
rpcNO_CLOSED       // No validated ledger

Handler Errors

rpcACT_NOT_FOUND   // Account not found
rpcLGR_NOT_FOUND   // Ledger not found
rpcINTERNAL        // Unexpected error

---

Real-World Example: Tracing an account_info Request

Let's trace a complete request:

1. Client Request

{
    "method": "account_info",
    "params": [{
        "account": "rN7n7otQDd6FczFgLdlqtyMVrn3NnrcVXs",
        "ledger_index": "validated"
    }]
}

2. Reception (HTTP)

POST / HTTP/1.1
Host: localhost:5005

3. Parsing

method = "account_info"
params = { "account": "rN7n...", "ledger_index": "validated" }

4. Role Determination

remoteIP = 127.0.0.1 → Role::ADMIN

5. Handler Lookup

handler = doAccountInfo
required_role = Role::USER
condition = NEEDS_CURRENT_LEDGER

6. Permission Check

ADMIN >= USER → PASS

7. Condition Check

haveLedger() == true → PASS

8. Context Construction

context.params = params
context.role = ADMIN
context.ledger = currentLedger

9. Handler Invocation

result = doAccountInfo(context)

10. Response

{
    "result": {
        "status": "success",
        "account_data": {
            "Account": "rN7n7otQDd6FczFgLdlqtyMVrn3NnrcVXs",
            "Balance": "1000000000"
        }
    }
}

---

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.

---