mirror of https://github.com/status-im/EIPs.git
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
---
|
|
eip: 778
|
|
title: Ethereum Node Records (ENR)
|
|
author: Felix Lange <fjl@ethereum.org>
|
|
type: Standards Track
|
|
category: Networking
|
|
status: Draft
|
|
created: 2017-11-23
|
|
discussions-to: https://github.com/ethereum/devp2p/issues/43
|
|
---
|
|
|
|
# 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. "v4" |
|
|
| `secp256k1` | compressed secp256k1 public key, 33 bytes |
|
|
| `ip` | IP address, 4 or 16 bytes |
|
|
| `tcp` | TCP port |
|
|
| `udp` | UDP port |
|
|
|
|
### "v4" Identity Scheme
|
|
|
|
This specification defines a single scheme to be used as the default. The "v4" scheme is
|
|
backwards-compatible with the cryptosystem used by Node Discovery Protocol v4.
|
|
|
|
- To sign record `content` with this scheme, apply the keccak256 hash function (as used by
|
|
the EVM) 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 uncompressed 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 a IPv4 address, when signed
|
|
using the "v4" scheme occupies roughly 120 bytes, leaving plenty of room for additional
|
|
metadata.
|
|
|
|
# Copyright
|
|
|
|
Copyright and related rights waived via CC0.
|