@parity/product-sdk-bulletin 0.1.0 → 0.2.0

package/src/verify.ts

@@ -0,0 +1,384 @@
+/**
+ * Chain-storage verification for stored CIDs.
+ *
+ * The bulletin chain doesn't store content bytes on-chain — `TransactionStorage
+ * .Transactions[block]` holds metadata only (`{ chunk_root, content_hash,
+ * hashing, cid_codec, size, block_chunks }`), and the bytes themselves live
+ * in IPFS. So "read by CID from chain" isn't possible. What *is* possible is
+ * proving that a given CID was stored: parse the CID's digest + multihash
+ * code, then look it up in `TransactionStorage.Transactions` and confirm a
+ * matching `content_hash` + `hashing`.
+ *
+ * Common use case: just-after-upload UX — `await client.store(data).send()`
+ * gives you back `{ cid, blockNumber, extrinsicIndex? }`, and a follow-up
+ * `verifyOnChain(api, cid, { block: blockNumber })` confirms the metadata
+ * landed where expected.
+ */
+import { CID } from "multiformats/cid";
+
+import { HashAlgorithm } from "./cid.js";
+import { BulletinCidError } from "./errors.js";
+import type { BulletinApi } from "./types.js";
+
+/**
+ * Match a multihash code in a CID against the chain's `hashing` enum value.
+ */
+const HASH_CODE_TO_ENUM_TYPE: Record<number, "Blake2b256" | "Sha2_256" | "Keccak256"> = {
+    [HashAlgorithm.Blake2b256]: "Blake2b256",
+    [HashAlgorithm.Sha2_256]: "Sha2_256",
+    [HashAlgorithm.Keccak256]: "Keccak256",
+};
+
+/** A single matched entry from `TransactionStorage.Transactions`. */
+export interface ChainStoredEntry {
+    /** Block number where the transaction was included. */
+    block: number;
+    /** Index of the entry within the block's transactions array. */
+    index: number;
+    /** Size of the stored data in bytes (from chain metadata). */
+    size: number;
+    /** Number of chunks (1 for unchunked data, >1 for chunked + manifest). */
+    blockChunks: number;
+}
+
+/**
+ * Verification options for {@link verifyOnChain}.
+ */
+export interface VerifyOnChainOptions {
+    /**
+     * Block number to look up. Pass the `blockNumber` returned from a prior
+     * `store(...).send()` for an O(1) lookup.
+     *
+     * If omitted, throws — full-chain scans are not supported because
+     * `RetentionPeriod` can be many days of blocks. Use `getEntries()` on
+     * `api.query.TransactionStorage.Transactions` directly if you need that.
+     */
+    block: number;
+    /**
+     * Optional: index within the block. When provided, narrows verification
+     * to that exact slot. Useful when re-checking a known `(block, index)`
+     * tuple from an earlier receipt.
+     */
+    index?: number;
+}
+
+/**
+ * Verify that a CID is recorded in the bulletin chain's `Transactions`
+ * storage at the given block.
+ *
+ * Returns the matched entry (with block + index) when the CID's content
+ * hash and hashing algorithm both match a `Transactions[block]` entry.
+ * Returns `null` when no match is found at that block.
+ *
+ * @param api     - Typed bulletin API.
+ * @param cid     - CIDv1 string to look up.
+ * @param options - Verification target (block number, optional index).
+ *
+ * @example
+ * ```ts
+ * const receipt = await client.store(data).send();
+ * if (receipt.blockNumber !== undefined) {
+ *   const entry = await verifyOnChain(client.api, receipt.cid!.toString(), {
+ *     block: receipt.blockNumber,
+ *     index: receipt.extrinsicIndex,
+ *   });
+ *   if (!entry) console.warn("CID not found in expected block — chain reorg?");
+ * }
+ * ```
+ */
+export async function verifyOnChain(
+    api: BulletinApi,
+    cid: string,
+    options: VerifyOnChainOptions,
+): Promise<ChainStoredEntry | null> {
+    const parsed = parseCidForVerify(cid);
+
+    const queryFn = (api as unknown as TransactionsQueryApi).query?.TransactionStorage?.Transactions
+        ?.getValue;
+    if (!queryFn) {
+        throw new Error(
+            "Bulletin API does not expose query.TransactionStorage.Transactions — " +
+                "the typed API may be incomplete or the runtime version doesn't match the descriptor.",
+        );
+    }
+
+    const entries = await queryFn(options.block);
+    if (!entries || entries.length === 0) return null;
+
+    // When an explicit index is provided, check that slot directly — no
+    // reason to walk the full array just to skip everything else.
+    if (options.index !== undefined) {
+        const entry = entries[options.index];
+        if (entry && matchesEntry(entry, parsed)) {
+            return {
+                block: options.block,
+                index: options.index,
+                size: entry.size,
+                blockChunks: entry.block_chunks,
+            };
+        }
+        return null;
+    }
+
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i]!;
+        if (matchesEntry(entry, parsed)) {
+            return {
+                block: options.block,
+                index: i,
+                size: entry.size,
+                blockChunks: entry.block_chunks,
+            };
+        }
+    }
+
+    return null;
+}
+
+interface ParsedCid {
+    digest: Uint8Array;
+    hashType: "Blake2b256" | "Sha2_256" | "Keccak256";
+}
+
+/**
+ * Hand-rolled mirror of `TransactionStorage.Transactions[block][n]` — the
+ * shape PAPI returns at runtime when you call `query.TransactionStorage
+ * .Transactions.getValue(block)`. Defined here (rather than derived from
+ * `BulletinTypedApi`) because the typed API surfaces these values through
+ * `Anonymize<I…>` codec aliases that aren't ergonomic to inline.
+ *
+ * **If the bulletin runtime changes the entry shape, update this here too.**
+ * Source of truth: `TransactionInfo` in
+ * `packages/descriptors/chains/bulletin/generated/dist/common-types.d.ts`
+ * (look for `chunk_root: FixedSizeBinary<32>` to anchor it). When the
+ * descriptor regenerates and the fields shift, this interface, the
+ * `cid_codec`/`hashing` matching in `matchesEntry`, and the
+ * `HASH_CODE_TO_ENUM_TYPE` map above all need to be re-validated together.
+ *
+ * `Uint8Array | { asBytes(): Uint8Array }` covers both the raw and Binary-
+ * wrapped shapes the codec can return depending on configuration.
+ */
+interface ChainEntry {
+    chunk_root: { asBytes(): Uint8Array } | Uint8Array;
+    content_hash: { asBytes(): Uint8Array } | Uint8Array;
+    hashing: { type: "Blake2b256" | "Sha2_256" | "Keccak256" };
+    cid_codec: bigint;
+    size: number;
+    block_chunks: number;
+}
+
+interface TransactionsQueryApi {
+    query?: {
+        TransactionStorage?: {
+            Transactions?: {
+                getValue: (block: number) => Promise<ChainEntry[] | undefined>;
+            };
+        };
+    };
+}
+
+function parseCidForVerify(cid: string): ParsedCid {
+    let parsed;
+    try {
+        parsed = CID.parse(cid);
+    } catch {
+        throw new BulletinCidError(`Invalid CID: ${cid}`, cid);
+    }
+    if (parsed.version !== 1) {
+        throw new BulletinCidError(`Expected CIDv1, got CIDv${parsed.version}`, cid);
+    }
+    const hashType = HASH_CODE_TO_ENUM_TYPE[parsed.multihash.code];
+    if (!hashType) {
+        throw new BulletinCidError(
+            `Unsupported hash algorithm 0x${parsed.multihash.code.toString(16)}`,
+            cid,
+        );
+    }
+    return { digest: parsed.multihash.digest, hashType };
+}
+
+function matchesEntry(entry: ChainEntry, target: ParsedCid): boolean {
+    if (entry.hashing.type !== target.hashType) return false;
+    const onChainBytes =
+        entry.content_hash instanceof Uint8Array
+            ? entry.content_hash
+            : entry.content_hash.asBytes();
+    if (onChainBytes.length !== target.digest.length) return false;
+    for (let i = 0; i < onChainBytes.length; i++) {
+        if (onChainBytes[i] !== target.digest[i]) return false;
+    }
+    return true;
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    function makeMockApi(getValue: (block: number) => Promise<ChainEntry[] | undefined>) {
+        return {
+            query: {
+                TransactionStorage: {
+                    Transactions: { getValue },
+                },
+            },
+        } as unknown as BulletinApi;
+    }
+
+    function makeEntry(
+        digest: Uint8Array,
+        hashType: "Blake2b256" | "Sha2_256" | "Keccak256" = "Blake2b256",
+        size = 100,
+        blockChunks = 1,
+    ): ChainEntry {
+        return {
+            chunk_root: digest,
+            content_hash: digest,
+            hashing: { type: hashType },
+            cid_codec: 0x55n,
+            size,
+            block_chunks: blockChunks,
+        };
+    }
+
+    // Build a real CIDv1 (blake2b-256, raw) we can verify against
+    async function makeCidWithDigest(digest: Uint8Array, hashCode = 0xb220): Promise<string> {
+        const Digest = await import("multiformats/hashes/digest");
+        return CID.createV1(0x55, Digest.create(hashCode, digest)).toString();
+    }
+
+    describe("verifyOnChain", () => {
+        test("returns entry when CID matches at given block", async () => {
+            const digest = new Uint8Array(32).fill(0xab);
+            const cid = await makeCidWithDigest(digest);
+            const api = makeMockApi(vi.fn().mockResolvedValue([makeEntry(digest)]));
+
+            const result = await verifyOnChain(api, cid, { block: 100 });
+            expect(result).toEqual({ block: 100, index: 0, size: 100, blockChunks: 1 });
+        });
+
+        test("returns null when block has no entries", async () => {
+            const digest = new Uint8Array(32).fill(0xab);
+            const cid = await makeCidWithDigest(digest);
+            const api = makeMockApi(vi.fn().mockResolvedValue(undefined));
+
+            const result = await verifyOnChain(api, cid, { block: 100 });
+            expect(result).toBeNull();
+        });
+
+        test("returns null when block has entries but none match", async () => {
+            const targetDigest = new Uint8Array(32).fill(0xab);
+            const otherDigest = new Uint8Array(32).fill(0xcd);
+            const cid = await makeCidWithDigest(targetDigest);
+            const api = makeMockApi(vi.fn().mockResolvedValue([makeEntry(otherDigest)]));
+
+            const result = await verifyOnChain(api, cid, { block: 100 });
+            expect(result).toBeNull();
+        });
+
+        test("returns null when hashing algorithm differs", async () => {
+            const digest = new Uint8Array(32).fill(0xab);
+            // CID uses blake2b-256, chain entry says sha2-256 with same digest bytes
+            const cid = await makeCidWithDigest(digest, 0xb220);
+            const api = makeMockApi(vi.fn().mockResolvedValue([makeEntry(digest, "Sha2_256")]));
+
+            const result = await verifyOnChain(api, cid, { block: 100 });
+            expect(result).toBeNull();
+        });
+
+        test("finds match at correct index when multiple entries exist", async () => {
+            const targetDigest = new Uint8Array(32).fill(0xab);
+            const filler = new Uint8Array(32).fill(0xcd);
+            const cid = await makeCidWithDigest(targetDigest);
+            const api = makeMockApi(
+                vi
+                    .fn()
+                    .mockResolvedValue([
+                        makeEntry(filler),
+                        makeEntry(filler),
+                        makeEntry(targetDigest),
+                    ]),
+            );
+
+            const result = await verifyOnChain(api, cid, { block: 100 });
+            expect(result?.index).toBe(2);
+        });
+
+        test("respects explicit index option", async () => {
+            const targetDigest = new Uint8Array(32).fill(0xab);
+            const filler = new Uint8Array(32).fill(0xcd);
+            const cid = await makeCidWithDigest(targetDigest);
+            // Target is at index 2, but caller says index 0 — should not match
+            const api = makeMockApi(
+                vi
+                    .fn()
+                    .mockResolvedValue([
+                        makeEntry(filler),
+                        makeEntry(filler),
+                        makeEntry(targetDigest),
+                    ]),
+            );
+
+            const result = await verifyOnChain(api, cid, { block: 100, index: 0 });
+            expect(result).toBeNull();
+        });
+
+        test("returns the entry when explicit index matches", async () => {
+            const targetDigest = new Uint8Array(32).fill(0xab);
+            const filler = new Uint8Array(32).fill(0xcd);
+            const cid = await makeCidWithDigest(targetDigest);
+            const api = makeMockApi(
+                vi
+                    .fn()
+                    .mockResolvedValue([
+                        makeEntry(filler),
+                        makeEntry(filler),
+                        makeEntry(targetDigest),
+                    ]),
+            );
+
+            const result = await verifyOnChain(api, cid, { block: 100, index: 2 });
+            expect(result?.index).toBe(2);
+        });
+
+        test("throws BulletinCidError on invalid CID", async () => {
+            const api = makeMockApi(vi.fn());
+            await expect(verifyOnChain(api, "not-a-cid", { block: 1 })).rejects.toThrow(
+                BulletinCidError,
+            );
+        });
+
+        test("throws when api lacks the expected query path", async () => {
+            const api = {} as BulletinApi;
+            const digest = new Uint8Array(32).fill(0xab);
+            const cid = await makeCidWithDigest(digest);
+            await expect(verifyOnChain(api, cid, { block: 1 })).rejects.toThrow(
+                /does not expose query/,
+            );
+        });
+
+        test("handles content_hash as a Binary-like wrapper", async () => {
+            const digest = new Uint8Array(32).fill(0xab);
+            const cid = await makeCidWithDigest(digest);
+            const wrapper = { asBytes: () => digest };
+            const entry: ChainEntry = {
+                chunk_root: wrapper,
+                content_hash: wrapper,
+                hashing: { type: "Blake2b256" },
+                cid_codec: 0x55n,
+                size: 50,
+                block_chunks: 1,
+            };
+            const api = makeMockApi(vi.fn().mockResolvedValue([entry]));
+            const result = await verifyOnChain(api, cid, { block: 1 });
+            expect(result).toEqual({ block: 1, index: 0, size: 50, blockChunks: 1 });
+        });
+
+        test("passes the block number to the storage call", async () => {
+            const digest = new Uint8Array(32).fill(0xab);
+            const cid = await makeCidWithDigest(digest);
+            const getValue = vi.fn().mockResolvedValue([makeEntry(digest)]);
+            const api = makeMockApi(getValue);
+            await verifyOnChain(api, cid, { block: 42 });
+            expect(getValue).toHaveBeenCalledWith(42);
+        });
+    });
+}

package/src/gateway.ts

@@ -1,209 +0,0 @@
-import { BulletinGatewayFetchError, BulletinGatewayUnavailableError } from "./errors.js";
-import type { Environment, FetchOptions } from "./types.js";
-
-/** Add entries here as bulletin gateways go live on each network. */
-const GATEWAYS: Partial<Record<Environment, string>> = {
-    paseo: "https://paseo-ipfs.polkadot.io/ipfs/",
-};
-
-const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
-
-/**
- * Get the IPFS gateway URL for an environment.
- * @throws {BulletinGatewayUnavailableError} If the network doesn't have a live gateway yet.
- */
-export function getGateway(env: Environment): string {
-    const gw = GATEWAYS[env];
-    if (!gw) {
-        throw new BulletinGatewayUnavailableError(env);
-    }
-    return gw;
-}
-
-/** Build the full gateway URL for a CID. */
-export function gatewayUrl(cid: string, gateway: string): string {
-    return `${gateway}${cid}`;
-}
-
-/** Check if a CID exists on the gateway (HEAD request). Returns false on any error or timeout. */
-export async function cidExists(
-    cid: string,
-    gateway: string,
-    options?: FetchOptions,
-): Promise<boolean> {
-    const timeoutMs = options?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetch(gatewayUrl(cid, gateway), {
-            method: "HEAD",
-            signal: controller.signal,
-        });
-        return response.ok;
-    } catch {
-        return false;
-    } finally {
-        clearTimeout(timer);
-    }
-}
-
-/**
- * Fetch raw bytes from the gateway.
- * @throws {BulletinGatewayFetchError} If the gateway returns a non-OK response.
- */
-export async function fetchBytes(
-    cid: string,
-    gateway: string,
-    options?: FetchOptions,
-): Promise<Uint8Array> {
-    const timeoutMs = options?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-        const response = await fetch(gatewayUrl(cid, gateway), { signal: controller.signal });
-        if (!response.ok) {
-            throw new BulletinGatewayFetchError(cid, response.status, response.statusText);
-        }
-        return new Uint8Array(await response.arrayBuffer());
-    } finally {
-        clearTimeout(timer);
-    }
-}
-
-/** Fetch and parse JSON from the gateway. */
-export async function fetchJson<T>(
-    cid: string,
-    gateway: string,
-    options?: FetchOptions,
-): Promise<T> {
-    const bytes = await fetchBytes(cid, gateway, options);
-    return JSON.parse(new TextDecoder().decode(bytes)) as T;
-}
-
-if (import.meta.vitest) {
-    const { describe, test, expect, vi, afterEach } = import.meta.vitest;
-
-    afterEach(() => {
-        vi.restoreAllMocks();
-    });
-
-    describe("getGateway", () => {
-        test("returns known URL for paseo", () => {
-            const gw = getGateway("paseo");
-            expect(gw).toMatch(/^https:\/\//);
-            expect(gw).toMatch(/\/ipfs\/$/);
-        });
-
-        test("throws BulletinGatewayUnavailableError for environments without a live gateway", () => {
-            expect(() => getGateway("polkadot")).toThrow(BulletinGatewayUnavailableError);
-            expect(() => getGateway("kusama")).toThrow(BulletinGatewayUnavailableError);
-        });
-    });
-
-    describe("gatewayUrl", () => {
-        test("concatenates gateway and CID", () => {
-            expect(gatewayUrl("bafyabc", "https://gw.example/ipfs/")).toBe(
-                "https://gw.example/ipfs/bafyabc",
-            );
-        });
-    });
-
-    describe("cidExists", () => {
-        test("returns true for 200 response", async () => {
-            vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
-            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(true);
-        });
-
-        test("returns false for 404 response", async () => {
-            vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 404 }));
-            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(false);
-        });
-
-        test("returns false on network error", async () => {
-            vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network")));
-            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(false);
-        });
-
-        test("returns false on timeout", async () => {
-            vi.stubGlobal(
-                "fetch",
-                vi.fn().mockImplementation(
-                    (_url: string, init: { signal: AbortSignal }) =>
-                        new Promise((_resolve, reject) => {
-                            init.signal.addEventListener("abort", () =>
-                                reject(new DOMException("aborted", "AbortError")),
-                            );
-                        }),
-                ),
-            );
-            expect(await cidExists("bafyabc", "https://gw/ipfs/", { timeoutMs: 10 })).toBe(false);
-        });
-    });
-
-    describe("fetchBytes", () => {
-        test("returns bytes from response", async () => {
-            const payload = new Uint8Array([1, 2, 3]);
-            vi.stubGlobal(
-                "fetch",
-                vi.fn().mockResolvedValue({
-                    ok: true,
-                    arrayBuffer: () => Promise.resolve(payload.buffer),
-                }),
-            );
-            const result = await fetchBytes("bafyabc", "https://gw/ipfs/");
-            expect(result).toEqual(payload);
-        });
-
-        test("throws BulletinGatewayFetchError on non-ok response", async () => {
-            vi.stubGlobal(
-                "fetch",
-                vi.fn().mockResolvedValue({
-                    ok: false,
-                    status: 500,
-                    statusText: "Internal Server Error",
-                }),
-            );
-            const err = await fetchBytes("bafyabc", "https://gw/ipfs/").catch((e) => e);
-            expect(err).toBeInstanceOf(BulletinGatewayFetchError);
-            expect(err.cid).toBe("bafyabc");
-            expect(err.status).toBe(500);
-        });
-
-        test("throws on timeout", async () => {
-            vi.stubGlobal(
-                "fetch",
-                vi.fn().mockImplementation(
-                    (_url: string, init: { signal: AbortSignal }) =>
-                        new Promise((_resolve, reject) => {
-                            init.signal.addEventListener("abort", () =>
-                                reject(new DOMException("aborted", "AbortError")),
-                            );
-                        }),
-                ),
-            );
-            await expect(
-                fetchBytes("bafyabc", "https://gw/ipfs/", { timeoutMs: 10 }),
-            ).rejects.toThrow();
-        });
-    });
-
-    describe("fetchJson", () => {
-        test("parses JSON from response", async () => {
-            const obj = { name: "test", value: 42 };
-            const bytes = new TextEncoder().encode(JSON.stringify(obj));
-            vi.stubGlobal(
-                "fetch",
-                vi.fn().mockResolvedValue({
-                    ok: true,
-                    arrayBuffer: () => Promise.resolve(bytes.buffer),
-                }),
-            );
-            const result = await fetchJson<{ name: string; value: number }>(
-                "bafyabc",
-                "https://gw/ipfs/",
-            );
-            expect(result).toEqual(obj);
-        });
-    });
-}

package/src/resolve-signer.ts

@@ -1,66 +0,0 @@
-import { getPreimageManager } from "@parity/product-sdk-host";
-import { createLogger } from "@parity/product-sdk-logger";
-import type { PolkadotSigner } from "polkadot-api";
-
-import { BulletinHostUnavailableError } from "./errors.js";
-
-const log = createLogger("bulletin");
-
-/**
- * Discriminated union describing how data will be uploaded to the Bulletin Chain.
- *
- * - `"preimage"` — the host handles signing and chain submission via its preimage API.
- * - `"signer"`   — a `TransactionStorage.store` transaction is signed and submitted directly.
- */
-export type UploadStrategy =
-    | { kind: "preimage"; submit: (data: Uint8Array) => Promise<string> }
-    | { kind: "signer"; signer: PolkadotSigner };
-
-/**
- * Determine the upload strategy for the Bulletin Chain.
- *
- * Resolution order:
- * 1. If an explicit signer is provided, use it directly.
- * 2. Otherwise, use the host preimage API (the SDK is designed to run inside a container).
- *
- * @param explicitSigner - Optional signer provided by the caller. When present,
- *                         skips host auto-detection entirely.
- * @returns The resolved upload strategy.
- * @throws {Error} If no signer is provided and the host preimage API is unavailable.
- */
-export async function resolveUploadStrategy(
-    explicitSigner?: PolkadotSigner,
-): Promise<UploadStrategy> {
-    if (explicitSigner) {
-        log.debug("using explicit signer provided by caller");
-        return { kind: "signer", signer: explicitSigner };
-    }
-
-    // Use the host preimage API (inside container)
-    const preimageManager = await getPreimageManager();
-    if (preimageManager) {
-        log.info("using host preimage API for bulletin upload");
-        return { kind: "preimage", submit: (data) => preimageManager.submit(data) };
-    }
-
-    throw new BulletinHostUnavailableError("upload");
-}
-
-if (import.meta.vitest) {
-    const { describe, test, expect, vi } = import.meta.vitest;
-
-    describe("resolveUploadStrategy", () => {
-        test("returns explicit signer when provided", async () => {
-            const signer = { publicKey: new Uint8Array(32) } as PolkadotSigner;
-            const strategy = await resolveUploadStrategy(signer);
-            expect(strategy.kind).toBe("signer");
-            if (strategy.kind === "signer") {
-                expect(strategy.signer).toBe(signer);
-            }
-        });
-
-        // Note: Tests for host preimage manager integration require e2e testing
-        // as they depend on the actual host container environment.
-        // The explicit signer path above validates the core logic.
-    });
-}