@aztec/foundation 0.0.1-commit.b655e406 → 0.0.1-commit.fce3e4f

package/src/branded-types/types.ts

@@ -0,0 +1,2 @@
+/** Adds a branding to a type for nominal typing. */
+export type Branded<T, Brand> = T & { _branding: Brand };

package/src/config/env_var.ts

@@ -86,6 +86,7 @@ export type EnvVar =
   | 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT'
   | 'OTEL_COLLECT_INTERVAL_MS'
   | 'OTEL_EXCLUDE_METRICS'
+  | 'OTEL_INCLUDE_METRICS'
   | 'OTEL_EXPORT_TIMEOUT_MS'
   | 'PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'
   | 'PUBLIC_OTEL_INCLUDE_METRICS'
@@ -136,6 +137,7 @@ export type EnvVar =
   | 'P2P_DROP_TX'
   | 'P2P_DROP_TX_CHANCE'
   | 'P2P_TX_POOL_DELETE_TXS_AFTER_REORG'
+  | 'DEBUG_P2P_INSTRUMENT_MESSAGES'
   | 'PEER_ID_PRIVATE_KEY'
   | 'PEER_ID_PRIVATE_KEY_PATH'
   | 'PROVER_AGENT_COUNT'
@@ -168,6 +170,7 @@ export type EnvVar =
   | 'PROVER_TEST_DELAY_FACTOR'
   | 'PROVER_TEST_DELAY_MS'
   | 'PROVER_TEST_DELAY_TYPE'
+  | 'PROVER_TEST_VERIFICATION_DELAY_MS'
   | 'PXE_L2_BLOCK_BATCH_SIZE'
   | 'PXE_PROVER_ENABLED'
   | 'RPC_MAX_BATCH_SIZE'
@@ -247,7 +250,8 @@ export type EnvVar =
   | 'AZTEC_SLOT_DURATION'
   | 'AZTEC_EPOCH_DURATION'
   | 'AZTEC_TARGET_COMMITTEE_SIZE'
-  | 'AZTEC_LAG_IN_EPOCHS'
+  | 'AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET'
+  | 'AZTEC_LAG_IN_EPOCHS_FOR_RANDAO'
   | 'AZTEC_PROOF_SUBMISSION_EPOCHS'
   | 'AZTEC_ACTIVATION_THRESHOLD'
   | 'AZTEC_EJECTION_THRESHOLD'
@@ -270,10 +274,13 @@ export type EnvVar =
   | 'AZTEC_EXIT_DELAY_SECONDS'
   | 'L1_GAS_LIMIT_BUFFER_PERCENTAGE'
   | 'L1_GAS_PRICE_MAX'
+  | 'L1_FEE_PER_GAS_GWEI_MAX'
   | 'L1_BLOB_FEE_PER_GAS_MAX'
+  | 'L1_BLOB_FEE_PER_GAS_GWEI_MAX'
   | 'L1_PRIORITY_FEE_BUMP_PERCENTAGE'
   | 'L1_PRIORITY_FEE_RETRY_BUMP_PERCENTAGE'
   | 'L1_FIXED_PRIORITY_FEE_PER_GAS'
+  | 'L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI'
   | 'L1_TX_MONITOR_MAX_ATTEMPTS'
   | 'L1_TX_MONITOR_CHECK_INTERVAL_MS'
   | 'L1_TX_MONITOR_STALL_TIME_MS'
@@ -294,4 +301,7 @@ export type EnvVar =
   | 'AUTO_UPDATE_URL'
   | 'WEB3_SIGNER_URL'
   | 'SKIP_ARCHIVER_INITIAL_SYNC'
-  | 'BLOB_ALLOW_EMPTY_SOURCES';
+  | 'BLOB_ALLOW_EMPTY_SOURCES'
+  | 'FISHERMAN_MODE'
+  | 'MAX_ALLOWED_ETH_CLIENT_DRIFT_SECONDS'
+  | 'LEGACY_BLS_CLI';

package/src/crypto/aes128/index.ts

@@ -22,7 +22,7 @@ export class Aes128 {
     paddingBuffer.fill(numPaddingBytes);
     const input = Buffer.concat([data, paddingBuffer]);
 
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.aesEncrypt({
       plaintext: input,
@@ -42,7 +42,7 @@ export class Aes128 {
    * @returns Decrypted data.
    */
   public async decryptBufferCBCKeepPadding(data: Uint8Array, iv: Uint8Array, key: Uint8Array): Promise<Buffer> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.aesDecrypt({
       ciphertext: data,

package/src/crypto/bn254/index.ts

@@ -68,6 +68,9 @@ export class Bn254G1Point {
    * in the most significant bit.
    */
   static async fromCompressed(compressed: Buffer): Promise<Bn254G1Point> {
+    if (compressed.length !== 32) {
+      throw new Error('Invalid compressed point length');
+    }
     await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
 

package/src/crypto/ecdsa/index.ts

@@ -16,7 +16,7 @@ export class Ecdsa {
    * @returns A secp256k1 public key.
    */
   public async computePublicKey(privateKey: Buffer): Promise<Buffer> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response =
       this.curve === 'secp256r1'
@@ -32,7 +32,7 @@ export class Ecdsa {
    * @returns An ECDSA signature of the form (r, s, v).
    */
   public async constructSignature(msg: Uint8Array, privateKey: Buffer) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response =
       this.curve === 'secp256r1'
@@ -48,7 +48,7 @@ export class Ecdsa {
    * @returns The secp256k1 public key of the signer.
    */
   public async recoverPublicKey(msg: Uint8Array, sig: EcdsaSignature): Promise<Buffer> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response =
       this.curve === 'secp256r1'
@@ -65,7 +65,7 @@ export class Ecdsa {
    * @returns True or false.
    */
   public async verifySignature(msg: Uint8Array, pubKey: Buffer, sig: EcdsaSignature) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response =
       this.curve === 'secp256r1'

package/src/crypto/grumpkin/index.ts

@@ -20,7 +20,7 @@ export class Grumpkin {
    * @returns Result of the multiplication.
    */
   public static async mul(point: Point, scalar: GrumpkinScalar): Promise<Point> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.grumpkinMul({
       point: { x: point.x.toBuffer(), y: point.y.toBuffer() },
@@ -36,7 +36,7 @@ export class Grumpkin {
    * @returns Result of the addition.
    */
   public static async add(a: Point, b: Point): Promise<Point> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.grumpkinAdd({
       pointA: { x: a.x.toBuffer(), y: a.y.toBuffer() },
@@ -52,7 +52,7 @@ export class Grumpkin {
    * @returns Points multiplied by the scalar.
    */
   public static async batchMul(points: Point[], scalar: GrumpkinScalar) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.grumpkinBatchMul({
       points: points.map(p => ({ x: p.x.toBuffer(), y: p.y.toBuffer() })),
@@ -67,7 +67,7 @@ export class Grumpkin {
    * @returns Random field element.
    */
   public static async getRandomFr(): Promise<Fr> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.grumpkinGetRandomFr({ dummy: 0 });
     return Fr.fromBuffer(Buffer.from(response.value));
@@ -79,7 +79,7 @@ export class Grumpkin {
    * @returns Buffer representation of the field element.
    */
   public static async reduce512BufferToFr(uint512Buf: Buffer): Promise<Fr> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.grumpkinReduce512({ input: uint512Buf });
     return Fr.fromBuffer(Buffer.from(response.value));

package/src/crypto/keys/index.ts

@@ -3,7 +3,7 @@ import { BarretenbergSync } from '@aztec/bb.js';
 import { Fr } from '../../fields/fields.js';
 
 export async function vkAsFieldsMegaHonk(input: Buffer): Promise<Fr[]> {
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.megaVkAsFields({ verificationKey: input });
   return response.fields.map(field => Fr.fromBuffer(Buffer.from(field)));

package/src/crypto/pedersen/pedersen.wasm.ts

@@ -12,7 +12,7 @@ export async function pedersenCommit(input: Buffer[], offset = 0) {
     throw new Error('All Pedersen Commit input buffers must be <= 32 bytes.');
   }
   input = input.map(i => (i.length < 32 ? Buffer.concat([Buffer.alloc(32 - i.length, 0), i]) : i));
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.pedersenCommit({
     inputs: input,
@@ -29,7 +29,7 @@ export async function pedersenCommit(input: Buffer[], offset = 0) {
  */
 export async function pedersenHash(input: Fieldable[], index = 0): Promise<Fr> {
   const inputFields = serializeToFields(input);
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.pedersenHash({
     inputs: inputFields.map(i => i.toBuffer()),
@@ -42,7 +42,7 @@ export async function pedersenHash(input: Fieldable[], index = 0): Promise<Fr> {
  * Create a pedersen hash from an arbitrary length buffer.
  */
 export async function pedersenHashBuffer(input: Buffer, index = 0) {
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.pedersenHashBuffer({
     input,

package/src/crypto/poseidon/index.ts

@@ -10,7 +10,7 @@ import { type Fieldable, serializeToFields } from '../../serialize/serialize.js'
  */
 export async function poseidon2Hash(input: Fieldable[]): Promise<Fr> {
   const inputFields = serializeToFields(input);
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),
@@ -27,7 +27,7 @@ export async function poseidon2Hash(input: Fieldable[]): Promise<Fr> {
 export async function poseidon2HashWithSeparator(input: Fieldable[], separator: number): Promise<Fr> {
   const inputFields = serializeToFields(input);
   inputFields.unshift(new Fr(separator));
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),
@@ -37,7 +37,7 @@ export async function poseidon2HashWithSeparator(input: Fieldable[], separator:
 
 export async function poseidon2HashAccumulate(input: Fieldable[]): Promise<Fr> {
   const inputFields = serializeToFields(input);
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.poseidon2HashAccumulate({
     inputs: inputFields.map(i => i.toBuffer()),
@@ -54,7 +54,7 @@ export async function poseidon2Permutation(input: Fieldable[]): Promise<Fr[]> {
   const inputFields = serializeToFields(input);
   // We'd like this assertion but it's not possible to use it in the browser.
   // assert(input.length === 4, 'Input state must be of size 4');
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.poseidon2Permutation({
     inputs: inputFields.map(i => i.toBuffer()),
@@ -75,7 +75,7 @@ export async function poseidon2HashBytes(input: Buffer): Promise<Fr> {
     inputFields.push(Fr.fromBuffer(fieldBytes));
   }
 
-  await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+  await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
   const response = api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),

package/src/crypto/schnorr/index.ts

@@ -15,7 +15,7 @@ export class Schnorr {
    * @returns A grumpkin public key.
    */
   public async computePublicKey(privateKey: GrumpkinScalar): Promise<Point> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.schnorrComputePublicKey({ privateKey: privateKey.toBuffer() });
     return Point.fromBuffer(Buffer.concat([Buffer.from(response.publicKey.x), Buffer.from(response.publicKey.y)]));
@@ -28,7 +28,7 @@ export class Schnorr {
    * @returns A Schnorr signature of the form (s, e).
    */
   public async constructSignature(msg: Uint8Array, privateKey: GrumpkinScalar) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.schnorrConstructSignature({
       message: msg,
@@ -45,7 +45,7 @@ export class Schnorr {
    * @returns True or false.
    */
   public async verifySignature(msg: Uint8Array, pubKey: Point, sig: SchnorrSignature) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.schnorrVerifySignature({
       message: msg,

package/src/crypto/secp256k1/index.ts

@@ -27,7 +27,7 @@ export class Secp256k1 {
    * @returns Result of the multiplication.
    */
   public async mul(point: Uint8Array, scalar: Uint8Array) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.secp256k1Mul({
       point: { x: point.subarray(0, 32), y: point.subarray(32, 64) },
@@ -41,7 +41,7 @@ export class Secp256k1 {
    * @returns Random field element.
    */
   public async getRandomFr() {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.secp256k1GetRandomFr({ dummy: 0 });
     return Buffer.from(response.value);
@@ -53,7 +53,7 @@ export class Secp256k1 {
    * @returns Buffer representation of the field element.
    */
   public async reduce512BufferToFr(uint512Buf: Buffer) {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.secp256k1Reduce512({ input: uint512Buf });
     return Buffer.from(response.value);

package/src/crypto/sync/index.ts

@@ -3,4 +3,4 @@ import { BarretenbergSync } from '@aztec/bb.js';
 export * from './poseidon/index.js';
 export * from './pedersen/index.js';
 
-await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+await BarretenbergSync.initSingleton();

package/src/eth-address/index.ts

@@ -41,6 +41,24 @@ export class EthAddress {
     return new EthAddress(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
   }
 
+  /**
+   * Creates an EthAddress from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers (20 or 32 bytes), strings, or existing instances.
+   * @param obj - Plain object, buffer, string, or EthAddress instance
+   * @returns An EthAddress instance
+   */
+  public static fromPlainObject(obj: any): EthAddress {
+    if (obj instanceof EthAddress) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return obj.length === 20 ? new EthAddress(obj) : EthAddress.fromField(new Fr(obj));
+    }
+    return EthAddress.fromString(obj);
+  }
+
   /**
    * Create a random EthAddress instance with 20 random bytes.
    * This method generates a new Ethereum address with a randomly generated set of 20 bytes.
@@ -240,6 +258,7 @@ export class EthAddress {
   }
 
   static get schema() {
+    // Serialization from hex string.
     return hexSchemaFor(EthAddress, EthAddress.isAddress);
   }
 }

package/src/fields/fields.ts

@@ -335,7 +335,23 @@ export class Fr extends BaseField {
     return this.toString();
   }
 
+  /**
+   * Creates an Fr instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers, strings, numbers, bigints, or existing instances.
+   * @param obj - Plain object, buffer, string, number, bigint, boolean, or Fr instance
+   * @returns An Fr instance
+   */
+  static fromPlainObject(obj: any): Fr {
+    if (obj instanceof Fr) {
+      return obj;
+    }
+    return new Fr(obj);
+  }
+
   static get schema() {
+    // Serialization from hex string.
     return hexSchemaFor(Fr);
   }
 }

package/src/fields/point.ts

@@ -42,9 +42,28 @@ export class Point {
   }
 
   static get schema() {
+    // Serialization from hex string.
     return hexSchemaFor(Point);
   }
 
+  /**
+   * Creates a Point from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers, existing instances, or objects with x, y, and isInfinite fields.
+   * @param obj - Plain object, buffer, or Point instance
+   * @returns A Point instance
+   */
+  static fromPlainObject(obj: any): Point {
+    if (obj instanceof Point) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return Point.fromBuffer(obj);
+    }
+    return new Point(Fr.fromPlainObject(obj.x), Fr.fromPlainObject(obj.y), obj.isInfinite ?? false);
+  }
+
   /**
    * Generate a random Point instance.
    *

package/src/index.ts

@@ -1,5 +1,6 @@
 // Reexport all folders at the root for packages targeting CommonJS
 export * as asyncMap from './async-map/index.js';
+export * as brandedTypes from './branded-types/index.js';
 export * as bigintBuffer from './bigint-buffer/index.js';
 export * as collection from './collection/index.js';
 export * as committable from './committable/index.js';

package/src/schemas/schemas.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+import { EpochNumber, EpochNumberSchema } from '../branded-types/epoch.js';
+import { SlotNumber, SlotNumberSchema } from '../branded-types/slot.js';
 import { Buffer32 } from '../buffer/buffer32.js';
 import { SecretValue } from '../config/secret_value.js';
 import { EthAddress } from '../eth-address/index.js';
@@ -9,6 +11,12 @@ import { isHex, withoutHexPrefix } from '../string/index.js';
 import { bufferSchema, hexSchema } from './utils.js';
 
 export const schemas = {
+  /** Accepts a number, bigint, or string as an EpochNumber. */
+  EpochNumber: EpochNumberSchema,
+
+  /** Accepts a number, bigint, or string as a SlotNumber. */
+  SlotNumber: SlotNumberSchema,
+
   /** Accepts a hex string. */
   EthAddress: EthAddress.schema,
 
@@ -54,15 +62,7 @@ export const schemas = {
   Buffer32: z.string().refine(isHex, 'Not a valid hex string').transform(Buffer32.fromString),
 
   /** Accepts a base64 string or an object `{ type: 'Buffer', data: [byte, byte...] }` as a buffer. */
-  Buffer: z.union([
-    bufferSchema,
-    z
-      .object({
-        type: z.literal('Buffer'),
-        data: z.array(z.number().int().min(0).max(255)),
-      })
-      .transform(({ data }) => Buffer.from(data)),
-  ]),
+  Buffer: bufferSchema,
 
   /** Accepts a hex string as a buffer. */
   BufferHex: z
@@ -79,4 +79,4 @@ export const schemas = {
 };
 
 // These are needed to avoid errors such as: "The inferred type of 'YourClassSchema' cannot be named without a reference to..."
-export type { EthAddress, Fq, Fr, Point };
+export type { EpochNumber, EthAddress, Fq, Fr, Point, SlotNumber };

package/src/schemas/utils.ts

@@ -21,13 +21,25 @@ export const hexSchema = z.string().refine(isHex, 'Not a valid hex string').tran
 // Copied from zod internals, which was copied from https://stackoverflow.com/questions/7860392/determine-if-string-is-in-base64-using-javascript
 const base64Regex = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/;
 
-/** Schema for a buffer represented as a base64 string. */
-export const bufferSchema = z
-  .string()
-  // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
-  // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
-  .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
-  .transform(data => Buffer.from(data, 'base64'));
+/** Schema for a buffer represented as a base64 string or a Buffer object. */
+export const bufferSchema: ZodFor<Buffer> = z.union([
+  // Serialization from base64 string.
+  z
+    .string()
+    // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
+    // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
+    .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
+    .transform(data => Buffer.from(data, 'base64')),
+  // Serialization from Buffer-annotated object.
+  z
+    .object({
+      type: z.literal('Buffer'),
+      data: z.array(z.number().int().min(0).max(255)),
+    })
+    .transform(({ data }) => Buffer.from(data)),
+  // Serialization from Buffer
+  z.instanceof(Buffer),
+]);
 
 export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
   _isNullableOptional = true;
@@ -88,12 +100,13 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
  */
 export function bufferSchemaFor<TClass extends { fromBuffer(buf: Buffer): any }>(
   klazz: TClass,
+  refinement?: (buf: Buffer) => boolean,
 ): ZodType<
   TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never,
   any,
   string
 > {
-  return bufferSchema.transform(klazz.fromBuffer.bind(klazz));
+  return bufferSchema.refine(refinement ?? (() => true), 'Not a valid buffer').transform(klazz.fromBuffer.bind(klazz));
 }
 
 /** Creates a schema for a js Map type that matches the serialization used in jsonStringify. */

package/src/testing/files/index.ts

@@ -63,7 +63,7 @@ export function updateProtocolCircuitSampleInputs(circuitName: string, value: st
   logger(`Updated test data in ${targetFile} for ${circuitName}`);
 }
 
-function getPathToFile(targetFileFromRepoRoot: string) {
+export function getPathToFile(targetFileFromRepoRoot: string) {
   const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../../');
   if (!existsSync(join(repoRoot, 'CODEOWNERS'))) {
     throw new Error(`Path to repo root is incorrect (got ${repoRoot})`);

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/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';

package/src/trees/merkle_tree_calculator.ts

@@ -1,4 +1,4 @@
-import { pedersenHash, sha256Trunc } from '@aztec/foundation/crypto';
+import { pedersenHash } from '@aztec/foundation/crypto';
 
 import type { AsyncHasher } from './hasher.js';
 import { MerkleTree } from './merkle_tree.js';
@@ -69,37 +69,4 @@ export class MerkleTreeCalculator {
 
     return leaves[0];
   }
-
-  /**
-   * Computes the Merkle root with the provided leaves **synchronously**.
-   *
-   * This method uses a synchronous hash function (defaults to `sha256Trunc`) and **does not** allow for padding.
-   * If the number of leaves is not a power of two, it throws an error.
-   * This contrasts with the above non-static async method `computeTreeRoot`, which can handle any number of leaves by
-   * padding with zero hashes.
-   */
-  static computeTreeRootSync(leaves: Buffer[], hasher = sha256Trunc): 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');
-    }
-
-    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(Buffer.concat([l, r]));
-      }
-      nodes = nodes.slice(0, j);
-    }
-
-    return nodes[0];
-  }
 }