@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/trees/unbalanced_tree_store.ts

@@ -0,0 +1,161 @@
+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): T | undefined {
+    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;
+  }
+
+  getRoot(): T | undefined {
+    return this.getNode({ level: 0, index: 0 });
+  }
+
+  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}`;
+  }
+}
+
+/// 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

@@ -0,0 +1,103 @@
+/** Strips methods of a type. */
+export type FieldsOf<T> = {
+  [P in keyof T as T[P] extends Function ? never : P]: T[P];
+};
+
+/** Extracts methods of a type. */
+export type FunctionsOf<T> = {
+  [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>;
+}
+
+/** 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

@@ -0,0 +1,72 @@
+// 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);
+  }
+}