@mysten/sui-stack-messaging

TypeScript SDK for encrypted group messaging on Sui, powered by Seal for end-to-end encryption.

Installation

npm install @mysten/sui-stack-messaging

Architecture

The SDK is transport-agnostic. It handles encryption, decryption, key management, and on-chain group operations — but delegates message delivery and storage to a pluggable RelayerTransport interface. You can implement this interface to connect to any backend (HTTP server, WebSocket, peer-to-peer, etc.).

We provide two reference implementations:

• HTTPRelayerTransport — Built-in transport that works with the reference relayer. Ships with the SDK.
• WalrusRecoveryTransport (example) — Read-only recovery adapter that fetches messages from Walrus storage via the Discovery Indexer. Implements RecoveryTransport. Not part of the SDK — see examples/recovery-transport/ for a reference implementation.

Neither is required — you can build your own transport from scratch.

Quick Start

With the reference relayer (built-in HTTP transport)

The SDK uses Sui's client extension pattern. Chain $extend() to compose suiGroups, a Seal extension, and suiStackMessaging:

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { suiGroups } from '@mysten/sui-groups';
import { suiStackMessaging } from '@mysten/sui-stack-messaging';

const client = new SuiGrpcClient({ network: 'testnet' })
    .$extend(
        suiGroups({ witnessType: `${pkg}::messaging::Messaging` }),
        seal({ sealKeyServers }), // from @mysten/seal
    )
    .$extend(
        suiStackMessaging({
            encryption: { sessionKey: { ttlMin: 10, signer: keypair } },
            relayer: { relayerUrl: 'https://relayer.example.com' },
        }),
    );

// Send a message
await client.messaging.sendMessage({
    signer: keypair,
    groupRef: { uuid: 'my-group' },
    text: 'Hello, group!',
});

// Fetch and decrypt messages
const { messages } = await client.messaging.getMessages({
    signer: keypair,
    groupRef: { uuid: 'my-group' },
});

With a custom transport

import { suiStackMessaging } from '@mysten/sui-stack-messaging';
import type { RelayerTransport } from '@mysten/sui-stack-messaging';

class MyTransport implements RelayerTransport {
    // Implement sendMessage, fetchMessages, subscribe, etc.
    // Connect to whatever backend you want.
}

// Use { transport: ... } instead of { relayerUrl: ... }
const client = baseClient.$extend(
    suiStackMessaging({
        encryption: { sessionKey: { ttlMin: 10, signer: keypair } },
        relayer: { transport: new MyTransport() },
    }),
);

Recovery from Walrus

If your message backend persists messages to Walrus (as the reference relayer does), the SDK provides utilities to read them back directly — useful when the backend is unavailable and you need to restore conversation history.

SDK Utilities

• fromWalrusMessage(wire) — Converts a raw Walrus message (the serde_json wire format used by the reference relayer) to the SDK's RelayerMessage format. Handles number[] to Uint8Array, ISO 8601 to unix timestamps, field name mapping, and deriving isEdited/isDeleted.

• WalrusMessageWire — TypeScript type for the raw JSON shape stored on Walrus.

import { fromWalrusMessage } from '@mysten/sui-stack-messaging';
import type { WalrusMessageWire, RelayerMessage } from '@mysten/sui-stack-messaging';

// Read a message blob/patch from Walrus (via aggregator, SDK, etc.)
const rawJson = await fetchFromWalrus(blobId, patchId);
const wire: WalrusMessageWire = JSON.parse(rawJson);

// Convert to the SDK's standard format — ready for decryption
const message: RelayerMessage = fromWalrusMessage(wire);

Building a Recovery Transport

To restore full conversation history from Walrus, implement RecoveryTransport (1 method: recoverMessages) that:

1. Queries an indexer for which Walrus blobs contain a group's messages
2. Downloads message content from the Walrus aggregator
3. Converts each message using fromWalrusMessage()
4. Returns them sorted by order

See examples/recovery-transport/ for a complete reference implementation using the Discovery Indexer.

API Reference

Client Methods

Transport Interface (RelayerTransport)

Recovery Exports

License

Apache-2.0