From 55dfcf950ac01cba1e21c7d2d073991e54cfd552 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 7 Oct 2025 00:42:32 +0200 Subject: [PATCH 01/13] 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 02/13] 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 03/13] 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 04/13] 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 05/13] 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 06/13] 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 07e23fd791617218afcafe2a9d5e3aed37fc44da Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:46:25 +0200 Subject: [PATCH 07/13] 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 e7be2b49eb2620f69f5d785ea8fcad1434468e68 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 28 Oct 2025 01:27:38 +0100 Subject: [PATCH 08/13] 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 09/13] 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 35dc6ac6d6730ce375cca2f1867fb8a7268904ff Mon Sep 17 00:00:00 2001 From: Sasha Date: Wed, 29 Oct 2025 22:22:45 +0100 Subject: [PATCH 10/13] 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 11/13] 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 12/13] 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 13/13] 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: