@polkadot-apps/statement-store 0.2.0

package/dist/errors.js

@@ -0,0 +1,152 @@
+import { MAX_STATEMENT_SIZE } from "./types.js";
+/**
+ * Base class for all statement store errors.
+ *
+ * Use `instanceof StatementStoreError` to catch any error originating
+ * from the statement store package.
+ */
+export class StatementStoreError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "StatementStoreError";
+    }
+}
+/**
+ * A SCALE encoding or decoding operation failed.
+ *
+ * Thrown when statement bytes cannot be parsed (corrupt data, unknown field tags)
+ * or when encoding produces invalid output.
+ */
+export class StatementEncodingError extends StatementStoreError {
+    constructor(message, options) {
+        super(`Encoding error: ${message}`, options);
+        this.name = "StatementEncodingError";
+    }
+}
+/**
+ * The statement store node rejected a submitted statement.
+ *
+ * Carries the raw RPC response detail for programmatic inspection.
+ */
+export class StatementSubmitError extends StatementStoreError {
+    /** The raw response from the RPC call. */
+    detail;
+    constructor(detail) {
+        super(`Statement submission rejected: ${JSON.stringify(detail)}`);
+        this.name = "StatementSubmitError";
+        this.detail = detail;
+    }
+}
+/**
+ * Failed to set up or maintain a statement subscription.
+ *
+ * This is a non-fatal error — the client falls back to polling
+ * when subscriptions are unavailable.
+ */
+export class StatementSubscriptionError extends StatementStoreError {
+    constructor(message, options) {
+        super(`Subscription error: ${message}`, options);
+        this.name = "StatementSubscriptionError";
+    }
+}
+/**
+ * Failed to connect to the statement store transport.
+ *
+ * Thrown when the WebSocket connection cannot be established
+ * or the chain-client's bulletin chain is not connected.
+ */
+export class StatementConnectionError extends StatementStoreError {
+    constructor(message, options) {
+        super(`Connection error: ${message}`, options);
+        this.name = "StatementConnectionError";
+    }
+}
+/**
+ * The statement data payload exceeds the maximum allowed size.
+ *
+ * The statement store protocol limits individual statement data
+ * to {@link MAX_STATEMENT_SIZE} bytes (512 bytes).
+ */
+export class StatementDataTooLargeError extends StatementStoreError {
+    /** The actual size of the data in bytes. */
+    actualSize;
+    /** The maximum allowed size in bytes. */
+    maxSize;
+    constructor(actualSize, maxSize = MAX_STATEMENT_SIZE) {
+        super(`Statement data too large: ${actualSize} bytes exceeds maximum of ${maxSize} bytes`);
+        this.name = "StatementDataTooLargeError";
+        this.actualSize = actualSize;
+        this.maxSize = maxSize;
+    }
+}
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+    describe("StatementStoreError hierarchy", () => {
+        test("StatementStoreError is instanceof Error", () => {
+            const err = new StatementStoreError("test");
+            expect(err).toBeInstanceOf(Error);
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err.name).toBe("StatementStoreError");
+            expect(err.message).toBe("test");
+        });
+        test("StatementEncodingError", () => {
+            const err = new StatementEncodingError("bad field tag");
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err).toBeInstanceOf(Error);
+            expect(err.name).toBe("StatementEncodingError");
+            expect(err.message).toContain("bad field tag");
+        });
+        test("StatementEncodingError preserves cause", () => {
+            const cause = new Error("original");
+            const err = new StatementEncodingError("wrap", { cause });
+            expect(err.cause).toBe(cause);
+        });
+        test("StatementSubmitError", () => {
+            const detail = { status: "rejected", reason: "bad proof" };
+            const err = new StatementSubmitError(detail);
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err.name).toBe("StatementSubmitError");
+            expect(err.detail).toBe(detail);
+            expect(err.message).toContain("rejected");
+        });
+        test("StatementSubscriptionError", () => {
+            const err = new StatementSubscriptionError("not supported");
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err.name).toBe("StatementSubscriptionError");
+            expect(err.message).toContain("not supported");
+        });
+        test("StatementConnectionError", () => {
+            const err = new StatementConnectionError("timeout");
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err.name).toBe("StatementConnectionError");
+            expect(err.message).toContain("timeout");
+        });
+        test("StatementDataTooLargeError", () => {
+            const err = new StatementDataTooLargeError(600);
+            expect(err).toBeInstanceOf(StatementStoreError);
+            expect(err.name).toBe("StatementDataTooLargeError");
+            expect(err.actualSize).toBe(600);
+            expect(err.maxSize).toBe(512);
+            expect(err.message).toContain("600");
+            expect(err.message).toContain("512");
+        });
+        test("StatementDataTooLargeError with custom max", () => {
+            const err = new StatementDataTooLargeError(2000, 1024);
+            expect(err.actualSize).toBe(2000);
+            expect(err.maxSize).toBe(1024);
+        });
+        test("all errors are catchable via base class", () => {
+            const errors = [
+                new StatementEncodingError("test"),
+                new StatementSubmitError("test"),
+                new StatementSubscriptionError("test"),
+                new StatementConnectionError("test"),
+                new StatementDataTooLargeError(600),
+            ];
+            for (const err of errors) {
+                expect(err).toBeInstanceOf(StatementStoreError);
+            }
+        });
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { StatementStoreClient } from "./client.js";
+export { ChannelStore } from "./channels.js";
+export { createTopic, createChannel, serializeTopicFilter, topicToHex, topicsEqual, } from "./topics.js";
+export { encodeData, decodeData, encodeStatement, decodeStatement, createSignatureMaterial, toHex, fromHex, } from "./codec.js";
+export { RpcTransport, createTransport } from "./transport.js";
+export type { RpcClient } from "./transport.js";
+export { StatementStoreError, StatementEncodingError, StatementSubmitError, StatementSubscriptionError, StatementConnectionError, StatementDataTooLargeError, } from "./errors.js";
+export type { TopicHash, ChannelHash, StatementFields, DecodedStatement, TopicFilter, SerializedTopicFilter, StatementStoreConfig, PublishOptions, ReceivedStatement, StatementSigner, StatementSignerWithKey, SubmitStatus, StatementTransport, Unsubscribable, StatementEvent, } from "./types.js";
+export { MAX_STATEMENT_SIZE, MAX_USER_TOTAL, DEFAULT_TTL_SECONDS, DEFAULT_POLL_INTERVAL_MS, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,EACH,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,WAAW,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACH,UAAU,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,KAAK,EACL,OAAO,GACV,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EACH,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,GAC7B,MAAM,aAAa,CAAC;AAGrB,YAAY,EACR,SAAS,EACT,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,cAAc,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,GAC3B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// Client
+export { StatementStoreClient } from "./client.js";
+export { ChannelStore } from "./channels.js";
+// Topics
+export { createTopic, createChannel, serializeTopicFilter, topicToHex, topicsEqual, } from "./topics.js";
+// Codec (advanced use — for consumers that need direct SCALE access)
+export { encodeData, decodeData, encodeStatement, decodeStatement, createSignatureMaterial, toHex, fromHex, } from "./codec.js";
+// Transport (advanced use — for consumers that need custom transport implementations)
+export { RpcTransport, createTransport } from "./transport.js";
+// Errors
+export { StatementStoreError, StatementEncodingError, StatementSubmitError, StatementSubscriptionError, StatementConnectionError, StatementDataTooLargeError, } from "./errors.js";
+// Constants
+export { MAX_STATEMENT_SIZE, MAX_USER_TOTAL, DEFAULT_TTL_SECONDS, DEFAULT_POLL_INTERVAL_MS, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,SAAS;AACT,OAAO,EACH,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,WAAW,GACd,MAAM,aAAa,CAAC;AAErB,qEAAqE;AACrE,OAAO,EACH,UAAU,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,KAAK,EACL,OAAO,GACV,MAAM,YAAY,CAAC;AAEpB,sFAAsF;AACtF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG/D,SAAS;AACT,OAAO,EACH,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,GAC7B,MAAM,aAAa,CAAC;AAqBrB,YAAY;AACZ,OAAO,EACH,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,GAC3B,MAAM,YAAY,CAAC"}

package/dist/topics.d.ts

@@ -0,0 +1,60 @@
+import type { ChannelHash, SerializedTopicFilter, TopicFilter, TopicHash } from "./types.js";
+/**
+ * Create a 32-byte topic hash from a human-readable string.
+ *
+ * Uses blake2b-256 to hash the UTF-8 encoded string into a deterministic
+ * 32-byte topic identifier. Statements are tagged with topics so subscribers
+ * can filter efficiently on the network.
+ *
+ * @param name - A human-readable topic name (e.g., "ss-webrtc", "my-app").
+ * @returns A branded 32-byte topic hash.
+ *
+ * @example
+ * ```ts
+ * const topic = createTopic("ss-webrtc");
+ * // Use in subscriptions and publish options
+ * ```
+ */
+export declare function createTopic(name: string): TopicHash;
+/**
+ * Create a 32-byte channel hash from a human-readable channel name.
+ *
+ * Channels enable last-write-wins semantics: for a given channel,
+ * only the most recent statement (by timestamp) is retained.
+ *
+ * @param name - A human-readable channel name (e.g., "presence/peer-abc").
+ * @returns A branded 32-byte channel hash.
+ *
+ * @example
+ * ```ts
+ * const channel = createChannel("presence/peer-abc123");
+ * ```
+ */
+export declare function createChannel(name: string): ChannelHash;
+/**
+ * Convert a topic or channel hash to a hex string (with 0x prefix).
+ *
+ * @param hash - A 32-byte topic or channel hash.
+ * @returns Hex string with "0x" prefix.
+ */
+export declare function topicToHex(hash: Uint8Array): string;
+/**
+ * Compare two topic or channel hashes for byte equality.
+ *
+ * @param a - First hash.
+ * @param b - Second hash.
+ * @returns True if the hashes are identical.
+ */
+export declare function topicsEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Serialize a {@link TopicFilter} into the JSON-RPC format expected by statement store nodes.
+ *
+ * - `"any"` is passed through as the string `"any"`.
+ * - `{ matchAll: [...] }` becomes `{ matchAll: ["0x...", ...] }` with hex-encoded topics.
+ * - `{ matchAny: [...] }` becomes `{ matchAny: ["0x...", ...] }` with hex-encoded topics.
+ *
+ * @param filter - The topic filter to serialize.
+ * @returns A JSON-RPC compatible filter value.
+ */
+export declare function serializeTopicFilter(filter: TopicFilter): SerializedTopicFilter;
+//# sourceMappingURL=topics.d.ts.map

package/dist/topics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE7F;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAGnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMnD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAMjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,qBAAqB,CAQ/E"}

package/dist/topics.js

@@ -0,0 +1,187 @@
+import { blake2b } from "@noble/hashes/blake2.js";
+/**
+ * Create a 32-byte topic hash from a human-readable string.
+ *
+ * Uses blake2b-256 to hash the UTF-8 encoded string into a deterministic
+ * 32-byte topic identifier. Statements are tagged with topics so subscribers
+ * can filter efficiently on the network.
+ *
+ * @param name - A human-readable topic name (e.g., "ss-webrtc", "my-app").
+ * @returns A branded 32-byte topic hash.
+ *
+ * @example
+ * ```ts
+ * const topic = createTopic("ss-webrtc");
+ * // Use in subscriptions and publish options
+ * ```
+ */
+export function createTopic(name) {
+    const bytes = new TextEncoder().encode(name);
+    return blake2b(bytes, { dkLen: 32 });
+}
+/**
+ * Create a 32-byte channel hash from a human-readable channel name.
+ *
+ * Channels enable last-write-wins semantics: for a given channel,
+ * only the most recent statement (by timestamp) is retained.
+ *
+ * @param name - A human-readable channel name (e.g., "presence/peer-abc").
+ * @returns A branded 32-byte channel hash.
+ *
+ * @example
+ * ```ts
+ * const channel = createChannel("presence/peer-abc123");
+ * ```
+ */
+export function createChannel(name) {
+    const bytes = new TextEncoder().encode(name);
+    return blake2b(bytes, { dkLen: 32 });
+}
+/**
+ * Convert a topic or channel hash to a hex string (with 0x prefix).
+ *
+ * @param hash - A 32-byte topic or channel hash.
+ * @returns Hex string with "0x" prefix.
+ */
+export function topicToHex(hash) {
+    let hex = "0x";
+    for (let i = 0; i < hash.length; i++) {
+        hex += hash[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/**
+ * Compare two topic or channel hashes for byte equality.
+ *
+ * @param a - First hash.
+ * @param b - Second hash.
+ * @returns True if the hashes are identical.
+ */
+export function topicsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Serialize a {@link TopicFilter} into the JSON-RPC format expected by statement store nodes.
+ *
+ * - `"any"` is passed through as the string `"any"`.
+ * - `{ matchAll: [...] }` becomes `{ matchAll: ["0x...", ...] }` with hex-encoded topics.
+ * - `{ matchAny: [...] }` becomes `{ matchAny: ["0x...", ...] }` with hex-encoded topics.
+ *
+ * @param filter - The topic filter to serialize.
+ * @returns A JSON-RPC compatible filter value.
+ */
+export function serializeTopicFilter(filter) {
+    if (filter === "any")
+        return "any";
+    if ("matchAll" in filter) {
+        return { matchAll: filter.matchAll.map(topicToHex) };
+    }
+    return { matchAny: filter.matchAny.map(topicToHex) };
+}
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+    describe("createTopic", () => {
+        test("produces a 32-byte hash", () => {
+            const topic = createTopic("test");
+            expect(topic).toBeInstanceOf(Uint8Array);
+            expect(topic.length).toBe(32);
+        });
+        test("is deterministic (same input = same hash)", () => {
+            const a = createTopic("ss-webrtc");
+            const b = createTopic("ss-webrtc");
+            expect(topicsEqual(a, b)).toBe(true);
+        });
+        test("different inputs produce different hashes", () => {
+            const a = createTopic("topic-a");
+            const b = createTopic("topic-b");
+            expect(topicsEqual(a, b)).toBe(false);
+        });
+        test("empty string produces a valid hash", () => {
+            const topic = createTopic("");
+            expect(topic.length).toBe(32);
+        });
+    });
+    describe("createChannel", () => {
+        test("produces a 32-byte hash", () => {
+            const channel = createChannel("presence/peer-abc");
+            expect(channel).toBeInstanceOf(Uint8Array);
+            expect(channel.length).toBe(32);
+        });
+        test("same input as createTopic produces same bytes", () => {
+            const topic = createTopic("test-name");
+            const channel = createChannel("test-name");
+            expect(topicsEqual(topic, channel)).toBe(true);
+        });
+    });
+    describe("topicToHex", () => {
+        test("converts to hex with 0x prefix", () => {
+            const hash = new Uint8Array(32);
+            hash[0] = 0xab;
+            hash[1] = 0xcd;
+            const hex = topicToHex(hash);
+            expect(hex).toMatch(/^0x/);
+            expect(hex).toBe("0x" + "abcd" + "00".repeat(30));
+        });
+        test("round-trips through hex encoding", () => {
+            const topic = createTopic("round-trip-test");
+            const hex = topicToHex(topic);
+            expect(hex.length).toBe(2 + 64); // "0x" + 64 hex chars
+        });
+        test("pads single-digit bytes with leading zero", () => {
+            const hash = new Uint8Array([0x0a]);
+            expect(topicToHex(hash)).toBe("0x0a");
+        });
+    });
+    describe("topicsEqual", () => {
+        test("returns true for identical hashes", () => {
+            const a = createTopic("same");
+            const b = createTopic("same");
+            expect(topicsEqual(a, b)).toBe(true);
+        });
+        test("returns false for different hashes", () => {
+            const a = createTopic("alpha");
+            const b = createTopic("beta");
+            expect(topicsEqual(a, b)).toBe(false);
+        });
+        test("returns false for different lengths", () => {
+            const a = new Uint8Array(32);
+            const b = new Uint8Array(16);
+            expect(topicsEqual(a, b)).toBe(false);
+        });
+        test("returns true for empty arrays", () => {
+            expect(topicsEqual(new Uint8Array(0), new Uint8Array(0))).toBe(true);
+        });
+    });
+    describe("serializeTopicFilter", () => {
+        test("serializes 'any' as string", () => {
+            expect(serializeTopicFilter("any")).toBe("any");
+        });
+        test("serializes matchAll with hex topics", () => {
+            const topics = [createTopic("a"), createTopic("b")];
+            const result = serializeTopicFilter({ matchAll: topics });
+            expect(result.matchAll).toHaveLength(2);
+            expect(result.matchAll[0]).toMatch(/^0x[0-9a-f]{64}$/);
+            expect(result.matchAll[1]).toMatch(/^0x[0-9a-f]{64}$/);
+        });
+        test("serializes matchAny with hex topics", () => {
+            const topics = [createTopic("x")];
+            const result = serializeTopicFilter({ matchAny: topics });
+            expect(result.matchAny).toHaveLength(1);
+            expect(result.matchAny[0]).toMatch(/^0x[0-9a-f]{64}$/);
+        });
+        test("matchAll preserves order", () => {
+            const topicA = createTopic("first");
+            const topicB = createTopic("second");
+            const result = serializeTopicFilter({ matchAll: [topicA, topicB] });
+            expect(result.matchAll[0]).toBe(topicToHex(topicA));
+            expect(result.matchAll[1]).toBe(topicToHex(topicB));
+        });
+    });
+}
+//# sourceMappingURL=topics.js.map

package/dist/topics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topics.js","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,94 @@
+import type { StatementTransport, SubmitStatus, TopicFilter, TopicHash, Unsubscribable } from "./types.js";
+/**
+ * A PolkadotClient-compatible interface for raw RPC operations.
+ *
+ * This matches the subset of `PolkadotClient` methods we need.
+ * Using an interface allows easy mocking in tests.
+ */
+export interface RpcClient {
+    /** Make a one-shot RPC request. */
+    request: (method: string, params: unknown[]) => Promise<unknown>;
+    /** Start a subscription. Returns an unsubscribe function. */
+    _request: <T, S>(method: string, params: unknown[], callbacks: {
+        onSuccess: (subscriptionId: T, followSubscription: (id: T, handlers: {
+            next: (event: S) => void;
+            error: (e: Error) => void;
+        }) => void) => void;
+        onError: (error: Error) => void;
+    }) => () => void;
+    /** Destroy the client and close the connection. */
+    destroy: () => void;
+}
+/**
+ * Statement store transport using JSON-RPC over WebSocket.
+ *
+ * Communicates with a statement store node via the standard `statement_*` RPC methods.
+ * Supports both subscription-based real-time delivery and polling-based queries
+ * with graceful fallback across multiple RPC methods.
+ */
+export declare class RpcTransport implements StatementTransport {
+    private readonly client;
+    private readonly ownsClient;
+    /**
+     * @param client - The RPC client to use for communication.
+     * @param ownsClient - If true, `destroy()` will also destroy the client.
+     *   Set to false when sharing a client from chain-client.
+     */
+    constructor(client: RpcClient, ownsClient: boolean);
+    /**
+     * Subscribe to statements matching a topic filter.
+     *
+     * Uses the `statement_subscribeStatement` RPC method which returns
+     * batched events via a subscription stream. Handles all three event formats
+     * (raw hex, StatementEvent, nested wrappers) for cross-node compatibility.
+     *
+     * If the node does not support subscriptions, `onError` is called
+     * and the caller should fall back to polling.
+     */
+    subscribe(filter: TopicFilter, onStatement: (statementHex: string) => void, onError: (error: Error) => void): Unsubscribable;
+    /**
+     * Submit a signed statement via the `statement_submit` RPC method.
+     *
+     * @returns The submission status extracted from the RPC response.
+     */
+    submit(statementHex: string): Promise<SubmitStatus>;
+    /**
+     * Query existing statements from the store.
+     *
+     * Tries multiple RPC methods with graceful fallback:
+     * 1. `statement_posted` — filtered by topics + decryptionKey (most efficient)
+     * 2. `statement_broadcasts` — filtered by topics only
+     * 3. `statement_dump` — unfiltered, returns all statements
+     *
+     * Each method returns hex-encoded statements. If a method is not supported
+     * by the node, the next one is tried.
+     */
+    query(topics: TopicHash[], decryptionKey?: string): Promise<string[]>;
+    /**
+     * Destroy the transport and release resources.
+     *
+     * If this transport owns the RPC client (created via `endpoint` config),
+     * the client is also destroyed. If the client is shared from chain-client,
+     * only the transport's state is cleaned up.
+     */
+    destroy(): void;
+}
+/**
+ * Create a statement store transport.
+ *
+ * Strategy (Host API first):
+ * 1. Try chain-client's bulletin chain connection — this uses product-sdk's
+ *    `createPapiProvider` which routes through the Host API when inside a container,
+ *    falling back to direct RPC outside.
+ * 2. If chain-client is unavailable (not initialized, not installed), fall back
+ *    to a direct WebSocket connection using the provided `endpoint`.
+ * 3. If neither works, throw {@link StatementConnectionError}.
+ *
+ * @param config - Configuration with an optional fallback `endpoint`.
+ * @returns A configured {@link StatementTransport}.
+ * @throws {StatementConnectionError} If no connection method is available.
+ */
+export declare function createTransport(config: {
+    endpoint?: string;
+}): Promise<StatementTransport>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAER,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACjB,MAAM,YAAY,CAAC;AAoDpB;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACtB,mCAAmC;IACnC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EAAE,EACjB,SAAS,EAAE;QACP,SAAS,EAAE,CACP,cAAc,EAAE,CAAC,EACjB,kBAAkB,EAAE,CAChB,EAAE,EAAE,CAAC,EACL,QAAQ,EAAE;YAAE,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;YAAC,KAAK,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAA;SAAE,KAChE,IAAI,KACR,IAAI,CAAC;QACV,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KACnC,KACA,MAAM,IAAI,CAAC;IAChB,mDAAmD;IACnD,OAAO,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,kBAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC;;;;OAIG;gBACS,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO;IAKlD;;;;;;;;;OASG;IACH,SAAS,CACL,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,EAC3C,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAChC,cAAc;IAoDjB;;;;OAIG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQzD;;;;;;;;;;OAUG;IACG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyC3E;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAKlB;AA8BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsB9B"}