@forestrie/receipt-verify 2.2.0 → 3.0.1

package/src/checkpoint-chain.ts

@@ -20,11 +20,15 @@
  * "keyless first checkpoint" case). `tree-size-1` stays unsigned prover
  * context: the publisher relays several sealed steps and may re-base a step
  * under the head checkpoint's signature, so the declared base of a
- * checkpoint can differ from what the sealer had (D2 chain semantics is
- * withdrawn) — a signed size-1 comparison would reject every re-based
- * publish and every multi-link catch-up. A checkpoint without the signed
- * size-2 label, or whose signed size-2 disagrees with its declared proof,
- * is rejected before any fold is attempted.
+ * checkpoint can differ from what the sealer had (the signed origin
+ * ADR-0066 D2 first proposed was withdrawn) — a signed size-1 comparison
+ * would reject every re-based publish and every multi-link catch-up. One
+ * checkpoint may itself relay SEVERAL sealed steps (ADR-0066 D2): the
+ * draft carries them under vdp key -2 as
+ * `consistency-proofs = [ + consistency-proof ]`, folded here in order,
+ * with only the last step's size signed. A checkpoint without the signed
+ * size-2 label, or whose signed size-2 disagrees with the last proof it
+ * relays, is rejected before any fold is attempted.
  *
  * This rung depends only on the public log store — the complement of the
  * `CheckpointPublished` event scan (public chain data only); see the
@@ -53,25 +57,64 @@ import {
 } from "@forestrie/merklelog";
 import { SubtleHasher } from "./subtle-hasher.js";
 import { parseCheckpoint } from "./build-receipt-offline.js";
-import { decodeConsistencyProofFromUnprotected } from "./decode-checkpoint-consistency-proof.js";
+import {
+  decodeConsistencyProofsFromUnprotected,
+  EmptyConsistencyProofsError,
+  type DecodedConsistencyProof,
+} from "./decode-checkpoint-consistency-proof.js";
 
-/** Draft-bryce consistency proof embedded in a v3 checkpoint. `treeSize2` is
- * cross-checked against the checkpoint's SIGNED tree-size-2 (ADR-0066 D1 as
- * amended); `treeSize1` is unsigned prover context, not cross-checked here —
- * see {@link verifyCheckpointChain}, which compares it with the trusted
- * origin instead. */
+/**
+ * The draft-bryce consistency proofs embedded in a v3 checkpoint: one or
+ * more, in relay order (`consistency-proofs = [ + consistency-proof ]`,
+ * ADR-0066 D2). A checkpoint sealing a single step carries the chain of
+ * one; there is no separate single-proof shape.
+ *
+ * {@link treeSize2} — the LAST proof's — is cross-checked against the
+ * checkpoint's SIGNED tree-size-2 (ADR-0066 D1 as amended, D5.5).
+ * {@link treeSize1} — the FIRST proof's — is unsigned prover context, not
+ * cross-checked here; see {@link verifyCheckpointChain}, which compares it
+ * with the trusted origin instead. The sizes between the two are named by
+ * no signature: {@link computeCheckpointAccumulator} holds the chain
+ * together by requiring each proof to continue the one before it.
+ */
 export type CheckpointConsistencyProof = {
+  /** The relayed proofs, in chain order; never empty. */
+  proofs: DecodedConsistencyProof[];
+  /** `tree-size-1` of the FIRST proof: the size the chain continues from. */
   treeSize1: bigint;
+  /** `tree-size-2` of the LAST proof: the size the chain reaches. */
   treeSize2: bigint;
   /** Signed `tree-size-2` (protected header label -65933); equal to
    * {@link treeSize2} — {@link checkpointConsistencyProof} enforces this. */
   signedTreeSize2: bigint;
-  /** One inclusion path per tree-size-1 peak, proven at tree-size-2. */
-  paths: Uint8Array[][];
-  /** New peaks not covered by the proven roots (draft `right-peaks`). */
-  rightPeaks: Uint8Array[];
 };
 
+/**
+ * A relayed consistency-proof chain does not join up: a proof's declared
+ * `tree-size-1` is not the size the fold has reached — the caller's trusted
+ * size for the first proof, the previous proof's `tree-size-2` after that —
+ * or, having applied every proof, the fold reaches a size other than the
+ * chain link's own declared `tree-size-2` (F3: a caller-assembled link —
+ * `freshenReceipt` callers build these from on-chain calldata, never
+ * through {@link checkpointConsistencyProof} — can set `proofs` and
+ * `treeSize2` independently, which `checkpointConsistencyProof` itself
+ * never allows to disagree). go-merklelog reuses its equivalent
+ * `ErrProofChainNotContiguous` for this same end-of-chain comparison
+ * (`checkpointverify.go:245-251`, folded size vs. signed size). Reported as
+ * `"size_mismatch"` by {@link verifyCheckpointChain}, the same as any other
+ * size disagreement, because the sizes it names are unsigned (ADR-0066 D2):
+ * nothing distinguishes a relay assembled in the wrong order from one
+ * assembled over a different log.
+ */
+export class ConsistencyChainNotContiguousError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConsistencyChainNotContiguousError";
+  }
+}
+
+export { EmptyConsistencyProofsError };
+
 /**
  * The checkpoint's SIGNED `tree-size-2` (protected header, ADR-0066 D1 as
  * amended) differs from the declared `tree-size-2` of its embedded
@@ -125,12 +168,14 @@ export class CheckpointProtectedHeaderAlgError extends Error {
 }
 
 /**
- * Decode the embedded consistency proof (`vdp` 396 key -2) and require its
- * declared `tree-size-2` to equal the checkpoint's SIGNED `tree-size-2` from
- * the protected header (ADR-0066 D1 as amended, D5.5, label -65933).
- * `tree-size-1` is not signed and is not checked here (D2 is withdrawn); see
- * {@link verifyCheckpointChain} for its comparison against the trusted
- * origin.
+ * Decode the embedded consistency proofs (`vdp` 396 key -2, one or more in
+ * relay order) and require the LAST proof's declared `tree-size-2` to equal
+ * the checkpoint's SIGNED `tree-size-2` from the protected header (ADR-0066
+ * D1 as amended, D2, D5.5, label -65933). The earlier proofs' sizes are not
+ * signed: the fold checks them against each other
+ * ({@link computeCheckpointAccumulator}). `tree-size-1` is not signed
+ * either; see {@link verifyCheckpointChain} for its comparison against the
+ * trusted origin.
  *
  * Also rejects a malleable high-s ES256 signature (see
  * {@link CheckpointHighSSignatureError}) before any fold or WebCrypto verify
@@ -138,12 +183,14 @@ export class CheckpointProtectedHeaderAlgError extends Error {
  * subject to this check, since it does not go through the P-256 WebCrypto
  * path this guards.
  *
- * @throws {Error} when the protected header carries no consistency proof,
- *   the proof is structurally malformed (see
- *   {@link decodeConsistencyProofFromUnprotected}), or the protected header
+ * @throws {Error} when the unprotected header carries no consistency proof,
+ *   a proof is structurally malformed (see
+ *   {@link decodeConsistencyProofsFromUnprotected}), or the protected header
  *   carries no signed tree-size-2 label
+ * @throws {EmptyConsistencyProofsError} when the consistency-proofs array is
+ *   present but empty
  * @throws {CheckpointSignedSizeMismatchError} when the signed tree-size-2
- *   differs from the declared proof's tree-size-2
+ *   differs from the LAST declared proof's tree-size-2
  * @throws {CheckpointHighSSignatureError} when the checkpoint is ES256-signed
  *   with a high-s (malleable) signature
  * @throws {CheckpointProtectedHeaderAlgError} when the protected header
@@ -174,75 +221,125 @@ export function checkpointConsistencyProof(
         "to match the univocity contract's P-256 verifier and go-merklelog",
     );
   }
-  const declared = decodeConsistencyProofFromUnprotected(unprotected);
-  if (declared === null) {
+  const proofs = decodeConsistencyProofsFromUnprotected(unprotected);
+  if (proofs === null) {
     throw new Error("checkpoint carries no consistency proof (vdp key -2)");
   }
+  const last = proofs[proofs.length - 1]!;
   const signedTreeSize2 = readProtectedTreeSize2(coseSign1[0]);
   if (signedTreeSize2 === null) {
     throw new Error(
       "checkpoint protected header carries no signed tree-size-2 (-65933)",
     );
   }
-  if (signedTreeSize2 !== declared.treeSize2) {
+  // The signature covers the size the LAST proof reaches, and only that
+  // size: a relay may hold any number of steps before it, none of them
+  // signed (ADR-0066 D2).
+  if (signedTreeSize2 !== last.treeSize2) {
     throw new CheckpointSignedSizeMismatchError(
-      `signed tree-size-2 (-65933) ${signedTreeSize2} != declared consistency-proof tree-size-2 ${declared.treeSize2}`,
+      `signed tree-size-2 (-65933) ${signedTreeSize2} != declared consistency-proof tree-size-2 ${last.treeSize2}`,
     );
   }
   return {
-    treeSize1: declared.treeSize1,
-    treeSize2: declared.treeSize2,
+    proofs,
+    treeSize1: proofs[0]!.treeSize1,
+    treeSize2: last.treeSize2,
     signedTreeSize2,
-    paths: declared.paths,
-    rightPeaks: declared.rightPeaks,
   };
 }
 
 /**
- * One fold step: from the CALLER-TRUSTED accumulator at `sizeFrom`, produce
- * the `proof.treeSize2` accumulator via the size-driven
- * {@link consistentRootsForSizes} (ADR-0066 D5) — `roots` (the proven
- * prefix) followed by the proof's supplied right-peaks (the target peaks no
- * path reaches).
+ * Fold a checkpoint's relayed consistency proofs, in order, from the
+ * CALLER-TRUSTED accumulator at `sizeFrom` to the accumulator at the last
+ * proof's `tree-size-2` — the value the checkpoint's signature covers.
  *
- * `sizeFrom` is a parameter, not read off `proof`, because the fold must run
- * against a size the CALLER already trusts (the previous link's verified
- * `treeSize2`, or the caller's anchor for a first link) — reading it from
- * the proof instead would let an unsigned or substituted proof dictate its
- * own starting point. `proof.treeSize1` must equal it regardless: the two
- * disagreeing means this proof does not continue from the state being
- * folded, not a mere shape defect, so it is checked before any fold work.
+ * Each proof is applied by the size-driven {@link consistentRootsForSizes}
+ * (ADR-0066 D5), which yields `roots` (the proven prefix); the proof's own
+ * right-peaks (the target peaks no path reaches) complete that step's
+ * accumulator, and it becomes the next step's input. A checkpoint sealing
+ * one step carries the chain of one and runs the same loop once.
  *
- * @throws {Error} when `proof.treeSize1 !== sizeFrom`, or when the proof
- *   supplies a right-peaks count other than
+ * `sizeFrom` is a parameter, not read off the proofs, because the fold must
+ * start from a size the CALLER already trusts (the previous checkpoint's
+ * verified `treeSize2`, or the caller's anchor for a first link) — reading
+ * it from the relay instead would let an unsigned or substituted proof
+ * dictate its own starting point (ADR-0066 D5.4). Every proof after the
+ * first is held to the size the previous one reached for the same reason:
+ * only the last step's size is signed, so the intermediate sizes are worth
+ * no more than their agreement with each other.
+ *
+ * `proof.proofs` must hold at least one step and, once every step has been
+ * applied, the fold must have reached exactly `proof.treeSize2` (F3).
+ * `checkpointConsistencyProof` already guarantees both — the decode rejects
+ * an empty `consistency-proofs` array (`EmptyConsistencyProofsError`) and
+ * sets `treeSize2` from the last decoded proof — but a caller-assembled
+ * link (`freshenReceipt` callers building from on-chain calldata) is not
+ * decoded through it, so both are re-checked here rather than trusted from
+ * the type.
+ *
+ * @throws {EmptyConsistencyProofsError} when `proof.proofs` is empty — an
+ *   already-decoded link the caller assembled themselves rather than one
+ *   `checkpointConsistencyProof` produced, which never returns one
+ * @throws {ConsistencyChainNotContiguousError} when the first proof's
+ *   `treeSize1` is not `sizeFrom`, a later proof's `treeSize1` is not the
+ *   previous proof's `treeSize2`, or the size the fold reaches after every
+ *   proof is not `proof.treeSize2`
+ * @throws {Error} when a proof supplies a right-peaks count other than
  *   {@link consistentRootsForSizes}'s `expectedRight`
- * @throws {ConsistencyShapeError} (`@forestrie/merklelog`) when the proof
- *   does not have the shape MMR(sizeFrom) -> MMR(proof.treeSize2) implies
+ * @throws {ConsistencyShapeError} (`@forestrie/merklelog`) when a proof does
+ *   not have the shape its two sizes imply
  */
 export async function computeCheckpointAccumulator(
   proof: CheckpointConsistencyProof,
   accumulatorFrom: Uint8Array[],
   sizeFrom: bigint,
 ): Promise<Uint8Array[]> {
-  if (proof.treeSize1 !== sizeFrom) {
-    throw new Error(
-      `consistency proof base tree-size-1 ${proof.treeSize1} does not match the trusted size ${sizeFrom}`,
+  if (proof.proofs.length === 0) {
+    throw new EmptyConsistencyProofsError(
+      "consistency proof relays no proofs (empty proofs array); at least " +
+        "one is required to fold",
     );
   }
   const hasher = new SubtleHasher();
-  const { roots, expectedRight } = await consistentRootsForSizes(
-    hasher,
-    sizeFrom,
-    proof.treeSize2,
-    accumulatorFrom,
-    proof.paths,
-  );
-  if (proof.rightPeaks.length !== expectedRight) {
-    throw new Error(
-      `checkpoint supplies ${proof.rightPeaks.length} right-peaks; size ${proof.treeSize2} requires ${expectedRight}`,
+  let accumulator = accumulatorFrom;
+  let size = sizeFrom;
+  for (let i = 0; i < proof.proofs.length; i++) {
+    const step = proof.proofs[i]!;
+    if (step.treeSize1 !== size) {
+      throw new ConsistencyChainNotContiguousError(
+        i === 0
+          ? `consistency proof base tree-size-1 ${step.treeSize1} does not match the trusted size ${size}`
+          : `consistency-proofs entry ${i} declares tree-size-1 ${step.treeSize1}; the previous proof reached ${size}`,
+      );
+    }
+    const { roots, expectedRight } = await consistentRootsForSizes(
+      hasher,
+      size,
+      step.treeSize2,
+      accumulator,
+      step.paths,
     );
+    if (step.rightPeaks.length !== expectedRight) {
+      throw new Error(
+        `checkpoint supplies ${step.rightPeaks.length} right-peaks; size ${step.treeSize2} requires ${expectedRight}`,
+      );
+    }
+    accumulator = [...roots, ...step.rightPeaks];
+    size = step.treeSize2;
   }
-  return [...roots, ...proof.rightPeaks];
+  // The fold must land exactly on the size the LINK itself declares —
+  // `proof.treeSize2` — not merely on whatever size its last proof happened
+  // to reach: a caller-assembled link can set the two independently (e.g.
+  // proofs folding 1 -> 3 alongside a declared treeSize2 of 7), which would
+  // otherwise fold to 3 and be reported as size 7 to every downstream
+  // caller reading the declared field instead of the fold. Mirrors
+  // go-merklelog's own end-of-chain check (checkpointverify.go:245-251).
+  if (size !== proof.treeSize2) {
+    throw new ConsistencyChainNotContiguousError(
+      `consistency proof folds to tree-size-2 ${size}; the chain's declared tree-size-2 is ${proof.treeSize2}`,
+    );
+  }
+  return accumulator;
 }
 
 /** Detached payload the checkpoint signature covers (ADR-0046): the raw
@@ -289,8 +386,10 @@ export type CheckpointChainResult =
          * `tree-size-2` (ADR-0066 D1 as amended, D5.5), or a link's declared
          * `tree-size-1` disagrees with the size the fold starts from — the
          * caller's `trustedBase.size` (0 with no `trustedBase`) for the
-         * first link, the previous link's `tree-size-2` after that.
-         * `detail` names both sizes.
+         * first link, the previous link's `tree-size-2` after that — or a
+         * relayed proof WITHIN a checkpoint disagrees with the size the
+         * proof before it reached ({@link
+         * ConsistencyChainNotContiguousError}). `detail` names both sizes.
          */
         | "size_mismatch";
       /** Index of the offending checkpoint. */
@@ -319,15 +418,20 @@ export type CheckpointChainResult =
  * - The first link's declared `tree-size-1` must equal that trusted
  *   starting size, and every subsequent link's must equal the previous
  *   link's sealed `tree-size-2`; either disagreement is `size_mismatch`.
- *   `tree-size-1` itself is never compared with a signed value (D2 is
- *   withdrawn): only this trusted-origin comparison applies. Because it is
+ *   `tree-size-1` itself is never compared with a signed value (the signed
+ *   origin ADR-0066 D2 first proposed was withdrawn): only this
+ *   trusted-origin comparison applies. Because it is
  *   unsigned, the reason it produces carries no more meaning than the size
  *   disagreement itself (ADR-0066 D6: no pre-FOR-410 state is supported, so
  *   there is no drift condition to fall back from).
- * - Each checkpoint's SIGNED `tree-size-2` (ADR-0066 D1 as amended) must
- *   equal its declared consistency-proof `tree-size-2`
- *   ({@link checkpointConsistencyProof}); a disagreement is
- *   `size_mismatch`.
+ * - A checkpoint may relay SEVERAL consistency proofs under one signature
+ *   (ADR-0066 D2; draft `consistency-proofs = [ + consistency-proof ]`).
+ *   Its SIGNED `tree-size-2` (ADR-0066 D1 as amended) must equal the LAST
+ *   proof's declared `tree-size-2` ({@link checkpointConsistencyProof}),
+ *   and each relayed proof must continue the one before it
+ *   ({@link computeCheckpointAccumulator}); either disagreement is
+ *   `size_mismatch`. A checkpoint sealing one step is the relay of one and
+ *   takes the same path.
  * - Each link's signature is checked over its computed accumulator via
  *   the injected verifier (the caller owns trust resolution — genesis
  *   roots, caller-known keys, or the label-1000 delegation path). A link
@@ -460,9 +564,15 @@ export async function verifyCheckpointChain(opts: {
         expectedBase,
       );
     } catch (err) {
+      // A relay that does not join up is a size disagreement like any
+      // other: every size it names but the last is unsigned, so the reason
+      // can say no more than that two sizes differ.
       return {
         ok: false,
-        reason: "proof_malformed",
+        reason:
+          err instanceof ConsistencyChainNotContiguousError
+            ? "size_mismatch"
+            : "proof_malformed",
         at: i,
         detail: err instanceof Error ? err.message : String(err),
         links,

package/src/decode-checkpoint-consistency-proof.ts

@@ -1,7 +1,20 @@
 /**
- * Decode the draft-bryce consistency proof `[tree-size-1, tree-size-2, paths,
- * right-peaks]` carried under a checkpoint's verifiable-proofs UNPROTECTED
- * header (draft-bryce label 396, key -2 = `VDP_CONSISTENCY_PROOF_KEY`).
+ * Decode the draft-bryce consistency proofs carried under a checkpoint's
+ * verifiable-proofs UNPROTECTED header (draft-bryce label 396, key -2 =
+ * `VDP_CONSISTENCY_PROOF_KEY`).
+ *
+ * The draft's CDDL is
+ * `consistency-proofs = [ + consistency-proof ]`, with each
+ * `consistency-proof = bstr .cbor [tree-size-1, tree-size-2, paths,
+ * right-peaks]` — one or more proofs, relayed in chain order under a single
+ * signature (ADR-0066 D2). Both shapes are accepted under the -2 key:
+ *
+ * - an ARRAY of one or more proof bstrs — the draft's wire form, and the
+ *   only form that can carry a relayed chain;
+ * - a BARE proof bstr — the shape every checkpoint sealed before the array
+ *   form carries, and the shape the pinned `checkpoint-receipt-kat39.json`
+ *   vector's `conventions.receipt` still states. It decodes to the array of
+ *   one, so nothing downstream distinguishes it.
  *
  * Single source of truth for this decode, shared by `parseCheckpoint`
  * (build-receipt-offline.ts, lenient: an absent or malformed proof yields a
@@ -9,8 +22,9 @@
  * (checkpoint-chain.ts, full validation: an absent proof or a malformed
  * shape throws, and the SIGNED `tree-size-2` from the protected header —
  * read separately via `readProtectedTreeSize2`, ADR-0066 D1 as amended —
- * must match the `tree-size-2` decoded here; `tree-size-1` is unsigned
- * prover context and is not cross-checked against a signed value).
+ * must match the `tree-size-2` of the LAST proof decoded here;
+ * `tree-size-1` is unsigned prover context and is not cross-checked against
+ * a signed value).
  */
 
 import {
@@ -19,7 +33,7 @@ import {
   decodeCborDeterministic,
 } from "@forestrie/encoding";
 
-/** The declared (unprotected, unsigned) consistency proof of a checkpoint. */
+/** One declared (unprotected, unsigned) consistency proof of a checkpoint. */
 export type DecodedConsistencyProof = {
   treeSize1: bigint;
   treeSize2: bigint;
@@ -29,6 +43,21 @@ export type DecodedConsistencyProof = {
   rightPeaks: Uint8Array[];
 };
 
+/**
+ * The verifiable-proofs header carries the consistency-proof key with an
+ * EMPTY array. Distinct from an absent proof (no -2 key at all, which
+ * decodes to `null`): the key is present and claims to relay a chain, but
+ * the chain has no links, so there is nothing to fold and no last proof for
+ * the signed `tree-size-2` to equal. `consistency-proofs = [ + ... ]`
+ * requires at least one.
+ */
+export class EmptyConsistencyProofsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EmptyConsistencyProofsError";
+  }
+}
+
 function asBigint(v: unknown, what: string): bigint {
   // Unsigned only: a negative size flows into peakMMRIndexes /
   // consistentRootsForSizes, which reject or spin on a non-positive
@@ -56,36 +85,18 @@ function asBytesArray(v: unknown, what: string): Uint8Array[] {
   return v as Uint8Array[];
 }
 
-/**
- * Decode the embedded consistency proof from a checkpoint's UNPROTECTED
- * header map. Returns `null` when the checkpoint carries no verifiable-proofs
- * header (396) or no consistency-proof bstr there (key -2) — an ABSENT
- * proof, not a malformed one.
- *
- * @throws When a consistency-proof bstr IS present but its contents are not
- *   the shape `[tree-size-1, tree-size-2, paths, right-peaks]`, either size
- *   is not an unsigned integer, the proof does not grow the tree
- *   (`tree-size-2 <= tree-size-1`), a path element or a right-peak is not a
- *   32-byte string — or when header 396 is present but is not map-valued,
- *   or its `-2` entry is present but not a byte string.
- */
-export function decodeConsistencyProofFromUnprotected(
-  unprotected: Map<number, unknown>,
-): DecodedConsistencyProof | null {
-  const vdpRaw = unprotected.get(COSE_LABEL_VDP);
-  if (vdpRaw === undefined || vdpRaw === null) return null;
-  if (!(vdpRaw instanceof Map)) {
-    throw new Error("checkpoint carries no verifiable-proofs header (396)");
-  }
-  const proofBstr = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
-  if (proofBstr === undefined || proofBstr === null) return null;
-  if (!(proofBstr instanceof Uint8Array)) {
-    throw new Error("checkpoint carries no consistency proof (vdp key -2)");
-  }
+/** Decode one `bstr .cbor [tree-size-1, tree-size-2, paths, right-peaks]`. */
+function decodeOneProof(proofBstr: Uint8Array): DecodedConsistencyProof {
   const proof = decodeCborDeterministic(proofBstr);
-  if (!Array.isArray(proof) || proof.length < 4) {
+  // Exactly 4 — the draft's CDDL names a fixed-arity array, and
+  // go-merklelog's decoder rejects any other length (F2). A 5th element
+  // (e.g. another proof tuple, mistaken for a chain of two) is as malformed
+  // as a 3rd missing.
+  if (!Array.isArray(proof) || proof.length !== 4) {
     throw new Error(
-      "consistency proof must be [tree-size-1, tree-size-2, paths, right-peaks]",
+      `consistency proof must be [tree-size-1, tree-size-2, paths, right-peaks] (4 elements), got ${
+        Array.isArray(proof) ? proof.length : typeof proof
+      }`,
     );
   }
   const pathsRaw = proof[2];
@@ -134,3 +145,76 @@ export function decodeConsistencyProofFromUnprotected(
     rightPeaks: asBytesArray(proof[3], "right-peaks"),
   };
 }
+
+/**
+ * Decode proof `at` of a relayed chain, naming its position in the message
+ * so a chain of several says which link is malformed. A header carrying a
+ * single proof names no position: its message is the one a single-proof
+ * checkpoint has always produced.
+ */
+function decodeProofAt(
+  proofBstr: Uint8Array,
+  at: number | null,
+): DecodedConsistencyProof {
+  if (at === null) return decodeOneProof(proofBstr);
+  try {
+    return decodeOneProof(proofBstr);
+  } catch (err) {
+    throw new Error(
+      `consistency-proofs entry ${at}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/**
+ * Decode the embedded consistency proofs from a checkpoint's UNPROTECTED
+ * header map, in the order they are relayed. Returns `null` when the
+ * checkpoint carries no verifiable-proofs header (396) or no
+ * consistency-proof entry there (key -2) — an ABSENT proof, not a malformed
+ * one. A returned array always holds at least one proof.
+ *
+ * This decode establishes each proof's shape only. Nothing here relates one
+ * proof to the next, or to a signed size: the chain has to be checked
+ * against state the CALLER trusts, which is `computeCheckpointAccumulator`
+ * and `checkpointConsistencyProof` (ADR-0066 D5.4).
+ *
+ * @throws {EmptyConsistencyProofsError} when the -2 entry is an empty array
+ * @throws When a consistency proof IS present but its contents are not the
+ *   shape `[tree-size-1, tree-size-2, paths, right-peaks]`, either size is
+ *   not an unsigned integer, a proof does not grow the tree
+ *   (`tree-size-2 <= tree-size-1`), a path element or a right-peak is not a
+ *   32-byte string — or when header 396 is present but is not map-valued,
+ *   or its `-2` entry is neither a byte string nor an array of byte strings.
+ */
+export function decodeConsistencyProofsFromUnprotected(
+  unprotected: Map<number, unknown>,
+): DecodedConsistencyProof[] | null {
+  const vdpRaw = unprotected.get(COSE_LABEL_VDP);
+  if (vdpRaw === undefined || vdpRaw === null) return null;
+  if (!(vdpRaw instanceof Map)) {
+    throw new Error("checkpoint carries no verifiable-proofs header (396)");
+  }
+  const entry = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
+  if (entry === undefined || entry === null) return null;
+  if (entry instanceof Uint8Array) {
+    // The pre-array shape: a single proof written straight under -2. It is
+    // the array of one, and is reported as such.
+    return [decodeOneProof(entry)];
+  }
+  if (!Array.isArray(entry)) {
+    throw new Error("checkpoint carries no consistency proof (vdp key -2)");
+  }
+  if (entry.length === 0) {
+    throw new EmptyConsistencyProofsError(
+      "consistency-proofs (vdp key -2) is empty; at least one proof is required",
+    );
+  }
+  return entry.map((proofBstr, i) => {
+    if (!(proofBstr instanceof Uint8Array)) {
+      throw new Error(
+        `consistency-proofs entry ${i} is not a byte string (vdp key -2)`,
+      );
+    }
+    return decodeProofAt(proofBstr, entry.length === 1 ? null : i);
+  });
+}

package/src/freshen-receipt.ts

@@ -81,11 +81,13 @@ export type FreshenReceiptInput = {
    * value `verify` recomputes from the entry (caller derives it). */
   leafValue: Uint8Array;
   /** Consistency-proof chain covering [0 or the trusted base] → the latest
-   * sealed size, in ascending contiguous order (the raw per-checkpoint
-   * proofs, with `paths`). Every link's `signedTreeSize2` must equal its
-   * `treeSize2`, as `checkpointConsistencyProof` requires of the checkpoint
-   * it decoded each link from. The chain's last link must end at the
-   * checkpoint's sealed size. */
+   * sealed size, in ascending contiguous order: one entry per checkpoint,
+   * each holding the proofs that checkpoint relays (`proofs`, one or more —
+   * ADR-0066 D2). Every link's `signedTreeSize2` must equal its
+   * `treeSize2` — the size its LAST relayed proof reaches — as
+   * `checkpointConsistencyProof` requires of the checkpoint it decoded each
+   * link from. The chain's last link must end at the checkpoint's sealed
+   * size. */
   consistencyProofs: readonly CheckpointConsistencyProof[];
   /** Trusted base for a suffix chain — the size the caller already trusts
    * and that size's accumulator; omit for a chain from base 0 (size 0, an
@@ -196,7 +198,9 @@ export async function freshenReceipt(
       `first consistency proof declares tree-size-1 ${firstLink.treeSize1}; the trusted base size is ${baseSize}`,
     );
   }
-  // Contiguity: each link continues where the previous one sealed.
+  // Contiguity BETWEEN checkpoints: each link continues where the previous
+  // one sealed. Contiguity WITHIN a link — between the proofs one
+  // checkpoint relays — is `computeCheckpointAccumulator`'s, below.
   for (let i = 1; i < links.length; i++) {
     if (links[i]!.treeSize1 !== links[i - 1]!.treeSize2) {
       throw new Error(
@@ -212,10 +216,11 @@ export async function freshenReceipt(
     );
   }
 
-  // Fold the chain to the latest accumulator (self-check target). Each step
+  // Fold the chain to the latest accumulator (self-check target). Each link
   // runs against a size the caller trusts, never one read off the link being
   // folded: the trusted base for the first link, and the size the previous
-  // link was just folded TO for every link after it.
+  // link was just folded TO for every link after it. A link relaying several
+  // proofs folds them all, in order, and ends at its last one.
   let accumulator = baseAccumulator;
   let sizeFrom = baseSize;
   for (const p of links) {
@@ -259,18 +264,21 @@ export async function freshenReceipt(
   for (let k = 0; k < oldPath.length; k++) {
     store.set(fullIndices[k]!, oldPath[k]!);
   }
-  for (const link of links) {
-    // A base-0 link (treeSize1 === 0) has no from-peaks to climb — a 0→N
+  // Every relayed proof contributes, not just one per checkpoint: a link
+  // that relays several sealed steps (ADR-0066 D2) carries one set of paths
+  // per step, each addressed by that step's own two sizes.
+  for (const step of links.flatMap((link) => link.proofs)) {
+    // A base-0 step (treeSize1 === 0) has no from-peaks to climb — a 0→N
     // consistency proof carries `paths: []` (the whole accumulator is its
     // right-peaks). Skip it: it contributes no store nodes, and calling
     // `peakMMRIndexes(-1n)` would throw (`posHeight(0)`, FOR-414). A genesis-
-    // rooted `.sth` chain always starts with such a link.
-    if (link.treeSize1 === 0n) continue;
-    const fromPeaks = peakMMRIndexes(link.treeSize1 - 1n);
+    // rooted `.sth` chain always starts with such a step.
+    if (step.treeSize1 === 0n) continue;
+    const fromPeaks = peakMMRIndexes(step.treeSize1 - 1n);
     fromPeaks.forEach((peakIndex, j) => {
-      const climb = link.paths[j];
+      const climb = step.paths[j];
       if (climb === undefined) return;
-      const climbIndices = inclusionProofPath(link.treeSize2 - 1n, peakIndex);
+      const climbIndices = inclusionProofPath(step.treeSize2 - 1n, peakIndex);
       climbIndices.forEach((ix, e) => {
         const v = climb[e];
         if (v !== undefined) store.set(ix, v);

package/src/index.ts

@@ -158,10 +158,15 @@ export {
   CheckpointHighSSignatureError,
   CheckpointProtectedHeaderAlgError,
   CheckpointSignedSizeMismatchError,
+  ConsistencyChainNotContiguousError,
+  EmptyConsistencyProofsError,
   type CheckpointChainLink,
   type CheckpointChainResult,
   type CheckpointConsistencyProof,
 } from "./checkpoint-chain.js";
+/** One relayed consistency proof; `CheckpointConsistencyProof.proofs` holds
+ * the chain of them a checkpoint carries (ADR-0066 D2). */
+export type { DecodedConsistencyProof } from "./decode-checkpoint-consistency-proof.js";
 /**
  * Univocity leaf commitment hash. Was CLI-private (forestrie-cli's own
  * mirror, "hoist to the library when the FOR-297 multi-hop resolver lands");