diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 741fc80..7771608 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -318,9 +318,12 @@ types: 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: + "message:*": 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." + description: "Event emitted when a message is received on the specified content topic. The event name is `message:` concatenated with the content topic string (e.g. `message:/supercrypto/1/notification/proto`, and the event payload is the raw message bytes." + "error:*": + type: string + description: "Event emitted when subscription irrevocably fails for specified content topic. The event name is `error:` concatenated with the content topic string (e.g. `error:/supercrypto/1/notification/proto`, and the event payload is a string describing the error." ``` #### Function definitions @@ -334,7 +337,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: result + type: void ``` #### Predefined values @@ -361,6 +364,19 @@ 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 irrevocable failures should lead to emitting a subscription error. +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 irrevocable 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.