logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-02-17 12:43:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into waku-api/subscribe

Browse Source
This commit is contained in:
Fabiana Cecin 2026-02-03 12:20:37 -03:00
commit 1c6ee9345d
No known key found for this signature in database
GPG Key ID: BCAB8A55CB51B6C7
4 changed files with 436 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
.wordlist.txt
View File

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

1
README.md
View File

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

330
standards/application/waku-api.md
View File

@ -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<T>` where `T` is the element type (e.g., `array<string>`, `array<byte>`).
- `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<string>
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<WakuNode, error>
```
#### 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<byte>
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<RequestId, error>
```
#### 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<void, error>
```
#### 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.

133
standards/core/rendezvous.md
View File

@ -1,66 +1,121 @@
---
title: WAKU-RENDEZVOUS
name: Waku Rendezvous discovery
editor: Simon-Pierre Vivier <simvivier@status.im>
contributors:
editor: Prem Chaitanya Prathi <premprathi@proton.me>
contributors: Simon-Pierre Vivier <simvivier@status.im>
---
## 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/<cluster-id>/<capability>`.
`<capability>` 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/<cluster-id>/<shard>`) 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)