mirror of https://github.com/status-im/EIPs.git
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
|
# Preamble
|
||
|
|
|
||
|
|
EIP: 778
|
||
|
|
Title: Ethereum Node Records (ENR)
|
||
|
|
Author: Felix Lange <fjl@ethereum.org>
|
||
|
|
Type: Standard Track
|
||
|
|
Category Networking
|
||
|
|
Status: Draft
|
||
|
|
Created: 2017-05-17
|
||
|
|
|
||
|
|
# 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`: A sequence number. 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 *identy 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
|
||
|
|
|
||
|
|
Key/Value keys can be any byte sequence, but should be text. The following keys are
|
||
|
|
pre-defined:
|
||
|
|
|
||
|
|
| Key | Value |
|
||
|
|
|:-------------|:-------------------------------------------------|
|
||
|
|
| `id` | name of identity scheme, e.g. "secp256k1-keccak" |
|
||
|
|
| `secp256k1` | compressed secp256k1 public key |
|
||
|
|
| `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 `r` and `s`.
|
||
|
|
- 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.
|
||
|
|
|