@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/trees/unbalanced_merkle_tree_calculator.ts

@@ -0,0 +1,176 @@
+import { type Hasher, shaMerkleHash } from './hasher.js';
+import { SiblingPath } from './sibling_path.js';
+import { type TreeNodeLocation, UnbalancedTreeStore } from './unbalanced_tree_store.js';
+
+interface TreeNode {
+  value: Buffer;
+  leafIndex?: number;
+}
+
+/**
+ * An ephemeral unbalanced Merkle tree implementation.
+ * Follows the rollup implementation which greedily hashes pairs of nodes up the tree.
+ * Remaining rightmost nodes are shifted up until they can be paired.
+ * The values that match the `valueToCompress` are skipped and the sibling of the compressed leaf are shifted up until
+ * they can be paired.
+ * If there is only one leaf, the root is the leaf.
+ */
+export class UnbalancedMerkleTreeCalculator {
+  private store: UnbalancedTreeStore<TreeNode>;
+  private leafLocations: TreeNodeLocation[] = [];
+
+  public constructor(
+    private readonly leaves: Buffer[],
+    private readonly valueToCompress: Buffer,
+    private readonly emptyRoot: Buffer,
+    private readonly hasher: Hasher['hash'],
+  ) {
+    this.store = new UnbalancedTreeStore(leaves.length);
+    this.buildTree();
+  }
+
+  static create(
+    leaves: Buffer[],
+    valueToCompress = Buffer.alloc(0),
+    emptyRoot = Buffer.alloc(32),
+    hasher = shaMerkleHash,
+  ) {
+    return new UnbalancedMerkleTreeCalculator(leaves, valueToCompress, emptyRoot, hasher);
+  }
+
+  /**
+   * Returns the root of the tree.
+   * @returns The root of the tree.
+   */
+  public getRoot(): Buffer {
+    return this.store.getRoot()!.value;
+  }
+
+  /**
+   * Returns a sibling path for the element.
+   * @param value - The value of the element.
+   * @returns A sibling path for the element.
+   * Note: The sibling path is an array of sibling hashes, with the lowest hash (leaf hash) first, and the highest hash last.
+   */
+  public getSiblingPath<N extends number>(value: Buffer): SiblingPath<N> {
+    const leafIndex = this.leaves.findIndex(leaf => leaf.equals(value));
+    if (leafIndex === -1) {
+      throw Error(`Leaf value ${value.toString('hex')} not found in tree.`);
+    }
+
+    return this.getSiblingPathByLeafIndex(leafIndex);
+  }
+
+  /**
+   * Returns a sibling path for the leaf at the given index.
+   * @param leafIndex - The index of the leaf.
+   * @returns A sibling path for the leaf.
+   */
+  public getSiblingPathByLeafIndex<N extends number>(leafIndex: number): SiblingPath<N> {
+    if (leafIndex >= this.leaves.length) {
+      throw Error(`Leaf index ${leafIndex} out of bounds. Tree has ${this.leaves.length} leaves.`);
+    }
+
+    const leaf = this.leaves[leafIndex];
+    if (leaf.equals(this.valueToCompress)) {
+      throw Error(`Leaf at index ${leafIndex} has been compressed.`);
+    }
+
+    const path: Buffer[] = [];
+    let location = this.leafLocations[leafIndex];
+    while (location.level > 0) {
+      const sibling = this.store.getSibling(location)!;
+      path.push(sibling.value);
+      location = this.store.getParentLocation(location);
+    }
+
+    return new SiblingPath<N>(path.length as N, path);
+  }
+
+  public getLeafLocation(leafIndex: number) {
+    return this.leafLocations[leafIndex];
+  }
+
+  /**
+   * Adds leaves and nodes to the store. Updates the leafLocations.
+   * @param leaves - The leaves of the tree.
+   */
+  private buildTree() {
+    this.leafLocations = this.leaves.map((value, i) => this.store.setLeaf(i, { value, leafIndex: i }));
+
+    // Start with the leaves that are not compressed.
+    let toProcess = this.leafLocations.filter((_, i) => !this.leaves[i].equals(this.valueToCompress));
+    if (!toProcess.length) {
+      // All leaves are compressed. Set empty root to the root.
+      this.store.setNode({ level: 0, index: 0 }, { value: this.emptyRoot });
+      return;
+    }
+
+    const level = toProcess[0].level;
+    for (let i = level; i > 0; i--) {
+      const toProcessNext = [];
+      for (const location of toProcess) {
+        if (location.level !== i) {
+          toProcessNext.push(location);
+          continue;
+        }
+
+        const parentLocation = this.store.getParentLocation(location);
+        if (this.store.getNode(parentLocation)) {
+          // Parent has been updated by its (left) sibling.
+          continue;
+        }
+
+        const sibling = this.store.getSibling(location);
+        // If sibling is undefined, all its children are compressed.
+        const shouldShiftUp = !sibling || sibling.value.equals(this.valueToCompress);
+        if (shouldShiftUp) {
+          // The node becomes the parent if the sibling is a compressed leaf.
+          this.shiftNodeUp(location, parentLocation);
+        } else {
+          // Hash the value with the (right) sibling and update the parent node.
+          const node = this.store.getNode(location)!;
+          const parentValue = this.hasher(node.value, sibling.value);
+          this.store.setNode(parentLocation, { value: parentValue });
+        }
+
+        // Add the parent location to be processed next.
+        toProcessNext.push(parentLocation);
+      }
+
+      toProcess = toProcessNext;
+    }
+  }
+
+  private shiftNodeUp(from: TreeNodeLocation, to: TreeNodeLocation) {
+    // Collect all nodes that need to shift.
+    const nodesToShift = this.collectNodesToShift(from, to);
+    // Move all nodes to their new locations.
+    for (const { node, newLocation } of nodesToShift) {
+      this.store.setNode(newLocation, node);
+      if (node.leafIndex !== undefined) {
+        this.leafLocations[node.leafIndex] = newLocation;
+      }
+    }
+  }
+
+  private collectNodesToShift(from: TreeNodeLocation, to: TreeNodeLocation) {
+    const node = this.store.getNode(from);
+    if (!node) {
+      return [];
+    }
+
+    let result = [{ node, newLocation: to }];
+
+    // If not a leaf, collect its children.
+    if (node.leafIndex === undefined) {
+      const [leftChild, rightChild] = this.store.getChildLocations(from);
+      const [leftChildNew, rightChildNew] = this.store.getChildLocations(to);
+      result = result
+        .concat(this.collectNodesToShift(leftChild, leftChildNew))
+        .concat(this.collectNodesToShift(rightChild, rightChildNew));
+    }
+
+    return result;
+  }
+}

package/src/trees/unbalanced_merkle_tree_root.ts

@@ -0,0 +1,112 @@
+import { computeBalancedMerkleTreeRoot, computeBalancedMerkleTreeRootAsync } from './balanced_merkle_tree_root.js';
+import { shaMerkleHash } from './hasher.js';
+import { UnbalancedMerkleTreeCalculator } from './unbalanced_merkle_tree_calculator.js';
+
+export const computeUnbalancedShaRoot = (leaves: Buffer[]) => computeUnbalancedMerkleTreeRoot(leaves, shaMerkleHash);
+
+export const computeWonkyShaRoot = (leaves: Buffer[]) => computeWonkyMerkleTreeRoot(leaves);
+
+/**
+ * Computes the Merkle root of an unbalanced tree.
+ *
+ * Unlike a balanced Merkle tree, which requires the number of leaves to be a power of two, an unbalanced tree can have
+ * any number of leaves.
+ *
+ * The tree is constructed by iteratively extracting the smallest power-of-two-sized subtrees from **right to left**.
+ * For each such subtree, it computes the subtree root and then combines all subtree roots (again from right to left)
+ * into a single root using the provided hash function.
+ *
+ * Note: We need the final tree to be as shallow as possible, to minimize the size of the sibling path required to prove
+ * membership of a leaf. Therefor, the computation proceeds from right to left - smaller subtrees must always be
+ * combined before being merged with a larger sibling on their left.
+ *
+ * For example, consider an unbalanced tree made of three subtrees of sizes 2, 4, and 8. If we combine the size-2 and
+ * size-4 subtrees first (producing a subtree of depth 3), and then merge it with the size-8 subtree (also depth 3), the
+ * resulting tree has a maximum depth of 4.
+ *
+ * But if we instead combine the size-4 and size-8 subtrees first (depth 4), and then merge with the size-2 subtree
+ * (depth 1), the final tree has a depth of 5.
+ */
+export function computeUnbalancedMerkleTreeRoot(
+  leaves: Buffer[],
+  hasher = shaMerkleHash,
+  emptyRoot = Buffer.alloc(32),
+): Buffer {
+  if (!leaves.length) {
+    return emptyRoot;
+  }
+
+  if (leaves.length === 1) {
+    return leaves[0];
+  }
+
+  let numRemainingLeaves = leaves.length;
+  let subtreeSize = 1;
+  let root: Buffer | undefined;
+  while (numRemainingLeaves > 1) {
+    if ((numRemainingLeaves & subtreeSize) !== 0) {
+      const subtreeLeaves = leaves.slice(numRemainingLeaves - subtreeSize, numRemainingLeaves);
+      const subtreeRoot = computeBalancedMerkleTreeRoot(subtreeLeaves, hasher);
+      if (!root) {
+        root = subtreeRoot;
+      } else {
+        root = hasher(subtreeRoot, root);
+      }
+
+      numRemainingLeaves -= subtreeSize;
+    }
+
+    subtreeSize *= 2;
+  }
+
+  return root!;
+}
+
+export async function computeUnbalancedMerkleTreeRootAsync(
+  leaves: Buffer[],
+  hasher: (left: Uint8Array, right: Uint8Array) => Promise<Buffer<ArrayBuffer>>,
+  emptyRoot = Buffer.alloc(32),
+): Promise<Buffer> {
+  if (!leaves.length) {
+    return emptyRoot;
+  }
+
+  if (leaves.length === 1) {
+    return leaves[0];
+  }
+
+  let numRemainingLeaves = leaves.length;
+  let subtreeSize = 1;
+  let root: Buffer | undefined;
+  while (numRemainingLeaves > 1) {
+    if ((numRemainingLeaves & subtreeSize) !== 0) {
+      const subtreeLeaves = leaves.slice(numRemainingLeaves - subtreeSize, numRemainingLeaves);
+      const subtreeRoot = await computeBalancedMerkleTreeRootAsync(subtreeLeaves, hasher);
+      if (!root) {
+        root = subtreeRoot;
+      } else {
+        root = await hasher(subtreeRoot, root);
+      }
+
+      numRemainingLeaves -= subtreeSize;
+    }
+
+    subtreeSize *= 2;
+  }
+
+  return root!;
+}
+
+// A **wonky** tree is a "compressed" unbalanced Merkle tree.
+// It is constructed in the same way as an unbalanced tree: by first creating the largest possible left subtree, with
+// the remaining leaves forming a right subtree that follows the same process recursively.
+// During construction, leaves equal to `valueToCompress` are skipped (compressed) and do not contribute to the tree.
+export function computeWonkyMerkleTreeRoot(
+  leaves: Buffer[],
+  valueToCompress = Buffer.alloc(32),
+  emptyRoot = Buffer.alloc(32),
+  hasher = shaMerkleHash,
+): Buffer {
+  const calculator = UnbalancedMerkleTreeCalculator.create(leaves, valueToCompress, emptyRoot, hasher);
+  return calculator.getRoot();
+}

package/src/trees/unbalanced_tree_store.ts

@@ -1,5 +1,3 @@
-import { findLeafLevelAndIndex } from './unbalanced_merkle_tree.js';
-
 export interface TreeNodeLocation {
   level: number;
   index: number;
@@ -68,7 +66,7 @@ export class UnbalancedTreeStore<T> {
     return [left, right];
   }
 
-  getLeaf(leafIndex: number) {
+  getLeaf(leafIndex: number): T | undefined {
     const { level, indexAtLevel } = findLeafLevelAndIndex(this.#numLeaves, leafIndex);
     const location = {
       level,
@@ -81,6 +79,10 @@ export class UnbalancedTreeStore<T> {
     return this.#nodeMapping.get(this.#getKey(location))?.value;
   }
 
+  getRoot(): T | undefined {
+    return this.getNode({ level: 0, index: 0 });
+  }
+
   getParent(location: TreeNodeLocation): T | undefined {
     const parentLocation = this.getParentLocation(location);
     return this.getNode(parentLocation);
@@ -100,3 +102,60 @@ export class UnbalancedTreeStore<T> {
     return `${location.level}-${location.index}`;
   }
 }
+
+/// Get the depth of the maximum balanced tree that can be created with the given number of leaves. The subtree will be
+/// the left most subtree of the unbalanced tree with a total of `numLeaves` leaves.
+///
+/// Note: All the leaves may not be used to form the tree. For example, if there are 5 leaves, the maximum depth is 2,
+/// only 4 leaves are used to form a balanced tree.
+function getMaxBalancedSubtreeDepth(numLeaves: number) {
+  return Math.floor(Math.log2(numLeaves));
+}
+
+/// Get the maximum depth of an unbalanced tree that can be created with the given number of leaves.
+function getMaxUnbalancedTreeDepth(numLeaves: number) {
+  return Math.ceil(Math.log2(numLeaves));
+}
+
+function findPosition(
+  rootLevel: number,
+  leafLevel: number,
+  numLeaves: number,
+  indexOffset: number,
+  targetIndex: number,
+): { level: number; indexAtLevel: number } {
+  if (numLeaves <= 1) {
+    // Single leaf.
+    return { level: rootLevel, indexAtLevel: indexOffset };
+  }
+
+  // The largest balanced tree that can be created with the given number of leaves.
+  const maxBalancedTreeDepth = getMaxBalancedSubtreeDepth(numLeaves);
+  const numBalancedLeaves = 2 ** maxBalancedTreeDepth;
+  const numRemainingLeaves = numLeaves - numBalancedLeaves;
+
+  if (targetIndex < numBalancedLeaves) {
+    // Target is in the balanced tree.
+
+    // - If numRemainingLeaves is 0: this balanced tree is grown from the current root.
+    // - If numRemainingLeaves is not 0: the remaining leaves will form another tree, which will become the right child of the root.
+    //   And the balanced tree will be the left child of the root.
+    //   There will be an extra level between the root of the balanced tree and the current root.
+    const extraLevel = numRemainingLeaves ? 1 : 0;
+
+    return { level: rootLevel + maxBalancedTreeDepth + extraLevel, indexAtLevel: indexOffset + targetIndex };
+  } else {
+    // Target is in the right branch.
+    const rightBranchMaxLevel = getMaxUnbalancedTreeDepth(numRemainingLeaves);
+    const shiftedUp = leafLevel - rootLevel - rightBranchMaxLevel - 1;
+    const nextLeafLevel = leafLevel - shiftedUp;
+    const newIndexOffset = (indexOffset + numBalancedLeaves) >> shiftedUp;
+    const shiftedTargetIndex = targetIndex - numBalancedLeaves;
+    return findPosition(rootLevel + 1, nextLeafLevel, numRemainingLeaves, newIndexOffset, shiftedTargetIndex);
+  }
+}
+
+export function findLeafLevelAndIndex(numLeaves: number, leafIndex: number) {
+  const maxLevel = getMaxUnbalancedTreeDepth(numLeaves);
+  return findPosition(0, maxLevel, numLeaves, 0, leafIndex);
+}

package/src/types/index.ts

@@ -1,12 +1,10 @@
 /** Strips methods of a type. */
 export type FieldsOf<T> = {
-  // eslint-disable-next-line @typescript-eslint/ban-types
   [P in keyof T as T[P] extends Function ? never : P]: T[P];
 };
 
 /** Extracts methods of a type. */
 export type FunctionsOf<T> = {
-  // eslint-disable-next-line @typescript-eslint/ban-types
   [P in keyof T as T[P] extends Function ? P : never]: T[P];
 };
 
@@ -21,5 +19,85 @@ export function unfreeze<T>(obj: T): Writeable<T> {
   return obj as Writeable<T>;
 }
 
-/** Maybe exists, maybe not. */
-export type Maybe<T extends object> = T | unknown;
+/** Is defined type guard */
+export function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+/** Type guard for error classes */
+export function isErrorClass<T extends Error>(value: unknown, errorClass: new (...args: any[]) => T): value is T {
+  return value instanceof errorClass || (value instanceof Error && value.name === errorClass.name);
+}
+
+const MAX_ERR_DEPTH = 10;
+
+/** Returns the first error in the cause chain matching the given error class. */
+export function getErrorCause<T extends Error>(err: unknown, errorClass: new (...args: any[]) => T): T | undefined {
+  let current = err;
+  for (let i = 0; current !== undefined && current !== null && i < MAX_ERR_DEPTH; i++) {
+    if (isErrorClass(current, errorClass)) {
+      return current;
+    }
+
+    if (typeof current === 'object' && Object.hasOwn(current, 'cause')) {
+      current = (current as { cause: unknown }).cause;
+    } else {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Resolves a record-like type. Lifted from viem. */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/** Returns a type T based on a flag: T if true, undefined if false, optional otherwise. */
+export type DefineIfFlag<Opts, Key extends keyof Opts, T> = Opts extends {
+  [K in Key]: true;
+}
+  ? T
+  : Opts extends { [K in Key]: false }
+    ? never
+    : Opts extends { [K in Key]?: boolean }
+      ? T | undefined
+      : never;
+
+/** Returns a type with fields conditionally required based on a flag */
+export type PickIfFlag<
+  OptsSchema,
+  Opts extends OptsSchema,
+  Key extends keyof OptsSchema,
+  Field extends object,
+> = Opts extends { [K in Key]: true }
+  ? Field
+  : Opts extends { [K in Key]: false }
+    ? {}
+    : Opts extends { [K in Key]?: boolean }
+      ? Partial<Field>
+      : {};
+
+/** Picks only the defined (non-undefined) properties of a type. */
+export type PickDefined<T> = Prettify<Pick<T, { [K in keyof T]: T[K] extends undefined ? never : K }[keyof T]>>;
+
+/**
+ * Type-safe Event Emitter type
+ * @example
+ * export type ArchiverEmitter = TypedEventEmitter<{
+ *  [L2BlockSourceEvents.L2PruneUnproven]: (args: L2BlockSourceEvent) => void;
+ *  [L2BlockSourceEvents.L2BlockProven]: (args: L2BlockSourceEvent) => void;
+ * }>;
+ * class Archiver extends (EventEmitter as new () => ArchiverEmitter) {
+ *  // ...
+ * }
+ */
+export interface TypedEventEmitter<TEventMap extends { [key in keyof TEventMap]: (...args: any[]) => void }> {
+  once<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): this;
+  on<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): this;
+  off<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): this;
+  emit<K extends keyof TEventMap>(event: K, ...args: Parameters<TEventMap[K]>): boolean;
+  removeListener<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): this;
+  removeAllListeners<K extends keyof TEventMap>(event: K): this;
+  // Can add other EventEmitter methods if needed, like once(), listenerCount(), etc.
+}

package/src/url/index.ts

@@ -1,4 +1,3 @@
-/* eslint-disable */
 // Copyright (c) 2014 Nathan Rajlich <nathan@tootallnate.net>
 // Permission is hereby granted, free of charge, to any person obtaining
 // a copy of this software and associated documentation files (the

package/dest/crypto/index.d.ts

@@ -1,15 +0,0 @@
-export * from './keccak/index.js';
-export * from './random/index.js';
-export * from './sha256/index.js';
-export * from './sha512/index.js';
-export * from './pedersen/index.js';
-export * from './poseidon/index.js';
-export * from './secp256k1-signer/index.js';
-export * from './keys/index.js';
-export * from './aes128/index.js';
-export * from './grumpkin/index.js';
-export * from './ecdsa/index.js';
-export * from './secp256k1/index.js';
-export * from './schnorr/index.js';
-export * from './signature/index.js';
-//# sourceMappingURL=index.d.ts.map

package/dest/crypto/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dest/crypto/index.js

@@ -1,14 +0,0 @@
-export * from './keccak/index.js';
-export * from './random/index.js';
-export * from './sha256/index.js';
-export * from './sha512/index.js';
-export * from './pedersen/index.js';
-export * from './poseidon/index.js';
-export * from './secp256k1-signer/index.js';
-export * from './keys/index.js';
-export * from './aes128/index.js';
-export * from './grumpkin/index.js';
-export * from './ecdsa/index.js';
-export * from './secp256k1/index.js';
-export * from './schnorr/index.js';
-export * from './signature/index.js';

package/dest/crypto/pedersen/pedersen.elliptic.d.ts

@@ -1,13 +0,0 @@
-/// <reference types="node" resolution-mode="require"/>
-/// <reference types="node" resolution-mode="require"/>
-/**
- * Create a pedersen commitment (point) from an array of input fields.
- * Left pads any inputs less than 32 bytes.
- */
-export declare function pedersenCommit(input: Buffer[], generatorOffset?: number): Buffer[];
-/**
- * Create a pedersen hash (field) from an array of input fields.
- * Left pads any inputs less than 32 bytes.
- */
-export declare function pedersenHash(input: Buffer[], index?: number): Buffer;
-//# sourceMappingURL=pedersen.elliptic.d.ts.map

package/dest/crypto/pedersen/pedersen.elliptic.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pedersen.elliptic.d.ts","sourceRoot":"","sources":["../../../src/crypto/pedersen/pedersen.elliptic.ts"],"names":[],"mappings":";;AA+iBA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,eAAe,SAAI,YAOlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,SAAI,UAOtD"}