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

Add Send API to Waku API

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.