@forestrie/merklelog 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -15,7 +15,7 @@ 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";

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,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"}

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

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/merklelog",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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";

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