@orangecheck/stamp-ots 0.1.1 → 0.2.1

package/src/ots.ts

@@ -0,0 +1,320 @@
+// OpenTimestamps proof format: parse, walk, serialize, merge.
+//
+// Follows python-opentimestamps (core/timestamp.py, core/op.py,
+// core/notary.py). Two encodings are accepted:
+//
+//   - a bare timestamp rooted at the digest (what an OTS calendar returns from
+//     POST /digest, and what OC Stamp envelopes carry in `ots.proof`);
+//   - a detached `.ots` file (magic header + file-hash op + digest + timestamp).
+
+import { ripemd160, sha1 } from '@noble/hashes/legacy';
+import { sha256 } from '@noble/hashes/sha2';
+import { keccak_256 } from '@noble/hashes/sha3';
+
+import { hexEncode } from './base64.js';
+
+const HEADER_MAGIC = new Uint8Array([
+    0x00, 0x4f, 0x70, 0x65, 0x6e, 0x54, 0x69, 0x6d, 0x65, 0x73, 0x74, 0x61, 0x6d, 0x70, 0x73, 0x00,
+    0x00, 0x50, 0x72, 0x6f, 0x6f, 0x66, 0x00, 0xbf, 0x89, 0xe2, 0xe8, 0x84, 0xe8, 0x92, 0x94,
+]);
+
+const TAG_BITCOIN = '0588960d73d71901';
+const TAG_PENDING = '83dfe30d2ef90c8e';
+
+const MAX_DEPTH = 256;
+const MAX_MSG = 4096;
+
+export type OtsOp =
+    | { kind: 'sha256' | 'ripemd160' | 'sha1' | 'keccak256' | 'reverse' | 'hexlify' }
+    | { kind: 'append' | 'prepend'; arg: Uint8Array };
+
+export type OtsAttestation =
+    | { kind: 'bitcoin'; height: number }
+    | { kind: 'pending'; uri: string }
+    | { kind: 'unknown'; tag: string; payload: Uint8Array };
+
+export interface OtsTimestamp {
+    /** The message at this node: the digest after every op on the path to it. */
+    msg: Uint8Array;
+    attestations: OtsAttestation[];
+    ops: { op: OtsOp; child: OtsTimestamp }[];
+}
+
+class Reader {
+    private pos = 0;
+    constructor(private readonly buf: Uint8Array) {}
+    byte(): number {
+        if (this.pos >= this.buf.length) throw new Error('ots: unexpected end of proof');
+        return this.buf[this.pos++]!;
+    }
+    bytes(n: number): Uint8Array {
+        if (n < 0 || this.pos + n > this.buf.length) throw new Error('ots: unexpected end of proof');
+        const out = this.buf.subarray(this.pos, this.pos + n);
+        this.pos += n;
+        return out;
+    }
+    varuint(): number {
+        let value = 0;
+        let shift = 0;
+        for (;;) {
+            const b = this.byte();
+            value += (b & 0x7f) * 2 ** shift;
+            if (!(b & 0x80)) return value;
+            shift += 7;
+            if (shift > 49) throw new Error('ots: varuint too large');
+        }
+    }
+    varbytes(max: number): Uint8Array {
+        const n = this.varuint();
+        if (n > max) throw new Error('ots: varbytes too long');
+        return this.bytes(n);
+    }
+    get done(): boolean {
+        return this.pos === this.buf.length;
+    }
+}
+
+const UNARY: Record<number, OtsOp['kind']> = {
+    0x02: 'sha1',
+    0x03: 'ripemd160',
+    0x08: 'sha256',
+    0x67: 'keccak256',
+    0xf2: 'reverse',
+    0xf3: 'hexlify',
+};
+
+export function applyOp(op: OtsOp, msg: Uint8Array): Uint8Array {
+    switch (op.kind) {
+        case 'sha256':
+            return sha256(msg);
+        case 'ripemd160':
+            return ripemd160(msg);
+        case 'sha1':
+            return sha1(msg);
+        case 'keccak256':
+            return keccak_256(msg);
+        case 'reverse':
+            return new Uint8Array(msg).reverse();
+        case 'hexlify':
+            return new TextEncoder().encode(hexEncode(msg));
+        case 'append':
+            return concat(msg, op.arg);
+        case 'prepend':
+            return concat(op.arg, msg);
+    }
+}
+
+function readOp(r: Reader, tag: number): OtsOp {
+    const unary = UNARY[tag];
+    if (unary) return { kind: unary } as OtsOp;
+    if (tag === 0xf0) return { kind: 'append', arg: r.varbytes(MAX_MSG) };
+    if (tag === 0xf1) return { kind: 'prepend', arg: r.varbytes(MAX_MSG) };
+    throw new Error(`ots: unknown op tag 0x${tag.toString(16)}`);
+}
+
+function readAttestation(r: Reader): OtsAttestation {
+    const tag = hexEncode(r.bytes(8));
+    const payload = r.varbytes(8192);
+    const p = new Reader(payload);
+    if (tag === TAG_BITCOIN) return { kind: 'bitcoin', height: p.varuint() };
+    if (tag === TAG_PENDING) return { kind: 'pending', uri: new TextDecoder().decode(p.varbytes(1000)) };
+    return { kind: 'unknown', tag, payload };
+}
+
+function readTimestamp(r: Reader, msg: Uint8Array, depth: number): OtsTimestamp {
+    if (depth > MAX_DEPTH) throw new Error('ots: proof too deep');
+    const node: OtsTimestamp = { msg, attestations: [], ops: [] };
+    const item = (tag: number) => {
+        if (tag === 0x00) {
+            node.attestations.push(readAttestation(r));
+            return;
+        }
+        const op = readOp(r, tag);
+        const next = applyOp(op, msg);
+        if (next.length > MAX_MSG) throw new Error('ots: message too long');
+        node.ops.push({ op, child: readTimestamp(r, next, depth + 1) });
+    };
+    let tag = r.byte();
+    while (tag === 0xff) {
+        item(r.byte());
+        tag = r.byte();
+    }
+    item(tag);
+    return node;
+}
+
+/** Parse a bare timestamp whose root message is `digest`. */
+export function parseTimestamp(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp {
+    const r = new Reader(bytes);
+    const ts = readTimestamp(r, digest, 0);
+    if (!r.done) throw new Error('ots: trailing bytes after timestamp');
+    return ts;
+}
+
+export function isDetached(bytes: Uint8Array): boolean {
+    return bytes.length > HEADER_MAGIC.length && bytesEqual(bytes.subarray(0, HEADER_MAGIC.length), HEADER_MAGIC);
+}
+
+/** Parse a detached `.ots` file. Only sha256 file digests are accepted. */
+export function parseDetached(bytes: Uint8Array): { digest: Uint8Array; timestamp: OtsTimestamp } {
+    if (!isDetached(bytes)) throw new Error('ots: missing detached-file header');
+    const r = new Reader(bytes.subarray(HEADER_MAGIC.length));
+    const major = r.varuint();
+    if (major !== 1) throw new Error(`ots: unsupported file version ${major}`);
+    if (r.byte() !== 0x08) throw new Error('ots: only sha256 file digests are supported');
+    const digest = new Uint8Array(r.bytes(32));
+    const timestamp = readTimestamp(r, digest, 0);
+    if (!r.done) throw new Error('ots: trailing bytes after timestamp');
+    return { digest, timestamp };
+}
+
+/**
+ * Parse either encoding and require that it commits to `digest`. A detached
+ * file for some other digest is rejected rather than walked.
+ */
+export function parseProof(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp {
+    if (!isDetached(bytes)) return parseTimestamp(bytes, digest);
+    const d = parseDetached(bytes);
+    if (!bytesEqual(d.digest, digest)) throw new Error('ots: proof commits to a different digest');
+    return d.timestamp;
+}
+
+/** Every attestation in the tree with the message it attests to. */
+export function attestations(ts: OtsTimestamp): { msg: Uint8Array; attestation: OtsAttestation }[] {
+    const out: { msg: Uint8Array; attestation: OtsAttestation }[] = [];
+    const walk = (n: OtsTimestamp) => {
+        for (const a of n.attestations) out.push({ msg: n.msg, attestation: a });
+        for (const { child } of n.ops) walk(child);
+    };
+    walk(ts);
+    return out;
+}
+
+/**
+ * Bitcoin attestations, lowest height first. `merkleRoot` is the message at
+ * the attestation, which equals the block header's Merkle root in header
+ * byte order.
+ */
+export function bitcoinAnchors(ts: OtsTimestamp): { blockHeight: number; merkleRoot: Uint8Array }[] {
+    return attestations(ts)
+        .flatMap(({ msg, attestation }) =>
+            attestation.kind === 'bitcoin' ? [{ blockHeight: attestation.height, merkleRoot: msg }] : []
+        )
+        .sort((a, b) => a.blockHeight - b.blockHeight);
+}
+
+/** Pending calendar attestations: where to ask, and the commitment to ask for. */
+export function pendingCommitments(ts: OtsTimestamp): { uri: string; commitment: Uint8Array }[] {
+    return attestations(ts).flatMap(({ msg, attestation }) =>
+        attestation.kind === 'pending' ? [{ uri: attestation.uri, commitment: msg }] : []
+    );
+}
+
+/**
+ * Graft `upgrade` (a timestamp rooted at some node's message) onto the node
+ * with that message, as python-opentimestamps' Timestamp.merge does. Returns
+ * false when no node carries that message.
+ */
+export function mergeAt(ts: OtsTimestamp, upgrade: OtsTimestamp): boolean {
+    if (bytesEqual(ts.msg, upgrade.msg)) {
+        for (const a of upgrade.attestations) {
+            if (!ts.attestations.some((b) => attestationKey(b) === attestationKey(a))) ts.attestations.push(a);
+        }
+        for (const { op, child } of upgrade.ops) {
+            const same = ts.ops.find((o) => opKey(o.op) === opKey(op));
+            if (same) mergeAt(same.child, child);
+            else ts.ops.push({ op, child });
+        }
+        return true;
+    }
+    return ts.ops.some(({ child }) => mergeAt(child, upgrade));
+}
+
+function writeVaruint(out: number[], n: number) {
+    do {
+        let b = n % 128;
+        n = Math.floor(n / 128);
+        if (n > 0) b |= 0x80;
+        out.push(b);
+    } while (n > 0);
+}
+
+function writeVarbytes(out: number[], bytes: Uint8Array) {
+    writeVaruint(out, bytes.length);
+    out.push(...bytes);
+}
+
+const OP_TAG: Record<OtsOp['kind'], number> = {
+    sha1: 0x02,
+    ripemd160: 0x03,
+    sha256: 0x08,
+    keccak256: 0x67,
+    append: 0xf0,
+    prepend: 0xf1,
+    reverse: 0xf2,
+    hexlify: 0xf3,
+};
+
+function writeAttestation(out: number[], a: OtsAttestation) {
+    const payload: number[] = [];
+    let tag: string;
+    if (a.kind === 'bitcoin') {
+        tag = TAG_BITCOIN;
+        writeVaruint(payload, a.height);
+    } else if (a.kind === 'pending') {
+        tag = TAG_PENDING;
+        writeVarbytes(payload, new TextEncoder().encode(a.uri));
+    } else {
+        tag = a.tag;
+        payload.push(...a.payload);
+    }
+    out.push(0x00);
+    for (let i = 0; i < 16; i += 2) out.push(parseInt(tag.slice(i, i + 2), 16));
+    writeVarbytes(out, new Uint8Array(payload));
+}
+
+function writeTimestamp(out: number[], ts: OtsTimestamp) {
+    const items: (() => void)[] = [
+        ...ts.attestations.map((a) => () => writeAttestation(out, a)),
+        ...ts.ops.map(({ op, child }) => () => {
+            out.push(OP_TAG[op.kind]);
+            if (op.kind === 'append' || op.kind === 'prepend') writeVarbytes(out, op.arg);
+            writeTimestamp(out, child);
+        }),
+    ];
+    if (items.length === 0) throw new Error('ots: cannot serialize an empty timestamp node');
+    items.forEach((write, i) => {
+        if (i < items.length - 1) out.push(0xff);
+        write();
+    });
+}
+
+/** Serialize as a bare timestamp (the encoding carried in `ots.proof`). */
+export function serializeTimestamp(ts: OtsTimestamp): Uint8Array {
+    const out: number[] = [];
+    writeTimestamp(out, ts);
+    return new Uint8Array(out);
+}
+
+function attestationKey(a: OtsAttestation): string {
+    if (a.kind === 'bitcoin') return `b:${a.height}`;
+    if (a.kind === 'pending') return `p:${a.uri}`;
+    return `u:${a.tag}:${hexEncode(a.payload)}`;
+}
+
+function opKey(op: OtsOp): string {
+    return 'arg' in op ? `${op.kind}:${hexEncode(op.arg)}` : op.kind;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+    if (a.byteLength !== b.byteLength) return false;
+    for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+    return true;
+}

package/src/submit.test.ts

@@ -73,23 +73,6 @@ describe('upgradeProof', () => {
         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,

package/src/types.ts

@@ -6,7 +6,7 @@ export type OtsProofStatus = 'pending' | 'confirmed';
 
 export interface OtsProof {
     status: OtsProofStatus;
-    /** Raw proof bytes as base64. Opaque at this layer; parsers plug in. */
+    /** OTS timestamp rooted at the envelope id (or a detached .ots file), base64. */
     proof: string;
     /** Calendar URLs that contain this proof, in submission order. */
     calendars: string[];
@@ -33,13 +33,14 @@ export interface CalendarClient {
     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.
+     * Fetch the continuation of a pending proof. `commitment` is the message
+     * at the calendar's pending attestation (see `pendingCommitments`), not
+     * the submitted digest. Returns null if the calendar has nothing yet.
      *
-     * OTS calendar HTTP API: GET <url>/timestamp/<hex(digest)>, returns the
-     * proof bytes or 404.
+     * OTS calendar HTTP API: GET <url>/timestamp/<hex(commitment)>, returns a
+     * timestamp rooted at the commitment, or 404.
      */
-    fetchProof(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
+    fetchProof(commitment: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
 }
 
 export interface AnchorVerificationInput {

package/src/upgrade.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeAnchorVerifier } from './anchor.js';
+import { base64Encode, hexDecode, hexEncode } from './base64.js';
+import { parseDetached, serializeTimestamp, type OtsTimestamp } from './ots.js';
+import {
+    BLOCK_HASH,
+    BLOCK_HEADER_HEX,
+    BLOCK_HEIGHT,
+    HELLO_DIGEST,
+    HELLO_OTS_FILE,
+} from './ots-fixture.test-helper.js';
+import type { BlockHeaderSource, OtsProof } from './types.js';
+import { upgradeProof } from './upgrade.js';
+
+const CAL = 'https://cal.test';
+const chain: BlockHeaderSource = {
+    async getHeaderAt(h) {
+        return h === BLOCK_HEIGHT ? hexDecode(BLOCK_HEADER_HEX) : null;
+    },
+};
+
+// Split the real proof the way a calendar does: the client holds the path to
+// a pending attestation, the calendar later serves the rest from that point.
+function split(depth: number): { pending: OtsTimestamp; rest: OtsTimestamp } {
+    const full = parseDetached(HELLO_OTS_FILE).timestamp;
+    const toBitcoin = (n: OtsTimestamp): boolean =>
+        n.attestations.some((a) => a.kind === 'bitcoin') || n.ops.some((o) => toBitcoin(o.child));
+    const copy: OtsTimestamp = { msg: full.msg, attestations: [], ops: [] };
+    let src = full;
+    let dst = copy;
+    for (let i = 0; i < depth; i++) {
+        const next = src.ops.find((o) => toBitcoin(o.child))!;
+        const child: OtsTimestamp = { msg: next.child.msg, attestations: [], ops: [] };
+        dst.ops.push({ op: next.op, child });
+        src = next.child;
+        dst = child;
+    }
+    dst.attestations.push({ kind: 'pending', uri: CAL });
+    return { pending: copy, rest: src };
+}
+
+function pendingProof(tree: OtsTimestamp, calendars = [CAL]): OtsProof {
+    return {
+        status: 'pending',
+        proof: base64Encode(serializeTimestamp(tree)),
+        calendars,
+        blockHeight: null,
+        blockHash: null,
+        upgradedAt: null,
+    };
+}
+
+function calendarServing(commitment: Uint8Array, body: Uint8Array, seen: string[]) {
+    return (async (url: string) => {
+        seen.push(url);
+        return url === `${CAL}/timestamp/${hexEncode(commitment)}`
+            ? new Response(body)
+            : new Response(null, { status: 404 });
+    }) as unknown as typeof fetch;
+}
+
+describe('upgradeProof', () => {
+    it('asks the calendar for its commitment and returns a proof that verifies', async () => {
+        const { pending, rest } = split(6);
+        const seen: string[] = [];
+        const out = await upgradeProof(pendingProof(pending), HELLO_DIGEST, {
+            headerSource: chain,
+            fetch: calendarServing(rest.msg, serializeTimestamp(rest), seen),
+        });
+        expect(seen).toEqual([`${CAL}/timestamp/${hexEncode(rest.msg)}`]);
+        expect(out.status).toBe('confirmed');
+        expect(out.blockHeight).toBe(BLOCK_HEIGHT);
+        expect(out.blockHash).toBe(BLOCK_HASH);
+        const verify = makeAnchorVerifier({ headerSource: chain });
+        expect(await verify(out.proof, out.blockHeight!, out.blockHash!, HELLO_DIGEST)).toBe(true);
+    });
+
+    it('stays pending when the calendar answer does not reach the block header', async () => {
+        const { pending, rest } = split(6);
+        const bogus: OtsTimestamp = { msg: rest.msg, attestations: [{ kind: 'bitcoin', height: BLOCK_HEIGHT }], ops: [] };
+        const out = await upgradeProof(pendingProof(pending), HELLO_DIGEST, {
+            headerSource: chain,
+            fetch: calendarServing(rest.msg, serializeTimestamp(bogus), []),
+        });
+        expect(out.status).toBe('pending');
+    });
+
+    it('does not contact calendars the proof was not submitted to', async () => {
+        const { pending, rest } = split(6);
+        const seen: string[] = [];
+        await expect(
+            upgradeProof(pendingProof(pending, ['https://other.test']), HELLO_DIGEST, {
+                headerSource: chain,
+                fetch: calendarServing(rest.msg, serializeTimestamp(rest), seen),
+            })
+        ).rejects.toThrow(/no pending attestation/);
+        expect(seen).toEqual([]);
+    });
+
+    it('returns the proof unchanged while the calendar has nothing new', async () => {
+        const { pending } = split(6);
+        const current = pendingProof(pending);
+        const out = await upgradeProof(current, HELLO_DIGEST, {
+            headerSource: chain,
+            fetch: (async () => new Response(null, { status: 404 })) as unknown as typeof fetch,
+        });
+        expect(out).toEqual(current);
+    });
+});

package/src/upgrade.ts

@@ -1,28 +1,37 @@
 // 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).
+// A pending proof ends in calendar attestations, each naming a calendar and
+// the commitment (the message at that leaf) the calendar will later anchor.
+// Calendars index upgrades by that commitment, not by the submitted digest.
+// For each pending leaf we ask its calendar for the continuation, graft it on,
+// and report the proof as confirmed once it reaches a Bitcoin attestation
+// whose block header checks out.
 
+import { blockHashOf } from './anchor.js';
 import { base64Decode, base64Encode, hexDecode } from './base64.js';
 import { createCalendarClient } from './calendar.js';
-import type { CalendarClient, OtsProof } from './types.js';
+import {
+    bitcoinAnchors,
+    bytesEqual,
+    mergeAt,
+    parseProof,
+    parseTimestamp,
+    pendingCommitments,
+    serializeTimestamp,
+} from './ots.js';
+import type { BlockHeaderSource, 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.
+     * Header source used to resolve the anchor's block hash and to check that
+     * the proof's Merkle root is in that block.
+     */
+    headerSource?: BlockHeaderSource;
+    /**
+     * Alternative to `headerSource`: given the merged proof bytes, return the
+     * anchor if the proof is confirmed, else null.
      */
-    parseAnchor: (proofBytes: Uint8Array) => Promise<{ blockHeight: number; blockHash: string } | null>;
+    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. */
@@ -30,73 +39,69 @@ export interface UpgradeOptions {
     signal?: AbortSignal;
 }
 
+const norm = (u: string) => u.replace(/\/+$/, '');
+
 export async function upgradeProof(
     current: OtsProof,
     idHex: string,
     opts: UpgradeOptions
 ): Promise<OtsProof> {
     if (current.status === 'confirmed') return current; // idempotent
+    if (!opts.headerSource && !opts.parseAnchor) {
+        throw new Error('upgradeProof: pass headerSource or parseAnchor');
+    }
 
-    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 before = base64Decode(current.proof);
+    const tree = parseProof(before, hexDecode(idHex));
+
+    // Only ask calendars this proof was submitted to.
+    const listed = new Set(current.calendars.map(norm));
+    const pending = pendingCommitments(tree).filter((p) => listed.has(norm(p.uri)));
+    if (pending.length === 0 && bitcoinAnchors(tree).length === 0) {
+        throw new Error('upgradeProof: proof has no pending attestation from a listed calendar');
     }
 
-    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 };
+    const answered: string[] = [];
+    await Promise.allSettled(
+        pending.map(async ({ uri, commitment }) => {
+            const client = createCalendarClient(uri, { fetch: opts.fetch, timeoutMs: opts.timeoutMs });
+            const bytes = await client.fetchProof(commitment, opts.signal);
+            if (!bytes) return;
+            if (mergeAt(tree, parseTimestamp(bytes, commitment))) answered.push(norm(uri));
         })
     );
 
-    // 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'),
-            };
-        }
-    }
+    const merged = serializeTimestamp(tree);
+    const anchor = await resolveAnchor(merged, tree, opts);
+    const calendars = [...answered, ...current.calendars.filter((c) => !answered.includes(norm(c)))];
 
-    // 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 (anchor) {
+        return {
+            status: 'confirmed',
+            proof: base64Encode(merged),
+            calendars,
+            blockHeight: anchor.blockHeight,
+            blockHash: anchor.blockHash,
+            upgradedAt: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+        };
     }
-    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,
-            };
-        }
+    if (!bytesEqual(merged, before)) {
+        return { ...current, proof: base64Encode(merged), calendars };
     }
     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;
+async function resolveAnchor(
+    merged: Uint8Array,
+    tree: ReturnType<typeof parseTimestamp>,
+    opts: UpgradeOptions
+): Promise<{ blockHeight: number; blockHash: string } | null> {
+    if (opts.parseAnchor) return opts.parseAnchor(merged);
+    for (const a of bitcoinAnchors(tree)) {
+        const header = await opts.headerSource!.getHeaderAt(a.blockHeight);
+        if (header && header.byteLength === 80 && bytesEqual(header.subarray(36, 68), a.merkleRoot)) {
+            return { blockHeight: a.blockHeight, blockHash: blockHashOf(header) };
+        }
+    }
+    return null;
 }