@forestrie/receipt-verify 3.0.1 → 3.2.0

package/src/verify-grant-receipt-offline.ts

@@ -7,7 +7,9 @@ import {
 import type { Grant } from "@forestrie/encoding";
 import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
-import { es256ReceiptVerifyKeys } from "./decode-trust-root-cbor.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
 import {
   checkDelegationConstraints,
   resolveDelegatedVerifyKey,
@@ -16,12 +18,17 @@ import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
 import { SubtleHasher } from "./subtle-hasher.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
 
 export type VerifyGrantReceiptOfflineInput = {
   genesisCbor: Uint8Array;
   receiptCbor: Uint8Array;
   grant: Grant;
   idtimestampBe8: Uint8Array;
+  /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
+  ks256Attestation?: Ks256Attestation;
+  /** See {@link VerifyReceiptOfflineInput.ks256Attestations}. */
+  ks256Attestations?: readonly Ks256Attestation[];
 };
 
 function readIdtimestampBe8(bytes: Uint8Array): bigint {
@@ -116,16 +123,15 @@ export async function verifyGrantReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
+    ks256Attestations: attestationCandidates(input),
   });
 }
 
 export type VerifyGrantReceiptOfflineWithKeysInput = Omit<
   VerifyGrantReceiptOfflineInput,
   "genesisCbor"
-> & {
-  /** Caller-known ES256 trust keys — see {@link VerifyReceiptOfflineWithKeysInput}. */
-  trustKeys: CryptoKey[];
-};
+> &
+  Pick<VerifyReceiptOfflineWithKeysInput, "trustKeys" | "forestGenesisCbor">;
 
 /**
  * {@link verifyGrantReceiptOffline} under caller-supplied trust keys instead of
@@ -146,6 +152,10 @@ export async function verifyGrantReceiptOfflineWithKeys(
     idtimestampBe8: input.idtimestampBe8,
     inner,
     trustKeys: input.trustKeys,
+    ks256Attestations: attestationCandidates(input),
+    forestChainId: input.forestGenesisCbor
+      ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+      : undefined,
   });
 }
 
@@ -160,6 +170,21 @@ export type VerifyReceiptOfflineInput = {
    */
   payload: Uint8Array;
   idtimestampBe8: Uint8Array;
+  /**
+   * ERC-1271 attestation for a KS256 contract root (plan-2610-03 D4). Used
+   * only when ecrecover doesn't match the root, and accepted only when it
+   * binds the root address, the certificate digest and the genesis chain id.
+   */
+  ks256Attestation?: Ks256Attestation;
+  /**
+   * Several attestations (owner ruling D8): the one whose digest and
+   * signature hash match the receipt's certificate is used
+   * ({@link selectKs256Attestation}). Combined with
+   * {@link ks256Attestation} when both are given. When none matches, one
+   * still reaches the KS256 check only to name the mismatch: it can never
+   * verify the certificate.
+   */
+  ks256Attestations?: readonly Ks256Attestation[];
 };
 
 /**
@@ -183,6 +208,7 @@ export async function verifyReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
+    ks256Attestations: attestationCandidates(input),
   });
 }
 
@@ -191,12 +217,19 @@ export type VerifyReceiptOfflineWithKeysInput = Omit<
   "genesisCbor"
 > & {
   /**
-   * Caller-known ES256 trust keys, tried in order. For a child-log receipt
+   * Caller-known trust keys, tried in order: ES256 `CryptoKey`s or KS256
+   * 20-byte addresses ({@link knownLogKeyFromBytes}). For a child-log receipt
    * this is the log OWNER's key (the delegation-cert issuer), NOT the sealer
    * key — the label-1000 cert is verified under these keys and the delegated
    * sealer key is extracted from it, so the anchor survives sealer rotation.
    */
-  trustKeys: CryptoKey[];
+  trustKeys: RootVerifyKey[];
+  /**
+   * The forest's genesis, read only for the chain id a `ks256Attestation`
+   * must match (D6); it supplies no trust keys. Without it an attestation is
+   * refused with `ks256_attestation_chain_unbound`.
+   */
+  forestGenesisCbor?: Uint8Array;
 };
 
 /**
@@ -230,9 +263,41 @@ export async function verifyReceiptOfflineWithKeys(
     idtimestampBe8: input.idtimestampBe8,
     inner,
     trustKeys: input.trustKeys,
+    ks256Attestations: attestationCandidates(input),
+    forestChainId: input.forestGenesisCbor
+      ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+      : undefined,
   });
 }
 
+/**
+ * Every attestation the caller supplied: the list, then the singular field
+ * (kept for 3.1.0 callers).
+ */
+function attestationCandidates(input: {
+  ks256Attestation?: Ks256Attestation | undefined;
+  ks256Attestations?: readonly Ks256Attestation[] | undefined;
+}): Ks256Attestation[] {
+  return [
+    ...(input.ks256Attestations ?? []),
+    ...(input.ks256Attestation ? [input.ks256Attestation] : []),
+  ];
+}
+
+/**
+ * The forest's chain id from its genesis chain binding, or `undefined` when
+ * the genesis carries none (an attestation then can't be bound, D6).
+ */
+function genesisChainIdOrUndefined(
+  genesisCbor: Uint8Array,
+): bigint | undefined {
+  try {
+    return BigInt(decodeChainBindingFromGenesis(genesisCbor).chainId);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Shared offline-verify core: reconstruct the leaf as
  * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
@@ -245,37 +310,40 @@ async function verifyReceiptOfflineWithLeafInner(input: {
   receiptCbor: Uint8Array;
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
+  ks256Attestations: Ks256Attestation[];
 }): Promise<ReceiptVerifyResult> {
-  let trustRoot;
+  let trustRoot: RootVerifyKey;
   try {
     trustRoot = await decodeTrustRootFromGenesis(input.genesisCbor);
   } catch {
     return { ok: false, stage: "parse", reason: "genesis_invalid" };
   }
 
-  const verifyKeys = es256ReceiptVerifyKeys([trustRoot]) as CryptoKey[];
-  if (!verifyKeys.length) {
-    return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
-  }
-
   return verifyReceiptOfflineWithLeafInnerKeys({
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner: input.inner,
-    trustKeys: verifyKeys,
+    trustKeys: [trustRoot],
+    ks256Attestations: input.ks256Attestations,
+    forestChainId: genesisChainIdOrUndefined(input.genesisCbor),
   });
 }
 
 /**
  * Trust-key-parameterised offline-verify core. Identical to the genesis path
  * once the trust keys are in hand: resolve the (possibly delegated, FOR-297)
- * verify key against `trustKeys`, then check signature + inclusion.
+ * verify key against `trustKeys`, then check signature + inclusion. Receipts
+ * are always ES256, so a KS256 trust key only ever verifies the delegation
+ * certificate; only ES256 trust keys are tried on the receipt itself.
  */
 async function verifyReceiptOfflineWithLeafInnerKeys(input: {
   receiptCbor: Uint8Array;
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
-  trustKeys: CryptoKey[];
+  trustKeys: RootVerifyKey[];
+  ks256Attestations: Ks256Attestation[];
+  /** The forest genesis chain id an attestation must carry, if known. */
+  forestChainId: bigint | undefined;
 }): Promise<ReceiptVerifyResult> {
   let parsed: ReturnType<typeof parseReceipt>;
   try {
@@ -293,17 +361,38 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input: {
   // delegated key first. A cert present but not chaining to a trust key is a
   // hard failure — do not silently fall back to the trust key (which cannot
   // verify a delegated-signed receipt anyway).
-  const delegation = await resolveDelegatedVerifyKey(
+  // D8: the attestations made for THIS receipt's certificate (digest and
+  // signature hash), tried in order; none matching, a stand-in only names
+  // the mismatch.
+  const { resolution: delegation } = await resolveWithKs256Attestations(
     input.receiptCbor,
     input.trustKeys,
+    input.ks256Attestations,
+    input.forestChainId,
   );
   if (delegation.kind === "broken") {
-    return { ok: false, stage: "signature", reason: "delegation_invalid" };
+    return {
+      ok: false,
+      stage: "signature",
+      reason: delegation.reason ?? "delegation_invalid",
+    };
+  }
+  const es256TrustKeys = input.trustKeys.filter(
+    (k): k is CryptoKey => !isParsedKs256RootKey(k),
+  );
+  if (delegation.kind === "root-only" && !es256TrustKeys.length) {
+    // A KS256 root never signs a receipt; without a certificate there is no
+    // ES256 key to check it with.
+    return {
+      ok: false,
+      stage: "signature",
+      reason: "ks256_root_requires_delegation",
+    };
   }
   const allVerifyKeys =
     delegation.kind === "resolved"
-      ? [delegation.delegatedKey, ...input.trustKeys]
-      : input.trustKeys;
+      ? [delegation.delegatedKey, ...es256TrustKeys]
+      : es256TrustKeys;
 
   let idtimestamp: bigint;
   try {

package/src/verify-ks256-delegation.ts

@@ -0,0 +1,120 @@
+/**
+ * Offline KS256 root → delegation certificate check (plan-2610-03 D4, D5;
+ * protocol ADR-0045 amendment 2026-10-18). Receipts are always ES256, signed
+ * by a sealer's P-256 delegated key; what a KS256 root changes is how the
+ * label-1000 delegation certificate is checked against it.
+ *
+ * - An EOA root verifies by ecrecover through `@forestrie/delegation-cose`'s
+ *   `verifyDelegationCertificateKs256` with no hooks: pure, the same guarantee
+ *   as an ES256 root. delegation-cose also enforces the KS256 alg binding.
+ * - Anything ecrecover doesn't match (a contract root such as a Safe, or a
+ *   wrong signer: offline you can't tell which) fails with
+ *   `ks256_root_not_recovered`, unless the caller supplies an ERC-1271
+ *   attestation (ks256-attestation.ts) bound to this root, this digest, this
+ *   signature and the forest's genesis chain.
+ *
+ * No network and no injected callback: the chain read is a separate helper's
+ * job (forestrie-cli, mcp-resolve), as for the known accumulator.
+ */
+
+import { coseUnprotectedToMap, decodeCoseSign1 } from "@forestrie/encoding";
+import {
+  extractKs256CertificateDigest,
+  verifyDelegationCertificateKs256,
+  type Ks256CertificateDigest,
+} from "@forestrie/delegation-cose";
+import { keccak_256 } from "@noble/hashes/sha3";
+import {
+  ERC1271_MAGIC_VALUE,
+  type Ks256Attestation,
+} from "./ks256-attestation.js";
+
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+
+/**
+ * Chain evidence a caller may supply for a KS256 contract root. `forestChainId`
+ * is read from the forest's genesis, never from the attestation or a
+ * coordinator; an attestation without it is refused.
+ */
+export type Ks256DelegationEvidence = {
+  attestation?: Ks256Attestation | undefined;
+  forestChainId?: bigint | undefined;
+};
+
+/**
+ * Check a delegation certificate against a KS256 root address.
+ *
+ * @param certBytes - The receipt's label-1000 COSE_Sign1 certificate.
+ * @param rootAddress - 20-byte root from genesis or a caller-known log key.
+ * @param evidence - Optional ERC-1271 attestation and the genesis chain id.
+ * @returns `ok`, or a stable reason: `delegation_not_ks256` (wrong alg,
+ *   WebAuthn envelope or malformed), `ks256_root_not_recovered`, or a
+ *   `ks256_attestation_*` mismatch.
+ */
+export async function verifyKs256DelegationCert(
+  certBytes: Uint8Array,
+  rootAddress: Uint8Array,
+  evidence: Ks256DelegationEvidence,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  let parts: Ks256CertificateDigest;
+  try {
+    parts = extractKs256CertificateDigest(certBytes);
+  } catch {
+    return { ok: false, reason: "delegation_not_ks256" };
+  }
+  if (await verifyDelegationCertificateKs256(certBytes, rootAddress)) {
+    return { ok: true };
+  }
+  const { attestation, forestChainId } = evidence;
+  if (!attestation) {
+    return { ok: false, reason: "ks256_root_not_recovered" };
+  }
+  if (!bytesEqual(attestation.address, rootAddress)) {
+    return { ok: false, reason: "ks256_attestation_address_mismatch" };
+  }
+  if (!bytesEqual(attestation.digest, parts.digest)) {
+    return { ok: false, reason: "ks256_attestation_digest_mismatch" };
+  }
+  if (!bytesEqual(attestation.signatureHash, keccak_256(parts.signature))) {
+    return { ok: false, reason: "ks256_attestation_signature_mismatch" };
+  }
+  if (forestChainId === undefined) {
+    return { ok: false, reason: "ks256_attestation_chain_unbound" };
+  }
+  if (attestation.chainId !== forestChainId) {
+    return { ok: false, reason: "ks256_attestation_chain_mismatch" };
+  }
+  if (!bytesEqual(attestation.magic, ERC1271_MAGIC_VALUE)) {
+    return { ok: false, reason: "ks256_attestation_magic_invalid" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Extract the KS256 delegation certificate's root address, digest and
+ * signature from a receipt: what an ERC-1271 attestation helper calls
+ * `isValidSignature` with. Does not verify anything.
+ *
+ * @param receiptCbor - COSE_Sign1 receipt bytes.
+ * @returns `null` when the receipt carries no label-1000 certificate.
+ * @throws When the certificate is not a KS256 certificate.
+ */
+export function extractKs256DelegationDigest(
+  receiptCbor: Uint8Array,
+): Ks256CertificateDigest | null {
+  const decoded = decodeCoseSign1(receiptCbor);
+  if (!decoded) throw new Error("receipt is not a COSE_Sign1");
+  const certRaw = coseUnprotectedToMap(decoded.unprotected).get(
+    DELEGATION_CERT_LABEL,
+  );
+  if (!(certRaw instanceof Uint8Array) || certRaw.length === 0) return null;
+  return extractKs256CertificateDigest(certRaw);
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let x = 0;
+  for (let i = 0; i < a.length; i++) x |= a[i]! ^ b[i]!;
+  return x === 0;
+}

package/src/verify-receipt-against-checkpoint-chain.ts

@@ -0,0 +1,256 @@
+/**
+ * The checkpoint-chain trust root (FOR-368 Phase 3; owner ruling D8): fold a
+ * retained `.sth` chain under the caller's roots with per-link delegation
+ * limits ({@link makeCheckpointLinkVerifier}), match the receipt's peak
+ * against ANY authenticated link, then judge certificate expiry on the
+ * links covering the now-bound leaf ({@link checkCheckpointLinkExpiry}).
+ * Lifted from mcp-verify 0.6.1's `verifyAtCheckpointChain`; forestrie-cli,
+ * which matches peaks its own way, can use the pieces instead.
+ *
+ * Later links' signed consistency proofs commit an earlier accumulator
+ * forward, so burial never turns an honest receipt tamper-shaped. Retention
+ * limits coverage, never validity: a receipt newer than the chain fails
+ * closed with a refresh remedy.
+ *
+ * Pure over bytes; no network (canopy rule C1).
+ */
+import { calculateRoot, peakMMRIndexes } from "@forestrie/merklelog";
+import {
+  verifyCheckpointChain,
+  type CheckpointChainLink,
+} from "./checkpoint-chain.js";
+import type { CheckpointChainReceiptOutcome } from "./checkpoint-chain-receipt-outcome.js";
+import {
+  checkCheckpointLinkExpiry,
+  makeCheckpointLinkVerifier,
+} from "./checkpoint-link-verifier.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { summarizeKs256AttestationUsage } from "./ks256-attestation-usage.js";
+import { inclusionWalkEndIndex } from "./inclusion-walk-end.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { parseReceipt } from "./parse-receipt.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+
+/** Input to {@link verifyReceiptAgainstCheckpointChain}. */
+export type VerifyReceiptAgainstCheckpointChainInput = {
+  receiptCbor: Uint8Array;
+  /** The leaf's idtimestamp; the last 8 bytes are used (big-endian). */
+  idtimestampBe8: Uint8Array;
+  /** Leaf ContentHash: SHA-256(payload), or the grant commitment hash. */
+  inner: Uint8Array;
+  /** Retained checkpoints in fold (ascending size) order. */
+  checkpoints: readonly Uint8Array[];
+  /** ES256 keys and KS256 addresses, from genesis or caller-known keys. */
+  rootKeys: readonly RootVerifyKey[];
+  /** ERC-1271 attestations, one per contract-root certificate. */
+  attestations?: readonly Ks256Attestation[] | undefined;
+  /**
+   * The forest genesis, read only for its chain id (attestations must
+   * match it). Give this or {@link forestChainId}; both must agree.
+   */
+  forestGenesisCbor?: Uint8Array | undefined;
+  forestChainId?: bigint | undefined;
+  /** Trusted base for a suffix chain; see `verifyCheckpointChain`. */
+  trustedBase?: { size: bigint; accumulator: Uint8Array[] } | undefined;
+};
+
+/**
+ * Verify a receipt against a retained checkpoint chain.
+ *
+ * The receipt's own signature is not checked: the authenticated chain is
+ * the authority, and the peak is ALWAYS recomputed from the leaf
+ * (`idtimestamp ‖ inner`) and the inclusion path, never taken from an
+ * attached payload. A match binds the leaf's idtimestamp (through the leaf
+ * hash) and its mmrIndex (through the matched peak's POSITION, which must be
+ * the node the inclusion walk reaches: the leaf hash alone does not commit
+ * its position, and an empty path commits none).
+ * Links are searched newest first; the newest cover is reported.
+ */
+export async function verifyReceiptAgainstCheckpointChain(
+  input: VerifyReceiptAgainstCheckpointChainInput,
+): Promise<CheckpointChainReceiptOutcome> {
+  const attestations = input.attestations ?? [];
+  const empty = {
+    links: [] as CheckpointChainLink[],
+    records: [],
+    attestations: summarizeKs256AttestationUsage(attestations, []),
+  };
+  if (input.rootKeys.length === 0) {
+    return { ...empty, ok: false, stage: "input", reason: "no_trust_key" };
+  }
+  let forestChainId = input.forestChainId;
+  if (input.forestGenesisCbor !== undefined) {
+    let fromGenesis: bigint;
+    try {
+      fromGenesis = BigInt(
+        decodeChainBindingFromGenesis(input.forestGenesisCbor).chainId,
+      );
+    } catch {
+      return {
+        ...empty,
+        ok: false,
+        stage: "input",
+        reason: "forest_genesis_invalid",
+      };
+    }
+    if (forestChainId !== undefined && forestChainId !== fromGenesis) {
+      return {
+        ...empty,
+        ok: false,
+        stage: "input",
+        reason: "forest_chain_id_mismatch",
+      };
+    }
+    forestChainId = fromGenesis;
+  }
+
+  const verifier = makeCheckpointLinkVerifier({
+    rootKeys: input.rootKeys,
+    attestations,
+    forestChainId,
+  });
+  const chain = await verifyCheckpointChain({
+    checkpoints: [...input.checkpoints],
+    verifySignature: verifier.verifySignature,
+    ...(input.trustedBase !== undefined
+      ? { trustedBase: input.trustedBase }
+      : {}),
+  });
+  const linkFailure = verifier.failure();
+  const common = {
+    links: chain.links,
+    records: verifier.records,
+    attestations: summarizeKs256AttestationUsage(
+      attestations,
+      verifier.records,
+      linkFailure,
+    ),
+  };
+  if (!chain.ok) {
+    return {
+      ...common,
+      ok: false,
+      stage: "chain",
+      reason: linkFailure?.reason ?? `checkpoint_chain_${chain.reason}`,
+      at: chain.at,
+      detail: chain.detail,
+      ...(linkFailure !== undefined ? { linkFailure } : {}),
+    };
+  }
+
+  let parsed: ReturnType<typeof parseReceipt>;
+  try {
+    parsed = parseReceipt(input.receiptCbor);
+  } catch {
+    return {
+      ...common,
+      ok: false,
+      stage: "parse",
+      reason: "receipt_malformed",
+    };
+  }
+  if (input.idtimestampBe8.length < 8) {
+    return {
+      ...common,
+      ok: false,
+      stage: "parse",
+      reason: "idtimestamp_invalid",
+    };
+  }
+  const idtimestamp = readU64Be(input.idtimestampBe8.slice(-8));
+  // parseReceipt always sets mmrIndex; leafIndex wins when present, as in
+  // every other peak recompute in this package.
+  const leafMmrIndex = parsed.proof.leafIndex ?? parsed.proof.mmrIndex;
+  if (leafMmrIndex === undefined) {
+    return {
+      ...common,
+      ok: false,
+      stage: "parse",
+      reason: "receipt_malformed",
+    };
+  }
+
+  const links = chain.links;
+  const final = links[links.length - 1]!;
+  if (leafMmrIndex >= final.treeSize2) {
+    return {
+      ...common,
+      ok: false,
+      stage: "anchor",
+      reason: "receipt_newer_than_checkpoint_chain",
+    };
+  }
+
+  let peak: Uint8Array;
+  try {
+    peak = await calculateRoot(
+      new SubtleHasher(),
+      await univocityLeafHash(idtimestamp, input.inner),
+      parsed.proof,
+      leafMmrIndex,
+    );
+  } catch {
+    return {
+      ...common,
+      ok: false,
+      stage: "parse",
+      reason: "receipt_malformed",
+    };
+  }
+
+  // The peak the path claims to reach. A leaf hash does not commit its
+  // position (and an empty path commits none), so a value match alone would
+  // leave mmrIndex a caller claim: the matched peak must sit at this index.
+  const peakIndex = inclusionWalkEndIndex(
+    leafMmrIndex,
+    parsed.proof.path.length,
+  );
+  for (let i = links.length - 1; i >= 0; i--) {
+    const link = links[i]!;
+    const p =
+      link.treeSize2 > 0n
+        ? peakMMRIndexes(link.treeSize2 - 1n).indexOf(peakIndex)
+        : -1;
+    if (p < 0 || !bytesEqual(link.accumulator[p] ?? new Uint8Array(), peak)) {
+      continue;
+    }
+    // The leaf hash, inclusion path and peak position now bind idtimestamp
+    // and mmrIndex to an authenticated accumulator, so expiry can be judged
+    // on them.
+    const expiry = checkCheckpointLinkExpiry(verifier.records, {
+      mmrIndex: leafMmrIndex,
+      idtimestamp,
+    });
+    if (!expiry.ok) {
+      return {
+        ...common,
+        ok: false,
+        stage: "delegation",
+        reason: expiry.reason,
+        at: expiry.at,
+      };
+    }
+    return { ...common, ok: true, matchedLink: i, matchedPeak: p };
+  }
+  return {
+    ...common,
+    ok: false,
+    stage: "anchor",
+    reason: "peak_not_in_checkpoint_chain",
+  };
+}
+
+function readU64Be(be8: Uint8Array): bigint {
+  let v = 0n;
+  for (const b of be8) v = (v << 8n) | BigInt(b);
+  return v;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let x = 0;
+  for (let i = 0; i < a.length; i++) x |= a[i]! ^ b[i]!;
+  return x === 0;
+}