@forestrie/merklelog 0.0.1

package/src/mmr/index.ts

@@ -0,0 +1,75 @@
+/**
+ * MMR index calculation functions
+ *
+ * These functions are needed by the massifs module for computing
+ * firstIndex and peakStackLen.
+ *
+ * Also exports the core mmrIndex function for converting leaf indices to MMR indices.
+ */
+
+/**
+ * Returns the number of peaks preceding iLeaf that the future tree requires.
+ *
+ * This corresponds to the number of preceding nodes that will be required to
+ * derive future interior nodes. If those preceding nodes are maintained in a
+ * stack, this is the current length of the stack.
+ *
+ * Translated from go-merklelog/mmr/spurs.go LeafMinusSpurSum
+ */
+export function leafMinusSpurSum(leafIndex: bigint): bigint {
+  let sum = leafIndex;
+  let current = leafIndex >> 1n;
+  while (current > 0n) {
+    sum -= current;
+    current >>= 1n;
+  }
+  return sum;
+}
+
+/**
+ * Returns the MMR index of the first leaf in the massif blob identified by massifIndex
+ *
+ * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
+ */
+export function massifFirstLeaf(
+  massifHeight: number,
+  massifIndex: number,
+): bigint {
+  // The number of nodes 'm' in a massif is: m = (1 << h) - 1
+  const m = BigInt((1 << massifHeight) - 1);
+
+  // 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
+  const leafIndex = f * BigInt(massifIndex);
+
+  // Apply MMRIndex to the leaf index to get the MMR index
+  return mmrIndex(leafIndex);
+}
+
+/**
+ * Returns the node index for the leaf e
+ *
+ * Args:
+ *   - leafIndex: the leaf index, where the leaves are numbered consecutively, ignoring interior nodes.
+ *
+ * Returns:
+ *   The mmr index for the element leafIndex
+ *
+ * Translated from go-merklelog/mmr/mmrindex.go MMRIndex
+ */
+export function mmrIndex(leafIndex: bigint): bigint {
+  let sum = 0n;
+  let current = leafIndex;
+
+  while (current > 0n) {
+    // Find the position of the most significant bit (height)
+    const h = BigInt(current.toString(2).length);
+    sum += (1n << h) - 1n;
+    const half = 1n << (h - 1n);
+    current -= half;
+  }
+
+  return sum;
+}

package/src/mmr/math.ts

@@ -0,0 +1,190 @@
+import { Uint64 } from "../uint64/index.js";
+
+/**
+ * MMR Math Functions
+ *
+ * Core mathematical functions for Merkle Mountain Range operations.
+ * Uses Uint64 wrapper for all arithmetic to ensure correctness.
+ */
+
+/**
+ * Returns the zero-based height index (g) of an MMR index
+ *
+ * The height index of a leaf is 0.
+ * Translated from go-merklelog/mmr/indexheight.go IndexHeight
+ */
+export function heightIndex(mmrIndex: Uint64): number {
+  // Convert from zero-based index to 1-based position
+  const pos = mmrIndex.add(new Uint64(1));
+  return posHeight(pos);
+}
+
+/**
+ * Returns the one-based height (h) of an MMR index
+ *
+ * h = g + 1 where g is the height index
+ */
+export function height(mmrIndex: Uint64): number {
+  return heightIndex(mmrIndex) + 1;
+}
+
+/**
+ * PosHeight - obtains height from a 1-based position
+ *
+ * Translated from go-merklelog/mmr/indexheight.go PosHeight
+ */
+function posHeight(pos: Uint64): number {
+  let current = pos;
+  while (!allOnes(current)) {
+    current = jumpLeftPerfect(current);
+  }
+  return bitLength(current) - 1;
+}
+
+/**
+ * JumpLeftPerfect - jumps left to the leftmost node at the same height
+ *
+ * Translated from go-merklelog/mmr/indexheight.go JumpLeftPerfect
+ */
+function jumpLeftPerfect(pos: Uint64): Uint64 {
+  const bitLen = bitLength(pos);
+  const mostSignificantBit = new Uint64(1).shl(bitLen - 1);
+  return pos.sub(mostSignificantBit.sub(new Uint64(1)));
+}
+
+/**
+ * Checks if a value has all bits set (all ones in binary)
+ */
+function allOnes(value: Uint64): boolean {
+  // A value has all ones if value + 1 is a power of 2
+  const next = value.add(new Uint64(1));
+  const bitLen = bitLength(next);
+  const powerOf2 = new Uint64(1).shl(bitLen - 1);
+  return next.equals(powerOf2);
+}
+
+/**
+ * Returns the number of bits needed to represent the value
+ */
+function bitLength(value: Uint64): number {
+  const bigInt = value.toBigInt();
+  if (bigInt === 0n) {
+    return 0;
+  }
+  return bigInt.toString(2).length;
+}
+
+/**
+ * Converts leaf index to MMR index
+ *
+ * @param leafIndex - Zero-based leaf index
+ * @returns MMR index
+ */
+export function mmrIndexFromLeafIndex(leafIndex: Uint64): Uint64 {
+  // Use the mmrIndex function from index.ts
+  // Import it dynamically to avoid circular dependency
+  return new Uint64(mmrIndexFromLeafIndexInternal(leafIndex.toBigInt()));
+}
+
+// Internal helper that matches the implementation in index.ts
+function mmrIndexFromLeafIndexInternal(leafIndex: bigint): bigint {
+  let sum = 0n;
+  let current = leafIndex;
+
+  while (current > 0n) {
+    const h = BigInt(current.toString(2).length);
+    sum += (1n << h) - 1n;
+    const half = 1n << (h - 1n);
+    current -= half;
+  }
+
+  return sum;
+}
+
+/**
+ * Converts MMR index to leaf index
+ *
+ * @param mmrIndex - MMR index
+ * @returns Leaf index
+ */
+export function leafIndex(mmrIndex: Uint64): Uint64 {
+  // This needs to be implemented based on the MMR structure
+  // For now, we'll use an iterative approach
+  let current = mmrIndex;
+  let leafCount = new Uint64(0);
+
+  while (current.toBigInt() > 0n) {
+    const h = heightIndex(current);
+    const peakSize = new Uint64(1).shl(h + 1).sub(new Uint64(1)); // (1 << (h+1)) - 1
+    leafCount = leafCount.add(new Uint64(1).shl(h)); // Add 2^h leaves
+    current = current.sub(peakSize);
+  }
+
+  return leafCount.sub(new Uint64(1)); // Convert to zero-based
+}
+
+/**
+ * Converts MMR index to MMR position (index + 1)
+ *
+ * @param mmrIndex - Zero-based MMR index
+ * @returns One-based MMR position
+ */
+export function mmrPosition(mmrIndex: Uint64): Uint64 {
+  return mmrIndex.add(new Uint64(1));
+}
+
+/**
+ * Returns the number of nodes given a height index (g)
+ *
+ * n = 2^(g+1) - 1 = (2 << g) - 1
+ * Translated from go-merklelog/mmr/size.go HeightIndexSize
+ */
+export function mmrSizeFromHeightIndex(heightIndex: number): Uint64 {
+  return new Uint64(1).shl(heightIndex + 1).sub(new Uint64(1));
+}
+
+/**
+ * Returns the number of leaves in the largest valid MMR whose size is
+ * <= `mmrSize`.
+ *
+ * Mirrors go-merklelog `LeafCount`, which is defined as `PeaksBitmap(mmrSize)`:
+ * the leaf count's binary representation maps directly onto the peak structure
+ * (each set bit is a perfect subtree). The naive `(n + 1) / 2` is only correct
+ * for single-peak (perfect) sizes — e.g. size 4 (3 leaves) gives 2 with the
+ * naive form but 3 here — so it must not be used. When `mmrSize` is not a valid
+ * MMR size this returns the leaf count of the highest valid size <= `mmrSize`.
+ */
+export function leafCount(mmrSize: Uint64): Uint64 {
+  return new Uint64(peaksBitmap(mmrSize.toBigInt()));
+}
+
+/**
+ * Returns the peaks bitmap for an MMR size (go-merklelog `PeaksBitmap`).
+ *
+ * The numeric value equals the leaf count of the largest valid MMR with size
+ * <= `mmrSize`; each set bit marks a perfect subtree (peak) at that height.
+ */
+function peaksBitmap(mmrSize: bigint): bigint {
+  if (mmrSize === 0n) return 0n;
+  let pos = mmrSize;
+  let peakSize = (1n << BigInt(bitLength(new Uint64(mmrSize)))) - 1n;
+  let peakMap = 0n;
+  while (peakSize > 0n) {
+    peakMap <<= 1n;
+    if (pos >= peakSize) {
+      pos -= peakSize;
+      peakMap |= 1n;
+    }
+    peakSize >>= 1n;
+  }
+  return peakMap;
+}
+
+/**
+ * Returns the number of leaves given a height index
+ *
+ * f = 2^g = 1 << g
+ */
+export function leafCountFromHeightIndex(heightIndex: number): Uint64 {
+  return new Uint64(1).shl(heightIndex);
+}

package/src/mmr/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Proof types for MMR inclusion and consistency proofs
+ */
+
+/**
+ * Proof - Inclusion or consistency proof structure
+ */
+export interface Proof {
+  /** The proof path (sibling hashes) */
+  path: Uint8Array[];
+  /** The leaf index being proven */
+  leafIndex?: bigint;
+  /** The MMR index being proven */
+  mmrIndex?: bigint;
+}
+
+/**
+ * Peak - A peak node in the MMR
+ */
+export interface Peak {
+  /** The MMR index of the peak */
+  index: bigint;
+  /** The hash value of the peak */
+  hash: Uint8Array;
+}
+
+/**
+ * Hasher interface for cryptographic hashing operations.
+ * digest() is async so callers can use crypto.subtle (Workers, browser) or
+ * wrap Node's crypto.createHash (e.g. digest(): Promise.resolve(syncDigest())).
+ */
+export interface Hasher {
+  /** Reset the hasher state */
+  reset(): void;
+  /** Update the hasher with data */
+  update(data: Uint8Array): void;
+  /** Finalize and return the hash */
+  digest(): Promise<Uint8Array>;
+}

package/src/uint64/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Uint64 - A BigInt-based wrapper for 64-bit unsigned integer operations
+ *
+ * Provides arithmetic and bitwise operations for 64-bit unsigned integers,
+ * ensuring all operations stay within the 64-bit range using BigInt.asUintN(64, value).
+ */
+export class Uint64 {
+  private readonly value: bigint;
+
+  /**
+   * Creates a new Uint64 instance
+   * @param value - The initial value as number, bigint, or string
+   */
+  constructor(value: number | bigint | string | Uint64) {
+    if (value instanceof Uint64) {
+      this.value = value.value;
+    } else {
+      const bigIntValue = typeof value === "bigint" ? value : BigInt(value);
+      this.value = BigInt.asUintN(64, bigIntValue);
+    }
+  }
+
+  /**
+   * Addition with overflow handling (wraps around at 2^64)
+   * @param other - The value to add
+   * @returns New Uint64 instance with the result
+   */
+  add(other: Uint64): Uint64 {
+    const result = this.value + other.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Subtraction with underflow handling (wraps around at 0)
+   * @param other - The value to subtract
+   * @returns New Uint64 instance with the result
+   */
+  sub(other: Uint64): Uint64 {
+    const result = this.value - other.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Left shift
+   * @param bits - Number of bits to shift left
+   * @returns New Uint64 instance with the result
+   */
+  shl(bits: number): Uint64 {
+    if (bits < 0 || bits > 63) {
+      throw new Error("Shift amount must be between 0 and 63");
+    }
+    const result = this.value << BigInt(bits);
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Right shift (logical, zero-fill)
+   * @param bits - Number of bits to shift right
+   * @returns New Uint64 instance with the result
+   */
+  shr(bits: number): Uint64 {
+    if (bits < 0 || bits > 63) {
+      throw new Error("Shift amount must be between 0 and 63");
+    }
+    const result = this.value >> BigInt(bits);
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Bitwise AND
+   * @param other - The value to AND with
+   * @returns New Uint64 instance with the result
+   */
+  and(other: Uint64): Uint64 {
+    const result = this.value & other.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Bitwise OR
+   * @param other - The value to OR with
+   * @returns New Uint64 instance with the result
+   */
+  or(other: Uint64): Uint64 {
+    const result = this.value | other.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Bitwise XOR
+   * @param other - The value to XOR with
+   * @returns New Uint64 instance with the result
+   */
+  xor(other: Uint64): Uint64 {
+    const result = this.value ^ other.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Bitwise complement (one's complement)
+   * @returns New Uint64 instance with the result
+   */
+  not(): Uint64 {
+    // For unsigned 64-bit, complement is ~value masked to 64 bits
+    const result = ~this.value;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Mask lower bits (equivalent to value & ((1 << bits) - 1))
+   * @param bits - Number of lower bits to keep
+   * @returns New Uint64 instance with the result
+   */
+  mask(bits: number): Uint64 {
+    if (bits < 0 || bits > 64) {
+      throw new Error("Mask bits must be between 0 and 64");
+    }
+    if (bits === 64) {
+      return new Uint64(this.value);
+    }
+    const maskValue = (BigInt(1) << BigInt(bits)) - BigInt(1);
+    const result = this.value & maskValue;
+    return new Uint64(BigInt.asUintN(64, result));
+  }
+
+  /**
+   * Returns the value as a BigInt
+   * @returns The 64-bit unsigned value as BigInt
+   */
+  toBigInt(): bigint {
+    return this.value;
+  }
+
+  /**
+   * Returns the value as a number (with range check)
+   * @returns The value as number if it fits in Number.MAX_SAFE_INTEGER
+   * @throws Error if value exceeds Number.MAX_SAFE_INTEGER
+   */
+  toNumber(): number {
+    if (this.value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error(
+        `Value ${this.value} exceeds Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER})`,
+      );
+    }
+    return Number(this.value);
+  }
+
+  /**
+   * Returns the value as a string
+   * @returns String representation of the value
+   */
+  toString(): string {
+    return this.value.toString();
+  }
+
+  /**
+   * Equality comparison
+   * @param other - The value to compare with
+   * @returns True if values are equal
+   */
+  equals(other: Uint64): boolean {
+    return this.value === other.value;
+  }
+}

package/src/utils/arrays.ts

@@ -0,0 +1,25 @@
+/**
+ * Utility functions for Uint8Array operations
+ */
+
+/**
+ * Compares two Uint8Arrays for equality
+ *
+ * Simple and efficient byte-by-byte comparison. Optimized for small
+ * fixed-size arrays like trie keys (32 bytes) and extraBytes (24 bytes).
+ *
+ * @param a - First array to compare
+ * @param b - Second array to compare
+ * @returns true if arrays are equal, false otherwise
+ */
+export function arraysEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}