The Post Office: How `CallRPC` Delivers the Message

8. The Post Office: How CallRPC Delivers the Message

We have the messenger. We have the address. We have the secret passcode. We have the formal envelope. Now comes the moment of action: the Delivery. In the Bitcoin Core source code, this is handled by a massive and complex function called CallRPC. It is the "Engine of Movement."

If the bitcoin-cli is the messenger, then CallRPC is the "Post Office." It is the system that takes the envelope, places it into a vehicle, drives it across the bridge, and then waits at the destination's "Return Window" for the reply. It is a high-stakes operation that involves coordinating networking, memory management, and timing. It is the bridge in "Active Motion."

The Vehicles of Delivery: HTTP and Libevent

To move the data, Bitcoin uses a protocol called HTTP (Hyper-Text Transfer Protocol). This is the exact same technology that your web browser uses to load a website. By using HTTP, Bitcoin can travel through almost any network on Earth, as every router and every firewall already knows how to handle it. It is the "Universal Transport Layer."

The "Engine" that drives this truck is once again libevent. Let's look at the "Logistics Operation" inside src/bitcoin-cli.cpp:

/**
 * The master delivery function. 
 * It manages the journey from your keyboard to the node's memory.
 */
static UniValue CallRPC(BaseRequestHandler* rh, const std::string& strMethod, const std::vector<std::string>& args)
{
    // 1. Creating the "Digital Truck" (The HTTP Request).
    // We tell the post office to call a specific function (http_request_done) 
    // as soon as the truck returns with an answer.
    raii_evhttp_request req = obtain_evhttp_request(http_request_done, (void*)&response);

    // 2. Applying the "Shipping Labels" (The Headers).
    struct evkeyvalq* output_headers = evhttp_request_get_output_headers(req.get());

    // Label 1: "This truck contains JSON data."
    evhttp_add_header(output_headers, "Content-Type", "application/json");

    // Label 2: "Here is my ID card (Authentication)."
    evhttp_add_header(output_headers, "Authorization", (std::string("Basic ") + credentials).c_str());

    // 3. Loading the Cargo.
    // We take our sealed JSON envelope and put it in the truck's "Cargo Hold" (the buffer).
    std::string strRequest = rh->PrepareRequest(strMethod, args).write() + "\n";
    struct evbuffer* output_buffer = evhttp_request_get_output_buffer(req.get());
    evbuffer_add(output_buffer, strRequest.data(), strRequest.size());

    // 4. The "Release": The truck leaves the station!
    // We send it to the node using the "POST" method.
    evhttp_make_request(evcon.get(), req.release(), EVHTTP_REQ_POST, "/");

    // 5. The "Wait": The messenger sits and listens for the engine's return.
    event_base_dispatch(base.get());

    // 6. Return the answer to the user.
    return response;
}

Explaining the Logistics to a Non-Coder

• obtain_evhttp_request: This is the "Allocation of Resources." The computer sets aside a small amount of memory (RAM) to act as the "Truck." This memory will hold the message, the headers, and eventually the answer. The raii_ prefix ensures that if anything goes wrong (like a power outage), the computer will "Clean Up" this memory so it doesn't get wasted. It is "Just-in-Time Engineering."

• evhttp_add_header: These are the instructions for the "Guards" along the way. The "Content-Type" header is like a sign on the side of a truck that says "PERISHABLE FOOD" or "FRAGILE GLASS." It tells the Bitcoin node how to handle the data inside. The "Authorization" header is the most critical; it contains the base64-encoded version of your password. It is the "Digital Wax Seal" on the truck's doors. It is "Contextual metadata."

• evbuffer_add: This is the "Loading Dock." The JSON envelope we built in the last chapter is just a piece of "Information." To send it over a wire, we must turn it into a "Stream of Bytes"—a long sequence of 1s and 0s. evbuffer is a high-speed system for managing these streams. It ensures that the data is packed as tightly and as safely as possible. It is "Data Serialization."

• event_base_dispatch: This is the most "Peaceful" part of the code. Once the truck has left, the messenger has nothing to do but wait. But a computer can't just "Do Nothing"; it would use up 100% of your CPU power just spinning in circles. event_base_dispatch tells the computer: "Go to sleep. Wake me up only when the network card receives a reply from the node." This is why your computer doesn't get hot or slow down when the CLI is waiting for a response. It is "Efficiency through Inactivity." It is the "Art of the Idle."

The Journey's Climax

When event_base_dispatch finally wakes up and returns, it means the journey is half over. The node has received the message, processed it, and sent back a reply. The truck has returned to the post office. The messenger now opens the "Cargo Hold" of the returning truck, takes out the node's JSON response, and prepares to show it to you.

This entire "Logistics Operation" happens every single time you type a command. Whether you are checking your balance or moving a billion dollars, CallRPC is the engine that makes it happen. It is a masterpiece of coordination, a system where thousands of tiny decisions are made in the blink of an eye to ensure that the bridge remains the most reliable path on Earth. It is the "Physicality" of the software, the moment where the "Logic" of your mind becomes the "Motion" of the machine. It is the "Kinematics" of Bitcoin.