@polkadot-apps/bulletin

TypeScript SDK for uploading and retrieving data on the Bulletin Chain — a Polkadot system parachain designed for on-chain data storage with IPFS-compatible content addressing.

Install

npm install @polkadot-apps/bulletin
# or
pnpm add @polkadot-apps/bulletin
Copy

Peer dependencies

• polkadot-api (required)
• @novasamatech/product-sdk (optional — needed only when running inside a host container like Polkadot Desktop or the Polkadot mobile app)

Quick start

import { BulletinClient } from "@polkadot-apps/bulletin";

const bulletin = await BulletinClient.create("paseo");

// Upload — signer is auto-resolved (see "Signer resolution" below)
const result = await bulletin.upload(new TextEncoder().encode("hello world"));
console.log(result.cid); // CIDv1 string

// Read back
const data = await bulletin.fetchBytes(result.cid);
Copy

Signer resolution

When no signer is passed to upload() or batchUpload(), the SDK auto-detects the environment and picks the best strategy:

You can always pass an explicit signer to override auto-resolution:

import { createDevSigner } from "@polkadot-apps/tx";

const alice = createDevSigner("Alice");
const result = await bulletin.upload(data, alice);
Copy

Query resolution

When fetching data with fetchBytes(), fetchJson(), or their standalone equivalents (queryBytes, queryJson), the SDK auto-detects the environment:

The query path is transparent — bulletin.fetchBytes(cid) works identically in both environments, but benefits from host-managed caching when available.

API

BulletinClient

High-level client that bundles a typed Bulletin API and an IPFS gateway URL.

BulletinClient.create(env)

Create a client for an environment. Resolves the chain connection and gateway automatically.

const bulletin = await BulletinClient.create("paseo");
Copy

Parameters:

• env — "paseo" | "polkadot" | "kusama"

BulletinClient.from(api, gateway)

Create a client from an explicit API instance and gateway URL. Useful for custom setups and testing.

import { bulletin as bulletinDescriptor } from "@polkadot-apps/descriptors/bulletin";

const api = client.getTypedApi(bulletinDescriptor);
const bulletin = BulletinClient.from(api, "https://paseo-ipfs.polkadot.io/ipfs/");
Copy

bulletin.upload(data, signer?, options?)

Upload data to the Bulletin Chain. Returns a discriminated union — use result.kind to determine the upload path.

const result = await bulletin.upload(fileBytes);

if (result.kind === "transaction") {
    console.log("Block hash:", result.blockHash);
} else {
    console.log("Preimage key:", result.preimageKey);
}
console.log("CID:", result.cid);
console.log("Gateway URL:", result.gatewayUrl);
Copy

Parameters:

• data — Uint8Array of raw bytes to store
• signer — optional PolkadotSigner; auto-resolved when omitted
• options — optional UploadOptions:
  • waitFor — "best-block" (default) or "finalized"
  • timeoutMs — timeout in ms (default: 300,000)
  • onStatus — lifecycle callback for UI progress

bulletin.batchUpload(items, signer?, options?)

Upload multiple items sequentially. The Bulletin Chain requires sequential submission for nonce ordering. Individual failures are captured per-item — the batch does not abort.

const items = [
    { data: new TextEncoder().encode("doc-1"), label: "document-1" },
    { data: new TextEncoder().encode("doc-2"), label: "document-2" },
];

const results = await bulletin.batchUpload(items, undefined, {
    onProgress: (completed, total, current) => {
        console.log(`${completed}/${total}: ${current.label} — ${current.success ? "ok" : current.error}`);
    },
});
Copy

Parameters:

• items — array of { data: Uint8Array, label: string }
• signer — optional PolkadotSigner; auto-resolved when omitted
• options — optional BatchUploadOptions (extends UploadOptions):
  • onProgress(completed, total, current) — called after each item

bulletin.fetchBytes(cid, options?)

Fetch raw bytes by CID. Auto-resolves the query path (see "Query resolution" above).

const bytes = await bulletin.fetchBytes("bafk...");

// With host lookup timeout override:
const bytes2 = await bulletin.fetchBytes("bafk...", { lookupTimeoutMs: 10_000 });
Copy

Parameters:

• cid — CIDv1 string
• options — optional QueryOptions:
  • timeoutMs — timeout for gateway fetch in ms (default: 30,000)
  • lookupTimeoutMs — timeout for host preimage lookup in ms (default: 30,000; host path only)

bulletin.fetchJson<T>(cid, options?)

Fetch and parse JSON by CID. Auto-resolves the query path (same as fetchBytes).

const metadata = await bulletin.fetchJson<{ name: string }>("bafk...");
Copy

bulletin.checkAuthorization(address)

Check whether an account is authorized to store data. Use as a pre-flight check before upload() to show "not authorized" or "insufficient quota" instead of letting the transaction fail.

const auth = await bulletin.checkAuthorization(myAddress);
if (!auth.authorized) {
    console.error("Account is not authorized for bulletin storage");
} else if (auth.remainingBytes < BigInt(fileBytes.length)) {
    console.error(`Insufficient quota: ${auth.remainingBytes} bytes remaining`);
}
Copy

Parameters:

• address — SS58-encoded account address

Returns: AuthorizationStatus with authorized, remainingTransactions, remainingBytes, expiration.

bulletin.cidExists(cid)

Check if a CID exists on the gateway (HEAD request). Returns false on any error or timeout.

bulletin.gatewayUrl(cid)

Build the full gateway URL for a CID.

BulletinClient.computeCid(data)

Compute the CID for data without uploading. Static method — no client instance needed.

const cid = BulletinClient.computeCid(new TextEncoder().encode("hello"));
Copy

BulletinClient.hashToCid(hexHash, hashCode?, codec?)

Reconstruct a CID from a 0x-prefixed hex hash stored on-chain. Static method — no client instance needed. Supports all hash algorithms and codecs used by the Bulletin Chain.

import { HashAlgorithm, CidCodec } from "@polkadot-apps/bulletin";

// Default (blake2b-256, raw)
const cid = BulletinClient.hashToCid("0x1a2b3c...");

// SHA2-256 content from bulletin-deploy
const cid2 = BulletinClient.hashToCid("0x1a2b3c...", HashAlgorithm.Sha2_256);

const url = bulletin.gatewayUrl(cid);
Copy

Standalone functions

The same operations are available as standalone functions for lower-level usage:

import {
    upload, batchUpload, checkAuthorization,
    computeCid, cidToPreimageKey, hashToCid,
    HashAlgorithm, CidCodec,
    fetchBytes, fetchJson, cidExists,
    queryBytes, queryJson, resolveQueryStrategy,
    getGateway, gatewayUrl,
} from "@polkadot-apps/bulletin";
Copy

upload(api, data, signer?, options?)

Upload data using an explicit BulletinApi instance.

batchUpload(api, items, signer?, options?)

Batch upload using an explicit BulletinApi instance.

checkAuthorization(api, address)

Check whether an account is authorized to store data. Standalone equivalent of bulletin.checkAuthorization().

import { checkAuthorization } from "@polkadot-apps/bulletin";

const auth = await checkAuthorization(api, address);
Copy

computeCid(data)

Compute a CIDv1 (blake2b-256, raw codec) for arbitrary bytes. Deterministic — same input always produces the same CID.

getGateway(env)

Get the IPFS gateway URL for an environment.

resolveUploadStrategy(signer?)

Resolve which upload strategy will be used. Returns a discriminated union:

import { resolveUploadStrategy } from "@polkadot-apps/bulletin";

const strategy = await resolveUploadStrategy();
console.log(strategy.kind); // "preimage" or "signer"
Copy

queryBytes(cid, gateway, options?)

Fetch raw bytes with auto-resolved query strategy. Equivalent to BulletinClient.fetchBytes but as a standalone function requiring an explicit gateway URL.

queryJson<T>(cid, gateway, options?)

Fetch and parse JSON with auto-resolved query strategy.

cidToPreimageKey(cid)

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 any hash algorithm supported by the Bulletin Chain (blake2b-256, sha2-256, keccak-256).

import { computeCid, cidToPreimageKey } from "@polkadot-apps/bulletin";

const cid = computeCid(data);
const key = cidToPreimageKey(cid); // "0x1a2b3c..."
Copy

hashToCid(hexHash, hashCode?, codec?)

Reconstruct a CIDv1 from a 0x-prefixed hex hash — the reverse of cidToPreimageKey. Use this when you have on-chain hashes and need to build 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. Defaults to blake2b-256 + raw (matching computeCid).

import { hashToCid, HashAlgorithm, CidCodec, gatewayUrl, getGateway } from "@polkadot-apps/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"));
Copy

HashAlgorithm

Hash algorithms supported by the Bulletin Chain (multihash codes):

CidCodec

CID codecs supported by the Bulletin Chain (multicodec codes):

resolveQueryStrategy()

Resolve which query strategy will be used. Returns a discriminated union:

import { resolveQueryStrategy } from "@polkadot-apps/bulletin";

const strategy = await resolveQueryStrategy();
console.log(strategy.kind); // "host-lookup" or "gateway"
Copy

Types

AuthorizationStatus

interface AuthorizationStatus {
    authorized: boolean;           // Whether an authorization entry exists
    remainingTransactions: number; // Remaining tx slots (0 if not authorized)
    remainingBytes: bigint;        // Remaining bytes (0n if not authorized)
    expiration: number;            // Expiration block number (0 if not authorized)
}
Copy

UploadResult

Discriminated union on kind:

type UploadResult =
    | { kind: "transaction"; cid: string; blockHash: string; gatewayUrl?: string }
    | { kind: "preimage"; cid: string; preimageKey: string; gatewayUrl?: string };
Copy

BatchUploadResult

Discriminated union on kind and success:

type BatchUploadResult =
    | { kind: "transaction"; success: true; label: string; cid: string; blockHash: string; gatewayUrl?: string }
    | { kind: "preimage"; success: true; label: string; cid: string; preimageKey: string; gatewayUrl?: string }
    | { kind: "transaction" | "preimage"; success: false; label: string; cid: string; error: string; gatewayUrl?: string };
Copy

UploadStrategy

type UploadStrategy =
    | { kind: "preimage"; submit: (data: Uint8Array) => Promise<string> }
    | { kind: "signer"; signer: PolkadotSigner };
Copy

Environment

type Environment = "polkadot" | "kusama" | "paseo";
Copy

QueryStrategy

type QueryStrategy =
    | { kind: "host-lookup"; lookup: (cid: string, timeoutMs?: number) => Promise<Uint8Array> }
    | { kind: "gateway" };
Copy

QueryOptions

interface QueryOptions extends FetchOptions {
    /** Timeout for host preimage lookup in ms (default: 30,000). Host path only. */
    lookupTimeoutMs?: number;
}
Copy

CID format

All CIDs are CIDv1 with:

• Hash function: blake2b-256
• Codec: raw
• Base encoding: base32-lower (starts with b)

This matches the Bulletin Chain's on-chain CID computation, ensuring the locally computed CID always matches what the chain stores.

License

Apache-2.0