@forestrie/merklelog 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -15,10 +15,10 @@ export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
-export type { MassifLeafIndex } 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,MAAM,wBAAwB,CAAC;AAG9D,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/massifs/leafindex.d.ts

@@ -26,6 +26,15 @@
 export declare class MissingIndexError extends Error {
     constructor(message: string);
 }
+/**
+ * A located leaf: its MMR index plus the 8-byte idtimestamp (big-endian) the
+ * urkle leaf record is keyed by. Together these are the two halves of the
+ * permanent entry id (`idtimestamp_be8 || mmrIndex_be8`).
+ */
+export interface LocatedLeaf {
+    mmrIndex: bigint;
+    idtimestampBe8: Uint8Array;
+}
 /** Content-hash leaf lookup over one massif blob (FOR-373). */
 export interface MassifLeafIndex {
     /**
@@ -34,6 +43,12 @@ export interface MassifLeafIndex {
      * bytes.
      */
     findByContentHash(h: Uint8Array): bigint | null;
+    /**
+     * Like {@link findByContentHash} but also recovers the leaf's idtimestamp
+     * (the 8-byte urkle leaf key), so a caller can reconstruct the full entry id
+     * offline. Returns `null` when the hash is not present. `h` must be 32 bytes.
+     */
+    findLeafByContentHash(h: Uint8Array): LocatedLeaf | null;
     /** Number of populated leaves in this blob. */
     leafCount: number;
 }

package/dist/massifs/leafindex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"leafindex.d.ts","sourceRoot":"","sources":["../../src/massifs/leafindex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAeH;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,UAAU,GAAG,eAAe,CA+D5E"}
+{"version":3,"file":"leafindex.d.ts","sourceRoot":"","sources":["../../src/massifs/leafindex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,UAAU,CAAC;CAC5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD;;;;OAIG;IACH,qBAAqB,CAAC,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC;IACzD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,UAAU,GAAG,eAAe,CAgF5E"}

package/dist/massifs/leafindex.js

@@ -27,6 +27,7 @@ import { massifLogEntries } from "./massiflogentries.js";
 import { firstMMRSize, peaksBitmap } from "../mmr/proof.js";
 import { mmrIndex as mmrIndexFromLeafIndex } from "../mmr/index.js";
 const HASH_BYTES = Urkle.LeafValueBytes; // 32
+const KEY_BYTES = Urkle.LeafKeyBytes; // 8 (idtimestamp, big-endian)
 const VALUE_OFFSET = Urkle.LeafValueOffset; // 8 (after the 8-byte key)
 const RECORD_BYTES = Urkle.LeafRecordBytes; // 128
 /**
@@ -98,7 +99,8 @@ export function openMassifLeafIndex(massifBytes) {
             break;
         populated = ordinal + 1;
     }
-    const findByContentHash = (h) => {
+    /** Ordinal of the populated leaf whose value column equals `h`, or -1. */
+    const ordinalForContentHash = (h) => {
         if (h.length !== HASH_BYTES) {
             throw new Error(`content hash must be ${HASH_BYTES} bytes, got ${h.length}`);
         }
@@ -107,11 +109,28 @@ export function openMassifLeafIndex(massifBytes) {
             const valueOff = recordOff + VALUE_OFFSET;
             if (valueOff + HASH_BYTES > massifBytes.byteLength)
                 break;
-            if (equals32(massifBytes, valueOff, h)) {
-                return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
-            }
+            if (equals32(massifBytes, valueOff, h))
+                return ordinal;
         }
-        return null;
+        return -1;
+    };
+    const findByContentHash = (h) => {
+        const ordinal = ordinalForContentHash(h);
+        if (ordinal < 0)
+            return null;
+        return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
+    };
+    const findLeafByContentHash = (h) => {
+        const ordinal = ordinalForContentHash(h);
+        if (ordinal < 0)
+            return null;
+        // The leaf record is `[key(8) || value(32) || …]`; the key IS the
+        // big-endian idtimestamp the sealer assigned (go-merklelog urkle leafrecord).
+        const keyOff = leafTableStart + ordinal * RECORD_BYTES;
+        return {
+            mmrIndex: mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal)),
+            idtimestampBe8: massifBytes.slice(keyOff, keyOff + KEY_BYTES),
+        };
     };
-    return { findByContentHash, leafCount: populated };
+    return { findByContentHash, findLeafByContentHash, leafCount: populated };
 }

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/package.json

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

package/src/index.ts

@@ -51,7 +51,7 @@ export type { MassifNodeStore } from "./massifs/nodestore.js";
 
 // Content-hash leaf lookup over the massif index region (FOR-373)
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
-export type { MassifLeafIndex } from "./massifs/leafindex.js";
+export type { MassifLeafIndex, LocatedLeaf } from "./massifs/leafindex.js";
 
 // Export mmr module
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
@@ -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/massifs/leafindex.ts

@@ -29,6 +29,7 @@ import { firstMMRSize, peaksBitmap } from "../mmr/proof.js";
 import { mmrIndex as mmrIndexFromLeafIndex } from "../mmr/index.js";
 
 const HASH_BYTES = Urkle.LeafValueBytes; // 32
+const KEY_BYTES = Urkle.LeafKeyBytes; // 8 (idtimestamp, big-endian)
 const VALUE_OFFSET = Urkle.LeafValueOffset; // 8 (after the 8-byte key)
 const RECORD_BYTES = Urkle.LeafRecordBytes; // 128
 
@@ -44,6 +45,16 @@ export class MissingIndexError extends Error {
   }
 }
 
+/**
+ * A located leaf: its MMR index plus the 8-byte idtimestamp (big-endian) the
+ * urkle leaf record is keyed by. Together these are the two halves of the
+ * permanent entry id (`idtimestamp_be8 || mmrIndex_be8`).
+ */
+export interface LocatedLeaf {
+  mmrIndex: bigint;
+  idtimestampBe8: Uint8Array;
+}
+
 /** Content-hash leaf lookup over one massif blob (FOR-373). */
 export interface MassifLeafIndex {
   /**
@@ -52,6 +63,12 @@ export interface MassifLeafIndex {
    * bytes.
    */
   findByContentHash(h: Uint8Array): bigint | null;
+  /**
+   * Like {@link findByContentHash} but also recovers the leaf's idtimestamp
+   * (the 8-byte urkle leaf key), so a caller can reconstruct the full entry id
+   * offline. Returns `null` when the hash is not present. `h` must be 32 bytes.
+   */
+  findLeafByContentHash(h: Uint8Array): LocatedLeaf | null;
   /** Number of populated leaves in this blob. */
   leafCount: number;
 }
@@ -123,7 +140,8 @@ export function openMassifLeafIndex(massifBytes: Uint8Array): MassifLeafIndex {
     populated = ordinal + 1;
   }
 
-  const findByContentHash = (h: Uint8Array): bigint | null => {
+  /** Ordinal of the populated leaf whose value column equals `h`, or -1. */
+  const ordinalForContentHash = (h: Uint8Array): number => {
     if (h.length !== HASH_BYTES) {
       throw new Error(
         `content hash must be ${HASH_BYTES} bytes, got ${h.length}`,
@@ -133,12 +151,28 @@ export function openMassifLeafIndex(massifBytes: Uint8Array): MassifLeafIndex {
       const recordOff = leafTableStart + ordinal * RECORD_BYTES;
       const valueOff = recordOff + VALUE_OFFSET;
       if (valueOff + HASH_BYTES > massifBytes.byteLength) break;
-      if (equals32(massifBytes, valueOff, h)) {
-        return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
-      }
+      if (equals32(massifBytes, valueOff, h)) return ordinal;
     }
-    return null;
+    return -1;
+  };
+
+  const findByContentHash = (h: Uint8Array): bigint | null => {
+    const ordinal = ordinalForContentHash(h);
+    if (ordinal < 0) return null;
+    return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
+  };
+
+  const findLeafByContentHash = (h: Uint8Array): LocatedLeaf | null => {
+    const ordinal = ordinalForContentHash(h);
+    if (ordinal < 0) return null;
+    // The leaf record is `[key(8) || value(32) || …]`; the key IS the
+    // big-endian idtimestamp the sealer assigned (go-merklelog urkle leafrecord).
+    const keyOff = leafTableStart + ordinal * RECORD_BYTES;
+    return {
+      mmrIndex: mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal)),
+      idtimestampBe8: massifBytes.slice(keyOff, keyOff + KEY_BYTES),
+    };
   };
 
-  return { findByContentHash, leafCount: populated };
+  return { findByContentHash, findLeafByContentHash, leafCount: populated };
 }

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