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.
## 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.
- **Rate Limit Manager** to comply with [RLN](https://lip.logos.co/messaging/standards/core/17/rln-relay.html) constraints when sending segmented messages.
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.
- **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).
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).
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: 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."
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."
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<byte>
returns:
type: result<array<byte>, error>
decrypt:
type: function
description: "Decrypts a byte payload. Returns the decrypted payload."
parameters:
- name: payload
type: array<byte>
returns:
type: result<array<byte>, 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."
- 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.
