P2P Network Protocol

Learn about Bitcoin Core’s peer-to-peer network protocol, peer discovery mechanisms, and connection management

Overview

Bitcoin Core operates on a peer-to-peer (P2P) network where nodes communicate directly with each other to relay transactions and blocks. The network is designed to be decentralized, resilient, and resistant to censorship.

Network Types

Bitcoin Core supports multiple network types, each identified by a specific address format:

• IPv4 - Traditional internet addresses (e.g., 192.168.1.1)
• IPv6 - Modern internet addresses (e.g., 2001:db8::1)
• Tor (Onion) - Privacy network addresses ending in .onion
• I2P - Privacy network addresses ending in .b32.i2p
• CJDNS - Encrypted IPv6 network using fc00::/8 range

Peer Discovery

Bitcoin Core uses several mechanisms to discover and connect to peers:

DNS Seeds

When a node first starts or has few connections, it queries DNS seeds to obtain initial peer addresses.

DNS seed queries are delayed based on the number of known peers:

• Few peers (< 1000): 11 second delay
• Many peers (≥ 1000): 5 minute delay

Configuration options:

# Query 3 DNS seeds at once when connections are low
DNSSEEDS_TO_QUERY_AT_ONCE=3

# Minimum outbound connections before stopping seed queries
SEED_OUTBOUND_CONNECTION_THRESHOLD=2

Address Manager (AddrMan)

The address manager maintains a database of known peer addresses, stored in peers.dat. It implements a tried-and-new bucketing system:

• Tried table - Addresses of peers successfully connected to
• New table - Recently learned addresses not yet connected

The address database is automatically dumped to disk every 15 minutes to preserve peer information across restarts.

Anchor Connections

Bitcoin Core maintains up to 2 block-relay-only anchor connections that persist across restarts. These connections are stored in anchors.dat and help prevent eclipse attacks.

// Maximum number of block-relay-only anchor connections
MAX_BLOCK_RELAY_ONLY_ANCHORS = 2

Connection Types

Bitcoin Core establishes different types of connections for various purposes:

Outbound Connections

1. Full Relay - Full transaction and block relay
2. Block Relay Only - Only blocks are relayed, no transactions
3. Feeler - Short-lived connections to test peer responsiveness
4. Address Fetch - Connections specifically to fetch peer addresses

Inbound Connections

Incoming connections from other nodes. By default, listening is enabled unless running behind a proxy.

# Enable listening for incoming connections
bitcoind -listen=1

# Disable listening
bitcoind -listen=0

Configuration Options

Basic Network Configuration

# Set custom port (default: 8333 for mainnet)
bitcoind -port=8333

# Bind to specific address
bitcoind -bind=192.168.1.100

# Connect to specific peer
bitcoind -connect=192.168.1.50:8333

# Add a node to connect to
bitcoind -addnode=node.example.com:8333

# Use specific seed node
bitcoind -seednode=seed.example.com

Network Selection

# Only connect to specific network(s)
bitcoind -onlynet=ipv4
bitcoind -onlynet=ipv6
bitcoind -onlynet=onion
bitcoind -onlynet=i2p
bitcoind -onlynet=cjdns

# Combine multiple networks
bitcoind -onlynet=onion -onlynet=i2p

External IP Advertisement

# Advertise your external IP address
bitcoind -externalip=203.0.113.5

# Multiple external addresses
bitcoind -externalip=203.0.113.5 -externalip=7zvj7a2i...shid.onion

Network Discovery

# Enable address discovery (default: on)
bitcoind -discover=1

# Disable discovery when using -externalip
bitcoind -discover=0 -externalip=your.onion.address

Privacy Network Integration

1. Understand Network Separation

   Bitcoin Core separates privacy networks from clearnet to prevent address correlation. Privacy network addresses (Tor, I2P) are not advertised to clearnet peers and vice versa.

2. Configure Multi-Network Operation

   You can run Bitcoin Core on multiple networks simultaneously:

   bitcoind -proxy=127.0.0.1:9050 -i2psam=127.0.0.1:7656 -cjdnsreachable
   
3. Monitor Network Status

   Use bitcoin-cli -netinfo to view connection information:

   bitcoin-cli -netinfo
   

Operating a node on multiple networks (e.g., IPv4 and Tor) can help strengthen the network but may allow adversaries to correlate identities through shared runtime characteristics. This is not recommended if you require unlinkability across networks.

Network Reachability

The network layer uses a reachability scoring system to determine the best local address to advertise to each peer:

// src/net.cpp - GetLocal() function
// Scores addresses based on:
// - Network compatibility (privacy net vs clearnet)
// - Reachability from peer's perspective
// - Local score (based on usage)

Monitoring and Debugging

Get Network Information

# View network info
bitcoin-cli getnetworkinfo

# View peer information
bitcoin-cli getpeerinfo

# Get node addresses by network
bitcoin-cli getnodeaddresses 10 "ipv4"
bitcoin-cli getnodeaddresses 10 "onion"

# View address info summary
bitcoin-cli -addrinfo

Network Statistics

# Detailed network info with peer counts
bitcoin-cli -netinfo 4

Debug Logging

Enable network-specific debug logging:

# General network debugging
bitcoind -debug=net

# Specific network debugging
bitcoind -debug=tor
bitcoind -debug=i2p

Performance Tuning

Upload Limits

# Limit upload bandwidth (in MiB per day)
bitcoind -maxuploadtarget=144  # ~6 MB/hour

The default timeframe is 24 hours (86400 seconds).

Connection Limits

# Maximum number of inbound+outbound connections
bitcoind -maxconnections=125

Security Considerations

Best Practices:

• Use multiple network types for redundancy
• Enable block-relay-only connections for privacy
• Monitor peer connections regularly
• Keep peers.dat backed up for faster restarts
• Consider using -onlynet=onion for maximum privacy

Advanced Features

Feeler Connections

Bitcoin Core periodically creates short-lived “feeler” connections to test if addresses in the new table are responsive. A random 0-1 second delay is added to prevent synchronization.

FEELER_SLEEP_WINDOW = 1s

Extra Network Peers

Every 5 minutes, Bitcoin Core attempts to connect to reachable networks it’s not currently connected to:

EXTRA_NETWORK_PEER_INTERVAL = 5min

Bridge Nodes

Nodes listening on multiple networks act as bridge nodes, increasing the cost and complexity of eclipse and partition attacks against the Bitcoin network.

RPC Commands

Command	Description
getnetworkinfo	Returns network-related information
getpeerinfo	Returns data about each connected peer
getnodeaddresses	Return known addresses from addr manager
addnode	Add/remove/query a node
disconnectnode	Disconnect from a specified node
setnetworkactive	Enable/disable all P2P network activity

See Also

• Tor Support - Configure Bitcoin Core with Tor
• I2P Support - Configure Bitcoin Core with I2P
• CJDNS Support - Configure Bitcoin Core with CJDNS
• ZMQ Notifications - Real-time event notifications