@orangecheck/stamp-ots 0.1.0 → 0.2.0

package/src/calendar.ts

@@ -2,11 +2,9 @@
 // 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
+//   GET  <url>/timestamp/<hex(commitment)>                    -> continuation, 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).
+// The client moves bytes only; ./ots.ts parses them.
 
 import type { CalendarClient } from './types.js';
 import { hexEncode } from './base64.js';
@@ -62,12 +60,12 @@ export function createCalendarClient(url: string, opts: HttpCalendarOptions = {}
             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');
+        async fetchProof(commitment, signal) {
+            if (commitment.byteLength === 0 || commitment.byteLength > 64) {
+                throw new Error('OTS: commitment must be 1-64 bytes');
             }
             const ac = withTimeout(signal, timeoutMs);
-            const resp = await fetchImpl(`${base}/timestamp/${hexEncode(digest)}`, {
+            const resp = await fetchImpl(`${base}/timestamp/${hexEncode(commitment)}`, {
                 method: 'GET',
                 headers: { Accept: 'application/vnd.opentimestamps.v1' },
                 signal: ac.signal,

package/src/index.ts

@@ -6,5 +6,22 @@ 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';
+export {
+    blockHashOf,
+    makeAnchorVerifier,
+    makeDefaultAnchorVerifier,
+    mempoolHeaderSource,
+    walkOtsProof,
+} from './anchor.js';
+export type { AnchorVerifierConfig, MempoolHeaderSourceOptions } from './anchor.js';
+export {
+    attestations,
+    bitcoinAnchors,
+    mergeAt,
+    parseDetached,
+    parseProof,
+    parseTimestamp,
+    pendingCommitments,
+    serializeTimestamp,
+} from './ots.js';
+export type { OtsAttestation, OtsOp, OtsTimestamp } from './ots.js';

package/src/ots-fixture.test-helper.ts

@@ -0,0 +1,24 @@
+// A real OpenTimestamps proof: opentimestamps-client examples/hello-world.txt.ots,
+// committing to sha256("Hello World!\n") and anchored in Bitcoin block 358391.
+
+import { base64Decode } from './base64.js';
+
+export const HELLO_DIGEST = '03ba204e50d126e4674c005e04d82e84c21366780af1f43bd54a37816b6ab340';
+
+export const HELLO_OTS_FILE = base64Decode(
+    'AE9wZW5UaW1lc3RhbXBzAABQcm9vZgC/ieLohOiSlAEIA7ogTlDRJuRnTABeBNguhMITZngK8fQ71Uo3gWtqs0AD' +
+    '8cgBAQAAAAHkgvnTLsw7ple2nYmAEIV7VEV6kEl5gv9W+XxOxY5vmAEAAABrSDBFAiEAslOt0dHPkIRDOKR1oE/x' +
+    'P8nnvSQrB3Yt6gf1YIst42cCIACyaMqcM0KzdpzdBiiRMXzc74eqwxC2hV6dk4mOu+jsASECDY5NEH0rM5sAUO/d' +
+    'S0oJJFqgVgSPElOWN06moqsHCcb/////AmUz5gUAAAAAGXapFAvwV9QPu6Z0SGJRX1tVojEN5XcviKyghgEAAAAA' +
+    'ABl2qRTwBoisAAAAAAgI8SCph/cWxTORPDFMeONdNYhMrJQ/pCysSdKyxp9AA/hfiAgI8SDexVs0h+Hj9yKkm1Wn' +
+    'eDIVhieF9KOss5KEYBn3HcZKnQgI8SCyyhj0heCAR44CXas9RktBbA4ey2Ypya786MghTQQkMggI8CARsOkGYRlv' +
+    '9LCBPD7aFBurXpFgSDe996DJ3zfbDjoRmAgI8CDDS8GkoQk//RSMAWseZkdCkU6Tnvq+TT01ZRWRSybZ4ggI8CDD' +
+    '5ufDjGn2ryTCvjTrrEglft5h7AohuVNeREMne+MGRggI8SAHmL+GBuAAJOXV1UvwyWD2Kd+52taRV0VbbyZSwOje' +
+    'gQgI8CA/mtptYLqiRABrsKrVFEitL6+51LZIegmZz/JrkfD1NggI8SDHAwGelZqN0/rvdIm7MoukhVdHWOcJHwFG' +
+    'TrZYcsl1yAgI8CDL/v/1E/+EuRXj/tb515lnZjD4Nk6ipsdVf62UpbXXiAgI8SAL4jcJhZkTur1EYLvd+O0hPnyH' +
+    'c6Sx+s4w+Kz98JO3BQgIAAWIlg1z1xkBA/fvFQ==');
+
+export const BLOCK_HEIGHT = 358391;
+export const BLOCK_HASH = '000000000000000003e892881a8cdcdc117c06d444057c98b6f04a9ee75a2319';
+export const BLOCK_HEADER_HEX =
+    '02000000b96394585a281b7e5f438fd1c9ed492645a1fd61cb3802040000000000000000007ee445d23ad061af4a36b809501fab1ac4f2d7e7a739817dd0cbb7ec661b8a1e376755f58616186272def6';

package/src/ots.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { hexDecode, hexEncode } from './base64.js';
+import { bitcoinAnchors, parseDetached, parseProof, serializeTimestamp } from './ots.js';
+import { BLOCK_HEADER_HEX, BLOCK_HEIGHT, HELLO_DIGEST, HELLO_OTS_FILE } from './ots-fixture.test-helper.js';
+
+describe('OTS proof parsing', () => {
+    it('walks a detached proof to the Merkle root in the attested block header', () => {
+        const { digest, timestamp } = parseDetached(HELLO_OTS_FILE);
+        expect(hexEncode(digest)).toBe(HELLO_DIGEST);
+        const [anchor] = bitcoinAnchors(timestamp);
+        expect(anchor?.blockHeight).toBe(BLOCK_HEIGHT);
+        expect(hexEncode(anchor!.merkleRoot)).toBe(BLOCK_HEADER_HEX.slice(72, 136));
+    });
+
+    it('serializes a parsed timestamp back to the same bytes', () => {
+        const { timestamp } = parseDetached(HELLO_OTS_FILE);
+        const bare = serializeTimestamp(timestamp);
+        expect(hexEncode(bare)).toBe(hexEncode(HELLO_OTS_FILE.subarray(HELLO_OTS_FILE.length - bare.length)));
+    });
+
+    it('accepts the bare timestamp encoding rooted at the digest', () => {
+        const bare = serializeTimestamp(parseDetached(HELLO_OTS_FILE).timestamp);
+        expect(bitcoinAnchors(parseProof(bare, hexDecode(HELLO_DIGEST)))[0]?.blockHeight).toBe(BLOCK_HEIGHT);
+    });
+
+    it('refuses a detached proof for a different digest', () => {
+        expect(() => parseProof(HELLO_OTS_FILE, hexDecode('00'.repeat(32)))).toThrow(/different digest/);
+    });
+
+    it('rejects truncated proofs', () => {
+        expect(() => parseDetached(HELLO_OTS_FILE.subarray(0, HELLO_OTS_FILE.length - 5))).toThrow();
+    });
+});

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);
+    });
+});