polkadot-bulletin

Polkadot Bulletin Chain SDK

@polkadot-apps/bulletin is a TypeScript SDK for uploading and retrieving data on the Polkadot Bulletin Chain -- a purpose-built parachain for decentralized data storage. Data is content-addressed using CIDv1 (blake2b-256 hash, raw codec) and retrievable via IPFS gateways.

Key Concepts

• Content-addressed storage: Data is identified by its CID (Content Identifier), computed deterministically from the bytes via blake2b-256.
• Two upload paths: Inside a host container (Polkadot Desktop/Mobile), uploads go through the host preimage API automatically. Standalone, a PolkadotSigner or dev signer is used to submit a TransactionStorage.store extrinsic.
• Two query paths: Inside a host container, queries use the host preimage lookup (with caching). Standalone, data is fetched directly from an IPFS gateway.
• Environments: "polkadot", "kusama", "paseo" -- currently only "paseo" has a live gateway.

Quick Start: Upload and Fetch

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

// Create a client for the Paseo test network
const bulletin = await BulletinClient.create("paseo");

// Upload data (MUST be Uint8Array, not a string)
const data = new TextEncoder().encode(JSON.stringify({ title: "Hello Bulletin" }));
const result = await bulletin.upload(data);
console.log("CID:", result.cid);

// Fetch it back as JSON
const content = await bulletin.fetchJson<{ title: string }>(result.cid);
console.log(content.title); // "Hello Bulletin"

WARNING: upload() expects Uint8Array, not strings. Always convert with new TextEncoder().encode(...). Passing a string will cause a type error or unexpected behavior.

BulletinClient

The BulletinClient class bundles a typed Bulletin API and IPFS gateway URL so you do not need to pass them on every call. Both upload and query paths auto-resolve based on the runtime environment.

Creating a Client

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

// From an environment name (resolves API via chain-client, gateway from known list)
const client = await BulletinClient.create("paseo");

// From explicit API and gateway (custom setups, testing)
import { getGateway } from "@polkadot-apps/bulletin";
const custom = BulletinClient.from(myApi, "https://my-gateway.example/ipfs/");