diff --git a/EIPS/eip-778.md b/EIPS/eip-778.md new file mode 100644 index 00000000000000..3931df6c6c2be3 --- /dev/null +++ b/EIPS/eip-778.md @@ -0,0 +1,104 @@ +--- +eip: 778 +title: Ethereum Node Records (ENR) +author: Felix Lange +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 keccak256[^1] 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. + +[^1]: As used by the EVM + +# 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. +