@orangecheck/stamp-ots 0.1.0

package/src/base64.ts

@@ -0,0 +1,81 @@
+// Minimal, dependency-free base64 <-> Uint8Array helpers. OTS proof bytes
+// are carried as base64 inside OC Stamp envelopes so they survive any text
+// transport (URL fragment, JSON, Nostr event content).
+
+const B64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_DECODE_TABLE = (() => {
+    const t = new Int16Array(128).fill(-1);
+    for (let i = 0; i < B64_CHARS.length; i++) t[B64_CHARS.charCodeAt(i)] = i;
+    t['='.charCodeAt(0)] = -2;
+    return t;
+})();
+
+export function base64Encode(bytes: Uint8Array): string {
+    let out = '';
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const a = bytes[i]!;
+        const b = bytes[i + 1]!;
+        const c = bytes[i + 2]!;
+        out +=
+            B64_CHARS[a >> 2]! +
+            B64_CHARS[((a & 0x03) << 4) | (b >> 4)]! +
+            B64_CHARS[((b & 0x0f) << 2) | (c >> 6)]! +
+            B64_CHARS[c & 0x3f]!;
+    }
+    if (i < bytes.length) {
+        const a = bytes[i]!;
+        const b = i + 1 < bytes.length ? bytes[i + 1]! : 0;
+        out += B64_CHARS[a >> 2]!;
+        out += B64_CHARS[((a & 0x03) << 4) | (b >> 4)]!;
+        out += i + 1 < bytes.length ? B64_CHARS[(b & 0x0f) << 2]! : '=';
+        out += '=';
+    }
+    return out;
+}
+
+export function base64Decode(s: string): Uint8Array {
+    const str = s.replace(/\s+/g, '');
+    const len = str.length;
+    if (len === 0) return new Uint8Array(0);
+    if (len % 4 !== 0) throw new Error('base64: bad length');
+    let padding = 0;
+    if (str[len - 1] === '=') padding++;
+    if (str[len - 2] === '=') padding++;
+    const outLen = (len / 4) * 3 - padding;
+    const out = new Uint8Array(outLen);
+    let o = 0;
+    for (let i = 0; i < len; i += 4) {
+        const c0 = B64_DECODE_TABLE[str.charCodeAt(i)]!;
+        const c1 = B64_DECODE_TABLE[str.charCodeAt(i + 1)]!;
+        const c2 = B64_DECODE_TABLE[str.charCodeAt(i + 2)]!;
+        const c3 = B64_DECODE_TABLE[str.charCodeAt(i + 3)]!;
+        if (c0 < 0 || c1 < 0 || c2 < -2 || c3 < -2) throw new Error('base64: bad char');
+        out[o++] = (c0 << 2) | (c1 >> 4);
+        if (c2 >= 0) out[o++] = ((c1 & 0x0f) << 4) | (c2 >> 2);
+        if (c3 >= 0) out[o++] = ((c2 & 0x03) << 6) | c3;
+    }
+    return out;
+}
+
+export function hexDecode(s: string): Uint8Array {
+    if (s.length % 2 !== 0) throw new Error('hex: odd length');
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const hi = parseInt(s[i * 2]!, 16);
+        const lo = parseInt(s[i * 2 + 1]!, 16);
+        if (Number.isNaN(hi) || Number.isNaN(lo)) throw new Error('hex: bad char');
+        out[i] = (hi << 4) | lo;
+    }
+    return out;
+}
+
+export function hexEncode(bytes: Uint8Array): string {
+    const HEX = '0123456789abcdef';
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i]!;
+        out += HEX[(b >> 4) & 0x0f]! + HEX[b & 0x0f]!;
+    }
+    return out;
+}

package/src/calendar.ts

@@ -0,0 +1,101 @@
+// HTTP client for an OpenTimestamps calendar. Implements the minimal subset
+// of the calendar protocol that an OC Stamp implementation needs:
+//
+//   POST <url>/digest          body = raw digest bytes        -> pending proof bytes
+//   GET  <url>/timestamp/<hex>                                -> upgraded proof bytes, or 404
+//
+// The client is thin by design. It does not parse proof bytes; that is a
+// separate concern addressed by whichever OTS proof library the consumer
+// plugs in (see verifyOtsAnchor in ./anchor.ts).
+
+import type { CalendarClient } from './types.js';
+import { hexEncode } from './base64.js';
+
+export const DEFAULT_CALENDARS: readonly string[] = [
+    'https://alice.btc.calendar.opentimestamps.org',
+    'https://bob.btc.calendar.opentimestamps.org',
+    'https://finney.calendar.eternitywall.com',
+];
+
+export interface HttpCalendarOptions {
+    /**
+     * Custom fetch implementation. Defaults to global `fetch`. Useful in
+     * environments that need a specific adapter (Node < 18, Cloudflare
+     * Workers, proxies).
+     */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds. Default 30_000. */
+    timeoutMs?: number;
+}
+
+export function createCalendarClient(url: string, opts: HttpCalendarOptions = {}): CalendarClient {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error(
+            '@orangecheck/stamp-ots: no fetch implementation available. Pass one via { fetch }.'
+        );
+    }
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const base = url.replace(/\/$/, '');
+
+    return {
+        url: base,
+        async submit(digest, signal) {
+            if (digest.byteLength !== 32) {
+                throw new Error('OTS: digest must be exactly 32 bytes');
+            }
+            const ac = withTimeout(signal, timeoutMs);
+            // Uint8Array is a valid fetch body at runtime in Node 18+ and all
+            // modern browsers, but TypeScript's DOM typings don't accept it
+            // directly under `strict` + `noUncheckedIndexedAccess`. The cast is
+            // narrow and intentional.
+            const resp = await fetchImpl(`${base}/digest`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/vnd.opentimestamps.v1' },
+                body: digest as unknown as BodyInit,
+                signal: ac.signal,
+            });
+            ac.clear();
+            if (!resp.ok) {
+                throw new Error(`OTS calendar ${base} submit failed: HTTP ${resp.status}`);
+            }
+            const buf = await resp.arrayBuffer();
+            return new Uint8Array(buf);
+        },
+        async fetchProof(digest, signal) {
+            if (digest.byteLength !== 32) {
+                throw new Error('OTS: digest must be exactly 32 bytes');
+            }
+            const ac = withTimeout(signal, timeoutMs);
+            const resp = await fetchImpl(`${base}/timestamp/${hexEncode(digest)}`, {
+                method: 'GET',
+                headers: { Accept: 'application/vnd.opentimestamps.v1' },
+                signal: ac.signal,
+            });
+            ac.clear();
+            if (resp.status === 404) return null;
+            if (!resp.ok) {
+                throw new Error(`OTS calendar ${base} fetchProof failed: HTTP ${resp.status}`);
+            }
+            const buf = await resp.arrayBuffer();
+            return new Uint8Array(buf);
+        },
+    };
+}
+
+function withTimeout(parent: AbortSignal | undefined, ms: number): { signal: AbortSignal; clear: () => void } {
+    const ac = new AbortController();
+    const onParent = () => ac.abort((parent as AbortSignal & { reason?: unknown }).reason);
+    if (parent) {
+        if (parent.aborted) ac.abort((parent as AbortSignal & { reason?: unknown }).reason);
+        else parent.addEventListener('abort', onParent, { once: true });
+    }
+    const t = setTimeout(() => ac.abort(new Error(`OTS request timed out after ${ms}ms`)), ms);
+    return {
+        signal: ac.signal,
+        clear: () => {
+            clearTimeout(t);
+            if (parent) parent.removeEventListener('abort', onParent);
+        },
+    };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './types.js';
+export { base64Decode, base64Encode, hexDecode, hexEncode } from './base64.js';
+export { createCalendarClient, DEFAULT_CALENDARS } from './calendar.js';
+export type { HttpCalendarOptions } from './calendar.js';
+export { submitToCalendars } from './submit.js';
+export type { SubmitOptions } from './submit.js';
+export { upgradeProof } from './upgrade.js';
+export type { UpgradeOptions } from './upgrade.js';
+export { makeAnchorVerifier, adaptAnchorVerifier } from './anchor.js';
+export type { AnchorVerifierConfig } from './anchor.js';

package/src/submit.test.ts

@@ -0,0 +1,108 @@
+// submit() / upgrade() tests using a fake CalendarClient — avoids hitting the
+// real OTS calendar network from CI. Verifies the composition logic only.
+
+import { describe, expect, it } from 'vitest';
+
+import { submitToCalendars } from './submit.js';
+import { upgradeProof } from './upgrade.js';
+import type { CalendarClient, OtsProof } from './types.js';
+
+const FIXED_ID = 'ad30c983dfc872a8c53cd70eb4d84e1869967a4b8433586beec7ba468b03c3de';
+
+function fakeCalendar(opts: {
+    url: string;
+    submitResult?: Uint8Array | (() => Promise<Uint8Array>);
+    fetchResult?: Uint8Array | null | (() => Promise<Uint8Array | null>);
+    submitShouldFail?: boolean;
+}): CalendarClient {
+    return {
+        url: opts.url,
+        async submit(digest) {
+            if (opts.submitShouldFail) throw new Error(`calendar ${opts.url} down`);
+            if (!opts.submitResult) return new Uint8Array([0xde, 0xad, ...digest.subarray(0, 4)]);
+            const r = typeof opts.submitResult === 'function' ? await opts.submitResult() : opts.submitResult;
+            return r;
+        },
+        async fetchProof() {
+            if (!opts.fetchResult && opts.fetchResult !== null)
+                return new Uint8Array([0xfe, 0xed, 0xfa, 0xce]);
+            const r = typeof opts.fetchResult === 'function' ? await opts.fetchResult() : opts.fetchResult;
+            return r;
+        },
+    };
+}
+
+describe('submitToCalendars', () => {
+    it('returns a pending proof with all successful calendars listed', async () => {
+        const cal1 = fakeCalendar({ url: 'https://a.example', submitResult: new Uint8Array([1, 2, 3]) });
+        const cal2 = fakeCalendar({ url: 'https://b.example', submitResult: new Uint8Array([4, 5, 6, 7]) });
+        const out = await submitToCalendars(FIXED_ID, { calendars: [cal1, cal2] });
+        expect(out.status).toBe('pending');
+        expect(out.calendars).toEqual(['https://a.example', 'https://b.example']);
+        expect(out.blockHeight).toBeNull();
+        expect(out.proof.length).toBeGreaterThan(0);
+    });
+
+    it('tolerates one calendar failure when minSuccesses defaults to 1', async () => {
+        const bad = fakeCalendar({ url: 'https://bad.example', submitShouldFail: true });
+        const good = fakeCalendar({ url: 'https://good.example', submitResult: new Uint8Array([9]) });
+        const out = await submitToCalendars(FIXED_ID, { calendars: [bad, good] });
+        expect(out.calendars).toEqual(['https://good.example']);
+    });
+
+    it('throws when minSuccesses is not met', async () => {
+        const bad1 = fakeCalendar({ url: 'https://x.example', submitShouldFail: true });
+        const bad2 = fakeCalendar({ url: 'https://y.example', submitShouldFail: true });
+        await expect(
+            submitToCalendars(FIXED_ID, { calendars: [bad1, bad2], minSuccesses: 1 })
+        ).rejects.toThrow(/did not reach/);
+    });
+
+    it('rejects invalid id hex', async () => {
+        await expect(submitToCalendars('deadbeef', { calendars: ['https://x'] })).rejects.toThrow();
+    });
+});
+
+describe('upgradeProof', () => {
+    const basePending: OtsProof = {
+        status: 'pending',
+        proof: 'AAEC',
+        calendars: ['https://a.example', 'https://b.example'],
+        blockHeight: null,
+        blockHash: null,
+        upgradedAt: null,
+    };
+
+    it('returns current proof unchanged when parseAnchor returns null from all calendars', async () => {
+        // Fake the fetch so calendars return same-length pending proofs.
+        // We have to monkey-patch createCalendarClient indirectly — instead,
+        // use a minimal harness: submit() isn't used here, upgradeProof reads
+        // calendars from the proof and creates new clients. Rather than
+        // rewire the module, we test the no-op path by making parseAnchor
+        // return null and ensure the function returns the input.
+        // The real network fetches will fail in test; we swallow via opts.fetch.
+        const fakeFetch = async () => new Response(null, { status: 404 });
+        const out = await upgradeProof(basePending, FIXED_ID, {
+            parseAnchor: async () => null,
+            fetch: fakeFetch as unknown as typeof fetch,
+        });
+        // Both calendars returned 404 => nothing to update.
+        expect(out).toEqual(basePending);
+    });
+
+    it('is idempotent when given a confirmed proof', async () => {
+        const confirmed: OtsProof = {
+            ...basePending,
+            status: 'confirmed',
+            blockHeight: 890123,
+            blockHash: '0'.repeat(64),
+            upgradedAt: '2026-04-24T19:00:00Z',
+        };
+        const out = await upgradeProof(confirmed, FIXED_ID, {
+            parseAnchor: async () => {
+                throw new Error('should not be called');
+            },
+        });
+        expect(out).toEqual(confirmed);
+    });
+});

package/src/submit.ts

@@ -0,0 +1,89 @@
+// Submit an envelope id to one or more OTS calendars. Returns a pending proof.
+// See SPEC.md §6.1.
+//
+// The submission strategy: try each calendar in parallel, take the first
+// success, report which calendar produced it. A stamp that only reaches one
+// calendar is a single point of failure for upgrade; the reference app
+// submits to at least two calendars for redundancy.
+
+import { base64Encode, hexDecode } from './base64.js';
+import { createCalendarClient, DEFAULT_CALENDARS } from './calendar.js';
+import type { CalendarClient, OtsProof } from './types.js';
+
+export interface SubmitOptions {
+    /**
+     * Calendars to submit to. Defaults to DEFAULT_CALENDARS. Can be strings
+     * (URLs) or pre-built CalendarClient instances.
+     */
+    calendars?: readonly (string | CalendarClient)[];
+    /**
+     * Minimum number of calendars that must succeed. Defaults to 1.
+     * If fewer than `minSuccesses` calendars respond with a proof,
+     * submit() throws an aggregate error.
+     */
+    minSuccesses?: number;
+    /** Optional custom fetch passed through to calendar clients. */
+    fetch?: typeof fetch;
+    /** Request timeout per calendar. Default 30_000ms. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+
+/**
+ * Submit the envelope `id` (64-hex) to OTS calendars and return an OtsProof in
+ * pending state. The caller merges this into the envelope's `ots` field.
+ *
+ * Implementation note: the raw proof bytes returned by OTS calendars are not
+ * a superset of the digest alone — they encode the calendar's commitment.
+ * Because different calendars return different pending-proof bytes for the
+ * same digest, we carry the FIRST successful calendar's bytes in the
+ * envelope. Upgrade (see upgrade.ts) can fetch richer proofs from any of the
+ * submitted-to calendars later.
+ */
+export async function submitToCalendars(idHex: string, opts: SubmitOptions = {}): Promise<OtsProof> {
+    const digest = hexDecode(idHex);
+    if (digest.byteLength !== 32) {
+        throw new Error('submitToCalendars: idHex must be 32 bytes (64 hex chars)');
+    }
+
+    const clients = (opts.calendars ?? DEFAULT_CALENDARS).map((c) =>
+        typeof c === 'string'
+            ? createCalendarClient(c, { fetch: opts.fetch, timeoutMs: opts.timeoutMs })
+            : c
+    );
+    if (clients.length === 0) {
+        throw new Error('submitToCalendars: at least one calendar is required');
+    }
+    const minSuccesses = Math.max(1, opts.minSuccesses ?? 1);
+
+    const settled = await Promise.allSettled(
+        clients.map(async (c) => {
+            const proof = await c.submit(digest, opts.signal);
+            return { url: c.url, proof };
+        })
+    );
+    const successes = settled
+        .filter((r): r is PromiseFulfilledResult<{ url: string; proof: Uint8Array }> => r.status === 'fulfilled')
+        .map((r) => r.value);
+    const failures = settled
+        .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
+        .map((r) => (r.reason instanceof Error ? r.reason.message : String(r.reason)));
+
+    if (successes.length < minSuccesses) {
+        // AggregateError would be nicer but targets ES2021; Error keeps us at ES2020.
+        const msg = `OTS submission did not reach ${minSuccesses} calendar(s). Errors: ${failures.join('; ')}`;
+        const err = new Error(msg) as Error & { errors: string[] };
+        err.errors = failures;
+        throw err;
+    }
+
+    const first = successes[0]!;
+    return {
+        status: 'pending',
+        proof: base64Encode(first.proof),
+        calendars: successes.map((s) => s.url),
+        blockHeight: null,
+        blockHash: null,
+        upgradedAt: null,
+    };
+}

package/src/types.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { fromStampOts, toStampOts } from './types.js';
+
+describe('toStampOts / fromStampOts', () => {
+    it('round-trips a pending proof', () => {
+        const original = {
+            status: 'pending' as const,
+            proof: 'xxxx',
+            calendars: ['https://a.example', 'https://b.example'],
+            blockHeight: null,
+            blockHash: null,
+            upgradedAt: null,
+        };
+        const stamp = toStampOts(original);
+        expect(stamp.status).toBe('pending');
+        expect(stamp.block_height).toBeNull();
+        const back = fromStampOts(stamp);
+        expect(back).toEqual(original);
+    });
+
+    it('round-trips a confirmed proof', () => {
+        const original = {
+            status: 'confirmed' as const,
+            proof: 'yyyy',
+            calendars: ['https://a.example'],
+            blockHeight: 890123,
+            blockHash: '0'.repeat(64),
+            upgradedAt: '2026-04-24T19:00:00Z',
+        };
+        const stamp = toStampOts(original);
+        expect(stamp.block_height).toBe(890123);
+        expect(stamp.block_hash).toBe('0'.repeat(64));
+        const back = fromStampOts(stamp);
+        expect(back).toEqual(original);
+    });
+});

package/src/types.ts

@@ -0,0 +1,101 @@
+// Types for @orangecheck/stamp-ots.
+
+import type { StampOts } from '@orangecheck/stamp-core';
+
+export type OtsProofStatus = 'pending' | 'confirmed';
+
+export interface OtsProof {
+    status: OtsProofStatus;
+    /** Raw proof bytes as base64. Opaque at this layer; parsers plug in. */
+    proof: string;
+    /** Calendar URLs that contain this proof, in submission order. */
+    calendars: string[];
+    /** Bitcoin block height at which this proof is anchored (null if pending). */
+    blockHeight: number | null;
+    /** Bitcoin block hash (hex, lowercase) at the anchor block (null if pending). */
+    blockHash: string | null;
+    /** ISO 8601 UTC of the upgrade (null if pending). */
+    upgradedAt: string | null;
+}
+
+export interface CalendarClient {
+    /** Base URL of the calendar, e.g. "https://alice.btc.calendar.opentimestamps.org". */
+    readonly url: string;
+
+    /**
+     * Submit a 32-byte digest to the calendar for aggregation. Returns the raw
+     * pending proof bytes.
+     *
+     * OTS calendar HTTP API: POST <url>/digest with the raw bytes as the body,
+     * Content-Type: application/vnd.opentimestamps.v1, returns the proof bytes
+     * as the response body.
+     */
+    submit(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;
+
+    /**
+     * Fetch the current (possibly upgraded) proof for a previously-submitted
+     * digest. Returns null if the calendar has no proof for this digest yet.
+     *
+     * OTS calendar HTTP API: GET <url>/timestamp/<hex(digest)>, returns the
+     * proof bytes or 404.
+     */
+    fetchProof(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
+}
+
+export interface AnchorVerificationInput {
+    /** Raw OTS proof bytes (base64-decoded by the caller). */
+    proofBytes: Uint8Array;
+    /** 32-byte digest that the proof commits to. */
+    digest: Uint8Array;
+    /** Declared block height from the envelope. */
+    blockHeight: number;
+    /** Declared block hash (hex) from the envelope. */
+    blockHash: string;
+    /**
+     * Optional block header source. If provided, the verifier uses this to
+     * fetch the header at `blockHeight` and compare its Merkle root to the
+     * one derived from walking the proof.
+     *
+     * If omitted, the verifier MAY still parse the proof and report
+     * structural validity but CANNOT report a bound anchor.
+     */
+    headerSource?: BlockHeaderSource;
+}
+
+export interface BlockHeaderSource {
+    /** Return the 80-byte raw block header at the given height, or null if unknown. */
+    getHeaderAt(height: number): Promise<Uint8Array | null>;
+}
+
+export type AnchorVerifier = (input: AnchorVerificationInput) => Promise<AnchorVerificationResult>;
+
+export type AnchorVerificationResult =
+    | { ok: true; merkleRoot: string }
+    | { ok: false; reason: string };
+
+/**
+ * Convert an OtsProof (library type) to the StampOts field shape that the
+ * envelope carries. The two are isomorphic; this function exists to keep
+ * stamp-core's type surface narrow.
+ */
+export function toStampOts(p: OtsProof): StampOts {
+    return {
+        status: p.status,
+        proof: p.proof,
+        calendars: p.calendars,
+        block_height: p.blockHeight,
+        block_hash: p.blockHash,
+        upgraded_at: p.upgradedAt,
+    };
+}
+
+export function fromStampOts(s: StampOts): OtsProof {
+    return {
+        status: s.status,
+        proof: s.proof,
+        calendars: s.calendars,
+        blockHeight: s.block_height,
+        blockHash: s.block_hash,
+        upgradedAt: s.upgraded_at,
+    };
+}

package/src/upgrade.ts

@@ -0,0 +1,102 @@
+// Upgrade a pending OTS proof to a confirmed one. See SPEC.md §6.2.
+//
+// Upgrade strategy: for each listed calendar, ask whether it has an upgraded
+// proof for this digest. If at least one calendar returns a proof longer than
+// the current pending one (heuristic for "more commitments included"),
+// return an upgraded OtsProof. The caller is responsible for verifying the
+// proof chains to a real Bitcoin block header (see anchor.ts).
+//
+// This package does NOT parse the proof bytes to extract block_height /
+// block_hash — that requires a full OTS proof parser. We provide an anchor
+// verifier callback pattern instead (see AnchorVerifier in ./types.ts).
+
+import { base64Decode, base64Encode, hexDecode } from './base64.js';
+import { createCalendarClient } from './calendar.js';
+import type { CalendarClient, OtsProof } from './types.js';
+
+export interface UpgradeOptions {
+    /**
+     * A parser that, given proof bytes, returns `{blockHeight, blockHash}` if
+     * the proof is fully anchored, or null if it's still pending.
+     *
+     * Callers plug in their own parser (e.g., via the `opentimestamps` npm
+     * package). This keeps @orangecheck/stamp-ots free of heavy parser deps.
+     */
+    parseAnchor: (proofBytes: Uint8Array) => Promise<{ blockHeight: number; blockHash: string } | null>;
+    /** Optional custom fetch passed through to calendar clients. */
+    fetch?: typeof fetch;
+    /** Request timeout per calendar. Default 30_000ms. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+
+export async function upgradeProof(
+    current: OtsProof,
+    idHex: string,
+    opts: UpgradeOptions
+): Promise<OtsProof> {
+    if (current.status === 'confirmed') return current; // idempotent
+
+    const digest = hexDecode(idHex);
+    const clients: CalendarClient[] = current.calendars.map((url) =>
+        createCalendarClient(url, { fetch: opts.fetch, timeoutMs: opts.timeoutMs })
+    );
+    if (clients.length === 0) {
+        throw new Error('upgradeProof: no calendars listed in current proof');
+    }
+
+    const attempts = await Promise.allSettled(
+        clients.map(async (c) => {
+            const proof = await c.fetchProof(digest, opts.signal);
+            if (!proof) return null;
+            const anchor = await opts.parseAnchor(proof);
+            return { url: c.url, proof, anchor };
+        })
+    );
+
+    // Prefer a fully-confirmed proof from any calendar.
+    for (const r of attempts) {
+        if (r.status !== 'fulfilled' || r.value === null) continue;
+        const { url, proof, anchor } = r.value;
+        if (anchor) {
+            return {
+                status: 'confirmed',
+                proof: base64Encode(proof),
+                calendars: uniqueFirst(current.calendars, url),
+                blockHeight: anchor.blockHeight,
+                blockHash: anchor.blockHash,
+                upgradedAt: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+            };
+        }
+    }
+
+    // No confirmation yet. Some calendars may still have returned updated
+    // pending bytes (more commitments included). Prefer the longest.
+    let longest: { url: string; proof: Uint8Array } | null = null;
+    for (const r of attempts) {
+        if (r.status !== 'fulfilled' || r.value === null) continue;
+        if (!longest || r.value.proof.byteLength > longest.proof.byteLength) {
+            longest = { url: r.value.url, proof: r.value.proof };
+        }
+    }
+    if (longest) {
+        const currentBytes = base64Decode(current.proof);
+        if (longest.proof.byteLength > currentBytes.byteLength) {
+            return {
+                status: 'pending',
+                proof: base64Encode(longest.proof),
+                calendars: uniqueFirst(current.calendars, longest.url),
+                blockHeight: null,
+                blockHash: null,
+                upgradedAt: null,
+            };
+        }
+    }
+    return current;
+}
+
+function uniqueFirst(arr: readonly string[], first: string): string[] {
+    const out = [first];
+    for (const x of arr) if (x !== first && !out.includes(x)) out.push(x);
+    return out;
+}