@forestrie/merklelog 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Bryce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @forestrie/merklelog
+
+TypeScript implementation of the MMR (Merkle Mountain Range) merklelog format.
+
+This package provides TypeScript implementations of the algorithms and data structures defined by the [go-merklelog](https://github.com/forestrie/go-merklelog) project.
+
+## Overview
+
+The package is organized into three main modules:
+
+- **uint64**: BigInt-based wrapper for 64-bit unsigned integer operations
+- **mmr**: Core MMR algorithms including inclusion proofs, consistency proofs, and mathematical operations
+- **massifs**: Efficient buffer-based access to massif blob data
+
+## Installation
+
+```bash
+pnpm add @forestrie/merklelog
+```
+
+## Usage
+
+### Uint64
+
+```typescript
+import { Uint64 } from "@forestrie/merklelog";
+
+const a = new Uint64(42);
+const b = new Uint64(10);
+const sum = a.add(b);
+console.log(sum.toBigInt()); // 52n
+```
+
+### Massif
+
+```typescript
+import { Massif } from "@forestrie/merklelog";
+
+const buffer = new Uint8Array(/* massif blob data */);
+const massif = new Massif(buffer);
+
+// Read fields dynamically
+const lastID = massif.lastID;
+const massifIndex = massif.massifIndex;
+
+// Get complete start information
+const start = massif.getStart();
+
+// Access field by index
+const field = massif.fieldref(0); // Returns 32-byte field at index 0
+```
+
+### MMR Algorithms
+
+```typescript
+import { bagPeaks, verifyInclusion, Hasher } from "@forestrie/merklelog";
+
+// Bag peaks to compute root (hasher.digest() is async)
+const root = await bagPeaks(hasher, peakHashes);
+
+// Verify inclusion proof
+const isValid = await verifyInclusion(hasher, leafHash, proof, root);
+```
+
+## Terminology
+
+This package follows the terminology defined in the [term cheatsheet](https://raw.githubusercontent.com/forestrie/go-merklelog/refs/heads/main/term-cheatsheet.md):
+
+- **mmrIndex**: Zero-based index of a node in the MMR
+- **mmrPosition**: One-based position of a node (mmrIndex + 1)
+- **leafIndex**: Zero-based index of a leaf node
+- **heightIndex (g)**: Zero-based height index
+- **height (h)**: One-based height (g + 1)
+
+## References
+
+- [go-merklelog](https://github.com/forestrie/go-merklelog) - Original Go implementation
+- [Term Cheatsheet](https://raw.githubusercontent.com/forestrie/go-merklelog/refs/heads/main/term-cheatsheet.md)
+- [MMR Math Cheatsheet](https://raw.githubusercontent.com/forestrie/go-merklelog/refs/heads/main/mmr-math-cheatsheet.md)
+
+## License
+
+See LICENSE file in the repository.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @forestrie/merklelog - TypeScript implementation of MMR Merklelog format
+ *
+ * This package provides TypeScript implementations of the MMR (Merkle Mountain Range)
+ * merklelog format as defined by the go-merklelog project.
+ *
+ * @packageDocumentation
+ */
+export { Uint64 } from "./uint64/index.js";
+export { Massif } from "./massifs/massif.js";
+export type { MassifStart, LeafComponent, LeafEnumeratorSpec, LeafEntry, } from "./massifs/types.js";
+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 { parseV2StorageObjectPath } from "./massifs/v2storagepaths.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 { createSyncHasher } from "./mmr/algorithms-sync.js";
+export type { Proof, Peak } from "./mmr/types.js";
+export type { Hasher } from "./mmr/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,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"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @forestrie/merklelog - TypeScript implementation of MMR Merklelog format
+ *
+ * This package provides TypeScript implementations of the MMR (Merkle Mountain Range)
+ * merklelog format as defined by the go-merklelog project.
+ *
+ * @packageDocumentation
+ */
+// Export uint64 module
+export { Uint64 } from "./uint64/index.js";
+// Export massifs module
+export { Massif } from "./massifs/massif.js";
+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 { parseV2StorageObjectPath } from "./massifs/v2storagepaths.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 { createSyncHasher } from "./mmr/algorithms-sync.js";

package/dist/massifs/indexformat.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Index format constants for v2 massif format
+ *
+ * Constants for the urkle trie and bloom filter index regions.
+ * Based on the Go implementations in:
+ * - go-merklelog/urkle/types.go
+ * - go-merklelog/bloom/types.go
+ * - go-merklelog/massifs/indexformat_v2.go
+ */
+/**
+ * Urkle - Constants for urkle trie format
+ */
+export declare namespace Urkle {
+    /** Fixed width of hashes and values (32 bytes) */
+    const HashBytes = 32;
+    /** Byte width of leafOrdinal in proofs and leaf hashes */
+    const LeafOrdinalBytes = 4;
+    /**
+     * LeafRecordBytes is the fixed byte width of a leaf table record.
+     *
+     * v1 layout (extended for Forestrie v2 index needs):
+     *   - key_be8 (uint64, 8 bytes)
+     *   - valueBytes[32] (committed by trie hash)
+     *   - extra1[24] (auxiliary; not committed by the trie hash)
+     *   - extra2[32] (auxiliary; not committed by the trie hash)
+     *   - extra3[32] (auxiliary; not committed by the trie hash)
+     *
+     * NOTE: Record size is intentionally a multiple of 32 bytes. To achieve this
+     * without truncating valueBytes, we sacrifice 8 bytes from the first extra
+     * field.
+     */
+    const LeafRecordBytes = 128;
+    /** Fixed byte width of a node store record */
+    const NodeRecordBytes = 64;
+    /** Size of FrontierStateV1 snapshot for resuming append-only construction */
+    const FrontierStateV1Bytes = 544;
+    const LeafKeyBytes = 8;
+    const LeafValueBytes = 32;
+    const LeafExtra1Bytes: number;
+    const LeafExtraBytes = 32;
+    const LeafValueOffset = 8;
+    const LeafExtraOffset: number;
+    const LeafExtra1Offset: number;
+    const LeafExtra2Offset: number;
+    const LeafExtra3Offset: number;
+}
+/**
+ * Bloom - Constants for bloom filter format
+ */
+export declare namespace Bloom {
+    /** Fixed element width (Forestrie log value width) */
+    const ValueBytes = 32;
+    /** Number of parallel Bloom filters in this format */
+    const Filters = 4;
+    /** Fixed header size for BloomHeaderV1 */
+    const HeaderBytesV1 = 32;
+    /** Magic string for BloomHeaderV1 */
+    const MagicV1 = "BLM1";
+    /** Version number for v1 */
+    const VersionV1 = 1;
+    /** BitOrderLSB0: bit 0 is the least-significant bit of byte 0 */
+    const BitOrderLSB0 = 0;
+}
+/**
+ * IndexV2 - V2 massif index configuration constants
+ */
+export declare namespace IndexV2 {
+    /**
+     * BloomBitsPerElement is the fixed sizing knob for the v2 massif BloomRegion.
+     * mBits = bitsPerElement * leafCount, per filter.
+     */
+    const BloomBitsPerElement = 10;
+    /**
+     * BloomK is the number of hash-derived bit positions set per inserted element.
+     * For b=10, k≈round(0.693*b)=7.
+     */
+    const BloomK = 7;
+}
+/**
+ * Returns the fixed leaf capacity N for a massif height (one-based).
+ *
+ * In massifs, massifHeight is the one-based height h, so leaf capacity is:
+ *   N = 2^(h-1)
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Leaf capacity for the massif
+ */
+export declare function leafCountForMassifHeight(massifHeight: number): bigint;
+/**
+ * Returns the required leaf table bytes for leafCount leaves.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of the leaf table
+ */
+export declare function leafTableBytes(leafCount: bigint): bigint;
+/**
+ * Returns the maximum number of nodes in a binary trie with leafCount keys.
+ * For a Patricia/crit-bit style binary trie, node count is <= 2N-1.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Maximum node count
+ */
+export declare function nodeCountMax(leafCount: bigint): bigint;
+/**
+ * Returns the required node store bytes for leafCount leaves.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of the node store
+ */
+export declare function nodeStoreBytes(leafCount: bigint): bigint;
+/**
+ * Computes mBits = bitsPerElement * leafCount, returning 0 if overflow.
+ *
+ * @param leafCount - Number of leaves
+ * @param bitsPerElement - Bits per element (default: IndexV2.BloomBitsPerElement)
+ * @returns mBits value, or 0 if overflow
+ */
+export declare function bloomMBits(leafCount: bigint, bitsPerElement?: bigint): bigint;
+/**
+ * Returns ceil(mBits/8) - the number of bytes for a single filter bitset.
+ *
+ * @param mBits - Number of bits
+ * @returns Byte size of one filter bitset
+ */
+export declare function bloomBitsetBytes(mBits: bigint): bigint;
+/**
+ * Returns the required byte length for a 4-way BloomRegion given mBits:
+ *   HeaderBytesV1 + 4 * ceil(mBits/8)
+ *
+ * @param mBits - Number of bits per filter
+ * @returns Total byte size of bloom region (header + 4 bitsets)
+ */
+export declare function bloomRegionBytes(mBits: bigint): bigint;
+/**
+ * Returns the byte size of the v2 index data region, excluding the fixed 32B
+ * index header.
+ *
+ * v2 index header (32B) is BloomHeaderV1, and the index data is:
+ *   bloom bitsets || urkle frontier || urkle leaf table || urkle node store
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of index data region
+ * @throws Error if mBits overflows
+ */
+export declare function indexDataBytesV2(leafCount: bigint): bigint;
+//# sourceMappingURL=indexformat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexformat.d.ts","sourceRoot":"","sources":["../../src/massifs/indexformat.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,yBAAiB,KAAK,CAAC;IACrB,kDAAkD;IAC3C,MAAM,SAAS,KAAK,CAAC;IAE5B,0DAA0D;IACnD,MAAM,gBAAgB,IAAI,CAAC;IAElC;;;;;;;;;;;;;OAaG;IACI,MAAM,eAAe,MAAM,CAAC;IAEnC,8CAA8C;IACvC,MAAM,eAAe,KAAK,CAAC;IAElC,6EAA6E;IACtE,MAAM,oBAAoB,MAAM,CAAC;IAGjC,MAAM,YAAY,IAAI,CAAC;IACvB,MAAM,cAAc,KAAY,CAAC;IACjC,MAAM,eAAe,QAAgB,CAAC;IACtC,MAAM,cAAc,KAAY,CAAC;IAEjC,MAAM,eAAe,IAAe,CAAC;IACrC,MAAM,eAAe,QAAmC,CAAC;IACzD,MAAM,gBAAgB,QAAkB,CAAC;IACzC,MAAM,gBAAgB,QAAqC,CAAC;IAC5D,MAAM,gBAAgB,QAAoC,CAAC;CACnE;AAED;;GAEG;AACH,yBAAiB,KAAK,CAAC;IACrB,sDAAsD;IAC/C,MAAM,UAAU,KAAK,CAAC;IAE7B,sDAAsD;IAC/C,MAAM,OAAO,IAAI,CAAC;IAEzB,0CAA0C;IACnC,MAAM,aAAa,KAAK,CAAC;IAEhC,qCAAqC;IAC9B,MAAM,OAAO,SAAS,CAAC;IAE9B,4BAA4B;IACrB,MAAM,SAAS,IAAI,CAAC;IAE3B,iEAAiE;IAC1D,MAAM,YAAY,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,yBAAiB,OAAO,CAAC;IACvB;;;OAGG;IACI,MAAM,mBAAmB,KAAK,CAAC;IAEtC;;;OAGG;IACI,MAAM,MAAM,IAAI,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAA4C,GAC3D,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAmB1D"}

package/dist/massifs/indexformat.js

@@ -0,0 +1,191 @@
+/**
+ * Index format constants for v2 massif format
+ *
+ * Constants for the urkle trie and bloom filter index regions.
+ * Based on the Go implementations in:
+ * - go-merklelog/urkle/types.go
+ * - go-merklelog/bloom/types.go
+ * - go-merklelog/massifs/indexformat_v2.go
+ */
+/**
+ * Urkle - Constants for urkle trie format
+ */
+export var Urkle;
+(function (Urkle) {
+    /** Fixed width of hashes and values (32 bytes) */
+    Urkle.HashBytes = 32;
+    /** Byte width of leafOrdinal in proofs and leaf hashes */
+    Urkle.LeafOrdinalBytes = 4;
+    /**
+     * LeafRecordBytes is the fixed byte width of a leaf table record.
+     *
+     * v1 layout (extended for Forestrie v2 index needs):
+     *   - key_be8 (uint64, 8 bytes)
+     *   - valueBytes[32] (committed by trie hash)
+     *   - extra1[24] (auxiliary; not committed by the trie hash)
+     *   - extra2[32] (auxiliary; not committed by the trie hash)
+     *   - extra3[32] (auxiliary; not committed by the trie hash)
+     *
+     * NOTE: Record size is intentionally a multiple of 32 bytes. To achieve this
+     * without truncating valueBytes, we sacrifice 8 bytes from the first extra
+     * field.
+     */
+    Urkle.LeafRecordBytes = 128; // 8 + 32 + 24 + 32 + 32
+    /** Fixed byte width of a node store record */
+    Urkle.NodeRecordBytes = 64;
+    /** Size of FrontierStateV1 snapshot for resuming append-only construction */
+    Urkle.FrontierStateV1Bytes = 544; // 32 + 64*8
+    // Leaf record field offsets
+    Urkle.LeafKeyBytes = 8;
+    Urkle.LeafValueBytes = Urkle.HashBytes;
+    Urkle.LeafExtra1Bytes = Urkle.HashBytes - 8; // 24
+    Urkle.LeafExtraBytes = Urkle.HashBytes; // 32
+    Urkle.LeafValueOffset = Urkle.LeafKeyBytes; // 8
+    Urkle.LeafExtraOffset = Urkle.LeafValueOffset + Urkle.LeafValueBytes; // 40
+    Urkle.LeafExtra1Offset = Urkle.LeafExtraOffset; // 40
+    Urkle.LeafExtra2Offset = Urkle.LeafExtra1Offset + Urkle.LeafExtra1Bytes; // 64
+    Urkle.LeafExtra3Offset = Urkle.LeafExtra2Offset + Urkle.LeafExtraBytes; // 96
+})(Urkle || (Urkle = {}));
+/**
+ * Bloom - Constants for bloom filter format
+ */
+export var Bloom;
+(function (Bloom) {
+    /** Fixed element width (Forestrie log value width) */
+    Bloom.ValueBytes = 32;
+    /** Number of parallel Bloom filters in this format */
+    Bloom.Filters = 4;
+    /** Fixed header size for BloomHeaderV1 */
+    Bloom.HeaderBytesV1 = 32;
+    /** Magic string for BloomHeaderV1 */
+    Bloom.MagicV1 = "BLM1";
+    /** Version number for v1 */
+    Bloom.VersionV1 = 1;
+    /** BitOrderLSB0: bit 0 is the least-significant bit of byte 0 */
+    Bloom.BitOrderLSB0 = 0;
+})(Bloom || (Bloom = {}));
+/**
+ * IndexV2 - V2 massif index configuration constants
+ */
+export var IndexV2;
+(function (IndexV2) {
+    /**
+     * BloomBitsPerElement is the fixed sizing knob for the v2 massif BloomRegion.
+     * mBits = bitsPerElement * leafCount, per filter.
+     */
+    IndexV2.BloomBitsPerElement = 10;
+    /**
+     * BloomK is the number of hash-derived bit positions set per inserted element.
+     * For b=10, k≈round(0.693*b)=7.
+     */
+    IndexV2.BloomK = 7;
+})(IndexV2 || (IndexV2 = {}));
+/**
+ * Returns the fixed leaf capacity N for a massif height (one-based).
+ *
+ * In massifs, massifHeight is the one-based height h, so leaf capacity is:
+ *   N = 2^(h-1)
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Leaf capacity for the massif
+ */
+export function leafCountForMassifHeight(massifHeight) {
+    if (massifHeight === 0) {
+        return 0n;
+    }
+    return 1n << BigInt(massifHeight - 1);
+}
+/**
+ * Returns the required leaf table bytes for leafCount leaves.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of the leaf table
+ */
+export function leafTableBytes(leafCount) {
+    return leafCount * BigInt(Urkle.LeafRecordBytes);
+}
+/**
+ * Returns the maximum number of nodes in a binary trie with leafCount keys.
+ * For a Patricia/crit-bit style binary trie, node count is <= 2N-1.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Maximum node count
+ */
+export function nodeCountMax(leafCount) {
+    if (leafCount === 0n) {
+        return 0n;
+    }
+    return 2n * leafCount - 1n;
+}
+/**
+ * Returns the required node store bytes for leafCount leaves.
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of the node store
+ */
+export function nodeStoreBytes(leafCount) {
+    return nodeCountMax(leafCount) * BigInt(Urkle.NodeRecordBytes);
+}
+/**
+ * Computes mBits = bitsPerElement * leafCount, returning 0 if overflow.
+ *
+ * @param leafCount - Number of leaves
+ * @param bitsPerElement - Bits per element (default: IndexV2.BloomBitsPerElement)
+ * @returns mBits value, or 0 if overflow
+ */
+export function bloomMBits(leafCount, bitsPerElement = BigInt(IndexV2.BloomBitsPerElement)) {
+    const mBits = bitsPerElement * leafCount;
+    // Check overflow - mBits should fit in uint32
+    if (mBits > 0xffffffffn) {
+        return 0n;
+    }
+    return mBits;
+}
+/**
+ * Returns ceil(mBits/8) - the number of bytes for a single filter bitset.
+ *
+ * @param mBits - Number of bits
+ * @returns Byte size of one filter bitset
+ */
+export function bloomBitsetBytes(mBits) {
+    return (mBits + 7n) / 8n;
+}
+/**
+ * Returns the required byte length for a 4-way BloomRegion given mBits:
+ *   HeaderBytesV1 + 4 * ceil(mBits/8)
+ *
+ * @param mBits - Number of bits per filter
+ * @returns Total byte size of bloom region (header + 4 bitsets)
+ */
+export function bloomRegionBytes(mBits) {
+    const bitsetBytes = bloomBitsetBytes(mBits);
+    return BigInt(Bloom.HeaderBytesV1) + BigInt(Bloom.Filters) * bitsetBytes;
+}
+/**
+ * Returns the byte size of the v2 index data region, excluding the fixed 32B
+ * index header.
+ *
+ * v2 index header (32B) is BloomHeaderV1, and the index data is:
+ *   bloom bitsets || urkle frontier || urkle leaf table || urkle node store
+ *
+ * @param leafCount - Number of leaves
+ * @returns Byte size of index data region
+ * @throws Error if mBits overflows
+ */
+export function indexDataBytesV2(leafCount) {
+    const mBits = bloomMBits(leafCount);
+    if (mBits === 0n && leafCount > 0n) {
+        throw new Error("bloom mBits overflow");
+    }
+    if (leafCount === 0n) {
+        return 0n;
+    }
+    // Bloom region bytes includes the 32B header; we exclude that here because
+    // the massif index header is a fixed 32B already accounted for.
+    const bloomRegion = bloomRegionBytes(mBits);
+    const bloomBitsetsOnly = bloomRegion - BigInt(Bloom.HeaderBytesV1);
+    const frontierBytes = BigInt(Urkle.FrontierStateV1Bytes);
+    const ltBytes = leafTableBytes(leafCount);
+    const nsBytes = nodeStoreBytes(leafCount);
+    return bloomBitsetsOnly + frontierBytes + ltBytes + nsBytes;
+}

package/dist/massifs/logformat.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Massif log format constants
+ *
+ * Constants for calculating offsets and sizes in the massif blob format.
+ * Based on the Go implementation in go-merklelog/massifs/logformat.go
+ *
+ * Reference: https://github.com/datatrails/epic-8120-scalable-proof-mechanisms/blob/main/mmr/forestrie-mmrblobs.md#massif-basic-file-format
+ */
+/**
+ * LogFormat - Constants for massif data format
+ *
+ * Matching the Go implementation in go-merklelog/massifs/logformat.go
+ */
+export declare namespace LogFormat {
+    /**
+     * ValueBytes defines the width of ALL entries in the log. This fixed width
+     * makes it possible to compute mmr current sizes based on knowing only the
+     * massif height and the number of bytes in the file.
+     */
+    const ValueBytes = 32;
+    /**
+     * ReservedHeaderSlots reserves a place to put the urkle trie root, used for
+     * data recovery and proofs of exclusion, and any related material. And it
+     * gives us a little flex in the data format for the initial launch of
+     * forestrie. It would be frustrating to need a data migration for want of a
+     * few bytes.
+     */
+    const ReservedHeaderSlots = 7;
+    /**
+     * StartHeaderSize - Size of the start header including reserved slots
+     */
+    const StartHeaderSize: number;
+    /**
+     * StartHeaderEnd - End offset of the start header
+     */
+    const StartHeaderEnd: number;
+    /**
+     * MaxMmrHeight - Maximum MMR height - no single log can be taller than this
+     * Matches the allowable bit size of an mmrIndex.
+     * Note that the max height *index* is 63
+     */
+    const MaxMmrHeight = 64;
+    /**
+     * IndexHeaderBytes - Index header bytes - reserved space for index header.
+     * In v2, this 32B region is the BloomHeaderV1.
+     */
+    const IndexHeaderBytes = 32;
+}
+//# sourceMappingURL=logformat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logformat.d.ts","sourceRoot":"","sources":["../../src/massifs/logformat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,yBAAiB,SAAS,CAAC;IACzB;;;;OAIG;IACI,MAAM,UAAU,KAAK,CAAC;IAE7B;;;;;;OAMG;IACI,MAAM,mBAAmB,IAAI,CAAC;IAErC;;OAEG;IACI,MAAM,eAAe,QAAgD,CAAC;IAE7E;;OAEG;IACI,MAAM,cAAc,QAAkB,CAAC;IAE9C;;;;OAIG;IACI,MAAM,YAAY,KAAK,CAAC;IAE/B;;;OAGG;IACI,MAAM,gBAAgB,KAAK,CAAC;CACpC"}

package/dist/massifs/logformat.js

@@ -0,0 +1,49 @@
+/**
+ * Massif log format constants
+ *
+ * Constants for calculating offsets and sizes in the massif blob format.
+ * Based on the Go implementation in go-merklelog/massifs/logformat.go
+ *
+ * Reference: https://github.com/datatrails/epic-8120-scalable-proof-mechanisms/blob/main/mmr/forestrie-mmrblobs.md#massif-basic-file-format
+ */
+/**
+ * LogFormat - Constants for massif data format
+ *
+ * Matching the Go implementation in go-merklelog/massifs/logformat.go
+ */
+export var LogFormat;
+(function (LogFormat) {
+    /**
+     * ValueBytes defines the width of ALL entries in the log. This fixed width
+     * makes it possible to compute mmr current sizes based on knowing only the
+     * massif height and the number of bytes in the file.
+     */
+    LogFormat.ValueBytes = 32;
+    /**
+     * ReservedHeaderSlots reserves a place to put the urkle trie root, used for
+     * data recovery and proofs of exclusion, and any related material. And it
+     * gives us a little flex in the data format for the initial launch of
+     * forestrie. It would be frustrating to need a data migration for want of a
+     * few bytes.
+     */
+    LogFormat.ReservedHeaderSlots = 7; // reserves n * ValueBytes at the front of the blob
+    /**
+     * StartHeaderSize - Size of the start header including reserved slots
+     */
+    LogFormat.StartHeaderSize = LogFormat.ValueBytes + LogFormat.ValueBytes * LogFormat.ReservedHeaderSlots; // 256
+    /**
+     * StartHeaderEnd - End offset of the start header
+     */
+    LogFormat.StartHeaderEnd = LogFormat.StartHeaderSize;
+    /**
+     * MaxMmrHeight - Maximum MMR height - no single log can be taller than this
+     * Matches the allowable bit size of an mmrIndex.
+     * Note that the max height *index* is 63
+     */
+    LogFormat.MaxMmrHeight = 64;
+    /**
+     * IndexHeaderBytes - Index header bytes - reserved space for index header.
+     * In v2, this 32B region is the BloomHeaderV1.
+     */
+    LogFormat.IndexHeaderBytes = 32;
+})(LogFormat || (LogFormat = {}));