logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-01-02 14:13:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge 2de310e56d2d7e5031c817cc00d9463a94838a85 into 68bd15734a7a3238a18b15119ddfb126aab03a55

Browse Source
This commit is contained in:
fryorcraken 2025-10-13 05:33:15 +00:00 committed by GitHub
commit 987b87622c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 90 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
standards/application/waku-api.md
View File

@ -29,6 +29,13 @@ contributors:
* [Function definitions](#function-definitions)
* [Predefined values](#predefined-values)
* [Extended definitions](#extended-definitions)
* [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)
* [The Validation API](#the-validation-api)
* [Security/Privacy Considerations](#securityprivacy-considerations)
* [Copyright](#copyright)
@ -75,6 +82,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 +310,88 @@ 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
```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."
# Extending `WakuNode` definition
WakuNode:
fields:
messageEmitter:
type: MessageEmitter
description: "Event emitter for received messages, keyed by content topic."
```
#### Function definitions
```yaml
functions:
subscribe:
description: "Subscribe to specific content topics"
parameters:
- name: contentTopics
type: Array<string>
description: "The content topics for the node to subscribe to."
returns:
type: void
```
#### Predefined values
#### 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.
**`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;
[P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy.
Examples of irremediable 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.