@orangecheck/stamp-ots 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # @orangecheck/stamp-ots
 
+> **Full reference:** [docs.ochk.io/sdk/stamp-ots](https://docs.ochk.io/sdk/stamp-ots) — auto-generated from the TypeScript source on every release.
+> Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
+
+
 OpenTimestamps calendar client, proof helpers, and anchor-verification hooks for [OC Stamp](https://github.com/orangecheck/oc-stamp-protocol) envelopes.
 
 ## Install
@@ -13,31 +17,24 @@ npm i @orangecheck/stamp-core @orangecheck/stamp-ots
 OC Stamp envelopes carry an optional `ots` field that anchors the envelope `id` to a Bitcoin block via the [OpenTimestamps](https://opentimestamps.org) protocol. This package provides the thin client-side glue:
 
 - **`submitToCalendars(id, opts)`** — POST the envelope's 32-byte digest to one or more OTS calendars. Returns a pending `OtsProof` you can fold into the envelope's `ots` field.
-- **`upgradeProof(proof, id, opts)`** — poll calendars for an upgraded proof once OTS has anchored the containing batch to a Bitcoin block. Returns a confirmed `OtsProof` when available.
-- **`createCalendarClient(url)`** — low-level HTTP client implementing the minimal OTS calendar API (`POST /digest`, `GET /timestamp/<hex>`).
-- **`makeAnchorVerifier({ walkProof, headerSource })`** — adapter that turns a proof-parser plus a block-header source into a function `verify()` (from `@orangecheck/stamp-core`) can call via its `verifyOtsAnchor` parameter.
-
-## What it does NOT do
+- **`upgradeProof(proof, id, { headerSource })`** — ask each calendar for the continuation of its pending attestation (calendars index upgrades by that commitment) and graft it on. Returns a confirmed `OtsProof` once the proof reaches a Bitcoin block whose header checks out.
+- **`createCalendarClient(url)`** — low-level HTTP client implementing the minimal OTS calendar API (`POST /digest`, `GET /timestamp/<hex(commitment)>`).
+- **`makeAnchorVerifier({ headerSource })`** — the `verifyOtsAnchor` hook for `verify()` from `@orangecheck/stamp-core`. It walks the proof with the built-in OTS parser and requires that the proof commits to the envelope id, attests at the declared height, and that the header at that height has the proof's Merkle root and hashes to the declared block hash.
+- **`mempoolHeaderSource(opts)`** — block headers from an Esplora-compatible API (default `https://mempool.space/api`). Each header is checked against the declared block hash, so this source is trusted only to say which block sits at a height. Supply your own node or headers snapshot to remove that trust.
+- **`parseProof` / `parseDetached` / `serializeTimestamp` / `bitcoinAnchors` / `pendingCommitments`** — the OTS proof format, accepting both the bare timestamp carried in `ots.proof` and detached `.ots` files.
 
-This package does **not** ship a full OpenTimestamps proof parser. Parsing the binary proof format (Merkle path chunks, calendar attestations, Bitcoin attestations) requires a larger, maintained library like `javascript-opentimestamps`. We keep this package's dependency surface narrow and expose `walkProof` as a plug-in point.
-
-Consumers who want fully-offline verification should combine:
+## Verify an anchor
 
 ```ts
 import { verify } from '@orangecheck/stamp-core';
-import { makeAnchorVerifier, adaptAnchorVerifier, base64Decode, hexDecode } from '@orangecheck/stamp-ots';
-import { myOtsParser, myHeaderSource } from './your-adapters';
-
-const anchor = makeAnchorVerifier({
-    walkProof: myOtsParser,
-    headerSource: myHeaderSource,
-});
+import { makeAnchorVerifier, mempoolHeaderSource } from '@orangecheck/stamp-ots';
 
 const result = await verify({
     envelope: env,
-    verifyOtsAnchor: adaptAnchorVerifier(anchor, (blockHash) => hexDecode(env.id)),
+    verifyOtsAnchor: makeAnchorVerifier({ headerSource: mempoolHeaderSource() }),
     verifyBip322: myBip322Verifier,
 });
+// result.anchor.verified is true only when the proof checked out.
 ```
 
 ## Usage
@@ -57,11 +54,11 @@ const envWithOts = { ...env, ots: toStampOts(proof) };
 ### Upgrade later
 
 ```ts
-import { upgradeProof, fromStampOts, toStampOts } from '@orangecheck/stamp-ots';
+import { fromStampOts, mempoolHeaderSource, toStampOts, upgradeProof } from '@orangecheck/stamp-ots';
 
 const current = fromStampOts(envWithOts.ots!);
 const upgraded = await upgradeProof(current, envWithOts.id, {
-    parseAnchor: myOtsParser, // plug in your OTS proof parser
+    headerSource: mempoolHeaderSource(),
 });
 const envUpgraded = { ...envWithOts, ots: toStampOts(upgraded) };
 ```
@@ -70,7 +67,8 @@ const envUpgraded = { ...envWithOts, ots: toStampOts(upgraded) };
 
 - `submitToCalendars(id, opts)` / `upgradeProof(proof, id, opts)`
 - `createCalendarClient(url, opts)` / `DEFAULT_CALENDARS`
-- `makeAnchorVerifier(config)` / `adaptAnchorVerifier(verifier, digestLookup)`
+- `makeAnchorVerifier(config)` / `makeDefaultAnchorVerifier(config)` / `mempoolHeaderSource(opts)` / `walkOtsProof(input)` / `blockHashOf(header)`
+- `parseProof` / `parseDetached` / `parseTimestamp` / `serializeTimestamp` / `bitcoinAnchors` / `pendingCommitments` / `mergeAt` / `attestations`
 - `toStampOts(proof)` / `fromStampOts(stampOts)` — shape adapters
 - `base64Encode` / `base64Decode` / `hexEncode` / `hexDecode`
 - Types: `OtsProof`, `CalendarClient`, `AnchorVerifier`, `BlockHeaderSource`, etc.

package/dist/index.d.mts

@@ -12,7 +12,7 @@ interface OtsProof {
 interface CalendarClient {
     readonly url: string;
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;
-    fetchProof(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
+    fetchProof(commitment: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
 }
 interface AnchorVerificationInput {
     proofBytes: Uint8Array;
@@ -57,7 +57,8 @@ interface SubmitOptions {
 declare function submitToCalendars(idHex: string, opts?: SubmitOptions): Promise<OtsProof>;
 
 interface UpgradeOptions {
-    parseAnchor: (proofBytes: Uint8Array) => Promise<{
+    headerSource?: BlockHeaderSource;
+    parseAnchor?: (proofBytes: Uint8Array) => Promise<{
         blockHeight: number;
         blockHash: string;
     } | null>;
@@ -68,16 +69,79 @@ interface UpgradeOptions {
 declare function upgradeProof(current: OtsProof, idHex: string, opts: UpgradeOptions): Promise<OtsProof>;
 
 interface AnchorVerifierConfig {
-    walkProof: (input: {
+    walkProof?: (input: {
         proofBytes: Uint8Array;
         digest: Uint8Array;
+        blockHeight?: number;
     }) => Promise<{
         merkleRoot: Uint8Array;
         blockHeight: number;
     } | null>;
     headerSource: BlockHeaderSource;
 }
-declare function makeAnchorVerifier(cfg: AnchorVerifierConfig): AnchorVerifier;
-declare function adaptAnchorVerifier(verifier: AnchorVerifier, digestLookup: (blockHash: string) => Uint8Array): (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
+declare function walkOtsProof(input: {
+    proofBytes: Uint8Array;
+    digest: Uint8Array;
+    blockHeight?: number;
+}): Promise<{
+    merkleRoot: Uint8Array;
+    blockHeight: number;
+} | null>;
+declare function blockHashOf(header: Uint8Array): string;
+declare function makeAnchorVerifier(cfg: AnchorVerifierConfig): (proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean>;
+declare function makeDefaultAnchorVerifier(opts: {
+    headerSource: BlockHeaderSource;
+}): Promise<(proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean>>;
+interface MempoolHeaderSourceOptions {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function mempoolHeaderSource(opts?: MempoolHeaderSourceOptions): BlockHeaderSource;
+
+type OtsOp = {
+    kind: 'sha256' | 'ripemd160' | 'sha1' | 'keccak256' | 'reverse' | 'hexlify';
+} | {
+    kind: 'append' | 'prepend';
+    arg: Uint8Array;
+};
+type OtsAttestation = {
+    kind: 'bitcoin';
+    height: number;
+} | {
+    kind: 'pending';
+    uri: string;
+} | {
+    kind: 'unknown';
+    tag: string;
+    payload: Uint8Array;
+};
+interface OtsTimestamp {
+    msg: Uint8Array;
+    attestations: OtsAttestation[];
+    ops: {
+        op: OtsOp;
+        child: OtsTimestamp;
+    }[];
+}
+declare function parseTimestamp(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp;
+declare function parseDetached(bytes: Uint8Array): {
+    digest: Uint8Array;
+    timestamp: OtsTimestamp;
+};
+declare function parseProof(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp;
+declare function attestations(ts: OtsTimestamp): {
+    msg: Uint8Array;
+    attestation: OtsAttestation;
+}[];
+declare function bitcoinAnchors(ts: OtsTimestamp): {
+    blockHeight: number;
+    merkleRoot: Uint8Array;
+}[];
+declare function pendingCommitments(ts: OtsTimestamp): {
+    uri: string;
+    commitment: Uint8Array;
+}[];
+declare function mergeAt(ts: OtsTimestamp, upgrade: OtsTimestamp): boolean;
+declare function serializeTimestamp(ts: OtsTimestamp): Uint8Array;
 
-export { type AnchorVerificationInput, type AnchorVerificationResult, type AnchorVerifier, type AnchorVerifierConfig, type BlockHeaderSource, type CalendarClient, DEFAULT_CALENDARS, type HttpCalendarOptions, type OtsProof, type OtsProofStatus, type SubmitOptions, type UpgradeOptions, adaptAnchorVerifier, base64Decode, base64Encode, createCalendarClient, fromStampOts, hexDecode, hexEncode, makeAnchorVerifier, submitToCalendars, toStampOts, upgradeProof };
+export { type AnchorVerificationInput, type AnchorVerificationResult, type AnchorVerifier, type AnchorVerifierConfig, type BlockHeaderSource, type CalendarClient, DEFAULT_CALENDARS, type HttpCalendarOptions, type MempoolHeaderSourceOptions, type OtsAttestation, type OtsOp, type OtsProof, type OtsProofStatus, type OtsTimestamp, type SubmitOptions, type UpgradeOptions, attestations, base64Decode, base64Encode, bitcoinAnchors, blockHashOf, createCalendarClient, fromStampOts, hexDecode, hexEncode, makeAnchorVerifier, makeDefaultAnchorVerifier, mempoolHeaderSource, mergeAt, parseDetached, parseProof, parseTimestamp, pendingCommitments, serializeTimestamp, submitToCalendars, toStampOts, upgradeProof, walkOtsProof };

package/dist/index.d.ts

@@ -12,7 +12,7 @@ interface OtsProof {
 interface CalendarClient {
     readonly url: string;
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;
-    fetchProof(digest: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
+    fetchProof(commitment: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | null>;
 }
 interface AnchorVerificationInput {
     proofBytes: Uint8Array;
@@ -57,7 +57,8 @@ interface SubmitOptions {
 declare function submitToCalendars(idHex: string, opts?: SubmitOptions): Promise<OtsProof>;
 
 interface UpgradeOptions {
-    parseAnchor: (proofBytes: Uint8Array) => Promise<{
+    headerSource?: BlockHeaderSource;
+    parseAnchor?: (proofBytes: Uint8Array) => Promise<{
         blockHeight: number;
         blockHash: string;
     } | null>;
@@ -68,16 +69,79 @@ interface UpgradeOptions {
 declare function upgradeProof(current: OtsProof, idHex: string, opts: UpgradeOptions): Promise<OtsProof>;
 
 interface AnchorVerifierConfig {
-    walkProof: (input: {
+    walkProof?: (input: {
         proofBytes: Uint8Array;
         digest: Uint8Array;
+        blockHeight?: number;
     }) => Promise<{
         merkleRoot: Uint8Array;
         blockHeight: number;
     } | null>;
     headerSource: BlockHeaderSource;
 }
-declare function makeAnchorVerifier(cfg: AnchorVerifierConfig): AnchorVerifier;
-declare function adaptAnchorVerifier(verifier: AnchorVerifier, digestLookup: (blockHash: string) => Uint8Array): (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
+declare function walkOtsProof(input: {
+    proofBytes: Uint8Array;
+    digest: Uint8Array;
+    blockHeight?: number;
+}): Promise<{
+    merkleRoot: Uint8Array;
+    blockHeight: number;
+} | null>;
+declare function blockHashOf(header: Uint8Array): string;
+declare function makeAnchorVerifier(cfg: AnchorVerifierConfig): (proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean>;
+declare function makeDefaultAnchorVerifier(opts: {
+    headerSource: BlockHeaderSource;
+}): Promise<(proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean>>;
+interface MempoolHeaderSourceOptions {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function mempoolHeaderSource(opts?: MempoolHeaderSourceOptions): BlockHeaderSource;
+
+type OtsOp = {
+    kind: 'sha256' | 'ripemd160' | 'sha1' | 'keccak256' | 'reverse' | 'hexlify';
+} | {
+    kind: 'append' | 'prepend';
+    arg: Uint8Array;
+};
+type OtsAttestation = {
+    kind: 'bitcoin';
+    height: number;
+} | {
+    kind: 'pending';
+    uri: string;
+} | {
+    kind: 'unknown';
+    tag: string;
+    payload: Uint8Array;
+};
+interface OtsTimestamp {
+    msg: Uint8Array;
+    attestations: OtsAttestation[];
+    ops: {
+        op: OtsOp;
+        child: OtsTimestamp;
+    }[];
+}
+declare function parseTimestamp(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp;
+declare function parseDetached(bytes: Uint8Array): {
+    digest: Uint8Array;
+    timestamp: OtsTimestamp;
+};
+declare function parseProof(bytes: Uint8Array, digest: Uint8Array): OtsTimestamp;
+declare function attestations(ts: OtsTimestamp): {
+    msg: Uint8Array;
+    attestation: OtsAttestation;
+}[];
+declare function bitcoinAnchors(ts: OtsTimestamp): {
+    blockHeight: number;
+    merkleRoot: Uint8Array;
+}[];
+declare function pendingCommitments(ts: OtsTimestamp): {
+    uri: string;
+    commitment: Uint8Array;
+}[];
+declare function mergeAt(ts: OtsTimestamp, upgrade: OtsTimestamp): boolean;
+declare function serializeTimestamp(ts: OtsTimestamp): Uint8Array;
 
-export { type AnchorVerificationInput, type AnchorVerificationResult, type AnchorVerifier, type AnchorVerifierConfig, type BlockHeaderSource, type CalendarClient, DEFAULT_CALENDARS, type HttpCalendarOptions, type OtsProof, type OtsProofStatus, type SubmitOptions, type UpgradeOptions, adaptAnchorVerifier, base64Decode, base64Encode, createCalendarClient, fromStampOts, hexDecode, hexEncode, makeAnchorVerifier, submitToCalendars, toStampOts, upgradeProof };
+export { type AnchorVerificationInput, type AnchorVerificationResult, type AnchorVerifier, type AnchorVerifierConfig, type BlockHeaderSource, type CalendarClient, DEFAULT_CALENDARS, type HttpCalendarOptions, type MempoolHeaderSourceOptions, type OtsAttestation, type OtsOp, type OtsProof, type OtsProofStatus, type OtsTimestamp, type SubmitOptions, type UpgradeOptions, attestations, base64Decode, base64Encode, bitcoinAnchors, blockHashOf, createCalendarClient, fromStampOts, hexDecode, hexEncode, makeAnchorVerifier, makeDefaultAnchorVerifier, mempoolHeaderSource, mergeAt, parseDetached, parseProof, parseTimestamp, pendingCommitments, serializeTimestamp, submitToCalendars, toStampOts, upgradeProof, walkOtsProof };