Version Handshake
The version handshake is the initial message exchange between two Bitcoin nodes establishing protocol compatibility and connection parameters.
Key Takeaways
- The version handshake is the first exchange between two Bitcoin nodes when they connect: each node sends a
versionmessage containing its protocol version, supported services, and current block height, then both confirm with averackmessage. - Service flags advertised during the handshake (such as NODE_NETWORK, NODE_WITNESS, and NODE_COMPACT_FILTERS) tell each peer what capabilities the other supports, allowing nodes to decide whether a connection is useful for their needs.
- BIP 324 (v2 transport) replaces the plaintext handshake with an encrypted key exchange using ElligatorSwift encoding, preventing passive eavesdroppers from identifying Bitcoin traffic or reading message contents.
What Is the Version Handshake?
The version handshake is the mandatory initial message exchange that occurs every time two Bitcoin nodes establish a new peer-to-peer connection. Before any block data, transactions, or other protocol messages can flow between peers, both nodes must complete this handshake to confirm they speak a compatible protocol version and to share basic metadata about themselves.
Think of it as two people introducing themselves before a conversation: each side states who they are, what languages they speak, and what topics they can discuss. If the introductions reveal incompatibility, either side can disconnect immediately rather than wasting bandwidth on a connection that will not work.
The handshake has been part of the Bitcoin protocol since its earliest versions. The core structure has remained stable, though new fields (like the relay flag in protocol version 70001) and entirely new transport layers (BIP 324) have been layered on top over the years.
How It Works
The version handshake follows a strict four-message sequence. The node that initiates the TCP connection (the "initiator") goes first:
- The initiator sends a
versionmessage containing its protocol version number, service flags, timestamp, network addresses, a random nonce, its user agent string, and the height of the last block it has received - The receiving node validates the message and responds with its own
versionmessage containing the same set of fields from its own perspective - The initiator sends a
verack(version acknowledgment) message to confirm it accepted the remote node's version - The receiving node sends its own
verackto complete the handshake
Once both verack messages have been exchanged, the connection is considered established and regular protocol messages can begin. Both nodes use the lower of the two advertised protocol versions as the effective version for the session.
Version Message Fields
The version message carries several fields that give each node a snapshot of its new peer:
| Field | Size | Description |
|---|---|---|
| protocol version | 4 bytes | Integer identifying the P2P protocol version (e.g., 70016 for wtxid relay support, 70017 for feature negotiation) |
| services | 8 bytes | Bitfield of features the node supports (see service flags below) |
| timestamp | 8 bytes | Current UNIX timestamp in seconds from the sender's clock |
| addr_recv | 26 bytes | Network address of the receiving node as seen by the sender |
| addr_from | 26 bytes | Network address of the sending node |
| nonce | 8 bytes | Random value used to detect self-connections |
| user_agent | variable | Software identifier string (e.g., /Satoshi:31.0.0/) |
| start_height | 4 bytes | Block height of the last block the sender has received |
| relay | 1 byte | Whether the peer should relay unconfirmed transactions (added in protocol version 70001, per BIP 37) |
The nonce field serves a specific purpose: if a node receives a version message containing the same nonce it generated, it knows it has connected to itself and should drop the connection. This prevents wasted resources on loopback connections, which can happen when a node's external IP is included in its own peer list.
Service Flags
The services bitfield is one of the most important parts of the version message. Each bit signals a specific capability:
| Flag | Bit | Meaning |
|---|---|---|
| NODE_NETWORK | 0 | Node can serve full blocks (not just headers). Set by full nodes |
| NODE_BLOOM | 2 | Node supports BIP 37 bloom filter requests. Largely deprecated due to privacy concerns |
| NODE_WITNESS | 3 | Node can serve SegWit blocks and transactions with witness data |
| NODE_COMPACT_FILTERS | 6 | Node serves BIP 157/158 compact block filters for lightweight clients |
| NODE_NETWORK_LIMITED | 10 | Pruned node that serves only the most recent 288 blocks (per BIP 159) |
| NODE_P2P_V2 | 11 | Node supports BIP 324 encrypted v2 transport |
Nodes use these flags to make connection decisions. A node performing initial block download needs peers with NODE_NETWORK set. A lightweight client looking for compact block filters needs NODE_COMPACT_FILTERS. A node that only wants SegWit-valid blocks can require NODE_WITNESS.
Code Example
The following pseudocode illustrates the version handshake sequence from the initiator's perspective:
# Initiator connects to remote peer via TCP
connection = tcp_connect(remote_ip, 8333)
# Step 1: Send our version message
our_version = VersionMessage(
protocol_version = 70016,
services = NODE_NETWORK | NODE_WITNESS,
timestamp = current_unix_time(),
addr_recv = remote_address,
addr_from = our_address,
nonce = random_uint64(),
user_agent = "/Satoshi:31.0.0/",
start_height = our_best_block_height,
relay = True
)
connection.send(our_version)
# Step 2: Receive remote peer's version message
their_version = connection.receive("version")
# Check for self-connection
if their_version.nonce == our_version.nonce:
connection.close()
return
# Verify minimum protocol version
if their_version.protocol_version < MIN_SUPPORTED_VERSION:
connection.close()
return
# Step 3: Send verack to acknowledge their version
connection.send(VerackMessage())
# Step 4: Receive their verack
connection.receive("verack")
# Handshake complete: begin normal message exchange
effective_version = min(
our_version.protocol_version,
their_version.protocol_version
)BIP 324: The Encrypted Handshake
The traditional version handshake sends everything in plaintext. Any network observer can read the version messages, identify the software, and confirm that Bitcoin traffic is flowing. This makes Bitcoin connections vulnerable to passive surveillance and targeted censorship.
BIP 324 introduces v2 transport, which wraps the entire connection in encryption. The v2 handshake replaces the plaintext exchange with a cryptographic key agreement that happens before any Bitcoin protocol messages are sent:
- The initiator generates an ephemeral elliptic curve key pair on secp256k1 and sends the public key encoded using ElligatorSwift, a method that makes the 64-byte key indistinguishable from random data
- Up to 4,095 bytes of random "garbage" data may be appended to further obscure packet sizes and prevent fingerprinting
- The responder performs the same process: generating its own key, deriving a shared secret via elliptic curve Diffie-Hellman, and sending back its ElligatorSwift-encoded key with optional garbage
- Both sides derive symmetric encryption keys and a session ID using HKDF, then switch to ChaCha20-Poly1305 authenticated encryption for all subsequent messages
- The standard
version/verackexchange then proceeds inside the encrypted channel
BIP 324 was merged into Bitcoin Core in October 2023, shipped as opt-in in version 26.0, and enabled by default in version 27.0 (April 2024). The protocol is opportunistic: if a remote peer does not support v2, the initiator falls back to the plaintext v1 handshake automatically.
One important limitation: BIP 324 provides confidentiality against passive observers but does not authenticate peers. Bitcoin nodes have no stable identity, so a man-in-the-middle attacker who intercepts the connection at the TCP level can still perform the key exchange with both sides separately. The encryption stops passive eavesdropping and trivial traffic analysis, not active interception. For more on network-level security, see the research article on Bitcoin P2P network topology and resilience.
Use Cases
Feature Negotiation
The version handshake is how nodes discover what their peers can do. When a node needs SegWit blocks, compact block filters, or any specific capability, it checks the service flags in the peer's version message. This lets the P2P network evolve incrementally: new features are introduced behind new flags, and nodes that do not support them simply do not advertise the flag.
Peer Scoring and Connection Management
Nodes use handshake data to rank and manage their peer connections. The start_height field reveals whether a peer is synced to the chain tip or still catching up. The user_agent string identifies the software. Nodes can prefer peers running recent software versions, deprioritize peers that are significantly behind the chain tip, or disconnect peers advertising protocol versions too old to be useful.
Self-Connection Detection
The random nonce in the version message prevents a node from accidentally connecting to itself. Without this check, a node could waste one of its limited connection slots on a loopback connection that serves no purpose. If the nonce matches, the connection is dropped immediately.
Network Monitoring
Researchers and monitoring services (like Bitnodes) connect to thousands of nodes and collect version messages to map the network. The user agent strings, service flags, and block heights from handshakes provide a snapshot of network health: how many nodes run each software version, what percentage support SegWit or compact filters, and how well-synchronized the network is.
Risks and Considerations
Fingerprinting
The version message reveals a lot about a node: its software, protocol version, services, and approximate location (via timestamp and IP). Adversaries can use this information to target specific software versions with known vulnerabilities or to map the network topology. BIP 324's encryption mitigates passive fingerprinting, but an active attacker who completes the handshake still receives the version message contents.
Eclipse Attacks
During eclipse attacks, an adversary surrounds a target node with malicious peers. The handshake is the first line of defense: nodes can reject connections from peers with suspiciously old protocol versions or missing service flags. However, an attacker can forge version messages with any values, so the handshake alone does not prevent eclipse attacks. Additional protections like anchor connections, diverse peer selection, and peer scoring are needed.
Plaintext Exposure (v1)
On v1 (plaintext) connections, the version handshake is fully visible to any network observer. Internet service providers, state-level adversaries, and anyone on the network path can see that a Bitcoin node is running, identify its software version, and potentially correlate the connection with specific transactions. Upgrading to BIP 324 addresses this for the growing share of nodes that support v2 transport.
Compatibility Gaps
When Bitcoin Core increases its minimum supported protocol version, older nodes are cut off from the main network. While this is necessary for protocol evolution (service flags and features added in newer versions would be meaningless to very old software), it can temporarily fragment connectivity if a large portion of nodes has not yet upgraded. Node operators should keep their software up to date to maintain healthy peer connections.
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.