@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.5476d83

package/src/timer/timeout.ts

@@ -1,4 +1,5 @@
 import { TimeoutError } from '../error/index.js';
+import { promiseWithResolvers } from '../promise/utils.js';
 
 /**
  * TimeoutTask class creates an instance for managing and executing a given asynchronous function with a specified timeout duration.
@@ -8,15 +9,15 @@ import { TimeoutError } from '../error/index.js';
  * @typeparam T - The return type of the asynchronous function to be executed.
  */
 export class TimeoutTask<T> {
-  private interruptPromise!: Promise<any>;
-  private interrupt = () => {};
   private totalTime = 0;
+  private timeoutPromise: Promise<never> | undefined;
 
-  constructor(private fn: () => Promise<T>, private timeout: number, errorFn: () => any) {
-    this.interruptPromise = new Promise<T>((_, reject) => {
-      this.interrupt = () => reject(errorFn());
-    });
-  }
+  constructor(
+    private fn: (signal: AbortSignal) => Promise<T>,
+    private timeout: number,
+    private errorFn: () => Error,
+    private onAbort?: () => void,
+  ) {}
 
   /**
    * Executes the given function with a specified timeout.
@@ -27,15 +28,22 @@ export class TimeoutTask<T> {
    * @throws An error with a message indicating the function was interrupted due to exceeding the specified timeout.
    */
   public async exec() {
-    const interruptTimeout = setTimeout(this.interrupt, this.timeout);
-    try {
-      const start = Date.now();
-      const result = await Promise.race<T>([this.fn(), this.interruptPromise]);
-      this.totalTime = Date.now() - start;
-      return result;
-    } finally {
-      clearTimeout(interruptTimeout);
-    }
+    const signal = AbortSignal.timeout(this.timeout);
+    this.timeoutPromise = new Promise<never>((_, reject) => {
+      signal!.addEventListener(
+        'abort',
+        () => {
+          this.onAbort?.();
+          reject(this.errorFn());
+        },
+        { once: true },
+      );
+    });
+
+    const start = Date.now();
+    const result = await Promise.race<T>([this.fn(signal), this.timeoutPromise]);
+    this.totalTime = Date.now() - start;
+    return result;
   }
 
   /**
@@ -46,7 +54,7 @@ export class TimeoutTask<T> {
    * @returns The interrupt promise associated with the task.
    */
   public getInterruptPromise() {
-    return this.interruptPromise;
+    return this.timeoutPromise;
   }
 
   /**
@@ -60,11 +68,38 @@ export class TimeoutTask<T> {
   }
 }
 
-export async function executeTimeout<T>(fn: () => Promise<T>, timeout: number, errorOrFnName?: string | (() => any)) {
+/**
+ * Executes a function with a timeout.
+ * @param fn - The function to execute, accepts AbortSignal and returns a Promise.
+ * @param timeout - The maximum time in milliseconds to allow the function to run.
+ * @param errorOrFnName - Optional function name or a function that returns an Error to throw if the timeout is reached.
+ * @param onAbort - Optional callback to execute when the task is aborted.
+ *
+ * @returns A Promise that resolves with the result of the function fn if it completes within the timeout
+ *
+ * */
+export async function executeTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  timeout: number,
+  errorOrFnName?: string | (() => Error),
+  onAbort?: () => void,
+) {
   const errorFn =
     typeof errorOrFnName === 'function'
       ? errorOrFnName
       : () => new TimeoutError(`Timeout running ${errorOrFnName ?? 'function'} after ${timeout}ms.`);
-  const task = new TimeoutTask(fn, timeout, errorFn);
+  const task = new TimeoutTask(fn, timeout, errorFn, onAbort);
   return await task.exec();
 }
+
+/** Returns a promise that rejects after the given timeout */
+export function timeoutPromise(timeoutMs: number, errorMessage?: string) {
+  const promise = promiseWithResolvers<never>();
+
+  const timer = setTimeout(() => {
+    promise.reject(new TimeoutError(errorMessage ?? `Operation timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+
+  const cleanup = () => clearTimeout(timer);
+  return promise.promise.finally(cleanup);
+}

package/src/transport/index.ts

@@ -7,5 +7,4 @@ export * from './interface/socket.js';
 export * from './interface/transferable.js';
 export * from './transport_client.js';
 export * from './transport_server.js';
-export * from './browser/index.js';
 export * from './node/index.js';

package/src/transport/interface/connector.ts

@@ -4,6 +4,5 @@ import type { Socket } from './socket.js';
  * Opens a socket with corresponding TransportListener.
  */
 export interface Connector {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   createSocket(): Promise<Socket>;
 }

package/src/transport/interface/listener.ts

@@ -7,10 +7,9 @@ import type { Socket } from './socket.js';
  * Possible implementations could include MessageChannels or WebSockets.
  */
 export interface Listener extends EventEmitter {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   open(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   close(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   on(name: 'new_socket', cb: (client: Socket) => void): this;
 }

package/src/transport/interface/socket.ts

@@ -6,10 +6,9 @@
  * If `registerHandler` callback receives `undefined` that signals the other end closed.
  */
 export interface Socket {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   send(msg: any, transfer?: Transferable[]): Promise<void>;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   registerHandler(cb: (msg: any) => any): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   close(): void;
 }

package/src/transport/transport_client.ts

@@ -18,9 +18,9 @@ interface PendingRequest {
    * The unique message identifier used for tracking and matching request/response pairs.
    */
   msgId: number;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   resolve(data: any): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   reject(error: Error): void;
 }
 
@@ -30,9 +30,8 @@ interface PendingRequest {
  * for efficient and concurrent communication with a corresponding TransportServer.
  */
 export interface ITransportClient<Payload> extends EventEmitter {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   on(name: 'event_msg', handler: (payload: Payload) => void): this;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   emit(name: 'event_msg', payload: Payload): boolean;
 }
 

package/src/transport/transport_server.ts

@@ -9,7 +9,10 @@ import { isTransferDescriptor } from './interface/transferable.js';
 export class TransportServer<Payload> {
   private sockets: Socket[] = [];
 
-  constructor(private listener: Listener, private msgHandlerFn: (msg: Payload) => Promise<any>) {}
+  constructor(
+    private listener: Listener,
+    private msgHandlerFn: (msg: Payload) => Promise<any>,
+  ) {}
 
   /**
    * Starts the TransportServer, allowing it to accept new connections and handle incoming messages.

package/src/trees/balanced_merkle_tree.ts

@@ -0,0 +1,82 @@
+import { pedersenHash as pedersenHashArray, poseidon2Hash, sha256Trunc } from '@aztec/foundation/crypto';
+
+import type { AsyncHasher, Hasher } from './hasher.js';
+
+export const shaMerkleHash: Hasher['hash'] = (left: Buffer, right: Buffer) =>
+  sha256Trunc(Buffer.concat([left, right])) as Buffer<ArrayBuffer>;
+
+export const pedersenMerkleHash: AsyncHasher['hash'] = async (left: Buffer, right: Buffer) =>
+  (await pedersenHashArray([left, right])).toBuffer() as Buffer<ArrayBuffer>;
+
+export const poseidonMerkleHash: AsyncHasher['hash'] = async (left: Buffer, right: Buffer) =>
+  (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>;
+
+export const computeBalancedShaRoot = (leaves: Buffer[]) => computeBalancedMerkleTreeRoot(leaves);
+
+export const computeBalancedPedersenRoot = async (leaves: Buffer[]) =>
+  await computeBalancedMerkleTreeRootAsync(leaves, pedersenMerkleHash);
+
+export const computeBalancedPoseidonRoot = async (leaves: Buffer[]) =>
+  await computeBalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
+
+/**
+ * Computes the Merkle root with the provided leaves **synchronously**.
+ * This method uses a synchronous hash function (defaults to `sha256Trunc`).
+ *
+ * @throws If the number of leaves is not a power of two.
+ */
+export function computeBalancedMerkleTreeRoot(leaves: Buffer[], hasher = shaMerkleHash): Buffer {
+  const height = getTreeHeight(leaves);
+  let nodes = leaves.slice();
+
+  for (let i = 0; i < height; ++i) {
+    let j = 0;
+    for (; j < nodes.length / 2; ++j) {
+      const l = nodes[j * 2];
+      const r = nodes[j * 2 + 1];
+      nodes[j] = hasher(l, r);
+    }
+    nodes = nodes.slice(0, j);
+  }
+
+  return nodes[0];
+}
+
+/**
+ * Computes the Merkle root with the provided leaves **asynchronously**.
+ * This method uses an asynchronous hash function (defaults to `pedersenHash`).
+ *
+ * @throws If the number of leaves is not a power of two.
+ */
+export async function computeBalancedMerkleTreeRootAsync(
+  leaves: Buffer[],
+  hasher = poseidonMerkleHash,
+): Promise<Buffer> {
+  const height = getTreeHeight(leaves);
+  let nodes = leaves.slice();
+
+  for (let i = 0; i < height; ++i) {
+    let j = 0;
+    for (; j < nodes.length / 2; ++j) {
+      const l = nodes[j * 2];
+      const r = nodes[j * 2 + 1];
+      nodes[j] = await hasher(l, r);
+    }
+    nodes = nodes.slice(0, j);
+  }
+
+  return nodes[0];
+}
+
+function getTreeHeight(leaves: Buffer[]) {
+  if (leaves.length === 0) {
+    throw new Error('Cannot compute a Merkle root with no leaves');
+  }
+
+  const height = Math.log2(leaves.length);
+  if (!Number.isInteger(height)) {
+    throw new Error('Cannot compute a Merkle root with a non-power-of-two number of leaves');
+  }
+
+  return height;
+}

package/src/trees/hasher.ts

@@ -8,14 +8,14 @@ export interface Hasher {
    * @param rhs - The second array.
    * @returns The new 32-byte hash.
    */
-  hash(lhs: Uint8Array, rhs: Uint8Array): Buffer;
+  hash(lhs: Uint8Array, rhs: Uint8Array): Buffer<ArrayBuffer>;
 
   /**
    * Hashes an array of buffers.
    * @param inputs - The array of buffers to hash.
    * @returns The resulting 32-byte hash.
    */
-  hashInputs(inputs: Buffer[]): Buffer;
+  hashInputs(inputs: Buffer[]): Buffer<ArrayBuffer>;
 }
 
 /**
@@ -28,12 +28,12 @@ export interface AsyncHasher {
    * @param rhs - The second array.
    * @returns The new 32-byte hash.
    */
-  hash(lhs: Uint8Array, rhs: Uint8Array): Promise<Buffer>;
+  hash(lhs: Uint8Array, rhs: Uint8Array): Promise<Buffer<ArrayBuffer>>;
 
   /**
    * Hashes an array of buffers.
    * @param inputs - The array of buffers to hash.
    * @returns The resulting 32-byte hash.
    */
-  hashInputs(inputs: Buffer[]): Promise<Buffer>;
+  hashInputs(inputs: Buffer[]): Promise<Buffer<ArrayBuffer>>;
 }

package/src/trees/index.ts

@@ -1,3 +1,4 @@
+export * from './balanced_merkle_tree.js';
 export * from './unbalanced_merkle_tree.js';
 export * from './unbalanced_tree_store.js';
 export * from './merkle_tree_calculator.js';
@@ -8,3 +9,4 @@ export * from './sibling_path.js';
 export * from './membership_witness.js';
 export * from './hasher.js';
 export * from './indexed_tree_leaf.js';
+export * from './unbalanced_merkle_tree_calculator.js';

package/src/trees/indexed_merkle_tree.ts

@@ -6,7 +6,11 @@ import { MerkleTree } from './merkle_tree.js';
 
 /** A simple immutable indexed merkle tree container. Use a IndexedMerkleTreeCalculator to create a new instance from a set of leaves. */
 export class IndexedMerkleTree<T extends IndexedTreeLeafPreimage, N extends number> extends MerkleTree {
-  constructor(height: N, nodes: Buffer[], public readonly leafPreimages: T[]) {
+  constructor(
+    height: N,
+    nodes: Buffer[],
+    public readonly leafPreimages: T[],
+  ) {
     super(height, nodes);
   }
 

package/src/trees/indexed_merkle_tree_calculator.ts

@@ -28,7 +28,7 @@ export class IndexedMerkleTreeCalculator<T extends IndexedTreeLeafPreimage, N ex
   ) {
     const zeroHashes = [zeroLeaf];
     for (let i = 0; i < height; i++) {
-      zeroHashes.push(await hasher.hash(zeroHashes[i], zeroHashes[i]));
+      zeroHashes.push((await hasher.hash(zeroHashes[i], zeroHashes[i])) as Buffer<ArrayBuffer>);
     }
     return new IndexedMerkleTreeCalculator(height, zeroHashes, hasher, factory);
   }
@@ -59,7 +59,7 @@ export class IndexedMerkleTreeCalculator<T extends IndexedTreeLeafPreimage, N ex
 
     for (let i = 0; i < this.height; ++i) {
       const numLeaves = 2 ** (this.height - i);
-      const newLeaves: Buffer[] = [];
+      const newLeaves: Buffer<ArrayBuffer>[] = [];
       for (let j = 0; j < leaves.length / 2; ++j) {
         const l = leaves[j * 2];
         const r = leaves[j * 2 + 1] || this.zeroHashes[i];

package/src/trees/membership_witness.ts

@@ -1,6 +1,7 @@
 import { assertMemberLength } from '../array/array.js';
 import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
 import { Fr } from '../fields/fields.js';
+import { schemas } from '../schemas/schemas.js';
 import { BufferReader, type Tuple, serializeToBuffer } from '../serialize/index.js';
 import type { SiblingPath } from './sibling_path.js';
 
@@ -29,6 +30,18 @@ export class MembershipWitness<N extends number> {
     return serializeToBuffer(toBufferBE(this.leafIndex, 32), ...this.siblingPath);
   }
 
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  toFields(): Fr[] {
+    return [new Fr(this.leafIndex), ...this.siblingPath];
+  }
+
+  static schemaFor<N extends number>(size: N) {
+    return schemas.Buffer.transform(b => MembershipWitness.fromBuffer(b, size));
+  }
+
   /**
    * Creates a random membership witness. Used for testing purposes.
    * @param pathSize - Number of fields in the sibling path.

package/src/trees/merkle_tree.ts

@@ -1,6 +1,9 @@
 /** A simple immutable Merkle tree container. Use a MerkleTreeCalculator to create a new instance from a set of leaves. */
 export class MerkleTree {
-  constructor(public readonly height: number, public readonly nodes: Buffer[]) {
+  constructor(
+    public readonly height: number,
+    public readonly nodes: Buffer[],
+  ) {
     const expectedNodeCount = 2 ** (height + 1) - 1;
     if (nodes.length !== expectedNodeCount) {
       throw new Error(`Invalid node count for Merkle tree: got ${nodes.length} but expected ${expectedNodeCount}`);

package/src/trees/merkle_tree_calculator.ts

@@ -7,18 +7,23 @@ import { MerkleTree } from './merkle_tree.js';
  * Merkle tree calculator.
  */
 export class MerkleTreeCalculator {
-  private constructor(private height: number, private zeroHashes: Buffer[], private hasher: AsyncHasher['hash']) {
+  private constructor(
+    private height: number,
+    private zeroHashes: Buffer[],
+    private hasher: AsyncHasher['hash'],
+  ) {
     this.hasher = hasher;
   }
 
   static async create(
     height: number,
-    zeroLeaf = Buffer.alloc(32),
-    hasher = async (left: Buffer, right: Buffer) => (await pedersenHash([left, right])).toBuffer(),
+    zeroLeaf: Buffer = Buffer.alloc(32),
+    hasher = async (left: Buffer, right: Buffer) =>
+      (await pedersenHash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
   ) {
     const zeroHashes = [zeroLeaf];
     for (let i = 0; i < height; i++) {
-      zeroHashes.push(await hasher(zeroHashes[i], zeroHashes[i]));
+      zeroHashes.push((await hasher(zeroHashes[i], zeroHashes[i])) as Buffer<ArrayBuffer>);
     }
     return new MerkleTreeCalculator(height, zeroHashes, hasher);
   }

package/src/trees/unbalanced_merkle_tree.ts

@@ -1,60 +1,116 @@
-import { padArrayEnd } from '../collection/array.js';
-import { sha256Trunc } from '../crypto/sha256/index.js';
+import {
+  computeBalancedMerkleTreeRoot,
+  computeBalancedMerkleTreeRootAsync,
+  poseidonMerkleHash,
+  shaMerkleHash,
+} from './balanced_merkle_tree.js';
+
+export const computeUnbalancedShaRoot = (leaves: Buffer[]) => computeUnbalancedMerkleTreeRoot(leaves, shaMerkleHash);
+
+export const computeUnbalancedPoseidonRoot = async (leaves: Buffer[]) =>
+  await computeUnbalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
 
 /**
- * Computes the merkle root for an unbalanced tree.
+ * 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.
  *
- * @dev Adapted from unbalanced_tree.ts.
- * Calculates the tree upwards layer by layer until we reach the root.
- * The L1 calculation instead computes the tree from right to left (slightly cheaper gas).
- * TODO: A more thorough investigation of which method is cheaper, then use that method everywhere.
+ * 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 computeUnbalancedMerkleRoot(leaves: Buffer[], emptyLeaf?: Buffer, hasher = sha256Trunc): Buffer {
-  // Pad leaves to 2
-  if (leaves.length < 2) {
-    if (emptyLeaf === undefined) {
-      throw new Error('Cannot compute a Merkle root with less than 2 leaves');
-    } else {
-      leaves = padArrayEnd(leaves, emptyLeaf, 2);
-    }
+export function computeUnbalancedMerkleTreeRoot(
+  leaves: Buffer[],
+  hasher = shaMerkleHash,
+  emptyRoot = Buffer.alloc(32),
+): Buffer {
+  if (!leaves.length) {
+    return emptyRoot;
+  }
+
+  if (leaves.length === 1) {
+    return leaves[0];
   }
 
-  const depth = Math.ceil(Math.log2(leaves.length));
-  let [layerWidth, nodeToShift] =
-    leaves.length & 1 ? [leaves.length - 1, leaves[leaves.length - 1]] : [leaves.length, Buffer.alloc(0)];
-  // Allocate this layer's leaves and init the next layer up
-  let thisLayer = leaves.slice(0, layerWidth);
-  let nextLayer = [];
-  for (let i = 0; i < depth; i++) {
-    for (let j = 0; j < layerWidth; j += 2) {
-      // Store the hash of each pair one layer up
-      nextLayer[j / 2] = hasher(Buffer.concat([thisLayer[j], thisLayer[j + 1]]));
+  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;
     }
-    layerWidth /= 2;
-    if (layerWidth & 1) {
-      if (nodeToShift.length) {
-        // If the next layer has odd length, and we have a node that needs to be shifted up, add it here
-        nextLayer.push(nodeToShift);
-        layerWidth += 1;
-        nodeToShift = Buffer.alloc(0);
+
+    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 {
-        // If we don't have a node waiting to be shifted, store the next layer's final node to be shifted
-        layerWidth -= 1;
-        nodeToShift = nextLayer[layerWidth];
+        root = await hasher(subtreeRoot, root);
       }
+
+      numRemainingLeaves -= subtreeSize;
     }
-    // reset the layers
-    thisLayer = nextLayer;
-    nextLayer = [];
+
+    subtreeSize *= 2;
   }
-  // return the root
-  return thisLayer[0];
+
+  return root!;
 }
 
-function getMaxBalancedTreeDepth(numLeaves: number) {
+/// 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 wonky 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));
 }
@@ -72,7 +128,7 @@ function findPosition(
   }
 
   // The largest balanced tree that can be created with the given number of leaves.
-  const maxBalancedTreeDepth = getMaxBalancedTreeDepth(numLeaves);
+  const maxBalancedTreeDepth = getMaxBalancedSubtreeDepth(numLeaves);
   const numBalancedLeaves = 2 ** maxBalancedTreeDepth;
   const numRemainingLeaves = numLeaves - numBalancedLeaves;