diff --git a/.wordlist.txt b/.wordlist.txt index 8e754de..3764e71 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,8 +1,39 @@ +ABIs +addListener ALLOC +api +AsyncAPI +autosharding +AutoShardingConfig +bool +camelCase +cd +config +ConnectionStatus +ConnectionStatusEvent +contentTopic +createNode creativecommons danielkaiser +DefaultAutoShardingConfig +DefaultMessageValidation +DefaultNetworkingConfig +dev DHT +discv +DISCV DoS +enrtree +enum +Eth +eth +ETH +EventEmitter +EventSource +eventType +fb +fBF +getMerkleRoot github GITHUB gossipsub @@ -10,14 +41,68 @@ GossipSub https iana IANA +IDL +implementor +ipv +iterable +KiB +Kozlov +libp libp2p +LIGHTPUSH md +MessageEnvelope +MessageErrorEvent +MessageEvents +MessagePropagatedEvent +MessageSentEvent +MessageValidation +multiaddr +NetworkConfig +NetworkingConfig +nim +NodeConfig +nodeConfig +num +Oleksandr +onEvent +OpenAPI +PartiallyConnected +PascalCase +Prathi +Prem +pre +ProtocolsConfig pubsub +RequestId rfc RFC +RLN +rln +RlnConfig +Royer +RPC +rpc SHARDING +sharding subnets +TBD +tcp +TCP +TheWakuNetworkMessageValidation +TheWakuNetworkPreset +TODO +TWN +udp +UDP +uint Waku +waku WAKU +WakuNode www +xB +yaml +YAML +yml ZXCV \ No newline at end of file diff --git a/README.md b/README.md index 66bd734..26b9864 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ This repository contains specifications for the Waku suite of protocols. |[TOR-PUSH](standards/application/tor-push.md)| Waku Tor Push | |[RLN-KEYSTORE](standards/application/rln-keystore.md)| Waku RLN Keystore JSON schema | |[P2P-RELIABILITY](standards/application/p2p-reliability.md)| Waku P2P Reliability | +|[WAKU-API](standards/application/waku-api.md)| Waku API | ### Informational diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index d75479f..3033d42 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -24,18 +24,25 @@ contributors: * [Language mappings](#language-mappings) * [Application](#application) * [The Waku API](#the-waku-api) - * [Initialise Waku node](#initialise-waku-node) - * [Type definitions](#type-definitions) - * [Function definitions](#function-definitions) - * [Predefined values](#predefined-values) - * [Extended definitions](#extended-definitions) - * [General events emission](#general-events-emission) - * [Type definitions](#type-definitions-1) - * [Subscribe to messages](#subscribe-to-messages) - * [Type definitions](#type-definitions-2) - * [Function definitions](#function-definitions-1) - * [Predefined values](#predefined-values-1) - * [Extended definitions](#extended-definitions-1) + * [Common](#common) + * [Common type definitions](#common-type-definitions) + * [Init node](#init-node) + * [Init node type definitions](#init-node-type-definitions) + * [Init node function definitions](#init-node-function-definitions) + * [Init node predefined values](#init-node-predefined-values) + * [Init node extended definitions](#init-node-extended-definitions) + * [Messaging](#messaging) + * [Messaging type definitions](#messaging-type-definitions) + * [Messaging function definitions](#messaging-function-definitions) + * [Messaging extended definitions](#messaging-extended-definitions) + * [Subscriptions](#subscriptions) + * [Subscriptions type definitions](#subscriptions-type-definitions) + * [Subscriptions function definitions](#subscriptions-function-definitions) + * [Subscriptions extended definitions](#subscriptions-extended-definitions) + * [Health](#health) + * [Health type definitions](#health-type-definitions) + * [Health function definitions](#health-function-definitions) + * [Health extended definitions](#health-extended-definitions) * [The Validation API](#the-validation-api) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -46,10 +53,10 @@ contributors: This document specifies an Application Programming Interface (API) that is RECOMMENDED for developers of the [WAKU2](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/10/waku2.md) clients to implement, and for consumers to use as a single entry point to its functionalities. -This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages. +This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages. Application developers SHOULD use it to access capabilities for peer discovery, message routing, and peer-to-peer reliability. -TODO: This spec must be further extended to include connection health inspection, message sending, subscription and store hash queries. +TODO: This spec must be further extended to include connection health inspection, subscription, and store hash queries. ## Motivation @@ -76,13 +83,13 @@ An alternative would be to choose a programming language. However, such choice m ### Primitive types and general guidelines - No `default` means that the value is mandatory, meaning a `default` value implies an optional parameter. -- Primitive types are `string`, `int`, `bool`, `enum` and `uint` +- Primitive types are `string`, `int`, `bool`, `byte`, `enum` and `uint` - Complex pre-defined types are: - `object`: object and other nested types. - - `array`: iterable object containing values of all the same type. + - `array`: iterable object containing values of all the same type. Syntax: `array` where `T` is the element type (e.g., `array`, `array`). - `result`: an enum type that either contains a value or void (success), or an error (failure); The error is left to the implementor. - `error`: Left to the implementor on whether `error` types are `string` or `object` in the given language. - - `event_emitter`: An object that emit events. + - `event_emitter`: an object that emits events with specific event names and associated event data types. - Usage of `result` is RECOMMENDED, usage of exceptions is NOT RECOMMENDED, no matter the language. TODO: Review whether to specify categories of errors. @@ -98,11 +105,13 @@ language_mappings: - functions: "camelCase" - variables: "camelCase" - types: "PascalCase" + event_emitter: "Use EventEmitter object with `emit`, `addListener`, etc; with event name the string specified in IDL. For example. eventEmitter.emit('message:sent',...)" nim: naming_convention: - functions: "camelCase" - variables: "camelCase" - types: "PascalCase" + event_emitter: TBD ``` ### Application @@ -117,15 +126,42 @@ library_name: "waku" description: "Waku: a private and censorship-resistant message routing library." ``` -### Initialise Waku node +### Common -#### Type definitions +This section describes common types used throughout the API. + +Note that all types in the API are described once in this document, in a single section. Types should just forward-reference other types when needed. + +#### Common type definitions ```yaml types: + WakuNode: type: object description: "A Waku node instance." + fields: + messageEvents: + type: MessageEvents + description: "The node's messaging event emitter" + subscriptionEvents: + type: SubscriptionEvents + description: "The node's content-topic subscription event emitter" + healthEvents: + type: HealthEvents + description: "The node's health monitoring event emitter" + + RequestId: + type: string + description: "A unique identifier for a request" +``` + +### Init node + +#### Init node type definitions + +```yaml +types: NodeConfig: type: object @@ -135,8 +171,8 @@ types: constraints: [ "edge", "core" ] default: "core" # "edge" for mobile and browser devices. description: "The mode of operation of the Waku node; 'edge' of the network: relies on other nodes for message routing; 'core' of the network: fully participate to message routing." - waku_config: - type: WakuConfig + protocols_config: + type: ProtocolsConfig default: TheWakuNetworkPreset networking_config: type: NetworkConfig @@ -145,7 +181,7 @@ types: type: array description: "Eth/Web3 RPC endpoint URLs, only required when RLN is used for message validation; fail-over available by passing multiple URLs. Accepting an object for ETH RPC will be added at a later stage." - WakuConfig: + ProtocolsConfig: type: object fields: entry_nodes: @@ -159,6 +195,7 @@ types: description: "The passed nodes are prioritised for store queries." cluster_id: type: uint + description: "The cluster ID for the Waku network. Cluster IDs are defined in [RELAY-SHARDING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/51/relay-sharding.md) and allocated in [RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md)." auto_sharding_config: type: AutoShardingConfig default: DefaultAutoShardingConfig @@ -209,19 +246,20 @@ types: fields: contract_address: type: string - description: "The address of the RLN contract exposes `root` and `getMerkleRoot` ABIs" + description: "The address of the RLN contract that exposes `root` and `getMerkleRoot` ABIs" chain_id: type: uint - description: "The chain id on which the RLN contract is deployed" + description: "The chain ID on which the RLN contract is deployed" epoch_size_sec: type: uint description: "The epoch size to use for RLN, in seconds" ``` -#### Function definitions +#### Init node function definitions ```yaml functions: + createNode: description: "Initialise a Waku node instance" parameters: @@ -232,7 +270,7 @@ functions: type: result ``` -#### Predefined values +#### Init node predefined values ```yaml values: @@ -245,13 +283,14 @@ values: discv5_udp_port: 9000 TheWakuNetworkPreset: - type: WakuConfig + type: ProtocolsConfig fields: entry_nodes: [ "enrtree://AIRVQ5DDA4FFWLRBCHJWUWOO6X6S4ZTZ5B667LQ6AJU6PEYDLRD5O@sandbox.waku.nodes.status.im" ] # On TWN, we encourage the usage of discovered store nodes static_store_nodes: [] cluster_id: 1 auto_sharding_config: + type: AutoShardingConfig fields: num_shards_in_cluster: 8 message_validation: TheWakuNetworkMessageValidation @@ -261,6 +300,7 @@ values: fields: max_message_size: "150 KiB" rln_config: + type: RlnConfig fields: contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6" chain_id: 59141 @@ -281,7 +321,7 @@ values: rln_config: none ``` -#### Extended definitions +#### Init node extended definitions **`mode`**: @@ -299,7 +339,6 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: - [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) - [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as service node - [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as service node -- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as service node - [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) as client - [METADATA](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/66/metadata.md) as client and service node - [P2P-RELIABILITY](/standards/application/p2p-reliability.md) @@ -310,55 +349,140 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: `edge` mode SHOULD be used if node functions in resource restricted environment, whereas `core` SHOULD be used if node has no strong hardware or bandwidth restrictions. -### General events emission +### Messaging -#### Type definitions +#### Messaging type definitions ```yaml types: - EventEmitter: - type: event_emitter - description: "An event emitter for general node events." - events: - "error:subscribe": - type: string - description: "Event emitted when subscription to a content topic irremediably fails. The event contains an error message." - "error:unsubscribe": - type: string - description: "Event emitted when unsubscribing from a content topic irremediably fails. The event contains an error message." - # Extending `WakuNode` definition - WakuNode: + + MessageEnvelope: + type: object fields: - events: - type: EventEmitter - description: "Event emitter for Waku node." + content_topic: + type: string + description: "Content-based filtering field as defined in [TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics)" + payload: + type: array + description: "The message data." + ephemeral: + type: bool + default: false + description: "Whether the message is ephemeral. Read at [ATTRIBUTES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md#message-attributes)" + + MessageReceivedEvent: + type: object + description: "Event emitted when a message is received from the network" + fields: + message: + type: MessageEnvelope + description: "The received message's payload and metadata" + + MessageSentEvent: + type: object + description: "Event emitted when a message is sent to the network" + fields: + request_id: + type: RequestId + description: "The request ID associated with the sent message" + message_hash: + type: string + description: "Hash of the message that got sent to the network" + + MessageSendErrorEvent: + type: object + description: "Event emitted when a message send operation fails" + fields: + request_id: + type: RequestId + description: "The request ID associated with the failed message" + message_hash: + type: string + description: "Optional property. Hash of the message that got error" + error: + type: string + description: "Error message describing what went wrong" + + MessageSendPropagatedEvent: + type: object + description: "Confirmation that a message has been correctly delivered to some neighbouring nodes." + fields: + request_id: + type: RequestId + description: "The request ID associated with the propagated message in the network" + message_hash: + type: string + description: "Hash of the message that got propagated within the network" + + MessageEvents: + type: event_emitter + description: "Event source for message-related events" + events: + "message:received": + type: MessageReceivedEvent + "message:sent": + type: MessageSentEvent + "message:send-error": + type: MessageSendErrorEvent + "message:send-propagated": + type: MessageSendPropagatedEvent ``` -### Subscribe to messages - -#### Type definitions - -```yaml -types: - MessageEmitter: - type: event_emitter - description: "An event emitter for message-related events. Emits events keyed by content topic, with the message payload as bytes." - events: - string: - type: bytes - description: "Event emitted when a message is received on the specified content topic. The event name is the content topic string, and the event payload is the raw message bytes." - # Extending `WakuNode` definition - WakuNode: - fields: - messageEmitter: - type: MessageEmitter - description: "Event emitter for received messages, keyed by content topic." -``` - -#### Function definitions +#### Messaging function definitions ```yaml functions: + + send: + description: "Send a message through the network." + parameters: + - name: message + type: MessageEnvelope + description: "Parameters for sending the message." + returns: + type: result +``` + +#### Messaging extended definitions + +A first `message` sent with a certain `contentTopic` SHOULD trigger a subscription for such `contentTopic` as described in the `Subscriptions` section. + +The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery. + +### Subscriptions + +#### Subscriptions type definitions + +```yaml +types: + + SubscriptionErrorEvent: + type: object + description: "Event emitted when a content topic subscription-related operation fails" + fields: + content-topic: + type: string + description: "Content topic that the node failed to subscribe to or unsubscribe from" + subscribe: + type: bool + description: "True if failed to subscribe, false if failed to unsubscribe instead" + error: + type: string + description: "Error message describing what went wrong" + + SubscriptionEvents: + type: event_emitter + description: "Event source for subscription-related events." + events: + "subscription:error": + type: SubscriptionErrorEvent +``` + +#### Subscriptions function definitions + +```yaml +functions: + subscribe: description: "Subscribe to specific content topics" parameters: @@ -367,6 +491,7 @@ functions: description: "The content topics for the node to subscribe to." returns: type: void + unsubscribe: description: "Unsubscribe from specific content topics" parameters: @@ -377,9 +502,7 @@ functions: type: void ``` -#### Predefined values - -#### Extended definitions +#### Subscriptions extended definitions **`mode`**: @@ -388,23 +511,80 @@ If the `mode` set is `edge`, `subscribe` SHOULD trigger set up a subscription us If the `mode` set is `core`, `subscribe` SHOULD trigger set up a subscription using [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). This MAY trigger joining a new shard if not already set. -Only messages on subscribed content topics SHOULD be emitted by `messageEmitter`, meaning messages received via `RELAY` SHOULD be filtered by content topics before emission. +Only messages on subscribed content topics SHOULD be emitted by a `MessageEvents` event source, meaning messages received via `RELAY` SHOULD be filtered by content topics before emission. **`error`**: -Only irremediable failures should lead to emitting a `"error:subscribe"`. +Only irremediable failures should lead to emitting a `"subscription:error"` for failed subscribe or unsubscribe operations. + Failure to reach nodes can be omitted, and should be handled via the health events; [P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. -An `"error:unsubscribe"` is emitted if there is no content topic subscription to unsubscribe from, or ongoing content topic subscription attempt to cancel. - Examples of irremediable failures are: - Invalid content topic format - Exceeding number of content topics - Node not started +- Already unsubscribed - Other node-level configuration issue +### Health + +#### Health type definitions + +```yml +types: + + ConnectionStatus: + type: enum + values: [Disconnected, PartiallyConnected, Connected] + description: "Used to identify health of the operating node" + + HealthConnectionStatusEvent: + type: object + description: "Event emitted when the overall node health status changes" + fields: + connection-status: + type: ConnectionStatus + description: "The node's new connection status" + + HealthEvents: + type: event_emitter + description: "Event source for health-related events." + events: + "health:connection-status": + type: HealthConnectionStatusEvent +``` + +#### Health function definitions + +```yml +functions: + + check-api-availability: + description: "Get current binary connectivity status" + parameters: + - name: waku + type: WakuNode + description: "The node to check for a binary connectivity status." + returns: + type: result +``` + +#### Health extended definitions + +`Disconnected` indicates that the node has lost connectivity for message reception, +sending, or both, and as a result, it cannot reliably receive or transmit messages. + +`PartiallyConnected` indicates that the node meets the minimum operational requirements: +it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +one peer with a protocol to receive messages ([FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +and one peer with [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) service capabilities, +although performance or reliability may still be impacted. + +`Connected` indicates that the node is operating optimally, +with full support for message reception and transmission. + ## The Validation API [WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md) is currently the primary message validation mechanism in place. diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 6a42abd..292be4c 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -1,66 +1,121 @@ --- title: WAKU-RENDEZVOUS name: Waku Rendezvous discovery -editor: Simon-Pierre Vivier -contributors: +editor: Prem Chaitanya Prathi +contributors: Simon-Pierre Vivier --- ## Abstract + This document describes the goal, -strategy and usage of the libp2p rendezvous protocol by Waku. +strategy, usage, and changes to the libp2p rendezvous protocol by Waku. Rendezvous is one of the discovery methods that can be used by Waku. It supplements Discovery v5 and Waku peer exchange. ## Background and Rationale -How do new nodes join the network is the question that discovery answers. -Discovery must be fast, pertinent and resilient to attacks. -Rendezvous is both fast and allow the discovery of relevant peers, -although it design can be easily abused -due to it's lack of protection against denial of service atacks. -The properties of rendezvous complements well the slower but safer methods like Discv5. -To contribute well, a Waku node must know a sufficient number of peers with -a wide variety of capabilities. -By using rendezvous in combination with -[Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) and -[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract), -Waku nodes will reach a good number of meaningful peers -faster than through a single discovery method. + +Waku needs discovery mechanism(s) that are both rapid and robust against attacks. +Fully centralised discovery (such as DNS lookup) may be fast but is not secure. +Fully decentralised discovery (such as discv5) may be robust, but too slow for some bootstrapping use cases +Rendezvous provides a limited, balanced solution that trades off some robustness for speed. +It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5 + +By combining rendezvous with +[Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) and +[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract), +Waku nodes can more quickly reach a meaningful set of peers +than by relying on a single discovery method. ## Semantics -Waku rendezvous fully inherits the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol). + +Waku rendezvous extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. +This allows nodes to advertise additional Waku-specific metadata beyond what is available in the standard libp2p peer record. ## Specifications -The namespaces used to register and request MUST be in the format `rs/cluster-id/shard`. -Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster and shard information. -Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. +**Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` + +### Wire Protocol + +Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/0c6c7d75f1580af329847dbc9900859a445ed980/table.csv). +The `WakuPeerRecord` is defined as follows: + +**WakuPeerRecord fields:** + +- `peer_id`: The libp2p PeerId of the node. +- `seqNo`: The time at which the record was created or last updated (Unix epoch, seconds). +- `multiaddrs`: A list of multiaddresses for connectivity. +- `mix_public_key`: The Mix protocol public key (only present for nodes supporting Mix). + +**Encoding:** +WakuPeerRecord is encoded as a protobuf message. The exact schema is: + +```protobuf +message WakuPeerRecord { + string peer_id = 1; + uint64 seqNo = 2; + repeated string multiaddrs = 3; + optional bytes mix_public_key = 4; +} +``` + +When a node discovers peers through rendezvous, it receives the complete `WakuPeerRecord` for each peer, allowing it to make informed decisions about which peers to connect to based on their advertised information. + +### Namespace Format + +The [rendezvous namespaces](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#the-protocol) used to register and request peer records +MUST be in the format `rs//`. +`` is a string representing the individual capability for which a discoverable Waku peer record is registered. +The Waku peer record is separately registered against each capability for which discovery is desired. +The only defined capability for now is `mix`, representing [Waku Mix](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/mix.md) support. +For example, a Waku peer record for a node supporting mix protocol in cluster `1` will be registered against a namespace: `rs/1/mix`. + +This allows for discovering peers with specific capabilities within a given cluster. +Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. + +Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/relay-sharding.md) for cluster information. + +### Registration and Discovery + +Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. +The RECOMMENDED registration interval is 10 seconds. -We RECOMMEND a registration interval of 10 seconds. -The node SHOULD register once for every shard it supports, -registering only the namespace corresponding to that shard. +All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. +All advertised records MUST conform to the `WakuPeerRecord` definition. -We RECOMMEND that rendezvous points expire registrations after 1 minute, -in order to keep discovered peer records to those recentrly online. +It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) +to keep discovered peer records limited to those recently online. -At startup, every Waku node SHOULD discover peers by -sending requests to random rendezvous points, -once for each shard it supports. +At startup, every Waku node supporting Mix SHOULD discover peers by +sending requests to random rendezvous points for the Mix capability namespace. -We RECOMMEND a maximum of 12 peers will be requested each time. -This number is enough for good GossipSub connectivity and -minimize the load on rendezvous points. +It is RECOMMENDED a maximum of 12 peers be requested each time. +This number is sufficient for good GossipSub connectivity and +minimizes the load on rendezvous points. -We RECOMMEND that bootstrap nodes participate in rendezvous discovery and -that other discovery methods are used in conjunction and +### Operational Recommendations + +It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and +that other discovery methods are used in conjunction and continue discovering peers for the lifetime of the local node. +For resource-constrained devices or light clients, a client-only mode MAY be used +where nodes only query for peers without acting as rendezvous points themselves +and without advertising their own peer records. + ## Future Work -Namespaces will not contain capabilities yet but may in the future. If the need arise nodes could use rendezvous to discover peers with specific capabilities. +The protocol currently supports advertising Mix-specific capabilities (Mix public keys) through `WakuPeerRecord`. +Future enhancements could include: + +- Extending `WakuPeerRecord` to advertise other Waku protocol capabilities (Relay, Store, Filter, Lightpush, etc.) +- Supporting shard-based namespaces (e.g., `rs//`) for general relay peer discovery without capability filtering +- Batch registration support allowing nodes to register across multiple namespaces in a single request # Copyright @@ -68,7 +123,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). # References - - [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) - - [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract) - - [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) - - [Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) + +- [Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) +- [ENR](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/enr.md) +- [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract) +- [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) +- [Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md)