Bitcoin Core addnode RPC: Controlled Peer Management Guide

This guide explains Bitcoin Core addnode RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Endpoint and command contract

The node argument identifies a peer, commonly as host and port, while command must be exactly add, remove or onetry in the historical interface. Validate syntax, network family and port before RPC. Resolve hostnames under a documented trust policy, because DNS changes can redirect a retained logical name even when the operator believes a fixed peer was selected.

Add versus onetry

Add creates an entry that the node will continue attempting, whereas onetry makes a single connection attempt. A successful RPC response is not proof of completed handshake, useful services or sustained connection. Inspect addednodeinfo and peer information, record negotiated protocol and services, then confirm whether the peer contributed headers, blocks or only connectivity.

Removal semantics

Remove stops managing the endpoint through the runtime addnode list but does not necessarily express a network ban or prove every existing connection is gone. Verify the active peer table and configuration files, because a peer may also be supplied through connect, addnode configuration or another automation process. Rollback should restore only reviewed entries, not an entire stale list.

Protected peer implications

Manually added peers were protected from some automatic disconnection rules and did not have to satisfy every normal outbound service requirement. That makes operator selection part of the node’s security boundary. A slow, eclipsing or obsolete manual peer can persist longer than an ordinary peer, so diversity and independent chainwork monitoring matter.

Privacy and topology

A fixed peer learns the node’s recurring address and transaction or block request patterns, while a small manual set can reveal operational topology. Avoid publishing private endpoints, segregate mining-template nodes from public gateways and monitor ASN, jurisdiction and ownership concentration without placing sensitive topology into general logs.

Access control

Network-control RPC credentials can reshape connectivity and should not be shared with read-only monitoring. Bind RPC to protected interfaces, use authentication, restrict command wrappers to an allowlist and record actor, endpoint fingerprint, intended duration and approval. Never interpolate untrusted host text into shell or configuration commands.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

addnode is a precise peer-management control, not a trust or synchronisation guarantee. Safe use requires validated endpoints, service and chainwork checks, topology monitoring and an auditable way to remove or restore only the intended peer.