@forestrie/merklelog 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -18,10 +18,11 @@ export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
 export type { MassifLeafIndex, LocatedLeaf } from "./massifs/leafindex.js";
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
 export { heightIndex, height, mmrIndexFromLeafIndex, leafIndex, mmrPosition, mmrSizeFromHeightIndex, leafCount, leafCountFromHeightIndex, } from "./mmr/math.js";
-export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, indexConsistencyProof, type ConsistencyProof, } from "./mmr/algorithms.js";
+export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, consistentRootsForSizes, indexConsistencyProof, type ConsistencyProof, } from "./mmr/algorithms.js";
+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";
-export { inclusionProof, inclusionProofPath, inclusionProofLocalExtend, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";
+export { inclusionProof, inclusionProofPath, inclusionProofLocalExtend, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, mmrSizeForLeafCount, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";
 export type { NodeGetter, ConsistencyProofLocal } from "./mmr/proof.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -20,7 +20,10 @@ export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
 // Export mmr module
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
 export { heightIndex, height, mmrIndexFromLeafIndex, leafIndex, mmrPosition, mmrSizeFromHeightIndex, leafCount, leafCountFromHeightIndex, } from "./mmr/math.js";
-export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, indexConsistencyProof, } from "./mmr/algorithms.js";
+export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, consistentRootsForSizes, indexConsistencyProof, } 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";
 // MMR proof building (pure; store-agnostic) — plan-2607-15 §4 (go: mmr/proof.go, peaks.go)
-export { inclusionProof, inclusionProofPath, inclusionProofLocalExtend, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";
+export { inclusionProof, inclusionProofPath, inclusionProofLocalExtend, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, mmrSizeForLeafCount, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";

package/dist/mmr/algorithms.d.ts

@@ -79,28 +79,114 @@ 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)
  */
 export declare function consistentRoots(hasher: Hasher, ifrom: bigint, accumulatorFrom: Uint8Array[], paths: Uint8Array[][]): Promise<Uint8Array[]>;
+/**
+ * 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 declare function consistentRootsForSizes(hasher: Hasher, sizeFrom: bigint, sizeTo: bigint, accumulatorFrom: Uint8Array[], paths: Uint8Array[][]): Promise<{
+    roots: Uint8Array[];
+    expectedRight: number;
+}>;
 /**
  * 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 declare function verifyConsistency(hasher: Hasher, proof: ConsistencyProof, peaksFrom: Uint8Array[], peaksTo: Uint8Array[]): Promise<{
+export declare function verifyConsistency(hasher: Hasher, sizeFrom: bigint, sizeTo: bigint, peaksFrom: Uint8Array[], paths: Uint8Array[][], peaksTo: Uint8Array[]): Promise<{
     ok: boolean;
     accumulator: Uint8Array[];
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"algorithms.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAkC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAqB7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,UAAU,EAAE,EACvB,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CAwBrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB"}
+{"version":3,"file":"algorithms.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AA4BpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CA+EzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,UAAU,EAAE,EACvB,KAAK,EAAE,UAAU,EAAE,EAAE,EACrB,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CAqBrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB"}

package/dist/mmr/algorithms.js

@@ -10,7 +10,8 @@
  * And the associated IETF draft specification:
  * https://raw.githubusercontent.com/robinbryce/draft-bryce-cose-receipts-mmr-profile/refs/heads/main/draft-bryce-cose-receipts-mmr-profile.md
  */
-import { inclusionProof, peakMMRIndexes } from "./proof.js";
+import { inclusionProof, peakMMRIndexes, bitLength, popcount, peaksBitmap, mmrSizeForLeafCount, } 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";
@@ -140,6 +141,12 @@ export async function verifyInclusion(hasher, leafHash, proof, root) {
  * 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)
@@ -162,40 +169,186 @@ export async function consistentRoots(hasher, ifrom, accumulatorFrom, paths) {
     }
     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, sizeFrom, sizeTo, accumulatorFrom, paths) {
+    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 = [];
+    // 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;
+    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)) {
+            throw new ConsistencyRootMismatch(i);
+        }
+        offset += subtree;
+        i += 1;
+    }
+    if (n > above) {
+        roots.push(root);
+    }
+    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, proof, peaksFrom, peaksTo) {
-    const proven = await consistentRoots(hasher, proof.mmrSizeA - 1n, peaksFrom, proof.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)) {
+export async function verifyConsistency(hasher, sizeFrom, sizeTo, peaksFrom, paths, peaksTo) {
+    const { roots, expectedRight } = await consistentRootsForSizes(hasher, sizeFrom, sizeTo, peaksFrom, paths);
+    // 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/dist/mmr/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 declare class ConsistencyShapeError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class IncompleteTreeSize extends ConsistencyShapeError {
+    readonly size: bigint;
+    constructor(size: bigint);
+}
+/**
+ * The accumulator or the proof list does not have one entry per origin peak.
+ * The origin peak count is fixed by `sizeFrom` alone.
+ */
+export declare class ConsistencyPeakCountMismatch extends ConsistencyShapeError {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+/**
+ * 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 declare class ConsistencyPathLengthMismatch extends ConsistencyShapeError {
+    readonly index: number;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(index: number, expected: number, actual: number);
+}
+/**
+ * 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 declare class ConsistencyRootMismatch extends ConsistencyShapeError {
+    readonly index: number;
+    constructor(index: number);
+}
+/**
+ * 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 declare class SizeMustIncrease extends ConsistencyShapeError {
+    readonly sizeFrom: bigint;
+    readonly sizeTo: bigint;
+    constructor(sizeFrom: bigint, sizeTo: bigint);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/mmr/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AAC9D,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIlC;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,qBAAqB;IAEnE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,qBAAqB;IAEpE,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAFd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,qBAAqB;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAInC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,qBAAqB;IAEvD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B"}

package/dist/mmr/errors.js

@@ -0,0 +1,95 @@
+/**
+ * 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";
+    }
+}

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.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";
@@ -86,6 +97,7 @@ export {
   peakMMRIndexes,
   peaksBitmap,
   peakIndexForLeafProof,
+  mmrSizeForLeafCount,
   indexHeight,
   firstMMRSize,
   massifIndexFromMMRIndex,

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;
 }
@@ -230,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) {