@aztec/foundation 0.76.4 → 0.77.0-testnet-ignition.21

package/src/trees/membership_witness.ts

@@ -0,0 +1,99 @@
+import { assertMemberLength } from '../array/array.js';
+import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
+import { Fr } from '../fields/fields.js';
+import { BufferReader, type Tuple, serializeToBuffer } from '../serialize/index.js';
+import type { SiblingPath } from './sibling_path.js';
+
+/**
+ * Contains information which can be used to prove that a leaf is a member of a Merkle tree.
+ */
+export class MembershipWitness<N extends number> {
+  constructor(
+    /**
+     * Size of the sibling path (number of fields it contains).
+     */
+    pathSize: N,
+    /**
+     * Index of a leaf in the Merkle tree.
+     */
+    public leafIndex: bigint,
+    /**
+     * Sibling path of the leaf in the Merkle tree.
+     */
+    public siblingPath: Tuple<Fr, N>,
+  ) {
+    assertMemberLength(this, 'siblingPath', pathSize);
+  }
+
+  toBuffer() {
+    return serializeToBuffer(toBufferBE(this.leafIndex, 32), ...this.siblingPath);
+  }
+
+  /**
+   * Creates a random membership witness. Used for testing purposes.
+   * @param pathSize - Number of fields in the sibling path.
+   * @returns Random membership witness.
+   */
+  public static random<N extends number>(pathSize: N) {
+    return new MembershipWitness<N>(
+      pathSize,
+      0n,
+      Array(pathSize)
+        .fill(0)
+        .map(() => Fr.random()) as Tuple<Fr, N>,
+    );
+  }
+
+  /**
+   * Creates a membership witness whose sibling path is full of zero fields.
+   * @param pathSize - Number of fields in the sibling path.
+   * @param leafIndex - Index of the leaf in the Merkle tree.
+   * @returns Membership witness with zero sibling path.
+   */
+  public static empty<N extends number>(pathSize: N, leafIndex = 0n): MembershipWitness<N> {
+    const arr = Array(pathSize)
+      .fill(0)
+      .map(() => Fr.ZERO) as Tuple<Fr, N>;
+    return new MembershipWitness<N>(pathSize, leafIndex, arr);
+  }
+
+  static fromBufferArray<N extends number>(leafIndex: bigint, siblingPath: Tuple<Buffer, N>): MembershipWitness<N> {
+    return new MembershipWitness<N>(
+      siblingPath.length as N,
+      leafIndex,
+      siblingPath.map(x => Fr.fromBuffer(x)) as Tuple<Fr, N>,
+    );
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer or reader to read from.
+   * @returns The deserialized `MembershipWitness`.
+   */
+  static fromBuffer<N extends number>(buffer: Buffer | BufferReader, size: N): MembershipWitness<N> {
+    const reader = BufferReader.asReader(buffer);
+    const leafIndex = toBigIntBE(reader.readBytes(32));
+    const siblingPath = reader.readArray(size, Fr);
+    return new MembershipWitness(size, leafIndex, siblingPath);
+  }
+
+  /**
+   * Creates a deserializer object for a MembershipWitness with a given size.
+   * @param size - Expected size of the witness.
+   * @returns A deserializer object.
+   */
+  static deserializer<N extends number>(size: N): { fromBuffer(buffer: Buffer | BufferReader): MembershipWitness<N> } {
+    return {
+      fromBuffer: (buffer: Buffer | BufferReader) => {
+        const reader = BufferReader.asReader(buffer);
+        const leafIndex = toBigIntBE(reader.readBytes(32));
+        const siblingPath = reader.readArray(size, Fr);
+        return new MembershipWitness(size, leafIndex, siblingPath);
+      },
+    };
+  }
+
+  static fromSiblingPath<N extends number>(leafIndex: bigint, siblingPath: SiblingPath<N>): MembershipWitness<N> {
+    return new MembershipWitness<N>(siblingPath.pathSize, leafIndex, siblingPath.toFields() as Tuple<Fr, N>);
+  }
+}

package/src/trees/merkle_tree.ts

@@ -0,0 +1,72 @@
+/** 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[]) {
+    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}`);
+    }
+  }
+
+  get root(): Buffer {
+    return this.nodes[this.nodes.length - 1];
+  }
+
+  get leaves(): Buffer[] {
+    return this.nodes.slice(0, 2 ** this.height);
+  }
+
+  /** Returns a sibling path to the given element or to the element in the given index. */
+  public getSiblingPath(leafIndex: number): Buffer[];
+  public getSiblingPath(leaf: Buffer): Buffer[];
+  public getSiblingPath(leafIndexOrLeaf: number | Buffer): Buffer[] {
+    if (Buffer.isBuffer(leafIndexOrLeaf)) {
+      return this.getSiblingPath(this.getIndex(leafIndexOrLeaf));
+    }
+    const leafIndex = leafIndexOrLeaf;
+    if (leafIndex < 0 || leafIndex >= 2 ** this.height) {
+      throw new Error(`Invalid leaf index: got ${leafIndex} but leaves count is ${2 ** this.height}`);
+    }
+    const tree = this.nodes;
+    let rowSize = Math.ceil(tree.length / 2);
+    let rowOffset = 0;
+    let index = leafIndex;
+    const siblingPath: Buffer[] = [];
+    while (rowSize > 1) {
+      const isRight = index & 1;
+      siblingPath.push(tree[rowOffset + index + (isRight ? -1 : 1)]);
+      rowOffset += rowSize;
+      rowSize >>= 1;
+      index >>= 1;
+    }
+    return siblingPath;
+  }
+
+  /** Returns the leaf index for a given element. */
+  public getIndex(element: Buffer) {
+    return this.leaves.findIndex(leaf => leaf.equals(element));
+  }
+
+  /** Returns a nice string representation of the tree, useful for debugging purposes. */
+  public drawTree(elemSize = 8) {
+    const levels: string[][] = [];
+    const tree = this.nodes;
+    const maxRowSize = Math.ceil(tree.length / 2);
+    let paddingSize = 1;
+    let rowSize = maxRowSize;
+    let rowOffset = 0;
+    while (rowSize > 0) {
+      levels.push(
+        tree
+          .slice(rowOffset, rowOffset + rowSize)
+          .map(n => n.toString('hex').slice(0, elemSize) + ' '.repeat((paddingSize - 1) * (elemSize + 1))),
+      );
+      rowOffset += rowSize;
+      paddingSize <<= 1;
+      rowSize >>= 1;
+    }
+    return levels
+      .reverse()
+      .map(row => row.join(' '))
+      .join('\n');
+  }
+}

package/src/trees/merkle_tree_calculator.ts

@@ -0,0 +1,67 @@
+import { pedersenHash } from '@aztec/foundation/crypto';
+
+import type { AsyncHasher } from './hasher.js';
+import { MerkleTree } from './merkle_tree.js';
+
+/**
+ * Merkle tree calculator.
+ */
+export class MerkleTreeCalculator {
+  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(),
+  ) {
+    const zeroHashes = [zeroLeaf];
+    for (let i = 0; i < height; i++) {
+      zeroHashes.push(await hasher(zeroHashes[i], zeroHashes[i]));
+    }
+    return new MerkleTreeCalculator(height, zeroHashes, hasher);
+  }
+
+  async computeTree(leaves: Buffer[] = []): Promise<MerkleTree> {
+    if (leaves.length === 0) {
+      leaves = new Array(2 ** this.height).fill(this.zeroHashes[0]);
+    }
+
+    let result = leaves.slice();
+
+    for (let i = 0; i < this.height; ++i) {
+      const numLeaves = 2 ** (this.height - i);
+      const newLeaves: Buffer[] = [];
+      for (let j = 0; j < leaves.length / 2; ++j) {
+        const l = leaves[j * 2];
+        const r = leaves[j * 2 + 1] || this.zeroHashes[i];
+        newLeaves[j] = await this.hasher(l, r);
+      }
+      result = result.concat(new Array(numLeaves - leaves.length).fill(this.zeroHashes[i]), newLeaves);
+      leaves = newLeaves;
+    }
+
+    return new MerkleTree(this.height, result);
+  }
+
+  async computeTreeRoot(leaves: Buffer[] = []): Promise<Buffer> {
+    if (leaves.length === 0) {
+      return this.zeroHashes[this.zeroHashes.length - 1];
+    }
+
+    leaves = leaves.slice();
+
+    for (let i = 0; i < this.height; ++i) {
+      let j = 0;
+      for (; j < leaves.length / 2; ++j) {
+        const l = leaves[j * 2];
+        const r = leaves[j * 2 + 1] || this.zeroHashes[i];
+        leaves[j] = await this.hasher(l, r);
+      }
+      leaves = leaves.slice(0, j);
+    }
+
+    return leaves[0];
+  }
+}

package/src/trees/sibling_path.ts

@@ -0,0 +1,183 @@
+import { makeTuple } from '../array/array.js';
+import { pedersenHash } from '../crypto/index.js';
+import { Fr } from '../fields/index.js';
+import { schemas } from '../schemas/index.js';
+import {
+  type Tuple,
+  assertLength,
+  deserializeArrayFromVector,
+  serializeArrayOfBufferableToVector,
+} from '../serialize/index.js';
+import { bufferToHex, hexToBuffer } from '../string/index.js';
+import type { Hasher } from './hasher.js';
+
+/**
+ * Contains functionality to compute and serialize/deserialize a sibling path.
+ * E.g. Sibling path for a leaf at index 3 in a tree of depth 3 consists of:
+ *      d0:                                            [ root ]
+ *      d1:                      [ ]                                               [*]
+ *      d2:         [*]                      [ ]                       [ ]                     [ ]
+ *      d3:   [ ]         [ ]          [*]         [ ]           [ ]         [ ]          [ ]        [ ].
+ *
+ *      And the elements would be ordered as: [ leaf_at_index_2, node_at_level_2_index_0, node_at_level_1_index_1 ].
+ */
+export class SiblingPath<N extends number> {
+  private data: Tuple<Buffer, N>;
+
+  /**
+   * Constructor.
+   * @param pathSize - The size of the sibling path.
+   * @param path - The sibling path data.
+   */
+  constructor(
+    /** Size of the sibling path (number of fields it contains). */
+    public pathSize: N,
+    /** The sibling path data. */
+    path: Buffer[],
+  ) {
+    this.data = assertLength(path, pathSize);
+  }
+
+  static get schema() {
+    return schemas.Buffer.transform(b => SiblingPath.fromBuffer(b));
+  }
+
+  static schemaFor<N extends number>(size: N) {
+    return schemas.Buffer.transform(b => SiblingPath.fromBuffer(b) as SiblingPath<N>).refine(
+      path => path.pathSize === size,
+      path => ({ message: `Expected sibling path size ${size} but got ${path.pathSize}` }),
+    );
+  }
+
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  /**
+   * Returns sibling path hashed up from the a element.
+   * @param size - The number of elements in a given path.
+   * @param zeroElement - Value of the zero element.
+   * @param hasher - Implementation of a hasher interface.
+   * @returns A sibling path hashed up from a zero element.
+   */
+  public static ZERO<N extends number>(size: N, zeroElement: Buffer, hasher: Hasher): SiblingPath<N> {
+    const bufs: Buffer[] = [];
+    let current = zeroElement;
+    for (let i = 0; i < size; ++i) {
+      bufs.push(current);
+      current = hasher.hash(current, current);
+    }
+    return new SiblingPath(size, bufs);
+  }
+
+  static random<N extends number>(number: N) {
+    const data = Array.from({ length: number }, () => Fr.random().toBuffer());
+    return new SiblingPath(number, data);
+  }
+
+  /**
+   * Serializes this SiblingPath object to a buffer.
+   * @returns The buffer representation of this object.
+   */
+  public toBuffer(): Buffer {
+    return serializeArrayOfBufferableToVector(this.data);
+  }
+
+  /**
+   * Returns the path buffer underlying the sibling path.
+   * @returns The Buffer array representation of this object.
+   */
+  public toBufferArray(): Buffer[] {
+    return this.data;
+  }
+
+  /**
+   * Convert the Sibling Path object into an array of field elements.
+   * @returns The field array representation of this object.
+   */
+  public toFields(): Fr[] {
+    return this.data.map(buf => Fr.fromBuffer(buf));
+  }
+
+  /**
+   * Convert Sibling Path object into a tuple of field elements.
+   * @returns A tuple representation of the sibling path.
+   */
+  public toTuple(): Tuple<Fr, N> {
+    const array = this.toFields();
+    return makeTuple(array.length as N, i => array[i], 0);
+  }
+
+  /**
+   * Deserializes a SiblingPath from a buffer.
+   * @param buf - A buffer containing the buffer representation of SiblingPath.
+   * @param offset - An offset to start deserializing from.
+   * @returns A SiblingPath object.
+   */
+  static fromBuffer<N extends number>(buf: Buffer, offset = 0): SiblingPath<N> {
+    const { elem } = SiblingPath.deserialize<N>(buf, offset);
+    return elem;
+  }
+
+  /**
+   * Deserializes a SiblingPath object from a slice of a part of a buffer and returns the amount of bytes advanced.
+   * @param buf - A buffer representation of the sibling path.
+   * @param offset - An offset to start deserializing from.
+   * @returns The deserialized sibling path and the number of bytes advanced.
+   */
+  static deserialize<N extends number>(buf: Buffer, offset = 0) {
+    const deserializePath = (buf: Buffer, offset: number) => ({
+      elem: buf.slice(offset, offset + 32),
+      adv: 32,
+    });
+    const { elem, adv } = deserializeArrayFromVector(deserializePath, buf, offset);
+    const size = elem.length;
+    return { elem: new SiblingPath<N>(size as N, elem), adv };
+  }
+
+  /**
+   * Serializes this SiblingPath object to a hex string representation.
+   * @returns A hex string representation of the sibling path.
+   */
+  public toString(): string {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Deserializes a SiblingPath object from a hex string representation.
+   * @param repr - A hex string representation of the sibling path.
+   * @returns A SiblingPath object.
+   */
+  public static fromString<N extends number>(repr: string): SiblingPath<N> {
+    return SiblingPath.fromBuffer<N>(hexToBuffer(repr));
+  }
+
+  /**
+   * Generate a subtree path from the current sibling path.
+   * @param subtreeHeight - The size of the subtree that we are getting the path for.
+   * @returns A new sibling path that is the for the requested subtree.
+   */
+  public getSubtreeSiblingPath<SubtreeHeight extends number, SubtreeSiblingPathHeight extends number>(
+    subtreeHeight: SubtreeHeight,
+  ): SiblingPath<SubtreeSiblingPathHeight> {
+    // Drop the size of the subtree from the path, and return the rest.
+    const subtreeData = this.data.slice(subtreeHeight);
+    const subtreePathSize = (this.pathSize - subtreeHeight) as SubtreeSiblingPathHeight;
+    return new SiblingPath(subtreePathSize, subtreeData);
+  }
+}
+
+/** Computes the expected root of a merkle tree given a leaf and its sibling path. */
+export async function computeRootFromSiblingPath(
+  leaf: Buffer,
+  siblingPath: Buffer[],
+  index: number,
+  hasher = async (left: Buffer, right: Buffer) => (await pedersenHash([left, right])).toBuffer(),
+) {
+  let result = leaf;
+  for (const sibling of siblingPath) {
+    result = index & 1 ? await hasher(sibling, result) : await hasher(result, sibling);
+    index >>= 1;
+  }
+  return result;
+}

package/src/trees/unbalanced_merkle_tree.ts

@@ -1,5 +1,5 @@
-import { padArrayEnd } from '@aztec/foundation/collection';
-import { sha256Trunc } from '@aztec/foundation/crypto';
+import { padArrayEnd } from '../collection/array.js';
+import { sha256Trunc } from '../crypto/sha256/index.js';
 
 /**
  * Computes the merkle root for an unbalanced tree.

package/src/wasm/index.ts

@@ -1 +1 @@
-export { WasmModule, IWasmModule } from './wasm_module.js';
+export { WasmModule, type IWasmModule } from './wasm_module.js';

package/src/worker/browser/start_web_module.ts

@@ -1,5 +1,5 @@
 import { type DispatchMsg, TransportServer, WorkerListener } from '../../transport/index.js';
-import { type WasmModule } from '../../wasm/index.js';
+import type { WasmModule } from '../../wasm/index.js';
 
 /**
  * Start the transport server corresponding to this module.

package/src/worker/browser/web_data_store.ts

@@ -1,7 +1,7 @@
 import levelup, { type LevelUp } from 'levelup';
 import memdown from 'memdown';
 
-import { type DataStore } from '../data_store.js';
+import type { DataStore } from '../data_store.js';
 
 /**
  * Cache for data used by wasm module.

package/src/worker/browser/web_worker.ts

@@ -1,6 +1,6 @@
 import { type DispatchMsg, TransportClient, WorkerConnector, createDispatchProxy } from '../../transport/index.js';
 import { WasmModule } from '../../wasm/index.js';
-import { type WasmWorker } from '../wasm_worker.js';
+import type { WasmWorker } from '../wasm_worker.js';
 
 /**
  * Instantiate a web worker.

package/src/worker/index.ts

@@ -1,2 +1,2 @@
 export { WorkerPool } from './worker_pool.js';
-export { WasmWorker } from './wasm_worker.js';
+export type { WasmWorker } from './wasm_worker.js';

package/src/worker/node/node_data_store.ts

@@ -2,7 +2,7 @@ import leveldown from 'leveldown';
 import levelup, { type LevelUp } from 'levelup';
 import memdown from 'memdown';
 
-import { type DataStore } from '../data_store.js';
+import type { DataStore } from '../data_store.js';
 
 /**
  * Cache for data used by wasm module.

package/src/worker/node/node_worker.ts

@@ -2,7 +2,7 @@ import { Worker } from 'worker_threads';
 
 import { type DispatchMsg, NodeConnector, TransportClient, createDispatchProxy } from '../../transport/index.js';
 import { WasmModule } from '../../wasm/wasm_module.js';
-import { type WasmWorker } from '../wasm_worker.js';
+import type { WasmWorker } from '../wasm_worker.js';
 
 /**
  * Creates a node worker.

package/src/worker/node/start_node_module.ts

@@ -1,7 +1,7 @@
 import { parentPort } from 'worker_threads';
 
 import { type DispatchMsg, NodeListener, TransportServer } from '../../transport/index.js';
-import { type WasmModule } from '../../wasm/wasm_module.js';
+import type { WasmModule } from '../../wasm/wasm_module.js';
 
 if (!parentPort) {
   throw new Error('InvalidWorker');

package/src/worker/wasm_worker.ts

@@ -1,5 +1,5 @@
-import { type Proxify } from '../transport/index.js';
-import { type WasmModule } from '../wasm/wasm_module.js';
+import type { Proxify } from '../transport/index.js';
+import type { WasmModule } from '../wasm/wasm_module.js';
 
 /**
  * Represents either a WASM web worker, or node.js worker.

package/src/worker/worker_pool.ts

@@ -1,5 +1,5 @@
 import { createLogger } from '../log/index.js';
-import { type WasmWorker } from './wasm_worker.js';
+import type { WasmWorker } from './wasm_worker.js';
 
 const log = createLogger('foundation:worker_pool');