Offline send, receive, and reconciliation

How the SDK handles out-of-order and skipped messages, what the subscription APIs cover, and which parts of offline behaviour your application still owns.

Status: pre-1.0
Applies to: 0.1.0
Platforms: Expo · Browser · Node
Prereqs: A working client from Start → Quickstart
Reading time: 10 min

Encrypted messaging is offline-first whether you planned for it or not. A ratchet is local state that advances with each encryption and decryption. After a week offline, a device does not only have a stale cache. It also holds a different position in a shared cryptographic sequence.

This page explains SDK behavior and application responsibilities.

The SDK does not own an outbox

There is no send queue in @open-e2ee/signal-protocol-sdk. send(recipientUserId, content) and encryptMessage(remoteAddress, plaintext) attempt the operation now and throw if they cannot complete it. If the user is on a train, your application must remember the composed message.

The same responsibility boundary applies here:

"The client owns protocol coordination; the host application owns persistence, authentication, authorization, and product policy."

An outbox combines persistence and policy. Your application determines the retry period and what to show after attempt six. It also determines how to handle a message that remains pending for two days. The SDK cannot make these product decisions.

What it gives you instead is a retry primitive with sane bounds:

import { withRetry } from '@open-e2ee/signal-protocol-sdk/utils/retry';

await withRetry(() => signal.send(recipientUserId, body), {
  operationName: 'send',
  maxRetries: 2,
  baseDelay: 1000,
  maxDelay: 10000,
});

withRetry is for a single operation crossing a flaky network. It is not a durable queue and it does not survive a process restart. Your outbox rows need to live in your own database, next to the decrypted message rows you already own.

Out-of-order and skipped messages

The Double Ratchet handles gaps by deriving and storing the message keys it skipped over, so a message that arrives late still decrypts. The bounds are configurable on ratchetConfig and default to:

Option	Default	What it bounds
`maxSkip`	`1000`	How far ahead of the last received counter a message may be
`maxMessageKeysStored`	`1000`	How many skipped keys are retained at once
`keyExpirationMs`	`604800000` (7 days)	How long a skipped key is kept before it is dropped

Separately, MAX_UNACKNOWLEDGED_SESSION_AGE_MS is 30 days. The SDK treats an unanswered prekey session as stale after that period.

These limits define the edge of "messages arrive eventually". A device can miss more than 1000 messages in one chain. It can also return after eight days for a key that expired after seven days. Both cases produce an error instead of a retry.

Failure mode — TOO_MANY_SKIPPED_MESSAGES and MESSAGE_TOO_OLD

Both surface as an EncryptionError whose .code is TOO_MANY_SKIPPED_MESSAGES or MESSAGE_TOO_OLD. Neither is recoverable by retrying the same ciphertext: the receiving device either never derived the required key material or already deleted it.

MESSAGE_DUPLICATE and DuplicatedMessageError identify the opposite case. They are usually benign. The ratchet already consumed that message number. Expect this result when a relay redelivers a message or the application replays a batch after a crash. Treat duplicates as a message-layer no-op. Do not show them as a user error.

What you cannot do is tell the user which of these happened in a way they can act on. The useful product behaviour is a gap marker in the thread plus a structured log line, not a modal.

Catching up after reconnect

Two subscriptions cover live delivery.

startRelaySubscription() starts local decryption. startRetryRequestSubscription() handles SESAME retries path when a peer cannot decrypt your message. stopRelaySubscription() ends the first subscription. stop() shuts down the complete client.

For a backlog, decrypt in batches rather than one call per message:

const results = await signal.processIncomingEnvelopes(pendingEnvelopes);

for (const result of results) {
  if ('plaintext' in result) {
    await db.insertMessage(result.envelope, result.plaintext);
  } else {
    await db.recordUndecryptable(result.envelope, result.error);
  }
}

processIncomingEnvelopes() returns a result for each envelope. It does not throw after the first failure. One invalid envelope therefore does not block the next ninety envelopes.

The method also sorts prekey messages before ordinary ciphertexts. A prekey message establishes the session that later messages require. Use decryptMessages(remoteAddress, ciphertexts) for a single peer's batch.

Read client.syncStatus before you show a connected state. Its value is 'synced' | 'failed' | 'none'. The 'none' value means that you did not configure a relay. The 'failed' value means that the sync did not complete. Call the idempotent syncToServer() method again to recover.

Opacity ledger

Artifact	Stays on device	Sent to relay	In object store	Visible as metadata
Application outbox rows (app-owned)	yes	no	no	no
Envelope ciphertext	yes	yes	no	size, sender/recipient routing, arrival time
Skipped message keys (`maxMessageKeysStored`)	yes	no	no	no
Session record (`version: 4`)	yes	no	no	no
`client.syncStatus`	yes	no	no	no
`markAsRead(messageId)` state	yes	no	no	no
`sendReadReceipt(recipientUserId, timestamps)` payload	yes	yes	no	that a receipt-shaped envelope moved
Decrypted plaintext from `processIncomingEnvelopes()`	yes	no	no	no

Reconciliation converges. It does not commit

This is the part that surprises teams coming from a server-authoritative stack. With a central database, two conflicting edits arrive at one place and one of them wins at a known instant. With end-to-end encryption there is no such place. The relay never needs message plaintext or device private keys, which also means it cannot arbitrate anything that depends on reading them. Every device reaches agreement on its own schedule from the operations it received.

This model provides no global order for business logic. It also provides no server-side "last write wins" behavior for encrypted fields. Two devices can show different states while both operate correctly. The users' offline periods, not your infrastructure, bound this window.

Tradeoff — Op-log growth under encryption

The standard fix for an ever-growing operation log is server compaction: the server reads the log, collapses superseded operations, and ships a snapshot. A relay cannot do that here, because compaction requires understanding what each operation means.

The log and cold-sync cost therefore grow together. You can use client-side snapshots. A device periodically writes an encrypted checkpoint, which the relay stores as opaque data. The relay serves this checkpoint instead of the complete log. You must build and version this system.

You can instead set a fixed retention limit. Older operations then expire. A device that exceeds the limit must resync from a checkpoint or start clean. Both options have costs. Choose before a user accumulates 200,000 operations.

0.1.x; public APIs and persisted formats may change before 1.0.

Recovery, backup, and migration: what happens to history a device was never present for
Error handling: the full error taxonomy behind TOO_MANY_SKIPPED_MESSAGES and related errors
Local-first architecture: why convergence, not commit, is the model
Offline, recovery, and identity change: an end-to-end worked example