DCIPs/EIPS/eip-778.md

---
eip: 778
title: Ethereum Node Records (ENR)
author: Felix Lange <fjl@ethereum.org>
type: Standards Track
category: Networking
status: Final
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 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

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 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

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   = [seq, k, v, ...]
    signature = sign(content)
    record    = [signature, seq, k, v, ...]

### Text Encoding

The textual form of a node record is the base64 encoding of its RLP representation,
prefixed by `enr:`. Implementations should use the [URL-safe base64 alphabet][base64url]
and omit padding characters.

### "v4" Identity Scheme

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
  signature is encoded as the concatenation of the `r` and `s` signature values (the
  recovery ID `v` is omitted).
- To verify a record, check that the signature was made by the public key in the
  "secp256k1" key/value pair of the record.
- 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.

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:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8
```

The record is signed using the "v4" identity scheme using sequence number `1` and this
private key:

```text
b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291
```

The RLP structure of the record is:

```text
[
  7098ad865b00a582051940cb9cf36836572411a47278783077011599ed5cd16b76f2635f4e234738f30813a89eb9137e3e3df5266e3a1f11df72ecf1145ccb9c,
  01,
  "id",
  "v4",
  "ip",
  7f000001,
  "secp256k1",
  03ca634cae0d49acb401d8a4c6b6fe8c55b70d115bf400769cc1400f3258cd3138,
  "udp",
  765f,
]
```

# Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).

[base64url]: https://tools.ietf.org/html/rfc4648#section-5