@aztec/foundation 0.0.0-test.0 → 0.0.1-commit.0208eb9

package/src/trees/unbalanced_merkle_tree_root.ts

@@ -0,0 +1,115 @@
+import { computeBalancedMerkleTreeRoot, computeBalancedMerkleTreeRootAsync } from './balanced_merkle_tree_root.js';
+import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+import { UnbalancedMerkleTreeCalculator } from './unbalanced_merkle_tree_calculator.js';
+
+export const computeUnbalancedShaRoot = (leaves: Buffer[]) => computeUnbalancedMerkleTreeRoot(leaves, shaMerkleHash);
+
+export const computeUnbalancedPoseidonRoot = async (leaves: Buffer[]) =>
+  await computeUnbalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
+
+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 = poseidonMerkleHash,
+  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,38 @@ 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);
+}
+
+/** Resolves a record-like type. Lifted from viem. */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/**
+ * 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"}