@aztec/foundation 0.0.0-test.0

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

@@ -0,0 +1,103 @@
+import { padArrayEnd } from '../collection/array.js';
+import { sha256Trunc } from '../crypto/sha256/index.js';
+
+/**
+ * Computes the merkle root for an unbalanced tree.
+ *
+ * @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.
+ */
+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);
+    }
+  }
+
+  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]]));
+    }
+    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);
+      } 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];
+      }
+    }
+    // reset the layers
+    thisLayer = nextLayer;
+    nextLayer = [];
+  }
+  // return the root
+  return thisLayer[0];
+}
+
+function getMaxBalancedTreeDepth(numLeaves: number) {
+  return Math.floor(Math.log2(numLeaves));
+}
+
+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 = getMaxBalancedTreeDepth(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/trees/unbalanced_tree_store.ts

@@ -0,0 +1,102 @@
+import { findLeafLevelAndIndex } from './unbalanced_merkle_tree.js';
+
+export interface TreeNodeLocation {
+  level: number;
+  index: number;
+}
+
+interface TreeNode<T> {
+  value: T;
+  location: TreeNodeLocation;
+}
+
+export class UnbalancedTreeStore<T> {
+  #nodeMapping: Map<string, TreeNode<T>> = new Map();
+  readonly #numLeaves: number;
+
+  constructor(numLeaves: number) {
+    this.#numLeaves = numLeaves;
+  }
+
+  setLeaf(leafIndex: number, value: T): TreeNodeLocation {
+    if (leafIndex >= this.#numLeaves) {
+      throw new Error(`Expected at most ${this.#numLeaves} leaves. Received a leaf at index ${leafIndex}.`);
+    }
+
+    const { level, indexAtLevel } = findLeafLevelAndIndex(this.#numLeaves, leafIndex);
+    const location = {
+      level,
+      index: indexAtLevel,
+    };
+    this.#nodeMapping.set(this.#getKey(location), {
+      location,
+      value,
+    });
+    return location;
+  }
+
+  setNode({ level, index }: TreeNodeLocation, value: T) {
+    const location = {
+      level,
+      index,
+    };
+    this.#nodeMapping.set(this.#getKey(location), {
+      location,
+      value,
+    });
+  }
+
+  getParentLocation({ level, index }: TreeNodeLocation): TreeNodeLocation {
+    if (level === 0) {
+      throw new Error('Tree root does not have a parent.');
+    }
+
+    return { level: level - 1, index: Math.floor(index / 2) };
+  }
+
+  getSiblingLocation({ level, index }: TreeNodeLocation): TreeNodeLocation {
+    if (level === 0) {
+      throw new Error('Tree root does not have a sibling.');
+    }
+
+    return { level, index: index % 2 ? index - 1 : index + 1 };
+  }
+
+  getChildLocations({ level, index }: TreeNodeLocation): [TreeNodeLocation, TreeNodeLocation] {
+    const left = { level: level + 1, index: index * 2 };
+    const right = { level: level + 1, index: index * 2 + 1 };
+    return [left, right];
+  }
+
+  getLeaf(leafIndex: number) {
+    const { level, indexAtLevel } = findLeafLevelAndIndex(this.#numLeaves, leafIndex);
+    const location = {
+      level,
+      index: indexAtLevel,
+    };
+    return this.getNode(location);
+  }
+
+  getNode(location: TreeNodeLocation): T | undefined {
+    return this.#nodeMapping.get(this.#getKey(location))?.value;
+  }
+
+  getParent(location: TreeNodeLocation): T | undefined {
+    const parentLocation = this.getParentLocation(location);
+    return this.getNode(parentLocation);
+  }
+
+  getSibling(location: TreeNodeLocation): T | undefined {
+    const siblingLocation = this.getSiblingLocation(location);
+    return this.getNode(siblingLocation);
+  }
+
+  getChildren(location: TreeNodeLocation): [T | undefined, T | undefined] {
+    const [left, right] = this.getChildLocations(location);
+    return [this.getNode(left), this.getNode(right)];
+  }
+
+  #getKey(location: TreeNodeLocation) {
+    return `${location.level}-${location.index}`;
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,25 @@
+/** 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];
+};
+
+/** Marks a set of properties of a type as optional. */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/** Removes readonly modifiers for a type. */
+export type Writeable<T> = { -readonly [P in keyof T]: T[P] };
+
+/** Removes readonly modifiers for an object. */
+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;

package/src/url/index.ts

@@ -0,0 +1,73 @@
+/* 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
+// 'Software'), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so, subject to
+// the following conditions:
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+import { sep } from 'path';
+
+/**
+ * File URI to Path function.
+ *
+ * @param {String} uri
+ * @return {String} path
+ * @api public
+ */
+
+export function fileURLToPath(uri: string): string {
+  if (typeof uri !== 'string' || uri.length <= 7 || uri.substring(0, 7) !== 'file://') {
+    throw new TypeError('must pass in a file:// URI to convert to a file path');
+  }
+
+  const rest = decodeURI(uri.substring(7));
+  const firstSlash = rest.indexOf('/');
+  let host = rest.substring(0, firstSlash);
+  let path = rest.substring(firstSlash + 1);
+
+  // 2.  Scheme Definition
+  // As a special case, <host> can be the string "localhost" or the empty
+  // string; this is interpreted as "the machine from which the URL is
+  // being interpreted".
+  if (host === 'localhost') {
+    host = '';
+  }
+
+  if (host) {
+    host = sep + sep + host;
+  }
+
+  // 3.2  Drives, drive letters, mount points, file system root
+  // Drive letters are mapped into the top of a file URI in various ways,
+  // depending on the implementation; some applications substitute
+  // vertical bar ("|") for the colon after the drive letter, yielding
+  // "file:///c|/tmp/test.txt".  In some cases, the colon is left
+  // unchanged, as in "file:///c:/tmp/test.txt".  In other cases, the
+  // colon is simply omitted, as in "file:///c/tmp/test.txt".
+  path = path.replace(/^(.+)\|/, '$1:');
+
+  // for Windows, we need to invert the path separators from what a URI uses
+  if (sep === '\\') {
+    path = path.replace(/\//g, '\\');
+  }
+
+  if (/^.+:/.test(path)) {
+    // has Windows drive at beginning of path
+  } else {
+    // unix path…
+    path = sep + path;
+  }
+
+  return host + path;
+}

package/src/validation/index.ts

@@ -0,0 +1,18 @@
+/** Utility function to throw an error if a required value is missing. */
+export function required<T>(value: T | undefined, errMsg?: string): T {
+  if (value === undefined) {
+    throw new Error(errMsg || 'Value is required');
+  }
+  return value;
+}
+
+/**
+ * Helper function to assert a condition is truthy
+ * @param x - A boolean condition to assert.
+ * @param err - Error message to throw if x isn't met.
+ */
+export function assert(x: any, err: string): asserts x {
+  if (!x) {
+    throw new Error(err);
+  }
+}

package/src/wasm/README.md

@@ -0,0 +1,6 @@
+# wasm
+
+Functionality to:
+
+1.  Call WebAssembly functions
+2.  Create asynchronous workers that host webassembly.