EIP-778: final update to IPv6 keys, use URL-safe base64

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