@forestrie/merklelog 0.3.0 → 0.5.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, 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";
-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,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,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, ConsistencyPathMalformed, ConsistencyRootMismatch, SizeMustIncrease, SizeNotUint64, } 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,117 @@ 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 {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 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;AAsCpB;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;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,CA2FzD;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,10 +10,18 @@
  * 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, 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.
  *
@@ -140,6 +148,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 +176,201 @@ 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 {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, sizeFrom, sizeTo, accumulatorFrom, paths) {
+    // 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 = [];
+    // 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 };
 }
 /**
@@ -211,3 +386,34 @@ export function indexConsistencyProof(get, mmrIndexA, mmrIndexB) {
     }
     return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }
+/** Name the value found where a path or a path element was required. */
+function typeName(value) {
+    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) {
+    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];
+        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] instanceof Uint8Array)) {
+                throw new ConsistencyPathMalformed(`element ${j} is not a Uint8Array (got ${typeName(path[j])})`, i);
+            }
+        }
+    }
+}

package/dist/mmr/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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);
+}
+/**
+ * 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 declare class SizeNotUint64 extends ConsistencyShapeError {
+    readonly which: "sizeFrom" | "sizeTo";
+    readonly size: bigint;
+    constructor(which: "sizeFrom" | "sizeTo", size: bigint);
+}
+/**
+ * `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 declare class ConsistencyPathMalformed extends ConsistencyShapeError {
+    readonly detail: string;
+    readonly index?: number | undefined;
+    constructor(detail: string, index?: number | undefined);
+}
+//# 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;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,qBAAqB;IAEpD,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,KAAK,EAAE,UAAU,GAAG,QAAQ,EAC5B,IAAI,EAAE,MAAM;CAKxB;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,SAAQ,qBAAqB;IAE/D,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;gBADd,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,YAAA;CAO1B"}