Merge pull request #87 from waku-org/weboko/waku-send-api

Add Send API to Waku API
2026-01-02 14:13:06 +00:00 · 2025-11-13 16:22:02 +11:00 · 2025-11-13 16:22:02 +11:00 · fe5cfdf823
commit fe5cfdf823
parent 68bd15734a cfe7cddc38
1 changed files with 122 additions and 7 deletions
--- 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

@ -69,12 +75,13 @@ An alternative would be to choose a programming language. However, such choice m
 ### Primitive types and general guidelines

 - No `default` means that the value is mandatory, meaning a `default` value implies an optional parameter.
- Primitive types are `string`, `int`, `bool`, `enum` and `uint`
+- Primitive types are `string`, `int`, `bool`, `byte`, `enum` and `uint`
 - Complex pre-defined types are:
  - `object`: object and other nested types.
-  - `array`: iterable object containing values of all the same type.
+  - `array`: iterable object containing values of all the same type. Syntax: `array<T>` where `T` is the element type (e.g., `array<string>`, `array<byte>`).
  - `result`: an enum type that either contains a value or void (success), or an error (failure); The error is left to the implementor.
  - `error`: Left to the implementor on whether `error` types are `string` or `object` in the given language.
+  - `event_emitter`: an object that 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"
@ -244,6 +258,7 @@ values:
      static_store_nodes: []
      cluster_id: 1
      auto_sharding_config:
+        type: AutoShardingConfig
        fields:
          num_shards_in_cluster: 8
      message_validation: TheWakuNetworkMessageValidation
@ -253,6 +268,7 @@ values:
    fields:
      max_message_size: "150 KiB"
      rln_config:
+        type: RlnConfig
        fields:
          contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6"
          chain_id: 59141
@ -291,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)
@ -302,6 +317,106 @@ 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:
+  MessageEnvelope:
+    type: object
+    fields:
+      content_topic:
+        type: string
+        description: "Content-based filtering field as defined in [TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics)"
+      payload:
+        type: array<byte>
+        description: "The message data to be sent."
+      ephemeral:
+        type: bool
+        default: false
+        description: "Whether the message is ephemeral. Read at [ATTRIBUTES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md#message-attributes)"
+
+  RequestId:
+    type: string
+    description: "A unique identifier for a request"
+```
+
+#### Function definitions
+
+```yaml
+functions:
+  send:
+    description: "Send a message through the network."
+    parameters:
+      - name: message
+        type: MessageEnvelope
+        description: "Parameters for sending the message."
+    returns:
+      type: result<RequestId, error>
+```
+
+#### Extended definitions
+
+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.
+
+## Event source
+
+#### Type definitions
+
+```yml
+types:
+  MessageSentEvent:
+    type: object
+    description: "Event emitted when a message is sent to the network"
+    fields:
+      request_id:
+        type: RequestId
+        description: "The request ID associated with the sent message"
+      message_hash:
+        type: string
+        description: "Hash of the message that got sent to the network"
+
+  MessageErrorEvent:
+    type: object
+    description: "Event emitted when a message send operation fails"
+    fields:
+      request_id:
+        type: RequestId
+        description: "The request ID associated with the failed message"
+      message_hash:
+        type: string
+        description: "Optional property. Hash of the message that got error"
+      error:
+        type: string
+        description: "Error message describing what went wrong"
+
+  MessagePropagatedEvent:
+    type: object
+    description: "Confirmation that a message has been correctly delivered to some neighbouring nodes."
+    fields:
+      request_id:
+        type: RequestId
+        description: "The request ID associated with the propagated message in the network"
+      message_hash:
+        type: string
+        description: "Hash of the message that got propagated within the network"
+
+  MessageEvents:
+    type: event_emitter
+    description: "Event source for message-related events"
+    events:
+      "message:sent":
+        type: MessageSentEvent
+      "message:error":
+        type: MessageErrorEvent
+      "message:propagated":
+        type: MessagePropagatedEvent
+```
+
 ## 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.