diff --git a/EIPS/eip-778.md b/EIPS/eip-778.md index ae64e93da52e0..b0976c8784a74 100644 --- a/EIPS/eip-778.md +++ b/EIPS/eip-778.md @@ -39,25 +39,31 @@ The components of a node record are: - `signature`: cryptographic signature of record contents - `seq`: The sequence number, a 64-bit unsigned 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. Keys must be unique. +- The remainder of the record consists of arbitrary key/value pairs 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. -The keys in key/value pairs can technically be any byte sequence, but ASCII text is -preferred. Keys in the table below have pre-defined meaning. - -| Key | Value | -|:------------|:------------------------------------------| -| `id` | name of identity scheme, e.g. "v4" | -| `secp256k1` | compressed secp256k1 public key, 33 bytes | -| `ip` | IPv4 address, 4 bytes | -| `ip6` | IPv6 address, 16 bytes | -| `tcp` | TCP port, big endian integer | -| `udp` | UDP port, big endian integer | - -All keys except `id` are optional. +The key/value pairs must be sorted by key and must be unique, i.e. any key may be present +only once. The keys can technically be any byte sequence, but ASCII text is preferred. Key +names in the table below have pre-defined meaning. + +| Key | Value | +|:------------|:-------------------------------------------| +| `id` | name of identity scheme, e.g. "v4" | +| `secp256k1` | compressed secp256k1 public key, 33 bytes | +| `ip` | IPv4 address, 4 bytes | +| `tcp` | TCP port, big endian integer | +| `udp` | UDP port, big endian integer | +| `ip6` | IPv6 address, 16 bytes | +| `tcp6` | IPv6-specific TCP port, big endian integer | +| `udp6` | IPv6-specific UDP port, big endian integer | + +All keys except `id` are optional, including IP addresses and ports. A record without +endpoint information is still valid as long as its signature is valid. If no `tcp6` / +`udp6` port is provided, the `tcp` / `udp` port applies to both IP addresses. Declaring +the same port number in both `tcp`, `tcp6` or `udp`, `udp6` should be avoided but doesn't +render the record invalid. ### RLP Encoding @@ -74,12 +80,14 @@ Records are signed and encoded as follows: ### Text Encoding The textual form of a node record is the base64 encoding of its RLP representation, -prefixed by `enr:`. +prefixed by `enr:`. Implementations should use the [URL-safe base64 alphabet][base64url] +and omit padding characters. ### "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 v4. +This specification defines a single identity scheme to be used as the default until other +schemes are defined by further EIPs. The "v4" scheme is backwards-compatible with the +cryptosystem used by Node Discovery 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 @@ -105,15 +113,19 @@ in size-constrained protocols such as DNS. A record containing a IPv4 address, w using the "v4" scheme occupies roughly 120 bytes, leaving plenty of room for additional metadata. +You might wonder about the need for so many pre-defined keys related to IP addresses and +ports. This need arises because residential and mobile network setups often put IPv4 +behind NAT while IPv6 traffic—if supported—is directly routed to the same host. Declaring +both address types ensures a node is reachable from IPv4-only locations and those +supporting both protocols. + # Test Vectors This is an example record containing the IPv4 address `127.0.0.1` and UDP port `30303`. The node ID is `a448f24c6d18e575453db13171562b71999873db5b286df957af199ec94617f7`. ```text -enr:+IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj -499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2 -/oxVtw0RW/QAdpzBQA8yWM0xOIN1ZHCCdl8= +enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8 ``` The record is signed using the "v4" identity scheme using sequence number `1` and this @@ -143,3 +155,5 @@ The RLP structure of the record is: # Copyright Copyright and related rights waived via CC0. + +[base64url]: https://tools.ietf.org/html/rfc4648#section-5