addrv2 (BIP155)

addrv2 (BIP155) is the peer-to-peer message format Bitcoin nodes use to share known peer addresses with one another, defined as the successor to the legacy addr message. Address gossip is how nodes discover peers beyond their initial bootstrap — each node relays a sampling of addresses it knows, building every participant a diverse view of the network. The legacy format allotted a fixed 16 bytes per address, enough for IPv4 and IPv6 but structurally incapable of carrying the longer endpoint identifiers used by modern privacy networks. BIP155 replaced that rigidity with a general container, making privacy-preserving transports first-class citizens of peer discovery.

Why addr ran out of room

The forcing event was Tor's evolution. Tor v2 onion addresses were short enough to squeeze into 16 bytes through an encoding trick, but Tor v3 — with its 32-byte ed25519 service keys and materially better cryptography — simply did not fit. Without a new format, Bitcoin nodes could not gossip v3 onion peers at all, which would have stranded node operators on a deprecated Tor generation as v2 was sunset. The fix generalized rather than patched: BIP155 gives each address entry an 8-bit network identifier and a variable-length address field, so future networks need only a new ID, not a new message.

Networks it can carry

The format currently encodes IPv4 (4 bytes), IPv6 (16 bytes), Tor v3 onion services (32-byte keys), I2P (32-byte hash-based destinations), and CJDNS (IPv6-shaped addresses in the fc00::/8 range), with Yggdrasil among the networks slotted into the identifier space. The obsolete 10-byte Tor v2 format remains representable for completeness but is no longer operational. Service flags accompany each entry as a CompactSize integer rather than a fixed field — the same modernization instinct applied throughout the message.

Negotiation and compatibility

Deployment was designed to be painless. During the version handshake, a peer signals support by sending a sendaddrv2 message; only after both sides advertise it do they exchange the new format. Legacy peers continue receiving old-style addr messages containing whatever fits, so nothing breaks — the network upgraded organically as software rolled forward. This handshake-gated pattern is the standard Bitcoin approach to P2P evolution, used likewise by the encrypted-transport upgrade covered under BIP324.

Why it matters for sovereign node operation

Operators steer all of this through node configuration. Bitcoin Core exposes options to enable or restrict specific networks, route each through its own proxy, and control whether the node advertises addresses on them — so one machine might accept clearnet and onion connections while reaching I2P peers outbound only, or clamp itself to a single privacy network entirely. The address manager deliberately maintains diversity across network groups when selecting peers, which blunts eclipse attempts that saturate any single network. addrv2 is what makes those choices expressible at the gossip layer: the network cannot use endpoints it has no vocabulary for. It is a reminder that decentralization often advances through unglamorous format work: one message definition quietly widened the set of places a Bitcoin node can safely live.

addrv2 is quiet infrastructure with loud consequences. Because v3 onion, I2P, and CJDNS endpoints propagate through ordinary address gossip, a node can run reachably on those networks — accepting inbound connections without ever exposing a clearnet IP tied to a home address. Operators in hostile jurisdictions, or anyone who prefers their node not advertise where they live, can participate fully rather than only making outbound connections. A common resilient configuration spans several networks at once, making the node hard to eclipse and its traffic hard to correlate; pairing that reach with transport encryption and relay-layer privacy like Dandelion (BIP156) layers the protections. The routing substrate all of this rides on is covered under TCP/IP.