@parity/product-sdk-bulletin 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,194 +1,52 @@
-import { TypedApi, PolkadotSigner } from 'polkadot-api';
+import { BulletinTypedApi, AsyncBulletinClient, ClientConfig, StoreBuilder, AuthCallBuilder, CallBuilder } from '@parity/bulletin-sdk';
+export { AsyncBulletinClient, AuthCallBuilder, AuthorizationScope, BulletinClientInterface, BulletinError, BulletinPreparer, BulletinTypedApi, CID, CallBuilder, Chunk, ChunkDetails, ChunkProgressEvent, ChunkStatus, ChunkedStoreResult, ChunkerConfig, ClientConfig, DEFAULT_CHUNKER_CONFIG, DEFAULT_CLIENT_CONFIG, DEFAULT_STORE_OPTIONS, DagManifest, ErrorCode, MAX_CHUNK_SIZE, MAX_FILE_SIZE, MockBulletinClient, MockClientConfig, MockOperation, ProgressCallback, ProgressEvent, StoreBuilder, StoreOptions, StoreResult, SubmitFn, TransactionReceipt, TransactionStatusEvent, TxStatus, WaitFor, calculateCid, cidFromBytes, cidToBytes, convertCid, estimateAuthorization, getContentHash, parseCid, reassembleChunks, resolveClientConfig, validateChunkSize } from '@parity/bulletin-sdk';
+import { PolkadotSigner } from 'polkadot-api';
+import { bulletin } from '@parity/product-sdk-descriptors/bulletin';
 import { WaitFor, TxStatus } from '@parity/product-sdk-tx';
-import { Environment } from '@parity/product-sdk-chain-client';
 export { Environment } from '@parity/product-sdk-chain-client';
 
 /**
- * Hash algorithms supported by the Bulletin Chain.
+ * Known Bulletin Chain networks.
  *
- * Values are multihash codes as defined in the
- * {@link https://github.com/multiformats/multicodec multicodec table}.
+ * Pairs each environment with the genesis hash and the PAPI descriptor needed
+ * to construct an `AsyncBulletinClient`. Re-uses the descriptor exported by
+ * `@parity/product-sdk-descriptors/bulletin` — the bulletin descriptor is the
+ * same across all environments today, so the difference between entries is
+ * the genesis hash (and, downstream, the chain RPC URL).
  */
-declare const HashAlgorithm: {
-    /** BLAKE2b-256 — default for product-sdk and the chain SDK. */
-    readonly Blake2b256: 45600;
-    /** SHA2-256 — default for bulletin-deploy. */
-    readonly Sha2_256: 18;
-    /** Keccak-256 — Ethereum compatibility. */
-    readonly Keccak256: 27;
-};
-/** A multihash code supported by the Bulletin Chain. */
-type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
+
+interface BulletinNetwork {
+    /** Genesis hash of the bulletin chain on this environment. */
+    genesisHash: `0x${string}`;
+    /** PAPI descriptor for typed API access. */
+    descriptor: typeof bulletin;
+}
 /**
- * CID codecs supported by the Bulletin Chain.
+ * Bulletin Chain network presets.
  *
- * Values are multicodec codes.
+ * Use these with {@link BulletinClient.create} when you want to be explicit
+ * about the network rather than passing an environment string. Reads go
+ * through the host's preimage subscription (container-only); no gateway
+ * URL is configured per network.
  */
-declare const CidCodec: {
-    /** Raw binary — default for single-chunk data. */
-    readonly Raw: 85;
-    /** DAG-PB — used for multi-chunk manifests / directory structures. */
-    readonly DagPb: 112;
-    /** DAG-CBOR — alternative DAG encoding. */
-    readonly DagCbor: 113;
+declare const BulletinChain: {
+    readonly paseo: {
+        readonly genesisHash: "0x744960c32e3a3df5440e1ecd4d34096f1ce2230d7016a5ada8a765d5a622b4ea";
+        readonly descriptor: any;
+    };
 };
-/** A multicodec code supported by the Bulletin Chain. */
-type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
-/**
- * Compute the CIDv1 (blake2b-256, raw codec) for arbitrary data.
- * Deterministic: same input always produces the same CID.
- */
-declare function computeCid(data: Uint8Array): string;
-/**
- * Extract the content hash digest from a CIDv1 string and return it as a
- * `0x`-prefixed hex string — the preimage key format used by the host API.
- *
- * Accepts CIDv1 with any hash algorithm supported by the Bulletin Chain
- * (blake2b-256, sha2-256, keccak-256).
- *
- * @param cid - CIDv1 base32 string (as produced by {@link computeCid} or {@link hashToCid}).
- * @returns `0x`-prefixed hex string of the 32-byte hash digest.
- * @throws If the CID is not CIDv1 or uses an unsupported hash algorithm.
- */
-declare function cidToPreimageKey(cid: string): `0x${string}`;
-/**
- * Reconstruct a CIDv1 from a `0x`-prefixed hex hash stored on-chain.
- *
- * This is the inverse of {@link cidToPreimageKey}: given a 32-byte content hash
- * and the CID configuration used when the data was stored, it rebuilds the
- * original CIDv1 so you can construct IPFS gateway URLs.
- *
- * The Bulletin Chain supports multiple hash algorithms and codecs — pass the
- * values that match the on-chain `TransactionInfo` to get the correct CID.
- * When omitted, defaults match {@link computeCid} (blake2b-256, raw).
- *
- * @param hexHash   - `0x`-prefixed hex string of a 32-byte hash digest
- *   (66 characters total: `"0x"` + 64 hex chars).
- * @param hashCode  - Multihash code of the hashing algorithm (default: blake2b-256 `0xb220`).
- *   Use {@link HashAlgorithm} for the supported values.
- * @param codec     - Multicodec code of the CID codec (default: raw `0x55`).
- *   Use {@link CidCodec} for the supported values.
- * @returns Base32-lower CIDv1 string.
- * @throws If `hexHash` is not exactly 66 characters, or if the hash/codec is unsupported.
- *
- * @example
- * ```ts
- * import { hashToCid, HashAlgorithm, CidCodec, gatewayUrl, getGateway } from "@parity/product-sdk-bulletin";
- *
- * // Default (blake2b-256, raw) — matches computeCid output
- * const cid = hashToCid(onChainHash);
- *
- * // SHA2-256 content stored via bulletin-deploy
- * const cid2 = hashToCid(onChainHash, HashAlgorithm.Sha2_256);
- *
- * // DAG-PB manifest with blake2b-256
- * const cid3 = hashToCid(manifestHash, HashAlgorithm.Blake2b256, CidCodec.DagPb);
- *
- * const url = gatewayUrl(cid, getGateway("paseo"));
- * ```
- *
- * @see {@link cidToPreimageKey} for the reverse direction (CID → hex hash).
- * @see {@link computeCid} for computing a CID from raw data.
- * @see {@link HashAlgorithm} for supported hash algorithms.
- * @see {@link CidCodec} for supported CID codecs.
- */
-declare function hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
+/** Network keys with built-in presets in {@link BulletinChain}. */
+type BulletinEnvironment = keyof typeof BulletinChain;
 
-/** Typed API for the Bulletin Chain, derived from PAPI descriptors. */
-type BulletinApi = TypedApi<any>;
+/** Typed API for the Bulletin Chain (re-export from upstream). */
+type BulletinApi = BulletinTypedApi;
 
-/**
- * Options for {@link upload}.
- *
- * Note: `waitFor`, `timeoutMs`, and `onStatus` only apply to the **transaction**
- * upload path (when an explicit signer is used or the dev signer fallback is active).
- * The preimage path delegates to the host which controls its own submission
- * lifecycle — these options are ignored in that case.
- */
-interface UploadOptions {
-    /** IPFS gateway base URL (e.g., from `getGateway("paseo")`). If provided, result includes gatewayUrl. */
-    gateway?: string;
-    /** When to resolve: `"best-block"` (default) or `"finalized"`. Transaction path only. */
-    waitFor?: WaitFor;
-    /** Timeout in ms. Default: 300_000 (5 min). Transaction path only. */
-    timeoutMs?: number;
-    /** Lifecycle status callback for UI progress. Transaction path only. */
-    onStatus?: (status: TxStatus) => void;
-}
-/** Fields common to all upload results. */
-interface UploadResultBase {
-    /** CIDv1 string (blake2b-256, raw codec). */
-    cid: string;
-    /** Gateway URL. Present only if `gateway` was provided in options. */
-    gatewayUrl?: string;
-}
-/**
- * Result of a successful upload to the Bulletin Chain.
- *
- * Discriminated on `kind`:
- * - `"transaction"` — uploaded via a signed `TransactionStorage.store` extrinsic.
- * - `"preimage"` — uploaded via the host preimage API (no user signing).
- *
- * Use `result.kind` to narrow the type and access path-specific fields.
- */
-type UploadResult = (UploadResultBase & {
-    /** Upload was performed via a signed transaction. */
-    kind: "transaction";
-    /** Block hash where the store transaction was included. */
-    blockHash: string;
-}) | (UploadResultBase & {
-    /** Upload was performed via the host preimage API. */
-    kind: "preimage";
-    /** Hex key returned by the host preimage API. */
-    preimageKey: string;
-});
-/** A single item in a batch upload. */
-interface BatchUploadItem {
-    /** Raw bytes to upload. */
-    data: Uint8Array;
-    /** Label for progress tracking (e.g., filename). */
-    label: string;
-}
-/** Fields common to all batch upload results. */
-interface BatchUploadResultBase {
-    label: string;
-    cid: string;
-    gatewayUrl?: string;
-}
-/**
- * Result for one item in a batch upload.
- *
- * Discriminated on `kind` (upload path) and `success` (outcome).
- * Use `result.success` to check for errors, then `result.kind` to access
- * path-specific fields like `blockHash` or `preimageKey`.
- */
-type BatchUploadResult = (BatchUploadResultBase & {
-    kind: "transaction";
-    success: true;
-    /** Block hash where the store transaction was included. */
-    blockHash: string;
-}) | (BatchUploadResultBase & {
-    kind: "preimage";
-    success: true;
-    /** Hex key returned by the host preimage API. */
-    preimageKey: string;
-}) | (BatchUploadResultBase & {
-    kind: "transaction" | "preimage";
-    success: false;
-    /** Error message describing the failure. */
-    error: string;
-});
-/** Options for {@link batchUpload}. */
-interface BatchUploadOptions extends UploadOptions {
-    /** Called after each item completes (success or failure). */
-    onProgress?: (completed: number, total: number, current: BatchUploadResult) => void;
-}
 /**
  * Authorization status for a Bulletin Chain account.
  *
- * Returned by {@link checkAuthorization} to enable pre-flight checks before
- * uploading. Consumers can use this to show "not authorized" or "insufficient
- * quota" messages instead of letting the transaction fail.
+ * Returned by {@link checkAuthorization} as a pre-flight check before storing
+ * data. Consumers can use this to show "not authorized" or "insufficient quota"
+ * messages instead of letting the transaction fail mid-execution.
  */
 interface AuthorizationStatus {
     /** Whether an authorization entry exists for this account. */
@@ -200,104 +58,220 @@ interface AuthorizationStatus {
     /** Block number when the authorization expires. 0 if not authorized. */
     expiration: number;
 }
-/** Options for gateway fetch operations. */
-interface FetchOptions {
-    /** Timeout in ms. Default: 30_000. */
-    timeoutMs?: number;
-}
-/** Options for query operations that support host lookup auto-resolution. */
-interface QueryOptions extends FetchOptions {
+/**
+ * Options for {@link BulletinClient.fetchBytes} / {@link BulletinClient.fetchJson}.
+ */
+interface QueryOptions {
     /**
-     * Timeout for the host preimage lookup subscription in ms.
-     * Only applies when the query resolves through the host path.
-     * Default: 30_000.
+     * Timeout for the host preimage lookup subscription, in ms.
+     * Default: 30_000. Applied per lookup — for chunked content (DAG-PB
+     * manifest CIDs), the manifest fetch and each child chunk fetch
+     * each get this budget.
      */
     lookupTimeoutMs?: number;
+    /**
+     * When `true`, return the raw bytes for the requested CID without
+     * parsing or recursing into a DAG-PB manifest. Default: `false` — the
+     * client transparently reassembles chunked content so callers don't
+     * need to know whether a CID points at a single chunk or a manifest.
+     *
+     * Set this if you want to inspect the manifest itself, e.g., to read
+     * `unixfs.fileSize()` ahead of fetching, or to drive your own chunk
+     * pipeline.
+     */
+    noReassemble?: boolean;
 }
 
+/** A single matched entry from `TransactionStorage.Transactions`. */
+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;
+}
 /**
- * Ergonomic entry point for Bulletin Chain operations.
+ * Verification options for {@link verifyOnChain}.
+ */
+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.
  *
- * Bundles a typed Bulletin API (from chain-client) and an IPFS gateway URL
- * so callers don't need to re-pass them on every call.
+ * 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.
  *
- * Both upload and query paths use the host container APIs:
- * - **Uploads** — the host preimage API signs and submits automatically.
- * - **Queries** (`fetchBytes`/`fetchJson`) — uses host preimage lookup with caching.
+ * @param api     - Typed bulletin API.
+ * @param cid     - CIDv1 string to look up.
+ * @param options - Verification target (block number, optional index).
  *
  * @example
  * ```ts
- * const bulletin = await BulletinClient.create("paseo");
- * const result = await bulletin.upload(fileBytes);
- * const metadata = await bulletin.fetchJson<Metadata>(result.cid);
+ * 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?");
+ * }
+ * ```
+ */
+declare function verifyOnChain(api: BulletinApi, cid: string, options: VerifyOnChainOptions): Promise<ChainStoredEntry | null>;
+
+/**
+ * Options for {@link BulletinClient.create}.
+ *
+ * One of two construction shapes is supported:
+ *
+ * - **Environment shorthand** — pass an `environment` string keyed by
+ *   {@link BulletinChain}. Wires up the chain-client automatically.
+ * - **Explicit network** — pass `genesisHash` and `descriptor` directly
+ *   (e.g., spread from a {@link BulletinChain} entry, or supply custom
+ *   values for a private chain).
+ */
+type CreateBulletinClientOptions = (CreateBulletinClientCommon & {
+    environment: BulletinEnvironment;
+}) | (CreateBulletinClientCommon & {
+    genesisHash: `0x${string}`;
+    descriptor: (typeof BulletinChain)[BulletinEnvironment]["descriptor"];
+});
+interface CreateBulletinClientCommon {
+    /** Signer for transaction submission. Required — every store needs a signer. */
+    signer: PolkadotSigner;
+    /** Optional config forwarded to {@link AsyncBulletinClient}. */
+    config?: Partial<ClientConfig>;
+}
+/**
+ * Ergonomic entry point for Bulletin Chain operations.
+ *
+ * Wraps {@link AsyncBulletinClient} from `@parity/bulletin-sdk` (which handles
+ * chunking, DAG-PB manifests, CID calculation, and progress events) and adds:
+ *
+ * - **Network presets** via {@link BulletinClient.create} and {@link BulletinChain}.
+ * - **Read helpers** ({@link fetchBytes}, {@link fetchJson}) routed through
+ *   the host's preimage subscription — upstream is upload-only and the SDK
+ *   is container-only by design (no public-gateway fetches).
+ * - **Pre-flight authorization check** ({@link checkAuthorization}) for
+ *   friendlier UX before submitting a store.
+ *
+ * For uploads, mirror upstream's fluent builders:
+ *
+ * ```ts
+ * const client = await BulletinClient.create({ environment: "paseo", signer });
+ * const result = await client.store(data).send();
+ * ```
+ *
+ * For chunked uploads with progress:
+ *
+ * ```ts
+ * const result = await client
+ *   .store(largeFile)
+ *   .withChunkSize(1 << 20)
+ *   .withCallback((evt) => console.log(evt))
+ *   .send();
  * ```
  */
 declare class BulletinClient {
+    /** Underlying upstream client — exposed for power users. */
+    readonly inner: AsyncBulletinClient;
+    /** Typed Bulletin Chain API. */
     readonly api: BulletinApi;
-    readonly gateway: string;
+    /** Lazy-resolved host-preimage query strategy, cached for the client lifetime. */
     private queryStrategyPromise;
+    /** Constructed via {@link create} or {@link from}. */
     private constructor();
-    /** Lazily resolve and cache the query strategy for the client lifetime. */
+    /** Resolve and cache the host query strategy on first use. */
     private resolveQuery;
-    /** Create from an environment — resolves API via chain-client, gateway from known list. */
-    static create(env: Environment): Promise<BulletinClient>;
-    /** Create from an explicit API and gateway (custom setups, testing). */
-    static from(api: BulletinApi, gateway: string): BulletinClient;
-    /** Compute CID without uploading. Static — no instance needed. */
-    static computeCid(data: Uint8Array): string;
     /**
-     * Reconstruct a CID from a `0x`-prefixed hex hash. Static — no instance needed.
+     * Create a client from an environment shorthand or an explicit network.
      *
-     * Useful for converting on-chain hashes back to CIDs for IPFS gateway lookups.
-     * Pass optional hash algorithm and codec to match the on-chain CID configuration.
+     * Environment form uses our `getChainAPI(env)` to resolve the typed API.
+     * Explicit form skips the environment lookup and lets you pass any
+     * genesis/descriptor combo.
      *
-     * @see {@link hashToCid} for full documentation.
-     */
-    static hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
-    /**
-     * Upload data to the Bulletin Chain.
+     * @example
+     * ```ts
+     * // Shorthand
+     * const client = await BulletinClient.create({ environment: "paseo", signer });
      *
-     * @param data   - Raw bytes to store.
-     * @param signer - Optional signer. When omitted, uses the host preimage API.
-     * @param options - Upload options (timeout, waitFor, status callback).
+     * // Explicit (custom network)
+     * const client = await BulletinClient.create({
+     *   ...BulletinChain.paseo,
+     *   signer,
+     *   config: { defaultChunkSize: 1 << 20 },
+     * });
+     * ```
      */
-    upload(data: Uint8Array, signer?: PolkadotSigner, options?: Omit<UploadOptions, "gateway">): Promise<UploadResult>;
+    static create(options: CreateBulletinClientOptions): Promise<BulletinClient>;
     /**
-     * Upload multiple items sequentially.
+     * Construct from a pre-built `AsyncBulletinClient` and PAPI typed API.
      *
-     * @param items  - Array of items to upload, each with data and a label.
-     * @param signer - Optional signer. When omitted, auto-resolved.
-     * @param options - Batch upload options (timeout, progress callback).
+     * Use this when you already own the connection lifecycle (BYOD setups,
+     * tests). The caller is responsible for calling `papiClient.destroy()`
+     * — this client's {@link destroy} only tears down the upstream's
+     * `onDestroy` hook.
      */
-    batchUpload(items: BatchUploadItem[], signer?: PolkadotSigner, options?: Omit<BatchUploadOptions, "gateway">): Promise<BatchUploadResult[]>;
+    static from(inner: AsyncBulletinClient, api: BulletinApi): BulletinClient;
+    /** Build a store transaction. See upstream `StoreBuilder` for chained options. */
+    store(data: Uint8Array): StoreBuilder;
+    /** Authorize an account to store data on the chain (sudo required on most networks). */
+    authorizeAccount(who: string, transactions: number, bytes: bigint): AuthCallBuilder;
+    /** Authorize content storage by hash (anyone can store; no fees). */
+    authorizePreimage(contentHash: Uint8Array, maxSize: bigint): AuthCallBuilder;
+    /** Renew a stored transaction by block + index. */
+    renew(block: number, index: number): CallBuilder;
+    /** Estimate the authorization (transactions + bytes) needed for `dataSize`. */
+    estimateAuthorization(dataSize: number): {
+        transactions: number;
+        bytes: number;
+    };
     /**
-     * Fetch raw bytes by CID.
+     * Fetch raw bytes for a CID via the host's preimage lookup.
      *
-     * Uses host preimage lookup with caching.
-     */
-    fetchBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
-    /**
-     * Fetch and parse JSON by CID.
+     * Container-only — outside a Polkadot Browser / Desktop host this
+     * throws {@link BulletinHostUnavailableError}. The chain stores
+     * content metadata (`content_hash`, size, codec) but the bytes
+     * themselves are surfaced through the host's preimage subscription.
      *
-     * Auto-resolves query path (same as {@link fetchBytes}).
+     * Use {@link verifyOnChain} if you only need to confirm a CID was
+     * recorded on-chain (no byte fetch).
      */
+    fetchBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
+    /** Fetch and parse JSON for a CID. */
     fetchJson<T>(cid: string, options?: QueryOptions): Promise<T>;
-    /** Check if a CID exists on the gateway. */
-    cidExists(cid: string): Promise<boolean>;
-    /** Build the full gateway URL for a CID. */
-    gatewayUrl(cid: string): string;
+    /** Pre-flight: check whether `address` can store on the bulletin chain. */
+    checkAuthorization(address: string): Promise<AuthorizationStatus>;
     /**
-     * Check whether an account is authorized to store data on the Bulletin Chain.
-     *
-     * Use as a pre-flight check before {@link upload} to provide clear UX
-     * instead of letting the transaction fail mid-execution.
+     * Verify that a CID was recorded on-chain at the given block.
      *
-     * @param address - SS58-encoded account address to check.
-     * @returns Authorization status with remaining quota.
-     *
-     * @see {@link checkAuthorization} for the standalone function equivalent.
+     * Common pattern: pass `blockNumber` (and optionally `extrinsicIndex`)
+     * from a `store(...).send()` receipt to confirm the upload landed.
+     * See {@link verifyOnChain} for details.
      */
-    checkAuthorization(address: string): Promise<AuthorizationStatus>;
+    verifyOnChain(cid: string, options: VerifyOnChainOptions): Promise<ChainStoredEntry | null>;
+    /** Tear down the underlying connection. */
+    destroy(): Promise<void>;
 }
 
 /**
@@ -331,122 +305,108 @@ declare class BulletinClient {
  * @see {@link BulletinClient.checkAuthorization} for the client method equivalent.
  */
 declare function checkAuthorization(api: BulletinApi, address: string): Promise<AuthorizationStatus>;
-
 /**
- * Base class for all Bulletin Chain errors.
- *
- * Use `instanceof BulletinError` to catch any bulletin-related error.
- *
- * @example
- * ```ts
- * try {
- *   await bulletin.upload(data);
- * } catch (e) {
- *   if (e instanceof BulletinError) {
- *     console.error("Bulletin operation failed:", e.message);
- *   }
- * }
- * ```
+ * Options for {@link authorizeAccount}.
  */
-declare class BulletinError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-/**
- * The host preimage API is unavailable.
- *
- * Thrown when bulletin operations require the host container but it's not available.
- * This typically means the SDK is running outside of Polkadot Browser/Desktop.
- */
-declare class BulletinHostUnavailableError extends BulletinError {
-    constructor(operation: "upload" | "query");
+interface AuthorizeAccountOptions {
+    /**
+     * Wrap the extrinsic in `Sudo.sudo(...)` before submission. Default: `false`.
+     *
+     * Use `true` on networks where granting bulletin storage authorization
+     * requires sudo permissions (most production / managed test networks).
+     * Use `false` (default) when the account self-authorizes — typical for
+     * local development chains.
+     */
+    viaSudo?: boolean;
+    /** When to resolve: `"best-block"` (default) or `"finalized"`. */
+    waitFor?: WaitFor;
+    /** Timeout in ms. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Lifecycle status callback for UI progress. */
+    onStatus?: (status: TxStatus) => void;
 }
 /**
- * The host preimage lookup timed out.
+ * Grant an account authorization to store data on the Bulletin Chain.
+ *
+ * Submits a `TransactionStorage.authorize_account` extrinsic, optionally
+ * wrapped in `Sudo.sudo(...)` for networks that require sudo to grant
+ * authorization. Mirrors the call shape of {@link upload} — top-level
+ * function, takes an explicit signer, returns a block hash on success.
+ *
+ * Pair with {@link checkAuthorization} for a typical "check, grant if
+ * insufficient, then upload" flow.
+ *
+ * ## Additive semantics — call once per authorization need
+ *
+ * `authorize_account` is **additive** within an unexpired authorization window
+ * for `AuthorizationScope::Account` (see `pallet-bulletin-transaction-storage`,
+ * `fn authorize`). Each successful call **adds** to the existing
+ * `transactions_allowance` and `bytes_allowance` rather than overwriting them.
+ *
+ * Implications for callers:
+ *
+ * - Calling this function twice with `(100, 1MB)` while the previous
+ *   authorization is still active leaves the account with quota for `200`
+ *   transactions and `2MB` — likely unintended.
+ * - **This function does NOT use `withRetry`.** Retrying a successful-but-
+ *   acknowledgment-lost submission would double-grant the quota. Callers
+ *   needing retry should wrap this function and use {@link checkAuthorization}
+ *   to verify the post-state before retrying.
+ * - To "reset" a quota, let the existing authorization expire
+ *   (`AuthorizationPeriod` blocks). The next call after expiry creates a fresh
+ *   authorization rather than adding.
+ *
+ * Note: `AuthorizationScope::Preimage` uses `set` semantics in the same
+ * pallet. This helper is for account-scope authorization only.
+ *
+ * @param api          - Typed Bulletin Chain API instance.
+ * @param who          - SS58-encoded account to authorize.
+ * @param transactions - Number of transactions to **add** to the account's allowance.
+ * @param bytes        - Byte budget to **add** to the account's allowance.
+ * @param signer       - Signer for the extrinsic. On `viaSudo: true` this must be the sudo key.
+ * @param options      - Optional `viaSudo` flag plus standard submission controls.
+ * @returns Block hash where the extrinsic was included.
+ * @throws {ProductBulletinError} If `viaSudo: true` is requested but the chain has no `Sudo` pallet.
+ *
+ * @example Direct (account self-authorizes — local dev)
+ * ```ts
+ * import { authorizeAccount } from "@parity/product-sdk-bulletin";
  *
- * The host was unable to retrieve the requested content within the timeout period.
- * The content may still become available later.
- */
-declare class BulletinLookupTimeoutError extends BulletinError {
-    /** The CID that was being looked up. */
-    readonly cid: string;
-    /** The timeout duration in milliseconds. */
-    readonly timeoutMs: number;
-    constructor(cid: string, timeoutMs: number);
-}
-/**
- * The host interrupted the preimage lookup.
+ * await authorizeAccount(api, address, 100, 100n * 1024n * 1024n, signer);
+ * ```
  *
- * The host terminated the lookup subscription, typically after repeated failures
- * or when the host determines the content is unavailable.
- */
-declare class BulletinLookupInterruptedError extends BulletinError {
-    /** The CID that was being looked up. */
-    readonly cid: string;
-    constructor(cid: string);
-}
-/**
- * Failed to check authorization status for an account.
+ * @example Sudo-wrapped (managed test network)
+ * ```ts
+ * await authorizeAccount(api, userAddress, 100, 1_000_000n, sudoSigner, {
+ *     viaSudo: true,
+ * });
+ * ```
  *
- * Wraps RPC or query errors that occur when checking if an account
- * is authorized to store data on the Bulletin Chain.
+ * @see {@link checkAuthorization} for the read counterpart.
+ * @see {@link BulletinClient.authorizeAccount} for the client method equivalent.
  */
-declare class BulletinAuthorizationError extends BulletinError {
-    /** The address that was being checked. */
-    readonly address: string;
-    constructor(address: string, cause?: unknown);
-}
+declare function authorizeAccount(api: BulletinApi, who: string, transactions: number, bytes: bigint, signer: PolkadotSigner, options?: AuthorizeAccountOptions): Promise<{
+    blockHash: string;
+}>;
+
 /**
- * The IPFS gateway for the specified environment is not available.
+ * Build a `PolkadotSigner` whose underlying signer is resolved on every call.
  *
- * Thrown when attempting to use gateway features for a network that
- * doesn't have a live bulletin gateway yet.
- */
-declare class BulletinGatewayUnavailableError extends BulletinError {
-    /** The environment that was requested. */
-    readonly environment: string;
-    constructor(environment: string);
-}
-/**
- * An IPFS gateway request failed.
+ * `AsyncBulletinClient` takes a fixed `PolkadotSigner` at construction, but
+ * apps often build the bulletin client before any account is selected. This
+ * wrapper defers signer resolution: each call to `signTx` / `signBytes`
+ * invokes `getSigner()` and forwards to the result. If the getter returns
+ * `null`, calls throw with a clear message.
  *
- * Thrown when a fetch to the IPFS gateway returns a non-OK response.
- */
-declare class BulletinGatewayFetchError extends BulletinError {
-    /** The CID that was being fetched. */
-    readonly cid: string;
-    /** The HTTP status code returned by the gateway. */
-    readonly status: number;
-    /** The HTTP status text returned by the gateway. */
-    readonly statusText: string;
-    constructor(cid: string, status: number, statusText: string);
-}
-/**
- * Invalid CID format or version.
+ * The `publicKey` field is *also* resolved lazily — accessing it before a
+ * signer is available throws. This means callers that read `publicKey`
+ * eagerly will fail fast with the same error rather than seeing a stale
+ * key from a previously-selected account.
  *
- * Thrown when a CID string cannot be parsed or has an unexpected version/codec.
+ * Account changes between calls are picked up automatically: each sign
+ * resolves the current signer.
  */
-declare class BulletinCidError extends BulletinError {
-    /** The invalid CID string, if available. */
-    readonly cid?: string;
-    constructor(message: string, cid?: string);
-}
-
-/**
- * Get the IPFS gateway URL for an environment.
- * @throws {BulletinGatewayUnavailableError} If the network doesn't have a live gateway yet.
- */
-declare function getGateway(env: Environment): string;
-/** Build the full gateway URL for a CID. */
-declare function gatewayUrl(cid: string, gateway: string): string;
-/** Check if a CID exists on the gateway (HEAD request). Returns false on any error or timeout. */
-declare function cidExists(cid: string, gateway: string, options?: FetchOptions): Promise<boolean>;
-/**
- * Fetch raw bytes from the gateway.
- * @throws {BulletinGatewayFetchError} If the gateway returns a non-OK response.
- */
-declare function fetchBytes(cid: string, gateway: string, options?: FetchOptions): Promise<Uint8Array>;
-/** Fetch and parse JSON from the gateway. */
-declare function fetchJson<T>(cid: string, gateway: string, options?: FetchOptions): Promise<T>;
+declare function createLazySigner(getSigner: () => PolkadotSigner | null, onMissing?: string): PolkadotSigner;
 
 /**
  * Query strategy for the Bulletin Chain.
@@ -470,86 +430,175 @@ interface QueryStrategy {
 declare function resolveQueryStrategy(): Promise<QueryStrategy>;
 
 /**
- * Fetch raw bytes for a CID using the host preimage lookup.
+ * Fetch raw bytes for a CID via the host's preimage lookup.
+ *
+ * Container-only by design: the bulletin SDK does not retrieve content
+ * through public IPFS gateways. Inside a Polkadot Browser / Desktop
+ * container, the host's `preimageManager` provides a cached, polling-
+ * managed lookup that returns bytes when the underlying IPFS network
+ * makes them available. Outside a container, this throws
+ * {@link BulletinHostUnavailableError}.
  *
- * Uses local cache + managed IPFS polling via the host container.
+ * The bulletin chain stores transaction *metadata* on-chain
+ * (`chunk_root`, `content_hash`, `size`, `cid_codec`, `hashing`) — the
+ * content bytes themselves live in IPFS and are surfaced through the
+ * host's preimage subscription, never via direct gateway fetch.
+ *
+ * To prove that a CID was stored on-chain (without fetching the bytes),
+ * use `verifyOnChain` from `verify.ts`.
  *
  * @param cid     - CIDv1 string to fetch.
- * @param options - Query options (lookupTimeoutMs for host).
- * @returns Raw bytes of the content.
- * @throws {Error} If the host preimage API is unavailable.
+ * @param options - Query options (`lookupTimeoutMs` for host).
+ * @throws {BulletinHostUnavailableError} If running outside a container.
  */
 declare function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
 /**
- * Fetch and parse JSON for a CID, auto-resolving the query path.
- *
- * Delegates to {@link queryBytes} and parses the result as JSON.
+ * Fetch and parse JSON for a CID via the host's preimage lookup.
  *
- * @param cid     - CIDv1 string to fetch.
- * @param options - Query options.
- * @returns Parsed JSON value.
- * @throws {Error} If the host preimage API is unavailable.
+ * Convenience wrapper over {@link queryBytes}.
  */
 declare function queryJson<T>(cid: string, options?: QueryOptions): Promise<T>;
+/**
+ * Execute a query using a pre-resolved strategy.
+ *
+ * Exposed so `BulletinClient` can resolve the strategy once at
+ * construction time and reuse it across calls without re-detecting
+ * the host environment on every fetch.
+ *
+ * **Reassembly is automatic.** If `cid` carries the DAG-PB codec
+ * (`0x70`) — meaning the upload was chunked and a UnixFS manifest was
+ * created — this function recursively fetches each chunk via `strategy
+ * .lookup` and returns the concatenated bytes. Pass `noReassemble: true`
+ * to get the raw manifest bytes instead.
+ *
+ * For raw-codec CIDs (`0x55`, single-chunk content), the bytes returned
+ * by the host are returned directly — no parsing overhead.
+ */
+declare function executeQuery(strategy: QueryStrategy, cid: string, options?: QueryOptions): Promise<Uint8Array>;
 
 /**
- * Discriminated union describing how data will be uploaded to the Bulletin Chain.
+ * Hash algorithms supported by 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.
+ * Values are multihash codes from the multicodec table.
  */
-type UploadStrategy = {
-    kind: "preimage";
-    submit: (data: Uint8Array) => Promise<string>;
-} | {
-    kind: "signer";
-    signer: PolkadotSigner;
+declare const HashAlgorithm: {
+    /** BLAKE2b-256 — chain default. */
+    readonly Blake2b256: 45600;
+    /** SHA2-256. */
+    readonly Sha2_256: 18;
+    /** Keccak-256 — Ethereum compatibility. */
+    readonly Keccak256: 27;
+};
+type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
+/**
+ * CID codecs supported by the Bulletin Chain.
+ */
+declare const CidCodec: {
+    /** Raw binary — default for single-chunk data. */
+    readonly Raw: 85;
+    /** DAG-PB — used for multi-chunk manifests / IPFS UnixFS. */
+    readonly DagPb: 112;
+    /** DAG-CBOR — alternative DAG encoding. */
+    readonly DagCbor: 113;
 };
+type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
 /**
- * Determine the upload strategy for the Bulletin Chain.
+ * Reconstruct a CIDv1 from a `0x`-prefixed 32-byte hex hash.
  *
- * 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).
+ * Useful when reading on-chain `TransactionInfo.content_hash` and you need
+ * the CID to look up content via an IPFS gateway.
  *
- * @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.
+ * @param hexHash  - 66-char `0x`-prefixed hex of a 32-byte digest.
+ * @param hashCode - Multihash code (default: blake2b-256).
+ * @param codec    - Multicodec code (default: raw).
  */
-declare function resolveUploadStrategy(explicitSigner?: PolkadotSigner): Promise<UploadStrategy>;
+declare function hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
+/**
+ * Extract the 32-byte content hash digest from a CIDv1 and return it as a
+ * `0x`-prefixed hex string.
+ *
+ * Useful for matching a CID against on-chain `TransactionInfo.content_hash`.
+ */
+declare function cidToPreimageKey(cid: string): `0x${string}`;
 
 /**
- * Upload data to the Bulletin Chain.
+ * Bulletin error types.
  *
- * When a signer is provided, submits a `TransactionStorage.store` transaction
- * directly. When omitted, uses the host preimage API — the host signs and
- * submits automatically.
+ * Two error families coexist:
  *
- * Computes the CIDv1 (blake2b-256, raw codec) locally.
+ * 1. **Upstream SDK errors** — `BulletinError` and `ErrorCode` from
+ *    `@parity/bulletin-sdk` cover upload/store/authorization failures
+ *    surfaced by `AsyncBulletinClient`. Each carries `code`, `retryable`,
+ *    and `recoveryHint`.
+ * 2. **Read-side errors** declared here — host preimage availability /
+ *    lookup timeouts / interrupts, plus CID format problems, surfaced by
+ *    our retrieval helpers (`fetchBytes`, `fetchJson`, `verifyOnChain`).
  *
- * @param api    - Typed Bulletin Chain API.
- * @param data   - Raw bytes to store.
- * @param signer - Optional signer. When omitted, uses host preimage API.
- * @param options - Upload options (gateway, timeout, waitFor, status callback).
- * @returns Upload result with CID and either blockHash or preimageKey.
+ * Catch upstream errors with `instanceof BulletinError`. Catch our read-side
+ * errors with `instanceof ProductBulletinError` (or the specific subclass).
  */
-declare function upload(api: BulletinApi, data: Uint8Array, signer?: PolkadotSigner, options?: UploadOptions): Promise<UploadResult>;
+
 /**
- * Upload multiple items sequentially to the Bulletin Chain.
+ * Base class for read-side errors raised by `@parity/product-sdk-bulletin`.
  *
- * Bulletin Chain requires sequential transaction submission (nonce ordering).
- * Individual failures are captured in results — the batch does not abort.
+ * Distinct from upstream `BulletinError` which covers upload/store failures.
+ */
+declare class ProductBulletinError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The host preimage API is unavailable.
  *
- * Signer resolution follows the same rules as {@link upload}: when omitted,
- * the strategy is auto-resolved once and reused for all items.
+ * Thrown when bulletin operations require the host container but it's not
+ * available. This typically means the SDK is running outside Polkadot
+ * Browser / Desktop. The bulletin SDK is container-only by design — see
+ * the README for the rationale.
+ */
+declare class BulletinHostUnavailableError extends ProductBulletinError {
+    constructor(operation: "upload" | "query");
+}
+/**
+ * The host preimage lookup timed out.
  *
- * @param api    - Typed Bulletin Chain API.
- * @param items  - Array of items to upload, each with data and a label.
- * @param signer - Optional signer. When omitted, auto-resolved.
- * @param options - Batch upload options (gateway, timeout, progress callback).
- * @returns Array of results, one per item, preserving input order.
+ * The host was unable to retrieve the requested content within the timeout
+ * period. The content may still become available later.
  */
-declare function batchUpload(api: BulletinApi, items: BatchUploadItem[], signer?: PolkadotSigner, options?: BatchUploadOptions): Promise<BatchUploadResult[]>;
+declare class BulletinLookupTimeoutError extends ProductBulletinError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    /** The timeout duration in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(cid: string, timeoutMs: number);
+}
+/**
+ * The host interrupted the preimage lookup.
+ *
+ * The host terminated the lookup subscription, typically after repeated
+ * failures or when the host determines the content is unavailable.
+ */
+declare class BulletinLookupInterruptedError extends ProductBulletinError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    constructor(cid: string);
+}
+/**
+ * Invalid CID format or version.
+ */
+declare class BulletinCidError extends ProductBulletinError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+    constructor(message: string, cid?: string);
+}
+/**
+ * Failed to check authorization status for an account.
+ *
+ * Wraps RPC or query errors that occur when checking if an account
+ * is authorized to store data on the Bulletin Chain.
+ */
+declare class BulletinAuthorizationError extends ProductBulletinError {
+    /** The address that was being checked. */
+    readonly address: string;
+    constructor(address: string, cause?: unknown);
+}
 
-export { type AuthorizationStatus, type BatchUploadItem, type BatchUploadOptions, type BatchUploadResult, type BulletinApi, BulletinAuthorizationError, BulletinCidError, BulletinClient, BulletinError, BulletinGatewayFetchError, BulletinGatewayUnavailableError, BulletinHostUnavailableError, BulletinLookupInterruptedError, BulletinLookupTimeoutError, CidCodec, type FetchOptions, HashAlgorithm, type QueryOptions, type QueryStrategy, type UploadOptions, type UploadResult, type UploadStrategy, batchUpload, checkAuthorization, cidExists, cidToPreimageKey, computeCid, fetchBytes, fetchJson, gatewayUrl, getGateway, hashToCid, queryBytes, queryJson, resolveQueryStrategy, resolveUploadStrategy, upload };
+export { type AuthorizationStatus, type AuthorizeAccountOptions, type BulletinApi, BulletinAuthorizationError, BulletinChain, BulletinCidError, BulletinClient, type BulletinEnvironment, BulletinHostUnavailableError, BulletinLookupInterruptedError, BulletinLookupTimeoutError, type BulletinNetwork, type ChainStoredEntry, CidCodec, type CreateBulletinClientOptions, HashAlgorithm, ProductBulletinError, type QueryOptions, type QueryStrategy, type VerifyOnChainOptions, authorizeAccount, checkAuthorization, cidToPreimageKey, createLazySigner, executeQuery, hashToCid, queryBytes, queryJson, resolveQueryStrategy, verifyOnChain };