Update and rename BINDINGS-API.md to bindings-api.md

2026-01-09 15:48:03 -05:00 · 2024-02-01 22:12:53 -05:00
parent 38d68cef7f
commit e9469d0a5a
1 changed files with 59 additions and 57 deletions
--- a/waku/standards/core/36/bindings-api.md
+++ b/waku/standards/core/36/bindings-api.md
@@ -9,7 +9,7 @@ contributors:
 - Franck Royer <franck@status.im>
 ---

-# Introduction
+## Introduction

 Native applications that wish to integrate Waku may not be able to use nwaku and its JSON RPC API due to constraints
 on packaging, performance or executables.
@@ -19,7 +19,7 @@ An alternative is to link existing Waku implementation as a static or dynamic li
 This specification describes the C API that SHOULD be implemented by native Waku library and that SHOULD be used to
 consume them.

-# Design requirements
+## Design requirements

 The API should be generic enough, so:

@@ -31,11 +31,11 @@ The selected format to pass data to and from the API is `JSON`.
 It has been selected due to its widespread usage and easiness of use. Other alternatives MAY replace it in the future (C
 structure, protobuf) if it brings limitations that need to be lifted.

-# The API
+## The API

-## General
+### General

-### `JsonResponse` type
+#### `JsonResponse` type

 All the API functions return a `JsonResponse` unless specified otherwise. The returned `JsonResponse` is a `char *` whose format depends on whether the function was executed successfully or not. And it is important to notice that this returned `JsonReponse` is returned from the latest argument, instead of from the actual function's returned value.

@@ -65,7 +65,7 @@ On success:

 The type of the `result` object depends on the function it was returned by. 

-### `JsonMessage` type
+#### `JsonMessage` type

 A Waku Message in JSON Format:

@@ -85,7 +85,7 @@ Fields:
 - `version`: The Waku Message version number.
 - `timestamp`: Unix timestamp in nanoseconds.

-### `DecodedPayload` type
+#### `DecodedPayload` type

 A payload once decoded, used when a received Waku Message is encrypted:

@@ -105,7 +105,7 @@ Fields:
 - `data`: Decrypted message payload base64 encoded,
 - `padding`: Padding base64 encoded.

-### `FilterSubscription` type
+#### `FilterSubscription` type

 The criteria to create subscription to a light node in JSON Format:

@@ -122,7 +122,7 @@ Fields:
 - `topic`: Optional pubsub topic.


-### `ContentFilter` type
+#### `ContentFilter` type

 ```ts
 {
@@ -134,7 +134,7 @@ Fields:

 - `contentTopic`: The content topic of a Waku message.

-### `StoreQuery` type
+#### `StoreQuery` type

 Criteria used to retrieve historical messages

@@ -156,7 +156,7 @@ Fields:
 - `endTime`: The inclusive upper bound on the timestamp of queried messages. This field holds the Unix epoch time in nanoseconds.
 - `pagingOptions`: Paging information in [`PagingOptions`](#pagingoptions-type) format.

-### `StoreResponse` type
+#### `StoreResponse` type

 The response received after doing a query to a store node:

@@ -171,7 +171,7 @@ Fields:
 - `messages`: Array of retrieved historical messages in [`JsonMessage`](#jsonmessage-type) format.
 - `pagingOption`: Paging information in [`PagingOptions`](#pagingoptions-type) format from which to resume further historical queries

-### `PagingOptions` type
+#### `PagingOptions` type

 ```ts
 interface PagingOptions {
@@ -204,13 +204,13 @@ Fields:
 - `senderTime`: UNIX timestamp in nanoseconds at which the message is generated by its sender.
 - `pubsubTopic`: The pubsub topic of the message at this [`Index`](#index-type).

-## Events
+### Events

 Asynchronous events require a callback to be registered.
 An example of an asynchronous event that might be emitted is receiving a message.
 When an event is emitted, this callback will be triggered receiving a JSON string of type `JsonSignal`.

-### `JsonSignal` type
+#### `JsonSignal` type

 ```ts
 {
@@ -247,7 +247,7 @@ For example:
 |:----------|--------------------|
 | `message` | `JsonMessageEvent` | 

-### `JsonMessageEvent` type
+#### `JsonMessageEvent` type

 Type of `event` field for a `message` event:

@@ -263,7 +263,7 @@ Type of `event` field for a `message` event:
 - `messageId`: The message id.
 - `wakuMessage`: The message in [`JsonMessage`](#jsonmessage-type) format.

-### `extern void waku_set_event_callback(void* cb)`
+#### `extern void waku_set_event_callback(void* cb)`

 Register callback to act as event handler and receive application signals,
 which are used to react to asynchronous events in Waku.
@@ -273,9 +273,9 @@ which are used to react to asynchronous events in Waku.
 1. `void* cb`: callback that will be executed when an async event is emitted.
  The function signature for the callback should be `void myCallback(char* jsonSignal)`

-## Node management
+### Node management

-### `JsonConfig` type
+#### `JsonConfig` type

 Type holding a node configuration:

@@ -356,7 +356,7 @@ For example:
 ```


-### `GossipsubParameters` type
+#### `GossipsubParameters` type

 Type holding custom gossipsub configuration:

@@ -457,7 +457,7 @@ If a key is `undefined`, or `null`, a default value will be set.
 - `seenMessagesTTLSeconds`: configures when a previously seen message ID can be forgotten about.
  Default `120` seconds

-### `extern unsigned int waku_new(char* jsonConfig, char* jsonResp)`
+#### `extern unsigned int waku_new(char* jsonConfig, char* jsonResp)`

 Instantiates a Waku node.

@@ -491,7 +491,7 @@ Unsigned int. Possible values:



-### `extern unsigned int waku_start(char* jsonResp)`
+#### `extern unsigned int waku_start(char* jsonResp)`

 Starts a Waku node mounting all the protocols that were enabled during the Waku node instantiation.

@@ -512,7 +512,7 @@ Unsigned int. Possible values:
   - 1 - The operation was completed successfuly.
   - 0 - The operation failed for any reason. It worth checking the value of `jsonResp` in this case.

-### `extern unsigned int waku_stop(char* jsonResp)`
+#### `extern unsigned int waku_stop(char* jsonResp)`

 Stops a Waku node.

@@ -533,7 +533,7 @@ Unsigned int. Possible values:
   - 1 - The operation was completed successfuly.
   - 0 - The operation failed for any reason. It worth checking the value of `jsonResp` in this case.

-### `extern char* waku_peerid()`
+#### `extern char* waku_peerid()`

 Get the peer ID of the waku node.

@@ -550,7 +550,7 @@ For example:
 }
 ```

-### `extern char* waku_listen_addresses()`
+#### `extern char* waku_listen_addresses()`

 Get the multiaddresses the Waku node is listening to.

@@ -572,9 +572,9 @@ For example:
 }
 ```

-## Connecting to peers
+### Connecting to peers

-### `extern char* waku_add_peer(char* address, char* protocolId)`
+#### `extern char* waku_add_peer(char* address, char* protocolId)`

 Add a node multiaddress and protocol to the waku node's peerstore.

@@ -596,7 +596,7 @@ For example:
 }
 ```

-### `extern unsigned int waku_connect(char* address, int timeoutMs, char* jsonResp)`
+#### `extern unsigned int waku_connect(char* address, int timeoutMs, char* jsonResp)`

 Dial peer using a multiaddress.

@@ -632,7 +632,7 @@ Unsigned int. Possible values:
   - 0 - The operation failed for any reason. It worth checking the value of `jsonResp` in this case.


-### `extern char* waku_connect_peerid(char* peerId, int timeoutMs)`
+#### `extern char* waku_connect_peerid(char* peerId, int timeoutMs)`

 Dial peer using its peer ID.

@@ -660,7 +660,7 @@ For example:
 }
 ```

-### `extern char* waku_disconnect(char* peerId)`
+#### `extern char* waku_disconnect(char* peerId)`

 Disconnect a peer using its peerID

@@ -681,7 +681,7 @@ For example:
 }
 ```

-### `extern char* waku_peer_count()`
+#### `extern char* waku_peer_count()`

 Get number of connected peers.

@@ -698,7 +698,7 @@ For example:
 }
 ```

-### `extern char* waku_peers()`
+#### `extern char* waku_peers()`

 Retrieve the list of peers known by the Waku node.

@@ -726,11 +726,11 @@ The list of peers has this format:
 }
 ```

-## Waku Relay
+### Waku Relay

-### `extern void waku_content_topic(char* applicationName, unsigned int applicationVersion, char* contentTopicName, char* encoding, char* outContentTopic)`
+#### `extern void waku_content_topic(char* applicationName, unsigned int applicationVersion, char* contentTopicName, char* encoding, char* outContentTopic)`

-Create a content topic string according to [RFC 23](https://rfc.vac.dev/spec/23/).
+Create a content topic string according to [23/WAKU2-TOPICS](../../../informational/23/topics.md).

 **Parameters**

@@ -738,42 +738,42 @@ Create a content topic string according to [RFC 23](https://rfc.vac.dev/spec/23/
 2. **[input]** `unsigned int applicationVersion`
 3. **[input]** `char* contentTopicName`
 4. **[input]** `char* encoding`: depending on the payload, use `proto`, `rlp` or `rfc26`
-5. **[output]** `char* outContentTopic`. Gets populated with a content topic formatted according to [RFC 23](https://rfc.vac.dev/spec/23/).
+5. **[output]** `char* outContentTopic`. Gets populated with a content topic formatted according to [23/WAKU2-TOPICS](../../../informational/23/topics.md).
   ```
   /{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}
   ```



-### `extern char* waku_pubsub_topic(char* name, char* encoding, char* outPubsubTopic)`
+#### `extern char* waku_pubsub_topic(char* name, char* encoding, char* outPubsubTopic)`

-Create a pubsub topic string according to [RFC 23](https://rfc.vac.dev/spec/23/).
+Create a pubsub topic string according to [23/WAKU2-TOPICS](../../../informational/23/topics.md).

 **Parameters**

 1. **[input]** `char* name`
 2. **[input]** `char* encoding`: depending on the payload, use `proto`, `rlp` or `rfc26`
-3. **[output]** `char* outPubsubTopic`. Gets populated with a pubsub topic formatted according to [RFC 23](https://rfc.vac.dev/spec/23/).
+3. **[output]** `char* outPubsubTopic`. Gets populated with a pubsub topic formatted according to [23/WAKU2-TOPICS](../../../informational/23/topics.md).
   ```
   /waku/2/{topic-name}/{encoding}
   ```


-### `extern void waku_default_pubsub_topic(char* defaultPubsubTopic)`
+#### `extern void waku_default_pubsub_topic(char* defaultPubsubTopic)`

-Returns the default pubsub topic used for exchanging waku messages defined in [RFC 10](https://rfc.vac.dev/spec/10/).
+Returns the default pubsub topic used for exchanging waku messages defined in [RFC 10](../10/waku2.md).

 **Parameters**
 1. **[output]** `char* defaultPubsubTopic`. Gets populated with  `/waku/2/default-waku/proto`


-### `extern unsinged int waku_relay_publish(char* messageJson, char* pubsubTopic, int timeoutMs, char* jsonResp)`
+#### `extern unsinged int waku_relay_publish(char* messageJson, char* pubsubTopic, int timeoutMs, char* jsonResp)`

 Publish a message using Waku Relay.

 **Parameters**

-1. **[input]** `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. **[input]** `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. **[input]** `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. **[input]** `int timeoutMs`: Timeout value in milliseconds to execute the call.
@@ -792,7 +792,7 @@ Unsigned int. Possible values:



-### `extern char* waku_relay_publish_enc_asymmetric(char* messageJson, char* pubsubTopic, char* publicKey, char* optionalSigningKey, int timeoutMs)`
+#### `extern char* waku_relay_publish_enc_asymmetric(char* messageJson, char* pubsubTopic, char* publicKey, char* optionalSigningKey, int timeoutMs)`

 Optionally sign,
 encrypt using asymmetric encryption
@@ -800,7 +800,7 @@ and publish a message using Waku Relay.

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. `char* publicKey`: hex encoded public key to be used for encryption.
@@ -817,7 +817,7 @@ Note: `messageJson.version` is overwritten to `1`.
 A [`JsonResponse`](#jsonresponse-type).
 If the execution is successful, the `result` field contains the message ID.

-### `extern char* waku_relay_publish_enc_symmetric(char* messageJson, char* pubsubTopic, char* symmetricKey, char* optionalSigningKey, int timeoutMs)`
+#### `extern char* waku_relay_publish_enc_symmetric(char* messageJson, char* pubsubTopic, char* symmetricKey, char* optionalSigningKey, int timeoutMs)`

 Optionally sign,
 encrypt using symmetric encryption
@@ -825,7 +825,7 @@ and publish a message using Waku Relay.

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. `char* symmetricKey`: hex encoded secret key to be used for encryption.
@@ -842,7 +842,7 @@ Note: `messageJson.version` is overwritten to `1`.
 A [`JsonResponse`](#jsonresponse-type).
 If the execution is successful, the `result` field contains the message ID.

-### `extern char* waku_relay_enough_peers(char* pubsubTopic)`
+#### `extern char* waku_relay_enough_peers(char* pubsubTopic)`

 Determine if there are enough peers to publish a message on a given pubsub topic.

@@ -864,7 +864,7 @@ For example:
 }
 ```

-### `extern unsigned int waku_relay_subscribe(char* topic, char* jsonResp)`
+#### `extern unsigned int waku_relay_subscribe(char* topic, char* jsonResp)`

 Subscribe to a Waku Relay pubsub topic to receive messages.

@@ -919,7 +919,7 @@ For Example:
 }
 ```

-### `extern unsigned int waku_relay_unsubscribe(char* topic, char* jsonResp)`
+#### `extern unsigned int waku_relay_unsubscribe(char* topic, char* jsonResp)`

 Closes the pubsub subscription to a pubsub topic. No more messages will be received
 from this pubsub topic.
@@ -945,7 +945,7 @@ Unsigned int. Possible values:
   - 0 - The operation failed for any reason. It worth checking the value of `jsonResp` in this case.


-### `extern char* waku_relay_topics()`
+#### `extern char* waku_relay_topics()`

 Get the list of subscribed pubsub topics in Waku Relay.

@@ -1052,7 +1052,7 @@ Publish a message using Waku Lightpush.

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. `char* peerID`: Peer ID supporting the lightpush protocol.
@@ -1080,7 +1080,7 @@ and publish a message using Waku Lightpush.

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. `char* peerID`: Peer ID supporting the lightpush protocol.
@@ -1109,7 +1109,7 @@ and publish a message using Waku Lightpush.

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* pubsubTopic`: pubsub topic on which to publish the message.
   If `NULL`, it uses the default pubsub topic.
 3. `char* peerID`: Peer ID supporting the lightpush protocol.
@@ -1164,7 +1164,7 @@ Decrypt a message using a symmetric key

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* symmetricKey`: 32 byte symmetric key hex encoded.

 Note: `messageJson.version` is expected to be `1`.
@@ -1191,7 +1191,7 @@ Decrypt a message using a secp256k1 private key

 **Parameters**

-1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
+1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
 2. `char* privateKey`: secp256k1 private key hex encoded.

 Note: `messageJson.version` is expected to be `1`.
@@ -1251,7 +1251,6 @@ An `error` message otherwise.
 ```


-
 ## Utils

 ### `extern char* waku_utils_base64_encode(char* data)`
@@ -1280,7 +1279,10 @@ Decode a base64 string (useful for reading the payload from Waku Messages).
 A [`JsonResponse`](#jsonresponse-type).
 If the execution is successful, the `result` field contains the decoded payload.

-# Copyright
+## Copyright

 Copyright and related rights waived via
 [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+## References
+