From d4690df2e69266d2cb7354836a4d59d34d7e6100 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Mon, 23 Mar 2026 22:29:04 +0100 Subject: [PATCH 001/101] 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 fa7ff625c225fcad3df8baf3ecb28ea59c8d0de8 Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Tue, 31 Mar 2026 20:44:09 +0200 Subject: [PATCH 002/101] 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 003/101] 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 004/101] 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 005/101] 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 006/101] 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 007/101] 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 008/101] 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 009/101] 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 010/101] 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 011/101] 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 012/101] 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 013/101] 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 014/101] 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 015/101] 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 016/101] 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 017/101] 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 018/101] 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 019/101] 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 020/101] 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 021/101] 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 022/101] 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 023/101] 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 024/101] 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 025/101] 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 026/101] 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 027/101] 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 028/101] 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 029/101] 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 030/101] 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 031/101] 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 032/101] 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 033/101] 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 034/101] 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 035/101] 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 036/101] 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 037/101] 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 038/101] 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 039/101] 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 040/101] 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 041/101] 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 042/101] 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 043/101] 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 044/101] 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 045/101] 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 046/101] 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 047/101] 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 048/101] 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 049/101] 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 050/101] 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 051/101] 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 052/101] 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 053/101] 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 054/101] 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 055/101] 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 056/101] 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 057/101] 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 058/101] 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 059/101] 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 060/101] 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 061/101] 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 062/101] 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 063/101] 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 064/101] 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 065/101] 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 066/101] 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 067/101] 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 068/101] 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 069/101] 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 070/101] 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 071/101] 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 072/101] 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 073/101] 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 074/101] 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 075/101] 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 076/101] 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 077/101] 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 078/101] 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 079/101] 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 080/101] 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 081/101] 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 082/101] 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 083/101] 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 084/101] 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 085/101] 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 086/101] 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 087/101] 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 088/101] 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 089/101] 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 090/101] 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 091/101] 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 092/101] 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 093/101] 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 094/101] 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 095/101] 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 096/101] 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 097/101] 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 098/101] 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 099/101] 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 100/101] 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 101/101] 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