polkadot-statement-store

Polkadot Statement Store

The Statement Store is a pub/sub messaging system built on top of the Polkadot Bulletin Chain. It lets peers publish small, signed, ephemeral statements tagged with topics and optional channels. Subscribers filter by topic to receive relevant statements in near real-time (via WebSocket subscriptions) with a polling fallback for reliability.

All code lives in a single package: @polkadot-apps/statement-store.

DATA SIZE LIMIT: MAX_STATEMENT_SIZE = 512 bytes. The JSON-serialized payload of any single statement must not exceed 512 bytes after UTF-8 encoding. Attempting to publish larger data throws StatementDataTooLargeError. Keep payloads minimal -- use the statement store for signaling and metadata, not bulk data transfer.

TWO CONNECTION MODES. connect() takes a ConnectionCredentials object, not a raw signer. Use { mode: "host", accountId } inside containers (proof creation is delegated to the host API) or { mode: "local", signer } outside containers (statements are signed locally with Sr25519).

Dependencies

{
  "dependencies": {
    "@polkadot-apps/statement-store": "workspace:*"
  }
}

The package internally depends on:

• @polkadot-apps/host -- for Host API transport and DEFAULT_BULLETIN_ENDPOINT
• @novasamatech/sdk-statement -- for statement SCALE codec and SDK
• @polkadot-api/substrate-client -- for WebSocket RPC transport

Optional peer dependency (auto-detected at runtime):

• @novasamatech/product-sdk -- for container-hosted transport (host mode)

Quick Start: Host Mode (Inside Container)

import { StatementStoreClient } from "@polkadot-apps/statement-store";

// 1. Create client with an application namespace
const client = new StatementStoreClient({ appName: "my-app" });

// 2. Connect with host credentials (inside a container)
//    accountId is a [ss58Address, chainPrefix] tuple from product-sdk
await client.connect({ mode: "host", accountId: ["5Grw...", 42] });

// 3. Subscribe to incoming statements
const sub = client.subscribe<{ type: string; peerId: string }>(statement => {
  console.log(statement.data.type, statement.signerHex);
});

// 4. Publish a statement (must be JSON-serializable, <= 512 bytes)
await client.publish(
  { type: "presence", peerId: "abc123" },
  { channel: "presence/abc123", topic2: "room-42" },
);

// 5. Clean up
sub.unsubscribe();
client.destroy();