Merge pull request #778 from fjl/enr

EIP-778: Ethereum Node Records

EIPS/eip-778.md

@@ -0,0 +1,104 @@
+---
+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 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.
+