Skip to main content
netspecsEthereum networking

1.3.Ethereum node records

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

An Ethereum Node record (ENR) is a signed, versioned set of node properties. Discovery protocols exchange ENRs so a peer can check identity, endpoints, and capabilities before it opens a transport session. The identity page defines the identity forms that sign or consume an ENR. Layer profiles define additional keys such as eth, eth2, attnets, and syncnets.

Record structure

The canonical RLP form is:

record  = [signature, seq, key, value, key, value, ...]
content = [seq, key, value, ...]

seq is an unsigned 64-bit integer. A node increases it and republishes the record when any signed value changes. Keys are unique byte strings in ascending byte order. The signature covers the content list, not the outer signature field. The id key names the identity scheme that verifies the signature and derives the node ID.

The encoded record is at most 300 bytes. A receiver should reject a larger record before it stores or relays it. Unknown keys do not invalidate a record; they let a newer profile add data without changing the envelope.

Common fields

Key Value
id Identity-scheme name, for example v4. This is the only required common key.
secp256k1 A 33-byte compressed secp256k1 public key for the v4 scheme.
ip A 4-byte IPv4 address.
ip6 A 16-byte IPv6 address.
tcp, udp A big-endian port. The generic port also applies to IPv6 when its IPv6-specific key is absent.
tcp6, udp6 An IPv6-specific big-endian port.

All endpoint keys are optional. A valid record can have no dialable endpoint. Repeating one port in both the generic and IPv6-specific key is valid but discouraged. A discovery profile can require a particular endpoint and capability before it selects the record.

Text encoding

The text form is the canonical RLP record encoded with URL-safe base64, without padding, and prefixed with enr::

enr:<base64url-without-padding>

DNS discovery stores this text as an enr: leaf. discv4 and discv5 carry the RLP record itself in their response payloads.

v4 identity scheme

For v4, the signer computes keccak256(content) and stores a 64-byte r || s secp256k1 signature. The recovery identifier is omitted. The receiver checks the signature against the compressed public key in secp256k1.

The node ID is the Keccak-256 hash of the uncompressed public-key coordinates:

node_id = keccak256(x || y)

Both coordinates are left-padded to 32 bytes. A discovery table uses this ID for routing distance; the transport may use a different identity object.

Validation and update rules

  1. Decode one RLP list and reject an encoding larger than 300 bytes.
  2. Check that keys are unique and sorted in byte order.
  3. Read id and apply the identity scheme's signature and node-ID rules.
  4. Check the signature over [seq, key, value, ...].
  5. Store the valid record with the greatest sequence number for that identity.
  6. Retain unknown keys when relaying a valid record.

An implementation must not treat a sequence increase as proof of continuity after a key rotation. A new identity key creates a new node ID.

The envelope stays small so a record can travel in UDP discovery and DNS TXT entries. Profiles can add signed capability keys without changing this common wire format.