Skip to main content
netspecsEthereum networking

3.2.RLPx session

Stage
Current
Validity
Active non-fork protocol.
Sources
1 pinned source

Scope

RLPx version 5 is the encrypted TCP transport for execution-layer peer protocols. One connection carries the required p2p capability and any shared application capabilities, including eth and snap.

Cryptographic handshake

The initiator opens TCP and sends an ECIES-encrypted auth message. The recipient checks it and returns an encrypted ack.

The handshake authenticates each node's static secp256k1 key. It uses ephemeral ECDH, both nonces, Keccak-256, AES-128-CTR, and Keccak-based MAC states to derive the session secrets.

Each side checks the MAC of the first encrypted frame. Authentication failure closes the connection. Peers ignore handshake-version mismatches and trailing RLP items for forward compatibility.

Framing

Each frame has an encrypted header, header MAC, encrypted body, and body MAC. The header carries a 24-bit body size. Zero padding aligns header and body data to 16-byte AES blocks.

After Hello, message data uses Snappy compression. A peer reads the Snappy length before decompression and closes the connection when the uncompressed data exceeds 16 MiB.

Capability negotiation

Both peers first send Hello, which lists client identity, node key, and supported capability name-version pairs. No application message is valid before the peer's Hello.

The peers select the highest shared version of each capability name. They order shared names alphabetically and assign compact message-ID ranges from 0x10. IDs 0x00 through 0x0f belong to p2p.

Ping requests an empty Pong. Either peer can send Disconnect with a reason such as protocol breach, too many peers, duplicate connection, or ping timeout.

Failure handling

  • Close the TCP connection when ECIES, frame MAC, or Snappy checks fail.
  • Reject a message whose uncompressed size is more than 16 MiB.
  • Do not send application messages before Hello.
  • Ignore capabilities that the peers do not share.
  • Use only the highest shared version for one capability name.
  • Ignore trailing handshake and Hello fields.

Design rationale

One authenticated stream avoids a separate TCP connection for each execution protocol. Message-ID ranges multiplex capabilities even though the frame header does not use its capability ID fields.

History

RLPx version 4 added EIP-8 forward-compatible handshake parsing. Version 5 added Snappy compression after Hello.