@forestrie/merklelog 0.6.0 → 0.7.0

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/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/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.0",
   "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/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/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;