From 073f49bd180904ae9c0f5899866dc8d472e9925a Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 30 Oct 2024 00:49:32 -0400 Subject: [PATCH 1/2] Create enr.md --- waku/standards/core/31/enr.md | 170 ++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 waku/standards/core/31/enr.md diff --git a/waku/standards/core/31/enr.md b/waku/standards/core/31/enr.md new file mode 100644 index 00000000..1e667cec --- /dev/null +++ b/waku/standards/core/31/enr.md @@ -0,0 +1,170 @@ +--- +slug: 31 +title: WAKU2-ENR +name: Waku v2 ENR Usage +tags: waku/core-protocol +editor: Franck Royer +contributors: +--- + +## Abstract + +This RFC describes the usage of the ENR (Ethereum Node Records) format for [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) purposes. +The ENR format is defined in [EIP-778](https://eips.ethereum.org/EIPS/eip-778) [[3]](#references). + +This RFC is an extension of EIP-778, ENR used in Waku v2 MUST adhere to both EIP-778 and 31/WAKU2-ENR. + +## Motivation + +EIP-1459 with the usage of ENR has been implemented [[1]](#references) [[2]](#references) as a discovery protocol for Waku v2. + +EIP-778 specifies a number of pre-defined keys. +However, the usage of these keys alone does not allow for certain transport capabilities to be encoded, +such as Websocket. +Currently, Waku v2 nodes running in a Browser only support websocket transport protocol. +Hence, new ENR keys need to be defined to allow for the encoding of transport protocol other than raw TCP. + +### Usage of Multiaddr Format Rationale + +One solution would be to define new keys such as `ws` to encode the websocket port of a node. +However, we expect new transport protocols to be added overtime such as quic. +Hence, this would only provide a short term solution until another RFC would need to be added. + +Moreover, secure websocket involves SSL certificates. +SSL certificates are only valid for a given domain and ip, so an ENR containing the following information: + +- secure websocket port +- ipv4 fqdn +- ipv4 address +- ipv6 address + +Would carry some ambiguity: Is the certificate securing the websocket port valid for the ipv4 fqdn? +the ipv4 address? +the ipv6 address? + +The [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocol family is built on the [libp2p](https://github.com/libp2p/specs) protocol stack. +Hence, it uses [multiaddr](https://github.com/multiformats/multiaddr) to format network addresses. + +Directly storing one or several multiaddresses in the ENR would fix the issues listed above: + +- multiaddr is self-describing and support addresses for any network protocol: + No new RFC would be needed to support encoding other transport protocols in an ENR. +- multiaddr contains both the host and port information, allowing the ambiguity previously described to be resolved. + +## `multiaddrs` ENR key + +We define a `multiaddrs` key. + +- The value MUST be a list of binary encoded multiaddr prefixed by their size. +- The size of the multiaddr MUST be encoded in a Big Endian unsigned 16-bit integer. +- The size of the multiaddr MUST be encoded in 2 bytes. +- The `secp256k1` value MUST be present on the record; + `secp256k1` is defined in [EIP-778](https://eips.ethereum.org/EIPS/eip-778) and contains the compressed secp256k1 public key. +- The node's peer id SHOULD be deduced from the `secp256k1` value. +- The multiaddresses SHOULD NOT contain a peer id except for circuit relay addresses +- For raw TCP & UDP connections details, [EIP-778](https://eips.ethereum.org/EIPS/eip-778) pre-defined keys SHOULD be used; + The keys `tcp`, `udp`, `ip` (and `tcp6`, `udp6`, `ip6` for IPv6) are enough to convey all necessary information; +- To save space, `multiaddrs` key SHOULD only be used for connection details that cannot be represented using the [EIP-778](https://eips.ethereum.org/EIPS/eip-778) pre-defined keys. +- The 300 bytes size limit as defined by [EIP-778](https://eips.ethereum.org/EIPS/eip-778) still applies; + In practice, it is possible to encode 3 multiaddresses in ENR, more or less could be encoded depending on the size of each multiaddress. + +### Usage + +#### Many connection types + +Alice is a node operator, she runs a node that supports inbound connection for the following protocols: + +- TCP 10101 on `1.2.3.4` +- UDP 20202 on `1.2.3.4` +- TCP 30303 on `1234:5600:101:1::142` +- UDP 40404 on `1234:5600:101:1::142` +- Secure Websocket on `wss://example.com:443/` +- QUIC on `quic://quic.example.com:443/` +- A circuit relay address `/ip4/1.2.3.4/tcp/55555/p2p/QmRelay/p2p-circuit/p2p/QmAlice` + +Alice SHOULD structure the ENR for her node as follows: + +| key | value | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tcp` | `10101` | +| `udp` | `20202` | +| `tcp6` | `30303` | +| `udp6` | `40404` | +| `ip` | `1.2.3.4` | +| `ip6` | `1234:5600:101:1::142` | +| `secp256k1` | Alice's compressed secp256k1 public key, 33 bytes | +| `multiaddrs` | len1 | /dns4/example.com/tcp/443/wss | len2 | /dns4/quic.examle.com/tcp/443/quic | len3 | /ip4/1.2.3.4/tcp/55555/p2p/QmRelay | + +Where: + +- `|` is the concatenation operator, +- `len1` is the length of `/dns4/example.com/tcp/443/wss` byte representation, +- `len2` is the length of `/dns4/quic.examle.com/tcp/443/quic` byte representation. +- `len3` is the length of `/ip4/1.2.3.4/tcp/55555/p2p/QmRelay` byte representation. Notice that the `/p2p-circuit` component is not stored, but, since circuit relay addresses are the only one containing a `p2p` component, it's safe to assume that any address containing this component is a circuit relay address. Decoding this type of multiaddresses would require appending the `/p2p-circuit` component. + +#### Raw TCP only + +Bob is a node operator, he runs a node that supports inbound connection for the following protocols: + +- TCP 10101 on `1.2.3.4` + +Bob SHOULD structure the ENR for her node as follows: + +| key | value | +| ----------- | ----------------------------------------------- | +| `tcp` | `10101` | +| `ip` | `1.2.3.4` | +| `secp256k1` | Bob's compressed secp256k1 public key, 33 bytes | + +Indeed, as Bob's node's connection details can be represented with EIP-778's pre-defined keys only +then it is not needed to use the `multiaddrs` key. + +### Limitations + +Supported key type is `secp256k1` only. + +In the future, an extension of this RFC could be made to support other elliptic curve cryptography such as `ed25519`. + +## `waku2` ENR key + +We define a `waku2` field key: + +- The value MUST be an 8-bit flag field, + where bits set to `1` indicate `true` and bits set to `0` indicate `false` for the relevant flags. +- The flag values already defined are set out below, + with `bit 7` the most significant bit and `bit 0` the least significant bit. + +| bit 7 | bit 6 | bit 5 | bit 4 | bit 3 | bit 2 | bit 1 | bit 0 | +| ------- | ------- | ------- | ------- | ----------- | -------- | ------- | ------- | +| `undef` | `undef` | `undef` | `sync` | `lightpush` | `filter` | `store` | `relay` | + +- In the scheme above, the flags `sync`, `lightpush`, `filter`, `store` and `relay` correlates with support for protocols with the same name. + If a protocol is not supported, the corresponding field MUST be set to `false`. + Indicating positive support for any specific protocol is OPTIONAL, + though it MAY be required by the relevant application or discovery process. +- Flags marked as `undef` is not yet defined. + These SHOULD be set to `false` by default. + +### Usage + +- A Waku v2 node MAY choose to populate the `waku2` field for enhanced discovery capabilities, + such as indicating supported protocols. + Such a node MAY indicate support for any specific protocol by setting the corresponding flag to `true`. +- Waku v2 nodes that want to participate in [Node Discovery Protocol v5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) [[4]](#references), however, + MUST implement the `waku2` key with at least one flag set to `true`. +- Waku v2 nodes that discovered other participants using Discovery v5, + MUST filter out participant records that do not implement this field or do not have at least one flag set to `true`. +- In addition, such nodes MAY choose to filter participants on specific flags (such as supported protocols), + or further interpret the `waku2` field as required by the application. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +- [1](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +- [2](https://github.com/status-im/nim-waku/pull/690) +- [3](https://github.com/vacp2p/rfc/issues/462#issuecomment-943869940) +- [4](https://eips.ethereum.org/EIPS/eip-778) +- [5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) From 0bf253fe22974e1da91e73910d98f839f58081fd Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 30 Oct 2024 00:50:38 -0400 Subject: [PATCH 2/2] Update enr.md --- waku/standards/core/31/enr.md | 1 + 1 file changed, 1 insertion(+) diff --git a/waku/standards/core/31/enr.md b/waku/standards/core/31/enr.md index 1e667cec..c7f788ab 100644 --- a/waku/standards/core/31/enr.md +++ b/waku/standards/core/31/enr.md @@ -2,6 +2,7 @@ slug: 31 title: WAKU2-ENR name: Waku v2 ENR Usage +status: draft tags: waku/core-protocol editor: Franck Royer contributors: