@fluxpointstudios/orynq-sdk-quickstart 0.2.0

package/src/__tests__/quickstart.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @summary Quickstart contract tests.
+ *
+ * These tests pin the solo-dev sub-5-min DX contract:
+ *
+ *   1. `loadOrCreateIdentity()` is pure-local (no network), generates a fresh
+ *      sr25519 keypair from a fresh mnemonic when the config file does not
+ *      exist, and reloads byte-for-byte the same address on subsequent calls.
+ *   2. `firstTraceBundle()` produces a deterministic-shape `TraceBundle` in
+ *      under 1 second for a tiny payload — confirms the local-trace step
+ *      itself never blocks the 5-minute budget.
+ *   3. `buildExplorerUrls()` returns the trifecta of human-friendly URLs
+ *      (gateway blob status, Polkadot.js apps explorer, raw RPC genesis)
+ *      that solo devs need to *see* their trace after submission.
+ *
+ * Network-bound tests (faucet drip + on-chain submit) live in
+ * `quickstart.live.test.ts` and are gated by `ORYNQ_RUN_LIVE_TESTS=1`. They
+ * exercise the real preprod gateway when present, but never block CI for
+ * solo devs running `pnpm test` on their laptop.
+ */
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { cryptoWaitReady } from "@polkadot/util-crypto";
+import { loadOrCreateIdentity, firstTraceBundle, buildExplorerUrls } from "../index.js";
+import type { OrynqIdentity, TraceBundleLite } from "../index.js";
+
+beforeAll(async () => {
+  await cryptoWaitReady();
+});
+
+describe("loadOrCreateIdentity", () => {
+  it("generates a fresh identity when no config file exists, then reloads the same address", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "orynq-qs-test-"));
+    const configPath = join(tmpDir, "config.json");
+    try {
+      // First call: generate
+      const id1: OrynqIdentity = await loadOrCreateIdentity({ configPath });
+      expect(id1.address).toMatch(/^[15][a-zA-Z0-9]{45,47}$/);
+      expect(id1.mnemonic.split(" ").length).toBeGreaterThanOrEqual(12);
+      expect(id1.generatedAt).toBeTruthy();
+      expect(existsSync(configPath)).toBe(true);
+
+      // Second call: reload
+      const id2: OrynqIdentity = await loadOrCreateIdentity({ configPath });
+      expect(id2.address).toBe(id1.address);
+      expect(id2.mnemonic).toBe(id1.mnemonic);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("writes the config file with 0600 permissions on POSIX systems", async () => {
+    if (process.platform === "win32") return; // chmod is no-op on Windows
+    const tmpDir = mkdtempSync(join(tmpdir(), "orynq-qs-test-"));
+    const configPath = join(tmpDir, "config.json");
+    try {
+      await loadOrCreateIdentity({ configPath });
+      const { statSync } = await import("fs");
+      const mode = statSync(configPath).mode & 0o777;
+      expect(mode).toBe(0o600);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects a config file with malformed contents instead of silently regenerating", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "orynq-qs-test-"));
+    const configPath = join(tmpDir, "config.json");
+    try {
+      const { writeFileSync } = await import("fs");
+      writeFileSync(configPath, "not-json-at-all");
+      await expect(loadOrCreateIdentity({ configPath })).rejects.toThrow(/identity/i);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("firstTraceBundle", () => {
+  it("produces a finalised bundle with stable shape in under 1s", async () => {
+    const start = Date.now();
+    const bundle: TraceBundleLite = await firstTraceBundle({
+      agentId: "qs-test-agent",
+      summary: "hello from quickstart tests",
+    });
+    const elapsed = Date.now() - start;
+
+    expect(elapsed).toBeLessThan(1000);
+    expect(bundle.rootHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(bundle.merkleRoot).toMatch(/^[0-9a-f]{64}$/);
+    expect(bundle.manifestHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(bundle.runId).toMatch(/^[0-9a-f-]{36}$/);
+    expect(bundle.content.length).toBeGreaterThan(0);
+  });
+
+  it("produces deterministic hashes for fixed inputs given a fixed timestamp", async () => {
+    const fixed = new Date("2026-05-14T12:00:00.000Z");
+    const a = await firstTraceBundle({
+      agentId: "fixed-agent",
+      summary: "fixed",
+      now: () => fixed,
+      runId: "00000000-0000-4000-8000-000000000000",
+      spanId: "11111111-1111-4111-8111-111111111111",
+      eventId: "22222222-2222-4222-8222-222222222222",
+    });
+    const b = await firstTraceBundle({
+      agentId: "fixed-agent",
+      summary: "fixed",
+      now: () => fixed,
+      runId: "00000000-0000-4000-8000-000000000000",
+      spanId: "11111111-1111-4111-8111-111111111111",
+      eventId: "22222222-2222-4222-8222-222222222222",
+    });
+    expect(a.rootHash).toBe(b.rootHash);
+    expect(a.merkleRoot).toBe(b.merkleRoot);
+    expect(a.manifestHash).toBe(b.manifestHash);
+  });
+});
+
+describe("buildExplorerUrls", () => {
+  it("returns the four explorer surfaces solo devs need to *see* their trace", () => {
+    const urls = buildExplorerUrls({
+      contentHash: "0x" + "ab".repeat(32),
+      blockHash: "0x" + "cd".repeat(32),
+      gatewayBaseUrl: "https://materios.fluxpointstudios.com/blobs",
+      rpcUrl: "wss://materios.fluxpointstudios.com/rpc",
+    });
+    // The SDK's upload path is `${baseUrl}/blobs/<hash>/manifest`. The
+    // status URL preserves that shape so it routes through the same
+    // nginx mount.
+    expect(urls.blobStatus).toBe(
+      "https://materios.fluxpointstudios.com/blobs/blobs/" + "ab".repeat(32) + "/status",
+    );
+    expect(urls.explorer).toContain("polkadot.js.org/apps");
+    expect(urls.explorer).toContain(encodeURIComponent("wss://materios.fluxpointstudios.com/rpc"));
+    expect(urls.explorer).toContain("cd".repeat(32));
+    // /chain-info and /health live on the root express app, not the
+    // /blobs router — we strip the /blobs prefix for those.
+    expect(urls.chainInfo).toBe("https://materios.fluxpointstudios.com/chain-info");
+    expect(urls.gatewayHealth).toBe("https://materios.fluxpointstudios.com/health");
+  });
+
+  it("when baseUrl omits /blobs, the same origin is used for both blob + root URLs", () => {
+    const urls = buildExplorerUrls({
+      contentHash: "ab".repeat(32),
+      blockHash: "cd".repeat(32),
+      gatewayBaseUrl: "https://my-gateway.example.com",
+      rpcUrl: "wss://my-rpc.example.com",
+    });
+    expect(urls.blobStatus).toBe(
+      "https://my-gateway.example.com/blobs/" + "ab".repeat(32) + "/status",
+    );
+    expect(urls.chainInfo).toBe("https://my-gateway.example.com/chain-info");
+    expect(urls.gatewayHealth).toBe("https://my-gateway.example.com/health");
+  });
+
+  it("strips 0x from the gateway URL path but preserves 0x on the polkadot.js apps URL", () => {
+    const urls = buildExplorerUrls({
+      contentHash: "0x" + "ab".repeat(32),
+      blockHash: "0x" + "cd".repeat(32),
+      gatewayBaseUrl: "https://gw.example.com",
+      rpcUrl: "wss://rpc.example.com",
+    });
+    // Gateway paths are bare hex (no 0x), to avoid double-prefix
+    // collisions in the route matcher.
+    expect(urls.blobStatus).not.toContain("/0x");
+    // Polkadot.js apps explorer wants the 0x prefix. The query path is
+    //   #/explorer/query/0x<blockhash>
+    expect(urls.explorer).toContain("/explorer/query/0x" + "cd".repeat(32));
+  });
+});

package/src/bootstrap.ts

@@ -0,0 +1,299 @@
+/**
+ * @summary One-call solo-dev bootstrap.
+ *
+ * `bootstrapAndTrace()` does ALL of:
+ *
+ *   1. `loadOrCreateIdentity()`  — fresh sr25519 keypair on first run.
+ *   2. `requestFaucet()`         — free-tier MATRA drip on the gateway.
+ *   3. `firstTraceBundle()`      — build + finalise a "hello" trace.
+ *   4. `submitCertifiedReceipt()` — upload blob + submit receipt on chain.
+ *   5. `buildExplorerUrls()`     — compose the URLs the dev needs to click.
+ *
+ * Compared to the manual flow (e2e-flow.ts), this collapses ~10 lines of
+ * MateriosProvider config + 30 lines of error handling into a single
+ * `await bootstrapAndTrace({})`. Defaults target Materios preprod; pass
+ * env-driven overrides to point at a different chain.
+ *
+ * Designed to surface, not paper over, real failures. Faucet cooldown is
+ * NOT retried; certification timeout is NOT swallowed. The expectation is
+ * that a fresh dev sees a green path on first run and a clear error
+ * message otherwise — never a hung "loading...".
+ */
+
+import { createHash } from "crypto";
+import { Keyring } from "@polkadot/keyring";
+import { cryptoWaitReady } from "@polkadot/util-crypto";
+import {
+  MateriosProvider,
+  submitReceipt,
+  uploadBlobs,
+  prepareBlobData,
+  waitForCertification,
+  waitForMotra,
+} from "@fluxpointstudios/orynq-sdk-anchors-materios";
+
+import { loadOrCreateIdentity } from "./identity.js";
+import type { OrynqIdentity } from "./identity.js";
+import { firstTraceBundle } from "./trace.js";
+import type { TraceBundleLite } from "./trace.js";
+import { requestFaucet } from "./faucet.js";
+import type { FaucetDripResult } from "./faucet.js";
+import { buildExplorerUrls } from "./explorer.js";
+import type { ExplorerUrls } from "./explorer.js";
+
+export const DEFAULT_RPC_URL = "wss://materios.fluxpointstudios.com/rpc";
+export const DEFAULT_GATEWAY_URL = "https://materios.fluxpointstudios.com/blobs";
+export const DEFAULT_AGENT_ID = "orynq-quickstart";
+
+export interface BootstrapAndTraceOptions {
+  /** Path to the on-disk identity (defaults to `~/.orynq/config.json`). */
+  configPath?: string | undefined;
+  /** Substrate WS RPC URL. Defaults to preprod. */
+  rpcUrl?: string | undefined;
+  /** Blob-gateway base URL (with or without /blobs suffix). */
+  gatewayBaseUrl?: string | undefined;
+  /** AgentId stamped on the trace bundle. */
+  agentId?: string | undefined;
+  /**
+   * One-liner observation stamped as the public event of the first trace.
+   * Defaults to a self-describing message that includes the env's wall
+   * clock, so the trace is identifiable on the explorer.
+   */
+  summary?: string | undefined;
+  /**
+   * Wait this long for the cert-daemon committee to certify the receipt.
+   * Defaults to 120 s. Set to 0 to skip the cert wait entirely (returns
+   * as soon as the receipt is on chain). On preprod the cert window is
+   * ~30-90 s depending on attestor load + finality gap; 120 s gives the
+   * happy path a comfortable margin without keeping the dev hanging.
+   */
+  certTimeoutMs?: number | undefined;
+  /**
+   * If true, a cert timeout is treated as success — the receipt is on
+   * chain, the explorer URL is printed, and the cert is just "still
+   * pending". Defaults to true so a fresh dev sees a working trace URL
+   * even when the committee is mid-vote.
+   */
+  treatCertTimeoutAsSuccess?: boolean | undefined;
+  /**
+   * Hook fired after each major step. Lets the CLI render a live status
+   * line without coupling business logic to console.log.
+   */
+  onProgress?: ((step: BootstrapStep) => void) | undefined;
+  /**
+   * If true, the faucet step is skipped — useful when the dev has
+   * pre-funded their address via Discord faucet, an existing wallet, etc.
+   * Defaults to false.
+   */
+  skipFaucet?: boolean | undefined;
+}
+
+export type BootstrapStep =
+  | { kind: "identity-loaded"; identity: OrynqIdentity }
+  | { kind: "faucet-result"; result: FaucetDripResult }
+  | { kind: "waiting-for-motra" }
+  | { kind: "motra-ready"; balance: bigint }
+  | { kind: "trace-built"; bundle: TraceBundleLite }
+  | { kind: "blob-uploaded"; contentHash: string }
+  | { kind: "receipt-submitted"; receiptId: string; blockHash: string }
+  | { kind: "certified"; certHash: string }
+  | { kind: "explorer-ready"; urls: ExplorerUrls };
+
+export interface BootstrapAndTraceResult {
+  identity: OrynqIdentity;
+  bundle: TraceBundleLite;
+  receiptId: string;
+  blockHash: string;
+  certHash?: string;
+  urls: ExplorerUrls;
+  /** Wall-clock duration from start of bootstrap to URLs available. */
+  elapsedMs: number;
+}
+
+/**
+ * Bootstrap a fresh dev to a chain-anchored first trace.
+ *
+ * Steps (each emits a progress event via `onProgress`):
+ *   1. load-or-create identity            ~50 ms
+ *   2. faucet drip (skipped if funded)    ~2 s
+ *   3. wait for MOTRA to generate         ~10-30 s (chain block production)
+ *   4. build local trace bundle           ~10 ms
+ *   5. upload blob + submit receipt       ~6 s (1 block)
+ *   6. await certification (optional)     ~10-30 s (committee voting)
+ *   7. compose explorer URLs              instant
+ *
+ * Total budget on a fresh address: 30-60 s wall-clock. With faucet skipped
+ * and MOTRA already in hand: <10 s.
+ */
+export async function bootstrapAndTrace(
+  opts: BootstrapAndTraceOptions = {},
+): Promise<BootstrapAndTraceResult> {
+  await cryptoWaitReady();
+  const start = Date.now();
+  const onProgress = opts.onProgress ?? (() => {});
+
+  // Step 1: identity
+  const identity = await loadOrCreateIdentity({
+    ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
+  });
+  onProgress({ kind: "identity-loaded", identity });
+
+  const gateway = opts.gatewayBaseUrl ?? DEFAULT_GATEWAY_URL;
+  const rpcUrl = opts.rpcUrl ?? DEFAULT_RPC_URL;
+
+  // Step 2: faucet (best-effort; idempotent under success + already-funded)
+  if (!opts.skipFaucet) {
+    const faucetResult = await requestFaucet({ address: identity.address, gatewayBaseUrl: gateway });
+    onProgress({ kind: "faucet-result", result: faucetResult });
+    if (faucetResult.kind === "error" || faucetResult.kind === "cooldown") {
+      throw new Error(
+        `faucet drip failed for ${identity.address}: ${faucetResult.kind} — ${faucetResult.message ?? "unknown"}. ` +
+          `Workarounds: (1) skipFaucet:true if you've already funded ${identity.address} elsewhere; ` +
+          `(2) retry in a few minutes if cooldown; (3) ask in Discord (#materios) for a top-up.`,
+      );
+    }
+  }
+
+  // Step 3: connect to chain, wait for MOTRA
+  const provider = new MateriosProvider({ rpcUrl, signerUri: identity.mnemonic });
+  await provider.connect();
+  try {
+    onProgress({ kind: "waiting-for-motra" });
+    // 1 MATRA at 6-dec = 1_000_000 units. We need enough MOTRA (the fee
+    // currency, auto-generated from MATRA at ~6.94e-12 MOTRA per MATRA-block)
+    // to cover one submit_receipt. The default min in waitForMotra
+    // (1.5e12) is empirically the floor that covers one extrinsic + a
+    // chain-tx + a chunk upload.
+    const balance = await waitForMotra(provider, undefined, { timeoutMs: 90_000 });
+    onProgress({ kind: "motra-ready", balance });
+
+    // Step 4: build the trace
+    const bundle = await firstTraceBundle({
+      agentId: opts.agentId ?? DEFAULT_AGENT_ID,
+      summary:
+        opts.summary ??
+        `first trace via orynq-sdk-quickstart at ${new Date().toISOString()}`,
+    });
+    onProgress({ kind: "trace-built", bundle });
+
+    // Step 5: upload blob + submit receipt + (optionally) wait for cert.
+    //
+    // We call the three SDK primitives explicitly instead of
+    // `submitCertifiedReceipt()` so a cert-poll timeout doesn't lose the
+    // submit result. The on-chain receipt + blockHash are already known
+    // by then — we just want to surface "submitted, pending cert" cleanly.
+    const keypair = provider.getKeypair();
+    const contentBuf = Buffer.from(bundle.content, "utf-8");
+    const contentHash = bundle.manifestHash; // canonical content == addressable blob
+    const certTimeoutMs = opts.certTimeoutMs ?? 120_000;
+    const treatCertTimeoutAsSuccess = opts.treatCertTimeoutAsSuccess !== false;
+
+    // 5a. Derive the receiptId the same way submit_receipt does: it's
+    //     sha256 of the (binary) contentHash. The blob-gateway routes
+    //     all chunk + manifest paths under this receiptId so they must
+    //     match the on-chain id byte-for-byte.
+    const contentHashHex = contentHash.startsWith("0x") ? contentHash.slice(2) : contentHash;
+    const receiptIdHex = "0x" + createHash("sha256")
+      .update(Buffer.from(contentHashHex, "hex"))
+      .digest("hex");
+
+    // 5b. Upload the blob via sig-only auth (no API key required).
+    const { manifest, chunks } = prepareBlobData(receiptIdHex, contentBuf);
+    const uploadResult = await uploadBlobs(
+      receiptIdHex,
+      manifest,
+      chunks,
+      {
+        baseUrl: gateway,
+        signerKeypair: {
+          address: keypair.address,
+          sign: (msg: Uint8Array) => keypair.sign(msg),
+        },
+      },
+    );
+    if (!uploadResult.success) {
+      throw new Error(`blob upload failed: ${uploadResult.error ?? "unknown"}`);
+    }
+
+    // 5c. Submit the on-chain receipt. Pass receiptId explicitly so the
+    //     gateway-side blob path + the on-chain receipt agree on the key
+    //     (the SDK's default derivation matches what we computed above).
+    const submitResult = await submitReceipt(provider, {
+      receiptId: receiptIdHex,
+      contentHash,
+      rootHash: bundle.rootHash,
+      manifestHash: uploadResult.storageLocatorHash ?? bundle.manifestHash,
+    });
+    onProgress({
+      kind: "receipt-submitted",
+      receiptId: submitResult.receiptId,
+      blockHash: submitResult.blockHash,
+    });
+
+    // 5c. Optionally wait for cert. Timeouts are surfaced as "submitted,
+    //     pending cert" rather than a hard failure so the dev still sees
+    //     a usable URL on a slow committee.
+    let certHash: string | undefined;
+    if (certTimeoutMs > 0) {
+      try {
+        const certResult = await waitForCertification(
+          provider,
+          submitResult.receiptId,
+          { timeoutMs: certTimeoutMs },
+        );
+        certHash = certResult.certHash;
+        onProgress({ kind: "certified", certHash });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const isCertTimeout = /Certification timeout/i.test(msg);
+        if (!(isCertTimeout && treatCertTimeoutAsSuccess)) {
+          throw err;
+        }
+        // Cert pending — proceed with the URLs we have.
+      }
+    }
+
+    // The gateway routes blob status by the same key the SDK uploaded
+    // under — that's the receiptId, NOT the content sha256. Pass it as
+    // `contentHash` to buildExplorerUrls (the parameter name carries the
+    // legacy meaning from the gateway route).
+    const urls = buildExplorerUrls({
+      contentHash: receiptIdHex,
+      blockHash: submitResult.blockHash,
+      gatewayBaseUrl: gateway,
+      rpcUrl,
+    });
+    onProgress({ kind: "explorer-ready", urls });
+
+    const result: BootstrapAndTraceResult = {
+      identity,
+      bundle,
+      receiptId: submitResult.receiptId,
+      blockHash: submitResult.blockHash,
+      urls,
+      elapsedMs: Date.now() - start,
+    };
+    if (certHash) {
+      result.certHash = certHash;
+    }
+    return result;
+  } finally {
+    await provider.disconnect().catch(() => {
+      // Swallow disconnect errors — we already have the result the caller
+      // wanted. Surfacing this would mask the real (successful) outcome.
+      // The provider's WS will tear itself down on process exit anyway.
+    });
+  }
+}
+
+/**
+ * Standalone helper: spin up a `Keyring` from a mnemonic. Exposed so the
+ * CLI can re-derive an address from the saved config without pulling in
+ * the full bootstrap path.
+ */
+export async function deriveAddress(mnemonic: string, ss58Format = 42): Promise<string> {
+  await cryptoWaitReady();
+  const keyring = new Keyring({ type: "sr25519", ss58Format });
+  return keyring.addFromUri(mnemonic).address;
+}
+

package/src/explorer.ts

@@ -0,0 +1,127 @@
+/**
+ * @summary Compose the user-facing URLs that close the loop on "first trace".
+ *
+ * The DX requirement (#175) is: after submission, the SDK MUST print a URL
+ * the developer can click and see something. Materios doesn't yet ship a
+ * native trace-detail explorer page, so we compose three known-good URLs:
+ *
+ *   1. `blobStatus`     — `${gateway}/blobs/<contentHash>/status` — gateway-
+ *                          side status of the receipt (HTTP 200 + JSON,
+ *                          browser-renderable).
+ *   2. `explorer`       — Polkadot.js apps explorer pre-pointed at the
+ *                          submission block. Shows the on-chain extrinsic
+ *                          with full SCALE-decoded args.
+ *   3. `chainInfo`      — `${gateway}/chain-info` — JSON with the live
+ *                          genesis hash + best block, useful as a sanity
+ *                          check that the gateway is the chain you think
+ *                          it is.
+ *   4. `gatewayHealth`  — `${gateway}/health` — cluster-health summary
+ *                          (cert-daemon, anchor-worker, storage usage).
+ *
+ * A follow-up will replace `explorer` with a first-party
+ * `https://materios.fluxpointstudios.com/trace/<contentHash>` page (filed
+ * separately) — at which point the field swaps and the rest of the SDK
+ * surface keeps working.
+ */
+
+export interface BuildExplorerUrlsInput {
+  /**
+   * Hex content hash, with or without `0x` prefix. Used to build the
+   * gateway status URL.
+   */
+  contentHash: string;
+  /**
+   * Hex block hash from the on-chain submission, with or without `0x`.
+   * Used to build the Polkadot.js apps query URL.
+   */
+  blockHash: string;
+  /**
+   * Gateway base URL. Accepts either `https://host` or `https://host/blobs`
+   * — the function normalises so callers don't have to remember which
+   * variant the env exports.
+   */
+  gatewayBaseUrl: string;
+  /**
+   * Substrate websocket RPC URL. Used to build the Polkadot.js apps
+   * pre-pointed-at-this-chain URL.
+   */
+  rpcUrl: string;
+}
+
+export interface ExplorerUrls {
+  /** Gateway blob status JSON. */
+  blobStatus: string;
+  /** Polkadot.js apps pre-pointed at this chain's submission block. */
+  explorer: string;
+  /** Gateway chain-info endpoint (genesis + best block). */
+  chainInfo: string;
+  /** Gateway top-level health roll-up. */
+  gatewayHealth: string;
+}
+
+/**
+ * Strip an optional `0x` prefix from a hex string. Returns the cleaned
+ * hex if present, otherwise the original string unchanged.
+ */
+function strip0x(hex: string): string {
+  return hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+}
+
+/**
+ * Normalise the gateway base URL.
+ *
+ * The blob-gateway's express routes are mounted at `/blobs/:contentHash/...`,
+ * and the gateway is exposed both directly AND via an nginx reverse-proxy
+ * that also prefixes `/blobs`. In production, the SDK is configured with
+ * `baseUrl="https://host/blobs"`, and constructs upload URLs like
+ * `${baseUrl}/blobs/<hash>/manifest` — i.e. the **upload path keeps both
+ * "/blobs" segments**. To produce a working *human-facing* status URL
+ * here, we must preserve the same shape.
+ *
+ * Accepts:
+ *   - `https://host`        — `originBase = host`
+ *   - `https://host/blobs`  — `originBase = host` (the /blobs is the
+ *                              nginx prefix; we keep it for blob URLs but
+ *                              strip it for the top-level /chain-info,
+ *                              /health endpoints which mount on the
+ *                              gateway's root express app, not the blobs
+ *                              router).
+ *
+ * Returns both the normalised forms callers need:
+ *   - `blobsBase`   the URL prefix the SDK already uses for /blobs/<h>/...
+ *                   uploads. Status URLs share this prefix.
+ *   - `rootBase`    the bare origin for /chain-info, /health.
+ */
+function normaliseGatewayBase(base: string): { blobsBase: string; rootBase: string } {
+  let s = base.trim();
+  if (s.endsWith("/")) s = s.slice(0, -1);
+  if (s.endsWith("/blobs")) {
+    const rootBase = s.slice(0, -"/blobs".length);
+    return { blobsBase: s, rootBase };
+  }
+  // No /blobs in baseUrl — assume nginx mounts gateway at the root.
+  // Blob URLs and root URLs share the same origin.
+  return { blobsBase: s, rootBase: s };
+}
+
+export function buildExplorerUrls(input: BuildExplorerUrlsInput): ExplorerUrls {
+  const contentHash = strip0x(input.contentHash);
+  const blockHash = strip0x(input.blockHash);
+  const { blobsBase, rootBase } = normaliseGatewayBase(input.gatewayBaseUrl);
+
+  // Polkadot.js apps URL format:
+  //   https://polkadot.js.org/apps/?rpc=<encoded-ws-url>#/explorer/query/<blockHash>
+  // The leading `?rpc=` lives BEFORE the hash because the apps router
+  // reads the query string ahead of the hash route.
+  const encodedRpc = encodeURIComponent(input.rpcUrl);
+  const explorer = `https://polkadot.js.org/apps/?rpc=${encodedRpc}#/explorer/query/0x${blockHash}`;
+
+  // Match the upload-side path shape: ${blobsBase}/blobs/<hash>/...
+  // (The SDK's `uploadBlobs()` does `${baseUrl}/blobs/<hash>/manifest`.)
+  return {
+    blobStatus: `${blobsBase}/blobs/${contentHash}/status`,
+    explorer,
+    chainInfo: `${rootBase}/chain-info`,
+    gatewayHealth: `${rootBase}/health`,
+  };
+}