From e42629eb9c85246255248c33d1cd8ab38a8a1d1a Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 1 Oct 2025 22:20:24 +1000 Subject: [PATCH 01/28] Rename Waku API's "Waku Config" to "Protocols" Config Make it clearer that with this config, we are configuring the Waku protocols, in contrast to other parameters which are more executable related. Related to https://github.com/waku-org/nwaku/issues/3493 --- standards/application/waku-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 6cfceb5..03d4bf6 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -127,8 +127,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 @@ -137,7 +137,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: @@ -237,7 +237,7 @@ 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 From 55dfcf950ac01cba1e21c7d2d073991e54cfd552 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 7 Oct 2025 00:42:32 +0200 Subject: [PATCH 02/28] add Send API --- standards/application/waku-api.md | 51 +++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 03d4bf6..38096dc 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -302,6 +302,57 @@ 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. +## Send messages + +#### Type definitions + +```yaml +types: + SendMessage: + type: object + fields: + contentTopic: + type: string + description: "The content topic for the message." + payload: + type: Uint8Array + description: "The message payload as bytes." + ephemeral: + type: bool + default: false + description: "Whether the message is ephemeral." + rateLimitProof: + type: Uint8Array + default: none + description: "Rate limiting proof as bytes" + + RequestId: + type: string + description: "A unique identifier for a request" +``` + +#### Function definitions + +```yaml +functions: + send: + description: "Send a message through the Waku network." + parameters: + - name: message + type: SendMessage + description: "The message to send" + returns: + type: result +``` + +#### Extended definitions + +When `message` is sent with `contentTopic` for a first time, +the node SHOULD trigger a subscription based on `Subscribe to messages` section. + +Additionally, the node SHOULD initiate recurring [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) queries +to validate if sent message was stored on the network and `static_store_nodes` SHOULD be prioritised. + ## 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. From a25e3b9d3ae25dedf9df888bc7983a7ef14950b1 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Wed, 8 Oct 2025 15:07:06 +0200 Subject: [PATCH 03/28] Update standards/application/waku-api.md Co-authored-by: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 38096dc..ad5b8b9 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -316,7 +316,7 @@ types: description: "The content topic for the message." payload: type: Uint8Array - description: "The message payload as bytes." + description: "The message data to be sent." ephemeral: type: bool default: false From 8387ada41cb9630fb96ed14e4b73972fc91470c0 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Wed, 8 Oct 2025 23:43:38 +0200 Subject: [PATCH 04/28] address comment --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index ad5b8b9..dba27b7 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -313,7 +313,7 @@ types: fields: contentTopic: type: string - description: "The content topic for the message." + 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: Uint8Array description: "The message data to be sent." From 79a96a6acf747d8bdf1bded5fcb991f65bcdd0f1 Mon Sep 17 00:00:00 2001 From: Sasha Date: Wed, 8 Oct 2025 23:49:54 +0200 Subject: [PATCH 05/28] address review --- standards/application/waku-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index ad5b8b9..baad5b7 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -69,7 +69,7 @@ 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. @@ -315,16 +315,16 @@ types: type: string description: "The content topic for the message." payload: - type: Uint8Array + type: array description: "The message data to be sent." ephemeral: type: bool default: false - description: "Whether the message is ephemeral." + 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)" rateLimitProof: - type: Uint8Array + type: array default: none - description: "Rate limiting proof as bytes" + description: "Rate limiting proof needed for [PUBLISHING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md#publishing)" RequestId: type: string @@ -336,7 +336,7 @@ types: ```yaml functions: send: - description: "Send a message through the Waku network." + description: "Send a message through the network." parameters: - name: message type: SendMessage From 681f38a388ff6fd8b310470b2e6dc7c34f8b2f83 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 21 Oct 2025 01:19:16 +0200 Subject: [PATCH 06/28] add EventSource and address comments --- standards/application/waku-api.md | 66 +++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 3d6fe83..406d32e 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -321,10 +321,6 @@ types: 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)" - rateLimitProof: - type: array - default: none - description: "Rate limiting proof needed for [PUBLISHING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md#publishing)" RequestId: type: string @@ -347,11 +343,67 @@ functions: #### Extended definitions -When `message` is sent with `contentTopic` for a first time, +When `message` is sent with `contentTopic` for the first time, the node SHOULD trigger a subscription based on `Subscribe to messages` section. -Additionally, the node SHOULD initiate recurring [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) queries -to validate if sent message was stored on the network and `static_store_nodes` SHOULD be prioritised. +The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery. + +## Event source + +#### Type definitions + +```yaml +types: + MessageSentEvent: + type: object + fields: + eventType: + type: string + default: "message:sent" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the sent message" + + MessageErrorEvent: + type: object + fields: + eventType: + type: string + default: "message:error" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the failed message" + error: + type: string + description: "Error message describing what went wrong" + + MessageAckEvent: + type: object + fields: + eventType: + type: string + default: "message:ack" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the acknowledged message" + ackType: + type: string + description: "Type of acknowledgment (e.g., 'store', 'filter')" + + EventSource: + type: object + description: "Event source for message-related events" + fields: + onEvent: + type: function + description: "Callback for message:sent events" + parameters: + - name: event + type: MessageSentEvent | MessageErrorEvent | MessageAckEvent +``` ## The Validation API From b68082cc7c04e8748b2ce5842cf6ee2f8962fb09 Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:17:09 +0200 Subject: [PATCH 07/28] address comments --- standards/application/waku-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 406d32e..63aafdb 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -379,19 +379,19 @@ types: type: string description: "Error message describing what went wrong" - MessageAckEvent: + MessagePropagatedEvent: type: object fields: eventType: type: string - default: "message:ack" + default: "message:propagated" description: "Event type identifier" requestId: type: RequestId - description: "The request ID associated with the acknowledged message" - ackType: + description: "The request ID associated with the propagated message in the network" + messageHash: type: string - description: "Type of acknowledgment (e.g., 'store', 'filter')" + description: "Hash of the message that got propagated within the network" EventSource: type: object From 36c3879a739bba68dab86f6f67b4629b1959eecb Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:41:31 +0200 Subject: [PATCH 08/28] chore: add health status --- standards/application/waku-api.md | 54 +++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 03d4bf6..9cc412c 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -30,6 +30,8 @@ contributors: * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) * [The Validation API](#the-validation-api) + * [Health Status](#health-status) + * [Event Source](#event-source) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -313,6 +315,58 @@ that would contain all validation parameters including RLN. In the time being, parameters specific to RLN are accepted for the message validation. RLN can also be disabled. +## Health Status + +#### Type definitions + +```yml +types: + HealthStatus: + type: enum + values: [Unhealthy, MinimallyHealthy, Healthy] + description: "Used to identify health of the operating node" +``` + +#### Extended definitions + +`Unhealthy` indicates that the node has lost connectivity for message reception, +sending, or both, and as a result, it cannot reliably process or transmit messages. + +`MinimallyHealthy` indicates that the node meets the minimum operational requirements, +although performance or reliability may be impacted. + +`Healthy` indicates that the node is operating optimally, +with full support for message processing and transmission. + +## Event source + +#### Type definitions + +```yaml +types: + HealthStatus: + type: object + fields: + eventType: + type: string + default: "health" + description: "Event type identifier" + status: + type: HealthStatus + description: "Node health status emitted on state change" + +EventSource: + type: object + description: "Event source for Waku API events" + fields: + onEvent: + type: function + description: "Callback for captured events" + parameters: + - name: event + type: HealthStatus +``` + ## Security/Privacy Considerations See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md). From ed2ffc151a3d0969bfd1acd469730c838afaf563 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Thu, 23 Oct 2025 00:44:30 +0200 Subject: [PATCH 09/28] use capital Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 9cc412c..7eaf329 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -338,7 +338,7 @@ although performance or reliability may be impacted. `Healthy` indicates that the node is operating optimally, with full support for message processing and transmission. -## Event source +## Event Source #### Type definitions From 88783f088d469a058eada785838c045ebeb0e18d Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:45:30 +0200 Subject: [PATCH 10/28] remove ambiguity --- standards/application/waku-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7eaf329..33cf149 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -344,7 +344,7 @@ with full support for message processing and transmission. ```yaml types: - HealthStatus: + HealthStatusEvent: type: object fields: eventType: @@ -364,7 +364,7 @@ EventSource: description: "Callback for captured events" parameters: - name: event - type: HealthStatus + type: HealthStatusEvent ``` ## Security/Privacy Considerations From 07e23fd791617218afcafe2a9d5e3aed37fc44da Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:46:25 +0200 Subject: [PATCH 11/28] fix type --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 63aafdb..15d0880 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -402,7 +402,7 @@ types: description: "Callback for message:sent events" parameters: - name: event - type: MessageSentEvent | MessageErrorEvent | MessageAckEvent + type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent ``` ## The Validation API From b957762ada12b8bc9856c0e4c72fae3de8a88b95 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Fri, 24 Oct 2025 01:48:17 +0200 Subject: [PATCH 12/28] up text Co-authored-by: fryorcraken <110212804+fryorcraken@users.noreply.github.com> --- standards/application/waku-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 33cf149..7f79533 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -332,7 +332,8 @@ types: `Unhealthy` indicates that the node has lost connectivity for message reception, sending, or both, and as a result, it cannot reliably process or transmit messages. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements, +`MinimallyHealthy` indicates that the node meets the minimum operational requirements: connect to at least one peer with a protocol to send messages ([LIGHT-PUSH]() or [RELAY]()) and one peer with a protocol to receive messages ([FILTER ] or [RELAY]) +and one peer with store service capabilities. although performance or reliability may be impacted. `Healthy` indicates that the node is operating optimally, From e7be2b49eb2620f69f5d785ea8fcad1434468e68 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 28 Oct 2025 01:27:38 +0100 Subject: [PATCH 13/28] address comments --- standards/application/waku-api.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 15d0880..79e4cef 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -308,7 +308,7 @@ whereas `core` SHOULD be used if node has no strong hardware or bandwidth restri ```yaml types: - SendMessage: + MessageEnvelope: type: object fields: contentTopic: @@ -335,16 +335,16 @@ functions: description: "Send a message through the network." parameters: - name: message - type: SendMessage - description: "The message to send" + type: MessageEnvelope + description: "Parameters for sending the message." returns: type: result ``` #### Extended definitions -When `message` is sent with `contentTopic` for the first time, -the node SHOULD trigger a subscription based on `Subscribe to messages` section. +A first `message` sent with a certain `contentTopic` +SHOULD trigger a subscription based on `Subscribe to messages` section for such `contentTopic`. The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery. @@ -364,6 +364,9 @@ types: requestId: type: RequestId description: "The request ID associated with the sent message" + messageHash: + type: string + description: "Hash of the message that got sent to the network" MessageErrorEvent: type: object @@ -375,6 +378,9 @@ types: requestId: type: RequestId description: "The request ID associated with the failed message" + messageHash: + type: string + description: "Optional property. Hash of the message that got error" error: type: string description: "Error message describing what went wrong" @@ -393,13 +399,13 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventSource: - type: object + EventEmitter: + type: event_emitter description: "Event source for message-related events" fields: - onEvent: + addEventListener: type: function - description: "Callback for message:sent events" + description: "Callback for subscribing to events" parameters: - name: event type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent From c20f692a1324395c9453799bd48fcd68da14f7f5 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Tue, 28 Oct 2025 01:36:46 +0100 Subject: [PATCH 14/28] Add property definitions section to waku-api.md Added property definitions for events in Waku API documentation. --- standards/application/waku-api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 79e4cef..b4bd522 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -224,6 +224,15 @@ functions: type: result ``` +#### Property definitions + +```yaml +properties: + events: + type: EventEmitter + description: "Event source for message-related events" +``` + #### Predefined values ```yaml From 78d0b9de668dfe0719084097d7dea95b470e71a3 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 28 Oct 2025 01:41:59 +0100 Subject: [PATCH 15/28] address comments --- standards/application/waku-api.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7f79533..2d5b889 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -330,14 +330,16 @@ types: #### Extended definitions `Unhealthy` indicates that the node has lost connectivity for message reception, -sending, or both, and as a result, it cannot reliably process or transmit messages. +sending, or both, and as a result, it cannot reliably receive or transmit messages. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements: connect to at least one peer with a protocol to send messages ([LIGHT-PUSH]() or [RELAY]()) and one peer with a protocol to receive messages ([FILTER ] or [RELAY]) -and one peer with store service capabilities. -although performance or reliability may be impacted. +`MinimallyHealthy` 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. `Healthy` indicates that the node is operating optimally, -with full support for message processing and transmission. +with full support for message reception and transmission. ## Event Source From 35dc6ac6d6730ce375cca2f1867fb8a7268904ff Mon Sep 17 00:00:00 2001 From: Sasha Date: Wed, 29 Oct 2025 22:22:45 +0100 Subject: [PATCH 16/28] use snake case --- standards/application/waku-api.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index b4bd522..f13aa66 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -320,7 +320,7 @@ types: MessageEnvelope: type: object fields: - contentTopic: + 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: @@ -366,28 +366,28 @@ types: MessageSentEvent: type: object fields: - eventType: + event_type: type: string default: "message:sent" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the sent message" - messageHash: + message_hash: type: string description: "Hash of the message that got sent to the network" MessageErrorEvent: type: object fields: - eventType: + event_type: type: string default: "message:error" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the failed message" - messageHash: + message_hash: type: string description: "Optional property. Hash of the message that got error" error: @@ -397,14 +397,14 @@ types: MessagePropagatedEvent: type: object fields: - eventType: + event_type: type: string default: "message:propagated" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the propagated message in the network" - messageHash: + message_hash: type: string description: "Hash of the message that got propagated within the network" From c61574b7beca06b7b3a717bf71091d2484443db3 Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 13 Nov 2025 00:43:11 +0100 Subject: [PATCH 17/28] add description to events --- standards/application/waku-api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index f13aa66..805ca91 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -365,6 +365,7 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat types: MessageSentEvent: type: object + description: "Event emitted when a message is sent to the network" fields: event_type: type: string @@ -379,6 +380,7 @@ types: MessageErrorEvent: type: object + description: "Event emitted when a message send operation fails" fields: event_type: type: string @@ -396,6 +398,7 @@ types: MessagePropagatedEvent: type: object + description: "Confirmation that a message has been correctly delivered to the network" fields: event_type: type: string From 11bc90ab309cccf8ee77876d39f5c049dc710e5d Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 13 Nov 2025 00:47:54 +0100 Subject: [PATCH 18/28] update event emitter syntax --- standards/application/waku-api.md | 30 +++++++++--------------------- 1 file changed, 9 insertions(+), 21 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 805ca91..042f888 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -361,16 +361,12 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat #### Type definitions -```yaml +```yml types: MessageSentEvent: type: object description: "Event emitted when a message is sent to the network" fields: - event_type: - type: string - default: "message:sent" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the sent message" @@ -382,10 +378,6 @@ types: type: object description: "Event emitted when a message send operation fails" fields: - event_type: - type: string - default: "message:error" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the failed message" @@ -400,10 +392,6 @@ types: type: object description: "Confirmation that a message has been correctly delivered to the network" fields: - event_type: - type: string - default: "message:propagated" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the propagated message in the network" @@ -411,16 +399,16 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventEmitter: + EventEventEmitter: type: event_emitter description: "Event source for message-related events" - fields: - addEventListener: - type: function - description: "Callback for subscribing to events" - parameters: - - name: event - type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent + events: + "message:sent": + type: MessageSentEvent + "message:error": + type: MessageErrorEvent + "message:propagated": + type: MessagePropagatedEvent ``` ## The Validation API From cfe7cddc381eb0d07ad4da79e4595e551ce34b66 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Thu, 13 Nov 2025 16:20:02 +1100 Subject: [PATCH 19/28] Some typos, improvements --- standards/application/waku-api.md | 40 ++++++++++++++++++------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 042f888..943a3b8 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,6 +29,12 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) + * [Send messages](#send-messages) + * [Type definitions](#type-definitions-1) + * [Function definitions](#function-definitions-1) + * [Extended definitions](#extended-definitions-1) + * [Event source](#event-source) + * [Type definitions](#type-definitions-2) * [The Validation API](#the-validation-api) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -39,10 +45,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 @@ -72,9 +78,10 @@ An alternative would be to choose a programming language. However, such choice m - 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 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. @@ -90,11 +97,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 @@ -118,6 +127,10 @@ types: WakuNode: type: object description: "A Waku node instance." + fields: + message_events: + type: MessageEvents + description: "Message related events." NodeConfig: type: object @@ -151,6 +164,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 @@ -201,10 +215,10 @@ 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" @@ -224,15 +238,6 @@ functions: type: result ``` -#### Property definitions - -```yaml -properties: - events: - type: EventEmitter - description: "Event source for message-related events" -``` - #### Predefined values ```yaml @@ -253,6 +258,7 @@ values: static_store_nodes: [] cluster_id: 1 auto_sharding_config: + type: AutoShardingConfig fields: num_shards_in_cluster: 8 message_validation: TheWakuNetworkMessageValidation @@ -262,6 +268,7 @@ values: fields: max_message_size: "150 KiB" rln_config: + type: RlnConfig fields: contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6" chain_id: 59141 @@ -300,7 +307,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) @@ -390,7 +396,7 @@ types: MessagePropagatedEvent: type: object - description: "Confirmation that a message has been correctly delivered to the network" + description: "Confirmation that a message has been correctly delivered to some neighbouring nodes." fields: request_id: type: RequestId @@ -399,7 +405,7 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventEventEmitter: + MessageEvents: type: event_emitter description: "Event source for message-related events" events: From 7aec995a0700d85783e90ac1bb44ad76917a5d05 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Wed, 29 Oct 2025 17:21:40 +0530 Subject: [PATCH 20/28] update rendezvous for mix node discovery --- standards/core/rendezvous.md | 99 ++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 6a42abd..d435ac6 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -1,66 +1,97 @@ --- 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 + +Waku nodes need a discovery mechanism that is both rapid and robust against attacks. Rendezvous enables quick identification of relevant peers, complementing slower but more resilient approaches like Discv5. For healthy network participation, nodes must connect to a diverse set of peers. However, the rendezvous protocol is vulnerable to denial of service attacks and depends on centralized rendezvous points, so it is best used in conjunction with other discovery methods such as Discv5. + +Ethereum Node Record (ENR) size constraints make it impractical to encode additional metadata, such as Mix public keys, in ENRs for Discv5-based discovery. Rendezvous, using a custom peer record (`WakuPeerRecord`), allows nodes to advertise Mix-specific information—including the Mix public key—without being restricted by ENR size. This serves as an interim solution until a comprehensive capability discovery mechanism is available. + +By combining rendezvous 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 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/master/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`. + +**Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` + +### Namespace Format + +The namespaces used to register and request MUST be in the format `rs//`. + +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/master/standards/core/relay-sharding.md) for cluster and shard information. +### Registration and Discovery + 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. Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. +Nodes supporting the Mix protocol MUST advertise their `WakuPeerRecord`, which includes their multiaddresses, supported protocols, and Mix public key. -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. +We RECOMMEND a registration interval of 10 seconds. -We RECOMMEND that rendezvous points expire registrations after 1 minute, -in order to keep discovered peer records to those recentrly online. +We RECOMMEND 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. +We RECOMMEND a maximum of 12 peers be requested each time. +This number is sufficient for good GossipSub connectivity and +minimizes the load on rendezvous points. + +### Peer Records + +Nodes advertise their information through `WakuPeerRecord`, which includes: + +- Multiaddresses for connectivity +- Supported protocol codecs +- Mix protocol public key (for nodes supporting the Mix protocol) + +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. + +### Operational Recommendations We RECOMMEND that bootstrap nodes participate in rendezvous discovery and -that other discovery methods are used in conjunction 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 +99,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/master/discv5/discv5.md#node-discovery-protocol-v5) +- [ENR](https://github.com/ethereum/devp2p/blob/master/enr.md) +- [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) From cd9a10cff1d995b63e7d2191bf6c917786ef3f58 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Wed, 29 Oct 2025 17:29:47 +0530 Subject: [PATCH 21/28] address review comments --- standards/core/rendezvous.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index d435ac6..bd999ce 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -41,7 +41,7 @@ The namespaces used to register and request MUST be in the format `rs/ Date: Thu, 30 Oct 2025 09:59:51 +0530 Subject: [PATCH 22/28] address review comments --- standards/core/rendezvous.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index bd999ce..422444e 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -50,23 +50,24 @@ Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/ Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. -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. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` specification. +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. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` definition. -We RECOMMEND a registration interval of 10 seconds. +The RECOMMENDED registration interval is 10 seconds. -We RECOMMEND that rendezvous points expire registrations after 1 minute (60 seconds TTL) +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 supporting Mix SHOULD discover peers by sending requests to random rendezvous points for the Mix capability namespace. -We RECOMMEND a maximum of 12 peers be requested each time. +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. ### Peer Records -Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. The specification for `WakuPeerRecord` is as follows: +Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** @@ -93,7 +94,7 @@ When a node discovers peers through rendezvous, it receives the complete `WakuPe ### Operational Recommendations -We RECOMMEND that bootstrap nodes participate in rendezvous discovery and +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. From 234249dc1d1b804fdf6aae1d8b417f6bd624d340 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Fri, 31 Oct 2025 18:26:53 +0530 Subject: [PATCH 23/28] aligning with implementation --- standards/core/rendezvous.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 422444e..b5999a3 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -67,15 +67,15 @@ minimizes the load on rendezvous points. ### Peer Records Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +Since this is a customPeerRecord, it uses a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/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. -- `protocols`: A list of supported protocol codecs (e.g., `/vac/waku/mix/1.0.0`). - `mix_public_key`: The Mix protocol public key (only present for nodes supporting Mix). -- `timestamp`: The time at which the record was created or last updated (Unix epoch, seconds). **Encoding:** WakuPeerRecord is encoded as a protobuf message. The exact schema is: @@ -83,10 +83,9 @@ WakuPeerRecord is encoded as a protobuf message. The exact schema is: ```protobuf message WakuPeerRecord { string peer_id = 1; - repeated string multiaddrs = 2; - repeated string protocols = 3; + uint64 seqNo = 2; + repeated string multiaddrs = 3; optional bytes mix_public_key = 4; - uint64 timestamp = 5; } ``` From 29322c5c01268e7789d9fd0dedf5cf573d1a5103 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Mon, 3 Nov 2025 03:13:29 +0530 Subject: [PATCH 24/28] address review comments --- standards/core/rendezvous.md | 77 ++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index b5999a3..7b8af58 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -15,9 +15,11 @@ It supplements Discovery v5 and Waku peer exchange. ## Background and Rationale -Waku nodes need a discovery mechanism that is both rapid and robust against attacks. Rendezvous enables quick identification of relevant peers, complementing slower but more resilient approaches like Discv5. For healthy network participation, nodes must connect to a diverse set of peers. However, the rendezvous protocol is vulnerable to denial of service attacks and depends on centralized rendezvous points, so it is best used in conjunction with other discovery methods such as Discv5. - -Ethereum Node Record (ENR) size constraints make it impractical to encode additional metadata, such as Mix public keys, in ENRs for Discv5-based discovery. Rendezvous, using a custom peer record (`WakuPeerRecord`), allows nodes to advertise Mix-specific information—including the Mix public key—without being restricted by ENR size. This serves as an interim solution until a comprehensive capability discovery mechanism is available. +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/master/discv5/discv5.md#node-discovery-protocol-v5) and @@ -34,40 +36,10 @@ This allows nodes to advertise additional Waku-specific metadata beyond what is **Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` -### Namespace Format - -The namespaces used to register and request MUST be in the format `rs//`. - -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/master/standards/core/relay-sharding.md) for cluster information. - -### Registration and Discovery - -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. - -Each relay node that participates in discovery -MUST register with random rendezvous points at regular intervals. - -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. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` definition. - -The RECOMMENDED registration interval is 10 seconds. - -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 supporting Mix SHOULD discover peers by -sending requests to random rendezvous points for the Mix capability namespace. - -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. - -### Peer Records +### Wire Protocol Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. -Since this is a customPeerRecord, it uses a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). +Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** @@ -91,6 +63,41 @@ message WakuPeerRecord { 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/master/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/master/standards/core/relay-sharding.md) for cluster information. + +### Registration and Discovery + +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. + +Each relay node that participates in discovery +MUST register with random rendezvous points at regular intervals. +The RECOMMENDED registration interval is 10 seconds. + +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. + +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 supporting Mix SHOULD discover peers by +sending requests to random rendezvous points for the Mix capability namespace. + +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. + ### Operational Recommendations It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and From ce9deda4500e1bc926d1afbbe0642d6bd018c79d Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Tue, 18 Nov 2025 16:42:58 +0530 Subject: [PATCH 25/28] update links with permalinks --- standards/core/rendezvous.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 7b8af58..292be4c 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -22,14 +22,14 @@ Rendezvous provides a limited, balanced solution that trades off some robustness It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5 By combining rendezvous 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), +[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 extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. +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 @@ -39,7 +39,7 @@ This allows nodes to advertise additional Waku-specific metadata beyond what is ### 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/master/table.csv). +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:** @@ -69,17 +69,17 @@ The [rendezvous namespaces](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d 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/master/standards/core/mix.md) support. +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/master/standards/core/relay-sharding.md) for cluster information. +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/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. +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. @@ -124,8 +124,8 @@ Copyright and related rights waived via # References -- [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) -- [ENR](https://github.com/ethereum/devp2p/blob/master/enr.md) -- [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) From fdcfcca3b58011c6fdc2ab8876c8bfb40430976b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 21 Nov 2025 11:41:50 -0300 Subject: [PATCH 26/28] add Waku API to readme --- README.md | 1 + 1 file changed, 1 insertion(+) 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 From a2584bf8c25093450ff2dea6a1a3e1c6a3bec946 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Mon, 26 Jan 2026 15:27:14 -0300 Subject: [PATCH 27/28] rename health status to connection status --- standards/application/waku-api.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 2d5b889..3cb9a45 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -30,7 +30,7 @@ contributors: * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) * [The Validation API](#the-validation-api) - * [Health Status](#health-status) + * [Connection Status](#connection-status) * [Event Source](#event-source) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -315,30 +315,30 @@ that would contain all validation parameters including RLN. In the time being, parameters specific to RLN are accepted for the message validation. RLN can also be disabled. -## Health Status +## Connection Status #### Type definitions ```yml types: - HealthStatus: + ConnectionStatus: type: enum - values: [Unhealthy, MinimallyHealthy, Healthy] + values: [Disconnected, PartiallyConnected, Connected] description: "Used to identify health of the operating node" ``` #### Extended definitions -`Unhealthy` indicates that the node has lost connectivity for message reception, +`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. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements: +`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. -`Healthy` indicates that the node is operating optimally, +`Connected` indicates that the node is operating optimally, with full support for message reception and transmission. ## Event Source @@ -347,7 +347,7 @@ with full support for message reception and transmission. ```yaml types: - HealthStatusEvent: + ConnectionStatusEvent: type: object fields: eventType: @@ -355,8 +355,8 @@ types: default: "health" description: "Event type identifier" status: - type: HealthStatus - description: "Node health status emitted on state change" + type: ConnectionStatus + description: "Node connection status emitted on state change" EventSource: type: object @@ -367,7 +367,7 @@ EventSource: description: "Callback for captured events" parameters: - name: event - type: HealthStatusEvent + type: ConnectionStatusEvent ``` ## Security/Privacy Considerations From 21b8c471fb37300cfb70046e6c39e4d4c964d82c Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Fri, 30 Jan 2026 10:50:12 -0300 Subject: [PATCH 28/28] bless spell-checking failures into .wordslist.txt --- .wordlist.txt | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) 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