@forestrie/merklelog 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -18,7 +18,7 @@ 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, } from "./mmr/algorithms.js";
+export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, indexConsistencyProof, type ConsistencyProof, } from "./mmr/algorithms.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";
 export type { Hasher } from "./mmr/types.js";

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,GAClB,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,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,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,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,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -20,7 +20,7 @@ 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, } from "./mmr/algorithms.js";
+export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, indexConsistencyProof, } from "./mmr/algorithms.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, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";

package/dist/mmr/algorithms.d.ts

@@ -11,6 +11,7 @@
  * https://raw.githubusercontent.com/robinbryce/draft-bryce-cose-receipts-mmr-profile/refs/heads/main/draft-bryce-cose-receipts-mmr-profile.md
  */
 import type { Proof, Hasher } from "./types.js";
+import { type NodeGetter } from "./proof.js";
 /**
  * Bags peaks together to compute a single root hash.
  *
@@ -59,21 +60,55 @@ export declare function calculateRoot(hasher: Hasher, leafHash: Uint8Array, proo
  */
 export declare function verifyInclusion(hasher: Hasher, leafHash: Uint8Array, proof: Proof, root: Uint8Array): Promise<boolean>;
 /**
- * Verifies a consistency proof between two MMR states.
+ * Consistency proof between two MMR states (draft-bryce `consistency-proof`,
+ * go-merklelog `ConsistencyProof`): one inclusion path per MMR(A) peak,
+ * proven in MMR(B). Verified against trusted accumulators for both sizes.
+ */
+export interface ConsistencyProof {
+    mmrSizeA: bigint;
+    mmrSizeB: bigint;
+    /** One sibling path per MMR(A) peak (ascending), in peak order. */
+    paths: Uint8Array[][];
+}
+/**
+ * Recover the MMR(B) accumulator prefix committed by the MMR(A) peaks
+ * (draft-bryce `consistent_roots`; go-merklelog `ConsistentRoots`).
  *
- * WARNING — NOT IMPLEMENTED. This is a stub: it compares each root against
- * itself and therefore ALWAYS returns true. It performs no real consistency
- * check and MUST NOT be relied upon for security. No worker path currently
- * calls it. See the reference `verify_consistency` (algorithms.py) for the
- * intended algorithm (verify proof2 extends proof1 via position-committed
- * interior hashing).
+ * Each MMR(A) peak is an interior node of MMR(B) at an immovable position;
+ * its inclusion path climbs to the covering MMR(B) peak. Consecutive
+ * duplicate roots collapse (many old peaks share one new peak). Requires
+ * one path per MMR(A) peak (draft: `len(peaks(ifrom)) == len(accumulatorfrom)`).
  *
- * @param hasher - Cryptographic hasher instance
- * @param proof1 - Proof for the first state
- * @param proof2 - Proof for the second state
- * @param root1 - Root hash of the first state
- * @param root2 - Root hash of the second state
- * @returns Always true (stub) — do not use for verification
+ * @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[]>;
+/**
+ * Verify MMR(A) is a committed prefix of MMR(B)
+ * (draft-bryce "Verifying the Receipt of consistency";
+ * go-merklelog `VerifyConsistency`).
+ *
+ * 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 peaksFrom - TRUSTED MMR(A) accumulator (e.g. a signed checkpoint
+ *   payload), descending height 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
+ */
+export declare function verifyConsistency(hasher: Hasher, proof: ConsistencyProof, peaksFrom: Uint8Array[], peaksTo: Uint8Array[]): Promise<{
+    ok: boolean;
+    accumulator: Uint8Array[];
+}>;
+/**
+ * Generate a consistency proof `mmrIndexA -> mmrIndexB` from node data
+ * (go-merklelog `IndexConsistencyProof`): an inclusion path in MMR(B) for
+ * each MMR(A) peak. Node access is by MMR index (massif tiles or any
+ * replicated store).
  */
-export declare function verifyConsistency(hasher: Hasher, proof1: Proof, proof2: Proof, root1: Uint8Array, root2: Uint8Array): boolean;
+export declare function indexConsistencyProof(get: NodeGetter, mmrIndexA: bigint, mmrIndexB: bigint): ConsistencyProof;
 //# sourceMappingURL=algorithms.d.ts.map

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;AAqBhD;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,KAAK,EACb,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,UAAU,GAChB,OAAO,CAKT"}
+{"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"}

package/dist/mmr/algorithms.js

@@ -10,6 +10,7 @@
  * 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 { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
@@ -131,25 +132,82 @@ export async function verifyInclusion(hasher, leafHash, proof, root) {
     return arraysEqual(calculatedRoot, root);
 }
 /**
- * Verifies a consistency proof between two MMR states.
+ * Recover the MMR(B) accumulator prefix committed by the MMR(A) peaks
+ * (draft-bryce `consistent_roots`; go-merklelog `ConsistentRoots`).
  *
- * WARNING — NOT IMPLEMENTED. This is a stub: it compares each root against
- * itself and therefore ALWAYS returns true. It performs no real consistency
- * check and MUST NOT be relied upon for security. No worker path currently
- * calls it. See the reference `verify_consistency` (algorithms.py) for the
- * intended algorithm (verify proof2 extends proof1 via position-committed
- * interior hashing).
+ * Each MMR(A) peak is an interior node of MMR(B) at an immovable position;
+ * its inclusion path climbs to the covering MMR(B) peak. Consecutive
+ * duplicate roots collapse (many old peaks share one new peak). Requires
+ * one path per MMR(A) peak (draft: `len(peaks(ifrom)) == len(accumulatorfrom)`).
  *
- * @param hasher - Cryptographic hasher instance
- * @param proof1 - Proof for the first state
- * @param proof2 - Proof for the second state
- * @param root1 - Root hash of the first state
- * @param root2 - Root hash of the second state
- * @returns Always true (stub) — do not use for verification
+ * @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 function verifyConsistency(hasher, proof1, proof2, root1, root2) {
-    // TODO(plan-0027): Implement full consistency check (verify proof2 extends
-    // proof1) with position-committed interior hashing. Until then this returns
-    // true unconditionally and must not be used for any trust decision.
-    return arraysEqual(root1, root1) && arraysEqual(root2, root2);
+export async function consistentRoots(hasher, ifrom, accumulatorFrom, paths) {
+    const fromPeaks = peakMMRIndexes(ifrom);
+    if (fromPeaks.length !== paths.length) {
+        throw new Error(`a proof for each accumulator peak is required: ${fromPeaks.length} peaks, ${paths.length} paths`);
+    }
+    if (accumulatorFrom.length !== fromPeaks.length) {
+        throw new Error(`accumulator length mismatch: ${accumulatorFrom.length} values for ${fromPeaks.length} peaks`);
+    }
+    const roots = [];
+    for (let i = 0; i < accumulatorFrom.length; i++) {
+        const root = await calculateRoot(hasher, accumulatorFrom[i], { path: paths[i], mmrIndex: fromPeaks[i] }, fromPeaks[i]);
+        if (roots.length > 0 && arraysEqual(roots[roots.length - 1], root)) {
+            continue;
+        }
+        roots.push(root);
+    }
+    return roots;
+}
+/**
+ * Verify MMR(A) is a committed prefix of MMR(B)
+ * (draft-bryce "Verifying the Receipt of consistency";
+ * go-merklelog `VerifyConsistency`).
+ *
+ * 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 peaksFrom - TRUSTED MMR(A) accumulator (e.g. a signed checkpoint
+ *   payload), descending height 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
+ */
+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)) {
+            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 };
+}
+/**
+ * Generate a consistency proof `mmrIndexA -> mmrIndexB` from node data
+ * (go-merklelog `IndexConsistencyProof`): an inclusion path in MMR(B) for
+ * each MMR(A) peak. Node access is by MMR index (massif tiles or any
+ * replicated store).
+ */
+export function indexConsistencyProof(get, mmrIndexA, mmrIndexB) {
+    const paths = [];
+    for (const peak of peakMMRIndexes(mmrIndexA)) {
+        paths.push(inclusionProof(get, mmrIndexB, peak));
+    }
+    return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }

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;AAoCnD;;;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;;;;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;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;;;;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"}

package/dist/mmr/proof.js

@@ -35,6 +35,13 @@ function jumpLeftPerfect(pos) {
  * (go-merklelog `mmr/indexheight.go` PosHeight)
  */
 function posHeight(pos) {
+    // Positions are 1-based; `pos <= 0` is out of domain and would spin forever
+    // (`jumpLeftPerfect(0) === 0`, `allOnes(0) === false`). Reject in bounded
+    // time so a malformed size fed to any caller (peakMMRIndexes, indexHeight,
+    // inclusionProof, …) fails loudly instead of hanging the verifier (FOR-414).
+    if (pos <= 0n) {
+        throw new Error(`posHeight: position must be >= 1, got ${pos}`);
+    }
     let current = pos;
     while (!allOnes(current)) {
         current = jumpLeftPerfect(current);

package/package.json

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

package/src/index.ts

@@ -70,6 +70,9 @@ export {
   calculateRoot,
   verifyInclusion,
   verifyConsistency,
+  consistentRoots,
+  indexConsistencyProof,
+  type ConsistencyProof,
 } from "./mmr/algorithms.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";

package/src/mmr/algorithms.ts

@@ -12,6 +12,7 @@
  */
 
 import type { Proof, Hasher } from "./types.js";
+import { inclusionProof, peakMMRIndexes, type NodeGetter } from "./proof.js";
 import { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
@@ -164,31 +165,124 @@ export async function verifyInclusion(
 }
 
 /**
- * Verifies a consistency proof between two MMR states.
+ * Consistency proof between two MMR states (draft-bryce `consistency-proof`,
+ * go-merklelog `ConsistencyProof`): one inclusion path per MMR(A) peak,
+ * proven in MMR(B). Verified against trusted accumulators for both sizes.
+ */
+export interface ConsistencyProof {
+  mmrSizeA: bigint;
+  mmrSizeB: bigint;
+  /** One sibling path per MMR(A) peak (ascending), in peak order. */
+  paths: Uint8Array[][];
+}
+
+/**
+ * Recover the MMR(B) accumulator prefix committed by the MMR(A) peaks
+ * (draft-bryce `consistent_roots`; go-merklelog `ConsistentRoots`).
  *
- * WARNING — NOT IMPLEMENTED. This is a stub: it compares each root against
- * itself and therefore ALWAYS returns true. It performs no real consistency
- * check and MUST NOT be relied upon for security. No worker path currently
- * calls it. See the reference `verify_consistency` (algorithms.py) for the
- * intended algorithm (verify proof2 extends proof1 via position-committed
- * interior hashing).
+ * Each MMR(A) peak is an interior node of MMR(B) at an immovable position;
+ * its inclusion path climbs to the covering MMR(B) peak. Consecutive
+ * duplicate roots collapse (many old peaks share one new peak). Requires
+ * one path per MMR(A) peak (draft: `len(peaks(ifrom)) == len(accumulatorfrom)`).
  *
- * @param hasher - Cryptographic hasher instance
- * @param proof1 - Proof for the first state
- * @param proof2 - Proof for the second state
- * @param root1 - Root hash of the first state
- * @param root2 - Root hash of the second state
- * @returns Always true (stub) — do not use for verification
+ * @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 async function consistentRoots(
+  hasher: Hasher,
+  ifrom: bigint,
+  accumulatorFrom: Uint8Array[],
+  paths: Uint8Array[][],
+): Promise<Uint8Array[]> {
+  const fromPeaks = peakMMRIndexes(ifrom);
+  if (fromPeaks.length !== paths.length) {
+    throw new Error(
+      `a proof for each accumulator peak is required: ${fromPeaks.length} peaks, ${paths.length} paths`,
+    );
+  }
+  if (accumulatorFrom.length !== fromPeaks.length) {
+    throw new Error(
+      `accumulator length mismatch: ${accumulatorFrom.length} values for ${fromPeaks.length} peaks`,
+    );
+  }
+  const roots: Uint8Array[] = [];
+  for (let i = 0; i < accumulatorFrom.length; i++) {
+    const root = await calculateRoot(
+      hasher,
+      accumulatorFrom[i],
+      { path: paths[i], mmrIndex: fromPeaks[i] },
+      fromPeaks[i],
+    );
+    if (roots.length > 0 && arraysEqual(roots[roots.length - 1], root)) {
+      continue;
+    }
+    roots.push(root);
+  }
+  return roots;
+}
+
+/**
+ * Verify MMR(A) is a committed prefix of MMR(B)
+ * (draft-bryce "Verifying the Receipt of consistency";
+ * go-merklelog `VerifyConsistency`).
+ *
+ * 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 peaksFrom - TRUSTED MMR(A) accumulator (e.g. a signed checkpoint
+ *   payload), descending height 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
  */
-export function verifyConsistency(
+export async function verifyConsistency(
   hasher: Hasher,
-  proof1: Proof,
-  proof2: Proof,
-  root1: Uint8Array,
-  root2: Uint8Array,
-): boolean {
-  // TODO(plan-0027): Implement full consistency check (verify proof2 extends
-  // proof1) with position-committed interior hashing. Until then this returns
-  // true unconditionally and must not be used for any trust decision.
-  return arraysEqual(root1, root1) && arraysEqual(root2, root2);
+  proof: ConsistencyProof,
+  peaksFrom: Uint8Array[],
+  peaksTo: Uint8Array[],
+): Promise<{ ok: boolean; accumulator: Uint8Array[] }> {
+  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)) {
+      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 };
+}
+
+/**
+ * Generate a consistency proof `mmrIndexA -> mmrIndexB` from node data
+ * (go-merklelog `IndexConsistencyProof`): an inclusion path in MMR(B) for
+ * each MMR(A) peak. Node access is by MMR index (massif tiles or any
+ * replicated store).
+ */
+export function indexConsistencyProof(
+  get: NodeGetter,
+  mmrIndexA: bigint,
+  mmrIndexB: bigint,
+): ConsistencyProof {
+  const paths: Uint8Array[][] = [];
+  for (const peak of peakMMRIndexes(mmrIndexA)) {
+    paths.push(inclusionProof(get, mmrIndexB, peak));
+  }
+  return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }

package/src/mmr/proof.ts

@@ -40,6 +40,13 @@ function jumpLeftPerfect(pos: bigint): bigint {
  * (go-merklelog `mmr/indexheight.go` PosHeight)
  */
 function posHeight(pos: bigint): number {
+  // Positions are 1-based; `pos <= 0` is out of domain and would spin forever
+  // (`jumpLeftPerfect(0) === 0`, `allOnes(0) === false`). Reject in bounded
+  // time so a malformed size fed to any caller (peakMMRIndexes, indexHeight,
+  // inclusionProof, …) fails loudly instead of hanging the verifier (FOR-414).
+  if (pos <= 0n) {
+    throw new Error(`posHeight: position must be >= 1, got ${pos}`);
+  }
   let current = pos;
   while (!allOnes(current)) {
     current = jumpLeftPerfect(current);