Manual Intervention: The `addnode` vs `connect` Commands

6. Manual Intervention: The addnode vs connect Commands

In the standard operating mode, the Bitcoin node is like a "Social Butterfly," automatically finding and connecting to peers through the discovery logic we just discussed. But for the Sovereign Architect, sometimes "Automatic" is not good enough. You might want to connect to a specific "High-Trust" node (like a friend's node, your own secondary node, or a non-profit block explorer) to ensure you are getting the "Absolute Truth" from a source you control. Or you might be running a node in a restricted environment where the automatic discovery is blocked. This is where the Manual Intervention commands come in: addnode and connect. These are the "Directives of the Master." These are the tools of the intentional connection.

These two commands might look similar at first glance—both take an IP address and try to make a connection—but they have very different "Philosophies" and "Internal Logics." Understanding the difference between them is the hallmark of a master network engineer. It is the difference between "Adding a VIP Friend" and "Closing the Doors to Everyone Else." It is the "Exercise of Authority" over the nervous system. It is the "Command of the Architect." It is the intentionality of the web.

The Persistent Friend: The addnode Command for Trust

The addnode command is used to tell your node: "I want you to connect to this specific peer, and I want you to keep trying forever." It is a "Persistent Intent." If the connection drops, or if your internet goes out and comes back, your node will automatically try to reconnect to this specific address. You can have up to 8 of these "Added Nodes" in addition to your standard automatic peers. It is the "Expansion of the Web." It is how you build a "Backbone" of trusted connections that you know will always be there, even if the general crowd vanishes. It is the "Anchor of Trust," the fixed point in a moving world.

The Exclusive Circle: The connect Command for Isolation

The connect command (usually set via the -connect flag or a configuration file) is much more "Radical." When you use connect, you are telling your node: "Only connect to these specific addresses. Ignore the DNS seeds, ignore the Address Manager, and refuse all other incoming or outgoing connections." It is the "Walled Garden" of the network. This is the ultimate tool for "Privacy" and "Isolation." It is often used for "Cold Storage" nodes or nodes running over a private VPN where you want absolute control over your network perimeter. It turns your node from a "Public Hub" into a "Private Vault." It is the "Sovereignty of the Wall," the boundary of the core.

Analyzing the "Manual Logic" in the Core: The Priority Manager

In the source code workshop (src/rpc/net.cpp), we can see how the node handles these manual instructions. It's not just a simple "Connect Now" signal; it's a "Policy Change" that affects how the Connection Manager (CConnman) spends its time and resources. It is the "Re-Programming of the Nerve," the intentional shift from "Discovery" to "Command." It is the exercise of the architect's will.

/**
 * This function handles the "addnode" command from the user.
 * It manages the list of "Special Peers" that we want to keep around forever.
 */
static UniValue addnode(const JSONRPCRequest& request)
{
    std::string strNode = request.params[0].get_str();
    std::string strCommand = request.params[1].get_str();

    // 1. "add": Put the peer in the "Keep-Alive" list.
    // This peer becomes a "Permanent Member" of our node's inner circle.
    if (strCommand == "add") {
        if (!connman.AddNode(strNode))
            throw JSONRPCError(RPC_CLIENT_NODE_ALREADY_ADDED, "Error: Node already added");
    }
    // 2. "remove": Take the peer off the permanent list.
    // We let them go back into the "General Crowd" of strangers.
    else if (strCommand == "remove") {
        if (!connman.RemoveAddedNode(strNode))
            throw JSONRPCError(RPC_CLIENT_NODE_NOT_ADDED, "Error: Node not added");
    }
    // 3. "onetry": Make a single attempt to connect, then forget it.
    // This is a "Probe" of the network reality.
    else if (strCommand == "onetry") {
        connman.ConnectNode(CAddress(strNode), ...);
    }

    return NullUniValue;
}

Explaining the Commands to a Non-Coder: The VIP List vs. the Private Club

• AddNode: Imagine you are at a crowded party. You are making many new friends automatically, but you also have a "VIP List" of 8 people you absolutely want to stay in touch with. Even if you get separated in the crowd or the lights go out, you will keep searching for them until you find them again. That is addnode. It ensures that your most trusted connections are always part of your nervous system, even if the rest of the network is chaotic or offline. It is the "Priority of the Known Friend." It is the "Security of the Trusted," the anchor of the web.

• onetry: This is like "Calling a Phone Number Once." You dial the number, see if they pick up, and if they don't (or if the call ends), you don't try again. It is a "One-Time Probe." This is useful for testing if a specific node is alive without committing to a permanent relationship. It is the "Flashlight in the Dark." It is the "Scout of the Web," the initial contact.

• ConnectNode (The -connect flag): This is like "Locking the Front Door and only giving keys to 5 people." You are no longer at a public party; you are in a private meeting. You don't want to hear from anyone else, and you don't want anyone else to know you exist. This is the "Maximum Security" mode of the Bitcoin node. It prevents your node from leaking your IP address to the public network or accepting data from strangers. It is the "Sovereign Isolation," the ultimate wall around the vault. It is the fortress of the core.

The Strategic Choice: Resilience vs. Control

Why would you choose one over the other? If you want your node to be part of the "Global Web" but you want to ensure it always hears from a few high-quality sources (like your own home node or a trusted friend), use addnode. If you are in a "High-Security" or "High-Privacy" situation where you only trust a small group of nodes and you want to be "Invisible" to the rest of the world, use connect. By mastering these commands, you are moving beyond the "Defaults" and becoming the "Active Architect" of your node's network topology. You are deciding exactly which nerves in the global system you want to rely on and which you want to ignore. You are the "Master of the Wire," the "Commander of the Connection." You are the master of the link.

The Sovereign's View: RPC Reflection

When you run addnode, you are performing an act of "Curated Connectivity." As an architect, you must ask: Who is on my VIP list? If it's empty, you are relying entirely on the "Kindness of Strangers." If it has too many, you are building a "Static Network" that might not be as resilient as the crowd. This command is your "Circle of Trust." You are the "Gatekeeper of the Inner Ring." You are the "Master of the Relationship." You are the auditor of trust.