@forestrie/merklelog 0.0.1

package/dist/massifs/urkleindex.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Urkle index helpers for efficient leaf data access
+ *
+ * Provides helpers for computing field indices and efficiently enumerating
+ * urkle leaf data components.
+ */
+/**
+ * Leaf components that can be read via the enumerator.
+ */
+export type LeafComponent = "idtimestamp" | "valueBytes" | "extra1" | "extra2" | "extra3";
+/**
+ * Returns the field index (for use with Massif.fieldref) of the start of the
+ * urkle leaf table data region.
+ *
+ * The field index is the offset in units of ValueBytes (32 bytes), which can be
+ * passed directly to Massif.fieldref() to get a view of the data.
+ *
+ * V2 layout before leaf table:
+ *   StartHeader (256 bytes = 8 fields)
+ *   IndexHeader (32 bytes = 1 field)
+ *   BloomBitsets (4 * ceil(mBits/8))
+ *   FrontierState (544 bytes)
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Field index (in units of 32-byte fields) where the leaf table starts
+ */
+export declare function urkleLeafTableStartFieldIndex(massifHeight: number): number;
+/**
+ * Returns the byte offset within a massif buffer where the urkle leaf table
+ * starts. This is useful for direct byte-level access.
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Byte offset where the leaf table starts
+ */
+export declare function urkleLeafTableStartByteOffset(massifHeight: number): number;
+/**
+ * LeafEnumeratorSpec specifies which leaf components to enumerate.
+ *
+ * Each component that is true will be read and returned during enumeration.
+ */
+export interface LeafEnumeratorSpec {
+    idtimestamp?: boolean;
+    valueBytes?: boolean;
+    extra1?: boolean;
+    extra2?: boolean;
+    extra3?: boolean;
+}
+/**
+ * LeafEntry represents a single leaf's data components.
+ *
+ * Only the components specified in the enumerator spec will be populated.
+ * Each component provides a DataView for efficient typed access.
+ */
+export interface LeafEntry {
+    /** Leaf ordinal (0-based index) */
+    ordinal: number;
+    /** ID timestamp as bigint (if idtimestamp was requested) */
+    idtimestamp?: bigint;
+    /** Committed value bytes as Uint8Array view (if valueBytes was requested) */
+    valueBytes?: Uint8Array;
+    /** Extra1 field as Uint8Array view (24 bytes, if extra1 was requested) */
+    extra1?: Uint8Array;
+    /** Extra2 field as Uint8Array view (32 bytes, if extra2 was requested) */
+    extra2?: Uint8Array;
+    /** Extra3 field as Uint8Array view (32 bytes, if extra3 was requested) */
+    extra3?: Uint8Array;
+}
+/**
+ * Creates an efficient leaf enumerator for iterating through urkle leaf data.
+ *
+ * The enumerator returns a generator function that yields LeafEntry objects
+ * for each leaf in the massif. Only the components specified in the spec
+ * are read and returned, minimizing overhead.
+ *
+ * The enumerator uses DataView for efficient typed access without copying.
+ *
+ * @param buffer - The massif buffer (Uint8Array)
+ * @param massifHeight - One-based massif height
+ * @param leafCount - Number of leaves to enumerate (from start position)
+ * @param spec - Specification of which components to read
+ * @param start - Starting leaf ordinal (0-based, defaults to 0)
+ * @returns Generator that yields LeafEntry objects
+ *
+ * @example
+ * ```typescript
+ * const enumerate = createLeafEnumerator(
+ *   massif.buffer,
+ *   massifHeight,
+ *   actualLeafCount,
+ *   { idtimestamp: true, valueBytes: true },
+ *   0 // start from first leaf
+ * );
+ *
+ * for (const leaf of enumerate()) {
+ *   console.log(leaf.ordinal, leaf.idtimestamp, leaf.valueBytes);
+ * }
+ * ```
+ */
+export declare function createLeafEnumerator(buffer: Uint8Array, massifHeight: number, leafCount: number, spec: LeafEnumeratorSpec, start?: number): () => Generator<LeafEntry, void, unknown>;
+/**
+ * Returns the byte offset of a specific leaf record's component.
+ *
+ * @param massifHeight - One-based massif height
+ * @param leafOrdinal - Zero-based leaf ordinal
+ * @param component - Which component to locate
+ * @returns Byte offset of the component within the massif buffer
+ */
+export declare function leafComponentByteOffset(massifHeight: number, leafOrdinal: number, component: LeafComponent): number;
+/**
+ * Returns the size in bytes of a leaf component.
+ *
+ * @param component - Which component
+ * @returns Size in bytes
+ */
+export declare function leafComponentSize(component: LeafComponent): number;
+//# sourceMappingURL=urkleindex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"urkleindex.d.ts","sourceRoot":"","sources":["../../src/massifs/urkleindex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAwBb;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAiB1E;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAa1E;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,kBAAkB,EACxB,KAAK,GAAE,MAAU,GAChB,MAAM,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAoE3C;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,aAAa,GACvB,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAElE"}

package/dist/massifs/urkleindex.js

@@ -0,0 +1,169 @@
+/**
+ * Urkle index helpers for efficient leaf data access
+ *
+ * Provides helpers for computing field indices and efficiently enumerating
+ * urkle leaf data components.
+ */
+import { LogFormat } from "./logformat.js";
+import { Urkle, Bloom, leafCountForMassifHeight, bloomMBits, bloomBitsetBytes, } from "./indexformat.js";
+/**
+ * Byte offsets within a leaf record for each component.
+ */
+const LEAF_COMPONENT_OFFSETS = {
+    idtimestamp: 0,
+    valueBytes: Urkle.LeafValueOffset, // 8
+    extra1: Urkle.LeafExtra1Offset, // 40
+    extra2: Urkle.LeafExtra2Offset, // 64
+    extra3: Urkle.LeafExtra3Offset, // 96
+};
+/**
+ * Byte sizes for each leaf component.
+ */
+const LEAF_COMPONENT_SIZES = {
+    idtimestamp: Urkle.LeafKeyBytes, // 8
+    valueBytes: Urkle.LeafValueBytes, // 32
+    extra1: Urkle.LeafExtra1Bytes, // 24
+    extra2: Urkle.LeafExtraBytes, // 32
+    extra3: Urkle.LeafExtraBytes, // 32
+};
+/**
+ * Returns the field index (for use with Massif.fieldref) of the start of the
+ * urkle leaf table data region.
+ *
+ * The field index is the offset in units of ValueBytes (32 bytes), which can be
+ * passed directly to Massif.fieldref() to get a view of the data.
+ *
+ * V2 layout before leaf table:
+ *   StartHeader (256 bytes = 8 fields)
+ *   IndexHeader (32 bytes = 1 field)
+ *   BloomBitsets (4 * ceil(mBits/8))
+ *   FrontierState (544 bytes)
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Field index (in units of 32-byte fields) where the leaf table starts
+ */
+export function urkleLeafTableStartFieldIndex(massifHeight) {
+    const leafCount = leafCountForMassifHeight(massifHeight);
+    const mBits = bloomMBits(leafCount);
+    const bloomBitsetsOnly = BigInt(Bloom.Filters) * bloomBitsetBytes(mBits > 0n ? mBits : 0n);
+    // Byte offset calculation
+    const startHeaderBytes = BigInt(LogFormat.StartHeaderSize); // 256
+    const indexHeaderBytes = BigInt(LogFormat.IndexHeaderBytes); // 32
+    const frontierBytes = BigInt(Urkle.FrontierStateV1Bytes); // 544
+    const byteOffset = startHeaderBytes + indexHeaderBytes + bloomBitsetsOnly + frontierBytes;
+    // Convert to field index (each field is 32 bytes)
+    // Note: this should be an exact division for valid massif heights
+    return Number(byteOffset / BigInt(LogFormat.ValueBytes));
+}
+/**
+ * Returns the byte offset within a massif buffer where the urkle leaf table
+ * starts. This is useful for direct byte-level access.
+ *
+ * @param massifHeight - One-based massif height
+ * @returns Byte offset where the leaf table starts
+ */
+export function urkleLeafTableStartByteOffset(massifHeight) {
+    const leafCount = leafCountForMassifHeight(massifHeight);
+    const mBits = bloomMBits(leafCount);
+    const bloomBitsetsOnly = BigInt(Bloom.Filters) * bloomBitsetBytes(mBits > 0n ? mBits : 0n);
+    const startHeaderBytes = BigInt(LogFormat.StartHeaderSize);
+    const indexHeaderBytes = BigInt(LogFormat.IndexHeaderBytes);
+    const frontierBytes = BigInt(Urkle.FrontierStateV1Bytes);
+    return Number(startHeaderBytes + indexHeaderBytes + bloomBitsetsOnly + frontierBytes);
+}
+/**
+ * Creates an efficient leaf enumerator for iterating through urkle leaf data.
+ *
+ * The enumerator returns a generator function that yields LeafEntry objects
+ * for each leaf in the massif. Only the components specified in the spec
+ * are read and returned, minimizing overhead.
+ *
+ * The enumerator uses DataView for efficient typed access without copying.
+ *
+ * @param buffer - The massif buffer (Uint8Array)
+ * @param massifHeight - One-based massif height
+ * @param leafCount - Number of leaves to enumerate (from start position)
+ * @param spec - Specification of which components to read
+ * @param start - Starting leaf ordinal (0-based, defaults to 0)
+ * @returns Generator that yields LeafEntry objects
+ *
+ * @example
+ * ```typescript
+ * const enumerate = createLeafEnumerator(
+ *   massif.buffer,
+ *   massifHeight,
+ *   actualLeafCount,
+ *   { idtimestamp: true, valueBytes: true },
+ *   0 // start from first leaf
+ * );
+ *
+ * for (const leaf of enumerate()) {
+ *   console.log(leaf.ordinal, leaf.idtimestamp, leaf.valueBytes);
+ * }
+ * ```
+ */
+export function createLeafEnumerator(buffer, massifHeight, leafCount, spec, start = 0) {
+    const leafTableStart = urkleLeafTableStartByteOffset(massifHeight);
+    const recordBytes = Urkle.LeafRecordBytes;
+    // Pre-compute which components we need to read
+    const readIdtimestamp = spec.idtimestamp ?? false;
+    const readValueBytes = spec.valueBytes ?? false;
+    const readExtra1 = spec.extra1 ?? false;
+    const readExtra2 = spec.extra2 ?? false;
+    const readExtra3 = spec.extra3 ?? false;
+    // Create DataView for the buffer (reused for all reads)
+    const dataView = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    return function* () {
+        for (let i = 0; i < leafCount; i++) {
+            const ordinal = start + i;
+            const recordOffset = leafTableStart + ordinal * recordBytes;
+            const entry = { ordinal };
+            if (readIdtimestamp) {
+                entry.idtimestamp = dataView.getBigUint64(recordOffset, false);
+            }
+            if (readValueBytes) {
+                entry.valueBytes = buffer.subarray(recordOffset + LEAF_COMPONENT_OFFSETS.valueBytes, recordOffset +
+                    LEAF_COMPONENT_OFFSETS.valueBytes +
+                    LEAF_COMPONENT_SIZES.valueBytes);
+            }
+            if (readExtra1) {
+                entry.extra1 = buffer.subarray(recordOffset + LEAF_COMPONENT_OFFSETS.extra1, recordOffset +
+                    LEAF_COMPONENT_OFFSETS.extra1 +
+                    LEAF_COMPONENT_SIZES.extra1);
+            }
+            if (readExtra2) {
+                entry.extra2 = buffer.subarray(recordOffset + LEAF_COMPONENT_OFFSETS.extra2, recordOffset +
+                    LEAF_COMPONENT_OFFSETS.extra2 +
+                    LEAF_COMPONENT_SIZES.extra2);
+            }
+            if (readExtra3) {
+                entry.extra3 = buffer.subarray(recordOffset + LEAF_COMPONENT_OFFSETS.extra3, recordOffset +
+                    LEAF_COMPONENT_OFFSETS.extra3 +
+                    LEAF_COMPONENT_SIZES.extra3);
+            }
+            yield entry;
+        }
+    };
+}
+/**
+ * Returns the byte offset of a specific leaf record's component.
+ *
+ * @param massifHeight - One-based massif height
+ * @param leafOrdinal - Zero-based leaf ordinal
+ * @param component - Which component to locate
+ * @returns Byte offset of the component within the massif buffer
+ */
+export function leafComponentByteOffset(massifHeight, leafOrdinal, component) {
+    const leafTableStart = urkleLeafTableStartByteOffset(massifHeight);
+    const recordOffset = leafTableStart + leafOrdinal * Urkle.LeafRecordBytes;
+    return recordOffset + LEAF_COMPONENT_OFFSETS[component];
+}
+/**
+ * Returns the size in bytes of a leaf component.
+ *
+ * @param component - Which component
+ * @returns Size in bytes
+ */
+export function leafComponentSize(component) {
+    return LEAF_COMPONENT_SIZES[component];
+}

package/dist/massifs/v2storagepaths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
+ * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
+ *
+ * @param path - The object path path from the R2 notification
+ * @returns Parsed components including logId, massifHeight, and massifIndex
+ * @throws Error if the path doesn't match expected format or if parsing fails
+ */
+export declare function parseV2StorageObjectPath(path: string): {
+    logId: string;
+    massifHeight: number;
+    massifIndex: number;
+    type: string;
+};
+//# sourceMappingURL=v2storagepaths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v2storagepaths.d.ts","sourceRoot":"","sources":["../../src/massifs/v2storagepaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM;;;;;EAkDpD"}

package/dist/massifs/v2storagepaths.js

@@ -0,0 +1,46 @@
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
+ * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
+ *
+ * @param path - The object path path from the R2 notification
+ * @returns Parsed components including logId, massifHeight, and massifIndex
+ * @throws Error if the path doesn't match expected format or if parsing fails
+ */
+export function parseV2StorageObjectPath(path) {
+    const parts = path.split("/");
+    if (parts.length < 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
+        throw new Error(`Unrecognized path format: ${path}`);
+    // Check for new v2 format: v2/merklelog/massifs/{massifHeight}/{logId}/{index}.log
+    // or v2/merklelog/checkpoints/{massifHeight}/{logId}/{index}.sth
+    const typePart = parts[2]; // "massifs" or "checkpoints"
+    const massifHeightStr = parts[3];
+    const logId = parts[4];
+    const filename = parts[5];
+    // Validate extension
+    const expectedExt = typePart === "massifs" ? ".log" : ".sth";
+    if (!filename.endsWith(expectedExt)) {
+        throw new Error(`Expected ${expectedExt} extension for ${typePart}, got: ${filename}`);
+    }
+    // Parse massif index (hex, 16 digits)
+    const massifIndexStr = filename.slice(0, -expectedExt.length);
+    if (massifIndexStr.length !== 16) {
+        throw new Error(`Massif index must be 16 hex digits, got ${massifIndexStr.length}: ${massifIndexStr}`);
+    }
+    const massifIndex = Number.parseInt(massifIndexStr, 16);
+    if (!Number.isFinite(massifIndex)) {
+        throw new Error(`Failed to parse massif index as hex number: ${massifIndexStr}`);
+    }
+    // Parse massifHeight
+    const massifHeight = Number.parseInt(massifHeightStr, 10);
+    if (!Number.isFinite(massifHeight)) {
+        throw new Error(`Failed to parse massif height as number: ${massifHeightStr}`);
+    }
+    return {
+        logId,
+        massifHeight,
+        massifIndex,
+        type: typePart,
+    };
+}

package/dist/mmr/algorithms-sync.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Convenience factory for a sync-backed Hasher (Node.js).
+ *
+ * createSyncHasher() returns a Hasher that uses node:crypto (SHA-256).
+ * digest() returns Promise.resolve(sync digest), so the hasher is suitable
+ * for callers who know they are in Node and want a sync-backed implementation.
+ */
+import type { Hasher } from "./types.js";
+/**
+ * Creates a Hasher that uses Node's crypto.createHash('sha256').
+ * digest() returns Promise.resolve(sync digest), so it is safe to use with
+ * when you need a sync-backed hasher (e.g. in Node).
+ *
+ * Only available in Node.js; throws if node:crypto is not available.
+ */
+export declare function createSyncHasher(): Promise<Hasher>;
+//# sourceMappingURL=algorithms-sync.d.ts.map

package/dist/mmr/algorithms-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algorithms-sync.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAazC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAiBxD"}

package/dist/mmr/algorithms-sync.js

@@ -0,0 +1,42 @@
+/**
+ * Convenience factory for a sync-backed Hasher (Node.js).
+ *
+ * createSyncHasher() returns a Hasher that uses node:crypto (SHA-256).
+ * digest() returns Promise.resolve(sync digest), so the hasher is suitable
+ * for callers who know they are in Node and want a sync-backed implementation.
+ */
+function concatChunks(chunks) {
+    const totalLength = chunks.reduce((s, c) => s + c.length, 0);
+    const out = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+/**
+ * Creates a Hasher that uses Node's crypto.createHash('sha256').
+ * digest() returns Promise.resolve(sync digest), so it is safe to use with
+ * when you need a sync-backed hasher (e.g. in Node).
+ *
+ * Only available in Node.js; throws if node:crypto is not available.
+ */
+export async function createSyncHasher() {
+    const { createHash } = await import("node:crypto");
+    const chunks = [];
+    return {
+        reset() {
+            chunks.length = 0;
+        },
+        update(data) {
+            chunks.push(data);
+        },
+        digest() {
+            const combined = concatChunks(chunks);
+            const buf = Buffer.from(combined);
+            const out = createHash("sha256").update(buf).digest();
+            return Promise.resolve(new Uint8Array(out));
+        },
+    };
+}

package/dist/mmr/algorithms.d.ts

@@ -0,0 +1,79 @@
+/**
+ * MMR Algorithm Implementations
+ *
+ * Core algorithms for Merkle Mountain Range operations including
+ * peak bagging, inclusion proofs, and consistency proofs.
+ *
+ * This implementation is based on the authoritative Python reference:
+ * https://raw.githubusercontent.com/robinbryce/merkle-mountain-range-proofs/refs/heads/main/algorithms.py
+ *
+ * And the associated IETF draft specification:
+ * https://raw.githubusercontent.com/robinbryce/draft-bryce-cose-receipts-mmr-profile/refs/heads/main/draft-bryce-cose-receipts-mmr-profile.md
+ */
+import type { Proof, Hasher } from "./types.js";
+/**
+ * Bags peaks together to compute a single root hash.
+ *
+ * The root is defined as the 'bagging' of all peaks, starting with the highest.
+ * This creates a binary merkle tree from the peaks to obtain a single tree root.
+ *
+ * WARNING — NOT used by the receipt verification path, and NOT spec-aligned for
+ * MMRIVER receipts. The MMR profile
+ * (draft-bryce-cose-receipts-mmr-profile) proves inclusion to a single peak
+ * (the accumulator is the list of peaks); it does not bag peaks. This helper
+ * also hashes `H(right || left)` WITHOUT the 1-based position prefix that
+ * `calculateRoot` commits, so it is inconsistent with go-merklelog interior
+ * hashing. Retained only for any legacy bagging caller; do not introduce new
+ * consumers without first reconciling with the spec.
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param peaks - Array of peak hashes (highest to lowest)
+ * @returns The bagged root hash
+ */
+export declare function bagPeaks(hasher: Hasher, peaks: Uint8Array[]): Promise<Uint8Array>;
+/**
+ * Calculates the root hash from a leaf hash and inclusion proof
+ *
+ * Mirrors the reference `included_root` (algorithms.py): each interior node is
+ * `H(pos_BE8 || left || right)` where `pos` is the 1-based node position.
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param leafHash - Hash of the leaf being proven
+ * @param proof - Inclusion proof path
+ * @param leafIndex - The zero-based MMR index of the node being proven. Despite
+ *   the name, this is treated as an MMR index (it seeds `currentPos = index + 1`
+ *   and `heightIndex(index)`). For leaf 0 the leaf index and MMR index coincide;
+ *   for any other leaf, callers MUST pass the MMR index (see `proof.mmrIndex`),
+ *   not the leaf index.
+ * @returns The calculated root hash
+ */
+export declare function calculateRoot(hasher: Hasher, leafHash: Uint8Array, proof: Proof, leafIndex: bigint): Promise<Uint8Array>;
+/**
+ * Verifies an inclusion proof
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param leafHash - Hash of the leaf being proven
+ * @param proof - Inclusion proof
+ * @param root - Expected root hash
+ * @returns True if the proof is valid
+ */
+export declare function verifyInclusion(hasher: Hasher, leafHash: Uint8Array, proof: Proof, root: Uint8Array): Promise<boolean>;
+/**
+ * Verifies a consistency proof between two MMR states.
+ *
+ * WARNING — NOT IMPLEMENTED. This is a stub: it compares each root against
+ * itself and therefore ALWAYS returns true. It performs no real consistency
+ * check and MUST NOT be relied upon for security. No worker path currently
+ * calls it. See the reference `verify_consistency` (algorithms.py) for the
+ * intended algorithm (verify proof2 extends proof1 via position-committed
+ * interior hashing).
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param proof1 - Proof for the first state
+ * @param proof2 - Proof for the second state
+ * @param root1 - Root hash of the first state
+ * @param root2 - Root hash of the second state
+ * @returns Always true (stub) — do not use for verification
+ */
+export declare function verifyConsistency(hasher: Hasher, proof1: Proof, proof2: Proof, root1: Uint8Array, root2: Uint8Array): boolean;
+//# sourceMappingURL=algorithms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"algorithms.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAqBhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,KAAK,EACb,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,UAAU,GAChB,OAAO,CAKT"}

package/dist/mmr/algorithms.js

@@ -0,0 +1,155 @@
+/**
+ * MMR Algorithm Implementations
+ *
+ * Core algorithms for Merkle Mountain Range operations including
+ * peak bagging, inclusion proofs, and consistency proofs.
+ *
+ * This implementation is based on the authoritative Python reference:
+ * https://raw.githubusercontent.com/robinbryce/merkle-mountain-range-proofs/refs/heads/main/algorithms.py
+ *
+ * And the associated IETF draft specification:
+ * https://raw.githubusercontent.com/robinbryce/draft-bryce-cose-receipts-mmr-profile/refs/heads/main/draft-bryce-cose-receipts-mmr-profile.md
+ */
+import { Uint64 } from "../uint64/index.js";
+import { heightIndex } from "./math.js";
+import { arraysEqual } from "../utils/arrays.js";
+/**
+ * Encodes a Uint64 as 8 bytes big-endian.
+ *
+ * Mirrors go-merklelog `HashWriteUint64` and the reference
+ * `pos.to_bytes(8, byteorder="big")` used by `hash_pospair64`.
+ */
+function u64BigEndian(value) {
+    const out = new Uint8Array(8);
+    let v = value.toBigInt() & 0xffffffffffffffffn;
+    for (let i = 7; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+/**
+ * Bags peaks together to compute a single root hash.
+ *
+ * The root is defined as the 'bagging' of all peaks, starting with the highest.
+ * This creates a binary merkle tree from the peaks to obtain a single tree root.
+ *
+ * WARNING — NOT used by the receipt verification path, and NOT spec-aligned for
+ * MMRIVER receipts. The MMR profile
+ * (draft-bryce-cose-receipts-mmr-profile) proves inclusion to a single peak
+ * (the accumulator is the list of peaks); it does not bag peaks. This helper
+ * also hashes `H(right || left)` WITHOUT the 1-based position prefix that
+ * `calculateRoot` commits, so it is inconsistent with go-merklelog interior
+ * hashing. Retained only for any legacy bagging caller; do not introduce new
+ * consumers without first reconciling with the spec.
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param peaks - Array of peak hashes (highest to lowest)
+ * @returns The bagged root hash
+ */
+export async function bagPeaks(hasher, peaks) {
+    if (peaks.length === 0) {
+        throw new Error("Cannot bag empty peaks array");
+    }
+    if (peaks.length === 1) {
+        return peaks[0];
+    }
+    const peakHashes = [...peaks];
+    while (peakHashes.length > 1) {
+        const right = peakHashes.pop();
+        const left = peakHashes.pop();
+        hasher.reset();
+        hasher.update(right);
+        hasher.update(left);
+        const combined = await hasher.digest();
+        peakHashes.push(combined);
+    }
+    return peakHashes[0];
+}
+/**
+ * Calculates the root hash from a leaf hash and inclusion proof
+ *
+ * Mirrors the reference `included_root` (algorithms.py): each interior node is
+ * `H(pos_BE8 || left || right)` where `pos` is the 1-based node position.
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param leafHash - Hash of the leaf being proven
+ * @param proof - Inclusion proof path
+ * @param leafIndex - The zero-based MMR index of the node being proven. Despite
+ *   the name, this is treated as an MMR index (it seeds `currentPos = index + 1`
+ *   and `heightIndex(index)`). For leaf 0 the leaf index and MMR index coincide;
+ *   for any other leaf, callers MUST pass the MMR index (see `proof.mmrIndex`),
+ *   not the leaf index.
+ * @returns The calculated root hash
+ */
+export async function calculateRoot(hasher, leafHash, proof, leafIndex) {
+    let currentHash = leafHash;
+    const mmrIndex = new Uint64(leafIndex);
+    let currentHeight = heightIndex(mmrIndex);
+    let currentPos = mmrIndex.add(new Uint64(1));
+    for (const siblingHash of proof.path) {
+        hasher.reset();
+        const nextHeight = heightIndex(new Uint64(currentPos.toBigInt()));
+        const isRightChild = nextHeight > currentHeight;
+        // Advance currentPos to the parent node's 1-based position, then commit it
+        // as the hash prefix: interior nodes are H(pos || left || right) per the
+        // MMR profile (draft-bryce-cose-receipts-mmr-profile `included_root` /
+        // `hash_pospair64`, and go-merklelog `HashPosPair64`). Omitting `pos`
+        // produces the wrong peak for any leaf above a single-leaf tree.
+        if (isRightChild) {
+            currentPos = currentPos.add(new Uint64(1));
+            hasher.update(u64BigEndian(currentPos));
+            hasher.update(siblingHash);
+            hasher.update(currentHash);
+        }
+        else {
+            currentPos = currentPos.add(new Uint64(2).shl(currentHeight));
+            hasher.update(u64BigEndian(currentPos));
+            hasher.update(currentHash);
+            hasher.update(siblingHash);
+        }
+        currentHash = await hasher.digest();
+        currentHeight += 1;
+    }
+    return currentHash;
+}
+/**
+ * Verifies an inclusion proof
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param leafHash - Hash of the leaf being proven
+ * @param proof - Inclusion proof
+ * @param root - Expected root hash
+ * @returns True if the proof is valid
+ */
+export async function verifyInclusion(hasher, leafHash, proof, root) {
+    if (proof.leafIndex === undefined && proof.mmrIndex === undefined) {
+        throw new Error("Proof must have either leafIndex or mmrIndex");
+    }
+    const leafIdx = proof.leafIndex !== undefined ? proof.leafIndex : proof.mmrIndex;
+    const calculatedRoot = await calculateRoot(hasher, leafHash, proof, leafIdx);
+    return arraysEqual(calculatedRoot, root);
+}
+/**
+ * Verifies a consistency proof between two MMR states.
+ *
+ * WARNING — NOT IMPLEMENTED. This is a stub: it compares each root against
+ * itself and therefore ALWAYS returns true. It performs no real consistency
+ * check and MUST NOT be relied upon for security. No worker path currently
+ * calls it. See the reference `verify_consistency` (algorithms.py) for the
+ * intended algorithm (verify proof2 extends proof1 via position-committed
+ * interior hashing).
+ *
+ * @param hasher - Cryptographic hasher instance
+ * @param proof1 - Proof for the first state
+ * @param proof2 - Proof for the second state
+ * @param root1 - Root hash of the first state
+ * @param root2 - Root hash of the second state
+ * @returns Always true (stub) — do not use for verification
+ */
+export function verifyConsistency(hasher, proof1, proof2, root1, root2) {
+    // TODO(plan-0027): Implement full consistency check (verify proof2 extends
+    // proof1) with position-committed interior hashing. Until then this returns
+    // true unconditionally and must not be used for any trust decision.
+    return arraysEqual(root1, root1) && arraysEqual(root2, root2);
+}