@forestrie/merklelog 0.3.0 → 0.5.0

package/dist/mmr/errors.js

@@ -0,0 +1,136 @@
+/**
+ * Typed errors for the size-driven consistency fold
+ * (`consistentRootsForSizes`).
+ *
+ * The names mirror the Solidity `IUnivocityErrors` members raised by the
+ * on-chain implementation (`univocity/src/algorithms/consistentRoots.sol`),
+ * so a shape rejection reads the same on both sides. Every one of these
+ * reports a condition the two sizes fix in advance — the proof does not
+ * have the shape MMR(sizeFrom) -> MMR(sizeTo) implies — as distinct from a
+ * value mismatch against a trusted accumulator, which callers surface as a
+ * plain verification failure.
+ *
+ * All derive from {@link ConsistencyShapeError} so a caller can map the whole
+ * family to "malformed proof" with a single `instanceof`.
+ */
+/** Base class for every consistency proof-shape rejection. */
+export class ConsistencyShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConsistencyShapeError";
+    }
+}
+/**
+ * The target size is not a complete MMR size.
+ *
+ * `peaksBitmap` rounds an incomplete size down to the largest complete MMR
+ * below it, so for an incomplete `sizeTo` the bitmap describes a different
+ * tree than the one named. Accepting it would anchor an accumulator that is
+ * no MMR's, and a later verifier would read its entries at the wrong heights.
+ */
+export class IncompleteTreeSize extends ConsistencyShapeError {
+    size;
+    constructor(size) {
+        super(`size ${size} is not a complete MMR size`);
+        this.size = size;
+        this.name = "IncompleteTreeSize";
+    }
+}
+/**
+ * The accumulator or the proof list does not have one entry per origin peak.
+ * The origin peak count is fixed by `sizeFrom` alone.
+ */
+export class ConsistencyPeakCountMismatch extends ConsistencyShapeError {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(`expected ${expected} entries for the origin peaks, got ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "ConsistencyPeakCountMismatch";
+    }
+}
+/**
+ * A path does not have the length the two sizes imply: 0 for an origin peak
+ * above the split, `split - h` for an origin peak of height `h` below it.
+ */
+export class ConsistencyPathLengthMismatch extends ConsistencyShapeError {
+    index;
+    expected;
+    actual;
+    constructor(index, expected, actual) {
+        super(`path ${index}: expected length ${expected}, got ${actual}`);
+        this.index = index;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "ConsistencyPathLengthMismatch";
+    }
+}
+/**
+ * Two origin peaks below the split proved different roots. Every origin peak
+ * below the split is committed by the single target peak of height `split`,
+ * so all of their paths must produce the same value.
+ */
+export class ConsistencyRootMismatch extends ConsistencyShapeError {
+    index;
+    constructor(index) {
+        super(`path ${index} proves a different root from the paths before it`);
+        this.index = index;
+        this.name = "ConsistencyRootMismatch";
+    }
+}
+/**
+ * The target size does not exceed the origin size. Consistency is defined for
+ * a growing log; equal or decreasing sizes have no proof shape to check.
+ */
+export class SizeMustIncrease extends ConsistencyShapeError {
+    sizeFrom;
+    sizeTo;
+    constructor(sizeFrom, sizeTo) {
+        super(`sizeTo (${sizeTo}) must exceed sizeFrom (${sizeFrom})`);
+        this.sizeFrom = sizeFrom;
+        this.sizeTo = sizeTo;
+        this.name = "SizeMustIncrease";
+    }
+}
+/**
+ * A size is outside the uint64 domain the MMR profile's sizes live in.
+ *
+ * Solidity and Go take these sizes as `uint64`, so the domain is part of
+ * their signatures; TypeScript's `bigint` has no bound of its own. Without
+ * this check a size at or above 2^64 folds here and nowhere else: the
+ * position prefix `hash_pospair64` writes is truncated to eight bytes, so
+ * the hashes computed above the bound are not the ones the other two
+ * implementations would compute, and a size that large is not one a CBOR
+ * unsigned integer can carry or the contract can store either.
+ */
+export class SizeNotUint64 extends ConsistencyShapeError {
+    which;
+    size;
+    constructor(which, size) {
+        super(`${which} (${size}) is outside the uint64 range [0, 2^64 - 1]`);
+        this.which = which;
+        this.size = size;
+        this.name = "SizeNotUint64";
+    }
+}
+/**
+ * `paths` is not a dense array of `Uint8Array[]`.
+ *
+ * A hole (a sparse array), a `null`/`undefined` entry, a path that is not an
+ * array, or a path element that is not a `Uint8Array` all survive the peak
+ * COUNT check and then surface as a bare `TypeError` out of the fold, which
+ * escapes the {@link ConsistencyShapeError} family callers are told to
+ * switch on. The shape of the proof material is a proof-shape condition like
+ * any other, so it is reported as one.
+ */
+export class ConsistencyPathMalformed extends ConsistencyShapeError {
+    detail;
+    index;
+    constructor(detail, index) {
+        super(index === undefined ? `paths: ${detail}` : `path ${index}: ${detail}`);
+        this.detail = detail;
+        this.index = index;
+        this.name = "ConsistencyPathMalformed";
+    }
+}

package/dist/mmr/proof.d.ts

@@ -11,6 +11,8 @@
  */
 /** Reads the 32-byte node at MMR index `i` from some backing store. */
 export type NodeGetter = (i: bigint) => Uint8Array;
+/** Number of bits needed to represent `num` (0 for 0). */
+export declare function bitLength(num: bigint): number;
 /**
  * Zero-based height index of the node at MMR index `i` (leaves are 0).
  * (go-merklelog `mmr/indexheight.go` IndexHeight)
@@ -68,6 +70,22 @@ export declare function inclusionProofLocalExtend(get: NodeGetter, mmrSizeA: big
  * subtree (peak). (go-merklelog `mmr/peaks.go` PeaksBitmap)
  */
 export declare function peaksBitmap(mmrSize: bigint): bigint;
+/**
+ * Node count of the complete MMR with `leaves` leaves (reference
+ * `mmr_size_for_leaf_count`, Solidity `mmrSizeForLeafCount`).
+ *
+ * Every leaf adds itself plus one interior node per binary carry, and each
+ * peak is a carry that has not happened, so the count is
+ * `2 * leaves - popcount(leaves)`.
+ *
+ * Because {@link peaksBitmap} rounds an incomplete size down to the largest
+ * complete MMR below it, `mmrSizeForLeafCount(peaksBitmap(size)) === size`
+ * holds exactly for complete sizes; that identity is the completeness test
+ * used by `consistentRootsForSizes`.
+ */
+export declare function mmrSizeForLeafCount(leaves: bigint): bigint;
+/** Population count of a non-negative BigInt. */
+export declare function popcount(x: bigint): number;
 /**
  * Accumulator slot (left-to-right) committed by an inclusion proof of length
  * `proofLen` in a tree of size `mmrSize`. (server resolve-receipt.ts:735,

package/dist/mmr/proof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/mmr/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;AA2CnD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,EACf,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,UAAU,EAAE,CAyBd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB5E;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,MAAM,GACR,qBAAqB,CA4CvB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnD;AAaD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAQD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAczD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrB"}
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/mmr/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;AAEnD,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG7C;AAqCD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,EACf,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,UAAU,EAAE,CAyBd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB5E;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,MAAM,GACR,qBAAqB,CA4CvB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAQD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAczD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrB"}

package/dist/mmr/proof.js

@@ -10,7 +10,7 @@
  * browser-safe (ADR-0048). Function names mirror the go-merklelog originals.
  */
 /** Number of bits needed to represent `num` (0 for 0). */
-function bitLength(num) {
+export function bitLength(num) {
     if (num <= 0n)
         return 0;
     return num.toString(2).length;
@@ -193,8 +193,24 @@ export function peaksBitmap(mmrSize) {
     }
     return peakMap;
 }
+/**
+ * Node count of the complete MMR with `leaves` leaves (reference
+ * `mmr_size_for_leaf_count`, Solidity `mmrSizeForLeafCount`).
+ *
+ * Every leaf adds itself plus one interior node per binary carry, and each
+ * peak is a carry that has not happened, so the count is
+ * `2 * leaves - popcount(leaves)`.
+ *
+ * Because {@link peaksBitmap} rounds an incomplete size down to the largest
+ * complete MMR below it, `mmrSizeForLeafCount(peaksBitmap(size)) === size`
+ * holds exactly for complete sizes; that identity is the completeness test
+ * used by `consistentRootsForSizes`.
+ */
+export function mmrSizeForLeafCount(leaves) {
+    return 2n * leaves - BigInt(popcount(leaves));
+}
 /** Population count of a non-negative BigInt. */
-function popcount(x) {
+export function popcount(x) {
     let count = 0;
     let v = x;
     while (v > 0n) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/merklelog",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "MMR (merkle mountain range) proofs and massif storage format for Forestrie transparency logs",

package/src/index.ts

@@ -71,9 +71,22 @@ export {
   verifyInclusion,
   verifyConsistency,
   consistentRoots,
+  consistentRootsForSizes,
   indexConsistencyProof,
   type ConsistencyProof,
 } from "./mmr/algorithms.js";
+// Typed proof-shape rejections raised by consistentRootsForSizes (names
+// mirror the Solidity IUnivocityErrors members) — plan-2609-10 s4.3, FOR-568.
+export {
+  ConsistencyShapeError,
+  IncompleteTreeSize,
+  ConsistencyPeakCountMismatch,
+  ConsistencyPathLengthMismatch,
+  ConsistencyPathMalformed,
+  ConsistencyRootMismatch,
+  SizeMustIncrease,
+  SizeNotUint64,
+} from "./mmr/errors.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";
 export type { Hasher } from "./mmr/types.js";
@@ -86,6 +99,7 @@ export {
   peakMMRIndexes,
   peaksBitmap,
   peakIndexForLeafProof,
+  mmrSizeForLeafCount,
   indexHeight,
   firstMMRSize,
   massifIndexFromMMRIndex,

package/src/mmr/algorithms.ts

@@ -12,11 +12,36 @@
  */
 
 import type { Proof, Hasher } from "./types.js";
-import { inclusionProof, peakMMRIndexes, type NodeGetter } from "./proof.js";
+import {
+  inclusionProof,
+  peakMMRIndexes,
+  bitLength,
+  popcount,
+  peaksBitmap,
+  mmrSizeForLeafCount,
+  type NodeGetter,
+} from "./proof.js";
+import {
+  ConsistencyPathLengthMismatch,
+  ConsistencyPathMalformed,
+  ConsistencyPeakCountMismatch,
+  ConsistencyRootMismatch,
+  IncompleteTreeSize,
+  SizeMustIncrease,
+  SizeNotUint64,
+} from "./errors.js";
 import { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
 
+/**
+ * Upper bound of the uint64 domain the MMR profile's sizes live in: Solidity
+ * and Go take every size as `uint64`, and a CBOR unsigned integer caps here
+ * too. `bigint` carries no such bound, so {@link consistentRootsForSizes}
+ * states it.
+ */
+const MAX_UINT64 = (1n << 64n) - 1n;
+
 /**
  * Encodes a Uint64 as 8 bytes big-endian.
  *
@@ -185,6 +210,12 @@ export interface ConsistencyProof {
  * duplicate roots collapse (many old peaks share one new peak). Requires
  * one path per MMR(A) peak (draft: `len(peaks(ifrom)) == len(accumulatorfrom)`).
  *
+ * This fold does not enforce the proof shape the two sizes imply: it reads
+ * whatever path lengths it is given and collapses whatever roots coincide.
+ * Use {@link consistentRootsForSizes} for verification — it checks each path
+ * against the length MMR(A) -> MMR(B) fixes and requires the paths under one
+ * target peak to agree.
+ *
  * @param ifrom - last node index of the complete MMR(A) (`mmrSizeA - 1`)
  * @param accumulatorFrom - MMR(A) peak values, descending height order
  * @param paths - inclusion path per peak, proven in MMR(B)
@@ -222,50 +253,227 @@ export async function consistentRoots(
   return roots;
 }
 
+/**
+ * Produce the peaks of MMR(sizeTo) that `paths` prove from the peaks of
+ * MMR(sizeFrom), requiring the paths to have exactly the shape the two sizes
+ * imply (draft-bryce-cose-receipts-mmr-profile, "Verifying the Receipt of
+ * consistency", with the draft's SHOULD on path lengths enforced in the same
+ * pass). Line-for-line port of the reference `consistent_roots_for_sizes`
+ * (algorithms.py) and of Solidity `consistentRootsForSizes`
+ * (univocity `src/algorithms/consistentRoots.sol`).
+ *
+ * Sizes are node counts (the MMR ending at index `i` has `i + 1` nodes).
+ * `sizeFrom` MUST be the size of the state the verifier already trusts; taken
+ * from the proof instead, the check is void. Only `sizeTo` is required to be
+ * a complete MMR size: every trusted size was itself a checked target.
+ *
+ * For a complete MMR the set bits of `peaksBitmap(size)` are the peak heights,
+ * high to low, which is accumulator order. Let `split` be the highest bit on
+ * which the two bitmaps differ; as `sizeTo > sizeFrom` the target has it and
+ * the origin does not. An origin peak above `split` is also a peak of the
+ * target: its path is empty and it is returned unchanged. Every origin peak
+ * below `split` is committed by the target peak of height `split`: its path
+ * has length `split - h`, and every such path must prove the same root. The
+ * target's remaining peaks lie below every origin peak, so no path reaches
+ * them; the prover supplies them separately and their count is returned.
+ *
+ * Because the shape is fixed by the sizes alone, no peak index list and no
+ * per-hop bookkeeping beyond the hash itself is needed: the bitmaps are
+ * iterated directly.
+ *
+ * @param hasher - cryptographic hasher instance
+ * @param sizeFrom - node count of the trusted origin state (0 for an empty log)
+ * @param sizeTo - node count of the target state; must exceed `sizeFrom` and
+ *   must be a complete MMR size
+ * @param accumulatorFrom - peaks of MMR(sizeFrom), descending height order
+ * @param paths - one path per origin peak, in the same order
+ * @returns `roots`, the peaks of MMR(sizeTo) proven from the origin peaks in
+ *   descending height order (the unchanged peaks, then the one proven root if
+ *   any), and `expectedRight`, the number of MMR(sizeTo) peaks the prover must
+ *   supply as right peaks. `roots` followed by those right peaks is the
+ *   accumulator of MMR(sizeTo).
+ * @throws {SizeNotUint64} if either size is outside `[0, 2^64 - 1]`
+ * @throws {SizeMustIncrease} if `sizeTo <= sizeFrom`
+ * @throws {IncompleteTreeSize} if `sizeTo` is not a complete MMR size
+ * @throws {ConsistencyPeakCountMismatch} if `accumulatorFrom` or `paths` does
+ *   not have one entry per origin peak
+ * @throws {ConsistencyPathMalformed} if `paths` is not a dense array of
+ *   `Uint8Array[]`
+ * @throws {ConsistencyPathLengthMismatch} if a path length differs from the
+ *   length the two sizes imply
+ * @throws {ConsistencyRootMismatch} if two paths under one target peak produce
+ *   different roots
+ */
+export async function consistentRootsForSizes(
+  hasher: Hasher,
+  sizeFrom: bigint,
+  sizeTo: bigint,
+  accumulatorFrom: Uint8Array[],
+  paths: Uint8Array[][],
+): Promise<{ roots: Uint8Array[]; expectedRight: number }> {
+  // The sizes are uint64 in Solidity and Go; `bigint` carries no such bound,
+  // so it is stated here before any arithmetic reads them.
+  if (sizeFrom < 0n || sizeFrom > MAX_UINT64) {
+    throw new SizeNotUint64("sizeFrom", sizeFrom);
+  }
+  if (sizeTo < 0n || sizeTo > MAX_UINT64) {
+    throw new SizeNotUint64("sizeTo", sizeTo);
+  }
+  if (sizeTo <= sizeFrom) {
+    throw new SizeMustIncrease(sizeFrom, sizeTo);
+  }
+  const to = peaksBitmap(sizeTo);
+  // peaksBitmap rounds an incomplete size down to the largest MMR below it,
+  // so `to` describes MMR(sizeTo) only if sizeTo is complete. Without this a
+  // target such as 6 anchors an accumulator that is no MMR's, and a verifier
+  // later reads its entries at the wrong heights.
+  if (mmrSizeForLeafCount(to) !== sizeTo) {
+    throw new IncompleteTreeSize(sizeTo);
+  }
+  const from = peaksBitmap(sizeFrom);
+  const n = popcount(from);
+  if (accumulatorFrom.length !== n) {
+    throw new ConsistencyPeakCountMismatch(n, accumulatorFrom.length);
+  }
+  if (!Array.isArray(paths)) {
+    throw new ConsistencyPathMalformed(`not an array (got ${typeName(paths)})`);
+  }
+  if (paths.length !== n) {
+    throw new ConsistencyPeakCountMismatch(n, paths.length);
+  }
+  assertDensePaths(paths);
+  const nto = popcount(to);
+  if (n === 0) {
+    return { roots: [], expectedRight: nto };
+  }
+
+  const split = bitLength(from ^ to) - 1;
+  const roots: Uint8Array[] = [];
+  // Nodes preceding the current origin peak's subtree; a peak of height h
+  // sits at offset + 2^(h+1) - 2 and its subtree has 2^(h+1) - 1 nodes.
+  let offset = 0n;
+  let i = 0;
+
+  // Origin peaks above the split are also peaks of the target. The path is
+  // not read; requiring it to be empty rejects unused material (a shape
+  // check: the result does not depend on it).
+  for (let h = bitLength(from) - 1; h > split; h--) {
+    if (((from >> BigInt(h)) & 1n) === 0n) continue;
+    if (paths[i].length !== 0) {
+      throw new ConsistencyPathLengthMismatch(i, 0, paths[i].length);
+    }
+    roots.push(accumulatorFrom[i]);
+    offset += (1n << BigInt(h + 1)) - 1n;
+    i += 1;
+  }
+
+  // Origin peaks below the split are all committed by the target peak of
+  // height `split` (bit `split` itself is clear in `from`), so each path must
+  // have length split - h and every path must prove the same root. The first
+  // `above` peaks were returned unchanged, so i === above at the first peak
+  // below the split.
+  const above = roots.length;
+  let root: Uint8Array | undefined;
+  for (let h = split - 1; h >= 0; h--) {
+    if (((from >> BigInt(h)) & 1n) === 0n) continue;
+    const expected = split - h;
+    if (paths[i].length !== expected) {
+      throw new ConsistencyPathLengthMismatch(i, expected, paths[i].length);
+    }
+    const subtree = (1n << BigInt(h + 1)) - 1n;
+    const peakMMRIndex = offset + subtree - 1n;
+    const proven = await calculateRoot(
+      hasher,
+      accumulatorFrom[i],
+      { path: paths[i], mmrIndex: peakMMRIndex },
+      peakMMRIndex,
+    );
+    if (i === above) {
+      root = proven;
+    } else if (!arraysEqual(proven, root as Uint8Array)) {
+      throw new ConsistencyRootMismatch(i);
+    }
+    offset += subtree;
+    i += 1;
+  }
+  if (n > above) {
+    roots.push(root as Uint8Array);
+  }
+
+  return { roots, expectedRight: nto - roots.length };
+}
+
 /**
  * Verify MMR(A) is a committed prefix of MMR(B)
  * (draft-bryce "Verifying the Receipt of consistency";
  * go-merklelog `VerifyConsistency`).
  *
+ * BOTH sizes are CALLER-SUPPLIED trusted state (ADR-0066 D5.4), never read
+ * off the proof: `sizeFrom` is the size of the state `peaksFrom` is the
+ * accumulator of, and `sizeTo` the size `peaksTo` is claimed to be the
+ * accumulator of. The proof contributes only `paths`. Taking either size
+ * from the proof makes the check void: the fold constrains a declared
+ * `sizeFrom` by the origin peak COUNT alone, which a whole family of sizes
+ * share, so one set of paths and peaks verified at many size pairs — with
+ * the draft's own MMR(11) -> MMR(39) material, 24 distinct pairs, of which
+ * one is the true relation. `indexConsistencyProof` still returns the
+ * {@link ConsistencyProof} wire type with its declared sizes; a caller that
+ * relays that type passes `proof.paths` here and supplies the sizes it
+ * trusts, comparing the declared sizes with them separately if it wants to
+ * report a disagreement.
+ *
+ * Routed through {@link consistentRootsForSizes}, so the proof must have the
+ * shape `sizeFrom -> sizeTo` implies: one path per MMR(A) peak, empty above
+ * the split and of length `split - h` below it, with every path below the
+ * split proving the same root. The proven roots must then be the leading
+ * entries of `peaksTo`, and `peaksTo` must hold exactly those plus the
+ * `expectedRight` right peaks no path reaches — so a truncated or padded
+ * target accumulator is rejected on its length alone.
+ *
  * Replaces the plan-0027 always-true stub (FOR-368 Phase 1,
  * plan-2607-29): the previous signature took two inclusion proofs and
  * returned true unconditionally; no caller existed.
  *
- * @param proof - consistency proof `mmrSizeA -> mmrSizeB`
+ * @param sizeFrom - TRUSTED node count of MMR(A)
+ * @param sizeTo - TRUSTED node count of MMR(B)
  * @param peaksFrom - TRUSTED MMR(A) accumulator (e.g. a signed checkpoint
  *   payload), descending height order
+ * @param paths - one inclusion path per MMR(A) peak, in the same order
  * @param peaksTo - MMR(B) accumulator to prove against (e.g. an anchored
  *   on-chain state), descending height order
- * @returns ok, with the MMR(B) accumulator on success
+ * @returns ok, with the MMR(B) accumulator on success. A value that does not
+ *   match `peaksTo` returns `{ok: false, accumulator: []}`; a proof that does
+ *   not have the shape the sizes imply throws one of the typed errors in
+ *   `./errors.js` (all `ConsistencyShapeError` subclasses), which callers
+ *   report as a malformed proof rather than a failed comparison.
  */
 export async function verifyConsistency(
   hasher: Hasher,
-  proof: ConsistencyProof,
+  sizeFrom: bigint,
+  sizeTo: bigint,
   peaksFrom: Uint8Array[],
+  paths: Uint8Array[][],
   peaksTo: Uint8Array[],
 ): Promise<{ ok: boolean; accumulator: Uint8Array[] }> {
-  const proven = await consistentRoots(
+  const { roots, expectedRight } = await consistentRootsForSizes(
     hasher,
-    proof.mmrSizeA - 1n,
+    sizeFrom,
+    sizeTo,
     peaksFrom,
-    proof.paths,
+    paths,
   );
-  // Both lists are in descending height order, so every proven root must
-  // appear in order within peaksTo (a linear scan; go-merklelog semantics:
-  // a proven root matches the current peak or exactly the next one down).
-  let ito = 0;
-  for (const root of proven) {
-    if (ito < peaksTo.length && arraysEqual(peaksTo[ito], root)) {
-      continue;
-    }
-    ito += 1;
-    if (ito >= peaksTo.length || !arraysEqual(peaksTo[ito], root)) {
+  // roots is the leading run of the MMR(B) accumulator and expectedRight
+  // counts the peaks below every MMR(A) peak, which no path reaches. Together
+  // they fix the length of MMR(B)'s accumulator, so the supplied peaksTo must
+  // have that length and must start with the proven roots.
+  if (peaksTo.length !== roots.length + expectedRight) {
+    return { ok: false, accumulator: [] };
+  }
+  for (let i = 0; i < roots.length; i++) {
+    if (!arraysEqual(peaksTo[i], roots[i])) {
       return { ok: false, accumulator: [] };
     }
   }
-  // The full MMR(B) accumulator is the proven prefix plus any right-peaks;
-  // returning peaksTo is safe because consistentRoots enforced one proof
-  // per MMR(A) peak (see go-merklelog VerifyConsistency).
   return { ok: true, accumulator: peaksTo };
 }
 
@@ -286,3 +494,40 @@ export function indexConsistencyProof(
   }
   return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }
+
+/** Name the value found where a path or a path element was required. */
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+/**
+ * Require `paths` to be a DENSE array of `Uint8Array[]`: no holes, and every
+ * element an array of `Uint8Array`. A hole and an out-of-type entry both
+ * survive the peak COUNT check and would otherwise reach the hashing loop,
+ * where they surface as a bare `TypeError` outside the
+ * `ConsistencyShapeError` family (review finding C6).
+ */
+function assertDensePaths(paths: Uint8Array[][]): void {
+  for (let i = 0; i < paths.length; i++) {
+    if (!(i in paths)) {
+      throw new ConsistencyPathMalformed("missing (the array is sparse)", i);
+    }
+    const path = paths[i] as unknown;
+    if (!Array.isArray(path)) {
+      throw new ConsistencyPathMalformed(
+        `not an array (got ${typeName(path)})`,
+        i,
+      );
+    }
+    for (let j = 0; j < path.length; j++) {
+      if (!(j in path) || !((path[j] as unknown) instanceof Uint8Array)) {
+        throw new ConsistencyPathMalformed(
+          `element ${j} is not a Uint8Array (got ${typeName(path[j])})`,
+          i,
+        );
+      }
+    }
+  }
+}