From 02af71b11d7226f2c202c822c13e6d2073b219b6 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 3 Oct 2025 16:30:09 +1000 Subject: [PATCH 01/12] Introduce the Waku API's subscribe function --- standards/application/waku-api.md | 59 +++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 6cfceb5..741fc80 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,6 +29,11 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) + * [Subscribe to messages](#subscribe-to-messages) + * [Type definitions](#type-definitions-1) + * [Function definitions](#function-definitions-1) + * [Predefined values](#predefined-values-1) + * [Extended definitions](#extended-definitions-1) * [The Validation API](#the-validation-api) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -75,6 +80,7 @@ An alternative would be to choose a programming language. However, such choice m - `array`: iterable object containing values of all the same type. - `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. - Usage of `result` is RECOMMENDED, usage of exceptions is NOT RECOMMENDED, no matter the language. TODO: Review whether to specify categories of errors. @@ -302,6 +308,59 @@ 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. +### 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." +``` + +#### Function definitions + +```yaml +functions: + subscribe: + description: "Subscribe to specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to subscribe to." + returns: + type: result +``` + +#### Predefined values + +Extending `WakuNode`: + +```yaml +types: + WakuNode: + fields: + messageEmitter: + type: MessageEmitter + description: "Event emitter for received messages, keyed by content topic." +``` + +#### Extended definitions + +**`mode`**: + +If the `mode` set is `edge`, `subscribe` SHOULD trigger set up a subscription using [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as client and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). + +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. + ## 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 e8964ac3b4a52614df2c55942c4c6142845f579f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 13 Oct 2025 15:47:12 +1100 Subject: [PATCH 02/12] remove error return for `subscribe` --- standards/application/waku-api.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 741fc80..7771608 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -318,9 +318,12 @@ types: 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: + "message:*": 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." + description: "Event emitted when a message is received on the specified content topic. The event name is `message:` concatenated with the content topic string (e.g. `message:/supercrypto/1/notification/proto`, and the event payload is the raw message bytes." + "error:*": + type: string + description: "Event emitted when subscription irrevocably fails for specified content topic. The event name is `error:` concatenated with the content topic string (e.g. `error:/supercrypto/1/notification/proto`, and the event payload is a string describing the error." ``` #### Function definitions @@ -334,7 +337,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: result + type: void ``` #### Predefined values @@ -361,6 +364,19 @@ 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. +**`error`**: + +Only irrevocable failures should lead to emitting a subscription error. +Failure to reach nodes can be omitted, and should be handled via the health (todo) events; +[P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. + +Examples of irrevocable failures are: + +- Invalid content topic format +- Exceeding number of content topics +- Node not started +- Other node-level configuration issue + ## 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 2de310e56d2d7e5031c817cc00d9463a94838a85 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 13 Oct 2025 16:33:08 +1100 Subject: [PATCH 03/12] fix error emission --- standards/application/waku-api.md | 63 +++++++++++++++++++------------ 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7771608..b1494be 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,8 +29,10 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) - * [Subscribe to messages](#subscribe-to-messages) + * [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) @@ -308,6 +310,27 @@ 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 + +#### 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." + # Extending `WakuNode` definition + WakuNode: + fields: + events: + type: EventEmitter + description: "Event emitter for Waku node." +``` + ### Subscribe to messages #### Type definitions @@ -315,15 +338,18 @@ whereas `core` SHOULD be used if node has no strong hardware or bandwidth restri ```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: - "message:*": - type: bytes - description: "Event emitted when a message is received on the specified content topic. The event name is `message:` concatenated with the content topic string (e.g. `message:/supercrypto/1/notification/proto`, and the event payload is the raw message bytes." - "error:*": - type: string - description: "Event emitted when subscription irrevocably fails for specified content topic. The event name is `error:` concatenated with the content topic string (e.g. `error:/supercrypto/1/notification/proto`, and the event payload is a string describing the error." + 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 @@ -342,17 +368,6 @@ functions: #### Predefined values -Extending `WakuNode`: - -```yaml -types: - WakuNode: - fields: - messageEmitter: - type: MessageEmitter - description: "Event emitter for received messages, keyed by content topic." -``` - #### Extended definitions **`mode`**: @@ -366,11 +381,11 @@ Only messages on subscribed content topics SHOULD be emitted by `messageEmitter` **`error`**: -Only irrevocable failures should lead to emitting a subscription error. -Failure to reach nodes can be omitted, and should be handled via the health (todo) events; +Only irremediable failures should lead to emitting a `"error:subscribe"`. +Failure to reach nodes can be omitted, and should be handled via the health (TODO) events; [P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. -Examples of irrevocable failures are: +Examples of irremediable failures are: - Invalid content topic format - Exceeding number of content topics From 92dc20de9fdd38c8b4ad1984fd96a056954459aa Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 09:14:29 -0300 Subject: [PATCH 04/12] add unsubscribe --- standards/application/waku-api.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index b1494be..d75479f 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -323,6 +323,9 @@ types: "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: fields: @@ -364,6 +367,14 @@ functions: description: "The content topics for the node to subscribe to." returns: type: void + unsubscribe: + description: "Unsubscribe from specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to unsubscribe from." + returns: + type: void ``` #### Predefined values @@ -382,9 +393,11 @@ Only messages on subscribed content topics SHOULD be emitted by `messageEmitter` **`error`**: Only irremediable failures should lead to emitting a `"error:subscribe"`. -Failure to reach nodes can be omitted, and should be handled via the health (TODO) events; +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 From 6792b0113c519d36ff50c0f5d4b245b1176a02ef Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 13:50:57 -0300 Subject: [PATCH 05/12] bless spellchecking failures --- .wordlist.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 3764e71..306b9c5 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -12,6 +12,7 @@ config ConnectionStatus ConnectionStatusEvent contentTopic +contentTopics createNode creativecommons danielkaiser @@ -38,11 +39,15 @@ github GITHUB gossipsub GossipSub +HealthConnectionStatusEvent +healthEvents +HealthEvents https iana IANA IDL implementor +Init ipv iterable KiB @@ -54,7 +59,11 @@ md MessageEnvelope MessageErrorEvent MessageEvents +messageEvents MessagePropagatedEvent +MessageReceivedEvent +MessageSendErrorEvent +MessageSendPropagatedEvent MessageSentEvent MessageValidation multiaddr @@ -86,6 +95,9 @@ rpc SHARDING sharding subnets +SubscriptionErrorEvent +subscriptionEvents +SubscriptionEvents TBD tcp TCP From 75bcb711d55411b10eba7c4d4497baffef923afb Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:09:48 -0300 Subject: [PATCH 06/12] add SubscribeAction enum instead of bool sub/unsub field to error --- standards/application/waku-api.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 3033d42..6e9c32e 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -456,6 +456,11 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat ```yaml types: + SubscribeAction: + type: enum + values: [Subscribe, Unsubscribe] + description: "Defines the subscription action that was performed" + SubscriptionErrorEvent: type: object description: "Event emitted when a content topic subscription-related operation fails" @@ -463,9 +468,9 @@ types: 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" + action: + type: SubscribeAction + description: "Defines the subscription action that was attempted" error: type: string description: "Error message describing what went wrong" From aa27f464c2a4bb3cf2854f0a44dcf19ab14b6fb3 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:10:28 -0300 Subject: [PATCH 07/12] 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 6e9c32e..16cbbbd 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -495,7 +495,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: void + type: result unsubscribe: description: "Unsubscribe from specific content topics" From 71e26dd1ee13fc6395a5a17a7cbaced2564ed552 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:12:49 -0300 Subject: [PATCH 08/12] Use distinct ContentTopic string type 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 16cbbbd..5dc17a8 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -501,7 +501,7 @@ functions: description: "Unsubscribe from specific content topics" parameters: - name: contentTopics - type: Array + type: Array description: "The content topics for the node to unsubscribe from." returns: type: void From 198501b8d8fdf52cc46a50ac24ceafeeec824d80 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:18:08 -0300 Subject: [PATCH 09/12] Remove confusing "binary" qualifier from checkApiAvailability desc 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 5dc17a8..426f538 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -567,7 +567,7 @@ types: functions: check-api-availability: - description: "Get current binary connectivity status" + description: "Get current connectivity status" parameters: - name: waku type: WakuNode From bba2661f30fcff5c72024bd058758c07753b3c8d Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:24:54 -0300 Subject: [PATCH 10/12] bless `SubscribeAction` spellcheck failure --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index 306b9c5..c22e798 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -95,6 +95,7 @@ rpc SHARDING sharding subnets +SubscribeAction SubscriptionErrorEvent subscriptionEvents SubscriptionEvents From 42d860d385b563fbaebe79b4070776454a976a2b Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Wed, 4 Feb 2026 08:14:16 -0300 Subject: [PATCH 11/12] Fixes from Ivan's review * Use sync impl awareness for subscription proc sync results * Delete subscription event source (for now) * Remove checkApiAvailability --- standards/application/waku-api.md | 32 +++++-------------------------- 1 file changed, 5 insertions(+), 27 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 426f538..fa8d93c 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -144,9 +144,6 @@ types: 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" @@ -456,21 +453,13 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat ```yaml types: - SubscribeAction: - type: enum - values: [Subscribe, Unsubscribe] - description: "Defines the subscription action that was performed" - - SubscriptionErrorEvent: + SubscriptionError: type: object - description: "Event emitted when a content topic subscription-related operation fails" + description: "A content topic subscription-related operation failed synchronously and irremediably" fields: content-topic: type: string description: "Content topic that the node failed to subscribe to or unsubscribe from" - action: - type: SubscribeAction - description: "Defines the subscription action that was attempted" error: type: string description: "Error message describing what went wrong" @@ -495,7 +484,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: result + type: result> unsubscribe: description: "Unsubscribe from specific content topics" @@ -504,7 +493,7 @@ functions: type: Array description: "The content topics for the node to unsubscribe from." returns: - type: void + type: result> ``` #### Subscriptions extended definitions @@ -563,18 +552,7 @@ types: #### Health function definitions -```yml -functions: - - check-api-availability: - description: "Get current connectivity status" - parameters: - - name: waku - type: WakuNode - description: "The node to check for a binary connectivity status." - returns: - type: result -``` +TODO #### Health extended definitions From aeddb7f9e7a640ec522463a15cb50fe9cd508b1a Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Wed, 4 Feb 2026 08:28:57 -0300 Subject: [PATCH 12/12] Remove dead IDL code, fix sync subscr error text, fix wordslist --- .wordlist.txt | 5 +---- standards/application/waku-api.md | 9 +-------- 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index c22e798..3d89df4 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -95,10 +95,7 @@ rpc SHARDING sharding subnets -SubscribeAction -SubscriptionErrorEvent -subscriptionEvents -SubscriptionEvents +SubscriptionError TBD tcp TCP diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index fa8d93c..fe633ff 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -463,13 +463,6 @@ types: 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 @@ -509,7 +502,7 @@ Only messages on subscribed content topics SHOULD be emitted by a `MessageEvents **`error`**: -Only irremediable failures should lead to emitting a `"subscription:error"` for failed subscribe or unsubscribe operations. +Only irremediable failures should lead to synchronously returning 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.