From c9d0bf09509d1e742b27cbc3a8659522ee5a9ea4 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 22 Sep 2025 16:34:33 -0700 Subject: [PATCH 001/174] Added Chat --- standards/application/chat.md | 133 ++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 standards/application/chat.md diff --git a/standards/application/chat.md b/standards/application/chat.md new file mode 100644 index 0000000..2c6f216 --- /dev/null +++ b/standards/application/chat.md @@ -0,0 +1,133 @@ +--- +title: CHAT +name: A modular framework for defining chat protocols +category: Information +status: raw +tags: chat +editor: Jazz Alyxzander +contributors: +--- +# Abstract + +This specification defines a modular communication protocol framework for describing chat protocols. It introduces abstraction boundaries, and a component model for describing chat protocol functionality. + + +# Background / Rationale / Motivation + +Chat protocols specifications can be long and dense documents. To fully describe a chat protocol there are many layers and operations which are required to be documented. This includes payloads, message transport, encryption as well as user level features such as account registration, typing indicators, content formatting. + +With the vast amount of information required to maintain compatibility between applications - protocol documentation is either comprehensive which leads to large monolithic specifications or lacking the required details for interop between implementors. + +# Theory / Semantics + +This specification defines a abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. + + +The chat protocol is be decomposed into 3 distinct phases. + +- **Discovery:** How does a Sender learn of other clients. +- **Initialization:** How does a Recipient learn a client wants to communicate with them. +- **Operation:** How do participants exchange content. + +and transport details are divided into: + +- **Delivery Service:** How are payloads are routed and delivered to a client. +- **Framing Strategy:** How are payloads encoded. + +Defining these 5 parameters allows for chat protocol implementations to be fully defined, which allows clients from different applications to exchange messages. + +## Abstract Transport + +### Delivery service + +The service or method that distributes payloads to clients is called abstractly called a `Delivery Service` or `DS`. + +- a DS MUST have a method for clients to subscribe to messages. +- a DS MAY NOT guarantee delivery of messages. +- a DS MAY NOT guarantee order of messages. + +How protocols are mapped to DS level concepts is to be defined by implementors. + +### Framing Strategy + +In this protocol framework, payloads from multiple protocols are potentially multiplexed over the same channel. This requires that clients are able to associate a given payload to a given instance of a protocol. + +A framing strategy should define a common payload type as well as a method to determine which state machine a receiving client must used to decode it. + + +## Protocol Components + +In order to exchange content clients must be able to learn of each others existence, gather the pre-requisite information/parameters and, remain synchronized over time. + +The lifecycle of a protocol instance is divided into three phases, which are described by a corresponding protocol. + +- **Discovery Phase:** Discovery Protocol +- **Initialization Phase:** Initialization Protocol +- **Operation Phase:** Conversation Protocol + +```mermaid +sequenceDiagram + participant D as ??? + participant S as Saro + participant R as Raya + + + Note over D,S: Discovery + D -->> S: + + Note over R,S: Initialization + S ->> R: Invite + + Note over R,S: Operation + + loop + par + R->> S: Send Message + and + S->> R: Send Message + end + end +``` + + + +### Discovery Protocol + +A discovery protocol defines how clients gather the prerequisite information to contact another client. + +The input requirements of the discovery protocol are not defined here, and largely determined by the desired user experience. + +The output requirements of the discovery protocol are very implementation specific, and will depend on the initialization protocol requirements and DS chosen by the implementation. The data provided by the discovery protocol and required by the initialization protocol is called the `IntroductionBundle`. + +- The discovery protocol MUST provide all data required for the initialization protocol. + +Note: There is no requirement that the Discovery protocol be a complicated nor interactive process. Hypothetically If all required values to construct a IntroductionBundle could be statically defined, that would be sufficient for this definition. + +### Initialization Protocol + +A initialization protocol specifies how two clients can initiate communication. The input to this process is the `IntroductionBundle` and the output is an established instance of a `Conversation` between the participants. + +The core of an initialization protocol is a defined location and procedure for receiving initial messages. + +Many chat protocols choose to define the initialization protocol within the conversation protocol. This tight coupling produces two negative artifacts. +- New conversation protocols must define and deploy there own initialization channels. Increasing overhead and adding complexity. +- New protocol upgrades then create partitions in the communication network, as older clients have no means of communicating with new clients. + +Separating channel initialization from conversation flow allows multiple conversations to reuse the same initialization channel. This reduces effort for new conversation protocols, and is especially valuable when upgrading existing ones. Being independent the initialization pathway can persist across conversation versions. Even if an older client cannot parse new message types, it can still recognize their presence, adding observability. + +### Conversation Protocol + +A conversation protocol defines how messages flow between participants, and subsequently determines the properties of that channel. + +- A Conversation protocol MUST define the payloads it uses and how to handle them. +- A Conversation protocol SHOULD outline the cryptographic properties provided +- A Conversation protocol SHOULD describe bidirectional communication. +- A Conversation protocol ... + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +A list of references. From e2d9b15eb190685689f5589ab1784a1199b3e60a Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 09:39:14 -0700 Subject: [PATCH 002/174] rename to CHAT-FRAMEWORK --- standards/application/{chat.md => chat-framework.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename standards/application/{chat.md => chat-framework.md} (99%) diff --git a/standards/application/chat.md b/standards/application/chat-framework.md similarity index 99% rename from standards/application/chat.md rename to standards/application/chat-framework.md index 2c6f216..85420b2 100644 --- a/standards/application/chat.md +++ b/standards/application/chat-framework.md @@ -1,5 +1,5 @@ --- -title: CHAT +title: CHAT-FRAMEWORK name: A modular framework for defining chat protocols category: Information status: raw From 0775ad6e084dc260a2a096dda3f30e4018ccb36b Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 12:53:10 -0700 Subject: [PATCH 003/174] add delivery address --- standards/application/chat-framework.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 85420b2..d8fda70 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -40,13 +40,15 @@ Defining these 5 parameters allows for chat protocol implementations to be fully ### Delivery service -The service or method that distributes payloads to clients is called abstractly called a `Delivery Service` or `DS`. +A Delivery Service (DS) is the service or method that distributes payloads to clients. A DS accepts payloads with a delivery_address and delivers them to all subscribers of that delivery_address. Protocols use delivery_addresses to establish delivery contracts between senders and recipients. The mapping of delivery_addresses to DS-level concepts is implementation-specific. -- a DS MUST have a method for clients to subscribe to messages. -- a DS MAY NOT guarantee delivery of messages. -- a DS MAY NOT guarantee order of messages. +#### Requirements + +- -A DS MUST provide a method for clients to subscribe to messages from a delivery_address +- Payloads sent to a delivery_address are delivered by a DS to all subscribers of that delivery_address +- A DS MAY NOT guarantee message delivery +- A DS MAY NOT guarantee message ordering -How protocols are mapped to DS level concepts is to be defined by implementors. ### Framing Strategy From 02af71b11d7226f2c202c822c13e6d2073b219b6 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 3 Oct 2025 16:30:09 +1000 Subject: [PATCH 004/174] Introduce the Waku API's subscribe function --- standards/application/waku-api.md | 59 +++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 6cfceb5..741fc80 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,6 +29,11 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) + * [Subscribe to messages](#subscribe-to-messages) + * [Type definitions](#type-definitions-1) + * [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 +80,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 +308,59 @@ 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. +### 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." +``` + +#### Function definitions + +```yaml +functions: + subscribe: + description: "Subscribe to specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to subscribe to." + returns: + type: result +``` + +#### Predefined values + +Extending `WakuNode`: + +```yaml +types: + WakuNode: + fields: + messageEmitter: + type: MessageEmitter + description: "Event emitter for received messages, keyed by content topic." +``` + +#### 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. + ## 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. From 55dfcf950ac01cba1e21c7d2d073991e54cfd552 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 7 Oct 2025 00:42:32 +0200 Subject: [PATCH 005/174] add Send API --- standards/application/waku-api.md | 51 +++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 03d4bf6..38096dc 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -302,6 +302,57 @@ 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: + SendMessage: + type: object + fields: + contentTopic: + type: string + description: "The content topic for the message." + payload: + type: Uint8Array + description: "The message payload as bytes." + ephemeral: + type: bool + default: false + description: "Whether the message is ephemeral." + rateLimitProof: + type: Uint8Array + default: none + description: "Rate limiting proof as bytes" + + RequestId: + type: string + description: "A unique identifier for a request" +``` + +#### Function definitions + +```yaml +functions: + send: + description: "Send a message through the Waku network." + parameters: + - name: message + type: SendMessage + description: "The message to send" + returns: + type: result +``` + +#### Extended definitions + +When `message` is sent with `contentTopic` for a first time, +the node SHOULD trigger a subscription based on `Subscribe to messages` section. + +Additionally, the node SHOULD initiate recurring [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) queries +to validate if sent message was stored on the network and `static_store_nodes` SHOULD be prioritised. + ## 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. From a25e3b9d3ae25dedf9df888bc7983a7ef14950b1 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Wed, 8 Oct 2025 15:07:06 +0200 Subject: [PATCH 006/174] Update standards/application/waku-api.md Co-authored-by: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 38096dc..ad5b8b9 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -316,7 +316,7 @@ types: description: "The content topic for the message." payload: type: Uint8Array - description: "The message payload as bytes." + description: "The message data to be sent." ephemeral: type: bool default: false From 8387ada41cb9630fb96ed14e4b73972fc91470c0 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Wed, 8 Oct 2025 23:43:38 +0200 Subject: [PATCH 007/174] address comment --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index ad5b8b9..dba27b7 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -313,7 +313,7 @@ types: fields: contentTopic: type: string - description: "The content topic for the message." + 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: Uint8Array description: "The message data to be sent." From 79a96a6acf747d8bdf1bded5fcb991f65bcdd0f1 Mon Sep 17 00:00:00 2001 From: Sasha Date: Wed, 8 Oct 2025 23:49:54 +0200 Subject: [PATCH 008/174] address review --- standards/application/waku-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index ad5b8b9..baad5b7 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -69,7 +69,7 @@ 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. @@ -315,16 +315,16 @@ types: type: string description: "The content topic for the message." payload: - type: Uint8Array + type: array description: "The message data to be sent." ephemeral: type: bool default: false - description: "Whether the message is ephemeral." + 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)" rateLimitProof: - type: Uint8Array + type: array default: none - description: "Rate limiting proof as bytes" + description: "Rate limiting proof needed for [PUBLISHING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md#publishing)" RequestId: type: string @@ -336,7 +336,7 @@ types: ```yaml functions: send: - description: "Send a message through the Waku network." + description: "Send a message through the network." parameters: - name: message type: SendMessage From e8964ac3b4a52614df2c55942c4c6142845f579f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 13 Oct 2025 15:47:12 +1100 Subject: [PATCH 009/174] remove error return for `subscribe` --- standards/application/waku-api.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) 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. From 2de310e56d2d7e5031c817cc00d9463a94838a85 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 13 Oct 2025 16:33:08 +1100 Subject: [PATCH 010/174] fix error emission --- standards/application/waku-api.md | 63 +++++++++++++++++++------------ 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7771608..b1494be 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -29,8 +29,10 @@ contributors: * [Function definitions](#function-definitions) * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) - * [Subscribe to messages](#subscribe-to-messages) + * [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) @@ -308,6 +310,27 @@ 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 @@ -315,15 +338,18 @@ whereas `core` SHOULD be used if node has no strong hardware or bandwidth restri ```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: - "message:*": - type: 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." + 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 @@ -342,17 +368,6 @@ functions: #### Predefined values -Extending `WakuNode`: - -```yaml -types: - WakuNode: - fields: - messageEmitter: - type: MessageEmitter - description: "Event emitter for received messages, keyed by content topic." -``` - #### Extended definitions **`mode`**: @@ -366,11 +381,11 @@ Only messages on subscribed content topics SHOULD be emitted by `messageEmitter` **`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; +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 irrevocable failures are: +Examples of irremediable failures are: - Invalid content topic format - Exceeding number of content topics From 681f38a388ff6fd8b310470b2e6dc7c34f8b2f83 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 21 Oct 2025 01:19:16 +0200 Subject: [PATCH 011/174] add EventSource and address comments --- standards/application/waku-api.md | 66 +++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 3d6fe83..406d32e 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -321,10 +321,6 @@ types: 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)" - rateLimitProof: - type: array - default: none - description: "Rate limiting proof needed for [PUBLISHING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md#publishing)" RequestId: type: string @@ -347,11 +343,67 @@ functions: #### Extended definitions -When `message` is sent with `contentTopic` for a first time, +When `message` is sent with `contentTopic` for the first time, the node SHOULD trigger a subscription based on `Subscribe to messages` section. -Additionally, the node SHOULD initiate recurring [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) queries -to validate if sent message was stored on the network and `static_store_nodes` SHOULD be prioritised. +The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery. + +## Event source + +#### Type definitions + +```yaml +types: + MessageSentEvent: + type: object + fields: + eventType: + type: string + default: "message:sent" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the sent message" + + MessageErrorEvent: + type: object + fields: + eventType: + type: string + default: "message:error" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the failed message" + error: + type: string + description: "Error message describing what went wrong" + + MessageAckEvent: + type: object + fields: + eventType: + type: string + default: "message:ack" + description: "Event type identifier" + requestId: + type: RequestId + description: "The request ID associated with the acknowledged message" + ackType: + type: string + description: "Type of acknowledgment (e.g., 'store', 'filter')" + + EventSource: + type: object + description: "Event source for message-related events" + fields: + onEvent: + type: function + description: "Callback for message:sent events" + parameters: + - name: event + type: MessageSentEvent | MessageErrorEvent | MessageAckEvent +``` ## The Validation API From b68082cc7c04e8748b2ce5842cf6ee2f8962fb09 Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:17:09 +0200 Subject: [PATCH 012/174] address comments --- standards/application/waku-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 406d32e..63aafdb 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -379,19 +379,19 @@ types: type: string description: "Error message describing what went wrong" - MessageAckEvent: + MessagePropagatedEvent: type: object fields: eventType: type: string - default: "message:ack" + default: "message:propagated" description: "Event type identifier" requestId: type: RequestId - description: "The request ID associated with the acknowledged message" - ackType: + description: "The request ID associated with the propagated message in the network" + messageHash: type: string - description: "Type of acknowledgment (e.g., 'store', 'filter')" + description: "Hash of the message that got propagated within the network" EventSource: type: object From 36c3879a739bba68dab86f6f67b4629b1959eecb Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:41:31 +0200 Subject: [PATCH 013/174] chore: add health status --- standards/application/waku-api.md | 54 +++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 03d4bf6..9cc412c 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -30,6 +30,8 @@ contributors: * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) * [The Validation API](#the-validation-api) + * [Health Status](#health-status) + * [Event Source](#event-source) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -313,6 +315,58 @@ that would contain all validation parameters including RLN. In the time being, parameters specific to RLN are accepted for the message validation. RLN can also be disabled. +## Health Status + +#### Type definitions + +```yml +types: + HealthStatus: + type: enum + values: [Unhealthy, MinimallyHealthy, Healthy] + description: "Used to identify health of the operating node" +``` + +#### Extended definitions + +`Unhealthy` indicates that the node has lost connectivity for message reception, +sending, or both, and as a result, it cannot reliably process or transmit messages. + +`MinimallyHealthy` indicates that the node meets the minimum operational requirements, +although performance or reliability may be impacted. + +`Healthy` indicates that the node is operating optimally, +with full support for message processing and transmission. + +## Event source + +#### Type definitions + +```yaml +types: + HealthStatus: + type: object + fields: + eventType: + type: string + default: "health" + description: "Event type identifier" + status: + type: HealthStatus + description: "Node health status emitted on state change" + +EventSource: + type: object + description: "Event source for Waku API events" + fields: + onEvent: + type: function + description: "Callback for captured events" + parameters: + - name: event + type: HealthStatus +``` + ## Security/Privacy Considerations See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md). From ed2ffc151a3d0969bfd1acd469730c838afaf563 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Thu, 23 Oct 2025 00:44:30 +0200 Subject: [PATCH 014/174] use capital Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 9cc412c..7eaf329 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -338,7 +338,7 @@ although performance or reliability may be impacted. `Healthy` indicates that the node is operating optimally, with full support for message processing and transmission. -## Event source +## Event Source #### Type definitions From 88783f088d469a058eada785838c045ebeb0e18d Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:45:30 +0200 Subject: [PATCH 015/174] remove ambiguity --- standards/application/waku-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7eaf329..33cf149 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -344,7 +344,7 @@ with full support for message processing and transmission. ```yaml types: - HealthStatus: + HealthStatusEvent: type: object fields: eventType: @@ -364,7 +364,7 @@ EventSource: description: "Callback for captured events" parameters: - name: event - type: HealthStatus + type: HealthStatusEvent ``` ## Security/Privacy Considerations From 07e23fd791617218afcafe2a9d5e3aed37fc44da Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 23 Oct 2025 00:46:25 +0200 Subject: [PATCH 016/174] fix type --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 63aafdb..15d0880 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -402,7 +402,7 @@ types: description: "Callback for message:sent events" parameters: - name: event - type: MessageSentEvent | MessageErrorEvent | MessageAckEvent + type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent ``` ## The Validation API From b957762ada12b8bc9856c0e4c72fae3de8a88b95 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Fri, 24 Oct 2025 01:48:17 +0200 Subject: [PATCH 017/174] up text Co-authored-by: fryorcraken <110212804+fryorcraken@users.noreply.github.com> --- standards/application/waku-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 33cf149..7f79533 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -332,7 +332,8 @@ types: `Unhealthy` indicates that the node has lost connectivity for message reception, sending, or both, and as a result, it cannot reliably process or transmit messages. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements, +`MinimallyHealthy` indicates that the node meets the minimum operational requirements: connect to at least one peer with a protocol to send messages ([LIGHT-PUSH]() or [RELAY]()) and one peer with a protocol to receive messages ([FILTER ] or [RELAY]) +and one peer with store service capabilities. although performance or reliability may be impacted. `Healthy` indicates that the node is operating optimally, From e7be2b49eb2620f69f5d785ea8fcad1434468e68 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 28 Oct 2025 01:27:38 +0100 Subject: [PATCH 018/174] address comments --- standards/application/waku-api.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 15d0880..79e4cef 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -308,7 +308,7 @@ whereas `core` SHOULD be used if node has no strong hardware or bandwidth restri ```yaml types: - SendMessage: + MessageEnvelope: type: object fields: contentTopic: @@ -335,16 +335,16 @@ functions: description: "Send a message through the network." parameters: - name: message - type: SendMessage - description: "The message to send" + type: MessageEnvelope + description: "Parameters for sending the message." returns: type: result ``` #### Extended definitions -When `message` is sent with `contentTopic` for the first time, -the node SHOULD trigger a subscription based on `Subscribe to messages` section. +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. @@ -364,6 +364,9 @@ types: requestId: type: RequestId description: "The request ID associated with the sent message" + messageHash: + type: string + description: "Hash of the message that got sent to the network" MessageErrorEvent: type: object @@ -375,6 +378,9 @@ types: requestId: type: RequestId description: "The request ID associated with the failed message" + messageHash: + type: string + description: "Optional property. Hash of the message that got error" error: type: string description: "Error message describing what went wrong" @@ -393,13 +399,13 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventSource: - type: object + EventEmitter: + type: event_emitter description: "Event source for message-related events" fields: - onEvent: + addEventListener: type: function - description: "Callback for message:sent events" + description: "Callback for subscribing to events" parameters: - name: event type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent From c20f692a1324395c9453799bd48fcd68da14f7f5 Mon Sep 17 00:00:00 2001 From: Sasha <118575614+weboko@users.noreply.github.com> Date: Tue, 28 Oct 2025 01:36:46 +0100 Subject: [PATCH 019/174] Add property definitions section to waku-api.md Added property definitions for events in Waku API documentation. --- standards/application/waku-api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 79e4cef..b4bd522 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -224,6 +224,15 @@ functions: type: result ``` +#### Property definitions + +```yaml +properties: + events: + type: EventEmitter + description: "Event source for message-related events" +``` + #### Predefined values ```yaml From 78d0b9de668dfe0719084097d7dea95b470e71a3 Mon Sep 17 00:00:00 2001 From: Sasha Date: Tue, 28 Oct 2025 01:41:59 +0100 Subject: [PATCH 020/174] address comments --- standards/application/waku-api.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 7f79533..2d5b889 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -330,14 +330,16 @@ types: #### Extended definitions `Unhealthy` indicates that the node has lost connectivity for message reception, -sending, or both, and as a result, it cannot reliably process or transmit messages. +sending, or both, and as a result, it cannot reliably receive or transmit messages. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements: connect to at least one peer with a protocol to send messages ([LIGHT-PUSH]() or [RELAY]()) and one peer with a protocol to receive messages ([FILTER ] or [RELAY]) -and one peer with store service capabilities. -although performance or reliability may be impacted. +`MinimallyHealthy` indicates that the node meets the minimum operational requirements: +it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +one peer with a protocol to receive messages ([FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +and one peer with [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) service capabilities, +although performance or reliability may still be impacted. `Healthy` indicates that the node is operating optimally, -with full support for message processing and transmission. +with full support for message reception and transmission. ## Event Source From 35dc6ac6d6730ce375cca2f1867fb8a7268904ff Mon Sep 17 00:00:00 2001 From: Sasha Date: Wed, 29 Oct 2025 22:22:45 +0100 Subject: [PATCH 021/174] use snake case --- standards/application/waku-api.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index b4bd522..f13aa66 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -320,7 +320,7 @@ types: MessageEnvelope: type: object fields: - contentTopic: + 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: @@ -366,28 +366,28 @@ types: MessageSentEvent: type: object fields: - eventType: + event_type: type: string default: "message:sent" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the sent message" - messageHash: + message_hash: type: string description: "Hash of the message that got sent to the network" MessageErrorEvent: type: object fields: - eventType: + event_type: type: string default: "message:error" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the failed message" - messageHash: + message_hash: type: string description: "Optional property. Hash of the message that got error" error: @@ -397,14 +397,14 @@ types: MessagePropagatedEvent: type: object fields: - eventType: + event_type: type: string default: "message:propagated" description: "Event type identifier" - requestId: + request_id: type: RequestId description: "The request ID associated with the propagated message in the network" - messageHash: + message_hash: type: string description: "Hash of the message that got propagated within the network" From c61574b7beca06b7b3a717bf71091d2484443db3 Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 13 Nov 2025 00:43:11 +0100 Subject: [PATCH 022/174] add description to events --- standards/application/waku-api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index f13aa66..805ca91 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -365,6 +365,7 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat types: MessageSentEvent: type: object + description: "Event emitted when a message is sent to the network" fields: event_type: type: string @@ -379,6 +380,7 @@ types: MessageErrorEvent: type: object + description: "Event emitted when a message send operation fails" fields: event_type: type: string @@ -396,6 +398,7 @@ types: MessagePropagatedEvent: type: object + description: "Confirmation that a message has been correctly delivered to the network" fields: event_type: type: string From 11bc90ab309cccf8ee77876d39f5c049dc710e5d Mon Sep 17 00:00:00 2001 From: Sasha Date: Thu, 13 Nov 2025 00:47:54 +0100 Subject: [PATCH 023/174] update event emitter syntax --- standards/application/waku-api.md | 30 +++++++++--------------------- 1 file changed, 9 insertions(+), 21 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 805ca91..042f888 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -361,16 +361,12 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat #### Type definitions -```yaml +```yml types: MessageSentEvent: type: object description: "Event emitted when a message is sent to the network" fields: - event_type: - type: string - default: "message:sent" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the sent message" @@ -382,10 +378,6 @@ types: type: object description: "Event emitted when a message send operation fails" fields: - event_type: - type: string - default: "message:error" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the failed message" @@ -400,10 +392,6 @@ types: type: object description: "Confirmation that a message has been correctly delivered to the network" fields: - event_type: - type: string - default: "message:propagated" - description: "Event type identifier" request_id: type: RequestId description: "The request ID associated with the propagated message in the network" @@ -411,16 +399,16 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventEmitter: + EventEventEmitter: type: event_emitter description: "Event source for message-related events" - fields: - addEventListener: - type: function - description: "Callback for subscribing to events" - parameters: - - name: event - type: MessageSentEvent | MessageErrorEvent | MessagePropagatedEvent + events: + "message:sent": + type: MessageSentEvent + "message:error": + type: MessageErrorEvent + "message:propagated": + type: MessagePropagatedEvent ``` ## The Validation API From cfe7cddc381eb0d07ad4da79e4595e551ce34b66 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Thu, 13 Nov 2025 16:20:02 +1100 Subject: [PATCH 024/174] Some typos, improvements --- standards/application/waku-api.md | 40 ++++++++++++++++++------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 042f888..943a3b8 100644 --- 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 @@ -72,9 +78,10 @@ An alternative would be to choose a programming language. However, such choice m - 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` where `T` is the element type (e.g., `array`, `array`). - `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" @@ -224,15 +238,6 @@ functions: type: result ``` -#### Property definitions - -```yaml -properties: - events: - type: EventEmitter - description: "Event source for message-related events" -``` - #### Predefined values ```yaml @@ -253,6 +258,7 @@ values: static_store_nodes: [] cluster_id: 1 auto_sharding_config: + type: AutoShardingConfig fields: num_shards_in_cluster: 8 message_validation: TheWakuNetworkMessageValidation @@ -262,6 +268,7 @@ values: fields: max_message_size: "150 KiB" rln_config: + type: RlnConfig fields: contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6" chain_id: 59141 @@ -300,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) @@ -390,7 +396,7 @@ types: MessagePropagatedEvent: type: object - description: "Confirmation that a message has been correctly delivered to the network" + description: "Confirmation that a message has been correctly delivered to some neighbouring nodes." fields: request_id: type: RequestId @@ -399,7 +405,7 @@ types: type: string description: "Hash of the message that got propagated within the network" - EventEventEmitter: + MessageEvents: type: event_emitter description: "Event source for message-related events" events: From 7aec995a0700d85783e90ac1bb44ad76917a5d05 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Wed, 29 Oct 2025 17:21:40 +0530 Subject: [PATCH 025/174] update rendezvous for mix node discovery --- standards/core/rendezvous.md | 99 ++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 6a42abd..d435ac6 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -1,66 +1,97 @@ --- title: WAKU-RENDEZVOUS name: Waku Rendezvous discovery -editor: Simon-Pierre Vivier -contributors: +editor: Prem Chaitanya Prathi +contributors: Simon-Pierre Vivier --- ## Abstract + This document describes the goal, -strategy and usage of the libp2p rendezvous protocol by Waku. +strategy, usage, and changes to the libp2p rendezvous protocol by Waku. Rendezvous is one of the discovery methods that can be used by Waku. It supplements Discovery v5 and Waku peer exchange. ## Background and Rationale -How do new nodes join the network is the question that discovery answers. -Discovery must be fast, pertinent and resilient to attacks. -Rendezvous is both fast and allow the discovery of relevant peers, -although it design can be easily abused -due to it's lack of protection against denial of service atacks. -The properties of rendezvous complements well the slower but safer methods like Discv5. -To contribute well, a Waku node must know a sufficient number of peers with -a wide variety of capabilities. -By using rendezvous in combination with + +Waku nodes need a discovery mechanism that is both rapid and robust against attacks. Rendezvous enables quick identification of relevant peers, complementing slower but more resilient approaches like Discv5. For healthy network participation, nodes must connect to a diverse set of peers. However, the rendezvous protocol is vulnerable to denial of service attacks and depends on centralized rendezvous points, so it is best used in conjunction with other discovery methods such as Discv5. + +Ethereum Node Record (ENR) size constraints make it impractical to encode additional metadata, such as Mix public keys, in ENRs for Discv5-based discovery. Rendezvous, using a custom peer record (`WakuPeerRecord`), allows nodes to advertise Mix-specific information—including the Mix public key—without being restricted by ENR size. This serves as an interim solution until a comprehensive capability discovery mechanism is available. + +By combining rendezvous with [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) and [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract), -Waku nodes will reach a good number of meaningful peers -faster than through a single discovery method. +Waku nodes can more quickly reach a meaningful set of peers +than by relying on a single discovery method. ## Semantics -Waku rendezvous fully inherits the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol). + +Waku rendezvous extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. +This allows nodes to advertise additional Waku-specific metadata beyond what is available in the standard libp2p peer record. ## Specifications -The namespaces used to register and request MUST be in the format `rs/cluster-id/shard`. + +**Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` + +### Namespace Format + +The namespaces used to register and request MUST be in the format `rs//`. + +This allows for discovering peers with specific capabilities within a given cluster. +Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. + Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster and shard information. +### Registration and Discovery + Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. +Nodes supporting the Mix protocol MUST advertise their `WakuPeerRecord`, which includes their multiaddresses, supported protocols, and Mix public key. -We RECOMMEND a registration interval of 10 seconds. -The node SHOULD register once for every shard it supports, -registering only the namespace corresponding to that shard. +We RECOMMEND a registration interval of 10 seconds. -We RECOMMEND that rendezvous points expire registrations after 1 minute, -in order to keep discovered peer records to those recentrly online. +We RECOMMEND that rendezvous points expire registrations after 1 minute (60 seconds TTL) +to keep discovered peer records limited to those recently online. -At startup, every Waku node SHOULD discover peers by -sending requests to random rendezvous points, -once for each shard it supports. +At startup, every Waku node supporting Mix SHOULD discover peers by +sending requests to random rendezvous points for the Mix capability namespace. -We RECOMMEND a maximum of 12 peers will be requested each time. -This number is enough for good GossipSub connectivity and -minimize the load on rendezvous points. +We RECOMMEND a maximum of 12 peers be requested each time. +This number is sufficient for good GossipSub connectivity and +minimizes the load on rendezvous points. + +### Peer Records + +Nodes advertise their information through `WakuPeerRecord`, which includes: + +- Multiaddresses for connectivity +- Supported protocol codecs +- Mix protocol public key (for nodes supporting the Mix protocol) + +When a node discovers peers through rendezvous, it receives the complete `WakuPeerRecord` for each peer, +allowing it to make informed decisions about which peers to connect to based on their advertised information. + +### Operational Recommendations We RECOMMEND that bootstrap nodes participate in rendezvous discovery and -that other discovery methods are used in conjunction and +that other discovery methods are used in conjunction and continue discovering peers for the lifetime of the local node. +For resource-constrained devices or light clients, a client-only mode MAY be used +where nodes only query for peers without acting as rendezvous points themselves +and without advertising their own peer records. + ## Future Work -Namespaces will not contain capabilities yet but may in the future. If the need arise nodes could use rendezvous to discover peers with specific capabilities. +The protocol currently supports advertising Mix-specific capabilities (Mix public keys) through `WakuPeerRecord`. +Future enhancements could include: + +- Extending `WakuPeerRecord` to advertise other Waku protocol capabilities (Relay, Store, Filter, Lightpush, etc.) +- Supporting shard-based namespaces (e.g., `rs//`) for general relay peer discovery without capability filtering +- Batch registration support allowing nodes to register across multiple namespaces in a single request # Copyright @@ -68,7 +99,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). # References - - [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) - - [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract) - - [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) - - [Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) + +- [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) +- [ENR](https://github.com/ethereum/devp2p/blob/master/enr.md) +- [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract) +- [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) +- [Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) From cd9a10cff1d995b63e7d2191bf6c917786ef3f58 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Wed, 29 Oct 2025 17:29:47 +0530 Subject: [PATCH 026/174] address review comments --- standards/core/rendezvous.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index d435ac6..bd999ce 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -41,7 +41,7 @@ The namespaces used to register and request MUST be in the format `rs/ Date: Thu, 30 Oct 2025 09:59:51 +0530 Subject: [PATCH 027/174] address review comments --- standards/core/rendezvous.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index bd999ce..422444e 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -50,23 +50,24 @@ Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/ Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. -All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` specification. +All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` definition. -We RECOMMEND a registration interval of 10 seconds. +The RECOMMENDED registration interval is 10 seconds. -We RECOMMEND that rendezvous points expire registrations after 1 minute (60 seconds TTL) +It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) to keep discovered peer records limited to those recently online. At startup, every Waku node supporting Mix SHOULD discover peers by sending requests to random rendezvous points for the Mix capability namespace. -We RECOMMEND a maximum of 12 peers be requested each time. +It is RECOMMENDED a maximum of 12 peers be requested each time. This number is sufficient for good GossipSub connectivity and minimizes the load on rendezvous points. ### Peer Records -Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. The specification for `WakuPeerRecord` is as follows: +Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** @@ -93,7 +94,7 @@ When a node discovers peers through rendezvous, it receives the complete `WakuPe ### Operational Recommendations -We RECOMMEND that bootstrap nodes participate in rendezvous discovery and +It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and that other discovery methods are used in conjunction and continue discovering peers for the lifetime of the local node. From 234249dc1d1b804fdf6aae1d8b417f6bd624d340 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Fri, 31 Oct 2025 18:26:53 +0530 Subject: [PATCH 028/174] aligning with implementation --- standards/core/rendezvous.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 422444e..b5999a3 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -67,15 +67,15 @@ minimizes the load on rendezvous points. ### Peer Records Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +Since this is a customPeerRecord, it uses a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** - `peer_id`: The libp2p PeerId of the node. +- `seqNo`: The time at which the record was created or last updated (Unix epoch, seconds). - `multiaddrs`: A list of multiaddresses for connectivity. -- `protocols`: A list of supported protocol codecs (e.g., `/vac/waku/mix/1.0.0`). - `mix_public_key`: The Mix protocol public key (only present for nodes supporting Mix). -- `timestamp`: The time at which the record was created or last updated (Unix epoch, seconds). **Encoding:** WakuPeerRecord is encoded as a protobuf message. The exact schema is: @@ -83,10 +83,9 @@ WakuPeerRecord is encoded as a protobuf message. The exact schema is: ```protobuf message WakuPeerRecord { string peer_id = 1; - repeated string multiaddrs = 2; - repeated string protocols = 3; + uint64 seqNo = 2; + repeated string multiaddrs = 3; optional bytes mix_public_key = 4; - uint64 timestamp = 5; } ``` From 29322c5c01268e7789d9fd0dedf5cf573d1a5103 Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Mon, 3 Nov 2025 03:13:29 +0530 Subject: [PATCH 029/174] address review comments --- standards/core/rendezvous.md | 77 ++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index b5999a3..7b8af58 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -15,9 +15,11 @@ It supplements Discovery v5 and Waku peer exchange. ## Background and Rationale -Waku nodes need a discovery mechanism that is both rapid and robust against attacks. Rendezvous enables quick identification of relevant peers, complementing slower but more resilient approaches like Discv5. For healthy network participation, nodes must connect to a diverse set of peers. However, the rendezvous protocol is vulnerable to denial of service attacks and depends on centralized rendezvous points, so it is best used in conjunction with other discovery methods such as Discv5. - -Ethereum Node Record (ENR) size constraints make it impractical to encode additional metadata, such as Mix public keys, in ENRs for Discv5-based discovery. Rendezvous, using a custom peer record (`WakuPeerRecord`), allows nodes to advertise Mix-specific information—including the Mix public key—without being restricted by ENR size. This serves as an interim solution until a comprehensive capability discovery mechanism is available. +Waku needs discovery mechanism(s) that are both rapid and robust against attacks. +Fully centralised discovery (such as DNS lookup) may be fast but is not secure. +Fully decentralised discovery (such as discv5) may be robust, but too slow for some bootstrapping use cases +Rendezvous provides a limited, balanced solution that trades off some robustness for speed. +It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5 By combining rendezvous with [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) and @@ -34,40 +36,10 @@ This allows nodes to advertise additional Waku-specific metadata beyond what is **Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` -### Namespace Format - -The namespaces used to register and request MUST be in the format `rs//`. - -This allows for discovering peers with specific capabilities within a given cluster. -Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. - -Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster information. - -### Registration and Discovery - -Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. - -Each relay node that participates in discovery -MUST register with random rendezvous points at regular intervals. - -All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. For non-Mix relay nodes, the `mix_public_key` field SHOULD be omitted. The standard libp2p PeerRecord is not used for Waku rendezvous; all advertised records MUST conform to the `WakuPeerRecord` definition. - -The RECOMMENDED registration interval is 10 seconds. - -It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) -to keep discovered peer records limited to those recently online. - -At startup, every Waku node supporting Mix SHOULD discover peers by -sending requests to random rendezvous points for the Mix capability namespace. - -It is RECOMMENDED a maximum of 12 peers be requested each time. -This number is sufficient for good GossipSub connectivity and -minimizes the load on rendezvous points. - -### Peer Records +### Wire Protocol Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. -Since this is a customPeerRecord, it uses a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). +Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** @@ -91,6 +63,41 @@ message WakuPeerRecord { When a node discovers peers through rendezvous, it receives the complete `WakuPeerRecord` for each peer, allowing it to make informed decisions about which peers to connect to based on their advertised information. +### Namespace Format + +The [rendezvous namespaces](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#the-protocol) used to register and request peer records +MUST be in the format `rs//`. +`` is a string representing the individual capability for which a discoverable Waku peer record is registered. +The Waku peer record is separately registered against each capability for which discovery is desired. +The only defined capability for now is `mix`, representing [Waku Mix](https://github.com/waku-org/specs/blob/master/standards/core/mix.md) support. +For example, a Waku peer record for a node supporting mix protocol in cluster `1` will be registered against a namespace: `rs/1/mix`. + +This allows for discovering peers with specific capabilities within a given cluster. +Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. + +Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster information. + +### Registration and Discovery + +Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. + +Each relay node that participates in discovery +MUST register with random rendezvous points at regular intervals. +The RECOMMENDED registration interval is 10 seconds. + +All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. +All advertised records MUST conform to the `WakuPeerRecord` definition. + +It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) +to keep discovered peer records limited to those recently online. + +At startup, every Waku node supporting Mix SHOULD discover peers by +sending requests to random rendezvous points for the Mix capability namespace. + +It is RECOMMENDED a maximum of 12 peers be requested each time. +This number is sufficient for good GossipSub connectivity and +minimizes the load on rendezvous points. + ### Operational Recommendations It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and From ce9deda4500e1bc926d1afbbe0642d6bd018c79d Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Tue, 18 Nov 2025 16:42:58 +0530 Subject: [PATCH 030/174] update links with permalinks --- standards/core/rendezvous.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 7b8af58..292be4c 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -22,14 +22,14 @@ Rendezvous provides a limited, balanced solution that trades off some robustness It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5 By combining rendezvous with -[Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) and -[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract), +[Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) and +[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract), Waku nodes can more quickly reach a meaningful set of peers than by relying on a single discovery method. ## Semantics -Waku rendezvous extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. +Waku rendezvous extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. This allows nodes to advertise additional Waku-specific metadata beyond what is available in the standard libp2p peer record. ## Specifications @@ -39,7 +39,7 @@ This allows nodes to advertise additional Waku-specific metadata beyond what is ### Wire Protocol Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. -Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). +Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/0c6c7d75f1580af329847dbc9900859a445ed980/table.csv). The `WakuPeerRecord` is defined as follows: **WakuPeerRecord fields:** @@ -69,17 +69,17 @@ The [rendezvous namespaces](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d MUST be in the format `rs//`. `` is a string representing the individual capability for which a discoverable Waku peer record is registered. The Waku peer record is separately registered against each capability for which discovery is desired. -The only defined capability for now is `mix`, representing [Waku Mix](https://github.com/waku-org/specs/blob/master/standards/core/mix.md) support. +The only defined capability for now is `mix`, representing [Waku Mix](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/mix.md) support. For example, a Waku peer record for a node supporting mix protocol in cluster `1` will be registered against a namespace: `rs/1/mix`. This allows for discovering peers with specific capabilities within a given cluster. Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. -Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster information. +Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/relay-sharding.md) for cluster information. ### Registration and Discovery -Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. +Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. @@ -124,8 +124,8 @@ Copyright and related rights waived via # References -- [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) -- [ENR](https://github.com/ethereum/devp2p/blob/master/enr.md) -- [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract) -- [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) -- [Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) +- [Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) +- [ENR](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/enr.md) +- [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract) +- [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) +- [Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md) From fdcfcca3b58011c6fdc2ab8876c8bfb40430976b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 21 Nov 2025 11:41:50 -0300 Subject: [PATCH 031/174] add Waku API to readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 66bd734..26b9864 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ This repository contains specifications for the Waku suite of protocols. |[TOR-PUSH](standards/application/tor-push.md)| Waku Tor Push | |[RLN-KEYSTORE](standards/application/rln-keystore.md)| Waku RLN Keystore JSON schema | |[P2P-RELIABILITY](standards/application/p2p-reliability.md)| Waku P2P Reliability | +|[WAKU-API](standards/application/waku-api.md)| Waku API | ### Informational From 1ae8c0d5704606214e45603a2e214d73ddbd5bc6 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 11 Dec 2025 18:15:54 -0500 Subject: [PATCH 032/174] Create op_Chan rfc --- standards/application/op-chan.md | 148 +++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 standards/application/op-chan.md diff --git a/standards/application/op-chan.md b/standards/application/op-chan.md new file mode 100644 index 0000000..26f90a7 --- /dev/null +++ b/standards/application/op-chan.md @@ -0,0 +1,148 @@ +--- +title: OP-CHAN +name: OpChan Decentralized Forum +status: raw +category: Standards Track +tags: waku +editor: +contributors: + - Jimmy Debe +--- + +## Abstract + +This document specifies the architecture of OpChan. +OpChan is a decentralized forum application built on the Waku protocol. + + +## Background + +OpChan supports ephemeral anonymous sessions and wallet- +backed identities, identity key delegation, and stores content locally +while distributing messages over the Waku network. +All user data persists locally +and syncs via Waku messages to peers. +- Authentication and user publishing are provided either by ed25519 stored in the client or +wallet signature. + +## Terminology + +- Forum: A discussion board (analogous to a forum or channel) that groups + posts and moderation controls. +- Post: Top-level user content created within a forum. +- Comment: A reply to a `Post` or other `Comment` (threaded discussion). +- Participant: Any actor able to publish or consume messages (anonymous or + wallet-backed). +- Anonymous session: A browser-generated ed25519 keypair used as + identity for a user without a wallet. + + +## Specification + +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and +“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). + +OpChan uses [10/WAKU](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +as the transport for peer-to-peer distribution of messages, +as [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md). +The messages are cryptographically signed using ed25519 keys generated locally in the broswer window. +Wallet users MAY create a token signed by the wallet's private key. + +OpChan messages fall into two broad classes: + +1. Content messages +2. Control messages + +Message routing and +discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). + +### Message Format (high-level) + +All messages transmitted over the Waku network MUST include the following envelope fields: + +``` js + +id: string +type: enum { CELL_CREATED, POST_CREATED, COMMENT_CREATED, VOTE, BOOKMARK, MODERATION, DELEGATION } +timestamp: uint64 +author: string // author public key or wallet address +signature: bytes // ed25519 signature of the canonical serialized body +delegationProof?: bytes // optional wallet signature authorizing the browser key +body: object // + +``` + +Rules for signing: + +1. Serialize `body` fields in stable key order (JSON canonical form or + protobuf deterministic encoding). +2. Construct signing bytes with: `type`, `timestamp`, `author` +3. Sign with the browser key registered for the session. + +OpChan MUST verify the `signature` against the `author` and, +when present, verify `delegationProof`. + +### Identity + +There are two types of identity options, +anonymous session and wallet delegation. +An anonymous session generates an ed25519 keypair locally with the client. +The key is used to sign all messages. +- The session may include a Call Sign. *** +A wallet delegation connects a user's wallet to OpChan. +The wallet produces a short-lived delegation signature as the key. +That delegation proof is attached to each message and +verified is by peers in the network. + +#### Delegation flow: + +1. Client generates a new ed25519 keypair and a delegation request. +2. Wallet signs the delegation request and returns a `delegationProof` with an + expiration `timestamp`. +3. The client stores the `delegationProof`, `browserKey`, +and `expiry`. +The `delegationProof` SHOULD be included in outgoing messages until `expiry`. + +- `delegationProof` verification, +verify the wallet signature over the delegation request matches the wallet public key, +the `author` public key in messages + +### Moderation & Permissions + + +A post has metadata (id, name, +creator, admins, admins can moderate (hide, remove, or penalize content within the forum). + +Moderation events are control messages with types like `MODERATION_ACTION`: + +- action: enum { HIDE, REMOVE, PIN, UNPIN, CHANGE_OWNERSHIP }, + +Moderation messages MUST be signed by a recognized post admin. +Clients MUST validate the admin membership before applying moderation actions locally. + + +OpChan + +- posts +- comments +- votes +- users (identities, call signs, delegation proofs) +- bookmarks +- moderations + +Incoming Waku messages are validated + +If delegation is revoked, +peers should ignore subsequent messages from the revoked delegation key. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References +- [10/WAKU](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +- [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) +- + + From 4ebec4b4f34b6df3194adc05e1f8f1c07cca18cb Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 18 Dec 2025 19:50:49 -0500 Subject: [PATCH 033/174] update OpChan.md --- standards/application/OpChan.md | 226 +++++++++++++++++++++++++++++++ standards/application/op-chan.md | 148 -------------------- 2 files changed, 226 insertions(+), 148 deletions(-) create mode 100644 standards/application/OpChan.md delete mode 100644 standards/application/op-chan.md diff --git a/standards/application/OpChan.md b/standards/application/OpChan.md new file mode 100644 index 0000000..4e4e5ad --- /dev/null +++ b/standards/application/OpChan.md @@ -0,0 +1,226 @@ +--- +title: OP-CHAN +name: OpChan Decentralized Forum +status: raw +category: Standards Track +tags: waku +editor: +contributors: + - Jimmy Debe +--- + +## Abstract + +This document specifies the architecture of OpChan. +OpChan is a decentralized forum application built on the Waku protocol. + +## Background + +In a decentralized forum content is hosted on multiple nodes, +making it difficult for user's post to be censorship resistant. +Users own their post data, so data cannot be removed by a third party, +and forum boards will not rely on moderators remaining active. + +OpChan is a web application hosted by some party through a web server. +The content being published by users are not stored by the server, +but by distributing the messages peer to peer. +OpChan supports ephemeral anonymous web sessions, +supporting a locally generated ED25519 keypairs for identity and +signing. +Wallet-backed identities, identity key delegation, and +content stored locally while distributing messages using the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocol. + +- WAKU-LIGHTPUSH + +## Terminology + +- Cell: A discussion board or channel that hosts posts and moderation controls. +- Post: User content created within a forum. +- Comment: A reply to a `Post` or other `Comment` (threaded discussion). +- Participant: Any user able to publish or consume messages (anonymous or + wallet-backed). +- Anonymous session: A client-generated ed25519 keypair used as + identity for a user without a wallet identity. + +## Specification + +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and +“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). + +OpChan uses the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +network for the distribution forum content amongst peers. +The messages, which are [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) objects, +are cryptographically signed using ED25519 keys generated by the client locally. +Users SHOULD use the [19WAKU2-LIGHTPUSH]() protocol to send messages to Waku nodes storing the forum's content. + +OpChan supports two types of messages, +content and control messages. +Content messages are user generated content on the forum. +The message types include the following: + +- Channel: Metadata information like name, description, admins of a forum board. +- Post: User content created within a cell. +- Comment: Users reply to a post or another comment. +- Vote: To cast upvote or downvote for a post or comment. +- User: Includes username, delegation proofs and identities. +See [identities](#identities) for more information. +- Bookmark: A user bookmarking a post or comment. + +Control messages consist of the user activity/interactions on the forum. +This includes the manage of the current forum state, +permissions, and moderations. +The message types include the following: + +- Create Channel: The initial event of creating a new channel within the forum. +- Delegation Events: Channel admins granting or revoking channel rights. +- Moderation Events: Channel admins able to hide, remove and + pin/unpin a post or comment. + Also can promote new admins and change the ownership of a channel. + +### Message Format + +Message routing and +discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). +Each content are assigned a `pubsub_topic` that clients MUST subscribe to discovery messages of from the channel. + +All messages transmitted over the Waku network MUST include the following envelope fields: + +``` js +{ + "id": "string", + "type": "CELL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", + "timestamp": "uint64" + "author": "string" // author public key or wallet address + "signature": "bytes" // ed25519 signature of the canonical serialized body + "delegationProof": "bytes" // optional wallet signature authorizing the browser key + "body": object // The message content +} + +``` + +Every message SHOULD be signed using ED25519 keys from the publishing user. +Clients SHOULD verify the signature against the `author` public key and, +when present, verify `delegationProof`. + +Signing Flow: + +1. Serialize `body` fields in stable key order. +2. Construct signing bytes with: `type`, `timestamp`, `author` and `body`. +3. Sign with the user's cryptograhic keys for the session. + +- channel admin + +### Identities + +There are two types of identities for users, +anonymous session and wallet delegation. +A wallet delegation MAY be an ENS(Ethereum Name Service) verified user. +An anonymous session generates an ed25519 keypair locally with the client. +The key is used to sign all messages and +a username MAY choose a username attached to the post or comments. +An anonymous user SHOULD NOT granted an admin role, +create moderation events or create a channel. + +A wallet delegation uses the user's wallet private key to sign a delegation message, +the `delegationProof`. +The `delegationProof` SHOULD be a short-lived message, +RECCOMENDED a few minutes to a few hours. +Once a `delegationProof` is generated, +the client SHOULD be able to sign messages, +without the need for repeated wallet prompts requesting to sign. + +#### Delegation Flow: + +1. The client generates a new `browserKey`, which is a ED25519 keypair. +2. The client generates a delegation request to authorize `browserKey` to sign. +3. The user's wallet signs the delegation request and +returns a `delegationProof` with an expiration timestamp, `expiry`. +4. The client stores the `delegationProof`, `browserKey`, +and `expiry`. + +A `delegrationProof` could become revoked by the wallet owner or +after the `expiry` time. +If a wallet delegation is revoked, +clients SHOULD ignore subsequent messages from the revoked delegation key. + +### Moderation & Permissions + +A post MAY be have moderation message types assigned by the channel admin. +The moderation types include: + +- `HIDE` : To hide a post or comment. +- `REMOVE` : To permanently remove a post or comment. +- `PIN` : To pin a post to the top of a channel feed or pin a comment to the top of a thread. +- `UNPIN` : To remove a `PIN` from a post feed or comment thread. +- `CHANGE_OWNERSHIP` : Change the `author` of a post or comment. + +Moderation messages MUST be signed by an admin, +which recognized `author` of the channel. +Clients SHOULD validate the admin before applying moderation events locally. + +### Relevance Score + +A post can gain better visibility on the forum channel and +the forum's search through the content relevance score. +Clients with verified wallet identities MUSt be favored when anonymous session. + +There are a few RECCOMENDED areas that collect points when calculating the relevance score of a post: + +Basic scores include the activites that each user is albe to engage in. + +- A channel has a score value of 15 +- Each post within a channel has a score value of 10 +- A base value if comments are present within a post boost the relevance score by a value of 5 + +Engagement score include different user activites for each post or comment. + +- Each wallet delegation upvote adds a score value of 1. +- Each comment indiviual comment adds a score value of 0.5. +- The total number of of post multipled by 0.5. +The total number of upvotes multiped by 0.1. +These two values are added together. + +For identity verification scores, +participants of post or comment that use wallet-based identities, +including an optional ENS, +the score is boosted over the anonymous identities. +If a participant has a verified ENS and a verified connected wallet, +only the ENS multipler SHOULD be applied. + +- Participants of who has a verified ENS name gains a value multiplier of 1.25(25%). +- For wallet connect participant the multiplier is 1.1(10%). +- For verified upvote participants the multipler is 0.1. +- For verified comment participants the multiplier is 0.05. + +There is a time decay that reduces the relevance score over time. +The older a post or comment was made the lower its score. + +$$ +\text{timeDecayMultiplier} = e^{-\lambda \cdot \text{daysOld}} +$$ + +Where $$\( -\lambda \)$$ is the time-decay rate per day. + +There SHOULD be a moderation penalty that reduces the score when a post or +comment is moderated with a value of 0.5(50%). +This penalty is applied once a post is `HIDDEN`, `REMOVED` or `FLAGGED` by a moderator. + +$$ +\text{moderationPenalty} = \begin{cases} 0.5, & \text{if moderated} \\ +1, & \text{otherwise} \end{cases} +$$ + +Total + +RelevanceScore = (basic + engagement + verifiedUpvote) * (1 + verifyIdentity) * timeDecay * moderationPenalty + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References +- [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +- [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) +- [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) +- diff --git a/standards/application/op-chan.md b/standards/application/op-chan.md deleted file mode 100644 index 26f90a7..0000000 --- a/standards/application/op-chan.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: OP-CHAN -name: OpChan Decentralized Forum -status: raw -category: Standards Track -tags: waku -editor: -contributors: - - Jimmy Debe ---- - -## Abstract - -This document specifies the architecture of OpChan. -OpChan is a decentralized forum application built on the Waku protocol. - - -## Background - -OpChan supports ephemeral anonymous sessions and wallet- -backed identities, identity key delegation, and stores content locally -while distributing messages over the Waku network. -All user data persists locally -and syncs via Waku messages to peers. -- Authentication and user publishing are provided either by ed25519 stored in the client or -wallet signature. - -## Terminology - -- Forum: A discussion board (analogous to a forum or channel) that groups - posts and moderation controls. -- Post: Top-level user content created within a forum. -- Comment: A reply to a `Post` or other `Comment` (threaded discussion). -- Participant: Any actor able to publish or consume messages (anonymous or - wallet-backed). -- Anonymous session: A browser-generated ed25519 keypair used as - identity for a user without a wallet. - - -## Specification - -The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, -“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and -“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). - -OpChan uses [10/WAKU](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) -as the transport for peer-to-peer distribution of messages, -as [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md). -The messages are cryptographically signed using ed25519 keys generated locally in the broswer window. -Wallet users MAY create a token signed by the wallet's private key. - -OpChan messages fall into two broad classes: - -1. Content messages -2. Control messages - -Message routing and -discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). - -### Message Format (high-level) - -All messages transmitted over the Waku network MUST include the following envelope fields: - -``` js - -id: string -type: enum { CELL_CREATED, POST_CREATED, COMMENT_CREATED, VOTE, BOOKMARK, MODERATION, DELEGATION } -timestamp: uint64 -author: string // author public key or wallet address -signature: bytes // ed25519 signature of the canonical serialized body -delegationProof?: bytes // optional wallet signature authorizing the browser key -body: object // - -``` - -Rules for signing: - -1. Serialize `body` fields in stable key order (JSON canonical form or - protobuf deterministic encoding). -2. Construct signing bytes with: `type`, `timestamp`, `author` -3. Sign with the browser key registered for the session. - -OpChan MUST verify the `signature` against the `author` and, -when present, verify `delegationProof`. - -### Identity - -There are two types of identity options, -anonymous session and wallet delegation. -An anonymous session generates an ed25519 keypair locally with the client. -The key is used to sign all messages. -- The session may include a Call Sign. *** -A wallet delegation connects a user's wallet to OpChan. -The wallet produces a short-lived delegation signature as the key. -That delegation proof is attached to each message and -verified is by peers in the network. - -#### Delegation flow: - -1. Client generates a new ed25519 keypair and a delegation request. -2. Wallet signs the delegation request and returns a `delegationProof` with an - expiration `timestamp`. -3. The client stores the `delegationProof`, `browserKey`, -and `expiry`. -The `delegationProof` SHOULD be included in outgoing messages until `expiry`. - -- `delegationProof` verification, -verify the wallet signature over the delegation request matches the wallet public key, -the `author` public key in messages - -### Moderation & Permissions - - -A post has metadata (id, name, -creator, admins, admins can moderate (hide, remove, or penalize content within the forum). - -Moderation events are control messages with types like `MODERATION_ACTION`: - -- action: enum { HIDE, REMOVE, PIN, UNPIN, CHANGE_OWNERSHIP }, - -Moderation messages MUST be signed by a recognized post admin. -Clients MUST validate the admin membership before applying moderation actions locally. - - -OpChan - -- posts -- comments -- votes -- users (identities, call signs, delegation proofs) -- bookmarks -- moderations - -Incoming Waku messages are validated - -If delegation is revoked, -peers should ignore subsequent messages from the revoked delegation key. - -## Copyright - -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). - -## References -- [10/WAKU](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) -- [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) -- - - From b73d5fff413db09fe5d431eaee50d50ac38be097 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Sun, 21 Dec 2025 20:40:19 -0500 Subject: [PATCH 034/174] Fix issues in OpChan.md --- standards/application/OpChan.md | 71 +++++++++++++++++---------------- 1 file changed, 37 insertions(+), 34 deletions(-) diff --git a/standards/application/OpChan.md b/standards/application/OpChan.md index 4e4e5ad..0933beb 100644 --- a/standards/application/OpChan.md +++ b/standards/application/OpChan.md @@ -16,16 +16,16 @@ OpChan is a decentralized forum application built on the Waku protocol. ## Background -In a decentralized forum content is hosted on multiple nodes, -making it difficult for user's post to be censorship resistant. +In a decentralized forum, content is hosted on multiple nodes, +making it difficult for a user's post to be censored. Users own their post data, so data cannot be removed by a third party, and forum boards will not rely on moderators remaining active. OpChan is a web application hosted by some party through a web server. -The content being published by users are not stored by the server, +The content being published by users is not stored by the server, but by distributing the messages peer to peer. OpChan supports ephemeral anonymous web sessions, -supporting a locally generated ED25519 keypairs for identity and +supporting a locally generated ED25519 key pair for identity and signing. Wallet-backed identities, identity key delegation, and content stored locally while distributing messages using the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocol. @@ -49,40 +49,40 @@ The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL N “OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). OpChan uses the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) -network for the distribution forum content amongst peers. +network for the distribution of forum content amongst peers. The messages, which are [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) objects, are cryptographically signed using ED25519 keys generated by the client locally. Users SHOULD use the [19WAKU2-LIGHTPUSH]() protocol to send messages to Waku nodes storing the forum's content. OpChan supports two types of messages, content and control messages. -Content messages are user generated content on the forum. +Content messages are user-generated content on the forum. The message types include the following: -- Channel: Metadata information like name, description, admins of a forum board. +- Channel: Metadata information like name, description, and admins of a forum feed. - Post: User content created within a cell. - Comment: Users reply to a post or another comment. - Vote: To cast upvote or downvote for a post or comment. -- User: Includes username, delegation proofs and identities. -See [identities](#identities) for more information. +- User: Includes username, delegation proofs, and identities. +See the [Identity](#identity) section for more information. - Bookmark: A user bookmarking a post or comment. Control messages consist of the user activity/interactions on the forum. -This includes the manage of the current forum state, +This includes the management of the current forum state, permissions, and moderations. The message types include the following: - Create Channel: The initial event of creating a new channel within the forum. - Delegation Events: Channel admins granting or revoking channel rights. -- Moderation Events: Channel admins able to hide, remove and +- Moderation Events: Channel admins are able to hide, remove, and pin/unpin a post or comment. - Also can promote new admins and change the ownership of a channel. + Also, it can promote new admins and change the ownership of a channel. ### Message Format Message routing and discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). -Each content are assigned a `pubsub_topic` that clients MUST subscribe to discovery messages of from the channel. +Each content is assigned a `pubsub_topic` that clients MUST subscribe to discovery messages from the channel. All messages transmitted over the Waku network MUST include the following envelope fields: @@ -107,20 +107,20 @@ Signing Flow: 1. Serialize `body` fields in stable key order. 2. Construct signing bytes with: `type`, `timestamp`, `author` and `body`. -3. Sign with the user's cryptograhic keys for the session. +3. Sign with the user's cryptographic keys for the session. - channel admin -### Identities +### Identity There are two types of identities for users, anonymous session and wallet delegation. A wallet delegation MAY be an ENS(Ethereum Name Service) verified user. -An anonymous session generates an ed25519 keypair locally with the client. +An anonymous session generates an Ed25519 keypair locally with the client. The key is used to sign all messages and a username MAY choose a username attached to the post or comments. -An anonymous user SHOULD NOT granted an admin role, -create moderation events or create a channel. +An anonymous user SHOULD NOT be granted an admin role, +create moderation events, or create a channel. A wallet delegation uses the user's wallet private key to sign a delegation message, the `delegationProof`. @@ -132,7 +132,7 @@ without the need for repeated wallet prompts requesting to sign. #### Delegation Flow: -1. The client generates a new `browserKey`, which is a ED25519 keypair. +1. The client generates a new `browserKey`, which is an Ed25519 keypair. 2. The client generates a delegation request to authorize `browserKey` to sign. 3. The user's wallet signs the delegation request and returns a `delegationProof` with an expiration timestamp, `expiry`. @@ -156,41 +156,41 @@ The moderation types include: - `CHANGE_OWNERSHIP` : Change the `author` of a post or comment. Moderation messages MUST be signed by an admin, -which recognized `author` of the channel. +which recognized the `author` of the channel. Clients SHOULD validate the admin before applying moderation events locally. ### Relevance Score A post can gain better visibility on the forum channel and the forum's search through the content relevance score. -Clients with verified wallet identities MUSt be favored when anonymous session. +Clients with verified wallet identities MUST be favored over an anonymous session identity. There are a few RECCOMENDED areas that collect points when calculating the relevance score of a post: -Basic scores include the activites that each user is albe to engage in. +Basic points include the activities that each user is able to engage in. - A channel has a score value of 15 - Each post within a channel has a score value of 10 -- A base value if comments are present within a post boost the relevance score by a value of 5 +- A base value if comments are present within a post boosts the relevance score by a value of 5 -Engagement score include different user activites for each post or comment. +Engagement points include the different user activities for each post or comment. - Each wallet delegation upvote adds a score value of 1. -- Each comment indiviual comment adds a score value of 0.5. -- The total number of of post multipled by 0.5. -The total number of upvotes multiped by 0.1. +- Each individual comment adds a score value of 0.5. +- The total number of posts multiplied by 0.5. +The total number of upvotes multiplied by 0.1. These two values are added together. -For identity verification scores, -participants of post or comment that use wallet-based identities, +For identity verification points, +participants of posts or comments that use wallet-based identities, including an optional ENS, the score is boosted over the anonymous identities. If a participant has a verified ENS and a verified connected wallet, -only the ENS multipler SHOULD be applied. +only the ENS multiplier SHOULD be applied. -- Participants of who has a verified ENS name gains a value multiplier of 1.25(25%). +- Participants who have a verified ENS name gain a value multiplier of 1.25(25%). - For wallet connect participant the multiplier is 1.1(10%). -- For verified upvote participants the multipler is 0.1. +- For verified upvote participants the multiplier is 0.1. - For verified comment participants the multiplier is 0.05. There is a time decay that reduces the relevance score over time. @@ -211,9 +211,12 @@ $$ 1, & \text{otherwise} \end{cases} $$ -Total +Below is the final relevance score based on the RECCOMENDED points above: -RelevanceScore = (basic + engagement + verifiedUpvote) * (1 + verifyIdentity) * timeDecay * moderationPenalty +$$ +\text{Total RelevanceScore} = (\text{basic} + \text{engagement} + \text{verifiedUpvote}) +\cdot (1 + \text{verifyIdentity}) \cdot \text{timeDecay} \cdot \text{moderationPenalty} +$$ ## Copyright From de0720a38c4c62d500c2a02e82ee6e975798da7c Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Mon, 22 Dec 2025 18:07:37 -0500 Subject: [PATCH 035/174] Fixes op-chan --- standards/application/OpChan.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/standards/application/OpChan.md b/standards/application/OpChan.md index 0933beb..12cc8a1 100644 --- a/standards/application/OpChan.md +++ b/standards/application/OpChan.md @@ -34,7 +34,7 @@ content stored locally while distributing messages using the [10/WAKU2](https:// ## Terminology -- Cell: A discussion board or channel that hosts posts and moderation controls. +- Channel: A discussion board or channel that hosts posts and moderation controls. - Post: User content created within a forum. - Comment: A reply to a `Post` or other `Comment` (threaded discussion). - Participant: Any user able to publish or consume messages (anonymous or @@ -51,16 +51,16 @@ The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL N OpChan uses the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) network for the distribution of forum content amongst peers. The messages, which are [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) objects, -are cryptographically signed using ED25519 keys generated by the client locally. -Users SHOULD use the [19WAKU2-LIGHTPUSH]() protocol to send messages to Waku nodes storing the forum's content. +are cryptographically signed using Ed25519 keys generated by the client locally. +Users SHOULD use the [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) protocol to send messages to Waku nodes storing the forum's content. OpChan supports two types of messages, content and control messages. Content messages are user-generated content on the forum. The message types include the following: -- Channel: Metadata information like name, description, and admins of a forum feed. -- Post: User content created within a cell. +- Channel: Includes the metadata information like name, description, and admins of a forum feed. +- Post: User content created within a channel. - Comment: Users reply to a post or another comment. - Vote: To cast upvote or downvote for a post or comment. - User: Includes username, delegation proofs, and identities. @@ -89,17 +89,17 @@ All messages transmitted over the Waku network MUST include the following envelo ``` js { "id": "string", - "type": "CELL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", + "type": "CHANNEL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", "timestamp": "uint64" "author": "string" // author public key or wallet address - "signature": "bytes" // ed25519 signature of the canonical serialized body + "signature": "bytes" // ed25519 signature "delegationProof": "bytes" // optional wallet signature authorizing the browser key "body": object // The message content } ``` -Every message SHOULD be signed using ED25519 keys from the publishing user. +Every message SHOULD be signed using `signature` owned by the publishing user. Clients SHOULD verify the signature against the `author` public key and, when present, verify `delegationProof`. @@ -107,9 +107,7 @@ Signing Flow: 1. Serialize `body` fields in stable key order. 2. Construct signing bytes with: `type`, `timestamp`, `author` and `body`. -3. Sign with the user's cryptographic keys for the session. - -- channel admin +3. Sign with the user's cryptographic keys, `signature`, for the session. ### Identity @@ -122,10 +120,10 @@ a username MAY choose a username attached to the post or comments. An anonymous user SHOULD NOT be granted an admin role, create moderation events, or create a channel. -A wallet delegation uses the user's wallet private key to sign a delegation message, -the `delegationProof`. +A wallet delegation is a user blockchain wallet's private key used to sign a message, +which is the `delegationProof`. The `delegationProof` SHOULD be a short-lived message, -RECCOMENDED a few minutes to a few hours. +RECOMMENDED a few minutes to a few hours. Once a `delegationProof` is generated, the client SHOULD be able to sign messages, without the need for repeated wallet prompts requesting to sign. @@ -165,7 +163,7 @@ A post can gain better visibility on the forum channel and the forum's search through the content relevance score. Clients with verified wallet identities MUST be favored over an anonymous session identity. -There are a few RECCOMENDED areas that collect points when calculating the relevance score of a post: +There are a few RECOMMENDED areas that collect points when calculating the relevance score of a post: Basic points include the activities that each user is able to engage in. @@ -204,14 +202,14 @@ Where $$\( -\lambda \)$$ is the time-decay rate per day. There SHOULD be a moderation penalty that reduces the score when a post or comment is moderated with a value of 0.5(50%). -This penalty is applied once a post is `HIDDEN`, `REMOVED` or `FLAGGED` by a moderator. +This penalty is applied once a post is `HIDDEN`, `REMOVED` or flagged by users to be reviewed by a moderator. $$ \text{moderationPenalty} = \begin{cases} 0.5, & \text{if moderated} \\ 1, & \text{otherwise} \end{cases} $$ -Below is the final relevance score based on the RECCOMENDED points above: +Below is the final relevance score based on the RECOMMENDED points above: $$ \text{Total RelevanceScore} = (\text{basic} + \text{engagement} + \text{verifiedUpvote}) @@ -224,6 +222,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References - [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) +- [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) - [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) - [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) - From a2584bf8c25093450ff2dea6a1a3e1c6a3bec946 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Mon, 26 Jan 2026 15:27:14 -0300 Subject: [PATCH 036/174] rename health status to connection status --- standards/application/waku-api.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 2d5b889..3cb9a45 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -30,7 +30,7 @@ contributors: * [Predefined values](#predefined-values) * [Extended definitions](#extended-definitions) * [The Validation API](#the-validation-api) - * [Health Status](#health-status) + * [Connection Status](#connection-status) * [Event Source](#event-source) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -315,30 +315,30 @@ that would contain all validation parameters including RLN. In the time being, parameters specific to RLN are accepted for the message validation. RLN can also be disabled. -## Health Status +## Connection Status #### Type definitions ```yml types: - HealthStatus: + ConnectionStatus: type: enum - values: [Unhealthy, MinimallyHealthy, Healthy] + values: [Disconnected, PartiallyConnected, Connected] description: "Used to identify health of the operating node" ``` #### Extended definitions -`Unhealthy` indicates that the node has lost connectivity for message reception, +`Disconnected` indicates that the node has lost connectivity for message reception, sending, or both, and as a result, it cannot reliably receive or transmit messages. -`MinimallyHealthy` indicates that the node meets the minimum operational requirements: +`PartiallyConnected` indicates that the node meets the minimum operational requirements: it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), one peer with a protocol to receive messages ([FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), and one peer with [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) service capabilities, although performance or reliability may still be impacted. -`Healthy` indicates that the node is operating optimally, +`Connected` indicates that the node is operating optimally, with full support for message reception and transmission. ## Event Source @@ -347,7 +347,7 @@ with full support for message reception and transmission. ```yaml types: - HealthStatusEvent: + ConnectionStatusEvent: type: object fields: eventType: @@ -355,8 +355,8 @@ types: default: "health" description: "Event type identifier" status: - type: HealthStatus - description: "Node health status emitted on state change" + type: ConnectionStatus + description: "Node connection status emitted on state change" EventSource: type: object @@ -367,7 +367,7 @@ EventSource: description: "Callback for captured events" parameters: - name: event - type: HealthStatusEvent + type: ConnectionStatusEvent ``` ## Security/Privacy Considerations From 21b8c471fb37300cfb70046e6c39e4d4c964d82c Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Fri, 30 Jan 2026 10:50:12 -0300 Subject: [PATCH 037/174] bless spell-checking failures into .wordslist.txt --- .wordlist.txt | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 8e754de..3764e71 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,8 +1,39 @@ +ABIs +addListener ALLOC +api +AsyncAPI +autosharding +AutoShardingConfig +bool +camelCase +cd +config +ConnectionStatus +ConnectionStatusEvent +contentTopic +createNode creativecommons danielkaiser +DefaultAutoShardingConfig +DefaultMessageValidation +DefaultNetworkingConfig +dev DHT +discv +DISCV DoS +enrtree +enum +Eth +eth +ETH +EventEmitter +EventSource +eventType +fb +fBF +getMerkleRoot github GITHUB gossipsub @@ -10,14 +41,68 @@ GossipSub https iana IANA +IDL +implementor +ipv +iterable +KiB +Kozlov +libp libp2p +LIGHTPUSH md +MessageEnvelope +MessageErrorEvent +MessageEvents +MessagePropagatedEvent +MessageSentEvent +MessageValidation +multiaddr +NetworkConfig +NetworkingConfig +nim +NodeConfig +nodeConfig +num +Oleksandr +onEvent +OpenAPI +PartiallyConnected +PascalCase +Prathi +Prem +pre +ProtocolsConfig pubsub +RequestId rfc RFC +RLN +rln +RlnConfig +Royer +RPC +rpc SHARDING +sharding subnets +TBD +tcp +TCP +TheWakuNetworkMessageValidation +TheWakuNetworkPreset +TODO +TWN +udp +UDP +uint Waku +waku WAKU +WakuNode www +xB +yaml +YAML +yml ZXCV \ No newline at end of file From 25b95be951713364e3edec5701023cb86354283d Mon Sep 17 00:00:00 2001 From: Prem Chaitanya Prathi Date: Tue, 3 Feb 2026 15:29:13 +0530 Subject: [PATCH 038/174] fix broken links in mix rfc --- standards/core/mix.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/standards/core/mix.md b/standards/core/mix.md index f75d851..e00264c 100644 --- a/standards/core/mix.md +++ b/standards/core/mix.md @@ -1,10 +1,10 @@ --- title: WAKU-MIX name: Waku Mix -editor: Prem Chaitanya Prathi +editor: Prem Chaitanya Prathi contributors: - - Akshaya Mani - - Hanno Cornelius + - Akshaya Mani + - Hanno Cornelius --- ## Tags @@ -12,7 +12,8 @@ contributors: `waku/core-protocol` # Abstract -The document describes [libp2p mix](https://rfc.vac.dev/vac/raw/mix/) integration into waku. + +The document describes [libp2p mix](https://lip.logos.co/ift-ts/raw/mix.html) integration into waku. This integration provides higher anonymity for users publishing or querying for messages to/from the Waku network. This document covers integration of mix with [lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) and [store](https://rfc.vac.dev/waku/standards/core/13/store) protocols. @@ -38,6 +39,7 @@ This network of mix nodes SHALL relay mix messages anonymously to the recepient. Anonymity of [Filter](https://rfc.vac.dev/waku/standards/core/12/filter) users is not addressed by this document. ## Terminology + The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -79,15 +81,18 @@ Resource-restricted/Edge nodes with short connection windows MUST _only_ act as Each waku node that supports the `mix intermediary or exit role` SHOULD indicate the same in its discoverable [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). The following fields MUST be set as part of the discoverable ENR of a mix waku node: + - The `bit 5` in the [waku2 ENR key](https://github.com/waku-org/specs/blob/master/standards/core/enr.md#waku2-enr-key) is reserved to indicate `mix` support. This bit MUST be set to true to indicate `mix` support. - A new field `mix-key` SHOULD be set to the `ed25519 public key` which is used for sphinx encryption. -Adding these fields to the ENR may cause the ENR size to cross the 300 byte limit especially in case a node supports multiple transports. +Adding these fields to the ENR may cause the ENR size to cross the 300 byte limit especially in case a node supports multiple transports. This limitation will have to be addressed in future. + ### Discovery Mix protocol provides better anonymity when a sender node has a sufficiently large pool of mix nodes to do path selection. This moves the problem into discovery domain and requires the following from discovery mechanisms: + 1. It is important for nodes to be able to discover as many nodes as possible quickly. This becomes especially important for edge nodes that come online just to publish/query messages for a short period of time. 2. The discovery mechanism MUST be unbiased and not biased toward specific subsets (e.g., nodes that are topologically closer). 3. It is important to have the most recent online status of the nodes so that mix paths that are selected are not broken which lead to reliability issues. @@ -101,15 +106,16 @@ Mix protocol in waku network SHOULD have `rate-limiting/spam` protection to hand 1. Any node can generate a mix packet and publish into the mix network. Hence there needs to be some validation as to who is allowed to publish and whether the user is within allowed rate-limits. 2. Any node can intentionally generate paths which are broken and send messages into the mix network. -3. An attacker can spawn a huge number of mix nodes so that user behaviour is observed in order to determine traffic patterns and deanonymize users. +3. An attacker can spawn a huge number of mix nodes so that user behaviour is observed in order to determine traffic patterns and deanonymize users. -There is a need to enforce rate-limits and spam protect the mix network. +There is a need to enforce rate-limits and spam protect the mix network. The rate-limiting and spam protection shall be addressed as part of future work. ## Tradeoffs Using `mix` protocol for publishing and querying messages adds certain overhead which is primarily the delay in delivering message to the destination. The overall additional delay `D` depends on the following params: + - path length `L` - delay added by each intermediary node `dm` - connection establishment time `dc` @@ -129,8 +135,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). ## References - - [libp2p mix](https://rfc.vac.dev/vac/raw/mix/) - - [waku lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) - - [waku relay](https://rfc.vac.dev/waku/standards/core/11/relay) - - [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) - - [sphinx encryption](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf) \ No newline at end of file + +- [libp2p mix](https://lip.logos.co/ift-ts/raw/mix.html) +- [waku lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) +- [waku relay](https://rfc.vac.dev/waku/standards/core/11/relay) +- [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) +- [sphinx encryption](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf) From 92dc20de9fdd38c8b4ad1984fd96a056954459aa Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 09:14:29 -0300 Subject: [PATCH 039/174] add unsubscribe --- standards/application/waku-api.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index b1494be..d75479f 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -323,6 +323,9 @@ types: "error:subscribe": type: string description: "Event emitted when subscription to a content topic irremediably fails. The event contains an error message." + "error:unsubscribe": + type: string + description: "Event emitted when unsubscribing from a content topic irremediably fails. The event contains an error message." # Extending `WakuNode` definition WakuNode: fields: @@ -364,6 +367,14 @@ functions: description: "The content topics for the node to subscribe to." returns: type: void + unsubscribe: + description: "Unsubscribe from specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to unsubscribe from." + returns: + type: void ``` #### Predefined values @@ -382,9 +393,11 @@ Only messages on subscribed content topics SHOULD be emitted by `messageEmitter` **`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; +Failure to reach nodes can be omitted, and should be handled via the health events; [P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. +An `"error:unsubscribe"` is emitted if there is no content topic subscription to unsubscribe from, or ongoing content topic subscription attempt to cancel. + Examples of irremediable failures are: - Invalid content topic format From 6792b0113c519d36ff50c0f5d4b245b1176a02ef Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 13:50:57 -0300 Subject: [PATCH 040/174] bless spellchecking failures --- .wordlist.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 3764e71..306b9c5 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -12,6 +12,7 @@ config ConnectionStatus ConnectionStatusEvent contentTopic +contentTopics createNode creativecommons danielkaiser @@ -38,11 +39,15 @@ github GITHUB gossipsub GossipSub +HealthConnectionStatusEvent +healthEvents +HealthEvents https iana IANA IDL implementor +Init ipv iterable KiB @@ -54,7 +59,11 @@ md MessageEnvelope MessageErrorEvent MessageEvents +messageEvents MessagePropagatedEvent +MessageReceivedEvent +MessageSendErrorEvent +MessageSendPropagatedEvent MessageSentEvent MessageValidation multiaddr @@ -86,6 +95,9 @@ rpc SHARDING sharding subnets +SubscriptionErrorEvent +subscriptionEvents +SubscriptionEvents TBD tcp TCP From 75bcb711d55411b10eba7c4d4497baffef923afb Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:09:48 -0300 Subject: [PATCH 041/174] add SubscribeAction enum instead of bool sub/unsub field to error --- standards/application/waku-api.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 3033d42..6e9c32e 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -456,6 +456,11 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat ```yaml types: + SubscribeAction: + type: enum + values: [Subscribe, Unsubscribe] + description: "Defines the subscription action that was performed" + SubscriptionErrorEvent: type: object description: "Event emitted when a content topic subscription-related operation fails" @@ -463,9 +468,9 @@ types: content-topic: type: string description: "Content topic that the node failed to subscribe to or unsubscribe from" - subscribe: - type: bool - description: "True if failed to subscribe, false if failed to unsubscribe instead" + action: + type: SubscribeAction + description: "Defines the subscription action that was attempted" error: type: string description: "Error message describing what went wrong" From aa27f464c2a4bb3cf2854f0a44dcf19ab14b6fb3 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:10:28 -0300 Subject: [PATCH 042/174] Update standards/application/waku-api.md Co-authored-by: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 6e9c32e..16cbbbd 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -495,7 +495,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: void + type: result unsubscribe: description: "Unsubscribe from specific content topics" From 71e26dd1ee13fc6395a5a17a7cbaced2564ed552 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:12:49 -0300 Subject: [PATCH 043/174] Use distinct ContentTopic string type Co-authored-by: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 16cbbbd..5dc17a8 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -501,7 +501,7 @@ functions: description: "Unsubscribe from specific content topics" parameters: - name: contentTopics - type: Array + type: Array description: "The content topics for the node to unsubscribe from." returns: type: void From 198501b8d8fdf52cc46a50ac24ceafeeec824d80 Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:18:08 -0300 Subject: [PATCH 044/174] Remove confusing "binary" qualifier from checkApiAvailability desc Co-authored-by: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 5dc17a8..426f538 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -567,7 +567,7 @@ types: functions: check-api-availability: - description: "Get current binary connectivity status" + description: "Get current connectivity status" parameters: - name: waku type: WakuNode From bba2661f30fcff5c72024bd058758c07753b3c8d Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Tue, 3 Feb 2026 16:24:54 -0300 Subject: [PATCH 045/174] bless `SubscribeAction` spellcheck failure --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index 306b9c5..c22e798 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -95,6 +95,7 @@ rpc SHARDING sharding subnets +SubscribeAction SubscriptionErrorEvent subscriptionEvents SubscriptionEvents From 42d860d385b563fbaebe79b4070776454a976a2b Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Wed, 4 Feb 2026 08:14:16 -0300 Subject: [PATCH 046/174] Fixes from Ivan's review * Use sync impl awareness for subscription proc sync results * Delete subscription event source (for now) * Remove checkApiAvailability --- standards/application/waku-api.md | 32 +++++-------------------------- 1 file changed, 5 insertions(+), 27 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 426f538..fa8d93c 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -144,9 +144,6 @@ types: messageEvents: type: MessageEvents description: "The node's messaging event emitter" - subscriptionEvents: - type: SubscriptionEvents - description: "The node's content-topic subscription event emitter" healthEvents: type: HealthEvents description: "The node's health monitoring event emitter" @@ -456,21 +453,13 @@ The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strat ```yaml types: - SubscribeAction: - type: enum - values: [Subscribe, Unsubscribe] - description: "Defines the subscription action that was performed" - - SubscriptionErrorEvent: + SubscriptionError: type: object - description: "Event emitted when a content topic subscription-related operation fails" + description: "A content topic subscription-related operation failed synchronously and irremediably" fields: content-topic: type: string description: "Content topic that the node failed to subscribe to or unsubscribe from" - action: - type: SubscribeAction - description: "Defines the subscription action that was attempted" error: type: string description: "Error message describing what went wrong" @@ -495,7 +484,7 @@ functions: type: Array description: "The content topics for the node to subscribe to." returns: - type: result + type: result> unsubscribe: description: "Unsubscribe from specific content topics" @@ -504,7 +493,7 @@ functions: type: Array description: "The content topics for the node to unsubscribe from." returns: - type: void + type: result> ``` #### Subscriptions extended definitions @@ -563,18 +552,7 @@ types: #### Health function definitions -```yml -functions: - - check-api-availability: - description: "Get current connectivity status" - parameters: - - name: waku - type: WakuNode - description: "The node to check for a binary connectivity status." - returns: - type: result -``` +TODO #### Health extended definitions From aeddb7f9e7a640ec522463a15cb50fe9cd508b1a Mon Sep 17 00:00:00 2001 From: Fabiana Cecin Date: Wed, 4 Feb 2026 08:28:57 -0300 Subject: [PATCH 047/174] Remove dead IDL code, fix sync subscr error text, fix wordslist --- .wordlist.txt | 5 +---- standards/application/waku-api.md | 9 +-------- 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index c22e798..3d89df4 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -95,10 +95,7 @@ rpc SHARDING sharding subnets -SubscribeAction -SubscriptionErrorEvent -subscriptionEvents -SubscriptionEvents +SubscriptionError TBD tcp TCP diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index fa8d93c..fe633ff 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -463,13 +463,6 @@ types: error: type: string description: "Error message describing what went wrong" - - SubscriptionEvents: - type: event_emitter - description: "Event source for subscription-related events." - events: - "subscription:error": - type: SubscriptionErrorEvent ``` #### Subscriptions function definitions @@ -509,7 +502,7 @@ Only messages on subscribed content topics SHOULD be emitted by a `MessageEvents **`error`**: -Only irremediable failures should lead to emitting a `"subscription:error"` for failed subscribe or unsubscribe operations. +Only irremediable failures should lead to synchronously returning a subscription error for failed subscribe or unsubscribe operations. Failure to reach nodes can be omitted, and should be handled via the health events; [P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. From f07c5b170c1b70598e618339025a78570462e748 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:13:01 -0800 Subject: [PATCH 048/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index d8fda70..f67ad69 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -113,7 +113,7 @@ The core of an initialization protocol is a defined location and procedure for r Many chat protocols choose to define the initialization protocol within the conversation protocol. This tight coupling produces two negative artifacts. - New conversation protocols must define and deploy there own initialization channels. Increasing overhead and adding complexity. -- New protocol upgrades then create partitions in the communication network, as older clients have no means of communicating with new clients. +- Protocol upgrades then create partitions in the communication network, as older clients have no means of communicating with new clients. Separating channel initialization from conversation flow allows multiple conversations to reuse the same initialization channel. This reduces effort for new conversation protocols, and is especially valuable when upgrading existing ones. Being independent the initialization pathway can persist across conversation versions. Even if an older client cannot parse new message types, it can still recognize their presence, adding observability. From 8235742ed95e9367c8df6b6fb02b395b7aac1ba6 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:13:09 -0800 Subject: [PATCH 049/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index f67ad69..90a6aa8 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -20,7 +20,7 @@ With the vast amount of information required to maintain compatibility between a # Theory / Semantics -This specification defines a abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. +This specification defines an abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. The chat protocol is be decomposed into 3 distinct phases. From c00e4e14f8f09f10e0399212a5119b720bd56670 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:13:31 -0800 Subject: [PATCH 050/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 90a6aa8..9fafeec 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -31,7 +31,7 @@ The chat protocol is be decomposed into 3 distinct phases. and transport details are divided into: -- **Delivery Service:** How are payloads are routed and delivered to a client. +- **Delivery Service:** How are payloads routed and delivered to a client. - **Framing Strategy:** How are payloads encoded. Defining these 5 parameters allows for chat protocol implementations to be fully defined, which allows clients from different applications to exchange messages. From b29e7573b88d1721e2a65315afa500822a4e5be6 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:13:39 -0800 Subject: [PATCH 051/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 9fafeec..408f8e9 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -44,7 +44,7 @@ A Delivery Service (DS) is the service or method that distributes payloads to cl #### Requirements -- -A DS MUST provide a method for clients to subscribe to messages from a delivery_address +- A DS MUST provide a method for clients to subscribe to messages from a delivery_address - Payloads sent to a delivery_address are delivered by a DS to all subscribers of that delivery_address - A DS MAY NOT guarantee message delivery - A DS MAY NOT guarantee message ordering From daf90fcfa0136956f6347863a42ac83ab11c0983 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:14:08 -0800 Subject: [PATCH 052/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 408f8e9..0f33ac7 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -54,7 +54,7 @@ A Delivery Service (DS) is the service or method that distributes payloads to cl In this protocol framework, payloads from multiple protocols are potentially multiplexed over the same channel. This requires that clients are able to associate a given payload to a given instance of a protocol. -A framing strategy should define a common payload type as well as a method to determine which state machine a receiving client must used to decode it. +A framing strategy should define a common payload type as well as a method to determine which state machine a receiving client must use to decode it. ## Protocol Components From efe7774c606d3f6850023842afb8d9518d5776a2 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:14:39 -0800 Subject: [PATCH 053/174] Apply suggestion from @igor-sirotin Co-authored-by: Igor Sirotin --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 0f33ac7..7a2c586 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -103,7 +103,7 @@ The output requirements of the discovery protocol are very implementation specif - The discovery protocol MUST provide all data required for the initialization protocol. -Note: There is no requirement that the Discovery protocol be a complicated nor interactive process. Hypothetically If all required values to construct a IntroductionBundle could be statically defined, that would be sufficient for this definition. +Note: There is no requirement that the Discovery protocol be neither a complicated nor interactive process. Hypothetically If all required values to construct a IntroductionBundle could be statically defined, that would be sufficient for this definition. ### Initialization Protocol From 21af11f55f53f443322bd6f0dcf29075a842ff45 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 6 Feb 2026 08:15:45 +0700 Subject: [PATCH 054/174] fixups --- standards/application/chat-framework.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 7a2c586..5f9b187 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -23,7 +23,7 @@ With the vast amount of information required to maintain compatibility between a This specification defines an abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. -The chat protocol is be decomposed into 3 distinct phases. +The chat protocol is decomposed into 3 distinct phases. - **Discovery:** How does a Sender learn of other clients. - **Initialization:** How does a Recipient learn a client wants to communicate with them. From ea0b56ed07c88fee98607752312015a60be46e2d Mon Sep 17 00:00:00 2001 From: Cofson Date: Thu, 5 Feb 2026 18:53:03 +0100 Subject: [PATCH 055/174] chore: address review feedback for OpChan RFC - Make spec transport-agnostic, add "Waku as Delivery Mechanism" section - Remove platform-specific language (web application) - Add ED25519 reference link (RFC 8032) - Clarify FLAGGED (user-initiated) vs admin moderation - Fix typo delegrationProof -> delegationProof - Use reference-style links for cleaner body text - Fix linting issues (trailing spaces, list markers) --- standards/application/OpChan.md | 131 ++++++++++++++++++-------------- 1 file changed, 76 insertions(+), 55 deletions(-) diff --git a/standards/application/OpChan.md b/standards/application/OpChan.md index 12cc8a1..29b6eb4 100644 --- a/standards/application/OpChan.md +++ b/standards/application/OpChan.md @@ -4,15 +4,17 @@ name: OpChan Decentralized Forum status: raw category: Standards Track tags: waku -editor: +editor: contributors: - Jimmy Debe --- ## Abstract -This document specifies the architecture of OpChan. -OpChan is a decentralized forum application built on the Waku protocol. +This document specifies the architecture of OpChan, +a decentralized forum application. +The specification is transport-agnostic, +with Waku as the reference delivery mechanism. ## Background @@ -21,16 +23,11 @@ making it difficult for a user's post to be censored. Users own their post data, so data cannot be removed by a third party, and forum boards will not rely on moderators remaining active. -OpChan is a web application hosted by some party through a web server. -The content being published by users is not stored by the server, -but by distributing the messages peer to peer. -OpChan supports ephemeral anonymous web sessions, -supporting a locally generated ED25519 key pair for identity and -signing. -Wallet-backed identities, identity key delegation, and -content stored locally while distributing messages using the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocol. - -- WAKU-LIGHTPUSH +OpChan clients distribute content through a peer-to-peer network +rather than relying on centralized server storage. +OpChan supports ephemeral anonymous sessions +using a locally generated [ED25519][ed25519] key pair for identity and signing. +Additionally, OpChan supports wallet-backed identities and identity key delegation. ## Terminology @@ -44,21 +41,18 @@ content stored locally while distributing messages using the [10/WAKU2](https:// ## Specification -The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, -“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and -“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in [RFC 2119][rfc2119]. -OpChan uses the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) -network for the distribution of forum content amongst peers. -The messages, which are [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) objects, -are cryptographically signed using Ed25519 keys generated by the client locally. -Users SHOULD use the [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) protocol to send messages to Waku nodes storing the forum's content. +OpChan distributes forum content amongst peers using a publish-subscribe messaging layer. +All messages are cryptographically signed using [ED25519][ed25519] keys generated by the client locally. OpChan supports two types of messages, content and control messages. Content messages are user-generated content on the forum. The message types include the following: - + - Channel: Includes the metadata information like name, description, and admins of a forum feed. - Post: User content created within a channel. - Comment: Users reply to a post or another comment. @@ -72,23 +66,21 @@ This includes the management of the current forum state, permissions, and moderations. The message types include the following: -- Create Channel: The initial event of creating a new channel within the forum. -- Delegation Events: Channel admins granting or revoking channel rights. -- Moderation Events: Channel admins are able to hide, remove, and - pin/unpin a post or comment. - Also, it can promote new admins and change the ownership of a channel. +- Create Channel: The initial event of creating a new channel within the forum. +- Delegation Events: Channel admins granting or revoking channel rights. +- Moderation Events: Channel admins are able to hide, remove, pin/unpin a post or comment, + promote new admins, and change the ownership of a channel. ### Message Format -Message routing and -discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). -Each content is assigned a `pubsub_topic` that clients MUST subscribe to discovery messages from the channel. +Each channel is assigned a unique topic identifier that clients MUST subscribe to +in order to discover messages from that channel. -All messages transmitted over the Waku network MUST include the following envelope fields: +All messages MUST include the following envelope fields: ``` js { - "id": "string", + "id": "string", "type": "CHANNEL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", "timestamp": "uint64" "author": "string" // author public key or wallet address @@ -111,24 +103,24 @@ Signing Flow: ### Identity -There are two types of identities for users, +There are two types of identities for users: anonymous session and wallet delegation. -A wallet delegation MAY be an ENS(Ethereum Name Service) verified user. -An anonymous session generates an Ed25519 keypair locally with the client. +A wallet delegation MAY be an ENS (Ethereum Name Service) verified user. +An anonymous session generates an [ED25519][ed25519] keypair locally with the client. The key is used to sign all messages and -a username MAY choose a username attached to the post or comments. -An anonymous user SHOULD NOT be granted an admin role, +a username MAY be attached to the post or comments. +An anonymous user SHOULD NOT be granted an admin role, create moderation events, or create a channel. A wallet delegation is a user blockchain wallet's private key used to sign a message, which is the `delegationProof`. The `delegationProof` SHOULD be a short-lived message, -RECOMMENDED a few minutes to a few hours. +RECOMMENDED a few minutes to a few hours. Once a `delegationProof` is generated, the client SHOULD be able to sign messages, without the need for repeated wallet prompts requesting to sign. -#### Delegation Flow: +#### Delegation Flow 1. The client generates a new `browserKey`, which is an Ed25519 keypair. 2. The client generates a delegation request to authorize `browserKey` to sign. @@ -137,26 +129,33 @@ returns a `delegationProof` with an expiration timestamp, `expiry`. 4. The client stores the `delegationProof`, `browserKey`, and `expiry`. -A `delegrationProof` could become revoked by the wallet owner or +A `delegationProof` could become revoked by the wallet owner or after the `expiry` time. -If a wallet delegation is revoked, +If a wallet delegation is revoked, clients SHOULD ignore subsequent messages from the revoked delegation key. ### Moderation & Permissions -A post MAY be have moderation message types assigned by the channel admin. +A post MAY have moderation message types assigned by the channel admin. The moderation types include: -- `HIDE` : To hide a post or comment. -- `REMOVE` : To permanently remove a post or comment. -- `PIN` : To pin a post to the top of a channel feed or pin a comment to the top of a thread. -- `UNPIN` : To remove a `PIN` from a post feed or comment thread. -- `CHANGE_OWNERSHIP` : Change the `author` of a post or comment. +- `HIDE`: Hide a post or comment from the channel feed. +- `REMOVE`: Permanently remove a post or comment. +- `PIN`: Pin a post to the top of a channel feed or pin a comment to the top of a thread. +- `UNPIN`: Remove a `PIN` from a post feed or comment thread. +- `CHANGE_OWNERSHIP`: Change the `author` of a post or comment. -Moderation messages MUST be signed by an admin, -which recognized the `author` of the channel. +Moderation messages MUST be signed by an admin, +who is recognized as the `author` of the channel. Clients SHOULD validate the admin before applying moderation events locally. +#### User Flagging + +Users MAY flag content for review by moderators. +A `FLAG` is user-initiated and distinct from admin moderation actions. +Flagged content SHOULD be queued for moderator review +but does not automatically result in content removal. + ### Relevance Score A post can gain better visibility on the forum channel and @@ -204,7 +203,7 @@ There SHOULD be a moderation penalty that reduces the score when a post or comment is moderated with a value of 0.5(50%). This penalty is applied once a post is `HIDDEN`, `REMOVED` or flagged by users to be reviewed by a moderator. -$$ +$$ \text{moderationPenalty} = \begin{cases} 0.5, & \text{if moderated} \\ 1, & \text{otherwise} \end{cases} $$ @@ -216,13 +215,35 @@ $$ \cdot (1 + \text{verifyIdentity}) \cdot \text{timeDecay} \cdot \text{moderationPenalty} $$ +## Waku as Delivery Mechanism + +This section describes how OpChan MAY use the Waku protocol as the delivery mechanism. + +OpChan clients MAY use the [10/WAKU2][waku2] network for the distribution of forum content amongst peers. +The messages are [14/WAKU-MESSAGE][waku-message] objects. +Users SHOULD use the [19/WAKU2-LIGHTPUSH][waku-lightpush] protocol +to send messages to Waku nodes storing the forum's content. + +Message routing and discovery are handled by [23/WAKU2-TOPICS][waku-topics]. +Each channel is assigned a `content_topic` that clients MUST subscribe to +in order to discover messages from that channel. + ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). ## References -- [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) -- [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) -- [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) -- [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) -- + +- [RFC 2119][rfc2119] +- [ED25519][ed25519] +- [10/WAKU2][waku2] +- [14/WAKU-MESSAGE][waku-message] +- [19/WAKU2-LIGHTPUSH][waku-lightpush] +- [23/WAKU2-TOPICS][waku-topics] + +[rfc2119]: https://www.ietf.org/rfc/rfc2119.txt +[ed25519]: https://datatracker.ietf.org/doc/html/rfc8032 +[waku2]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md +[waku-message]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md +[waku-lightpush]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md +[waku-topics]: https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md From 62c783ce219c4c64f60ec4edf1a6b80afafa4dcd Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Sat, 14 Feb 2026 08:18:09 -0800 Subject: [PATCH 056/174] Chat Cast (#99) * Add chat cast * add clarity about usage * Updated roles * Update Wordlist.txt --- .wordlist.txt | 28 +++++++--- informational/chat_cast.md | 104 +++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 8 deletions(-) create mode 100644 informational/chat_cast.md diff --git a/.wordlist.txt b/.wordlist.txt index 3d89df4..1889016 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -8,6 +8,7 @@ AutoShardingConfig bool camelCase cd +centric config ConnectionStatus ConnectionStatusEvent @@ -15,6 +16,7 @@ contentTopic contentTopics createNode creativecommons +cryptographic danielkaiser DefaultAutoShardingConfig DefaultMessageValidation @@ -26,8 +28,8 @@ DISCV DoS enrtree enum -Eth eth +Eth ETH EventEmitter EventSource @@ -47,9 +49,11 @@ iana IANA IDL implementor +Inclusivity Init ipv iterable +Jazzz KiB Kozlov libp @@ -58,8 +62,8 @@ LIGHTPUSH md MessageEnvelope MessageErrorEvent -MessageEvents messageEvents +MessageEvents MessagePropagatedEvent MessageReceivedEvent MessageSendErrorEvent @@ -70,30 +74,38 @@ multiaddr NetworkConfig NetworkingConfig nim -NodeConfig nodeConfig +NodeConfig num Oleksandr onEvent OpenAPI PartiallyConnected PascalCase +Pax Prathi -Prem pre +Prem ProtocolsConfig pubsub +pubsub +Raya +Raya's RequestId +responder +rfc rfc RFC -RLN +RFC rln +RLN RlnConfig Royer -RPC rpc -SHARDING +RPC +Saro sharding +SHARDING subnets SubscriptionError TBD @@ -106,8 +118,8 @@ TWN udp UDP uint -Waku waku +Waku WAKU WakuNode www diff --git a/informational/chat_cast.md b/informational/chat_cast.md new file mode 100644 index 0000000..1965997 --- /dev/null +++ b/informational/chat_cast.md @@ -0,0 +1,104 @@ +--- +title: CHAT-CAST +name: Roles and Entities Used in Chat Protocol Documentation +status: raw +category: Informational +tags: [chat/informational] +editor: Jazzz +contributors: +--- + +## Abstract + +This document defines a reusable cast of characters to be used in chat protocol documentation and related supporting materials. +The goal is to improve clarity and consistency when describing protocol roles, actors, and message flows. + +## Background + +When documenting applications and protocols, it is often beneficial to define a consistent set of characters representing common roles. +A shared cast allows authors to convey meaning and intent quickly to readers. +Readers are not required to understand these meanings, however consistent usage can make comprehension faster to achieve. + +This approach is well established in cryptographic literature, where `Alice` and `Bob` are commonly used to describe participants in key exchange protocols. +Within that context, Alice typically initiates the exchange and Bob responds. +Readers familiar with this convention can quickly understand protocol flows without additional explanation. + +In messaging and communication protocols, a similar approach can be helpful, particularly when describing multiple actors and roles required for correct protocol operation. +However, reusing `Alice` and `Bob` in these contexts can introduce ambiguity: + +- In cryptography, Alice is the initiator of a key exchange, but in a communication protocol the initiator role may vary by sub-protocol or phase. +- Complex, multi-step systems may embed multiple cryptographic and application-level processes, each with their own initiator and responder. +- The use of Alice and Bob implicitly frames the discussion as cryptographic, which may be misleading when describing application-level behavior such as message encoding, routing, or reliability. + +For these reasons, when documenting communication protocols that integrate multiple roles and procedures, it is preferable to use a context-specific cast of characters designed for that domain. + +## Guidelines + +### Use of Alice and Bob + +`Alice` and `Bob` SHOULD be used when describing novel cryptographic constructions or key exchange mechanisms that are not embedded within higher-layer communication protocols. +These names are widely understood in cryptographic contexts, and introducing alternatives would reduce clarity. + +Communication protocols may incorporate cryptographic components, but they are not themselves cryptographic key exchanges. +When documenting application-centric or protocol-level processes, the cast defined in this document SHOULD be used instead. +This separation establishes clear contextual boundaries and prepares the reader to reason about different layers independently. + +### Standalone Documents + +Knowledge of this cast MUST NOT be a requirement to understand a given document. +Documents MUST be fully standalone and understandable to first-time readers. + +### Consistency + +Use of the cast is optional. +Characters SHOULD only be used when their presence improves understanding. +Using characters in the wrong context can negatively impact comprehension by implying incorrect information. +It is always acceptable to use other identifiers. + +## Character List + +The following characters are defined for use throughout the documentation of chat protocols. Documentation and examples focus on a portion of a real clients operation for simplicity. Using the character who corresponds to the role or perspective being highlighted, can help convey this information to readers. + +**Saro** +Sender :: +Saro is the participant who sends the first message within a given time window or protocol context. +Saro MAY be the party who initiates a conversation, or simply the first participant to act relative to a defined starting reference. + +**Raya** +Recipient :: +Raya is the participant who receives the first message sent by Saro. +After the initial exchange, Raya MAY send messages and behave as a regular participant in the conversation. +When documenting message receipt or processing, Raya’s perspective SHOULD be used. + +**Pax** +Participant :: +Pax represents an additional member of a conversation, typically in a group context. +Pax is often used when the specific identity or perspective of the participant is not relevant to the discussion. + +## Decision Criteria + +The following criteria SHOULD be applied when considering the introduction of new character names or roles. + +### Clarity + +Names without strong pre-existing associations or implied behavior SHOULD be preferred where possible. + +### Brevity + +Short, easily distinguishable names SHOULD be preferred, provided they do not reduce clarity. + +### Inclusivity + +The cast of characters SHOULD be diverse, culturally neutral, and avoid reinforcing stereotypes. + +### Mnemonic Naming + +Where possible the characters name should hint at their role in order to make them easier to remember. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +[A global cast of characters for cryptography](https://github.com/jhaaaa/alix-and-bo) \ No newline at end of file From 424ea61cdc89cb7a8181275a4f50e440b5c60a70 Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Wed, 25 Feb 2026 14:31:07 +0100 Subject: [PATCH 057/174] add debug API --- standards/application/waku-api.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index fe633ff..33a2da9 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -561,6 +561,27 @@ although performance or reliability may still be impacted. `Connected` indicates that the node is operating optimally, with full support for message reception and transmission. +### Debug + +#### Debug function definitions + +```yaml +functions: + getAvailableNodeInfoIds: + description: "Returns a list of available node information identifiers. e.g., [ version, my_peer_id, metrics ]." + returns: + type: result, error> + + getNodeInfo: + description: "Returns the node's information that is requested" + parameters: + - name: nodeInfoId + type: string + description: "Information identifier. The only supported values are the ones returned by getAvailableNodeInfoItems function" + returns: + type: result +``` + ## 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. From 66a75584db36153919807abdae522a6301eb6a8d Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Fri, 27 Feb 2026 14:49:47 +0100 Subject: [PATCH 058/174] add getAvailableConfigs into debug API --- standards/application/waku-api.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 33a2da9..518f72b 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -573,13 +573,18 @@ functions: type: result, error> getNodeInfo: - description: "Returns the node's information that is requested" + description: "Returns the node's information that is requested." parameters: - name: nodeInfoId type: string - description: "Information identifier. The only supported values are the ones returned by getAvailableNodeInfoItems function" + description: "Information identifier. The only supported values are the ones returned by getAvailableNodeInfoItems function." returns: type: result + + getAvailableConfigs: + description: "Returns a list of all available options, their description and default values." + returns: + type: string ``` ## The Validation API From 63f8bc428292b1c4e5294ffbffe72cd1ecf1eb44 Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Fri, 27 Feb 2026 14:58:03 +0100 Subject: [PATCH 059/174] add new terms in .wordlist.txt to make speller happy --- .wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 1889016..197b7e4 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -36,7 +36,9 @@ EventSource eventType fb fBF +getAvailableNodeInfoItems getMerkleRoot +getNodeInfo github GITHUB gossipsub @@ -76,6 +78,7 @@ NetworkingConfig nim nodeConfig NodeConfig +nodeInfoId num Oleksandr onEvent From a35f47dfbe7d5d254f6fd944cf6b045413f5c147 Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Fri, 27 Feb 2026 14:59:58 +0100 Subject: [PATCH 060/174] adjust comment as per Zoltan's recommendation --- standards/application/waku-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 518f72b..2f38096 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -573,7 +573,7 @@ functions: type: result, error> getNodeInfo: - description: "Returns the node's information that is requested." + description: "Returns the JSON formatted node's information that is requested. Expect single value or list results depending on requested information." parameters: - name: nodeInfoId type: string From 296dbe943ec33fbdf9587b91058c2f1b2d7a5e2e Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Fri, 27 Feb 2026 15:13:06 +0100 Subject: [PATCH 061/174] add misspelled words exceptions --- .wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 197b7e4..86f95ad 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -36,6 +36,7 @@ EventSource eventType fb fBF +getAvailableConfigs getAvailableNodeInfoItems getMerkleRoot getNodeInfo @@ -56,6 +57,7 @@ Init ipv iterable Jazzz +JSON KiB Kozlov libp From 46caf0cc4d86bfc5d39f722e3500bc89e6e0c5ec Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Fri, 27 Feb 2026 15:14:20 +0100 Subject: [PATCH 062/174] same as previous commit --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index 86f95ad..e5562d0 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -37,6 +37,7 @@ eventType fb fBF getAvailableConfigs +getAvailableNodeInfoIds getAvailableNodeInfoItems getMerkleRoot getNodeInfo From db3d5a8df7675042f5c7aee3af006ee7ed892be8 Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Wed, 18 Mar 2026 22:25:47 +0100 Subject: [PATCH 063/174] rename waku-api.md to messaging-api.md --- standards/application/{waku-api.md => messaging-api.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename standards/application/{waku-api.md => messaging-api.md} (100%) diff --git a/standards/application/waku-api.md b/standards/application/messaging-api.md similarity index 100% rename from standards/application/waku-api.md rename to standards/application/messaging-api.md From 3d4a1d5ffe5579bc592bb36c593dee428d7a630b Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Wed, 18 Mar 2026 22:31:13 +0100 Subject: [PATCH 064/174] small refactor and fix broken links --- standards/application/messaging-api.md | 72 +++++++++++++------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/standards/application/messaging-api.md b/standards/application/messaging-api.md index 2f38096..653f7b8 100644 --- a/standards/application/messaging-api.md +++ b/standards/application/messaging-api.md @@ -1,6 +1,6 @@ --- -title: WAKU-API -name: Waku API definition +title: MESSAGING-API +name: Messaging API definition category: Standards Track status: raw tags: [reliability, application, api, protocol composition] @@ -23,7 +23,7 @@ contributors: * [Primitive types and general guidelines](#primitive-types-and-general-guidelines) * [Language mappings](#language-mappings) * [Application](#application) - * [The Waku API](#the-waku-api) + * [The Messaging API](#the-messaging-api) * [Common](#common) * [Common type definitions](#common-type-definitions) * [Init node](#init-node) @@ -53,17 +53,15 @@ 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 Logos Messaging 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, subscription, and store hash queries. - ## Motivation -The accessibility of Waku protocols is capped by the accessibility of their implementations, and hence API. +The accessibility of Logos Messaging protocols is capped by the accessibility of their implementations, and hence API. This RFC enables a concerted effort to draft an API that is simple and accessible, and provides an opinion on sane defaults. -The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocols. +The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2](https://lip.logos.co/messaging/standards/core/10/waku2.html) protocols. ## Syntax @@ -74,7 +72,7 @@ The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL N ### IDL -A custom Interface Definition Language (IDL) in YAML is used to define the Waku API. +A custom Interface Definition Language (IDL) in YAML is used to define the Messaging API. Existing IDL Such as OpenAPI, AsyncAPI or WIT do not exactly fit the requirements for this API. Hence, instead of having the reader learn a new IDL, we propose to use a simple IDL with self-describing syntax. @@ -118,12 +116,12 @@ language_mappings: This API is designed for generic use and ease across all programming languages, for `edge` and `core` type nodes. -## The Waku API +## The Messaging API ```yaml api_version: "0.0.1" -library_name: "waku" -description: "Waku: a private and censorship-resistant message routing library." +library_name: "liblogosdelivery" +description: "Logos Messaging: a private and censorship-resistant message routing library." ``` ### Common @@ -139,7 +137,7 @@ types: WakuNode: type: object - description: "A Waku node instance." + description: "A node instance." fields: messageEvents: type: MessageEvents @@ -167,7 +165,7 @@ types: type: string constraints: [ "edge", "core" ] default: "core" # "edge" for mobile and browser devices. - description: "The mode of operation of the Waku node; 'edge' of the network: relies on other nodes for message routing; 'core' of the network: fully participate to message routing." + description: "The mode of operation of the node; 'edge' of the network: relies on other nodes for message routing; 'core' of the network: fully participate to message routing." protocols_config: type: ProtocolsConfig default: TheWakuNetworkPreset @@ -192,7 +190,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)." + description: "The cluster ID for the network. Cluster IDs are defined in [RELAY-SHARDING](https://github.com/logos-messaging/specs/blob/master/standards/core/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 @@ -258,11 +256,11 @@ types: functions: createNode: - description: "Initialise a Waku node instance" + description: "Initialises a node instance" parameters: - name: nodeConfig type: NodeConfig - description: "The Waku node configuration." + description: "The node configuration." returns: type: result ``` @@ -324,23 +322,23 @@ values: If the `mode` set is `edge`, the initialised `WakuNode` SHOULD use: -- [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as client -- [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as client -- [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 -- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as client +- [LIGHTPUSH](https://lip.logos.co/messaging/standards/core/19/lightpush.html) as client +- [FILTER](https://lip.logos.co/messaging/standards/core/12/filter.html) as client +- [STORE](https://lip.logos.co/messaging/standards/core/13/store.html) as client +- [METADATA](https://lip.logos.co/messaging/standards/core/66/metadata.html) as client +- [PEER-EXCHANGE](https://lip.logos.co/messaging/standards/core/34/peer-exchange.html) as client - [P2P-RELIABILITY](/standards/application/p2p-reliability.md) 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 -- [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 +- [RELAY](https://lip.logos.co/messaging/standards/core/11/relay.html) +- [LIGHTPUSH](https://lip.logos.co/messaging/standards/core/19/lightpush.html) as service node +- [FILTER](https://lip.logos.co/messaging/standards/core/12/filter.html) as service node +- [STORE](https://lip.logos.co/messaging/standards/core/13/store.html) as client +- [METADATA](https://lip.logos.co/messaging/standards/core/66/metadata.html) as client and service node - [P2P-RELIABILITY](/standards/application/p2p-reliability.md) -- [DISCV5](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/33/discv5.md) -- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as client and service node +- [DISCV5](https://lip.logos.co/messaging/standards/core/33/discv5.html) +- [PEER-EXCHANGE](https://lip.logos.co/messaging/standards/core/34/peer-exchange.html) as client and service node - [RENDEZVOUS](https://github.com/waku-org/specs/blob/master/standards/core/rendezvous.md) as client and service node `edge` mode SHOULD be used if node functions in resource restricted environment, @@ -358,14 +356,14 @@ types: 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)" + description: "Content-based filtering field as defined in [TOPICS](https://lip.logos.co/messaging/informational/23/topics.html#content-topics)" payload: type: array description: "The message data." 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)" + description: "Whether the message is ephemeral. Read at [ATTRIBUTES](https://lip.logos.co/messaging/standards/core/14/message.html#message-attributes)" MessageReceivedEvent: type: object @@ -493,9 +491,9 @@ functions: **`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 `edge`, `subscribe` SHOULD trigger set up a subscription using [FILTER](https://lip.logos.co/messaging/standards/core/12/filter.html) 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). +If the `mode` set is `core`, `subscribe` SHOULD trigger set up a subscription using [RELAY](https://lip.logos.co/messaging/standards/core/11/relay.html) 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 a `MessageEvents` event source, meaning messages received via `RELAY` SHOULD be filtered by content topics before emission. @@ -553,9 +551,9 @@ TODO sending, or both, and as a result, it cannot reliably receive or transmit messages. `PartiallyConnected` indicates that the node meets the minimum operational requirements: -it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), -one peer with a protocol to receive messages ([FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), -and one peer with [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) service capabilities, +it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://lip.logos.co/messaging/standards/core/19/lightpush.html) or [RELAY](https://lip.logos.co/messaging/standards/core/11/relay.html)), +one peer with a protocol to receive messages ([FILTER](https://lip.logos.co/messaging/standards/core/12/filter.html) or [RELAY](https://lip.logos.co/messaging/standards/core/11/relay.html)), +and one peer with [STORE](https://lip.logos.co/messaging/standards/core/13/store.html) service capabilities, although performance or reliability may still be impacted. `Connected` indicates that the node is operating optimally, @@ -589,7 +587,7 @@ functions: ## 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. +[WAKU2-RLN-RELAY](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) is currently the primary message validation mechanism in place. Work is scheduled to specify a validate API to enable plug-in validation. As part of this API, it will be expected that a validation object can be passed, From ea1d5f301eea1ee5e633c6052e1bc88b5c560122 Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Wed, 18 Mar 2026 22:34:15 +0100 Subject: [PATCH 065/174] rm leftovers waku-org --- standards/application/messaging-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/application/messaging-api.md b/standards/application/messaging-api.md index 653f7b8..6531821 100644 --- a/standards/application/messaging-api.md +++ b/standards/application/messaging-api.md @@ -190,7 +190,7 @@ types: description: "The passed nodes are prioritised for store queries." cluster_id: type: uint - description: "The cluster ID for the network. Cluster IDs are defined in [RELAY-SHARDING](https://github.com/logos-messaging/specs/blob/master/standards/core/relay-sharding.md) and allocated in [RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md)." + description: "The cluster ID for the network. Cluster IDs are defined in [RELAY-SHARDING](https://github.com/logos-messaging/specs/blob/master/standards/core/relay-sharding.md) and allocated in [RELAY-STATIC-SHARD-ALLOC](https://github.com/logos-messaging/specs/blob/master/informational/relay-static-shard-alloc.md)." auto_sharding_config: type: AutoShardingConfig default: DefaultAutoShardingConfig @@ -339,7 +339,7 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: - [P2P-RELIABILITY](/standards/application/p2p-reliability.md) - [DISCV5](https://lip.logos.co/messaging/standards/core/33/discv5.html) - [PEER-EXCHANGE](https://lip.logos.co/messaging/standards/core/34/peer-exchange.html) as client and service node -- [RENDEZVOUS](https://github.com/waku-org/specs/blob/master/standards/core/rendezvous.md) as client and service node +- [RENDEZVOUS](https://github.com/logos-messaging/specs/blob/master/standards/core/rendezvous.md) as client and service node `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. @@ -598,7 +598,7 @@ RLN can also be disabled. ## Security/Privacy Considerations -See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md). +See [WAKU2-ADVERSARIAL-MODELS](https://github.com/logos-messaging/specs/blob/master/informational/adversarial-models.md). ## Copyright From 80622a0d188d964079e3b34e32a1f3f40a841ebf Mon Sep 17 00:00:00 2001 From: Ivan Folgueira Bande Date: Wed, 18 Mar 2026 22:40:23 +0100 Subject: [PATCH 066/174] make spelling checker happy --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index e5562d0..681877d 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -61,6 +61,7 @@ Jazzz JSON KiB Kozlov +liblogosdelivery libp libp2p LIGHTPUSH From d4690df2e69266d2cb7354836a4d59d34d7e6100 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 23 Mar 2026 22:29:04 +0100 Subject: [PATCH 067/174] First version reliable-channel-api spec --- .wordlist.txt | 70 ++- standards/application/reliable-channel-api.md | 473 ++++++++++++++++++ 2 files changed, 539 insertions(+), 4 deletions(-) create mode 100644 standards/application/reliable-channel-api.md diff --git a/.wordlist.txt b/.wordlist.txt index 681877d..1afbbc7 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,14 +1,26 @@ ABIs +acknowledgementTimeoutMs addListener ALLOC api AsyncAPI autosharding AutoShardingConfig +Backend +backend +backends bool camelCase +causalHistorySize cd centric +channelConfig +channelId +chunkId +chunkIndex +chunkSizeBytes +ciphertext +closeChannel config ConnectionStatus ConnectionStatusEvent @@ -18,16 +30,25 @@ createNode creativecommons cryptographic danielkaiser +decrypt +Decrypt +decrypted +Decrypts DefaultAutoShardingConfig DefaultMessageValidation DefaultNetworkingConfig +DefaultRateLimitConfig +DefaultSdsConfig +DefaultSegmentationConfig dev DHT discv DISCV DoS +encryptionKey enrtree enum +epochSizeMs eth Eth ETH @@ -48,11 +69,15 @@ GossipSub HealthConnectionStatusEvent healthEvents HealthEvents +historyBackend https iana IANA IDL +IEncryption implementor +implementors +Implementors Inclusivity Init ipv @@ -61,11 +86,16 @@ Jazzz JSON KiB Kozlov +lastChunkIndex liblogosdelivery libp libp2p +Lightpush LIGHTPUSH +maxRetransmissions md +MessageChunk +messageEnvelope MessageEnvelope MessageErrorEvent messageEvents @@ -76,6 +106,7 @@ MessageSendErrorEvent MessageSendPropagatedEvent MessageSentEvent MessageValidation +MiB multiaddr NetworkConfig NetworkingConfig @@ -86,23 +117,39 @@ nodeInfoId num Oleksandr onEvent +openChannel OpenAPI PartiallyConnected PascalCase Pax +plaintext +pluggable Prathi pre Prem +previousChunkId ProtocolsConfig pubsub -pubsub +rateLimitConfig +RateLimitConfig Raya Raya's +ReliableChannel +ReliableChannelConfig +ReliableEnvelope +ReliableMessageEvents +ReliableMessageReceivedEvent +ReliableMessageSendErrorEvent +ReliableMessageSentEvent +requestId RequestId responder +retransmission +Retransmission +retransmit +retransmitted +retransmitting rfc -rfc -RFC RFC rln RLN @@ -111,8 +158,19 @@ Royer rpc RPC Saro +Scalable +sds +SDS +SDS'ed +sdsConfig +SdsConfig +sdk +SDK +SegmentationConfig +segmentationConfig sharding SHARDING +sqlite subnets SubscriptionError TBD @@ -125,6 +183,10 @@ TWN udp UDP uint +unencrypted +unvalidated +UUID +UX waku Waku WAKU @@ -134,4 +196,4 @@ xB yaml YAML yml -ZXCV \ No newline at end of file +ZXCV diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md new file mode 100644 index 0000000..6a36b7b --- /dev/null +++ b/standards/application/reliable-channel-api.md @@ -0,0 +1,473 @@ +--- +title: RELIABLE-CHANNEL-API +name: Reliable Channel API definition +category: Standards Track +status: raw +tags: [reliability, application, api, sds, segmentation] +editor: Logos Messaging Team +--- + +## Table of contents + + + * [Table of contents](#table-of-contents) + * [Abstract](#abstract) + * [Motivation](#motivation) + * [Syntax](#syntax) + * [API design](#api-design) + * [IDL](#idl) + * [Architectural position](#architectural-position) + * [The Reliable Channel API](#the-reliable-channel-api) + * [Common](#common) + * [Common type definitions](#common-type-definitions) + * [Channel](#channel) + * [Channel type definitions](#channel-type-definitions) + * [Channel function definitions](#channel-function-definitions) + * [Channel predefined values](#channel-predefined-values) + * [Channel extended definitions](#channel-extended-definitions) + * [Messaging](#messaging) + * [Messaging type definitions](#messaging-type-definitions) + * [Messaging function definitions](#messaging-function-definitions) + * [Messaging extended definitions](#messaging-extended-definitions) + * [Components](#components) + * [Segmentation](#segmentation) + * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) + * [Rate Limit Manager](#rate-limit-manager) + * [Encryption Hook](#encryption-hook) + * [Security/Privacy Considerations](#securityprivacy-considerations) + * [Copyright](#copyright) + + +## Abstract + +This document specifies the **Reliable Channel API**, +an application-level interface that sits between the Chat SDK and the [MESSAGING-API](/standards/application/messaging-api.md) plus [P2P-RELIABILITY](/standards/application/p2p-reliability.md), i.e., `chat-sdk` <-> **reliable-channel-api** <-> `messaging-api/p2p-reliability`. + +It bundles segmentation, end-to-end reliability via [Scalable Data Sync (SDS)](https://lip.logos.co/ift-ts/raw/sds.html), rate limit management, and a pluggable encryption hook +into a single interface for sending and receiving messages reliably. + +Application developers SHOULD use this API when end-to-end reliability across multiple routing hops is required. + +## Motivation + +The [MESSAGING-API](/standards/application/messaging-api.md) provides peer-to-peer reliability via [P2P-RELIABILITY](/standards/application/p2p-reliability.md), +but does not provide high end-to-end delivery guarantees from sender to recipient. + +This API addresses that gap by introducing: +- **Segmentation** to handle large messages exceeding network size limits. +- **SDS** to provide causal-history-based end-to-end acknowledgement and retransmission. +- **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. +- **Encryption Hook** to allow upper layers (e.g., the Chat SDK) to provide a pluggable encryption mechanism. + +The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, +which are handled by higher layers. + +## Syntax + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). + +## API design + +### IDL + +A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). + +### Architectural position + +The Reliable Channel API sits between the Chat SDK and the Messaging API, as follows: + +``` +┌────────────────────────────────────────────────────────────┐ +│ Chat SDK │ +│ (Identity + Encryption + UX) │ +└───────────────────────────┬────────────────────────────────┘ + │ +┌───────────────────────────▼────────────────────────────────┐ +│ Reliable Channel API │ +│ ┌──────────────┐ ┌─────┐ ┌───────────────┐ ┌──────────┐ │ +│ │ Segmentation │ │ SDS │ │ Rate Limit Mgr│ │Encryption│ │ +│ │ │ │ │ │ │ │ Hook │ │ +│ └──────────────┘ └─────┘ └───────────────┘ └──────────┘ │ +└───────────────────────────┬────────────────────────────────┘ + │ +┌───────────────────────────▼────────────────────────────────┐ +│ Messaging API │ +│ (P2P Reliability, Relay, Filter, Lightpush, Store) │ +└────────────────────────────────────────────────────────────┘ +``` + +## The Reliable Channel API + +### Common + +#### Common type definitions + +This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following: + +```yaml +types: + MessageChunk: + type: object + description: "Represents the minimum unit of data transmitted across the network. Its size is governed by SegmentationConfig. Chunks are chained to their predecessors, and any chunk whose linkage to its predecessor cannot be verified MUST be discarded. + Only the first chunk on every message, is rate-limited (RLN) and the subsequent chunks MUST be accepted rate-limit wise." + fields: + chunkId: + type: string + description: UUID for the chunk + previousChunkId: + type: string + description: Previous chunk ID. Chunks with unvalidated previous chunks MUST be rejected. + This field is empty when chunkIndex == 0. + chunkIndex: + type: uint + description: "Zero-based position of this chunk within the ordered sequence of chunks that form the original message." + lastChunkIndex: + type: uint + description: "All chunks of same message have the same value, i.e., num-chunks - 1." + requestId: + type: RequestId + description: "The request id this chunk belongs to. This is generated by the send function and its type is defined in messaging-api." + + IEncryption: + type: object + description: "Interface for a pluggable encryption mechanism. Implementors MUST provide encrypt and decrypt operations." + fields: + encrypt: + type: function + description: "Encrypts a byte payload. Returns the encrypted payload." + parameters: + - name: plaintext + type: array + - name: encryptionKey + type: array + returns: + type: result, error> + decrypt: + type: function + description: "Decrypts a byte payload. Returns the decrypted payload." + parameters: + - name: ciphertext + type: array + - name: encryptionKey + type: array + returns: + type: result, error> +``` + +### Channel + +#### Channel type definitions + +```yaml +types: + ReliableEnvelope: + type: object + description: "Represents an extension of the MessageEnvelope defined in MESSAGING-API aiming mostly to allow + including a reliable channel id attribute that, when given, it will assume the message should be sent reliably. Therefore, we leave open for implementors to replace the MessageEnvelope implementation and just add the reliable channel id there." + fields: + messageEnvelope: + type: MessageEnvelope + description: "Please refer to the [MESSAGING-API](/standards/application/messaging-api.md) for details." + channelId: + type: string + default: "" + description: "Reliable channel identifier. + If empty, the message is considered ephemeral and is not sent reliably. + If != empty, the message will be segmented, SDS'ed and encrypted under the given reliable channel." + + ReliableChannel: + type: object + description: "A reliable channel instance or communication group having end-to-end reliable messaging on a single content topic." + fields: + channelId: + type: string + description: "Identifier of the communication group that is being synchronized" + messageEvents: + type: ReliableMessageEvents + description: "Event emitter for message-related events on this channel" + + ReliableChannelConfig: + type: object + fields: + segmentationConfig: + type: SegmentationConfig + default: DefaultSegmentationConfig + description: "Configuration for message segmentation." + sdsConfig: + type: SdsConfig + default: DefaultSdsConfig + description: "Configuration for Scalable Data Sync." + rateLimitConfig: + type: RateLimitConfig + default: DefaultRateLimitConfig + description: "Configuration for rate limit management." + encryption: + type: IEncryption + default: none + description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." + + SegmentationConfig: + type: object + fields: + chunkSizeBytes: + type: uint + default: 102400 # 100 KiB + description: "Maximum chunk size in bytes. + Messages larger than this value are split before SDS processing." + + SdsConfig: + type: object + fields: + historyBackend: + type: string + default: "memory" + description: "Backend for persisting the SDS local history. Implementations MAY support custom backends (e.g., 'memory', 'sqlite')." + acknowledgementTimeoutMs: + type: uint + default: 5000 + description: "Time in milliseconds to wait for acknowledgement before retransmitting." + maxRetransmissions: + type: uint + default: 5 + description: "Maximum number of retransmission attempts before considering delivery failed." + causalHistorySize: + type: uint + default: 2 + description: "Number of message IDs to consider in the causal history. With longer value, a stronger correctness is guaranteed but it requires higher bandwidth and memory." + + RateLimitConfig: + type: object + fields: + enabled: + type: bool + default: true + description: "Whether rate limiting is enforced. SHOULD be true when RLN is active." + epochSizeMs: + type: uint + default: 600000 # 10 minutes + description: "The epoch size used by the RLN relay, in milliseconds. Only the first message chunk is rate limited." +``` + +#### Channel function definitions + +```yaml +functions: + + openChannel: + description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." + parameters: + - name: nodeConfig + type: NodeConfig + description: "The node configuration. See [MESSAGING-API](/standards/application/messaging-api.md)." + - name: channelConfig + type: ReliableChannelConfig + description: "Configuration for the channel." + returns: + type: result + + closeChannel: + description: "Closes a reliable channel and releases all associated resources and internal state." + parameters: + - name: channel + type: ReliableChannel + description: "The channel to close." + returns: + type: result +``` + +#### Channel predefined values + +```yaml +values: + + DefaultSegmentationConfig: + type: SegmentationConfig + fields: + chunkSizeBytes: 102400 # 100 KiB + + DefaultSdsConfig: + type: SdsConfig + fields: + historyBackend: "memory" + acknowledgementTimeoutMs: 5000 + maxRetransmissions: 5 + causalHistorySize: 2 + + DefaultRateLimitConfig: + type: RateLimitConfig + fields: + enabled: true + epochSizeMs: 600000 +``` + +#### Channel extended definitions + +**State management**: + +Each `ReliableChannel` MUST maintain internal state for SDS, including: +- A committed message log recording sent messages and their acknowledgement status. +- An outgoing buffer of unacknowledged message chunks pending confirmation. +- An incoming buffer for partially received segmented messages awaiting full reassembly. + +The state MUST be persisted according to the `historyBackend` specified in `SdsConfig`. +The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. + +**Encryption**: + +The `encryption` field in `ReliableChannelConfig` is intentionally optional. +The Reliable Channel API is agnostic to encryption mechanisms. +Encryption is considered a concern of upper layers (e.g., the Chat SDK). +When an `IEncryption` implementation is provided, it MUST be applied as described in the [Messaging extended definitions](#messaging-extended-definitions). + +### Messaging + +#### Messaging type definitions + +```yaml +types: + ReliableMessageReceivedEvent: + type: object + description: "Event emitted when a complete message has been received and reassembled." + fields: + requestId: + type: RequestId + description: "Identifier of the `send` operation that initiated the message sending" + contentTopic: + type: string + description: "Content topic on which the message was received" + payload: + type: array + description: "The decrypted and reassembled message payload" + + ReliableMessageSentEvent: + type: object + description: "Event emitted when all chunks of a message have been acknowledged by the network." + fields: + requestId: + type: RequestId + description: "The request ID associated with the sent message" + + ReliableMessageSendErrorEvent: + type: object + description: "Event emitted when a message send operation fails after exhausting retransmission attempts." + fields: + requestId: + type: RequestId + description: "The request ID associated with the failed message" + error: + type: string + description: "Error message describing what went wrong" + + ReliableMessageEvents: + type: event_emitter + description: "Event source for reliable message events on a channel" + events: + "reliable:message:received": + type: ReliableMessageReceivedEvent + "reliable:message:sent": + type: ReliableMessageSentEvent + "reliable:message:send-error": + type: ReliableMessageSendErrorEvent +``` + +#### Messaging function definitions + +```yaml +functions: + send: + description: "Send a message reliably through the channel. Applies segmentation, SDS, and encryption (if configured) before dispatching." + parameters: + - name: channel + type: optional + description: "The reliable channel to use for sending. If not provided, the message is sent without delivery guarantees and is treated as ephemeral." + - name: payload + type: array + description: "The raw message payload to send." + returns: + type: result +``` + +#### Messaging extended definitions + +**Outgoing message processing order**: + +When `send` is called, the implementation MUST process the message in the following order: + +1. **Segment**: Split the payload into chunks of at most `chunkSizeBytes` as defined in `SegmentationConfig`. +2. **Apply SDS**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. +3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. +4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). + +**Incoming message processing order**: + +When a chunk is received from the network, the implementation MUST process it in the following order: + +1. **Decrypt**: If an `IEncryption` implementation is provided, decrypt the chunk. +2. **Apply SDS**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. +3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. + +**Retransmission**: + +The SDS layer MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, +up to `maxRetransmissions` times. +If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. + +**Rate limiting**: + +When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions +to comply with the RLN epoch constraints defined in `epochSizeMs`. +Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. + +## Components + +### Segmentation + +Segmentation splits outgoing messages into chunks before SDS processing. +This ensures each chunk fits within the network's maximum message size. + +- The default chunk size is `100 KiB` (`102400 bytes`.) +- Chunks MUST be tagged with metadata sufficient for the receiver to reassemble the original message: + a message identifier, chunk index, and total chunk count. +- Segmentation MUST be transparent to the SDS layer; SDS operates on individual chunks. +- The maximum allowed message size is `1MiB` (`1048576 bytes`.) +- Messages that are bigger than the maximum allowed size will be discarded automatically and an error will be given to the caller. + +### Scalable Data Sync (SDS) + +SDS provides end-to-end delivery guarantees using causal history tracking. + +- Each sent chunk is registered in an outgoing buffer. +- The recipient sends acknowledgements back to the sender upon receiving chunks. +- The sender removes acknowledged chunks from the outgoing buffer. +- Unacknowledged chunks are retransmitted after `acknowledgementTimeoutMs`. +- SDS state MUST be persisted in the configured `historyBackend`. + +### Rate Limit Manager + +The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. + +- It tracks how many messages have been sent in the current epoch (only the first chunk of each message counts toward the rate limit; subsequent chunks are exempt). +- When the limit is approached, chunk dispatch MUST be delayed to the next epoch. +- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. + +### Encryption Hook + +The Encryption Hook provides a pluggable interface for upper layers to inject encryption. + +- The hook is optional; when not provided, messages are sent as plaintext. +- Encryption is applied per chunk, after segmentation and SDS registration. +- Decryption is applied per chunk, before SDS delivery. +- The `IEncryption` interface MUST be implemented by the caller (e.g., the Chat SDK). +- The Reliable Channel API MUST NOT impose any specific encryption scheme. + +## Security/Privacy Considerations + +- This API does not provide confidentiality by default. An `IEncryption` implementation MUST be supplied when confidentiality is required. +- Chunk metadata (message ID, chunk index, total chunks) is visible to network observers unless encrypted by the hook. +- SDS acknowledgement messages are sent over the same content topic and are subject to the same confidentiality concerns. +- Rate limiting compliance is required to avoid exclusion from the network by RLN-enforcing relays. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From c8de3434d2cd5bacda1680399e4381c8801e8f73 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 30 Mar 2026 11:00:16 -0700 Subject: [PATCH 068/174] Chat Definitions (#80) * Add template * relocate to informational folder * Updated roles * Update message types * Updated definitions for OOB, client, app * Update spelling + aspell * Add html filter to aspell * Fix pyspell error * fix spell of contentTypes * chore: sort wordlist * Update informational/chatdefs.md Co-authored-by: kaichao * Clarify Content, Frames, Payloads * spelling fixes * Update informational/chatdefs.md Co-authored-by: kaichao * Add session / conversation differentiation * Update informational/chatdefs.md * Apply suggestions from code review Co-authored-by: Igor Sirotin * Remove Accounts + Identity Heading * Clarified Content, Frame, Payload * Update Client Application, and Conversation * fix spelling * Update informational/chatdefs.md --------- Co-authored-by: kaichao Co-authored-by: Igor Sirotin --- .wordlist.txt | 4 ++ informational/chatdefs.md | 98 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 informational/chatdefs.md diff --git a/.wordlist.txt b/.wordlist.txt index 681877d..e66ac9b 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -5,7 +5,9 @@ api AsyncAPI autosharding AutoShardingConfig +BCP bool +Bradner camelCase cd centric @@ -26,6 +28,7 @@ DHT discv DISCV DoS +encodings enrtree enum eth @@ -52,6 +55,7 @@ https iana IANA IDL +implementers implementor Inclusivity Init diff --git a/informational/chatdefs.md b/informational/chatdefs.md new file mode 100644 index 0000000..33ee099 --- /dev/null +++ b/informational/chatdefs.md @@ -0,0 +1,98 @@ +--- +title: CHAT-DEFINITIONS +name: Shared definitions for Chat Protocols +category: Informational +tags: definitions, terminology, reference +editor: +contributors: +--- + +## Abstract + +This specification establishes a common vocabulary and standardized definitions for terms used across chat protocol specifications. It serves as a normative reference to ensure consistent interpretation of terminology across application level specifications. + +## Background / Rationale / Motivation + +Chat protocol specifications often employ similar terminology with subtle but important semantic differences. The absence of standardized definitions leads to ambiguity in specification interpretation and implementation inconsistencies across different protocol variants. + +Establishing a shared definitions document provides several benefits: + +1. **Semantic Consistency**: Ensures uniform interpretation of common terms across multiple specifications +2. **Implementation Clarity**: Reduces ambiguity for protocol implementers +3. **Specification Quality**: Enables more precise and concise specification language through reference to established definitions +4. **Ecosystem Coherence**: Promotes consistent understanding within the chat protocol ecosystem. + +This specification provides normative definitions that other chat protocol specifications MAY reference to establish precise semantic meaning for common terminology. + +## Theory / Semantics + +### Definition Categories + +Terms are organized into the following categories for clarity and ease of reference: + +- **Roles**: Defined entity types that determine how a participant behaves within a communication protocol. +- **Message Types**: Classifications and categories of protocol messages +- **Transports**: Abstract methods of transmitting payloads +-**Software Entities**: Distinct software-defined actors or components that participate in the operation of chat protocols. + +## Definitions + +### Roles + +**Sender**: A client which is pushing a payload on to the network, to one or more recipients. + +**Recipient**: A client which is the intended receiver of a payload. In a group context there maybe multiple recipients + +**Participant**: A generic term for the rightful members of a conversation. Senders and Recipients are roles that participants can hold. + +### Message Types + +The term "message" often has multiple meanings depending on context. The following definitions are used to disambiguate between different abstraction levels. + +**Content**: An opaque byte sequence whose meaning is defined solely by the Application. The chat protocol layer neither interprets nor validates Content structure. + +**Frame**: A structured protocol message exchanged between Clients. Frames are typed data structures that carry protocol meaning — they are how clients coordinate state and exchange information. Some Frames may carry Content as an opaque field. Once serialized for transport they become Payloads. + +**Payload**: The serialized binary representation of a Frame, treated by the transport layer as an opaque byte sequence with no chat-layer semantics. + + +Other specific message types include: + +**Content Type**: A definition of the structure and encoding of a Content instance, interpreted solely by the Application. + +**Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt, delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. + +**Invite**: A frame used to initialize a new conversation. Invites notify a client that someone wants to communicate with them, and provides the required information to do so. + + +### Transports + +**Out-of-Band**: The transfer of information using a channel separate from the defined chat protocol. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is the implementer or other protocols in the suite. + + +### Software Entities + +**Client**: A software component that manages Conversations and exposes messaging capabilities to Applications. The Client acts as the interface between the Application and the underlying protocol. + +**Application**: Software that integrates with a Client in order to send and receive content. Applications are responsible for displaying content and controlling what content gets sent. + +**Conversation**: An instance of a chat protocol between a set of participants. Conversations are responsible for protocol operations including encryption, key management, and frame generation. + + +## Wire Format Specification / Syntax + +This specification does not define wire format elements. All definitions are semantic and apply to the interpretation of terms used in other specifications that do define wire formats. + +## Security/Privacy Considerations + +This specification defines terminology only and does not introduce security or privacy considerations beyond those present in specifications that reference these definitions. + +The definitions provided in this specification do not alter the security or privacy properties of implementations that adopt the defined terminology. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. \ No newline at end of file From fa7ff625c225fcad3df8baf3ecb28ea59c8d0de8 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 20:44:09 +0200 Subject: [PATCH 069/174] proper use of logos chat term --- standards/application/reliable-channel-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 6a36b7b..f1aab18 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -41,7 +41,7 @@ editor: Logos Messaging Team ## Abstract This document specifies the **Reliable Channel API**, -an application-level interface that sits between the Chat SDK and the [MESSAGING-API](/standards/application/messaging-api.md) plus [P2P-RELIABILITY](/standards/application/p2p-reliability.md), i.e., `chat-sdk` <-> **reliable-channel-api** <-> `messaging-api/p2p-reliability`. +an application-level interface that sits between the Logos Chat and the [MESSAGING-API](/standards/application/messaging-api.md) plus [P2P-RELIABILITY](/standards/application/p2p-reliability.md), i.e., `logos-chat` <-> **reliable-channel-api** <-> `messaging-api/p2p-reliability`. It bundles segmentation, end-to-end reliability via [Scalable Data Sync (SDS)](https://lip.logos.co/ift-ts/raw/sds.html), rate limit management, and a pluggable encryption hook into a single interface for sending and receiving messages reliably. @@ -57,7 +57,7 @@ This API addresses that gap by introducing: - **Segmentation** to handle large messages exceeding network size limits. - **SDS** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. -- **Encryption Hook** to allow upper layers (e.g., the Chat SDK) to provide a pluggable encryption mechanism. +- **Encryption Hook** to allow upper layers (e.g., the Logos Chat) to provide a pluggable encryption mechanism. The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, which are handled by higher layers. @@ -75,11 +75,11 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ### Architectural position -The Reliable Channel API sits between the Chat SDK and the Messaging API, as follows: +The Reliable Channel API sits between the Logos Chat and the Messaging API, as follows: ``` ┌────────────────────────────────────────────────────────────┐ -│ Chat SDK │ +│ Logos Chat │ │ (Identity + Encryption + UX) │ └───────────────────────────┬────────────────────────────────┘ │ @@ -317,7 +317,7 @@ The default `memory` backend does not survive process restarts; implementors pro The `encryption` field in `ReliableChannelConfig` is intentionally optional. The Reliable Channel API is agnostic to encryption mechanisms. -Encryption is considered a concern of upper layers (e.g., the Chat SDK). +Encryption is considered a concern of upper layers (e.g., the Logos Chat). When an `IEncryption` implementation is provided, it MUST be applied as described in the [Messaging extended definitions](#messaging-extended-definitions). ### Messaging @@ -458,7 +458,7 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en - The hook is optional; when not provided, messages are sent as plaintext. - Encryption is applied per chunk, after segmentation and SDS registration. - Decryption is applied per chunk, before SDS delivery. -- The `IEncryption` interface MUST be implemented by the caller (e.g., the Chat SDK). +- The `IEncryption` interface MUST be implemented by the caller (e.g., the Logos Chat). - The Reliable Channel API MUST NOT impose any specific encryption scheme. ## Security/Privacy Considerations From 9725dc84adc61e4f929c495a9cbecde2e174ca66 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 21:21:40 +0200 Subject: [PATCH 070/174] simplify IEncryption to only accept raw encrypt and decrypt functions --- standards/application/reliable-channel-api.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f1aab18..e8eecbc 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -139,8 +139,6 @@ types: parameters: - name: plaintext type: array - - name: encryptionKey - type: array returns: type: result, error> decrypt: @@ -149,8 +147,6 @@ types: parameters: - name: ciphertext type: array - - name: encryptionKey - type: array returns: type: result, error> ``` From 92a746cca864f61a1978ac7bf707e82e33732b16 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 21:24:29 +0200 Subject: [PATCH 071/174] make IEncryption clearly optional --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index e8eecbc..5dd8c28 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -199,7 +199,7 @@ types: default: DefaultRateLimitConfig description: "Configuration for rate limit management." encryption: - type: IEncryption + type: optional default: none description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." From c3daa9d127fa4123cb1d1469ffcb35f20d074dd6 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 21:28:14 +0200 Subject: [PATCH 072/174] rm line to avoid confusion --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 5dd8c28..f5c8b29 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -313,7 +313,7 @@ The default `memory` backend does not survive process restarts; implementors pro The `encryption` field in `ReliableChannelConfig` is intentionally optional. The Reliable Channel API is agnostic to encryption mechanisms. -Encryption is considered a concern of upper layers (e.g., the Logos Chat). + When an `IEncryption` implementation is provided, it MUST be applied as described in the [Messaging extended definitions](#messaging-extended-definitions). ### Messaging From 27fef43f95a64a9d5204de412c02eec77823eada Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 21:38:59 +0200 Subject: [PATCH 073/174] simplify reliale channel description --- standards/application/reliable-channel-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f5c8b29..c200f11 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -174,11 +174,11 @@ types: ReliableChannel: type: object - description: "A reliable channel instance or communication group having end-to-end reliable messaging on a single content topic." + description: "An entity that guarantees message delivery among all participants on a single content topic." fields: channelId: type: string - description: "Identifier of the communication group that is being synchronized" + description: "Unique identifier" messageEvents: type: ReliableMessageEvents description: "Event emitter for message-related events on this channel" From b44c2a5c27d4ae7261ad171cfc22934653b08f61 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 8 Apr 2026 15:54:43 +0200 Subject: [PATCH 074/174] rm SHOULD use comment from abstract --- standards/application/reliable-channel-api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index c200f11..034cd4a 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -46,7 +46,6 @@ an application-level interface that sits between the Logos Chat and the [MESSAGI It bundles segmentation, end-to-end reliability via [Scalable Data Sync (SDS)](https://lip.logos.co/ift-ts/raw/sds.html), rate limit management, and a pluggable encryption hook into a single interface for sending and receiving messages reliably. -Application developers SHOULD use this API when end-to-end reliability across multiple routing hops is required. ## Motivation From 9d793208a834a01d3ecdea51ecc8c5ca091eea5d Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 8 Apr 2026 16:05:32 +0200 Subject: [PATCH 075/174] Extend IEncryption description --- standards/application/reliable-channel-api.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 034cd4a..1e500e9 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -130,7 +130,11 @@ types: IEncryption: type: object - description: "Interface for a pluggable encryption mechanism. Implementors MUST provide encrypt and decrypt operations." + description: "Interface for a pluggable encryption mechanism. + When IEncryption is provided, see ReliableChannelConfig, the encrypt and decrypt operations MUST be provided by the API consumer. + Notice that the encrypt/decrypt signatures may defer from what are described below but the important + point is that both operations MUST have a mechanism to accept an byte array as input and return a + byte array as an output." fields: encrypt: type: function From 42316c9e7e14865113a936a609479192f55429c1 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 9 Apr 2026 15:35:41 +0200 Subject: [PATCH 076/174] make more explicit that messageEnvelop will get encrypted --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 1e500e9..1655867 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -173,7 +173,7 @@ types: default: "" description: "Reliable channel identifier. If empty, the message is considered ephemeral and is not sent reliably. - If != empty, the message will be segmented, SDS'ed and encrypted under the given reliable channel." + If != empty, the messageEnvelope will be segmented, SDS'ed and encrypted under the given reliable channel." ReliableChannel: type: object From ffea66cacc92538c0617b80602a3efa334df996a Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 9 Apr 2026 17:06:30 +0200 Subject: [PATCH 077/174] give better description about why encryption is needed --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 1655867..7d987c3 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -56,7 +56,7 @@ This API addresses that gap by introducing: - **Segmentation** to handle large messages exceeding network size limits. - **SDS** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. -- **Encryption Hook** to allow upper layers (e.g., the Logos Chat) to provide a pluggable encryption mechanism. +- **Encryption Hook** to allow upper layers (e.g., the Logos Chat) to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload and content_topic from MessageEnvelope, defined in [MESSAGING-API](/standards/application/messaging-api.md). The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, which are handled by higher layers. From a267622a0fbe19ad57bd5473652f60b9d873a001 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 9 Apr 2026 21:44:49 +0200 Subject: [PATCH 078/174] add concepts from Franck's PR #89 --- standards/application/reliable-channel-api.md | 64 ++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 7d987c3..82b429f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -128,6 +128,27 @@ types: type: RequestId description: "The request id this chunk belongs to. This is generated by the send function and its type is defined in messaging-api." + SyncStatusDetail: + type: object + description: "Provides a snapshot of the channel's synchronisation state." + fields: + received: + type: uint + description: "Number of messages successfully received." + missing: + type: uint + description: "Number of messages detected as missing but not yet retrieved." + lost: + type: uint + description: "Number of messages that could not be retrieved after all attempts." + + SyncStatus: + type: enum + description: "Indicates whether the channel has detected any outstanding missing messages." + values: + - synced: "No known missing messages (some may be permanently lost)." + - syncing: "Actively attempting to retrieve one or more missing messages." + IEncryption: type: object description: "Interface for a pluggable encryption mechanism. @@ -172,7 +193,9 @@ types: type: string default: "" description: "Reliable channel identifier. - If empty, the message is considered ephemeral and is not sent reliably. + If empty, the message is considered ephemeral: it is not tracked by SDS, never retransmitted, and NEVER segmented. + Ephemeral payloads exceeding the network size limit MUST be rejected with an error. + When the rate limit is approached, ephemeral messages are dropped immediately rather than queued. If != empty, the messageEnvelope will be segmented, SDS'ed and encrypted under the given reliable channel." ReliableChannel: @@ -185,6 +208,9 @@ types: messageEvents: type: ReliableMessageEvents description: "Event emitter for message-related events on this channel" + syncStatus: + type: SyncStatus + description: "Current synchronisation status of the channel. Transitions between 'syncing' and 'synced' as missing messages are detected and resolved." ReliableChannelConfig: type: object @@ -358,6 +384,33 @@ types: type: string description: "Error message describing what went wrong" + ReliableMessageAcknowledgedEvent: + type: object + description: "Event emitted when the message has been definitively acknowledged via causal history." + fields: + requestId: + type: RequestId + description: "The request ID associated with the acknowledged message" + + ReliableIrretrievableMessageEvent: + type: object + description: "Event emitted when a missing message could not be retrieved after all store-query attempts." + fields: + requestId: + type: RequestId + description: "The request ID of the unrecoverable message" + + ReliableSyncStatusEvent: + type: object + description: "Event emitted when the channel's sync status transitions between 'synced' and 'syncing'." + fields: + status: + type: SyncStatus + description: "The new sync status" + detail: + type: SyncStatusDetail + description: "Counters describing the current sync state" + ReliableMessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" @@ -366,8 +419,17 @@ types: type: ReliableMessageReceivedEvent "reliable:message:sent": type: ReliableMessageSentEvent + "reliable:message:acknowledged": + type: ReliableMessageAcknowledgedEvent + description: "Message definitively acknowledged via causal history." "reliable:message:send-error": type: ReliableMessageSendErrorEvent + "reliable:message:irretrievable": + type: ReliableIrretrievableMessageEvent + description: "Missing message could not be retrieved after all store-query attempts." + "reliable:sync:status": + type: ReliableSyncStatusEvent + description: "Channel sync status changed between 'synced' and 'syncing'." ``` #### Messaging function definitions From a7eaade39f640df7454aa32737480466a71b11e1 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 9 Apr 2026 21:49:13 +0200 Subject: [PATCH 079/174] fix spelling issue --- .wordlist.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 94d3586..0c53e71 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -141,10 +141,13 @@ Raya's ReliableChannel ReliableChannelConfig ReliableEnvelope +ReliableIrretrievableMessageEvent +ReliableMessageAcknowledgedEvent ReliableMessageEvents ReliableMessageReceivedEvent ReliableMessageSendErrorEvent ReliableMessageSentEvent +ReliableSyncStatusEvent requestId RequestId responder @@ -169,6 +172,9 @@ SDS'ed sdsConfig SdsConfig sdk +syncStatus +SyncStatus +SyncStatusDetail SDK SegmentationConfig segmentationConfig From 638f8676d65f8dc82dce67253f67e80819dfbd00 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 9 Apr 2026 22:41:53 +0200 Subject: [PATCH 080/174] clarify and make IEncrypt description more concise --- standards/application/reliable-channel-api.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 82b429f..184c148 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -152,10 +152,8 @@ types: IEncryption: type: object description: "Interface for a pluggable encryption mechanism. - When IEncryption is provided, see ReliableChannelConfig, the encrypt and decrypt operations MUST be provided by the API consumer. - Notice that the encrypt/decrypt signatures may defer from what are described below but the important - point is that both operations MUST have a mechanism to accept an byte array as input and return a - byte array as an output." + When provided, see ReliableChannelConfig, the API consumer MUST implement both encrypt and decrypt operations. + Implementations MAY use different signatures than those described below, as long as each operation accepts a byte array and returns a byte array." fields: encrypt: type: function From f8156d4c2aaf2f3d8670f6b16da1dda72c93c023 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 13 Apr 2026 17:56:30 +0200 Subject: [PATCH 081/174] as per Zoltan recommendation, remove unneeded parameter in openChannel --- standards/application/reliable-channel-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 184c148..3f35f36 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -280,9 +280,6 @@ functions: openChannel: description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." parameters: - - name: nodeConfig - type: NodeConfig - description: "The node configuration. See [MESSAGING-API](/standards/application/messaging-api.md)." - name: channelConfig type: ReliableChannelConfig description: "Configuration for the channel." From b2ecac4ad5215ce6b9041a9214045e3a9245cf27 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 21:47:51 +0200 Subject: [PATCH 082/174] avoid using the term logos chat --- standards/application/reliable-channel-api.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3f35f36..9c2e47f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -41,7 +41,7 @@ editor: Logos Messaging Team ## Abstract This document specifies the **Reliable Channel API**, -an application-level interface that sits between the Logos Chat and the [MESSAGING-API](/standards/application/messaging-api.md) plus [P2P-RELIABILITY](/standards/application/p2p-reliability.md), i.e., `logos-chat` <-> **reliable-channel-api** <-> `messaging-api/p2p-reliability`. +an application-level interface that sits between the application layer and the [MESSAGING-API](/standards/application/messaging-api.md) plus [P2P-RELIABILITY](/standards/application/p2p-reliability.md), i.e., `application` <-> **reliable-channel-api** <-> `messaging-api/p2p-reliability`. It bundles segmentation, end-to-end reliability via [Scalable Data Sync (SDS)](https://lip.logos.co/ift-ts/raw/sds.html), rate limit management, and a pluggable encryption hook into a single interface for sending and receiving messages reliably. @@ -56,7 +56,7 @@ This API addresses that gap by introducing: - **Segmentation** to handle large messages exceeding network size limits. - **SDS** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. -- **Encryption Hook** to allow upper layers (e.g., the Logos Chat) to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload and content_topic from MessageEnvelope, defined in [MESSAGING-API](/standards/application/messaging-api.md). +- **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload and content_topic from MessageEnvelope, defined in [MESSAGING-API](/standards/application/messaging-api.md). The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, which are handled by higher layers. @@ -74,12 +74,11 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ### Architectural position -The Reliable Channel API sits between the Logos Chat and the Messaging API, as follows: +The Reliable Channel API sits between the application layer and the Messaging API, as follows: ``` ┌────────────────────────────────────────────────────────────┐ -│ Logos Chat │ -│ (Identity + Encryption + UX) │ +│ Application Layer │ └───────────────────────────┬────────────────────────────────┘ │ ┌───────────────────────────▼────────────────────────────────┐ @@ -514,7 +513,7 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en - The hook is optional; when not provided, messages are sent as plaintext. - Encryption is applied per chunk, after segmentation and SDS registration. - Decryption is applied per chunk, before SDS delivery. -- The `IEncryption` interface MUST be implemented by the caller (e.g., the Logos Chat). +- The `IEncryption` interface MUST be implemented by the caller. - The Reliable Channel API MUST NOT impose any specific encryption scheme. ## Security/Privacy Considerations From 49936a1a115ec96d4370175385a601bbce381953 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:51:25 +0200 Subject: [PATCH 083/174] use createReliableChannel function name Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 9c2e47f..5f9dd50 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -276,7 +276,7 @@ types: ```yaml functions: - openChannel: + createReliableChannel: description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." parameters: - name: channelConfig From af1a8849d4b1f26ffac9357eb138ea00b24207b7 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:54:29 +0200 Subject: [PATCH 084/174] use content as parameter name instead of plaintext Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 5f9dd50..9e83d9f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -158,7 +158,7 @@ types: type: function description: "Encrypts a byte payload. Returns the encrypted payload." parameters: - - name: plaintext + - name: content type: array returns: type: result, error> From bfaf91d02b226466d0725a11e7400d6d412d5806 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:58:17 +0200 Subject: [PATCH 085/174] use term persistence instead of historyBackend Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 9e83d9f..af8bde7 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -241,7 +241,7 @@ types: SdsConfig: type: object fields: - historyBackend: + persistence: type: string default: "memory" description: "Backend for persisting the SDS local history. Implementations MAY support custom backends (e.g., 'memory', 'sqlite')." From 2fc897e6555908a1b4f65816f25f533dd450bb6b Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 22:05:41 +0200 Subject: [PATCH 086/174] proper name for event objs --- standards/application/reliable-channel-api.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index af8bde7..9ef1590 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -203,7 +203,7 @@ types: type: string description: "Unique identifier" messageEvents: - type: ReliableMessageEvents + type: MessageEvents description: "Event emitter for message-related events on this channel" syncStatus: type: SyncStatus @@ -345,7 +345,7 @@ When an `IEncryption` implementation is provided, it MUST be applied as describe ```yaml types: - ReliableMessageReceivedEvent: + EventMessageReceived: type: object description: "Event emitted when a complete message has been received and reassembled." fields: @@ -359,7 +359,7 @@ types: type: array description: "The decrypted and reassembled message payload" - ReliableMessageSentEvent: + EventReliableMessageSent: type: object description: "Event emitted when all chunks of a message have been acknowledged by the network." fields: @@ -367,7 +367,7 @@ types: type: RequestId description: "The request ID associated with the sent message" - ReliableMessageSendErrorEvent: + EventMessageSendError: type: object description: "Event emitted when a message send operation fails after exhausting retransmission attempts." fields: @@ -378,7 +378,7 @@ types: type: string description: "Error message describing what went wrong" - ReliableMessageAcknowledgedEvent: + EventMessageAcknowledged: type: object description: "Event emitted when the message has been definitively acknowledged via causal history." fields: @@ -386,7 +386,7 @@ types: type: RequestId description: "The request ID associated with the acknowledged message" - ReliableIrretrievableMessageEvent: + EventIrretrievableMessage: type: object description: "Event emitted when a missing message could not be retrieved after all store-query attempts." fields: @@ -394,7 +394,7 @@ types: type: RequestId description: "The request ID of the unrecoverable message" - ReliableSyncStatusEvent: + EventSyncStatus: type: object description: "Event emitted when the channel's sync status transitions between 'synced' and 'syncing'." fields: @@ -405,24 +405,24 @@ types: type: SyncStatusDetail description: "Counters describing the current sync state" - ReliableMessageEvents: + MessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" events: "reliable:message:received": - type: ReliableMessageReceivedEvent + type: EventMessageReceived "reliable:message:sent": - type: ReliableMessageSentEvent + type: EventMessageSent "reliable:message:acknowledged": - type: ReliableMessageAcknowledgedEvent + type: EventMessageAcknowledged description: "Message definitively acknowledged via causal history." "reliable:message:send-error": - type: ReliableMessageSendErrorEvent + type: EventMessageSendError "reliable:message:irretrievable": - type: ReliableIrretrievableMessageEvent + type: EventIrretrievableMessage description: "Missing message could not be retrieved after all store-query attempts." "reliable:sync:status": - type: ReliableSyncStatusEvent + type: EventSyncStatus description: "Channel sync status changed between 'synced' and 'syncing'." ``` From 89148cae12ece3515373a313a5ce57d78f6bcd36 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 22:11:08 +0200 Subject: [PATCH 087/174] make it clear where RequestId type is defined --- standards/application/reliable-channel-api.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 9ef1590..682d5bc 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -125,7 +125,7 @@ types: description: "All chunks of same message have the same value, i.e., num-chunks - 1." requestId: type: RequestId - description: "The request id this chunk belongs to. This is generated by the send function and its type is defined in messaging-api." + description: "The request id this chunk belongs to. This is generated by the send function. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." SyncStatusDetail: type: object @@ -351,7 +351,7 @@ types: fields: requestId: type: RequestId - description: "Identifier of the `send` operation that initiated the message sending" + description: "Identifier of the `send` operation that initiated the message sending. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." contentTopic: type: string description: "Content topic on which the message was received" @@ -365,7 +365,7 @@ types: fields: requestId: type: RequestId - description: "The request ID associated with the sent message" + description: "The request ID associated with the sent message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." EventMessageSendError: type: object @@ -373,7 +373,7 @@ types: fields: requestId: type: RequestId - description: "The request ID associated with the failed message" + description: "The request ID associated with the failed message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." error: type: string description: "Error message describing what went wrong" @@ -384,7 +384,7 @@ types: fields: requestId: type: RequestId - description: "The request ID associated with the acknowledged message" + description: "The request ID associated with the acknowledged message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." EventIrretrievableMessage: type: object @@ -392,7 +392,7 @@ types: fields: requestId: type: RequestId - description: "The request ID of the unrecoverable message" + description: "The request ID of the unrecoverable message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." EventSyncStatus: type: object @@ -441,6 +441,7 @@ functions: description: "The raw message payload to send." returns: type: result + description: "`RequestId` is defined in [MESSAGING-API](./messaging-api.md)." ``` #### Messaging extended definitions From 033f17af96489bd7de2f3f57c9ec010d43cf3dee Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 22:56:46 +0200 Subject: [PATCH 088/174] add IPersistence as sds config param --- standards/application/reliable-channel-api.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 682d5bc..b31ff42 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -170,6 +170,12 @@ types: type: array returns: type: result, error> + + IPersistence: + type: object + description: "Interface for a pluggable SDS persistence backend. + Implementations MUST provide all functions required to save and retrieve SDS state per channel. + Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." ``` ### Channel @@ -242,9 +248,8 @@ types: type: object fields: persistence: - type: string - default: "memory" - description: "Backend for persisting the SDS local history. Implementations MAY support custom backends (e.g., 'memory', 'sqlite')." + type: IPersistence + description: "Backend for persisting the SDS local history. Implementations MAY support custom backends." acknowledgementTimeoutMs: type: uint default: 5000 From 3ec5732050f844a48431735e1d915b6fa2c75979 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Thu, 23 Apr 2026 23:05:59 +0200 Subject: [PATCH 089/174] use payload term instead of ciphertext Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index b31ff42..55fb986 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -166,7 +166,7 @@ types: type: function description: "Decrypts a byte payload. Returns the decrypted payload." parameters: - - name: ciphertext + - name: payload type: array returns: type: result, error> From 9a67839c925b162a1389d44eb44e70260c48f33b Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 23:20:00 +0200 Subject: [PATCH 090/174] rm duplicated defaults --- standards/application/reliable-channel-api.md | 29 +------------------ 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 55fb986..31cc744 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -220,11 +220,9 @@ types: fields: segmentationConfig: type: SegmentationConfig - default: DefaultSegmentationConfig - description: "Configuration for message segmentation." + description: "Configuration for message segmentation. Please refer to [SEGMENTATION](./segmentation.md) for more details." sdsConfig: type: SdsConfig - default: DefaultSdsConfig description: "Configuration for Scalable Data Sync." rateLimitConfig: type: RateLimitConfig @@ -300,31 +298,6 @@ functions: type: result ``` -#### Channel predefined values - -```yaml -values: - - DefaultSegmentationConfig: - type: SegmentationConfig - fields: - chunkSizeBytes: 102400 # 100 KiB - - DefaultSdsConfig: - type: SdsConfig - fields: - historyBackend: "memory" - acknowledgementTimeoutMs: 5000 - maxRetransmissions: 5 - causalHistorySize: 2 - - DefaultRateLimitConfig: - type: RateLimitConfig - fields: - enabled: true - epochSizeMs: 600000 -``` - #### Channel extended definitions **State management**: From d7836f4b32341d1e1063622035c8921d8f706363 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 23:27:12 +0200 Subject: [PATCH 091/174] chunks should alse be rate-limited --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 31cc744..ef2d3da 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -271,7 +271,7 @@ types: epochSizeMs: type: uint default: 600000 # 10 minutes - description: "The epoch size used by the RLN relay, in milliseconds. Only the first message chunk is rate limited." + description: "The epoch size used by the RLN relay, in milliseconds." ``` #### Channel function definitions From bdab8f7cab9b6a8375e75071c0d797d016d579d0 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 23:32:50 +0200 Subject: [PATCH 092/174] rm unnecessary descriptions --- standards/application/reliable-channel-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index ef2d3da..ff126ac 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -393,15 +393,12 @@ types: type: EventMessageSent "reliable:message:acknowledged": type: EventMessageAcknowledged - description: "Message definitively acknowledged via causal history." "reliable:message:send-error": type: EventMessageSendError "reliable:message:irretrievable": type: EventIrretrievableMessage - description: "Missing message could not be retrieved after all store-query attempts." "reliable:sync:status": type: EventSyncStatus - description: "Channel sync status changed between 'synced' and 'syncing'." ``` #### Messaging function definitions From d85c71b7d12705e560a812ac86b187746b42e8c2 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 23 Apr 2026 23:37:01 +0200 Subject: [PATCH 093/174] rm segmentation api details --- standards/application/reliable-channel-api.md | 45 ++----------------- 1 file changed, 3 insertions(+), 42 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index ff126ac..06ca43f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -105,28 +105,6 @@ This API considers the types defined by [MESSAGING-API](/standards/application/m ```yaml types: - MessageChunk: - type: object - description: "Represents the minimum unit of data transmitted across the network. Its size is governed by SegmentationConfig. Chunks are chained to their predecessors, and any chunk whose linkage to its predecessor cannot be verified MUST be discarded. - Only the first chunk on every message, is rate-limited (RLN) and the subsequent chunks MUST be accepted rate-limit wise." - fields: - chunkId: - type: string - description: UUID for the chunk - previousChunkId: - type: string - description: Previous chunk ID. Chunks with unvalidated previous chunks MUST be rejected. - This field is empty when chunkIndex == 0. - chunkIndex: - type: uint - description: "Zero-based position of this chunk within the ordered sequence of chunks that form the original message." - lastChunkIndex: - type: uint - description: "All chunks of same message have the same value, i.e., num-chunks - 1." - requestId: - type: RequestId - description: "The request id this chunk belongs to. This is generated by the send function. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." - SyncStatusDetail: type: object description: "Provides a snapshot of the channel's synchronisation state." @@ -220,7 +198,7 @@ types: fields: segmentationConfig: type: SegmentationConfig - description: "Configuration for message segmentation. Please refer to [SEGMENTATION](./segmentation.md) for more details." + description: "Configuration for message segmentation. Refer to [SEGMENTATION-API](./segmentation-api.md) for details." sdsConfig: type: SdsConfig description: "Configuration for Scalable Data Sync." @@ -233,15 +211,6 @@ types: default: none description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." - SegmentationConfig: - type: object - fields: - chunkSizeBytes: - type: uint - default: 102400 # 100 KiB - description: "Maximum chunk size in bytes. - Messages larger than this value are split before SDS processing." - SdsConfig: type: object fields: @@ -425,7 +394,7 @@ functions: When `send` is called, the implementation MUST process the message in the following order: -1. **Segment**: Split the payload into chunks of at most `chunkSizeBytes` as defined in `SegmentationConfig`. +1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply SDS**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. 4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). @@ -454,15 +423,7 @@ Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit ### Segmentation -Segmentation splits outgoing messages into chunks before SDS processing. -This ensures each chunk fits within the network's maximum message size. - -- The default chunk size is `100 KiB` (`102400 bytes`.) -- Chunks MUST be tagged with metadata sufficient for the receiver to reassemble the original message: - a message identifier, chunk index, and total chunk count. -- Segmentation MUST be transparent to the SDS layer; SDS operates on individual chunks. -- The maximum allowed message size is `1MiB` (`1048576 bytes`.) -- Messages that are bigger than the maximum allowed size will be discarded automatically and an error will be given to the caller. +See [SEGMENTATION-API](./segmentation-api.md). ### Scalable Data Sync (SDS) From eed8689530a5fcb5312c5b08faba0b89f44f741e Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 00:10:43 +0200 Subject: [PATCH 094/174] improve ReliableEnvelope and its refs within the spec --- standards/application/reliable-channel-api.md | 34 ++++++++----------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 06ca43f..0a23961 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -164,20 +164,20 @@ types: types: ReliableEnvelope: type: object - description: "Represents an extension of the MessageEnvelope defined in MESSAGING-API aiming mostly to allow - including a reliable channel id attribute that, when given, it will assume the message should be sent reliably. Therefore, we leave open for implementors to replace the MessageEnvelope implementation and just add the reliable channel id there." + description: "Wraps a MessageEnvelope (defined in [MESSAGING-API](/standards/application/messaging-api.md)) with a reliable channel identifier. + An empty channelId marks the message as ephemeral; a non-empty value routes it through the named reliable channel for segmentation, SDS tracking, and encryption." fields: messageEnvelope: type: MessageEnvelope - description: "Please refer to the [MESSAGING-API](/standards/application/messaging-api.md) for details." + description: "The message payload and metadata. Refer to [MESSAGING-API](/standards/application/messaging-api.md) for details." channelId: type: string default: "" description: "Reliable channel identifier. - If empty, the message is considered ephemeral: it is not tracked by SDS, never retransmitted, and NEVER segmented. + If empty, the message is ephemeral: not tracked by SDS, never retransmitted, and NEVER segmented. Ephemeral payloads exceeding the network size limit MUST be rejected with an error. When the rate limit is approached, ephemeral messages are dropped immediately rather than queued. - If != empty, the messageEnvelope will be segmented, SDS'ed and encrypted under the given reliable channel." + If non-empty, the messageEnvelope is segmented, registered with SDS, and encrypted under the named reliable channel." ReliableChannel: type: object @@ -299,12 +299,9 @@ types: requestId: type: RequestId description: "Identifier of the `send` operation that initiated the message sending. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." - contentTopic: - type: string - description: "Content topic on which the message was received" - payload: - type: array - description: "The decrypted and reassembled message payload" + envelope: + type: ReliableEnvelope + description: "The reassembled message and its channel context. `envelope.messageEnvelope.payload` contains the fully reassembled content; `envelope.channelId` identifies the channel on which it arrived." EventReliableMessageSent: type: object @@ -375,14 +372,11 @@ types: ```yaml functions: send: - description: "Send a message reliably through the channel. Applies segmentation, SDS, and encryption (if configured) before dispatching." + description: "Send a message through the reliable channel API. Routing and guarantees are determined by the envelope's channelId: empty means ephemeral; non-empty applies segmentation, SDS, and encryption (if configured) before dispatching." parameters: - - name: channel - type: optional - description: "The reliable channel to use for sending. If not provided, the message is sent without delivery guarantees and is treated as ephemeral." - - name: payload - type: array - description: "The raw message payload to send." + - name: envelope + type: ReliableEnvelope + description: "The envelope containing the message and channel routing information." returns: type: result description: "`RequestId` is defined in [MESSAGING-API](./messaging-api.md)." @@ -392,12 +386,12 @@ functions: **Outgoing message processing order**: -When `send` is called, the implementation MUST process the message in the following order: +When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, the implementation MUST process `envelope.messageEnvelope.payload` in the following order: 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply SDS**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. -4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). +4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md) using `envelope.messageEnvelope.content_topic` as the destination. **Incoming message processing order**: From fabf0e0eb4e62603071e0d9a92a1bf1dfea7bf7c Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 00:15:29 +0200 Subject: [PATCH 095/174] rm sync status stuff to avoid confusion --- standards/application/reliable-channel-api.md | 37 ------------------- 1 file changed, 37 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 0a23961..d45935c 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -105,27 +105,6 @@ This API considers the types defined by [MESSAGING-API](/standards/application/m ```yaml types: - SyncStatusDetail: - type: object - description: "Provides a snapshot of the channel's synchronisation state." - fields: - received: - type: uint - description: "Number of messages successfully received." - missing: - type: uint - description: "Number of messages detected as missing but not yet retrieved." - lost: - type: uint - description: "Number of messages that could not be retrieved after all attempts." - - SyncStatus: - type: enum - description: "Indicates whether the channel has detected any outstanding missing messages." - values: - - synced: "No known missing messages (some may be permanently lost)." - - syncing: "Actively attempting to retrieve one or more missing messages." - IEncryption: type: object description: "Interface for a pluggable encryption mechanism. @@ -189,9 +168,6 @@ types: messageEvents: type: MessageEvents description: "Event emitter for message-related events on this channel" - syncStatus: - type: SyncStatus - description: "Current synchronisation status of the channel. Transitions between 'syncing' and 'synced' as missing messages are detected and resolved." ReliableChannelConfig: type: object @@ -338,17 +314,6 @@ types: type: RequestId description: "The request ID of the unrecoverable message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." - EventSyncStatus: - type: object - description: "Event emitted when the channel's sync status transitions between 'synced' and 'syncing'." - fields: - status: - type: SyncStatus - description: "The new sync status" - detail: - type: SyncStatusDetail - description: "Counters describing the current sync state" - MessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" @@ -363,8 +328,6 @@ types: type: EventMessageSendError "reliable:message:irretrievable": type: EventIrretrievableMessage - "reliable:sync:status": - type: EventSyncStatus ``` #### Messaging function definitions From 3eb8543c09c22bd0c59f11014cb29a2f52dd2524 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 00:18:20 +0200 Subject: [PATCH 096/174] cleanup some unnecessary event types --- standards/application/reliable-channel-api.md | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index d45935c..920dbf3 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -298,22 +298,6 @@ types: type: string description: "Error message describing what went wrong" - EventMessageAcknowledged: - type: object - description: "Event emitted when the message has been definitively acknowledged via causal history." - fields: - requestId: - type: RequestId - description: "The request ID associated with the acknowledged message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." - - EventIrretrievableMessage: - type: object - description: "Event emitted when a missing message could not be retrieved after all store-query attempts." - fields: - requestId: - type: RequestId - description: "The request ID of the unrecoverable message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." - MessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" @@ -322,12 +306,8 @@ types: type: EventMessageReceived "reliable:message:sent": type: EventMessageSent - "reliable:message:acknowledged": - type: EventMessageAcknowledged "reliable:message:send-error": type: EventMessageSendError - "reliable:message:irretrievable": - type: EventIrretrievableMessage ``` #### Messaging function definitions From b03f1b8f247dea36c3e33e04c8c86c93588e4c45 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 00:28:42 +0200 Subject: [PATCH 097/174] refactor doc structure --- standards/application/reliable-channel-api.md | 122 +++++++----------- 1 file changed, 48 insertions(+), 74 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 920dbf3..7499c05 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -18,17 +18,9 @@ editor: Logos Messaging Team * [IDL](#idl) * [Architectural position](#architectural-position) * [The Reliable Channel API](#the-reliable-channel-api) - * [Common](#common) - * [Common type definitions](#common-type-definitions) - * [Channel](#channel) - * [Channel type definitions](#channel-type-definitions) - * [Channel function definitions](#channel-function-definitions) - * [Channel predefined values](#channel-predefined-values) - * [Channel extended definitions](#channel-extended-definitions) - * [Messaging](#messaging) - * [Messaging type definitions](#messaging-type-definitions) - * [Messaging function definitions](#messaging-function-definitions) - * [Messaging extended definitions](#messaging-extended-definitions) + * [Type definitions](#type-definitions) + * [Channel lifecycle](#channel-lifecycle) + * [Channel usage](#channel-usage) * [Components](#components) * [Segmentation](#segmentation) * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) @@ -97,11 +89,9 @@ The Reliable Channel API sits between the application layer and the Messaging AP ## The Reliable Channel API -### Common +This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following. -#### Common type definitions - -This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following: +### Type definitions ```yaml types: @@ -133,14 +123,7 @@ types: description: "Interface for a pluggable SDS persistence backend. Implementations MUST provide all functions required to save and retrieve SDS state per channel. Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." -``` -### Channel - -#### Channel type definitions - -```yaml -types: ReliableEnvelope: type: object description: "Wraps a MessageEnvelope (defined in [MESSAGING-API](/standards/application/messaging-api.md)) with a reliable channel identifier. @@ -217,57 +200,7 @@ types: type: uint default: 600000 # 10 minutes description: "The epoch size used by the RLN relay, in milliseconds." -``` -#### Channel function definitions - -```yaml -functions: - - createReliableChannel: - description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." - parameters: - - name: channelConfig - type: ReliableChannelConfig - description: "Configuration for the channel." - returns: - type: result - - closeChannel: - description: "Closes a reliable channel and releases all associated resources and internal state." - parameters: - - name: channel - type: ReliableChannel - description: "The channel to close." - returns: - type: result -``` - -#### Channel extended definitions - -**State management**: - -Each `ReliableChannel` MUST maintain internal state for SDS, including: -- A committed message log recording sent messages and their acknowledgement status. -- An outgoing buffer of unacknowledged message chunks pending confirmation. -- An incoming buffer for partially received segmented messages awaiting full reassembly. - -The state MUST be persisted according to the `historyBackend` specified in `SdsConfig`. -The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. - -**Encryption**: - -The `encryption` field in `ReliableChannelConfig` is intentionally optional. -The Reliable Channel API is agnostic to encryption mechanisms. - -When an `IEncryption` implementation is provided, it MUST be applied as described in the [Messaging extended definitions](#messaging-extended-definitions). - -### Messaging - -#### Messaging type definitions - -```yaml -types: EventMessageReceived: type: object description: "Event emitted when a complete message has been received and reassembled." @@ -310,7 +243,48 @@ types: type: EventMessageSendError ``` -#### Messaging function definitions +### Channel lifecycle + +```yaml +functions: + + createReliableChannel: + description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." + parameters: + - name: channelConfig + type: ReliableChannelConfig + description: "Configuration for the channel." + returns: + type: result + + closeChannel: + description: "Closes a reliable channel and releases all associated resources and internal state." + parameters: + - name: channel + type: ReliableChannel + description: "The channel to close." + returns: + type: result +``` + +**State management**: + +Each `ReliableChannel` MUST maintain internal state for SDS, including: +- A committed message log recording sent messages and their acknowledgement status. +- An outgoing buffer of unacknowledged message chunks pending confirmation. +- An incoming buffer for partially received segmented messages awaiting full reassembly. + +The state MUST be persisted according to the `historyBackend` specified in `SdsConfig`. +The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. + +**Encryption**: + +The `encryption` field in `ReliableChannelConfig` is intentionally optional. +The Reliable Channel API is agnostic to encryption mechanisms. + +When an `IEncryption` implementation is provided, it MUST be applied as described in [Channel usage](#channel-usage). + +### Channel usage ```yaml functions: @@ -325,7 +299,7 @@ functions: description: "`RequestId` is defined in [MESSAGING-API](./messaging-api.md)." ``` -#### Messaging extended definitions +Incoming events are emitted on `ReliableChannel.messageEvents` as defined by `MessageEvents`. **Outgoing message processing order**: From ce68befbef5860d28d907671acce0f3fb37e7779 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 00:40:49 +0200 Subject: [PATCH 098/174] add senderId as param for createReliableChannel func --- standards/application/reliable-channel-api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 7499c05..d827c7e 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -254,6 +254,9 @@ functions: - name: channelConfig type: ReliableChannelConfig description: "Configuration for the channel." + - name: senderId + type: string + description: "An identifier for this sender. SHOULD be unique and persisted between sessions." returns: type: result From 761b5fe97b968333d5e6757daf0f1946d898e6c6 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 08:48:25 +0200 Subject: [PATCH 099/174] fix wordlist --- .wordlist.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 0c53e71..cfa3774 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -29,6 +29,7 @@ ConnectionStatusEvent contentTopic contentTopics createNode +createReliableChannel creativecommons cryptographic danielkaiser @@ -56,6 +57,10 @@ eth Eth ETH EventEmitter +EventMessageReceived +EventMessageSendError +EventMessageSent +EventReliableMessageSent EventSource eventType fb @@ -78,6 +83,7 @@ iana IANA IDL IEncryption +IPersistence implementers implementor implementors @@ -91,6 +97,7 @@ JSON KiB Kozlov lastChunkIndex +lifecycle liblogosdelivery libp libp2p @@ -172,6 +179,7 @@ SDS'ed sdsConfig SdsConfig sdk +senderId syncStatus SyncStatus SyncStatusDetail From f5b1199a87dc76d42a627f6fc2178c3d2f9dbe29 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 09:28:49 +0200 Subject: [PATCH 100/174] add some leftover tweaks --- standards/application/reliable-channel-api.md | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index d827c7e..9d7ae90 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -45,8 +45,8 @@ The [MESSAGING-API](/standards/application/messaging-api.md) provides peer-to-pe but does not provide high end-to-end delivery guarantees from sender to recipient. This API addresses that gap by introducing: -- **Segmentation** to handle large messages exceeding network size limits. -- **SDS** to provide causal-history-based end-to-end acknowledgement and retransmission. +- **[SEGMENTATION-API](/standards/application/segmentation-api.md)** to handle large messages exceeding network size limits. +- **[SDS](https://lip.logos.co/ift-ts/raw/sds.html)** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. - **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload and content_topic from MessageEnvelope, defined in [MESSAGING-API](/standards/application/messaging-api.md). @@ -121,7 +121,7 @@ types: IPersistence: type: object description: "Interface for a pluggable SDS persistence backend. - Implementations MUST provide all functions required to save and retrieve SDS state per channel. + Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." ReliableEnvelope: @@ -272,12 +272,12 @@ functions: **State management**: -Each `ReliableChannel` MUST maintain internal state for SDS, including: +Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html). This state MAY be persisted within SDS implementation layer and includes: - A committed message log recording sent messages and their acknowledgement status. - An outgoing buffer of unacknowledged message chunks pending confirmation. - An incoming buffer for partially received segmented messages awaiting full reassembly. -The state MUST be persisted according to the `historyBackend` specified in `SdsConfig`. +The state MUST be persisted using to the `persistence` tool specified in `SdsConfig`. The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. **Encryption**: @@ -309,28 +309,29 @@ Incoming events are emitted on `ReliableChannel.messageEvents` as defined by `Me When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, the implementation MUST process `envelope.messageEnvelope.payload` in the following order: 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). -2. **Apply SDS**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. -4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md) using `envelope.messageEnvelope.content_topic` as the destination. +4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). **Incoming message processing order**: When a chunk is received from the network, the implementation MUST process it in the following order: 1. **Decrypt**: If an `IEncryption` implementation is provided, decrypt the chunk. -2. **Apply SDS**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. 3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. **Retransmission**: -The SDS layer MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, +A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, +according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, up to `maxRetransmissions` times. If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. **Rate limiting**: When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions -to comply with the RLN epoch constraints defined in `epochSizeMs`. +to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. ## Components @@ -341,7 +342,7 @@ See [SEGMENTATION-API](./segmentation-api.md). ### Scalable Data Sync (SDS) -SDS provides end-to-end delivery guarantees using causal history tracking. +[SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. - Each sent chunk is registered in an outgoing buffer. - The recipient sends acknowledgements back to the sender upon receiving chunks. @@ -361,7 +362,7 @@ The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messag The Encryption Hook provides a pluggable interface for upper layers to inject encryption. -- The hook is optional; when not provided, messages are sent as plaintext. +- The hook is optional; when not provided, messages are sent unencrypted. - Encryption is applied per chunk, after segmentation and SDS registration. - Decryption is applied per chunk, before SDS delivery. - The `IEncryption` interface MUST be implemented by the caller. From 706fa664d1f4c2907e20262b86f40699ed2f4b14 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 09:32:35 +0200 Subject: [PATCH 101/174] consistency changes --- standards/application/reliable-channel-api.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 9d7ae90..d2fd05d 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -212,7 +212,7 @@ types: type: ReliableEnvelope description: "The reassembled message and its channel context. `envelope.messageEnvelope.payload` contains the fully reassembled content; `envelope.channelId` identifies the channel on which it arrived." - EventReliableMessageSent: + EventMessageSent: type: object description: "Event emitted when all chunks of a message have been acknowledged by the network." fields: @@ -277,7 +277,7 @@ Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos. - An outgoing buffer of unacknowledged message chunks pending confirmation. - An incoming buffer for partially received segmented messages awaiting full reassembly. -The state MUST be persisted using to the `persistence` tool specified in `SdsConfig`. +The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. **Encryption**: @@ -311,7 +311,8 @@ When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. -4. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). +4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. +5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). **Incoming message processing order**: @@ -348,7 +349,7 @@ See [SEGMENTATION-API](./segmentation-api.md). - The recipient sends acknowledgements back to the sender upon receiving chunks. - The sender removes acknowledged chunks from the outgoing buffer. - Unacknowledged chunks are retransmitted after `acknowledgementTimeoutMs`. -- SDS state MUST be persisted in the configured `historyBackend`. +- SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. ### Rate Limit Manager From 4a73efc414e85e15b9a1755584827942e67f7942 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 09:45:22 +0200 Subject: [PATCH 102/174] introduce ReliableSendId concept --- standards/application/reliable-channel-api.md | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index d2fd05d..6ceac22 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -95,6 +95,16 @@ This API considers the types defined by [MESSAGING-API](/standards/application/m ```yaml types: + ReliableSendId: + type: string + description: "Unique identifier for a single `send` operation on a reliable channel. + It groups all chunks produced by segmenting one envelope, so callers can correlate + acknowledgement and error events back to the original send call. + Internally, each chunk is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, + producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per chunk. + A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, + one per chunk sent." + IEncryption: type: object description: "Interface for a pluggable encryption mechanism. @@ -206,8 +216,8 @@ types: description: "Event emitted when a complete message has been received and reassembled." fields: requestId: - type: RequestId - description: "Identifier of the `send` operation that initiated the message sending. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." + type: ReliableSendId + description: "Identifier of the `send` operation that produced this message." envelope: type: ReliableEnvelope description: "The reassembled message and its channel context. `envelope.messageEnvelope.payload` contains the fully reassembled content; `envelope.channelId` identifies the channel on which it arrived." @@ -217,16 +227,16 @@ types: description: "Event emitted when all chunks of a message have been acknowledged by the network." fields: requestId: - type: RequestId - description: "The request ID associated with the sent message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." + type: ReliableSendId + description: "The identifier of the `send` operation whose chunks have all been acknowledged." EventMessageSendError: type: object description: "Event emitted when a message send operation fails after exhausting retransmission attempts." fields: requestId: - type: RequestId - description: "The request ID associated with the failed message. `RequestId` is defined in [MESSAGING-API](./messaging-api.md)." + type: ReliableSendId + description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." error: type: string description: "Error message describing what went wrong" @@ -298,8 +308,8 @@ functions: type: ReliableEnvelope description: "The envelope containing the message and channel routing information." returns: - type: result - description: "`RequestId` is defined in [MESSAGING-API](./messaging-api.md)." + type: result + description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." ``` Incoming events are emitted on `ReliableChannel.messageEvents` as defined by `MessageEvents`. From 1acec4f7e1b586accc9714d26435d933850d1803 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 09:45:43 +0200 Subject: [PATCH 103/174] have event names in same style as messaging-api --- standards/application/reliable-channel-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 6ceac22..cff2d7a 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -211,7 +211,7 @@ types: default: 600000 # 10 minutes description: "The epoch size used by the RLN relay, in milliseconds." - EventMessageReceived: + MessageReceivedEvent: type: object description: "Event emitted when a complete message has been received and reassembled." fields: @@ -222,7 +222,7 @@ types: type: ReliableEnvelope description: "The reassembled message and its channel context. `envelope.messageEnvelope.payload` contains the fully reassembled content; `envelope.channelId` identifies the channel on which it arrived." - EventMessageSent: + MessageSentEvent: type: object description: "Event emitted when all chunks of a message have been acknowledged by the network." fields: @@ -230,7 +230,7 @@ types: type: ReliableSendId description: "The identifier of the `send` operation whose chunks have all been acknowledged." - EventMessageSendError: + MessageSendErrorEvent: type: object description: "Event emitted when a message send operation fails after exhausting retransmission attempts." fields: @@ -246,11 +246,11 @@ types: description: "Event source for reliable message events on a channel" events: "reliable:message:received": - type: EventMessageReceived + type: MessageReceivedEvent "reliable:message:sent": - type: EventMessageSent + type: MessageSentEvent "reliable:message:send-error": - type: EventMessageSendError + type: MessageSendErrorEvent ``` ### Channel lifecycle From 03c146b6b9723c0d9a75016dd26547a008da439e Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 09:49:50 +0200 Subject: [PATCH 104/174] rm unneeded line --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index cff2d7a..d99cebb 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -288,7 +288,7 @@ Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos. - An incoming buffer for partially received segmented messages awaiting full reassembly. The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. -The default `memory` backend does not survive process restarts; implementors providing persistence SHOULD use a durable backend. + **Encryption**: From 506fbbd317667f3f53802559d18b63917ffcd180 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 11:04:33 +0200 Subject: [PATCH 105/174] fix spelling issue --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index cfa3774..6df90fa 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -148,6 +148,7 @@ Raya's ReliableChannel ReliableChannelConfig ReliableEnvelope +ReliableSendId ReliableIrretrievableMessageEvent ReliableMessageAcknowledgedEvent ReliableMessageEvents From 137f22f16d7652c08cdebb4c54fa33fd430f77fb Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 12:10:41 +0200 Subject: [PATCH 106/174] reorganize sections from goals to code --- standards/application/reliable-channel-api.md | 181 +++++++++--------- 1 file changed, 90 insertions(+), 91 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index d99cebb..baa374f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -15,17 +15,24 @@ editor: Logos Messaging Team * [Motivation](#motivation) * [Syntax](#syntax) * [API design](#api-design) - * [IDL](#idl) * [Architectural position](#architectural-position) - * [The Reliable Channel API](#the-reliable-channel-api) - * [Type definitions](#type-definitions) - * [Channel lifecycle](#channel-lifecycle) - * [Channel usage](#channel-usage) + * [IDL](#idl) * [Components](#components) * [Segmentation](#segmentation) * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) * [Rate Limit Manager](#rate-limit-manager) * [Encryption Hook](#encryption-hook) + * [Procedures](#procedures) + * [State management](#state-management) + * [Outgoing message processing](#outgoing-message-processing) + * [Incoming message processing](#incoming-message-processing) + * [Retransmission](#retransmission) + * [Rate limiting](#rate-limiting) + * [Encryption](#encryption) + * [The Reliable Channel API](#the-reliable-channel-api) + * [Type definitions](#type-definitions) + * [Channel lifecycle](#channel-lifecycle) + * [Channel usage](#channel-usage) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -60,10 +67,6 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH ## API design -### IDL - -A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). - ### Architectural position The Reliable Channel API sits between the application layer and the Messaging API, as follows: @@ -87,6 +90,84 @@ The Reliable Channel API sits between the application layer and the Messaging AP └────────────────────────────────────────────────────────────┘ ``` +### IDL + +A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). + +## Components + +### Segmentation + +See [SEGMENTATION-API](./segmentation-api.md). + +### Scalable Data Sync (SDS) + +[SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. + +- Each sent chunk is registered in an outgoing buffer. +- The recipient sends acknowledgements back to the sender upon receiving chunks. +- The sender removes acknowledged chunks from the outgoing buffer. +- Unacknowledged chunks are retransmitted after `acknowledgementTimeoutMs`. +- SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. + +### Rate Limit Manager + +The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. + +- It tracks how many messages have been sent in the current epoch (only the first chunk of each message counts toward the rate limit; subsequent chunks are exempt). +- When the limit is approached, chunk dispatch MUST be delayed to the next epoch. +- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. + +### Encryption Hook + +The Encryption Hook provides a pluggable interface for upper layers to inject encryption. + +- The hook is optional; when not provided, messages are sent unencrypted. +- Encryption is applied per chunk, after segmentation and SDS registration. +- Decryption is applied per chunk, before SDS delivery. +- The `IEncryption` interface MUST be implemented by the caller. +- The Reliable Channel API MUST NOT impose any specific encryption scheme. + +## Procedures + +### Outgoing message processing + +When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, the implementation MUST process `envelope.messageEnvelope.payload` in the following order: + +1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. +3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. +4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. +5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). + +### Incoming message processing + +When a chunk is received from the network, the implementation MUST process it in the following order: + +1. **Decrypt**: If an `IEncryption` implementation is provided, decrypt the chunk. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. +3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. + +### Retransmission + +A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, +according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, +up to `maxRetransmissions` times. +If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. + +### Rate limiting + +When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions +to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. +Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. + +### Encryption + +The `encryption` field in `ReliableChannelConfig` is intentionally optional. +The Reliable Channel API is agnostic to encryption mechanisms. + +When an `IEncryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). + ## The Reliable Channel API This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following. @@ -280,23 +361,6 @@ functions: type: result ``` -**State management**: - -Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html). This state MAY be persisted within SDS implementation layer and includes: -- A committed message log recording sent messages and their acknowledgement status. -- An outgoing buffer of unacknowledged message chunks pending confirmation. -- An incoming buffer for partially received segmented messages awaiting full reassembly. - -The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. - - -**Encryption**: - -The `encryption` field in `ReliableChannelConfig` is intentionally optional. -The Reliable Channel API is agnostic to encryption mechanisms. - -When an `IEncryption` implementation is provided, it MUST be applied as described in [Channel usage](#channel-usage). - ### Channel usage ```yaml @@ -314,71 +378,6 @@ functions: Incoming events are emitted on `ReliableChannel.messageEvents` as defined by `MessageEvents`. -**Outgoing message processing order**: - -When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, the implementation MUST process `envelope.messageEnvelope.payload` in the following order: - -1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. -3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. -4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. -5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). - -**Incoming message processing order**: - -When a chunk is received from the network, the implementation MUST process it in the following order: - -1. **Decrypt**: If an `IEncryption` implementation is provided, decrypt the chunk. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. -3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. - -**Retransmission**: - -A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, -according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, -up to `maxRetransmissions` times. -If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. - -**Rate limiting**: - -When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions -to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. -Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. - -## Components - -### Segmentation - -See [SEGMENTATION-API](./segmentation-api.md). - -### Scalable Data Sync (SDS) - -[SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. - -- Each sent chunk is registered in an outgoing buffer. -- The recipient sends acknowledgements back to the sender upon receiving chunks. -- The sender removes acknowledged chunks from the outgoing buffer. -- Unacknowledged chunks are retransmitted after `acknowledgementTimeoutMs`. -- SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. - -### Rate Limit Manager - -The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. - -- It tracks how many messages have been sent in the current epoch (only the first chunk of each message counts toward the rate limit; subsequent chunks are exempt). -- When the limit is approached, chunk dispatch MUST be delayed to the next epoch. -- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. - -### Encryption Hook - -The Encryption Hook provides a pluggable interface for upper layers to inject encryption. - -- The hook is optional; when not provided, messages are sent unencrypted. -- Encryption is applied per chunk, after segmentation and SDS registration. -- Decryption is applied per chunk, before SDS delivery. -- The `IEncryption` interface MUST be implemented by the caller. -- The Reliable Channel API MUST NOT impose any specific encryption scheme. - ## Security/Privacy Considerations - This API does not provide confidentiality by default. An `IEncryption` implementation MUST be supplied when confidentiality is required. From 7de551edf9745ac1104ec63b7523cf7a2115ef13 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 14:05:37 +0200 Subject: [PATCH 107/174] use encryption as a parameter in createReliableChannel --- standards/application/reliable-channel-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index baa374f..fb49446 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -163,7 +163,7 @@ Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit ### Encryption -The `encryption` field in `ReliableChannelConfig` is intentionally optional. +The `encryption` parameter in `createReliableChannel` is intentionally optional. The Reliable Channel API is agnostic to encryption mechanisms. When an `IEncryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). @@ -189,7 +189,7 @@ types: IEncryption: type: object description: "Interface for a pluggable encryption mechanism. - When provided, see ReliableChannelConfig, the API consumer MUST implement both encrypt and decrypt operations. + When provided as a parameter to `createReliableChannel`, the API consumer MUST implement both encrypt and decrypt operations. Implementations MAY use different signatures than those described below, as long as each operation accepts a byte array and returns a byte array." fields: encrypt: @@ -256,10 +256,6 @@ types: type: RateLimitConfig default: DefaultRateLimitConfig description: "Configuration for rate limit management." - encryption: - type: optional - default: none - description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." SdsConfig: type: object @@ -348,6 +344,10 @@ functions: - name: senderId type: string description: "An identifier for this sender. SHOULD be unique and persisted between sessions." + - name: encryption + type: optional + default: none + description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." returns: type: result From 17624e72ffc4aeb57ac7203a5aaf949ce05615b4 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 16:45:55 +0200 Subject: [PATCH 108/174] Remove ReliableEnvelope --- standards/application/reliable-channel-api.md | 33 +++++-------------- 1 file changed, 8 insertions(+), 25 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index fb49446..47a0921 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -132,7 +132,7 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en ### Outgoing message processing -When `send` is called with a `ReliableEnvelope` whose `channelId` is non-empty, the implementation MUST process `envelope.messageEnvelope.payload` in the following order: +When `send` is called, the implementation MUST process `message.payload` in the following order: 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. @@ -215,23 +215,6 @@ types: Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." - ReliableEnvelope: - type: object - description: "Wraps a MessageEnvelope (defined in [MESSAGING-API](/standards/application/messaging-api.md)) with a reliable channel identifier. - An empty channelId marks the message as ephemeral; a non-empty value routes it through the named reliable channel for segmentation, SDS tracking, and encryption." - fields: - messageEnvelope: - type: MessageEnvelope - description: "The message payload and metadata. Refer to [MESSAGING-API](/standards/application/messaging-api.md) for details." - channelId: - type: string - default: "" - description: "Reliable channel identifier. - If empty, the message is ephemeral: not tracked by SDS, never retransmitted, and NEVER segmented. - Ephemeral payloads exceeding the network size limit MUST be rejected with an error. - When the rate limit is approached, ephemeral messages are dropped immediately rather than queued. - If non-empty, the messageEnvelope is segmented, registered with SDS, and encrypted under the named reliable channel." - ReliableChannel: type: object description: "An entity that guarantees message delivery among all participants on a single content topic." @@ -295,9 +278,9 @@ types: requestId: type: ReliableSendId description: "Identifier of the `send` operation that produced this message." - envelope: - type: ReliableEnvelope - description: "The reassembled message and its channel context. `envelope.messageEnvelope.payload` contains the fully reassembled content; `envelope.channelId` identifies the channel on which it arrived." + message: + type: MessageEnvelope + description: "The reassembled message. Defined in [MESSAGING-API](/standards/application/messaging-api.md)." MessageSentEvent: type: object @@ -366,11 +349,11 @@ functions: ```yaml functions: send: - description: "Send a message through the reliable channel API. Routing and guarantees are determined by the envelope's channelId: empty means ephemeral; non-empty applies segmentation, SDS, and encryption (if configured) before dispatching." + description: "Send a message through the reliable channel. The message is always segmented, SDS-tracked, rate-limited, and encrypted (if configured)." parameters: - - name: envelope - type: ReliableEnvelope - description: "The envelope containing the message and channel routing information." + - name: message + type: MessageEnvelope + description: "The message to send. Defined in [MESSAGING-API](/standards/application/messaging-api.md)." returns: type: result description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." From 4a9026d665fc6804977143fc15f4744cd9e85614 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 24 Apr 2026 16:55:49 +0200 Subject: [PATCH 109/174] Avoid specify ReliableChannel as it is handled internally --- standards/application/reliable-channel-api.md | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 47a0921..f036051 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -215,17 +215,6 @@ types: Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." - ReliableChannel: - type: object - description: "An entity that guarantees message delivery among all participants on a single content topic." - fields: - channelId: - type: string - description: "Unique identifier" - messageEvents: - type: MessageEvents - description: "Event emitter for message-related events on this channel" - ReliableChannelConfig: type: object fields: @@ -319,8 +308,18 @@ types: functions: createReliableChannel: - description: "Opens a reliable channel. Sets up the required SDS state, segmentation, and encryption." + description: "Opens a reliable channel for the given content topic. Sets up the required SDS state, + segmentation, and encryption, and subscribes to `contentTopic` via the underlying + [MESSAGING-API](/standards/application/messaging-api.md) so that incoming chunks are + routed through the incoming processing pipeline (see Procedures)." parameters: + - name: node + type: WakuNode + description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md). + Used to send chunks and to subscribe/unsubscribe to the content topic." + - name: contentTopic + type: string + description: "The content topic this channel listens and sends on." - name: channelConfig type: ReliableChannelConfig description: "Configuration for the channel." @@ -332,14 +331,16 @@ functions: default: none description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." returns: - type: result + type: result closeChannel: - description: "Closes a reliable channel and releases all associated resources and internal state." + description: "Closes the reliable channel associated with the given content topic, + releases all associated resources and internal state, + and unsubscribes from `contentTopic` via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." parameters: - - name: channel - type: ReliableChannel - description: "The channel to close." + - name: contentTopic + type: string + description: "The content topic identifying the channel to close. MUST match the one passed to `createReliableChannel`." returns: type: result ``` @@ -349,17 +350,22 @@ functions: ```yaml functions: send: - description: "Send a message through the reliable channel. The message is always segmented, SDS-tracked, rate-limited, and encrypted (if configured)." + description: "Send a message through the reliable channel registered for `message.content_topic`. + The message is always segmented, SDS-tracked, rate-limited, and encrypted (if configured). + MUST return an error if no channel has been created for `message.content_topic`." parameters: + - name: node + type: WakuNode + description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md)." - name: message type: MessageEnvelope - description: "The message to send. Defined in [MESSAGING-API](/standards/application/messaging-api.md)." + description: "The message to send. `message.content_topic` is used to resolve the channel internally." returns: type: result description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." ``` -Incoming events are emitted on `ReliableChannel.messageEvents` as defined by `MessageEvents`. +Incoming events are emitted on the `node.messageEvents` event emitter, as defined by `MessageEvents` in [MESSAGING-API](/standards/application/messaging-api.md), filtered to the channel's content topic. ## Security/Privacy Considerations From 73e0e0ba0ab47d7496227ccdbe2f59925f4e1334 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Sat, 25 Apr 2026 00:05:32 +0200 Subject: [PATCH 110/174] restore back ReliableChannel object type and its deps --- standards/application/reliable-channel-api.md | 51 +++++++++++-------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f036051..f436dcd 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -215,6 +215,16 @@ types: Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." + ReliableChannel: + type: object + description: "An opaque handle representing a reliable channel. + Returned by `createReliableChannel` and used to send messages and receive events. + Internal state (SDS, segmentation, encryption) is managed by the implementation." + fields: + messageEvents: + type: MessageEvents + description: "Event emitter for reliable message events scoped to this channel." + ReliableChannelConfig: type: object fields: @@ -308,18 +318,21 @@ types: functions: createReliableChannel: - description: "Opens a reliable channel for the given content topic. Sets up the required SDS state, - segmentation, and encryption, and subscribes to `contentTopic` via the underlying + description: "Opens a reliable channel over the given content topics. Sets up the required SDS state, + segmentation, and encryption, and subscribes to `contentTopics` via the underlying [MESSAGING-API](/standards/application/messaging-api.md) so that incoming chunks are routed through the incoming processing pipeline (see Procedures)." parameters: - name: node type: WakuNode description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md). - Used to send chunks and to subscribe/unsubscribe to the content topic." - - name: contentTopic + Used to send chunks and to subscribe/unsubscribe to the content topics." + - name: channelId type: string - description: "The content topic this channel listens and sends on." + description: "Unique identifier for this channel." + - name: contentTopics + type: seq + description: "The content topics this channel listens and sends on." - name: channelConfig type: ReliableChannelConfig description: "Configuration for the channel." @@ -331,16 +344,15 @@ functions: default: none description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." returns: - type: result + type: result closeChannel: - description: "Closes the reliable channel associated with the given content topic, - releases all associated resources and internal state, - and unsubscribes from `contentTopic` via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." + description: "Closes a reliable channel, releases all associated resources and internal state, + and unsubscribes from its content topics via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." parameters: - - name: contentTopic - type: string - description: "The content topic identifying the channel to close. MUST match the one passed to `createReliableChannel`." + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." returns: type: result ``` @@ -350,22 +362,21 @@ functions: ```yaml functions: send: - description: "Send a message through the reliable channel registered for `message.content_topic`. - The message is always segmented, SDS-tracked, rate-limited, and encrypted (if configured). - MUST return an error if no channel has been created for `message.content_topic`." + description: "Send a message through a reliable channel. The message is always segmented, + SDS-tracked, rate-limited, and encrypted (if configured)." parameters: - - name: node - type: WakuNode - description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md)." + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." - name: message type: MessageEnvelope - description: "The message to send. `message.content_topic` is used to resolve the channel internally." + description: "The message to send. `message.content_topic` MUST be one of the topics the channel was opened with." returns: type: result description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." ``` -Incoming events are emitted on the `node.messageEvents` event emitter, as defined by `MessageEvents` in [MESSAGING-API](/standards/application/messaging-api.md), filtered to the channel's content topic. +Incoming events are emitted on `channel.messageEvents` as defined by `MessageEvents`. ## Security/Privacy Considerations From b0967ac293bde44d94038278f84aaf55b3aaff7d Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Sat, 25 Apr 2026 00:47:03 +0200 Subject: [PATCH 111/174] fix some leftovers --- standards/application/reliable-channel-api.md | 45 ++++++++++--------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f436dcd..1e4ac61 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -55,7 +55,7 @@ This API addresses that gap by introducing: - **[SEGMENTATION-API](/standards/application/segmentation-api.md)** to handle large messages exceeding network size limits. - **[SDS](https://lip.logos.co/ift-ts/raw/sds.html)** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. -- **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload and content_topic from MessageEnvelope, defined in [MESSAGING-API](/standards/application/messaging-api.md). +- **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload. The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, which are handled by higher layers. @@ -130,9 +130,18 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en ## Procedures +### State management + +Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html), keyed by `channelId`. This state MAY be persisted within the SDS implementation layer and includes: +- A committed message log recording sent messages and their acknowledgement status. +- An outgoing buffer of unacknowledged message chunks pending confirmation. +- An incoming buffer for partially received segmented messages awaiting full reassembly. + +The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. + ### Outgoing message processing -When `send` is called, the implementation MUST process `message.payload` in the following order: +When `send` is called, the implementation MUST process `message` in the following order: 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. @@ -179,7 +188,7 @@ types: ReliableSendId: type: string description: "Unique identifier for a single `send` operation on a reliable channel. - It groups all chunks produced by segmenting one envelope, so callers can correlate + It groups all chunks produced by segmenting one message, so callers can correlate acknowledgement and error events back to the original send call. Internally, each chunk is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per chunk. @@ -217,7 +226,7 @@ types: ReliableChannel: type: object - description: "An opaque handle representing a reliable channel. + description: "A handle representing an open reliable channel. Returned by `createReliableChannel` and used to send messages and receive events. Internal state (SDS, segmentation, encryption) is managed by the implementation." fields: @@ -274,12 +283,9 @@ types: type: object description: "Event emitted when a complete message has been received and reassembled." fields: - requestId: - type: ReliableSendId - description: "Identifier of the `send` operation that produced this message." message: - type: MessageEnvelope - description: "The reassembled message. Defined in [MESSAGING-API](/standards/application/messaging-api.md)." + type: array + description: "The reassembled message payload." MessageSentEvent: type: object @@ -318,10 +324,9 @@ types: functions: createReliableChannel: - description: "Opens a reliable channel over the given content topics. Sets up the required SDS state, - segmentation, and encryption, and subscribes to `contentTopics` via the underlying - [MESSAGING-API](/standards/application/messaging-api.md) so that incoming chunks are - routed through the incoming processing pipeline (see Procedures)." + description: "Opens a reliable channel over the given content topic. Sets up the required SDS state, + segmentation, and encryption, and subscribes to `contentTopic` via the underlying + [MESSAGING-API](/standards/application/messaging-api.md)." parameters: - name: node type: WakuNode @@ -329,10 +334,10 @@ functions: Used to send chunks and to subscribe/unsubscribe to the content topics." - name: channelId type: string - description: "Unique identifier for this channel." - - name: contentTopics - type: seq - description: "The content topics this channel listens and sends on." + description: "Unique identifier for this channel. Represents the reliable (SDS), segmented, and optionally-encrypted session." + - name: contentTopic + type: string + description: "The topic this channel listens and sends on. This has routing and filtering connotations." - name: channelConfig type: ReliableChannelConfig description: "Configuration for the channel." @@ -348,7 +353,7 @@ functions: closeChannel: description: "Closes a reliable channel, releases all associated resources and internal state, - and unsubscribes from its content topics via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." + and unsubscribes from its content topic via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." parameters: - name: channel type: ReliableChannel @@ -369,8 +374,8 @@ functions: type: ReliableChannel description: "The channel handle returned by `createReliableChannel`." - name: message - type: MessageEnvelope - description: "The message to send. `message.content_topic` MUST be one of the topics the channel was opened with." + type: array + description: "The raw message payload to send." returns: type: result description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." From 77b933377ecb53ce0fc8c35cd29385cd74a9b0f7 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 27 Apr 2026 16:05:49 +0200 Subject: [PATCH 112/174] put RateLimitConfig and SdsConfig at node-level --- standards/application/reliable-channel-api.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 1e4ac61..00ea1b9 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -179,7 +179,8 @@ When an `IEncryption` implementation is provided, it MUST be applied as describe ## The Reliable Channel API -This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following. +This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following (including `SdsConfig` and `RateLimitConfig`). +It also extends `NodeConfig`, defined in [MESSAGING-API](/standards/application/messaging-api.md), with `sds_config` and `rate_limit_config` fields, whose types are defined here. ### Type definitions @@ -234,22 +235,23 @@ types: type: MessageEvents description: "Event emitter for reliable message events scoped to this channel." - ReliableChannelConfig: - type: object - fields: - segmentationConfig: - type: SegmentationConfig - description: "Configuration for message segmentation. Refer to [SEGMENTATION-API](./segmentation-api.md) for details." - sdsConfig: - type: SdsConfig - description: "Configuration for Scalable Data Sync." rateLimitConfig: type: RateLimitConfig default: DefaultRateLimitConfig description: "Configuration for rate limit management." + NodeConfig: # Extends NodeConfig defined in MESSAGING-API + fields: + sds_config: + type: SdsConfig + description: "SDS configuration. See SdsConfig defined in this spec." + rate_limit_config: + type: RateLimitConfig + description: "Rate limiting configuration, including RLN-specific attributes. See RateLimitConfig defined in this spec." + SdsConfig: type: object + description: Scalable Data Sync config items. fields: persistence: type: IPersistence @@ -269,10 +271,11 @@ types: RateLimitConfig: type: object + description: Rate limiting configuration, containing RLN-specific attributes. fields: enabled: type: bool - default: true + default: false description: "Whether rate limiting is enforced. SHOULD be true when RLN is active." epochSizeMs: type: uint @@ -338,9 +341,6 @@ functions: - name: contentTopic type: string description: "The topic this channel listens and sends on. This has routing and filtering connotations." - - name: channelConfig - type: ReliableChannelConfig - description: "Configuration for the channel." - name: senderId type: string description: "An identifier for this sender. SHOULD be unique and persisted between sessions." From 6371ee653168205b5729376f9b09765f8eddad16 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 27 Apr 2026 16:09:24 +0200 Subject: [PATCH 113/174] rm I from interfaces type names --- standards/application/reliable-channel-api.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 00ea1b9..87024db 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -125,7 +125,7 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en - The hook is optional; when not provided, messages are sent unencrypted. - Encryption is applied per chunk, after segmentation and SDS registration. - Decryption is applied per chunk, before SDS delivery. -- The `IEncryption` interface MUST be implemented by the caller. +- The `Encryption` interface MUST be implemented by the caller. - The Reliable Channel API MUST NOT impose any specific encryption scheme. ## Procedures @@ -145,7 +145,7 @@ When `send` is called, the implementation MUST process `message` in the followin 1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. -3. **Encrypt**: If an `IEncryption` implementation is provided, encrypt each chunk before transmission. +3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each chunk before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. 5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). @@ -153,7 +153,7 @@ When `send` is called, the implementation MUST process `message` in the followin When a chunk is received from the network, the implementation MUST process it in the following order: -1. **Decrypt**: If an `IEncryption` implementation is provided, decrypt the chunk. +1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the chunk. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. 3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. @@ -175,7 +175,7 @@ Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit The `encryption` parameter in `createReliableChannel` is intentionally optional. The Reliable Channel API is agnostic to encryption mechanisms. -When an `IEncryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). +When an `Encryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). ## The Reliable Channel API @@ -196,7 +196,7 @@ types: A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, one per chunk sent." - IEncryption: + Encryption: type: object description: "Interface for a pluggable encryption mechanism. When provided as a parameter to `createReliableChannel`, the API consumer MUST implement both encrypt and decrypt operations. @@ -219,7 +219,7 @@ types: returns: type: result, error> - IPersistence: + Persistence: type: object description: "Interface for a pluggable SDS persistence backend. Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. @@ -254,7 +254,7 @@ types: description: Scalable Data Sync config items. fields: persistence: - type: IPersistence + type: Persistence description: "Backend for persisting the SDS local history. Implementations MAY support custom backends." acknowledgementTimeoutMs: type: uint @@ -345,7 +345,7 @@ functions: type: string description: "An identifier for this sender. SHOULD be unique and persisted between sessions." - name: encryption - type: optional + type: optional default: none description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." returns: @@ -385,7 +385,7 @@ Incoming events are emitted on `channel.messageEvents` as defined by `MessageEve ## Security/Privacy Considerations -- This API does not provide confidentiality by default. An `IEncryption` implementation MUST be supplied when confidentiality is required. +- This API does not provide confidentiality by default. An `Encryption` implementation MUST be supplied when confidentiality is required. - Chunk metadata (message ID, chunk index, total chunks) is visible to network observers unless encrypted by the hook. - SDS acknowledgement messages are sent over the same content topic and are subject to the same confidentiality concerns. - Rate limiting compliance is required to avoid exclusion from the network by RLN-enforcing relays. From 689bc0da1033cd191f7e8b7138aafae36bf4d7a7 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 27 Apr 2026 16:34:17 +0200 Subject: [PATCH 114/174] restructure from general to particular --- standards/application/reliable-channel-api.md | 433 +++++++++--------- 1 file changed, 223 insertions(+), 210 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 87024db..85e169c 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -17,6 +17,11 @@ editor: Logos Messaging Team * [API design](#api-design) * [Architectural position](#architectural-position) * [IDL](#idl) + * [The Reliable Channel API](#the-reliable-channel-api) + * [Channel lifecycle](#channel-lifecycle) + * [Channel usage](#channel-usage) + * [Node configuration](#node-configuration) + * [Type definitions](#type-definitions) * [Components](#components) * [Segmentation](#segmentation) * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) @@ -29,10 +34,6 @@ editor: Logos Messaging Team * [Retransmission](#retransmission) * [Rate limiting](#rate-limiting) * [Encryption](#encryption) - * [The Reliable Channel API](#the-reliable-channel-api) - * [Type definitions](#type-definitions) - * [Channel lifecycle](#channel-lifecycle) - * [Channel usage](#channel-usage) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -94,6 +95,224 @@ The Reliable Channel API sits between the application layer and the Messaging AP A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). +## The Reliable Channel API + +This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following (including `SdsConfig` and `RateLimitConfig`). + +### Channel lifecycle + +This point assumes that a WakuNode instance is created beforehand. See `createNode` function +in [MESSAGING-API](/standards/application/messaging-api.md). + +```yaml +functions: + + createReliableChannel: + description: "Opens a reliable channel over the given content topic. Sets up the required SDS state, + segmentation, and encryption, and subscribes to `contentTopic` via the underlying + [MESSAGING-API](/standards/application/messaging-api.md)." + parameters: + - name: node + type: WakuNode + description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md). + Used to send chunks and to subscribe/unsubscribe to the content topics." + - name: channelId + type: string + description: "Unique identifier for this channel. Represents the reliable (SDS), segmented, and optionally-encrypted session." + - name: contentTopic + type: string + description: "The topic this channel listens and sends on. This has routing and filtering connotations." + - name: senderId + type: string + description: "An identifier for this sender. SHOULD be unique and persisted between sessions." + - name: encryption + type: optional + default: none + description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." + returns: + type: result + + closeChannel: + description: "Closes a reliable channel, releases all associated resources and internal state, + and unsubscribes from its content topic via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + returns: + type: result +``` + +### Channel usage + +```yaml +functions: + send: + description: "Send a message through a reliable channel. The message is always segmented, + SDS-tracked, rate-limited, and encrypted (if configured)." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + - name: message + type: array + description: "The raw message payload to send." + returns: + type: result + description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." +``` + +Incoming events are emitted on `channel.messageEvents` as defined by `MessageEvents`. + +### Node configuration + +This spec extends `NodeConfig`, needed to create a node, which is +defined in [MESSAGING-API](/standards/application/messaging-api.md), +with `sds_config` and `rate_limit_config` fields, whose types are defined +in [Type definitions](#type-definitions). + +```yaml +NodeConfig: # Extends NodeConfig defined in MESSAGING-API + fields: + sds_config: + type: SdsConfig + description: "SDS configuration. See SdsConfig defined in this spec." + rate_limit_config: + type: RateLimitConfig + description: "Rate limiting configuration, including RLN-specific attributes. See RateLimitConfig defined in this spec." +``` + +### Type definitions + +```yaml +types: + + ReliableChannel: + type: object + description: "A handle representing an open reliable channel. + Returned by `createReliableChannel` and used to send messages and receive events. + Internal state (SDS, segmentation, encryption) is managed by the implementation." + fields: + messageEvents: + type: MessageEvents + description: "Event emitter for reliable message events scoped to this channel." + + rateLimitConfig: + type: RateLimitConfig + default: DefaultRateLimitConfig + description: "Configuration for rate limit management." + + MessageEvents: + type: event_emitter + description: "Event source for reliable message events on a channel" + events: + "reliable:message:received": + type: MessageReceivedEvent + "reliable:message:sent": + type: MessageSentEvent + "reliable:message:send-error": + type: MessageSendErrorEvent + + MessageReceivedEvent: + type: object + description: "Event emitted when a complete message has been received and reassembled." + fields: + message: + type: array + description: "The reassembled message payload." + + MessageSentEvent: + type: object + description: "Event emitted when all chunks of a message have been acknowledged by the network." + fields: + requestId: + type: ReliableSendId + description: "The identifier of the `send` operation whose chunks have all been acknowledged." + + MessageSendErrorEvent: + type: object + description: "Event emitted when a message send operation fails after exhausting retransmission attempts." + fields: + requestId: + type: ReliableSendId + description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." + error: + type: string + description: "Error message describing what went wrong" + + ReliableSendId: + type: string + description: "Unique identifier for a single `send` operation on a reliable channel. + It groups all chunks produced by segmenting one message, so callers can correlate + acknowledgement and error events back to the original send call. + Internally, each chunk is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, + producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per chunk. + A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, + one per chunk sent." + + SdsConfig: + type: object + description: Scalable Data Sync config items. + fields: + persistence: + type: Persistence + description: "Backend for persisting the SDS local history. Implementations MAY support custom backends." + acknowledgementTimeoutMs: + type: uint + default: 5000 + description: "Time in milliseconds to wait for acknowledgement before retransmitting." + maxRetransmissions: + type: uint + default: 5 + description: "Maximum number of retransmission attempts before considering delivery failed." + causalHistorySize: + type: uint + default: 2 + description: "Number of message IDs to consider in the causal history. With longer value, a stronger correctness is guaranteed but it requires higher bandwidth and memory." + + RateLimitConfig: + type: object + description: Rate limiting configuration, containing RLN-specific attributes. + fields: + enabled: + type: bool + default: false + description: "Whether rate limiting is enforced. SHOULD be true when RLN is active." + epochSizeMs: + type: uint + default: 600000 # 10 minutes + description: "The epoch size used by the RLN relay, in milliseconds." + + Encryption: + type: object + description: "Interface for a pluggable encryption mechanism. + When provided as a parameter to `createReliableChannel`, the API consumer MUST implement both encrypt and decrypt operations. + Implementations MAY use different signatures than those described below, as long as each operation accepts a byte array and returns a byte array." + fields: + encrypt: + type: function + description: "Encrypts a byte payload. Returns the encrypted payload." + parameters: + - name: content + type: array + returns: + type: result, error> + decrypt: + type: function + description: "Decrypts a byte payload. Returns the decrypted payload." + parameters: + - name: payload + type: array + returns: + type: result, error> + + Persistence: + type: object + description: "Interface for a pluggable SDS persistence backend. + Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. + Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." +``` + ## Components ### Segmentation @@ -177,212 +396,6 @@ The Reliable Channel API is agnostic to encryption mechanisms. When an `Encryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). -## The Reliable Channel API - -This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following (including `SdsConfig` and `RateLimitConfig`). -It also extends `NodeConfig`, defined in [MESSAGING-API](/standards/application/messaging-api.md), with `sds_config` and `rate_limit_config` fields, whose types are defined here. - -### Type definitions - -```yaml -types: - ReliableSendId: - type: string - description: "Unique identifier for a single `send` operation on a reliable channel. - It groups all chunks produced by segmenting one message, so callers can correlate - acknowledgement and error events back to the original send call. - Internally, each chunk is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, - producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per chunk. - A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, - one per chunk sent." - - Encryption: - type: object - description: "Interface for a pluggable encryption mechanism. - When provided as a parameter to `createReliableChannel`, the API consumer MUST implement both encrypt and decrypt operations. - Implementations MAY use different signatures than those described below, as long as each operation accepts a byte array and returns a byte array." - fields: - encrypt: - type: function - description: "Encrypts a byte payload. Returns the encrypted payload." - parameters: - - name: content - type: array - returns: - type: result, error> - decrypt: - type: function - description: "Decrypts a byte payload. Returns the decrypted payload." - parameters: - - name: payload - type: array - returns: - type: result, error> - - Persistence: - type: object - description: "Interface for a pluggable SDS persistence backend. - Implementations MUST provide all functions required to save and retrieve SDS state per channel. Implementations MUST also provide the persistence method of interest, e.g., SQLite, custom encrypted storage, etc. - Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." - - ReliableChannel: - type: object - description: "A handle representing an open reliable channel. - Returned by `createReliableChannel` and used to send messages and receive events. - Internal state (SDS, segmentation, encryption) is managed by the implementation." - fields: - messageEvents: - type: MessageEvents - description: "Event emitter for reliable message events scoped to this channel." - - rateLimitConfig: - type: RateLimitConfig - default: DefaultRateLimitConfig - description: "Configuration for rate limit management." - - NodeConfig: # Extends NodeConfig defined in MESSAGING-API - fields: - sds_config: - type: SdsConfig - description: "SDS configuration. See SdsConfig defined in this spec." - rate_limit_config: - type: RateLimitConfig - description: "Rate limiting configuration, including RLN-specific attributes. See RateLimitConfig defined in this spec." - - SdsConfig: - type: object - description: Scalable Data Sync config items. - fields: - persistence: - type: Persistence - description: "Backend for persisting the SDS local history. Implementations MAY support custom backends." - acknowledgementTimeoutMs: - type: uint - default: 5000 - description: "Time in milliseconds to wait for acknowledgement before retransmitting." - maxRetransmissions: - type: uint - default: 5 - description: "Maximum number of retransmission attempts before considering delivery failed." - causalHistorySize: - type: uint - default: 2 - description: "Number of message IDs to consider in the causal history. With longer value, a stronger correctness is guaranteed but it requires higher bandwidth and memory." - - RateLimitConfig: - type: object - description: Rate limiting configuration, containing RLN-specific attributes. - fields: - enabled: - type: bool - default: false - description: "Whether rate limiting is enforced. SHOULD be true when RLN is active." - epochSizeMs: - type: uint - default: 600000 # 10 minutes - description: "The epoch size used by the RLN relay, in milliseconds." - - MessageReceivedEvent: - type: object - description: "Event emitted when a complete message has been received and reassembled." - fields: - message: - type: array - description: "The reassembled message payload." - - MessageSentEvent: - type: object - description: "Event emitted when all chunks of a message have been acknowledged by the network." - fields: - requestId: - type: ReliableSendId - description: "The identifier of the `send` operation whose chunks have all been acknowledged." - - MessageSendErrorEvent: - type: object - description: "Event emitted when a message send operation fails after exhausting retransmission attempts." - fields: - requestId: - type: ReliableSendId - description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." - error: - type: string - description: "Error message describing what went wrong" - - MessageEvents: - type: event_emitter - description: "Event source for reliable message events on a channel" - events: - "reliable:message:received": - type: MessageReceivedEvent - "reliable:message:sent": - type: MessageSentEvent - "reliable:message:send-error": - type: MessageSendErrorEvent -``` - -### Channel lifecycle - -```yaml -functions: - - createReliableChannel: - description: "Opens a reliable channel over the given content topic. Sets up the required SDS state, - segmentation, and encryption, and subscribes to `contentTopic` via the underlying - [MESSAGING-API](/standards/application/messaging-api.md)." - parameters: - - name: node - type: WakuNode - description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md). - Used to send chunks and to subscribe/unsubscribe to the content topics." - - name: channelId - type: string - description: "Unique identifier for this channel. Represents the reliable (SDS), segmented, and optionally-encrypted session." - - name: contentTopic - type: string - description: "The topic this channel listens and sends on. This has routing and filtering connotations." - - name: senderId - type: string - description: "An identifier for this sender. SHOULD be unique and persisted between sessions." - - name: encryption - type: optional - default: none - description: "Optional pluggable encryption implementation. If none, messages are sent unencrypted." - returns: - type: result - - closeChannel: - description: "Closes a reliable channel, releases all associated resources and internal state, - and unsubscribes from its content topic via the underlying [MESSAGING-API](/standards/application/messaging-api.md)." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - returns: - type: result -``` - -### Channel usage - -```yaml -functions: - send: - description: "Send a message through a reliable channel. The message is always segmented, - SDS-tracked, rate-limited, and encrypted (if configured)." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - - name: message - type: array - description: "The raw message payload to send." - returns: - type: result - description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." -``` - -Incoming events are emitted on `channel.messageEvents` as defined by `MessageEvents`. - ## Security/Privacy Considerations - This API does not provide confidentiality by default. An `Encryption` implementation MUST be supplied when confidentiality is required. From 27324bb90b9f968964a22037527c7af3108c5000 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Tue, 28 Apr 2026 00:14:48 +0200 Subject: [PATCH 115/174] Update standards/application/reliable-channel-api.md Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 85e169c..2b199d2 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -53,7 +53,7 @@ The [MESSAGING-API](/standards/application/messaging-api.md) provides peer-to-pe but does not provide high end-to-end delivery guarantees from sender to recipient. This API addresses that gap by introducing: -- **[SEGMENTATION-API](/standards/application/segmentation-api.md)** to handle large messages exceeding network size limits. +- **[SEGMENTATION-API](/standards/application/segmentation.md)** to handle large messages exceeding network size limits. - **[SDS](https://lip.logos.co/ift-ts/raw/sds.html)** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. - **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload. From 7033ffd9c0894932d42531681c2a92bfcb00855c Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Tue, 28 Apr 2026 00:19:30 +0200 Subject: [PATCH 116/174] Update standards/application/reliable-channel-api.md Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 2b199d2..3de05f2 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -197,10 +197,6 @@ types: type: MessageEvents description: "Event emitter for reliable message events scoped to this channel." - rateLimitConfig: - type: RateLimitConfig - default: DefaultRateLimitConfig - description: "Configuration for rate limit management." MessageEvents: type: event_emitter From 9fde880ea404b79294e99bc3a4d18f12480e9447 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Tue, 28 Apr 2026 00:24:25 +0200 Subject: [PATCH 117/174] Update standards/application/reliable-channel-api.md Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3de05f2..906a7f8 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -97,7 +97,7 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ## The Reliable Channel API -This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following (including `SdsConfig` and `RateLimitConfig`). +This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following. ### Channel lifecycle From 20fc26d0bd2dab59e6c266683708ff3782fe17cc Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Tue, 28 Apr 2026 00:25:09 +0200 Subject: [PATCH 118/174] Update standards/application/reliable-channel-api.md Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 906a7f8..ebe3700 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -108,9 +108,8 @@ in [MESSAGING-API](/standards/application/messaging-api.md). functions: createReliableChannel: - description: "Opens a reliable channel over the given content topic. Sets up the required SDS state, - segmentation, and encryption, and subscribes to `contentTopic` via the underlying - [MESSAGING-API](/standards/application/messaging-api.md)." + description: "Creates a reliable channel over the given content topic. Sets up the required SDS state, + segmentation, and encryption, and subscribes to `contentTopic`." parameters: - name: node type: WakuNode From b0ebaf01edd1d29f164815bfde9dd627e0191a93 Mon Sep 17 00:00:00 2001 From: Ivan FB <128452529+Ivansete-status@users.noreply.github.com> Date: Tue, 28 Apr 2026 00:25:38 +0200 Subject: [PATCH 119/174] Update standards/application/reliable-channel-api.md Co-authored-by: Igor Sirotin --- standards/application/reliable-channel-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index ebe3700..ab824a5 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -167,8 +167,7 @@ Incoming events are emitted on `channel.messageEvents` as defined by `MessageEve This spec extends `NodeConfig`, needed to create a node, which is defined in [MESSAGING-API](/standards/application/messaging-api.md), -with `sds_config` and `rate_limit_config` fields, whose types are defined -in [Type definitions](#type-definitions). +with `sds_config` and `rate_limit_config` fields. ```yaml NodeConfig: # Extends NodeConfig defined in MESSAGING-API From bd6abfbb292044da04d1b774f62db36fc4c7db8a Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 00:32:50 +0200 Subject: [PATCH 120/174] improve event operations --- standards/application/reliable-channel-api.md | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index ab824a5..f29ba59 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -159,9 +159,52 @@ functions: returns: type: result description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." -``` -Incoming events are emitted on `channel.messageEvents` as defined by `MessageEvents`. + onMessageReceived: + description: "Subscribes a callback to be invoked when a complete message has been received and reassembled." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + - name: callback + type: function + description: "Invoked on each received message." + parameters: + - name: event + type: MessageReceivedEvent + returns: + type: result + + onMessageSent: + description: "Subscribes a callback to be invoked when all chunks of a sent message have been acknowledged." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + - name: callback + type: function + description: "Invoked when all chunks of a send operation are acknowledged." + parameters: + - name: event + type: MessageSentEvent + returns: + type: result + + onMessageSendError: + description: "Subscribes a callback to be invoked when a send operation fails after exhausting retransmission attempts." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + - name: callback + type: function + description: "Invoked when a send operation fails." + parameters: + - name: event + type: MessageSendErrorEvent + returns: + type: result +``` ### Node configuration @@ -190,10 +233,6 @@ types: description: "A handle representing an open reliable channel. Returned by `createReliableChannel` and used to send messages and receive events. Internal state (SDS, segmentation, encryption) is managed by the implementation." - fields: - messageEvents: - type: MessageEvents - description: "Event emitter for reliable message events scoped to this channel." MessageEvents: From 3c1125bddb751de5d5b92565fb0acaeff2273796 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 00:39:51 +0200 Subject: [PATCH 121/174] mv Procedures section --- standards/application/reliable-channel-api.md | 112 +++++++++--------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f29ba59..32d94c1 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -17,6 +17,13 @@ editor: Logos Messaging Team * [API design](#api-design) * [Architectural position](#architectural-position) * [IDL](#idl) + * [Procedures](#procedures) + * [State management](#state-management) + * [Outgoing message processing](#outgoing-message-processing) + * [Incoming message processing](#incoming-message-processing) + * [Retransmission](#retransmission) + * [Rate limiting](#rate-limiting) + * [Encryption](#encryption) * [The Reliable Channel API](#the-reliable-channel-api) * [Channel lifecycle](#channel-lifecycle) * [Channel usage](#channel-usage) @@ -27,13 +34,6 @@ editor: Logos Messaging Team * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) * [Rate Limit Manager](#rate-limit-manager) * [Encryption Hook](#encryption-hook) - * [Procedures](#procedures) - * [State management](#state-management) - * [Outgoing message processing](#outgoing-message-processing) - * [Incoming message processing](#incoming-message-processing) - * [Retransmission](#retransmission) - * [Rate limiting](#rate-limiting) - * [Encryption](#encryption) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -95,6 +95,55 @@ The Reliable Channel API sits between the application layer and the Messaging AP A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). +## Procedures + +### State management + +Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html), keyed by `channelId`. This state MAY be persisted within the SDS implementation layer and includes: +- A committed message log recording sent messages and their acknowledgement status. +- An outgoing buffer of unacknowledged message chunks pending confirmation. +- An incoming buffer for partially received segmented messages awaiting full reassembly. + +The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. + +### Outgoing message processing + +When `send` is called, the implementation MUST process `message` in the following order: + +1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. +3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each chunk before transmission. +4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. +5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). + +### Incoming message processing + +When a chunk is received from the network, the implementation MUST process it in the following order: + +1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the chunk. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. +3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. + +### Retransmission + +A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, +according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, +up to `maxRetransmissions` times. +If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. + +### Rate limiting + +When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions +to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. +Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. + +### Encryption + +The `encryption` parameter in `createReliableChannel` is intentionally optional. +The Reliable Channel API is agnostic to encryption mechanisms. + +When an `Encryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). + ## The Reliable Channel API This API considers the types defined by [MESSAGING-API](/standards/application/messaging-api.md) plus the following. @@ -380,55 +429,6 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en - The `Encryption` interface MUST be implemented by the caller. - The Reliable Channel API MUST NOT impose any specific encryption scheme. -## Procedures - -### State management - -Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html), keyed by `channelId`. This state MAY be persisted within the SDS implementation layer and includes: -- A committed message log recording sent messages and their acknowledgement status. -- An outgoing buffer of unacknowledged message chunks pending confirmation. -- An incoming buffer for partially received segmented messages awaiting full reassembly. - -The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. - -### Outgoing message processing - -When `send` is called, the implementation MUST process `message` in the following order: - -1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. -3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each chunk before transmission. -4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. -5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). - -### Incoming message processing - -When a chunk is received from the network, the implementation MUST process it in the following order: - -1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the chunk. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. -3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. - -### Retransmission - -A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, -according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, -up to `maxRetransmissions` times. -If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. - -### Rate limiting - -When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions -to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. -Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. - -### Encryption - -The `encryption` parameter in `createReliableChannel` is intentionally optional. -The Reliable Channel API is agnostic to encryption mechanisms. - -When an `Encryption` implementation is provided, it MUST be applied as described in [Outgoing message processing](#outgoing-message-processing) and [Incoming message processing](#incoming-message-processing). - ## Security/Privacy Considerations - This API does not provide confidentiality by default. An `Encryption` implementation MUST be supplied when confidentiality is required. From 198ad99bed87c2c2dbb02675291ecbc13ce0ca7e Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 00:43:22 +0200 Subject: [PATCH 122/174] rm state management --- standards/application/reliable-channel-api.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 32d94c1..34a1529 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -18,7 +18,6 @@ editor: Logos Messaging Team * [Architectural position](#architectural-position) * [IDL](#idl) * [Procedures](#procedures) - * [State management](#state-management) * [Outgoing message processing](#outgoing-message-processing) * [Incoming message processing](#incoming-message-processing) * [Retransmission](#retransmission) @@ -97,15 +96,6 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ## Procedures -### State management - -Each `ReliableChannel` MUST maintain internal state for [SDS](https://lip.logos.co/ift-ts/raw/sds.html), keyed by `channelId`. This state MAY be persisted within the SDS implementation layer and includes: -- A committed message log recording sent messages and their acknowledgement status. -- An outgoing buffer of unacknowledged message chunks pending confirmation. -- An incoming buffer for partially received segmented messages awaiting full reassembly. - -The state MUST be persisted using the `persistence` backend specified in `SdsConfig`. - ### Outgoing message processing When `send` is called, the implementation MUST process `message` in the following order: From 408af18b8d0ef8e05998bf7e41e3bac59c31038a Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 00:52:12 +0200 Subject: [PATCH 123/174] add MessageDeliveredEvent --- standards/application/reliable-channel-api.md | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 34a1529..35ea2d0 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -215,20 +215,38 @@ functions: type: result onMessageSent: - description: "Subscribes a callback to be invoked when all chunks of a sent message have been acknowledged." + description: "Subscribes a callback to be invoked when all chunks of a message have been transmitted to the network. + This confirms network-level dispatch but does not guarantee the recipient has processed the message. + For end-to-end confirmation, see `onMessageDelivered`." parameters: - name: channel type: ReliableChannel description: "The channel handle returned by `createReliableChannel`." - name: callback type: function - description: "Invoked when all chunks of a send operation are acknowledged." + description: "Invoked when all chunks of a send operation are acknowledged by the network." parameters: - name: event type: MessageSentEvent returns: type: result + onMessageDelivered: + description: "Subscribes a callback to be invoked when the recipient has confirmed receipt of a message via SDS acknowledgements. + This event is emitted asynchronously, after `MessageSentEvent`, once the SDS layer receives end-to-end acknowledgements from the recipient." + parameters: + - name: channel + type: ReliableChannel + description: "The channel handle returned by `createReliableChannel`." + - name: callback + type: function + description: "Invoked when the recipient confirms end-to-end delivery." + parameters: + - name: event + type: MessageDeliveredEvent + returns: + type: result + onMessageSendError: description: "Subscribes a callback to be invoked when a send operation fails after exhausting retransmission attempts." parameters: @@ -282,6 +300,8 @@ types: type: MessageReceivedEvent "reliable:message:sent": type: MessageSentEvent + "reliable:message:delivered": + type: MessageDeliveredEvent "reliable:message:send-error": type: MessageSendErrorEvent @@ -295,11 +315,22 @@ types: MessageSentEvent: type: object - description: "Event emitted when all chunks of a message have been acknowledged by the network." + description: "Event emitted when all chunks of a message have been transmitted to the network. + This confirms network-level dispatch only; it does not guarantee the recipient has processed the message. + For end-to-end confirmation, listen for `MessageDeliveredEvent`." fields: requestId: type: ReliableSendId - description: "The identifier of the `send` operation whose chunks have all been acknowledged." + description: "The identifier of the `send` operation whose chunks have all been dispatched to the network." + + MessageDeliveredEvent: + type: object + description: "Event emitted when the recipient has confirmed end-to-end receipt of a message via SDS acknowledgements. + This event is fired asynchronously after `MessageSentEvent`, once the SDS layer receives explicit acknowledgements from the recipient." + fields: + requestId: + type: ReliableSendId + description: "The identifier of the `send` operation confirmed as delivered by the recipient." MessageSendErrorEvent: type: object From 330e58ce4bf61592267e172df362ffefc5e14848 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 00:59:05 +0200 Subject: [PATCH 124/174] rm retransmission section --- standards/application/reliable-channel-api.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 35ea2d0..bf48b57 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -20,7 +20,6 @@ editor: Logos Messaging Team * [Procedures](#procedures) * [Outgoing message processing](#outgoing-message-processing) * [Incoming message processing](#incoming-message-processing) - * [Retransmission](#retransmission) * [Rate limiting](#rate-limiting) * [Encryption](#encryption) * [The Reliable Channel API](#the-reliable-channel-api) @@ -114,13 +113,6 @@ When a chunk is received from the network, the implementation MUST process it in 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. 3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. -### Retransmission - -A certain Reliable Channel MUST retransmit unacknowledged chunks after `acknowledgementTimeoutMs`, -according to the [SDS](https://lip.logos.co/ift-ts/raw/sds.html) channel state, -up to `maxRetransmissions` times. -If a chunk is not acknowledged after all retransmission attempts, a `reliable:message:send-error` event MUST be emitted. - ### Rate limiting When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions From 6590306abb9d86ea2001dddac23319d21ef026b0 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 01:10:29 +0200 Subject: [PATCH 125/174] detecting missing deps incoming mesage processing --- standards/application/reliable-channel-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index bf48b57..0d16966 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -111,6 +111,8 @@ When a chunk is received from the network, the implementation MUST process it in 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the chunk. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. + - **2.1. Detect missing dependencies**: If SDS detects a gap in the causal history (i.e., a referenced predecessor chunk has not yet been received), the implementation MUST attempt to retrieve the missing chunk. + - **2.2. Fetch from store**: The implementation MUST provide a mechanism to extract a retrieval hint from the received chunk (e.g., a store cursor or message hash embedded in the SDS causal history). The missing chunk MUST then be fetched from a store node via the [MESSAGING-API](/standards/application/messaging-api.md) store query, and re-injected into the incoming processing pipeline from step 1. 3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. ### Rate limiting From 0a57672eade10df38c646193f3b5dc75abaee757 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 01:17:05 +0200 Subject: [PATCH 126/174] leave room for sds headers in segments --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 0d16966..377410d 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -99,7 +99,7 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M When `send` is called, the implementation MUST process `message` in the following order: -1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). +1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). The maximum chunk size MUST be reduced by the size of the SDS header added in step 2, so that each chunk together with its SDS header stays within the network message size limit. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each chunk before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. From f8ab3562310c35d16561f09754b14878c6187683 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 01:18:42 +0200 Subject: [PATCH 127/174] Use segment term instead of chunk --- standards/application/reliable-channel-api.md | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 377410d..4491a7f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -99,27 +99,27 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M When `send` is called, the implementation MUST process `message` in the following order: -1. **Segment**: Split the payload into chunks as defined in [SEGMENTATION-API](./segmentation-api.md). The maximum chunk size MUST be reduced by the size of the SDS header added in step 2, so that each chunk together with its SDS header stays within the network message size limit. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each chunk with the SDS layer to track acknowledgements and enable retransmission. -3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each chunk before transmission. +1. **Segment**: Split the payload into segments as defined in [SEGMENTATION-API](./segmentation-api.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each segment with the SDS layer to track acknowledgements and enable retransmission. +3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. -5. **Dispatch**: Send each chunk via the underlying [MESSAGING-API](/standards/application/messaging-api.md). +5. **Dispatch**: Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). ### Incoming message processing -When a chunk is received from the network, the implementation MUST process it in the following order: +When a segment is received from the network, the implementation MUST process it in the following order: -1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the chunk. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the chunk to the SDS layer, which emits acknowledgements and detects gaps. - - **2.1. Detect missing dependencies**: If SDS detects a gap in the causal history (i.e., a referenced predecessor chunk has not yet been received), the implementation MUST attempt to retrieve the missing chunk. - - **2.2. Fetch from store**: The implementation MUST provide a mechanism to extract a retrieval hint from the received chunk (e.g., a store cursor or message hash embedded in the SDS causal history). The missing chunk MUST then be fetched from a store node via the [MESSAGING-API](/standards/application/messaging-api.md) store query, and re-injected into the incoming processing pipeline from step 1. -3. **Reassemble**: Once all chunks for a message have been received, reassemble and emit a `reliable:message:received` event. +1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. + - **2.1. Detect missing dependencies**: If SDS detects a gap in the causal history (i.e., a referenced predecessor segment has not yet been received), the implementation MUST attempt to retrieve the missing segment. + - **2.2. Fetch from store**: The implementation MUST provide a mechanism to extract a retrieval hint from the received segment (e.g., a store cursor or message hash embedded in the SDS causal history). The missing segment MUST then be fetched from a store node via the [MESSAGING-API](/standards/application/messaging-api.md) store query, and re-injected into the incoming processing pipeline from step 1. +3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. ### Rate limiting -When `RateLimitConfig.enabled` is `true`, the implementation MUST space chunk transmissions +When `RateLimitConfig.enabled` is `true`, the implementation MUST space segment transmissions to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. -Chunks MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. +Segments MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. ### Encryption @@ -147,7 +147,7 @@ functions: - name: node type: WakuNode description: "The underlying messaging node, as defined in [MESSAGING-API](/standards/application/messaging-api.md). - Used to send chunks and to subscribe/unsubscribe to the content topics." + Used to send segments and to subscribe/unsubscribe to the content topics." - name: channelId type: string description: "Unique identifier for this channel. Represents the reliable (SDS), segmented, and optionally-encrypted session." @@ -209,7 +209,7 @@ functions: type: result onMessageSent: - description: "Subscribes a callback to be invoked when all chunks of a message have been transmitted to the network. + description: "Subscribes a callback to be invoked when all segments of a message have been transmitted to the network. This confirms network-level dispatch but does not guarantee the recipient has processed the message. For end-to-end confirmation, see `onMessageDelivered`." parameters: @@ -218,7 +218,7 @@ functions: description: "The channel handle returned by `createReliableChannel`." - name: callback type: function - description: "Invoked when all chunks of a send operation are acknowledged by the network." + description: "Invoked when all segments of a send operation are acknowledged by the network." parameters: - name: event type: MessageSentEvent @@ -309,13 +309,13 @@ types: MessageSentEvent: type: object - description: "Event emitted when all chunks of a message have been transmitted to the network. + description: "Event emitted when all segments of a message have been transmitted to the network. This confirms network-level dispatch only; it does not guarantee the recipient has processed the message. For end-to-end confirmation, listen for `MessageDeliveredEvent`." fields: requestId: type: ReliableSendId - description: "The identifier of the `send` operation whose chunks have all been dispatched to the network." + description: "The identifier of the `send` operation whose segments have all been dispatched to the network." MessageDeliveredEvent: type: object @@ -340,12 +340,12 @@ types: ReliableSendId: type: string description: "Unique identifier for a single `send` operation on a reliable channel. - It groups all chunks produced by segmenting one message, so callers can correlate + It groups all segments produced by segmenting one message, so callers can correlate acknowledgement and error events back to the original send call. - Internally, each chunk is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, - producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per chunk. + Internally, each segment is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, + producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per segment. A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, - one per chunk sent." + one per segment sent." SdsConfig: type: object @@ -420,18 +420,18 @@ See [SEGMENTATION-API](./segmentation-api.md). [SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. -- Each sent chunk is registered in an outgoing buffer. -- The recipient sends acknowledgements back to the sender upon receiving chunks. -- The sender removes acknowledged chunks from the outgoing buffer. -- Unacknowledged chunks are retransmitted after `acknowledgementTimeoutMs`. +- Each sent segment is registered in an outgoing buffer. +- The recipient sends acknowledgements back to the sender upon receiving segments. +- The sender removes acknowledged segments from the outgoing buffer. +- Unacknowledged segments are retransmitted after `acknowledgementTimeoutMs`. - SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. ### Rate Limit Manager The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. -- It tracks how many messages have been sent in the current epoch (only the first chunk of each message counts toward the rate limit; subsequent chunks are exempt). -- When the limit is approached, chunk dispatch MUST be delayed to the next epoch. +- It tracks how many messages have been sent in the current epoch (only the first segment of each message counts toward the rate limit; subsequent segments are exempt). +- When the limit is approached, segment dispatch MUST be delayed to the next epoch. - The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. ### Encryption Hook @@ -439,15 +439,15 @@ The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messag The Encryption Hook provides a pluggable interface for upper layers to inject encryption. - The hook is optional; when not provided, messages are sent unencrypted. -- Encryption is applied per chunk, after segmentation and SDS registration. -- Decryption is applied per chunk, before SDS delivery. +- Encryption is applied per segment, after segmentation and SDS registration. +- Decryption is applied per segment, before SDS delivery. - The `Encryption` interface MUST be implemented by the caller. - The Reliable Channel API MUST NOT impose any specific encryption scheme. ## Security/Privacy Considerations - This API does not provide confidentiality by default. An `Encryption` implementation MUST be supplied when confidentiality is required. -- Chunk metadata (message ID, chunk index, total chunks) is visible to network observers unless encrypted by the hook. +- Segment metadata (message ID, segment index, total segments) is visible to network observers unless encrypted by the hook. - SDS acknowledgement messages are sent over the same content topic and are subject to the same confidentiality concerns. - Rate limiting compliance is required to avoid exclusion from the network by RLN-enforcing relays. From 4695574d63e150ccd04b62a505bf21edc6fe7015 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 01:21:32 +0200 Subject: [PATCH 128/174] fix spelling --- .wordlist.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 6df90fa..42bdd2e 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -106,6 +106,7 @@ LIGHTPUSH maxRetransmissions md MessageChunk +MessageDeliveredEvent messageEnvelope MessageEnvelope MessageErrorEvent @@ -128,6 +129,10 @@ nodeInfoId num Oleksandr onEvent +onMessageDelivered +onMessageReceived +onMessageSendError +onMessageSent openChannel OpenAPI PartiallyConnected From 44baedff422fc8ce231cb444cb30b35fe4c3f11f Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 15:27:19 +0200 Subject: [PATCH 129/174] rm chunk terms from .wordlist.txt --- .wordlist.txt | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 42bdd2e..2813625 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -18,9 +18,6 @@ cd centric channelConfig channelId -chunkId -chunkIndex -chunkSizeBytes ciphertext closeChannel config @@ -96,7 +93,6 @@ Jazzz JSON KiB Kozlov -lastChunkIndex lifecycle liblogosdelivery libp @@ -105,7 +101,6 @@ Lightpush LIGHTPUSH maxRetransmissions md -MessageChunk MessageDeliveredEvent messageEnvelope MessageEnvelope @@ -143,7 +138,6 @@ pluggable Prathi pre Prem -previousChunkId ProtocolsConfig pubsub rateLimitConfig From 682e3525e22598c1a59a61916274da1c4ffbddea Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 15:30:12 +0200 Subject: [PATCH 130/174] avoid using segmentation-api term and use segmentation instead --- standards/application/reliable-channel-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 4491a7f..3b0de91 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -51,7 +51,7 @@ The [MESSAGING-API](/standards/application/messaging-api.md) provides peer-to-pe but does not provide high end-to-end delivery guarantees from sender to recipient. This API addresses that gap by introducing: -- **[SEGMENTATION-API](/standards/application/segmentation.md)** to handle large messages exceeding network size limits. +- **[SEGMENTATION](/standards/application/segmentation.md)** to handle large messages exceeding network size limits. - **[SDS](https://lip.logos.co/ift-ts/raw/sds.html)** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. - **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload. @@ -99,7 +99,7 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M When `send` is called, the implementation MUST process `message` in the following order: -1. **Segment**: Split the payload into segments as defined in [SEGMENTATION-API](./segmentation-api.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. +1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each segment with the SDS layer to track acknowledgements and enable retransmission. 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. @@ -414,7 +414,7 @@ types: ### Segmentation -See [SEGMENTATION-API](./segmentation-api.md). +See [SEGMENTATION](./segmentation.md). ### Scalable Data Sync (SDS) From a23f89b4df7e1ba5a709352da3a247a4fd609f4c Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 16:19:49 +0200 Subject: [PATCH 131/174] add SegmentationConfig --- standards/application/reliable-channel-api.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3b0de91..78fb981 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -347,6 +347,20 @@ types: A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, one per segment sent." + SegmentationConfig: + type: object + fields: + enableReedSolomon: + type: bool + default: false + description: When enabled, the message sender adds parity (redundant) segments to allow recovery in case of data segment loss. See [SEGMENTATION](./segmentation.md). + + segmentSizeBytes: + type: uint + default: 102400 # 100 KiB + description: "Maximum segment size in bytes. + Messages larger than this value are split before SDS processing." + SdsConfig: type: object description: Scalable Data Sync config items. From 76ccd4154914869d476fa7252184cce57a8f3190 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 22:33:31 +0200 Subject: [PATCH 132/174] make more concise substep in sds in msgs --- standards/application/reliable-channel-api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 78fb981..c4d8274 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -111,8 +111,8 @@ When a segment is received from the network, the implementation MUST process it 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. - - **2.1. Detect missing dependencies**: If SDS detects a gap in the causal history (i.e., a referenced predecessor segment has not yet been received), the implementation MUST attempt to retrieve the missing segment. - - **2.2. Fetch from store**: The implementation MUST provide a mechanism to extract a retrieval hint from the received segment (e.g., a store cursor or message hash embedded in the SDS causal history). The missing segment MUST then be fetched from a store node via the [MESSAGING-API](/standards/application/messaging-api.md) store query, and re-injected into the incoming processing pipeline from step 1. + - **Detect missing dependencies and fetch from store**: If SDS detects a gap in the causal history (i.e., a referenced predecessor segment has not yet been received), and considers the message is irretrievably lost, + the implementation MUST attempt to retrieve the missing segment throughout store protocol (store API is never exposed and hence, store queries are handled internally). 3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. ### Rate limiting @@ -285,7 +285,6 @@ types: Returned by `createReliableChannel` and used to send messages and receive events. Internal state (SDS, segmentation, encryption) is managed by the implementation." - MessageEvents: type: event_emitter description: "Event source for reliable message events on a channel" From 33f89ccbd8d94f0a085f242b9105b2f6f85cb263 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 23:00:41 +0200 Subject: [PATCH 133/174] enrich MessageSendErrorEvent description --- standards/application/reliable-channel-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index c4d8274..3b870ff 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -334,7 +334,10 @@ types: description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." error: type: string - description: "Error message describing what went wrong" + description: "Describes the failure that prevented end-to-end delivery. Possible values: + - `irrecoverable_loss`: SDS marked the message as irretrievably lost — the recipient's acknowledgement was not received after `maxRetransmissions` retransmission attempts. + - `dispatch_failed`: the network layer rejected or could not dispatch the segment (e.g. lightpush returned `is_success: false`, or no relay/lightpush peers were reachable); propagated from the underlying [MESSAGING-API](/standards/application/messaging-api.md) `MessageSendErrorEvent` error field. + - `channel_closed`: the channel was closed before the recipient confirmed delivery, leaving one or more segments unacknowledged." ReliableSendId: type: string From dba72eb697679d4e44abe97d2a6abbf2aeaf5de4 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 23:27:22 +0200 Subject: [PATCH 134/174] improve RequestId definition --- standards/application/reliable-channel-api.md | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3b870ff..f951005 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -190,8 +190,8 @@ functions: type: array description: "The raw message payload to send." returns: - type: result - description: "Returns a `ReliableSendId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." + type: result + description: "Returns a `RequestId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." onMessageReceived: description: "Subscribes a callback to be invoked when a complete message has been received and reassembled." @@ -313,7 +313,7 @@ types: For end-to-end confirmation, listen for `MessageDeliveredEvent`." fields: requestId: - type: ReliableSendId + type: RequestId description: "The identifier of the `send` operation whose segments have all been dispatched to the network." MessageDeliveredEvent: @@ -322,7 +322,7 @@ types: This event is fired asynchronously after `MessageSentEvent`, once the SDS layer receives explicit acknowledgements from the recipient." fields: requestId: - type: ReliableSendId + type: RequestId description: "The identifier of the `send` operation confirmed as delivered by the recipient." MessageSendErrorEvent: @@ -330,7 +330,7 @@ types: description: "Event emitted when a message send operation fails after exhausting retransmission attempts." fields: requestId: - type: ReliableSendId + type: RequestId description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." error: type: string @@ -339,15 +339,21 @@ types: - `dispatch_failed`: the network layer rejected or could not dispatch the segment (e.g. lightpush returned `is_success: false`, or no relay/lightpush peers were reachable); propagated from the underlying [MESSAGING-API](/standards/application/messaging-api.md) `MessageSendErrorEvent` error field. - `channel_closed`: the channel was closed before the recipient confirmed delivery, leaving one or more segments unacknowledged." - ReliableSendId: + RequestId: type: string description: "Unique identifier for a single `send` operation on a reliable channel. It groups all segments produced by segmenting one message, so callers can correlate acknowledgement and error events back to the original send call. Internally, each segment is dispatched as an independent [MESSAGING-API](/standards/application/messaging-api.md) call, producing one `RequestId` (as defined in [MESSAGING-API](/standards/application/messaging-api.md)) per segment. - A single `ReliableSendId` therefore maps to one or more underlying `RequestId` values, - one per segment sent." + A single `RequestId` therefore maps to one or more underlying [MESSAGING-API](/standards/application/messaging-api.md)'s `RequestId` values, + one per segment sent. + For example, the `RequestId` `Req_a` yields these MESSAGING-API requests: + `Req_a:1`, `Req_a:2`, ..., `Req_a:N`, where `Req_a:k` represents the k-th + MESSAGING-API segment `RequestId`. + That is, `Req_a` is the `RequestId` from the RELIABLE-CHANNEL-API spec PoV, + whereas `Req_a:k` is the `RequestId` from the MESSAGING-API spec PoV. + " SegmentationConfig: type: object From b917da1b2db1d6a32bd85a662998a48fa5920ad5 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 28 Apr 2026 23:48:27 +0200 Subject: [PATCH 135/174] rm callback registration functions --- standards/application/reliable-channel-api.md | 67 ++----------------- 1 file changed, 4 insertions(+), 63 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f951005..ec872c8 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -192,69 +192,6 @@ functions: returns: type: result description: "Returns a `RequestId` that callers can use to correlate subsequent `MessageSentEvent` or `MessageSendErrorEvent` events." - - onMessageReceived: - description: "Subscribes a callback to be invoked when a complete message has been received and reassembled." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - - name: callback - type: function - description: "Invoked on each received message." - parameters: - - name: event - type: MessageReceivedEvent - returns: - type: result - - onMessageSent: - description: "Subscribes a callback to be invoked when all segments of a message have been transmitted to the network. - This confirms network-level dispatch but does not guarantee the recipient has processed the message. - For end-to-end confirmation, see `onMessageDelivered`." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - - name: callback - type: function - description: "Invoked when all segments of a send operation are acknowledged by the network." - parameters: - - name: event - type: MessageSentEvent - returns: - type: result - - onMessageDelivered: - description: "Subscribes a callback to be invoked when the recipient has confirmed receipt of a message via SDS acknowledgements. - This event is emitted asynchronously, after `MessageSentEvent`, once the SDS layer receives end-to-end acknowledgements from the recipient." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - - name: callback - type: function - description: "Invoked when the recipient confirms end-to-end delivery." - parameters: - - name: event - type: MessageDeliveredEvent - returns: - type: result - - onMessageSendError: - description: "Subscribes a callback to be invoked when a send operation fails after exhausting retransmission attempts." - parameters: - - name: channel - type: ReliableChannel - description: "The channel handle returned by `createReliableChannel`." - - name: callback - type: function - description: "Invoked when a send operation fails." - parameters: - - name: event - type: MessageSendErrorEvent - returns: - type: result ``` ### Node configuration @@ -284,6 +221,10 @@ types: description: "A handle representing an open reliable channel. Returned by `createReliableChannel` and used to send messages and receive events. Internal state (SDS, segmentation, encryption) is managed by the implementation." + fields: + messageEvents: + type: MessageEvents + description: "The node's messaging event emitter" MessageEvents: type: event_emitter From 6ff41e97f978eefabbf6e8d9c99700a80ef0df93 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 13:45:27 +0200 Subject: [PATCH 136/174] better explanation of outgoing message processing --- standards/application/reliable-channel-api.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index ec872c8..aece651 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -100,10 +100,16 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M When `send` is called, the implementation MUST process `message` in the following order: 1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Register each segment with the SDS layer to track acknowledgements and enable retransmission. +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)** for each segment that is sent: + - Generate a random MessageId. 40-char long. e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`. + - Persist the MessageId plus the payload for the current segment being sent. + - Get the retrieval hint from previously persisted messages (see point 5.). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. -5. **Dispatch**: Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). +5. **Dispatch** + - Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). + - Update the persisted MessageId entry, in point 2., with the sent MessageHash, only when + the event `MessageSendPropagatedEvent` is triggered (that event is defined in [MESSAGING-API](/standards/application/messaging-api.md)). ### Incoming message processing From 0c512d935c077741ca29f3a34021c86e5be2c081 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 13:53:04 +0200 Subject: [PATCH 137/174] rm rate_limit_config --- standards/application/reliable-channel-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index aece651..74d0b07 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -212,9 +212,6 @@ NodeConfig: # Extends NodeConfig defined in MESSAGING-API sds_config: type: SdsConfig description: "SDS configuration. See SdsConfig defined in this spec." - rate_limit_config: - type: RateLimitConfig - description: "Rate limiting configuration, including RLN-specific attributes. See RateLimitConfig defined in this spec." ``` ### Type definitions From 493b909f0282165c34a27b648997eeec2bc4b645 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 13:55:56 +0200 Subject: [PATCH 138/174] enhance event definitions --- standards/application/reliable-channel-api.md | 32 +++++++++++-------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 74d0b07..67d1a4e 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -224,14 +224,6 @@ types: description: "A handle representing an open reliable channel. Returned by `createReliableChannel` and used to send messages and receive events. Internal state (SDS, segmentation, encryption) is managed by the implementation." - fields: - messageEvents: - type: MessageEvents - description: "The node's messaging event emitter" - - MessageEvents: - type: event_emitter - description: "Event source for reliable message events on a channel" events: "reliable:message:received": type: MessageReceivedEvent @@ -241,6 +233,8 @@ types: type: MessageDeliveredEvent "reliable:message:send-error": type: MessageSendErrorEvent + "reliable:message:delivery-error": + type: MessageDeliveryErrorEvent MessageReceivedEvent: type: object @@ -271,17 +265,27 @@ types: MessageSendErrorEvent: type: object - description: "Event emitted when a message send operation fails after exhausting retransmission attempts." + description: "Event emitted when one or more segments of a message could not be dispatched to the network. + This indicates a network-level failure; the message was never fully transmitted." fields: requestId: type: RequestId - description: "The identifier of the `send` operation that failed after exhausting retransmission attempts." + description: "The identifier of the `send` operation that failed to dispatch." error: type: string - description: "Describes the failure that prevented end-to-end delivery. Possible values: - - `irrecoverable_loss`: SDS marked the message as irretrievably lost — the recipient's acknowledgement was not received after `maxRetransmissions` retransmission attempts. - - `dispatch_failed`: the network layer rejected or could not dispatch the segment (e.g. lightpush returned `is_success: false`, or no relay/lightpush peers were reachable); propagated from the underlying [MESSAGING-API](/standards/application/messaging-api.md) `MessageSendErrorEvent` error field. - - `channel_closed`: the channel was closed before the recipient confirmed delivery, leaving one or more segments unacknowledged." + description: "Human-readable description of the dispatch failure." + + MessageDeliveryErrorEvent: + type: object + description: "Event emitted when end-to-end delivery could not be confirmed. + Fired after `maxRetransmissions` attempts have been exhausted without receiving an SDS acknowledgement from the recipient." + fields: + requestId: + type: RequestId + description: "The identifier of the `send` operation that was not acknowledged by the recipient." + error: + type: string + description: "Human-readable description of the delivery failure." RequestId: type: string From 1500a0536d2685e0217025f7e71a3566d40ebe65 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 14:14:16 +0200 Subject: [PATCH 139/174] add node initialization procedure --- standards/application/messaging-api.md | 9 ++++++++ standards/application/reliable-channel-api.md | 21 ++++++++++++++++++- 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/standards/application/messaging-api.md b/standards/application/messaging-api.md index 6531821..5601271 100644 --- a/standards/application/messaging-api.md +++ b/standards/application/messaging-api.md @@ -344,6 +344,15 @@ 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. +**Fetching missed messages on startup**: + +The node MUST persist the timestamp of the last message it successfully received or sent before going offline. + +After the node is started and subscriptions are set up, the node SHOULD query the +[STORE](https://lip.logos.co/messaging/standards/core/13/store.html) protocol to retrieve messages +missed while offline, scoped to the subscribed content topics and using the persisted timestamp as the +lower bound of the query. + ### Messaging #### Messaging type definitions diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 67d1a4e..0864dce 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -18,6 +18,7 @@ editor: Logos Messaging Team * [Architectural position](#architectural-position) * [IDL](#idl) * [Procedures](#procedures) + * [Node initialization](#node-initialization) * [Outgoing message processing](#outgoing-message-processing) * [Incoming message processing](#incoming-message-processing) * [Rate limiting](#rate-limiting) @@ -95,6 +96,20 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ## Procedures +### Node initialization + +When a node is created via `createNode` (defined in [MESSAGING-API](/standards/application/messaging-api.md)), +the implementation MUST perform the following setup before the node is used: + +1. **Configure SDS persistence**: Supply the `Persistence` backend from `SdsConfig` to the SDS module so that + causal history and outgoing buffers survive restarts. +2. **Configure SDS hint provider**: Register a hint provider with the SDS module. + The hint provider converts an SDS `MessageId` into its corresponding `MessageHash`. +3. **Configure Segmentation persistence**: Supply the `Persistence` backend from `SegmentationConfig` to the + [Segmentation](./segmentation.md) module so that partially reassembled messages survive restarts. +4. **Fetch missed messages**: Retrieve messages missed while offline as described in + [MESSAGING-API — Fetching missed messages on startup](/standards/application/messaging-api.md#init-node-extended-definitions). + ### Outgoing message processing When `send` is called, the implementation MUST process `message` in the following order: @@ -310,12 +325,16 @@ types: type: bool default: false description: When enabled, the message sender adds parity (redundant) segments to allow recovery in case of data segment loss. See [SEGMENTATION](./segmentation.md). - segmentSizeBytes: type: uint default: 102400 # 100 KiB description: "Maximum segment size in bytes. Messages larger than this value are split before SDS processing." + persistence: + type: Persistence + description: "Backend for persisting partial reassembly state across restarts. + Implementations MUST use this backend to store received segments until all segments of a message have arrived and can be reassembled. + Refer to [SEGMENTATION](./segmentation.md) for the full definition of what state must be persisted." SdsConfig: type: object From 0ede28def994d846b1f44288c582ebe6742f6db2 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 15:15:31 +0200 Subject: [PATCH 140/174] mv components before procedures --- standards/application/reliable-channel-api.md | 79 +++++++++---------- 1 file changed, 39 insertions(+), 40 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 0864dce..bccf280 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -17,6 +17,11 @@ editor: Logos Messaging Team * [API design](#api-design) * [Architectural position](#architectural-position) * [IDL](#idl) + * [Components](#components) + * [Segmentation](#segmentation) + * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) + * [Rate Limit Manager](#rate-limit-manager) + * [Encryption Hook](#encryption-hook) * [Procedures](#procedures) * [Node initialization](#node-initialization) * [Outgoing message processing](#outgoing-message-processing) @@ -28,11 +33,6 @@ editor: Logos Messaging Team * [Channel usage](#channel-usage) * [Node configuration](#node-configuration) * [Type definitions](#type-definitions) - * [Components](#components) - * [Segmentation](#segmentation) - * [Scalable Data Sync (SDS)](#scalable-data-sync-sds) - * [Rate Limit Manager](#rate-limit-manager) - * [Encryption Hook](#encryption-hook) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -45,7 +45,6 @@ an application-level interface that sits between the application layer and the [ It bundles segmentation, end-to-end reliability via [Scalable Data Sync (SDS)](https://lip.logos.co/ift-ts/raw/sds.html), rate limit management, and a pluggable encryption hook into a single interface for sending and receiving messages reliably. - ## Motivation The [MESSAGING-API](/standards/application/messaging-api.md) provides peer-to-peer reliability via [P2P-RELIABILITY](/standards/application/p2p-reliability.md), @@ -94,6 +93,40 @@ The Reliable Channel API sits between the application layer and the Messaging AP A custom Interface Definition Language (IDL) in YAML is used, consistent with [MESSAGING-API](/standards/application/messaging-api.md). +## Components + +### Segmentation + +See [SEGMENTATION](./segmentation.md). + +### Scalable Data Sync (SDS) + +[SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. + +- Each sent segment is registered in an outgoing buffer. +- The recipient sends acknowledgements back to the sender upon receiving segments. +- The sender removes acknowledged segments from the outgoing buffer. +- Unacknowledged segments are retransmitted after `acknowledgementTimeoutMs`. +- SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. + +### Rate Limit Manager + +The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. + +- It tracks how many messages have been sent in the current epoch (only the first segment of each message counts toward the rate limit; subsequent segments are exempt). +- When the limit is approached, segment dispatch MUST be delayed to the next epoch. +- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. + +### Encryption Hook + +The Encryption Hook provides a pluggable interface for upper layers to inject encryption. + +- The hook is optional; when not provided, messages are sent unencrypted. +- Encryption is applied per segment, after segmentation and SDS registration. +- Decryption is applied per segment, before SDS delivery. +- The `Encryption` interface MUST be implemented by the caller. +- The Reliable Channel API MUST NOT impose any specific encryption scheme. + ## Procedures ### Node initialization @@ -399,40 +432,6 @@ types: Refer to the [SDS spec](https://lip.logos.co/ift-ts/raw/sds.html) for the full definition of what state must be persisted." ``` -## Components - -### Segmentation - -See [SEGMENTATION](./segmentation.md). - -### Scalable Data Sync (SDS) - -[SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. - -- Each sent segment is registered in an outgoing buffer. -- The recipient sends acknowledgements back to the sender upon receiving segments. -- The sender removes acknowledged segments from the outgoing buffer. -- Unacknowledged segments are retransmitted after `acknowledgementTimeoutMs`. -- SDS state MUST be persisted using the `persistence` backend configured in `SdsConfig`. - -### Rate Limit Manager - -The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. - -- It tracks how many messages have been sent in the current epoch (only the first segment of each message counts toward the rate limit; subsequent segments are exempt). -- When the limit is approached, segment dispatch MUST be delayed to the next epoch. -- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. - -### Encryption Hook - -The Encryption Hook provides a pluggable interface for upper layers to inject encryption. - -- The hook is optional; when not provided, messages are sent unencrypted. -- Encryption is applied per segment, after segmentation and SDS registration. -- Decryption is applied per segment, before SDS delivery. -- The `Encryption` interface MUST be implemented by the caller. -- The Reliable Channel API MUST NOT impose any specific encryption scheme. - ## Security/Privacy Considerations - This API does not provide confidentiality by default. An `Encryption` implementation MUST be supplied when confidentiality is required. From 8734fd5d8fe4b072ca163e39d712525a0708d8b4 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 17:49:10 +0200 Subject: [PATCH 141/174] revert changes in messaging-api --- standards/application/messaging-api.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/standards/application/messaging-api.md b/standards/application/messaging-api.md index 5601271..6531821 100644 --- a/standards/application/messaging-api.md +++ b/standards/application/messaging-api.md @@ -344,15 +344,6 @@ 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. -**Fetching missed messages on startup**: - -The node MUST persist the timestamp of the last message it successfully received or sent before going offline. - -After the node is started and subscriptions are set up, the node SHOULD query the -[STORE](https://lip.logos.co/messaging/standards/core/13/store.html) protocol to retrieve messages -missed while offline, scoped to the subscribed content topics and using the persisted timestamp as the -lower bound of the query. - ### Messaging #### Messaging type definitions From 81ee865e55ea525354c1ccb22ce04b3c3de690da Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 18:12:36 +0200 Subject: [PATCH 142/174] better describe sds requirements --- standards/application/reliable-channel-api.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index bccf280..25683c2 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -103,6 +103,11 @@ See [SEGMENTATION](./segmentation.md). [SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. +- Each new segment to be sent, requires the following data: + - `MessageId`: a 40-character random hex string (e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`), generated by the Reliable Channel API. + - `ChannelId`: the `channelId` passed to `createReliableChannel`. + - Retrieval hint: the transport `MessageHash` of the segment, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md). The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. + - Each sent segment is registered in an outgoing buffer. - The recipient sends acknowledgements back to the sender upon receiving segments. - The sender removes acknowledged segments from the outgoing buffer. @@ -148,10 +153,7 @@ the implementation MUST perform the following setup before the node is used: When `send` is called, the implementation MUST process `message` in the following order: 1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)** for each segment that is sent: - - Generate a random MessageId. 40-char long. e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`. - - Persist the MessageId plus the payload for the current segment being sent. - - Get the retrieval hint from previously persisted messages (see point 5.). +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: register each segment in the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. 5. **Dispatch** From 0b3a4aeb5ce1bb3894855f8494b8ceaa859efcd5 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 18:25:42 +0200 Subject: [PATCH 143/174] extend SDS component definition --- standards/application/reliable-channel-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 25683c2..84f4530 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -106,7 +106,8 @@ See [SEGMENTATION](./segmentation.md). - Each new segment to be sent, requires the following data: - `MessageId`: a 40-character random hex string (e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - - Retrieval hint: the transport `MessageHash` of the segment, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md). The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. + - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. + The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. - Each sent segment is registered in an outgoing buffer. - The recipient sends acknowledgements back to the sender upon receiving segments. From 8483bb10d9ee60e05c12fc68ef5670e7a24f2640 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 18:27:05 +0200 Subject: [PATCH 144/174] simplify dispatch step --- standards/application/reliable-channel-api.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 84f4530..3a487c9 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -157,10 +157,7 @@ When `send` is called, the implementation MUST process `message` in the followin 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: register each segment in the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. -5. **Dispatch** - - Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). - - Update the persisted MessageId entry, in point 2., with the sent MessageHash, only when - the event `MessageSendPropagatedEvent` is triggered (that event is defined in [MESSAGING-API](/standards/application/messaging-api.md)). +5. **Dispatch**: Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). ### Incoming message processing From f9c04366c5522caebd358032c891502d0f441290 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Wed, 29 Apr 2026 22:40:58 +0200 Subject: [PATCH 145/174] add missing terms to wordlist --- .wordlist.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 2813625..1c95563 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -5,6 +5,7 @@ ALLOC api AsyncAPI autosharding +ba AutoShardingConfig Backend backend @@ -15,6 +16,8 @@ Bradner camelCase causalHistorySize cd +da +df centric channelConfig channelId @@ -45,6 +48,7 @@ DHT discv DISCV DoS +enableReedSolomon encodings encryptionKey enrtree @@ -61,6 +65,7 @@ EventReliableMessageSent EventSource eventType fb +fd fBF getAvailableConfigs getAvailableNodeInfoIds @@ -102,6 +107,9 @@ LIGHTPUSH maxRetransmissions md MessageDeliveredEvent +MessageDeliveryErrorEvent +MessageHash +MessageId messageEnvelope MessageEnvelope MessageErrorEvent @@ -134,6 +142,7 @@ PartiallyConnected PascalCase Pax plaintext +PoV pluggable Prathi pre @@ -141,6 +150,7 @@ Prem ProtocolsConfig pubsub rateLimitConfig +Req RateLimitConfig Raya Raya's @@ -186,6 +196,7 @@ SyncStatusDetail SDK SegmentationConfig segmentationConfig +segmentSizeBytes sharding SHARDING sqlite @@ -193,6 +204,7 @@ subnets SubscriptionError TBD tcp +th TCP TheWakuNetworkMessageValidation TheWakuNetworkPreset From 01cf30d5e8f39e52a464df563ece8296433b5202 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 30 Apr 2026 00:31:17 +0200 Subject: [PATCH 146/174] MessageSentEvent is the one that confirms a msg was rx by a store node --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3a487c9..b430e13 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -106,7 +106,7 @@ See [SEGMENTATION](./segmentation.md). - Each new segment to be sent, requires the following data: - `MessageId`: a 40-character random hex string (e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. + - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSentEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. - Each sent segment is registered in an outgoing buffer. From 888ba213743c300199e2b395362944f5f7676501 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 30 Apr 2026 13:58:33 +0200 Subject: [PATCH 147/174] Revert "MessageSentEvent is the one that confirms a msg was rx by a store node" This reverts commit 01cf30d5e8f39e52a464df563ece8296433b5202. --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index b430e13..3a487c9 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -106,7 +106,7 @@ See [SEGMENTATION](./segmentation.md). - Each new segment to be sent, requires the following data: - `MessageId`: a 40-character random hex string (e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSentEvent` reception. + - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. - Each sent segment is registered in an outgoing buffer. From 5e68873188f2886d485b3bd86e8d97f34b7934bd Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 10:48:43 +0200 Subject: [PATCH 148/174] specify editor and contributors --- standards/application/reliable-channel-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 3a487c9..aa1c90f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -4,7 +4,10 @@ name: Reliable Channel API definition category: Standards Track status: raw tags: [reliability, application, api, sds, segmentation] -editor: Logos Messaging Team +editor: Ivan Folgueira Bande +contributors: +- Igor Sirotin +- Jazz Turner-Baggs --- ## Table of contents From f953a45e313db2ccb810f7994646af5cac8b1045 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 10:56:48 +0200 Subject: [PATCH 149/174] Set only editors field --- standards/application/reliable-channel-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index aa1c90f..e6b35d2 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -4,10 +4,10 @@ name: Reliable Channel API definition category: Standards Track status: raw tags: [reliability, application, api, sds, segmentation] -editor: Ivan Folgueira Bande -contributors: +editors: - Igor Sirotin - Jazz Turner-Baggs +- Ivan Folgueira Bande --- ## Table of contents From f39c7f0d0bef5a05bae276439dea471790df3ab1 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 10:59:24 +0200 Subject: [PATCH 150/174] apply Jazz suggestion for encryption hook description --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index e6b35d2..687fac0 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -57,7 +57,7 @@ This API addresses that gap by introducing: - **[SEGMENTATION](/standards/application/segmentation.md)** to handle large messages exceeding network size limits. - **[SDS](https://lip.logos.co/ift-ts/raw/sds.html)** to provide causal-history-based end-to-end acknowledgement and retransmission. - **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages. -- **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. The main motivation for encryption is to protect the payload. +- **Encryption Hook** to allow upper layers to provide a pluggable encryption mechanism. This enables applications to provide Confidentiality and Integrity if desired. The separation between Reliable Channels and encryption ensures the API remains agnostic to identity and key management concerns, which are handled by higher layers. From a6fd069eebbf641d3b9073dad9b83c023d39b3cb Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:11:01 +0200 Subject: [PATCH 151/174] add little segmentation description --- standards/application/reliable-channel-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 687fac0..b9ab040 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -100,6 +100,8 @@ A custom Interface Definition Language (IDL) in YAML is used, consistent with [M ### Segmentation +A protocol that splits message payloads into smaller units during transmission and reassembles them upon reception. The component is instantiated by supplying the appropriate value to SegmentationConfig. + See [SEGMENTATION](./segmentation.md). ### Scalable Data Sync (SDS) From 491b2e36d13f29bf2fb93b6cbb2534ebe847ed19 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:24:38 +0200 Subject: [PATCH 152/174] use keccak-256 instead of arbitrary random num when processing SDS msg --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index b9ab040..a154808 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -109,7 +109,7 @@ See [SEGMENTATION](./segmentation.md). [SDS](https://lip.logos.co/ift-ts/raw/sds.html) provides end-to-end delivery guarantees using causal history tracking. - Each new segment to be sent, requires the following data: - - `MessageId`: a 40-character random hex string (e.g. `a23f89b4df7e1ba5a709352da3a247a4fd609f4c`), generated by the Reliable Channel API. + - `MessageId`: a keccak-256([message](https://lip.logos.co/ift-ts/raw/sds.html#message)'s content) hex string (e.g. `4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. From f4e5ed59a0e5ee0dc3b289e228c1c93c4bf371f1 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:33:16 +0200 Subject: [PATCH 153/174] Clean incorrect comment in Rate Limit Manager --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index a154808..22d3145 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -124,7 +124,7 @@ See [SEGMENTATION](./segmentation.md). The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) rate constraints. -- It tracks how many messages have been sent in the current epoch (only the first segment of each message counts toward the rate limit; subsequent segments are exempt). +- It tracks how many messages have been sent in the current epoch. - When the limit is approached, segment dispatch MUST be delayed to the next epoch. - The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. From 94fab074d641608625f87136f5a27d4cc89bb064 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:41:34 +0200 Subject: [PATCH 154/174] properly specify epoch period in seconds --- standards/application/reliable-channel-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 22d3145..fa73d74 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -126,7 +126,7 @@ The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messag - It tracks how many messages have been sent in the current epoch. - When the limit is approached, segment dispatch MUST be delayed to the next epoch. -- The epoch size MUST match the `epochSizeMs` configured in `RateLimitConfig`. +- The epoch size MUST match the `[epochPeriodSec](https://lip.logos.co/messaging/standards/core/17/rln-relay.html#epoch-length)` configured in `RateLimitConfig`. ### Encryption Hook @@ -177,7 +177,7 @@ When a segment is received from the network, the implementation MUST process it ### Rate limiting When `RateLimitConfig.enabled` is `true`, the implementation MUST space segment transmissions -to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `epochSizeMs`. +to comply with the [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints defined in `[epochPeriodSec](https://lip.logos.co/messaging/standards/core/17/rln-relay.html#epoch-length)`. Segments MUST NOT be sent at a rate that would violate the RLN message rate limit for the active epoch. ### Encryption @@ -402,9 +402,9 @@ types: type: bool default: false description: "Whether rate limiting is enforced. SHOULD be true when RLN is active." - epochSizeMs: + epochPeriodSec: type: uint - default: 600000 # 10 minutes + default: 600 # 10 minutes description: "The epoch size used by the RLN relay, in milliseconds." Encryption: From 776a7db28ad77e84a8361b13593506830aa61c24 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:49:36 +0200 Subject: [PATCH 155/174] make some comments more natural and concise --- standards/application/reliable-channel-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index fa73d74..90bce37 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -114,7 +114,7 @@ See [SEGMENTATION](./segmentation.md). - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. -- Each sent segment is registered in an outgoing buffer. +- Each sent segment is added to an outgoing buffer. - The recipient sends acknowledgements back to the sender upon receiving segments. - The sender removes acknowledged segments from the outgoing buffer. - Unacknowledged segments are retransmitted after `acknowledgementTimeoutMs`. @@ -133,8 +133,8 @@ The Rate Limit Manager ensures compliance with [RLN](https://lip.logos.co/messag The Encryption Hook provides a pluggable interface for upper layers to inject encryption. - The hook is optional; when not provided, messages are sent unencrypted. -- Encryption is applied per segment, after segmentation and SDS registration. -- Decryption is applied per segment, before SDS delivery. +- Encryption is applied per segment, after segmentation and SDS. +- Decryption is applied per segment before being processed by SDS. - The `Encryption` interface MUST be implemented by the caller. - The Reliable Channel API MUST NOT impose any specific encryption scheme. From fd7e52dc5b4188b27044b37a62d61b84c20a0e07 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 11:54:05 +0200 Subject: [PATCH 156/174] make it more clear when encryption should be implemented --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 90bce37..cb5eddc 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -135,7 +135,7 @@ The Encryption Hook provides a pluggable interface for upper layers to inject en - The hook is optional; when not provided, messages are sent unencrypted. - Encryption is applied per segment, after segmentation and SDS. - Decryption is applied per segment before being processed by SDS. -- The `Encryption` interface MUST be implemented by the caller. +- The `Encryption` interface MUST be implemented by the caller when the hook is provided. - The Reliable Channel API MUST NOT impose any specific encryption scheme. ## Procedures From 9804f4ea7744596a73223afdf3bd1628343f87b9 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 12:10:19 +0200 Subject: [PATCH 157/174] clarify what is SDS header --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index cb5eddc..72314ef 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -158,7 +158,7 @@ the implementation MUST perform the following setup before the node is used: When `send` is called, the implementation MUST process `message` in the following order: -1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header added in step 2, so that each segment together with its SDS header stays within the network message size limit. +1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header (all that is not content, considering [SDS message](https://lip.logos.co/ift-ts/raw/sds.html#message)) added in step 2, so that each segment together with its SDS header stays within the network message size limit. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: register each segment in the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. From f3ba3f6d3fa6ac73d53093efcb4c1cbebaaedc53 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 15:38:54 +0200 Subject: [PATCH 158/174] avoid using the term segment in SDS explanation --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 72314ef..360c33e 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -159,7 +159,7 @@ the implementation MUST perform the following setup before the node is used: When `send` is called, the implementation MUST process `message` in the following order: 1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header (all that is not content, considering [SDS message](https://lip.logos.co/ift-ts/raw/sds.html#message)) added in step 2, so that each segment together with its SDS header stays within the network message size limit. -2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: register each segment in the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). +2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: add each sds message to the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. 5. **Dispatch**: Send each segment via the underlying [MESSAGING-API](/standards/application/messaging-api.md). From c7eb2bef623d183d0419f32c947a5b0cdb3ea555 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 15:43:05 +0200 Subject: [PATCH 159/174] better rewording in incoming msg procedure --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 360c33e..f138b28 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -170,7 +170,7 @@ When a segment is received from the network, the implementation MUST process it 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. - - **Detect missing dependencies and fetch from store**: If SDS detects a gap in the causal history (i.e., a referenced predecessor segment has not yet been received), and considers the message is irretrievably lost, + - **Detect missing dependencies and fetch from store**: If SDS detects a message in the causal history which has not yet been received , and considers the message is irretrievably lost, the implementation MUST attempt to retrieve the missing segment throughout store protocol (store API is never exposed and hence, store queries are handled internally). 3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. From 895a00c5ebe77efce01c0ede49cb5c4646111a07 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 15:49:53 +0200 Subject: [PATCH 160/174] rm irretrievable term --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index f138b28..0d5fc04 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -170,7 +170,7 @@ When a segment is received from the network, the implementation MUST process it 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. - - **Detect missing dependencies and fetch from store**: If SDS detects a message in the causal history which has not yet been received , and considers the message is irretrievably lost, + - **Detect missing dependencies and fetch from store**: If SDS detects a message in the causal history which has not yet been received, and considers the message is lost, the implementation MUST attempt to retrieve the missing segment throughout store protocol (store API is never exposed and hence, store queries are handled internally). 3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. From 5909a2f48df03dbe2bd821f165835c149bf390d9 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 16:11:45 +0200 Subject: [PATCH 161/174] better explanation on how missing deps are handled --- standards/application/reliable-channel-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 0d5fc04..654cb7b 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -170,8 +170,7 @@ When a segment is received from the network, the implementation MUST process it 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. - - **Detect missing dependencies and fetch from store**: If SDS detects a message in the causal history which has not yet been received, and considers the message is lost, - the implementation MUST attempt to retrieve the missing segment throughout store protocol (store API is never exposed and hence, store queries are handled internally). + - **Detect missing dependencies**: If SDS detects a message in the causal history which has not yet been received, it MUST make a best-effort attempt to retrieve the missing message, and MAY use the store protocol internally for this purpose. If the message cannot be retrieved, SDS MAY mark it as lost. 3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. ### Rate limiting From a26a7992a61b247f70a18566ed0b152f97cc5836 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 16:16:47 +0200 Subject: [PATCH 162/174] better description in send function --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 654cb7b..2a6ce55 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -239,7 +239,7 @@ functions: functions: send: description: "Send a message through a reliable channel. The message is always segmented, - SDS-tracked, rate-limited, and encrypted (if configured)." + SDS-tracked, rate-limited (optional), and encrypted (optional)." parameters: - name: channel type: ReliableChannel From 76d8f2fe74772403fc1f9f9b624f02ee07728b2e Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 16:18:27 +0200 Subject: [PATCH 163/174] minor tweak --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 2a6ce55..d28fc4f 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -111,7 +111,7 @@ See [SEGMENTATION](./segmentation.md). - Each new segment to be sent, requires the following data: - `MessageId`: a keccak-256([message](https://lip.logos.co/ift-ts/raw/sds.html#message)'s content) hex string (e.g. `4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - - Retrieval hint: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. + - `Retrieval hint`: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. - Each sent segment is added to an outgoing buffer. From 74e81e0125e7b9122c2b4ab9464d2fbbe2fe4430 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 16:26:18 +0200 Subject: [PATCH 164/174] simplify segment step --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index d28fc4f..61555b7 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -158,7 +158,7 @@ the implementation MUST perform the following setup before the node is used: When `send` is called, the implementation MUST process `message` in the following order: -1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). The maximum segment size MUST be reduced by the size of the SDS header (all that is not content, considering [SDS message](https://lip.logos.co/ift-ts/raw/sds.html#message)) added in step 2, so that each segment together with its SDS header stays within the network message size limit. +1. **Segment**: Split the payload into segments as defined in [SEGMENTATION](./segmentation.md). 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: add each sds message to the SDS outgoing buffer (see [SDS](#scalable-data-sync-sds) for parameter bindings). 3. **Encrypt**: If an `Encryption` implementation is provided, encrypt each segment before transmission. 4. **Rate Limit**: If `RateLimitConfig.enabled` is `true`, delay dispatch as needed to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) epoch constraints. From 4d539e0eb34ee096b9819f9fa7068ed2606293f4 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 16:48:39 +0200 Subject: [PATCH 165/174] update MessageDeliveryErrorEvent description --- standards/application/reliable-channel-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index 61555b7..af9c9c2 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -330,6 +330,7 @@ types: MessageDeliveryErrorEvent: type: object description: "Event emitted when end-to-end delivery could not be confirmed. + The message reached the network and there's no need to explicit re-send. Fired after `maxRetransmissions` attempts have been exhausted without receiving an SDS acknowledgement from the recipient." fields: requestId: From 59ff35b5e79e35fc5fc40fad51156df30a118591 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 17:51:57 +0200 Subject: [PATCH 166/174] better mention message_hash --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index af9c9c2..e70ee87 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -111,7 +111,7 @@ See [SEGMENTATION](./segmentation.md). - Each new segment to be sent, requires the following data: - `MessageId`: a keccak-256([message](https://lip.logos.co/ift-ts/raw/sds.html#message)'s content) hex string (e.g. `4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45`), generated by the Reliable Channel API. - `ChannelId`: the `channelId` passed to `createReliableChannel`. - - `Retrieval hint`: the transport `MessageHash` of previous segments, exposed by the underlying [MESSAGING-API](/standards/application/messaging-api.md) upon ``MessageSendPropagatedEvent` reception. + - `Retrieval hint`: the transport `MessageHash` of previous segments, mentioned as `message_hash` in [MESSAGING-API](/standards/application/messaging-api.md), upon ``MessageSendPropagatedEvent` reception. The hint provider registered during [Node initialization](#node-initialization) performs this `MessageId → MessageHash` lookup. In turn, that mapping MUST be persisted by SDS using the `persistence` backend configured in `SdsConfig`. - Each sent segment is added to an outgoing buffer. From ac4883fa15c21816a0a962a3eeee9ea6a3f5dac8 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 17:57:36 +0200 Subject: [PATCH 167/174] better explain why hint provider is needed. --- standards/application/reliable-channel-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/application/reliable-channel-api.md b/standards/application/reliable-channel-api.md index e70ee87..3439a5a 100644 --- a/standards/application/reliable-channel-api.md +++ b/standards/application/reliable-channel-api.md @@ -170,7 +170,7 @@ When a segment is received from the network, the implementation MUST process it 1. **Decrypt**: If an `Encryption` implementation is provided, decrypt the segment. 2. **Apply [SDS](https://lip.logos.co/ift-ts/raw/sds.html)**: Deliver the segment to the SDS layer, which emits acknowledgements and detects gaps. - - **Detect missing dependencies**: If SDS detects a message in the causal history which has not yet been received, it MUST make a best-effort attempt to retrieve the missing message, and MAY use the store protocol internally for this purpose. If the message cannot be retrieved, SDS MAY mark it as lost. + - **Detect missing dependencies**: If SDS detects a gap in the causal history, it MUST make a best-effort attempt to retrieve the missing message. The `Retrieval hint` (see [Scalable Data Sync (SDS)](#scalable-data-sync-sds)) carried in each SDS message provides the transport `MessageHash` needed to query the store; without it, store retrieval is not possible. If the message cannot be retrieved, SDS MAY mark it as lost. 3. **Reassemble**: Once all segments for a message have been received, reassemble and emit a `reliable:message:received` event. ### Rate limiting From aef8f6687a1b5c4db8e54881e1d19344416336ae Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Fri, 1 May 2026 18:02:02 +0200 Subject: [PATCH 168/174] fix spell --- .wordlist.txt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 1c95563..b6ff5a1 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,5 +1,6 @@ ABIs acknowledgementTimeoutMs +aea addListener ALLOC api @@ -7,6 +8,8 @@ AsyncAPI autosharding ba AutoShardingConfig +Baggs +Bande Backend backend backends @@ -53,6 +56,8 @@ encodings encryptionKey enrtree enum +ec +epochPeriodSec epochSizeMs eth Eth @@ -65,7 +70,9 @@ EventReliableMessageSent EventSource eventType fb +fc fd +Folgueira fBF getAvailableConfigs getAvailableNodeInfoIds @@ -96,6 +103,7 @@ ipv iterable Jazzz JSON +keccak KiB Kozlov lifecycle @@ -183,6 +191,7 @@ rpc RPC Saro Scalable +Sirotin sds SDS SDS'ed From a19d99b79f28fc295209101c085442a37868a1e1 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Sun, 3 May 2026 12:58:53 -0700 Subject: [PATCH 169/174] Chat Content Frames (#82) * Core dump * update background and context * Add content definition * Focus on interoperability * Towards SemBr * Fixed domain_id * Update wordlist --- .wordlist.txt | 4 + standards/application/contentframe.md | 179 ++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 standards/application/contentframe.md diff --git a/.wordlist.txt b/.wordlist.txt index b6ff5a1..df6ea94 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -29,6 +29,7 @@ closeChannel config ConnectionStatus ConnectionStatusEvent +ContentFrame contentTopic contentTopics createNode @@ -131,6 +132,7 @@ MessageSentEvent MessageValidation MiB multiaddr +namespace NetworkConfig NetworkingConfig nim @@ -151,11 +153,13 @@ PascalCase Pax plaintext PoV +permissionless pluggable Prathi pre Prem ProtocolsConfig +protobuf pubsub rateLimitConfig Req diff --git a/standards/application/contentframe.md b/standards/application/contentframe.md new file mode 100644 index 0000000..c66230d --- /dev/null +++ b/standards/application/contentframe.md @@ -0,0 +1,179 @@ +--- +title: CONTENTFRAME +name: +category: Standards Track +tags: +editor: Jazzz +contributors: +--- + +## Abstract + +This specification defines ContentFrame, a self-describing message format for decentralized chat networks. +ContentFrame wraps content payloads with metadata identifying their type and governing specification repository. +Using a `(domain, tag)` tuple, applications can uniquely identify message types and locate authoritative documentation for parsing unfamiliar content. +This approach enables permissionless innovation while maintaining the context needed for interoperability, allowing applications to gracefully handle messages from sources they don't explicitly know about. + +## Motivation + +In an interoperable chat network, participants cannot be assumed to use the same software to send and receive messages. +Users may employ different versions of the same application or different applications entirely. +This heterogeneity creates a fundamental challenge: how can applications support extensible message types without prior knowledge of every possible format? + +Two naive approaches each have significant drawbacks: + +**Developer-defined types** would allow flexibility but create fragmentation. +When developers define their own message types, the context for parsing these messages remains tightly coupled to the software that created them. +Other applications receiving these messages lack the necessary context to interpret them correctly. +This leads to multiple definitions of basic types such as `Text` and `Image` that are not compatible across applications. + +**Fixed type systems** would ensure universal understanding but restrict innovation. +A predetermined set of message types eliminates ambiguity but adds friction for developers who want to extend functionality. +In a permissionless, decentralized protocol, requiring centralized approval for new message types contradicts core design principles. + +The core challenge is managing fragmentation in a decentralized protocol while preserving developer freedom to innovate. + +**Solution:** A self-describing message format that encodes both the payload and the metadata needed to parse it. +This approach directs application developers on how a message should be parsed while providing a clear path to learn about unfamiliar content types they encounter. +By decoupling the encoded data from the specific software that created it, applications can gracefully handle messages from diverse sources without sacrificing extensibility. + + +## Theory / Semantics + +### ContentFrame + +A ContentFrame provides a self-describing format for payload types by encoding both the type identifier and its administrative origin. +The core principle is that each payload should declare which entity is responsible for its definition and provide a unique type discriminator within that entity's namespace. + +A ContentFrame consists of two key components: + +- **Domain**: Points to a specification repository that defines and governs a collection of types +- **Tag**: A unique identifier within that domain that specifies which type the payload conforms to + +Together, the tuple `(domain, tag)` serves two purposes: + +1. **Identification**: Uniquely identifies the payload type without ambiguity +2. **Discovery**: Provides a path for developers to learn how to parse and support unfamiliar types + +**Benefits:** + +This approach provides several advantages for decentralized interoperability: + +- **No naming collisions**: Developers can independently create types without coordinating with others, as each domain manages its own namespace +- **Type reuse**: Well-defined, established types can be shared across applications, reducing fragmentation +- **Graceful extensibility**: Applications encountering unknown types can direct developers to the authoritative specification +- **Decentralized governance**: No central authority is required to approve new types; domains manage their own specifications + +By separating the "who defines this" (domain) from the "what is this" (tag), ContentFrame enables permissionless innovation while maintaining the context needed for interoperability. + + +### Concept Mapping + +The following diagram illustrates the relationship between ContentFrame components and their specifications: +```mermaid +flowchart TD + d[Domain ID] -->|references| D + D[Domain] -->|Defines| T[Tag] + T -->|References| Specification +``` + +### Domain + +A domain identifies the authority responsible for defining and governing a set of content types. +By including the domain, receiving applications can locate the authoritative specification for a type, regardless of which application originally sent it. + +**Requirements:** + +- A domain MUST be a valid URL as defined in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) +- A domain MUST host or reference definitions for all content types within its namespace +- A domain SHOULD be a specification repository or index that developers can reference + +**Specification Format:** + +Domains are responsible for describing their types in whatever format is most appropriate. +The only requirement is that the information needed to parse and understand each type is accessible from the domain URL. + + +**Domain ID Mapping:** + +To minimize payload size, domains are mapped to integer identifiers. +Each domain is assigned a unique `domain_id` which is used in the wire format instead of the full URL. + +- A `domain_id` MUST be a positive integer value +- A `domain_id` MUST correspond to exactly one unique domain +- The canonical mapping of `domain_id` to domains can be found in [Appendix A: Domains](#appendix-a-domains) + +### Tag + +A tag is a numeric identifier that uniquely specifies a content type within a domain's namespace. +After resolving the domain and tag, application developers have all the information needed to locate the definition and parse the payload. + +**Requirements:** + +- A tag MUST be a positive integer value +- A tag MUST uniquely identify a single type within its domain +- Two payloads with the same `(domain, tag)` tuple MUST conform to the same type specification +- A tag's meaning MUST NOT change after it has been assigned within a domain + +**Domain Responsibility:** + +Each domain is responsible for: +- Assigning and managing tag values within its namespace +- Documenting how each tag maps to a type specification +- Ensuring tag assignments remain stable and unambiguous + +Tags are scoped to their domain, meaning the same tag value can represent different types in different domains without conflict. + + + +## Wire Format Specification / Syntax +```protobuf +message ContentFrame { + uint32 domain_id = 1; + uint32 tag = 2; + bytes payload = 3; +} +``` + +**Field Descriptions:** + +- **domain_id**: Identifies the domain that governs this content type +- **tag**: Identifies the specific content type within the domain's namespace +- **payload**: The encoded content data + +All fields are required. + + +## Implementation Suggestions + +### Tags to Specifications + +Where possible, tag values should directly correspond to specification identifiers. +Using specification IDs as tags removes the need to maintain a separate mapping between tags and specifications. + +### Fragmentation + +This protocol allows multiple competing definitions of similar content types. +Having multiple definitions of `Text` or `Image` increases fragmentation between applications. +Where possible, reusing existing types will reduce burden on developers and increase interoperability. + +Domains should focus on providing types unique to their service or use case. + + +# Appendix A: Domains + +![TODO] Find appropriate home for this registry. + +Domain IDs are assigned sequentially on a first-come, first-served basis. +New domains are added via pull request. + +**Registry Rules:** + +- A domain MUST only appear once in the table +- A domain MAY be updated by the original submitter if the repository has been moved + +**Registry:** + +| domain_id | specification repository | +|-----------|--------------------------------------| +| 1 | https://github.com/waku-org/specs | \ No newline at end of file From 63aa0d31b9bc3d1564efca7150c9d70bdbaa637f Mon Sep 17 00:00:00 2001 From: Pablo Lopez Date: Wed, 6 May 2026 01:11:15 +0300 Subject: [PATCH 170/174] feat: add segmentation spec (#91) --- .wordlist.txt | 76 +++++---- standards/application/segmentation.md | 220 ++++++++++++++++++++++++++ 2 files changed, 268 insertions(+), 28 deletions(-) create mode 100644 standards/application/segmentation.md diff --git a/.wordlist.txt b/.wordlist.txt index df6ea94..3e63ea7 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,27 +1,26 @@ ABIs acknowledgementTimeoutMs -aea addListener +aea ALLOC api AsyncAPI autosharding -ba AutoShardingConfig +ba +backend +Backend +backends Baggs Bande -Backend -backend -backends BCP bool Bradner camelCase causalHistorySize cd -da -df centric +Changelog channelConfig channelId ciphertext @@ -36,7 +35,10 @@ createNode createReliableChannel creativecommons cryptographic +da danielkaiser +dataSegments +dataSegments decrypt Decrypt decrypted @@ -47,17 +49,20 @@ DefaultNetworkingConfig DefaultRateLimitConfig DefaultSdsConfig DefaultSegmentationConfig +Deployability dev +dev +df DHT discv DISCV DoS +ec enableReedSolomon encodings encryptionKey enrtree enum -ec epochPeriodSec epochSizeMs eth @@ -71,10 +76,10 @@ EventReliableMessageSent EventSource eventType fb +fBF fc fd Folgueira -fBF getAvailableConfigs getAvailableNodeInfoIds getAvailableNodeInfoItems @@ -93,37 +98,39 @@ iana IANA IDL IEncryption -IPersistence implementers implementor implementors Implementors Inclusivity Init +IPersistence ipv iterable Jazzz JSON keccak +Keccak KiB Kozlov -lifecycle liblogosdelivery libp libp2p +lifecycle Lightpush LIGHTPUSH maxRetransmissions +maxTotalSegments md MessageDeliveredEvent MessageDeliveryErrorEvent -MessageHash -MessageId messageEnvelope MessageEnvelope MessageErrorEvent messageEvents MessageEvents +MessageHash +MessageId MessagePropagatedEvent MessageReceivedEvent MessageSendErrorEvent @@ -136,6 +143,8 @@ namespace NetworkConfig NetworkingConfig nim +nim +Nim nodeConfig NodeConfig nodeInfoId @@ -146,37 +155,39 @@ onMessageDelivered onMessageReceived onMessageSendError onMessageSent -openChannel OpenAPI +openChannel +parityRate PartiallyConnected PascalCase Pax -plaintext -PoV permissionless +plaintext pluggable +PoV Prathi pre Prem -ProtocolsConfig +proto protobuf +ProtocolsConfig pubsub rateLimitConfig -Req RateLimitConfig Raya Raya's ReliableChannel ReliableChannelConfig ReliableEnvelope -ReliableSendId ReliableIrretrievableMessageEvent ReliableMessageAcknowledgedEvent ReliableMessageEvents ReliableMessageReceivedEvent ReliableMessageSendErrorEvent ReliableMessageSentEvent +ReliableSendId ReliableSyncStatusEvent +Req requestId RequestId responder @@ -189,36 +200,41 @@ rfc RFC rln RLN +RLN +RLN RlnConfig Royer rpc RPC Saro Scalable -Sirotin +sdk +SDK sds SDS SDS'ed sdsConfig SdsConfig -sdk -senderId -syncStatus -SyncStatus -SyncStatusDetail -SDK -SegmentationConfig segmentationConfig +SegmentationConfig +SegmentMessageProto +segmentSize segmentSizeBytes +senderId +sharding sharding SHARDING +Sirotin sqlite subnets SubscriptionError +syncStatus +SyncStatus +SyncStatusDetail TBD tcp -th TCP +th TheWakuNetworkMessageValidation TheWakuNetworkPreset TODO @@ -226,13 +242,17 @@ TWN udp UDP uint +uint unencrypted unvalidated UUID UX waku +waku +waku Waku WAKU +Waku's WakuNode www xB diff --git a/standards/application/segmentation.md b/standards/application/segmentation.md new file mode 100644 index 0000000..6b82cbf --- /dev/null +++ b/standards/application/segmentation.md @@ -0,0 +1,220 @@ +--- +title: Message Segmentation and Reconstruction +name: Message Segmentation and Reconstruction +tags: [segmentation] +version: 0.1 +status: raw +--- + +## Abstract + +This specification defines an application-layer protocol for **segmentation** and **reconstruction** of messages carried over a transport/delivery service with a message-size limitation, when the original payload exceeds said limitation. +Applications partition the payload into multiple transport messages and reconstruct the original on receipt, +even when segments arrive out of order or up to a **predefined percentage** of segments are lost. +The protocol optionally uses **Reed–Solomon** erasure coding for fault tolerance. +All messages are wrapped in a `SegmentMessageProto`, including those that fit in a single segment. + +## Motivation + +Many message transport and delivery protocols impose a maximum message size that restricts the size of application payloads. +For example, Waku Relay typically propagates messages up to **150 KB** as per [64/WAKU2-NETWORK - Message](https://rfc.vac.dev/waku/standards/core/64/network#message-size). +To support larger application payloads, a segmentation layer is required. +This specification enables larger messages by partitioning them into multiple envelopes and reconstructing them at the receiver. +Erasure-coded parity segments provide resilience against partial loss or reordering. + +## Terminology + +- **original payload**: the full application payload before segmentation. +- **data segment**: one of the partitioned chunks of the original message payload. +- **parity segment**: an erasure-coded segment derived from the set of data segments. +- **segment message**: a wire-message whose `payload` field carries a serialized `SegmentMessageProto`. +- **`segmentSize`**: configured maximum size in bytes of each data segment's `payload` chunk (before protobuf serialization). + +The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"NOT RECOMMENDED"**, **"MAY"**, and **"OPTIONAL"** in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +## Wire Format + +Each segmented message is encoded as a `SegmentMessageProto` protobuf message: + +```protobuf +syntax = "proto3"; + +message SegmentMessageProto { + // Keccak256(original payload), 32 bytes + bytes entire_message_hash = 1; + + // Data segment indexing + uint32 data_segment_index = 2; // zero-indexed sequence number for data segments + uint32 data_segment_count = 3; // number of data segments (>= 1) + + // Segment payload (data or parity shard) + bytes payload = 4; + + // Parity segment indexing + uint32 parity_segment_index = 5; // zero-based sequence number for parity segments + uint32 parity_segment_count = 6; // number of parity segments + + // Segment type + bool is_parity = 7; // true for parity segments, false (default) for data segments +} +``` + +**Field descriptions:** + +- `entire_message_hash`: A 32-byte Keccak256 hash of the original complete payload, used to identify which segments belong together and verify reconstruction integrity. +- `data_segment_index`: Zero-indexed sequence number identifying this data segment's position (0, 1, 2, ..., data_segment_count - 1). Set only on data segments. +- `data_segment_count`: Total number of data segments the original message was split into. Set on every segment (data and parity). +- `payload`: The actual chunk of data or parity information for this segment. +- `parity_segment_index`: Zero-based sequence number for parity segments. Set only on parity segments. +- `parity_segment_count`: Total number of parity segments generated. Set on every segment (data and parity) when Reed–Solomon parity is used; `0` (default) otherwise. +- `is_parity`: Explicit segment type marker. `false` (default) for data segments; `true` for parity segments. + +A message is either a **data segment** (when `is_parity == false`) or a **parity segment** (when `is_parity == true`). + +### Validation + +Receivers **MUST** enforce: + +- `entire_message_hash.length == 32` +- `data_segment_count >= 1` +- `data_segment_count + parity_segment_count < maxTotalSegments` +- **Data segments** (`is_parity == false`): + `data_segment_index < data_segment_count` +- **Parity segments** (`is_parity == true`): + `parity_segment_count > 0` AND `parity_segment_index < parity_segment_count` + +No other combinations are permitted. +A `SegmentMessageProto` with `data_segment_count == 1` and `data_segment_index == 0` is a valid single-segment data message: the `payload` field carries the entire original payload (see [Sending](#sending)). + +## Segmentation + +### Sending + +To transmit a payload, the sender: + +- **MUST** compute a 32-byte `entire_message_hash = Keccak256(original_payload)`. +- **MUST** split the payload into one or more **data segments**, + each of size up to `segmentSize` bytes. + A payload of size ≤ `segmentSize` produces a single data segment (`data_segment_count == 1`). +- **MUST** pad the last segment to `segmentSize` for Reed-Solomon erasure coding (only if Reed-Solomon coding is enabled) +- **MAY** use Reed–Solomon erasure coding at the predefined parity rate. +- **MUST** encode every segment as a `SegmentMessageProto` with: + - The `entire_message_hash` + - `data_segment_count` (total number of data segments, always set) + - When Reed–Solomon parity is used, `parity_segment_count` (total number of parity segments, set on every segment) + - For data segments: `is_parity = false`, `data_segment_index` + - For parity segments: `is_parity = true`, `parity_segment_index` + - The raw payload data +- Send each segment as an individual transport message according to the underlying transport service. + +This yields a deterministic wire format: every transmitted payload is a `SegmentMessageProto`. + +### Receiving + +Upon receiving a segmented message, the receiver: + +- **MUST** validate each segment according to [Wire Format → Validation](#validation). +- **MUST** cache received segments +- **MUST** attempt reconstruction once at least `data_segment_count` distinct segments (data and parity combined) have been received: + - If all data segments are present, concatenate their `payload` fields in `data_segment_index` order. + - Otherwise, recover the payload via Reed–Solomon decoding over the available data and parity segments. +- **MUST** verify `Keccak256(reconstructed_payload)` matches `entire_message_hash`. + On mismatch, + the message **MUST** be discarded and logged as invalid. +- Once verified, + the reconstructed payload **SHALL** be delivered to the application. + +--- + +## Implementation Suggestions + +### Reed–Solomon + +Implementations that apply parity **SHALL** use fixed-size shards of length `segmentSize`. +The reference implementation uses **nim-leopard** (Leopard-RS) with a maximum of **256 total shards**. + +### Storage / Persistence + +Segments may be persisted (e.g., SQLite) and indexed by `entire_message_hash` and by sender. Sender may be authenticated, this is out of scope of this spec. +Implementations **SHOULD** support: + +- Duplicate detection and idempotent saves +- Completion flags to prevent duplicate processing +- Timeout-based cleanup of incomplete reconstructions +- Per-sender quotas for stored bytes and concurrent reconstructions + +### Configuration + +- `segmentSize` — maximum size in bytes of each data segment's payload chunk (before protobuf serialization). + **REQUIRED** parameter, configurable by the client. +- `parityRate` — fraction of parity shards relative to data shards. + Configurable by the client. Defaults to **0.125** (12.5%). +- `maxTotalSegments` — maximum number of total shards (data + parity) per message. + Implementation-specific parameter, fixed. The reference implementation uses **256**. + +**Reconstruction capability:** +With the predefined parity rate, reconstruction is possible if **all data segments** are received or if **any combination of data + parity** totals at least `data_segment_count` (i.e., up to the predefined percentage of loss tolerated). + +**API simplicity:** +Libraries **SHOULD** require only `segmentSize` from the application for normal operation. + +--- + +## Security Considerations + +### Privacy + +`entire_message_hash` enables correlation of segments that belong to the same original message but does not reveal content. +To prevent this correlation, applications **SHOULD** encrypt each segment after segmentation (see [Encryption](#encryption)). +Traffic analysis may still identify segmented flows. + +### Encryption + +This specification does not provide confidentiality. +Applications **SHOULD** encrypt each segment after segmentation +(i.e., encrypt the serialized `SegmentMessageProto` prior to transmission), +so that `entire_message_hash` and other identifying fields are not visible to observers. + +### Integrity + +Implementations **MUST** verify the Keccak256 hash post-reconstruction and discard on mismatch. + +### Denial of Service + +To mitigate resource exhaustion: + +- Limit total concurrent reconstructions and aggregate buffered bytes + - When sender identity is available, apply the same two limits per sender +- Enforce timeouts and size caps +- Validate segment counts (≤ 256) +- Consider rate-limiting at the transport layer (for example, via [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/waku/standards/core/17/rln-relay) on Waku) + +--- + +## Deployment Considerations + +**Overhead:** + +- Bandwidth overhead ≈ the predefined parity rate from parity (if enabled) +- Additional per-segment overhead ≤ **100 bytes** (protobuf + metadata) + +**Network impact:**Ac + +- Larger messages increase transport traffic and storage; + operators **SHOULD** consider policy limits + +**Compatibility:** + +- Nodes that do **not** implement this specification cannot reconstruct any messages. + +--- + +## References + +1. [10/WAKU2 – Waku](https://rfc.vac.dev/waku/standards/core/10/waku2) +2. [11/WAKU2-RELAY – Relay](https://rfc.vac.dev/waku/standards/core/11/relay) +3. [14/WAKU2-MESSAGE – Message](https://rfc.vac.dev/waku/standards/core/14/message) +4. [64/WAKU2-NETWORK](https://rfc.vac.dev/waku/standards/core/64/network#message-size) +5. [nim-leopard](https://github.com/status-im/nim-leopard) – Nim bindings for Leopard-RS (Reed–Solomon) +6. [Leopard-RS](https://github.com/catid/leopard) – Fast Reed–Solomon erasure coding library +7. [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) – Key words for use in RFCs to Indicate Requirement Levels From 6fd1e54565fdd57601e7e8a2630477f099c2a331 Mon Sep 17 00:00:00 2001 From: Patryk Osmaczko Date: Mon, 9 Feb 2026 16:44:59 +0100 Subject: [PATCH 171/174] feat: add introduction encoding --- .wordlist.txt | 10 ++ .../application/introduction_encoding.md | 153 ++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 standards/application/introduction_encoding.md diff --git a/.wordlist.txt b/.wordlist.txt index 3e63ea7..6b6aecb 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -23,9 +23,12 @@ centric Changelog channelConfig channelId +chatintro ciphertext +CLI closeChannel config +confusable ConnectionStatus ConnectionStatusEvent ContentFrame @@ -104,6 +107,7 @@ implementors Implementors Inclusivity Init +IntroBundle IPersistence ipv iterable @@ -158,8 +162,10 @@ onMessageSent OpenAPI openChannel parityRate +Parsers PartiallyConnected PascalCase +Patryk Pax permissionless plaintext @@ -171,6 +177,7 @@ Prem proto protobuf ProtocolsConfig +pubkey pubsub rateLimitConfig RateLimitConfig @@ -245,6 +252,8 @@ uint uint unencrypted unvalidated +url +UTF UUID UX waku @@ -256,6 +265,7 @@ Waku's WakuNode www xB +XEdDSA yaml YAML yml diff --git a/standards/application/introduction_encoding.md b/standards/application/introduction_encoding.md new file mode 100644 index 0000000..2411655 --- /dev/null +++ b/standards/application/introduction_encoding.md @@ -0,0 +1,153 @@ +--- +title: Introduction Bundle Encoding +name: introduction-bundle-encoding +category: Standards Track +tags: core, encoding +editor: +contributors: + - Patryk + - Jazzz +--- + +## Abstract + +This specification defines the encoding format for Introduction Bundles — the +out-of-band information shared so that a remote party can initiate contact with +the bundle publisher. + +## Background / Rationale / Motivation + +Users need a way to share contact information across arbitrary channels +(messaging apps, emails, QR codes, URLs, CLI terminals) without relying on a +centralized directory. The Introduction Bundle provides the cryptographic +material required to establish an encrypted conversation. + +The encoding must be: +- Copy-paste safe across arbitrary text transports. +- Space-efficient for manual sharing. +- Version-aware to support protocol evolution. + +## Theory / Semantics + +An Introduction Bundle is bound to a specific protocol version; its encoded +form identifies the version unambiguously. + +### Why ASCII, Not Unicode + +The encoded string consists entirely of printable ASCII. This is a natural +consequence of the design rather than a defensive choice against Unicode: + +1. **No human-readable content.** The format contains a fixed prefix, a numeric + version, and a binary-to-text encoded payload. These components do not + require characters outside ASCII. Common binary-to-text encodings such as + hex, base32, and base64 produce ASCII output. +2. **Encoding stability.** Printable ASCII characters are represented + identically in widely deployed text encodings such as UTF-8 and Latin-1, + avoiding ambiguity in character interpretation across transports. +3. **Restricted visible alphabet.** Limiting the character set reduces the risk + of visually confusable or non-rendering characters during manual comparison, + transcription, or copy-paste across different platforms, terminals, and + fonts. + +### Delimiter Choice + +The `_` character is present in the alphabets of common binary-to-text +encodings (hex, base32, base64url) and may therefore appear inside the payload. +Parsers MUST split the encoded string on the **first three** `_` characters; +everything after the third `_` is the payload verbatim. + +The underscore was chosen because it is a printable ASCII character that is +safe in URLs, filenames, and plain text without requiring escaping. Delimiters +outside this category (e.g., `.` or `:`) may require percent-encoding in +certain URL contexts, undermining the transport-safety goal. + +## Wire Format Specification / Syntax + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in [RFC 2119]. + +### Text Format + +The Introduction Bundle is encoded as a single ASCII string: + +``` +logos___ +``` + +| Field | Description | +|-------------|-------------------------------------------------------------------| +| `logos` | Fixed prefix. Identifies the string as a Logos protocol artifact. | +| `namespace` | Domain identifier. Distinguishes bundle types. | +| `version` | Protocol version number. Decimal integer, no leading zeros. | +| `payload` | Binary-to-text encoded payload (version-specific). | + +Fields are separated by `_` (underscore). + +### V1 + +#### Parameters + +| Parameter | Value | +|-------------|--------------------------------| +| `namespace` | `chatintro` | +| `version` | `1` | +| `encoding` | base64url, no padding | +| `payload` | Protobuf-encoded `IntroBundle` | + +#### Payload Encoding + +V1 uses **base64url without padding** ([RFC 4648 §5], padding +characters `=` omitted). This encoding was chosen for: + +- URL safety without percent-encoding. +- ~33% size overhead (compared to ~100% for hex). +- Wide library support across languages. + +Future versions MAY choose a different binary-to-text encoding. + +#### Binary Payload + +The payload is a Protocol Buffers (proto3) encoding of: + +```proto +syntax = "proto3"; + +message IntroBundle { + bytes installation_pubkey = 1; // 32 bytes, X25519 + bytes ephemeral_pubkey = 2; // 32 bytes, X25519 + bytes signature = 3; // 64 bytes, XEdDSA +} +``` + +The encoding MUST use standard proto3 serialization. Canonical (deterministic) +serialization is NOT REQUIRED; decoders MUST accept any valid proto3 encoding +of the message. + +#### Encoding Procedure + +1. Construct the `IntroBundle` protobuf message. +2. Serialize using proto3 encoding (~134 bytes). +3. Encode as base64url without padding (~179 characters). +4. Prepend the preamble with version prefix. + +The resulting string is ~197 printable ASCII characters. + +## Security/Privacy Considerations + +The signature prevents tampering but does not provide confidentiality. Bundles +should be transmitted over channels appropriate for the user's threat model. + +## Copyright + +Copyright and related rights waived via [CC0]. + +## References + +- [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) — Key words for use in RFCs +- [RFC 4648 §5](https://www.rfc-editor.org/rfc/rfc4648#section-5) — Base 64 Encoding with URL and Filename Safe Alphabet +- [CC0](https://creativecommons.org/publicdomain/zero/1.0/) — Creative Commons Zero Public Domain Dedication + +[RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt +[RFC 4648 §5]: https://www.rfc-editor.org/rfc/rfc4648#section-5 +[CC0]: https://creativecommons.org/publicdomain/zero/1.0/ From 4d9de1d746747a48f06cad99b185d796bbe6aab6 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 22 May 2026 15:43:16 -0700 Subject: [PATCH 172/174] Update DS requirements --- standards/application/chat-framework.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 5f9b187..c077fbd 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -46,8 +46,10 @@ A Delivery Service (DS) is the service or method that distributes payloads to cl - A DS MUST provide a method for clients to subscribe to messages from a delivery_address - Payloads sent to a delivery_address are delivered by a DS to all subscribers of that delivery_address +- A DS SHOULD handle segmentation if the underling transport limits message sizes - A DS MAY NOT guarantee message delivery - A DS MAY NOT guarantee message ordering +- A DS MAY reject payloads ### Framing Strategy From a78e10ca1bc72756cf309fb48fba99fc6bcb579b Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 22 May 2026 15:47:52 -0700 Subject: [PATCH 173/174] Update background context --- standards/application/chat-framework.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index c077fbd..306c0da 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -16,13 +16,12 @@ This specification defines a modular communication protocol framework for descri Chat protocols specifications can be long and dense documents. To fully describe a chat protocol there are many layers and operations which are required to be documented. This includes payloads, message transport, encryption as well as user level features such as account registration, typing indicators, content formatting. -With the vast amount of information required to maintain compatibility between applications - protocol documentation is either comprehensive which leads to large monolithic specifications or lacking the required details for interop between implementors. +With the vast amount of information required to maintain compatibility between applications - protocol documentation is either comprehensive which leads to large monolithic specifications or lacking the required details for interop between implementors. A suitable solution would provide both the specificity while also remaining lean and focused. # Theory / Semantics This specification defines an abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. - The chat protocol is decomposed into 3 distinct phases. - **Discovery:** How does a Sender learn of other clients. @@ -34,7 +33,8 @@ and transport details are divided into: - **Delivery Service:** How are payloads routed and delivered to a client. - **Framing Strategy:** How are payloads encoded. -Defining these 5 parameters allows for chat protocol implementations to be fully defined, which allows clients from different applications to exchange messages. +Defining these 5 parameters allows for chat protocol implementations to be fully defined, which allows clients from different applications to exchange messages. +While also dividing documents by their focus area. ## Abstract Transport From 091e3dc874f6a6c8245a3b83c161d5c621cdc0a8 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 22 May 2026 15:52:38 -0700 Subject: [PATCH 174/174] Standardize Phases and components --- standards/application/chat-framework.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/standards/application/chat-framework.md b/standards/application/chat-framework.md index 306c0da..b0a020c 100644 --- a/standards/application/chat-framework.md +++ b/standards/application/chat-framework.md @@ -20,15 +20,15 @@ With the vast amount of information required to maintain compatibility between a # Theory / Semantics -This specification defines an abstract framework for building a chat protocol. Its purpose is to name the components, and define modular boundaries between components to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 problem areas. +This specification defines an abstract framework for building a chat protocol. Its purpose is to name the distinct components/phases, and define modular boundaries between them to promote reuse. The end result is that a chat protocol implementation can be described by listing its approach to 5 things. -The chat protocol is decomposed into 3 distinct phases. +The lifecycle of a protocol instance is divided into three phases: - **Discovery:** How does a Sender learn of other clients. - **Initialization:** How does a Recipient learn a client wants to communicate with them. - **Operation:** How do participants exchange content. -and transport details are divided into: +and transport details are divided into 2 components: - **Delivery Service:** How are payloads routed and delivered to a client. - **Framing Strategy:** How are payloads encoded. @@ -59,7 +59,7 @@ In this protocol framework, payloads from multiple protocols are potentially mul A framing strategy should define a common payload type as well as a method to determine which state machine a receiving client must use to decode it. -## Protocol Components +## Protocol Phases In order to exchange content clients must be able to learn of each others existence, gather the pre-requisite information/parameters and, remain synchronized over time.