@forestrie/merklelog 0.0.1

package/dist/mmr/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function leafMinusSpurSum(leafIndex: bigint): bigint;
+/**
+ * Returns the MMR index of the first leaf in the massif blob identified by massifIndex
+ *
+ * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
+ */
+export declare function massifFirstLeaf(massifHeight: number, massifIndex: number): bigint;
+/**
+ * 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 declare function mmrIndex(leafIndex: bigint): bigint;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/mmr/index.js

@@ -0,0 +1,64 @@
+/**
+ * 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) {
+    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, massifIndex) {
+    // 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) {
+    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/dist/mmr/math.d.ts

@@ -0,0 +1,67 @@
+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 declare function heightIndex(mmrIndex: Uint64): number;
+/**
+ * Returns the one-based height (h) of an MMR index
+ *
+ * h = g + 1 where g is the height index
+ */
+export declare function height(mmrIndex: Uint64): number;
+/**
+ * Converts leaf index to MMR index
+ *
+ * @param leafIndex - Zero-based leaf index
+ * @returns MMR index
+ */
+export declare function mmrIndexFromLeafIndex(leafIndex: Uint64): Uint64;
+/**
+ * Converts MMR index to leaf index
+ *
+ * @param mmrIndex - MMR index
+ * @returns Leaf index
+ */
+export declare function leafIndex(mmrIndex: Uint64): Uint64;
+/**
+ * Converts MMR index to MMR position (index + 1)
+ *
+ * @param mmrIndex - Zero-based MMR index
+ * @returns One-based MMR position
+ */
+export declare function mmrPosition(mmrIndex: Uint64): Uint64;
+/**
+ * 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 declare function mmrSizeFromHeightIndex(heightIndex: number): Uint64;
+/**
+ * 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 declare function leafCount(mmrSize: Uint64): Uint64;
+/**
+ * Returns the number of leaves given a height index
+ *
+ * f = 2^g = 1 << g
+ */
+export declare function leafCountFromHeightIndex(heightIndex: number): Uint64;
+//# sourceMappingURL=math.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/mmr/math.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/C;AAgDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAI/D;AAiBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAclD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAwBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/mmr/math.js

@@ -0,0 +1,172 @@
+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) {
+    // 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) {
+    return heightIndex(mmrIndex) + 1;
+}
+/**
+ * PosHeight - obtains height from a 1-based position
+ *
+ * Translated from go-merklelog/mmr/indexheight.go PosHeight
+ */
+function posHeight(pos) {
+    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) {
+    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) {
+    // 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) {
+    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) {
+    // 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) {
+    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) {
+    // 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return new Uint64(1).shl(heightIndex);
+}

package/dist/mmr/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mmr/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,sCAAsC;IACtC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,6BAA6B;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,kCAAkC;IAClC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,mCAAmC;IACnC,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/B"}

package/dist/mmr/types.js

@@ -0,0 +1,4 @@
+/**
+ * Proof types for MMR inclusion and consistency proofs
+ */
+export {};

package/dist/uint64/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 declare class Uint64 {
+    private readonly value;
+    /**
+     * Creates a new Uint64 instance
+     * @param value - The initial value as number, bigint, or string
+     */
+    constructor(value: number | bigint | string | Uint64);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Left shift
+     * @param bits - Number of bits to shift left
+     * @returns New Uint64 instance with the result
+     */
+    shl(bits: number): Uint64;
+    /**
+     * Right shift (logical, zero-fill)
+     * @param bits - Number of bits to shift right
+     * @returns New Uint64 instance with the result
+     */
+    shr(bits: number): Uint64;
+    /**
+     * Bitwise AND
+     * @param other - The value to AND with
+     * @returns New Uint64 instance with the result
+     */
+    and(other: Uint64): Uint64;
+    /**
+     * Bitwise OR
+     * @param other - The value to OR with
+     * @returns New Uint64 instance with the result
+     */
+    or(other: Uint64): Uint64;
+    /**
+     * Bitwise XOR
+     * @param other - The value to XOR with
+     * @returns New Uint64 instance with the result
+     */
+    xor(other: Uint64): Uint64;
+    /**
+     * Bitwise complement (one's complement)
+     * @returns New Uint64 instance with the result
+     */
+    not(): Uint64;
+    /**
+     * 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;
+    /**
+     * Returns the value as a BigInt
+     * @returns The 64-bit unsigned value as BigInt
+     */
+    toBigInt(): bigint;
+    /**
+     * 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;
+    /**
+     * Returns the value as a string
+     * @returns String representation of the value
+     */
+    toString(): string;
+    /**
+     * Equality comparison
+     * @param other - The value to compare with
+     * @returns True if values are equal
+     */
+    equals(other: Uint64): boolean;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/uint64/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;gBACS,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM;IASpD;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK1B;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK1B;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQzB;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQzB;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK1B;;;;OAIG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAKzB;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK1B;;;OAGG;IACH,GAAG,IAAI,MAAM;IAMb;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAY1B;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IASlB;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAG/B"}

package/dist/uint64/index.js

@@ -0,0 +1,149 @@
+/**
+ * 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 {
+    value;
+    /**
+     * Creates a new Uint64 instance
+     * @param value - The initial value as number, bigint, or string
+     */
+    constructor(value) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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() {
+        // 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) {
+        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() {
+        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() {
+        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() {
+        return this.value.toString();
+    }
+    /**
+     * Equality comparison
+     * @param other - The value to compare with
+     * @returns True if values are equal
+     */
+    equals(other) {
+        return this.value === other.value;
+    }
+}

package/dist/utils/arrays.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function arraysEqual(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=arrays.d.ts.map

package/dist/utils/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../src/utils/arrays.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAUjE"}

package/dist/utils/arrays.js

@@ -0,0 +1,24 @@
+/**
+ * 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, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}