Skip to main content

31/WAKU2-ENR

Abstract​

This specification describes the usage of the ENR (Ethereum Node Records) format for 10/WAKU2 purposes. The ENR format is defined in EIP-778 [3].

This specification is an extension of EIP-778, ENR used in Waku MUST adhere to both EIP-778 and 31/WAKU2-ENR.

Motivation​

EIP-1459 with the usage of ENR has been implemented [1] [2] as a discovery protocol for Waku.

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 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 specification 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 protocol family is built on the libp2p protocol stack. Hence, it uses 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 specification 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.

Wire Format​

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 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 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 pre-defined keys.
  • The 300 bytes size limit as defined by 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 Waku 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:

keyvalue
tcp10101
udp20202
tcp630303
udp640404
ip1.2.3.4
ip61234:5600:101:1::142
secp256k1Alice's compressed secp256k1 public key, 33 bytes
multiaddrslen1 \| /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 multiaddrs:

  • | 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 that runs a node that supports inbound connection for the following protocols:

  • TCP 10101 on 1.2.3.4

Bob SHOULD structure the ENR for his node as follows:

keyvalue
tcp10101
ip1.2.3.4
secp256k1Bob's compressed secp256k1 public key, 33 bytes

As Bob's node's connection details can be represented with EIP-778's pre-defined keys only, it is not needed to use the multiaddrs key.

Limitations​

Supported key type is secp256k1 only.

Support for other elliptic curve cryptography such as ed25519 MAY be used.

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 7bit 6bit 5bit 4bit 3bit 2bit 1bit 0
undefundefundefsynclightpushfilterstorerelay
  • 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.

Key Usage​

  • A Waku 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 nodes that want to participate in Node Discovery Protocol v5 [4], however, MUST implement the waku2 key with at least one flag set to true.
  • Waku 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 and related rights waived via CC0.

References​