Network Topology

What Is Network Topology?

Network topology refers to the arrangement and connectivity pattern of nodes within a peer-to-peer network. In Bitcoin, it describes which nodes are connected to which other nodes, how they discover new peers, and how data propagates through the resulting graph. Unlike centralized systems where all clients connect to a single server, Bitcoin's topology is decentralized: every full node connects to a small subset of peers and relays information to them, creating a mesh that collectively covers the entire network.

The topology of a blockchain network directly influences its security, performance, and privacy. A well-connected graph ensures that blocks and transactions propagate quickly, reducing the risk of stale blocks and chain reorganizations. A poorly connected or manipulated topology, on the other hand, can lead to network partitions, eclipse attacks, and transaction deanonymization. Understanding network topology is essential for anyone running a node, building wallet software, or evaluating the resilience of a layer-1 protocol.

How It Works

Bitcoin Core organizes its peer connections into several distinct types, each serving a different purpose. The default configuration allows up to 125 simultaneous connections:

• 8 full-relay outbound connections: the node initiates these and uses them for blocks, transactions, and address gossip
• 2 block-relay-only outbound connections: carry only block data, not transactions or addresses, making them harder for third parties to detect
• 1 feeler connection: a short-lived probe that tests whether a candidate address is reachable before adding it to the peer database
• Up to 114 inbound connections: peers that connect to this node on their own initiative

The distinction between outbound and inbound connections is critical for security. Because the node chooses its own outbound peers, an attacker cannot easily control them. Inbound connections, however, can come from anyone, including adversaries. Bitcoin Core's security model assumes that all inbound connections could be malicious and relies on its self-selected outbound peers for honest chain data.

Peer Discovery

When a Bitcoin node starts for the first time, it needs to find peers to connect to. The discovery process follows a prioritized sequence:

1. DNS seeds: Bitcoin Core queries a hard-coded list of DNS seed servers maintained by community members. Some run dynamic seeders that continuously crawl the network for reachable nodes, while others maintain curated static lists. The returned addresses bootstrap the node's initial peer database.
2. Address gossip: once connected to at least one peer, the node exchanges addr and getaddr messages with its peers. This fully decentralized mechanism allows nodes to learn about new peers without relying on any central directory.
3. Hard-coded seed IPs: if DNS seeds are unreachable, Bitcoin Core falls back to a list of hard-coded IP addresses compiled into the binary. This is a last-resort mechanism used only when other methods fail.
4. Persistent storage: after the first run, the node stores known peer addresses to disk. On subsequent startups, it reconnects to previously known peers without needing to re-query DNS seeds.

For a deeper look at the bootstrap process, see the glossary entries on bootstrap nodes and peer discovery.

Eclipse Attack Defenses

An eclipse attack occurs when an adversary controls all of a victim node's connections, isolating it from the honest network. Bitcoin Core has added several topology-level defenses over the years:

• Feeler connections (since v0.13.1): short-lived probes that verify candidate addresses are reachable before promoting them from the "new" table to the "tried" table, preventing attackers from flooding the address database with unreachable entries
• Anchor connections (since v0.21.0): the node stores its two most recent block-relay-only peers in an anchors.dat file on shutdown and reconnects to them on restart, closing the window an attacker could exploit during the restart phase
• Deterministic bucketing: peer addresses are sorted into buckets based on their IP range and the source that advertised them, limiting how many entries a single attacker can place
• ASN-aware selection: peers are grouped by Autonomous System Number so that outbound connections span multiple hosting providers, reducing the risk of a single AS operator controlling all connections

Connection Message Example

When a node connects to a peer, the handshake begins with a version message that advertises the node's protocol version, services, and listening address:

# Simplified Bitcoin P2P version handshake
{
  "version": 70016,
  "services": "NODE_NETWORK | NODE_WITNESS",
  "timestamp": 1731168000,
  "addr_recv": "203.0.113.50:8333",
  "addr_from": "198.51.100.10:8333",
  "nonce": 0x1234567890abcdef,
  "user_agent": "/Satoshi:27.0.0/",
  "start_height": 870000,
  "relay": true
}

The relay field indicates whether the node wants to receive transaction announcements. Block-relay-only connections set this to false, receiving only block data.

Lightning Network Topology

The Lightning Network maintains its own distinct topology, separate from Bitcoin's base layer. While Bitcoin nodes form an unstructured random mesh, Lightning nodes create a channel graph where edges represent funded payment channels and vertices represent nodes that can route payments.

Lightning topology is governed by BOLT 7, which defines three gossip message types:

• channel_announcement: broadcasts a new channel to the network, carrying signatures from both nodes and a channel ID that references the on-chain funding transaction
• channel_update: communicates routing parameters for one direction of a channel, including routing fees, CLTV delta, and whether the channel is currently active
• node_announcement: advertises a node's alias, color, supported features, and network addresses

Unlike Bitcoin's base-layer topology, which is intentionally hidden from outside observers, Lightning's public channel graph is visible to all participants. This transparency is necessary for pathfinding but creates a different set of privacy tradeoffs. Private channels and blinded paths offer ways to reduce visibility.

Research from 2026 has proposed replacing Lightning's flooding-based gossip with set reconciliation techniques, which could reduce gossip sync time from hours to minutes for nodes rejoining the network after extended downtime.

Why It Matters

Network topology has practical implications for anyone interacting with Bitcoin or building on top of it:

• Block propagation speed: a well-connected topology ensures new blocks reach the entire network within seconds. Delays can cause miners to work on stale blocks, wasting energy and reducing economic security
• Transaction privacy: when a node broadcasts a transaction, observers connected to many peers can use timing analysis to infer which node originated it. The Dandelion protocol (BIP 156) was proposed to mitigate this by routing transactions along a random stem path before diffusion, though it has not been merged into Bitcoin Core
• Censorship resistance: a diverse, redundant topology makes it difficult for any single entity to block specific transactions from reaching miners
• Layer-2 performance: Spark and other layer-2 protocols depend on timely access to on-chain data. A node that is poorly connected or eclipsed could miss critical transactions, such as a justice transaction timeout

For a comprehensive analysis of how topology attacks threaten Bitcoin consensus, see Bitcoin P2P Network Resilience: How Topology Attacks Threaten Consensus.

Use Cases

Node Operators

Understanding topology helps node operators configure their nodes for resilience. Running a node with connections across multiple ISPs and geographic regions reduces the chance of being isolated by a localized outage or a targeted BGP hijacking attack. Operators can manually add trusted peers with the addnode RPC command or specify them in the configuration file to ensure at least some connections are to known-good nodes.

Network Researchers

Researchers study Bitcoin's topology to assess its decentralization and attack surface. Academic studies have found that node hosting is concentrated: as few as 8 Autonomous Systems host roughly 30% of Bitcoin nodes, and 24 ASes host about 50%. This concentration increases the feasibility of routing-level attacks where an AS operator or upstream ISP intercepts traffic between nodes.

Wallet Developers

Wallets that run lightweight clients or connect to a single trusted node inherit the topology risks of that node. A wallet backed by an eclipsed node could be shown a false chain state. Connecting to multiple independent nodes or using compact block filters (BIP 157/158) helps mitigate this risk.

Risks and Considerations

Network Partitioning

A network partition splits the Bitcoin network into two or more groups that cannot communicate. Research has identified several partition attack vectors: spatial attacks that exploit AS-level concentration, temporal attacks that target nodes during restarts, and logical attacks that leverage software version differences. A sustained partition could allow double-spend attacks against transactions confirmed on only one side of the split.

Transaction Origin Tracing

Bitcoin's default transaction relay uses diffusion: a node sends each transaction to its peers with independent random delays. A well-connected adversary monitoring many nodes can correlate these timing patterns to estimate which node first broadcast a transaction. This links IP addresses to on-chain activity, undermining pseudonymity. Countermeasures include broadcasting transactions over Tor, using the Dandelion protocol (not yet in Bitcoin Core), or submitting transactions directly to a miner.

Unreachable Node Majority

Research estimates that nodes behind NAT or firewalls (unreachable nodes) outnumber publicly reachable nodes by roughly 10 to 1. Unreachable nodes can only make outbound connections and cannot accept inbound ones, meaning they depend entirely on the reachable portion of the network for connectivity. If the reachable node count drops significantly, unreachable nodes may struggle to find enough peers.

Topology Mapping

Because Bitcoin does not encrypt its P2P traffic by default, network observers can identify connections between nodes by monitoring TCP sessions. BIP 324 (v2 transport protocol) introduces encrypted and authenticated connections to make passive topology mapping more difficult, though an observer can still see that two IP addresses are communicating.

For more on how Bitcoin defends against P2P-level attacks, see Eclipse Attacks on Bitcoin: How Adversaries Isolate Nodes and How the Network Defends.

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.