@forestrie/merklelog 0.2.1 → 0.4.0

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;
@@ -89,6 +89,89 @@ export function inclusionProof(get, mmrLastIndex, i) {
         g += 1n;
     }
 }
+/**
+ * The sibling *indices* of an inclusion proof for the node at MMR index `i` in
+ * the tree ending at `mmrLastIndex` — the index-only counterpart of
+ * {@link inclusionProof} (go-merklelog `mmr/proof.go` InclusionProofPath). The
+ * values at these indices, in order, are the proof. Store-free: pure position
+ * arithmetic, so a caller can assemble a proof's node values from any source
+ * (a receipt path, consistency-proof paths, tiles).
+ */
+export function inclusionProofPath(mmrLastIndex, i) {
+    let g = BigInt(indexHeight(i));
+    const proof = [];
+    for (;;) {
+        const siblingOffset = 2n << g;
+        let iSibling;
+        if (BigInt(indexHeight(i + 1n)) > g) {
+            iSibling = i - siblingOffset + 1n;
+            i += 1n;
+        }
+        else {
+            iSibling = i + siblingOffset - 1n;
+            i += siblingOffset;
+        }
+        if (iSibling > mmrLastIndex) {
+            return proof;
+        }
+        proof.push(iSibling);
+        g += 1n;
+    }
+}
+/**
+ * Extend the inclusion proof for node `i` from MMR size A to size B, reading
+ * sibling values from `get`. The result's `path` proves `i` at size B and shares
+ * its first `heightA` elements with the size-A proof — so a stale receipt's
+ * path (leaf → its old peak) is exactly `path[0..heightA]`, and the remainder is
+ * the tile-free extension. Direct port of go-merklelog `InclusionProofLocalExtend`.
+ *
+ * @throws if `mmrSizeB <= mmrSizeA`.
+ */
+export function inclusionProofLocalExtend(get, mmrSizeA, mmrSizeB, i) {
+    if (mmrSizeB <= mmrSizeA) {
+        throw new Error(`mmrSizeB (${mmrSizeB}) must be greater than mmrSizeA (${mmrSizeA})`);
+    }
+    const logIndex = i;
+    const path = [];
+    let height = 0n;
+    let prevComplete = false;
+    let peakIndexA = 0n;
+    let heightA = 0;
+    while (i < mmrSizeB) {
+        const siblingOffset = (2n << height) - 1n; // go-merklelog SiblingOffset
+        let iSibling;
+        let delta;
+        if (BigInt(indexHeight(i + 1n)) > BigInt(indexHeight(i))) {
+            iSibling = i - siblingOffset;
+            delta = 1n;
+        }
+        else {
+            iSibling = i + siblingOffset;
+            delta = 2n << height;
+        }
+        // The first sibling that lies outside MMR(A) marks the end of the size-A
+        // proof: `i` is the size-A covering peak and the prefix so far is its proof.
+        if (iSibling >= mmrSizeA && !prevComplete) {
+            peakIndexA = i;
+            heightA = path.length;
+            prevComplete = true;
+        }
+        if (iSibling >= mmrSizeB)
+            break;
+        path.push(get(iSibling));
+        i += delta;
+        height += 1n;
+    }
+    return {
+        logIndex,
+        path,
+        sizeA: mmrSizeA,
+        peakIndexA,
+        heightA,
+        sizeB: mmrSizeB,
+        peakIndexB: i,
+    };
+}
 /**
  * Peaks bitmap for an MMR size: the numeric value equals the leaf count of the
  * largest valid MMR with size <= `mmrSize`; each set bit marks a perfect
@@ -110,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.2.1",
+  "version": "0.4.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,20 @@ 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,
+  ConsistencyRootMismatch,
+  SizeMustIncrease,
+} 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";
@@ -81,12 +92,15 @@ export type { Hasher } from "./mmr/types.js";
 // MMR proof building (pure; store-agnostic) — plan-2607-15 §4 (go: mmr/proof.go, peaks.go)
 export {
   inclusionProof,
+  inclusionProofPath,
+  inclusionProofLocalExtend,
   peakMMRIndexes,
   peaksBitmap,
   peakIndexForLeafProof,
+  mmrSizeForLeafCount,
   indexHeight,
   firstMMRSize,
   massifIndexFromMMRIndex,
   peakStackMap,
 } from "./mmr/proof.js";
-export type { NodeGetter } from "./mmr/proof.js";
+export type { NodeGetter, ConsistencyProofLocal } from "./mmr/proof.js";

package/src/mmr/algorithms.ts

@@ -12,7 +12,22 @@
  */
 
 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,
+  ConsistencyPeakCountMismatch,
+  ConsistencyRootMismatch,
+  IncompleteTreeSize,
+  SizeMustIncrease,
+} from "./errors.js";
 import { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
@@ -185,6 +200,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 +243,212 @@ 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 {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 {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 }> {
+  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 (paths.length !== n) {
+    throw new ConsistencyPeakCountMismatch(n, paths.length);
+  }
+  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 };
 }
 

package/src/mmr/errors.ts

@@ -0,0 +1,93 @@
+/**
+ * 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: string) {
+    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 {
+  constructor(readonly size: bigint) {
+    super(`size ${size} is not a complete MMR 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 {
+  constructor(
+    readonly expected: number,
+    readonly actual: number,
+  ) {
+    super(`expected ${expected} entries for the origin peaks, got ${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 {
+  constructor(
+    readonly index: number,
+    readonly expected: number,
+    readonly actual: number,
+  ) {
+    super(`path ${index}: expected length ${expected}, got ${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 {
+  constructor(readonly index: number) {
+    super(`path ${index} proves a different root from the paths before it`);
+    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 {
+  constructor(
+    readonly sizeFrom: bigint,
+    readonly sizeTo: bigint,
+  ) {
+    super(`sizeTo (${sizeTo}) must exceed sizeFrom (${sizeFrom})`);
+    this.name = "SizeMustIncrease";
+  }
+}

package/src/mmr/proof.ts

@@ -14,7 +14,7 @@
 export type NodeGetter = (i: bigint) => Uint8Array;
 
 /** Number of bits needed to represent `num` (0 for 0). */
-function bitLength(num: bigint): number {
+export function bitLength(num: bigint): number {
   if (num <= 0n) return 0;
   return num.toString(2).length;
 }
@@ -100,6 +100,115 @@ export function inclusionProof(
   }
 }
 
+/**
+ * The sibling *indices* of an inclusion proof for the node at MMR index `i` in
+ * the tree ending at `mmrLastIndex` — the index-only counterpart of
+ * {@link inclusionProof} (go-merklelog `mmr/proof.go` InclusionProofPath). The
+ * values at these indices, in order, are the proof. Store-free: pure position
+ * arithmetic, so a caller can assemble a proof's node values from any source
+ * (a receipt path, consistency-proof paths, tiles).
+ */
+export function inclusionProofPath(mmrLastIndex: bigint, i: bigint): bigint[] {
+  let g = BigInt(indexHeight(i));
+  const proof: bigint[] = [];
+  for (;;) {
+    const siblingOffset = 2n << g;
+    let iSibling: bigint;
+    if (BigInt(indexHeight(i + 1n)) > g) {
+      iSibling = i - siblingOffset + 1n;
+      i += 1n;
+    } else {
+      iSibling = i + siblingOffset - 1n;
+      i += siblingOffset;
+    }
+    if (iSibling > mmrLastIndex) {
+      return proof;
+    }
+    proof.push(iSibling);
+    g += 1n;
+  }
+}
+
+/**
+ * An inclusion proof that has been extended from MMR size A to size B: the size-B
+ * proof is an *extension* of the size-A proof, sharing its first `heightA`
+ * elements. (go-merklelog `mmr/proofrefresh.go` ConsistencyProofLocal.)
+ */
+export type ConsistencyProofLocal = {
+  /** The node (leaf) MMR index being proven. */
+  logIndex: bigint;
+  /** Full inclusion path at size B; `path[0..heightA]` is the size-A proof. */
+  path: Uint8Array[];
+  sizeA: bigint;
+  /** Peak (root) index covering `logIndex` at size A. */
+  peakIndexA: bigint;
+  /** Length of the shared prefix — the size-A proof; the rest extends it. */
+  heightA: number;
+  sizeB: bigint;
+  /** Peak (root) index covering `logIndex` at size B. */
+  peakIndexB: bigint;
+};
+
+/**
+ * Extend the inclusion proof for node `i` from MMR size A to size B, reading
+ * sibling values from `get`. The result's `path` proves `i` at size B and shares
+ * its first `heightA` elements with the size-A proof — so a stale receipt's
+ * path (leaf → its old peak) is exactly `path[0..heightA]`, and the remainder is
+ * the tile-free extension. Direct port of go-merklelog `InclusionProofLocalExtend`.
+ *
+ * @throws if `mmrSizeB <= mmrSizeA`.
+ */
+export function inclusionProofLocalExtend(
+  get: NodeGetter,
+  mmrSizeA: bigint,
+  mmrSizeB: bigint,
+  i: bigint,
+): ConsistencyProofLocal {
+  if (mmrSizeB <= mmrSizeA) {
+    throw new Error(
+      `mmrSizeB (${mmrSizeB}) must be greater than mmrSizeA (${mmrSizeA})`,
+    );
+  }
+  const logIndex = i;
+  const path: Uint8Array[] = [];
+  let height = 0n;
+  let prevComplete = false;
+  let peakIndexA = 0n;
+  let heightA = 0;
+  while (i < mmrSizeB) {
+    const siblingOffset = (2n << height) - 1n; // go-merklelog SiblingOffset
+    let iSibling: bigint;
+    let delta: bigint;
+    if (BigInt(indexHeight(i + 1n)) > BigInt(indexHeight(i))) {
+      iSibling = i - siblingOffset;
+      delta = 1n;
+    } else {
+      iSibling = i + siblingOffset;
+      delta = 2n << height;
+    }
+    // The first sibling that lies outside MMR(A) marks the end of the size-A
+    // proof: `i` is the size-A covering peak and the prefix so far is its proof.
+    if (iSibling >= mmrSizeA && !prevComplete) {
+      peakIndexA = i;
+      heightA = path.length;
+      prevComplete = true;
+    }
+    if (iSibling >= mmrSizeB) break;
+    path.push(get(iSibling));
+    i += delta;
+    height += 1n;
+  }
+  return {
+    logIndex,
+    path,
+    sizeA: mmrSizeA,
+    peakIndexA,
+    heightA,
+    sizeB: mmrSizeB,
+    peakIndexB: i,
+  };
+}
+
 /**
  * Peaks bitmap for an MMR size: the numeric value equals the leaf count of the
  * largest valid MMR with size <= `mmrSize`; each set bit marks a perfect
@@ -121,8 +230,25 @@ export function peaksBitmap(mmrSize: bigint): bigint {
   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: bigint): bigint {
+  return 2n * leaves - BigInt(popcount(leaves));
+}
+
 /** Population count of a non-negative BigInt. */
-function popcount(x: bigint): number {
+export function popcount(x: bigint): number {
   let count = 0;
   let v = x;
   while (v > 0n) {