Skip to content

Latest commit

 

History

History
104 lines (74 loc) · 4.25 KB

eip-778.md

File metadata and controls

104 lines (74 loc) · 4.25 KB
Raw

Preamble

EIP: 778
Title: Ethereum Node Records (ENR)
Author: Felix Lange <fjl@ethereum.org>
Type: Standard Track
Category Networking
Status: Draft
Created: 2017-11-23

Abstract

This EIP defines Ethereum Node Records, an open format for p2p connectivity information.

Motivation

Ethereum nodes discover each other through the node discovery protocol. The purpose of that protocol is relaying node identity public keys (on the secp256k1 curve), their IP address and two port numbers. No other information can be relayed.

This specification seeks to lift the restrictions of the discovery v4 protocol by defining a flexible format, the node record, for connectivity-related information. Node records can be relayed through a future version of the node discovery protocol. They can also be relayed through arbitrary other mechanisms such as DNS, ENS, a devp2p subprotocol, etc.

Node records improve cryptographic agility and handling of protocol upgrades. A record can contain information about arbitrary transport protocols and public key material associated with them.

Another goal of the new format is to provide authoritative updates of connectivity information. If a node changes its endpoint and publishes a new record, other nodes should be able to determine which record is newer.

Specification

The components of a node record are:

  • signature: cryptographic signature of record contents
  • seq: The sequence number, a 64 bit integer. Nodes should increase the number whenever the record changes and republish the record.
  • The remainder of the record consists of arbitrary key/value pairs, which must be sorted by key.

A record's signature is made and validated according to an identity scheme. The identity scheme is also responsible for deriving a node's address in the DHT.

RLP Encoding

The canonical encoding of a node record is an RLP list of [signature, seq, k, v, ...]. The maximum encoded size of a node record is 300 bytes. Implementations should reject records larger than this size.

Records are signed and encoded as follows:

content   = rlp(seq) || rlp(k) || rlp(v) || ...
signature = rlp(sign(rlp_list(content)))
record    = rlp_list(signature || content)

Key/Value Pairs

The keys in key/value pairs can technically be any byte sequence, but ASCII text is preferred. The following keys are pre-defined:

Key Value
id name of identity scheme, e.g. "secp256k1-keccak"
secp256k1 compressed secp256k1 public key, 33 bytes
ip4 IPv4 address, 4 bytes
ip6 IPv6 address, 16 bytes
discv5 UDP port for discovery v5

secp256k1-keccak Identity Scheme

This specification defines a single scheme to be used as the default: "secp256k1-keccak".

  • To sign record content with this scheme, apply the keccak2561 hash function to content, then create a signature of the hash. The resulting 64-byte signature is encoded as the concatenation of the r and s signature values.
  • To verify a record, check that the signature was made by the public key in the "secp256k1" key/value pair.
  • To derive a node address, take the keccak256 hash of the public key.

Rationale

The format is meant to suit future needs in two ways:

  • Adding new key/value pairs: This is always possible and doesn't require implementation consensus. Existing clients will accept any key/value pairs regardless of whether they can interpret their content.
  • Adding identity schemes: these need implementation consensus because the network won't accept the signature otherwise. To introduce a new identity scheme, propose an EIP and get it implemented. The scheme can be used as soon as most clients accept it.

The size of a record is limited because records are relayed frequently and may be included in size-constrained protocols such as DNS. A record containing IPv4 address, when signed using the "secp256k1-keccak" scheme occupies roughly 120 bytes, leaving plenty of room for additional metadata.

Copyright

Copyright and related rights waived via CC0.

Footnotes

  1. As used by the EVM ↩