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.
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.
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`.
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.
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).
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.
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.
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."
