Peer Discovery

What Is Peer Discovery?

Peer discovery is the process by which a node on a peer-to-peer network finds and connects to other nodes. In Bitcoin, no central server tells a node who its neighbors are. Instead, nodes use a combination of hardcoded DNS seeds, address gossip messages, and locally cached peer lists to build and maintain their set of connections.

Effective peer discovery is fundamental to the security and decentralization of the network. If a node connects only to attacker-controlled peers, it can be fed a false version of the blockchain, have its transactions censored, or be cut off from valid blocks entirely. The peer discovery system in Bitcoin Core has evolved significantly since the early days of the network, with each improvement responding to demonstrated attacks or discovered weaknesses.

How It Works

The peer discovery lifecycle differs depending on whether a node is starting for the first time or restarting with existing peer data.

Initial Bootstrap: DNS Seeds

A brand-new node with no cached peers begins by querying DNS seeds: special DNS servers that return IP addresses of currently active Bitcoin nodes. Bitcoin Core hardcodes several DNS seed hostnames maintained by well-known community members, including Pieter Wuille (seed.bitcoin.sipa.be), Matt Corallo (dnsseed.bluematt.me), and others.

Each DNS seed runs an automated crawler that continuously scans the network and serves only nodes that appear reachable on the default port (8333 for mainnet). Addresses discovered through DNS seeds are initially given a zero timestamp to prevent them from being immediately re-gossiped to other peers.

If DNS seeds fail to respond within 60 seconds, the node falls back to a list of hardcoded seed node addresses compiled into the binary (stored in chainparamsseeds.h). These fallback connections are short-lived: the node requests addresses from the seed node and then disconnects.

Ongoing Discovery: addr and addrv2 Messages

Once connected to at least one peer, a node participates in address gossip. It announces its own address to neighbors, and those neighbors forward it further through the network. The gossip protocol ensures that new nodes become known across the network without any central directory.

Nodes can explicitly request addresses from peers using getaddr messages. The response contains at most 23% of the replying peer's address database, capped at 1,000 addresses. This response is cached for roughly one day to prevent spy nodes from using repeated queries to map network topology.

Each node self-announces its address to connected peers roughly every 24 hours (following an exponential distribution). Block-relay-only connections do not participate in address gossip at all, reducing the attack surface for topology inference.

Restart Behavior

A node that has run before loads its cached peer database from peers.dat on disk. It attempts to connect to known peers for up to 11 seconds. If at least one connection succeeds, DNS seeds are skipped entirely. If no connection succeeds within that window, the node falls back to the DNS seed process described above.

Since Bitcoin Core v0.21.0, the node also stores its two most recent block-relay-only outbound peers in an anchors.dat file on shutdown. On restart, it prioritizes reconnecting to these anchor peers, making it harder for an attacker to exploit the restart window to eclipse the node.

Connection Types and Limits

Bitcoin Core maintains several distinct types of outbound connections, each serving a different purpose:

The total connection cap defaults to 125. Of those, 11 are automatic outbound connections (8 full-relay + 2 block-relay-only + 1 feeler), leaving up to 114 slots for inbound peers. An additional extra block-relay-only connection is attempted every 5 minutes to test whether better peers are available.

The Address Manager (addrman)

The address manager is the data structure that stores and organizes known peer addresses. It uses a two-table design:

New Table vs. Tried Table

Each address is assigned to a bucket using a cryptographic hash that incorporates a randomly generated 256-bit secret key. For the new table, the source peer's network group determines which subset of buckets an address can land in. For the tried table, the address's own network group determines its bucket. This design ensures no single source or attacker can dominate the entire table.

An address is promoted from the new table to the tried table only after a successful outbound connection. The maximum address age is 30 days, after which entries expire.

BIP 155: addrv2 Messages

The original addr message format used a fixed 16-byte address field designed around IPv6. IPv4 addresses were encoded as IPv4-mapped IPv6 addresses (e.g., ::ffff:10.0.0.1), and Tor v2 addresses used an OnionCat mapping. This worked until Tor v3 introduced 32-byte addresses that simply could not fit.

BIP 155 introduced the addrv2 message format with a variable-length address field (up to 512 bytes) and an explicit network ID byte. Peers signal support by sending a sendaddrv2 message during the handshake.

// addrv2 message structure (BIP 155)
// For each address entry:
uint32_t  time        // Last seen timestamp
CompactSize services  // Service flags (variable-length)
uint8_t   networkID   // Network type identifier
vector    addr        // Variable-length address
uint16_t  port        // Port number

// Defined network IDs:
// 0x01 = IPv4    (4 bytes)
// 0x02 = IPv6    (16 bytes)
// 0x04 = Tor v3  (32 bytes)
// 0x05 = I2P     (32 bytes)
// 0x06 = CJDNS   (16 bytes)

The addrv2 format was implemented in Bitcoin Core v0.21.0 and enables discovery of nodes on diverse network types including Tor v3, I2P, and CJDNS.

Feeler Connections

Feeler connections are short-lived outbound connections that exist solely to test whether addresses in the new table are reachable. Every 2 minutes, the node selects an address from the new table, opens a TCP connection, performs the version handshake, and immediately disconnects.

If the handshake succeeds, the address is promoted to the tried table. If a promotion would evict an existing tried-table entry, the node first tests the existing address (a mechanism called test-before-evict, added in Bitcoin Core v0.17.0). Only if the existing address fails its connection test is it replaced. This prevents an attacker from rapidly filling the tried table with malicious addresses.

Before feeler connections were introduced in Bitcoin Core v0.13.1, research showed that 72-95% of addresses in tried tables were stale. Feeler connections keep the tried table fresh, making eclipse attacks significantly harder.

Tor and I2P Discovery

Nodes running on anonymity networks like Tor and I2P face a unique challenge: DNS seeds cannot serve their addresses because Tor v3 (32 bytes) and I2P (32 bytes) addresses are too large for DNS records, and DNS lookups over these networks are impractical.

Instead, Tor and I2P nodes rely on two discovery mechanisms:

• Hardcoded seed addresses compiled into the Bitcoin Core binary (stored in chainparamsseeds.h), updated with each release cycle
• addrv2 gossip from connected peers, which can relay addresses across network types (an IPv4 node can forward a Tor v3 address it received from another peer)

Since Bitcoin Core v22.0, a network diversity mechanism ensures at least one outbound connection to each reachable network type (IPv4, IPv6, Tor, I2P, CJDNS). Every 5 minutes, if all outbound slots are filled, the node attempts to add an extra connection to any reachable network it currently has zero connections to. Eviction logic protects the sole connection to each network type from being dropped.

Eclipse Attack Risks

If an attacker can control all of a victim node's peer connections, they can execute an eclipse attack: feeding the node a fabricated view of the blockchain. Consequences include double-spend attacks, transaction censorship, selfish mining amplification, and complete privacy loss (all transactions from the eclipsed node are attributable to it).

A 2015 USENIX Security paper demonstrated that an attacker with as few as 8,192 IP addresses could eclipse a node with over 85% probability. Bitcoin Core has since deployed numerous countermeasures:

• Deterministic bucketing with a secret key prevents an attacker from predicting where their addresses will land
• Feeler connections and test-before-evict keep the tried table populated with genuinely reachable nodes
• Anchor connections persist block-relay-only peers across restarts
• ASN-based bucketing (asmap) groups addresses by Autonomous System Number rather than /16 IP prefix, preventing a single ISP or hosting provider from dominating connections
• Unsolicited address rate limiting (token bucket at 0.1 addr/second) prevents address flooding
• Network diversity ensures connections span multiple network types

After these countermeasures, eclipsing a node requires roughly 163,000 IP addresses for a 50% success rate. For more on how peer-to-peer network security relates to broader node architecture, see this comparison of Bitcoin node implementations.

Why It Matters

Peer discovery is not just a networking detail: it is a security-critical system that underpins the trustless nature of Bitcoin. A node that cannot find honest peers cannot verify the blockchain independently. For full node operators, understanding peer discovery helps with diagnosing connectivity issues, hardening against targeted attacks, and configuring nodes for privacy (for example, routing through Tor for address anonymity).

Layer-2 protocols like Lightning and Spark inherit their security assumptions from the base layer. If a Lightning node's underlying Bitcoin node is eclipsed, penalty transactions may fail to propagate, enabling channel counterparties to steal funds. Robust peer discovery at the base layer is therefore essential for the security of the entire Bitcoin ecosystem, including off-chain protocols built on top of it.

Risks and Considerations

DNS Seed Trust

DNS seed results are not cryptographically authenticated. A malicious seed operator or a network-level attacker performing a man-in-the-middle attack could return only attacker-controlled IP addresses. Bitcoin Core mitigates this by using multiple independent seeds and preferring cached peers over fresh DNS lookups. BIP 324 (encrypted peer-to-peer transport) does not protect the DNS lookup itself, but it does make it harder to interfere with connections after discovery.

Sybil Attacks on Address Gossip

An attacker running many nodes can flood the network with addr messages pointing to their own IP addresses, attempting to fill other nodes' address tables. This is a form of Sybil attack on the address layer. Rate limiting, deterministic bucketing, and ASN-based grouping all reduce the effectiveness of this strategy.

Privacy Implications

Address gossip can leak topology information. If a spy node sends unique addresses to each peer and then monitors which addresses propagate where, it can infer the network graph. Cached getaddr responses, block-relay-only connections (which skip address gossip entirely), and Tor/I2P support all help protect node privacy. Future improvements like Erlay (BIP 330), which uses set reconciliation for transaction relay, could further reduce the bandwidth overhead of maintaining many connections and make it practical to increase the default outbound count.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.