@forestrie/merklelog 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export type { MassifStart, LeafComponent, LeafEnumeratorSpec, LeafEntry, } from
 export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
 export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.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,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,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"}
+{"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,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,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

@@ -14,6 +14,7 @@ export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
 export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 // Content-hash leaf lookup over the massif index region (FOR-373)
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";

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

@@ -1 +1 @@
-{"version":3,"file":"massiffull.d.ts","sourceRoot":"","sources":["../../src/massifs/massiffull.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAWT"}
+{"version":3,"file":"massiffull.d.ts","sourceRoot":"","sources":["../../src/massifs/massiffull.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAYT"}

package/dist/massifs/massiffull.js

@@ -13,8 +13,9 @@
 export function isMassifFull(massifHeight, logEntries) {
     // Convert 1-based height to 0-based height index
     const heightIndex = massifHeight - 1;
-    // Expected number of leaves for a full massif: f = 2^g = 1 << heightIndex
-    const expectedLeaves = BigInt(1 << heightIndex);
+    // Expected number of leaves for a full massif: f = 2^g, in bigint (a JS
+    // number `1 << g` wraps at g = 32).
+    const expectedLeaves = 1n << BigInt(heightIndex);
     // Actual number of leaves: f = (n + 1) / 2
     const actualLeaves = (logEntries + 1n) >> 1n;
     return actualLeaves >= expectedLeaves;

package/dist/massifs/massifindex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export declare function massifIndexFromLeafIndex(massifHeight: number, leafIndex: bigint | number): bigint;
+//# sourceMappingURL=massifindex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"massifindex.d.ts","sourceRoot":"","sources":["../../src/massifs/massifindex.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,MAAM,CAMR"}

package/dist/massifs/massifindex.js

@@ -0,0 +1,23 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+import { leafCountForMassifHeight } from "./indexformat.js";
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export function massifIndexFromLeafIndex(massifHeight, leafIndex) {
+    const leavesPerMassif = leafCountForMassifHeight(massifHeight);
+    if (leavesPerMassif === 0n) {
+        throw new RangeError("massifHeight must be at least 1");
+    }
+    return BigInt(leafIndex) / leavesPerMassif;
+}

package/dist/massifs/mmrindex.d.ts

@@ -11,5 +11,5 @@
  * @param blobSize - Size of the massif blob in bytes
  * @returns The last MMR index in the massif
  */
-export declare function computeLastMMRIndex(massifHeight: number, massifIndex: number, blobSize: number): bigint;
+export declare function computeLastMMRIndex(massifHeight: number, massifIndex: number | bigint, blobSize: number): bigint;
 //# sourceMappingURL=mmrindex.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mmrindex.d.ts","sourceRoot":"","sources":["../../src/massifs/mmrindex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,MAAM,CAUR"}
+{"version":3,"file":"mmrindex.d.ts","sourceRoot":"","sources":["../../src/massifs/mmrindex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,QAAQ,EAAE,MAAM,GACf,MAAM,CAUR"}

package/dist/mmr/index.d.ts

@@ -21,7 +21,7 @@ export declare function leafMinusSpurSum(leafIndex: bigint): bigint;
  *
  * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
  */
-export declare function massifFirstLeaf(massifHeight: number, massifIndex: number): bigint;
+export declare function massifFirstLeaf(massifHeight: number, massifIndex: number | bigint): bigint;
 /**
  * Returns the node index for the leaf e
  *

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mmr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,CAYR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAalD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mmr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAaR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAalD"}

package/dist/mmr/index.js

@@ -30,8 +30,9 @@ export function leafMinusSpurSum(leafIndex) {
  * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
  */
 export function massifFirstLeaf(massifHeight, massifIndex) {
-    // The number of nodes 'm' in a massif is: m = (1 << h) - 1
-    const m = BigInt((1 << massifHeight) - 1);
+    // The number of nodes 'm' in a massif is: m = (1 << h) - 1. BigInt shift:
+    // a JS number `1 << h` is negative at h=31 and wraps at h=32.
+    const m = (1n << BigInt(massifHeight)) - 1n;
     // The number of leaves 'f' in every massif: f = (m + 1) / 2
     const f = (m + 1n) >> 1n;
     // The first leaf index is then: leafIndex = f * massifIndex

package/package.json

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

package/src/index.ts

@@ -53,6 +53,7 @@ export {
 } from "./massifs/v2storagepaths.js";
 
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 

package/src/massifs/massiffull.ts

@@ -18,8 +18,9 @@ export function isMassifFull(
   // Convert 1-based height to 0-based height index
   const heightIndex = massifHeight - 1;
 
-  // Expected number of leaves for a full massif: f = 2^g = 1 << heightIndex
-  const expectedLeaves = BigInt(1 << heightIndex);
+  // Expected number of leaves for a full massif: f = 2^g, in bigint (a JS
+  // number `1 << g` wraps at g = 32).
+  const expectedLeaves = 1n << BigInt(heightIndex);
 
   // Actual number of leaves: f = (n + 1) / 2
   const actualLeaves = (logEntries + 1n) >> 1n;

package/src/massifs/massifindex.ts

@@ -0,0 +1,28 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+
+import { leafCountForMassifHeight } from "./indexformat.js";
+
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export function massifIndexFromLeafIndex(
+  massifHeight: number,
+  leafIndex: bigint | number,
+): bigint {
+  const leavesPerMassif = leafCountForMassifHeight(massifHeight);
+  if (leavesPerMassif === 0n) {
+    throw new RangeError("massifHeight must be at least 1");
+  }
+  return BigInt(leafIndex) / leavesPerMassif;
+}

package/src/massifs/mmrindex.ts

@@ -17,7 +17,7 @@ import { massifFirstLeaf } from "../mmr/index.js";
  */
 export function computeLastMMRIndex(
   massifHeight: number,
-  massifIndex: number,
+  massifIndex: number | bigint,
   blobSize: number,
 ): bigint {
   // Calculate number of log entries (nodes) in the blob

package/src/mmr/index.ts

@@ -33,10 +33,11 @@ export function leafMinusSpurSum(leafIndex: bigint): bigint {
  */
 export function massifFirstLeaf(
   massifHeight: number,
-  massifIndex: number,
+  massifIndex: number | bigint,
 ): bigint {
-  // The number of nodes 'm' in a massif is: m = (1 << h) - 1
-  const m = BigInt((1 << massifHeight) - 1);
+  // The number of nodes 'm' in a massif is: m = (1 << h) - 1. BigInt shift:
+  // a JS number `1 << h` is negative at h=31 and wraps at h=32.
+  const m = (1n << BigInt(massifHeight)) - 1n;
 
   // The number of leaves 'f' in every massif: f = (m + 1) / 2
   const f = (m + 1n) >> 1n;