EIP-778 Ethereum Node Records (ENR)
Final · Networking & nodes · EIP status Final · created 2017-11-23
Defines Ethereum Node Records (ENR), an open format for carrying a node's connection information as signed key/value pairs. A sequence number indicates which information is most recent, and new fields can be added freely.
Why it is needed
Ethereum nodes find each other through the node discovery protocol. However, the existing discovery v4 can only convey a node's public key (on the secp256k1 curve), IP address, and port number, with no way to carry anything else. There is no way to advertise a new transport protocol or the public key material associated with it. Also, when a node changes its connection endpoint and publishes new information, other nodes have no basis for determining which version is more recent. This EIP resolves these constraints by defining a node record format that holds connection-related information as free-form key/value pairs. Records can be distributed not only through future versions of the discovery protocol but also through other channels such as DNS, ENS, and devp2p subprotocols. Because records carry a signature and a sequence number, when a node changes its connection endpoint and publishes a new record, other nodes can tell which record is more recent.
What changes
Today
- Discovery v4 can only convey a public key, IP address, and port, with no way to carry other information
- There is no way to advertise a new transport protocol or its associated public key material
- When a node changes its connection endpoint, there is no basis for determining which information is most recent
After EIP-778
- Arbitrary connection information is carried in node records, a signed key/value pair format
- New key/value pairs can be added without implementer consensus, and new identity schemes are added via EIP
- Comparing sequence numbers determines which record is more recent
Who is affected
- Client teams: Implementations must handle signature generation and verification for records, the 300-byte size limit, and the enr: text encoding.
- Node operators: A node's connection information can be shared as a single line of text starting with enr:.
- Protocol designers: New transport protocol information or new cryptographic schemes (identity schemes) can be carried in records and propagated across the network.
In depth
The three components of a record
A node record consists of signature (a cryptographic signature over the record contents), seq (a sequence number as a 64-bit unsigned integer), and the remaining arbitrary key/value pairs. A node must increment seq and republish the record whenever the record changes. The key/value pairs must be sorted by key, and the same key must not appear twice. Keys can technically be any byte sequence, but ASCII text is preferred. The identity scheme is responsible for generating and verifying signatures and for deriving the node's address in the DHT.
Predefined keys and dual IPv4/IPv6 declarations
The predefined keys are id (the identity scheme name, e.g. "v4"), secp256k1 (a 33-byte compressed public key), ip (a 4-byte IPv4 address), tcp/udp (big-endian integer ports), ip6 (a 16-byte IPv6 address), and tcp6/udp6 (IPv6-specific ports). All keys except id are optional, so a record is still valid without an IP or port as long as the signature is valid. If no tcp6/udp6 port is given, the tcp/udp port applies to both addresses. Duplicating the same port across tcp and tcp6, or udp and udp6, should be avoided but does not invalidate the record. There are many IP-related keys because in home and mobile environments IPv4 is often behind NAT while IPv6 often routes directly to the same host. Declaring both addresses lets peers reach the node whether they only have IPv4 or support both.
RLP encoding and the 300-byte limit
The canonical encoding of a record is an RLP list of the form [signature, seq, k, v, ...]. The signature is computed over content = [seq, k, v, ...] (signature = sign(content)), and the final record is record = [signature, seq, k, v, ...]. The maximum size of an encoded record is 300 bytes, and implementations must reject larger records. The size is limited because records are relayed frequently and may be carried over protocols with size constraints, such as DNS. A record containing an IPv4 address and signed with the v4 scheme occupies roughly 120 bytes, leaving ample room for additional metadata.
Text encoding: the enr: prefix
The text form of a record is the RLP representation base64-encoded with enr: prepended. Implementations must use the URL-safe base64 alphabet and omit padding characters. The test vector in the source document shows a record containing the IPv4 address 127.0.0.1 and UDP port 30303, signed with the v4 scheme using sequence number 1 and a specified private key, along with the resulting enr: string and RLP structure.
The default identity scheme "v4"
This is the default scheme used until another scheme is defined in a separate EIP. It is backward compatible with the cryptography used by discovery v4. To sign, the keccak256 hash function (the same one used in the EVM) is applied to content, and the resulting hash is signed. The resulting 64-byte signature is encoded by concatenating the r and s values, omitting the recovery id v. To verify, the signature is checked against the public key given in the record's "secp256k1" key/value pair. The node address is derived as the keccak256 hash of the uncompressed public key.
Two extension paths
The format is designed to accommodate future needs in two ways. First, adding new key/value pairs is always possible and requires no implementation consensus. Existing clients accept any key/value pair whether or not they can interpret its contents. Second, adding a new identity scheme requires implementation consensus, since it cannot be used unless the network accepts its signatures. Introducing a new scheme requires proposing an EIP and getting it implemented, and it can only be used once most clients support it. This EIP itself is a finalized standard with status Final.