@aztec-labs/simulator 6.0.0-nightly.20260829

package/src/public/avm/testing/account_proof_fetcher.ts

@@ -0,0 +1,166 @@
+/**
+ * Fetches an account proof from the Ethereum mainnet and saves it as account_proof.json.
+ * This script is not using any Aztec library code, so it's easily portable.
+ */
+import fs from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { createPublicClient, fromRlp, hexToBytes, http } from 'viem';
+import { mainnet } from 'viem/chains';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const RPC_URL = process.env.RPC_URL;
+const ADDRESS = (process.env.ADDRESS || '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045') as `0x${string}`;
+const BLOCK_TAG = process.env.BLOCK_NUMBER ? BigInt(process.env.BLOCK_NUMBER) : 'latest';
+const MAX_ACCOUNT_PATH = 15;
+
+function padTo(arr: number[], len: number) {
+  return [...arr, ...Array(len - arr.length).fill(0)].slice(0, len);
+}
+
+function toBytes(hex: `0x${string}`) {
+  return Array.from(hexToBytes(hex));
+}
+
+function bytesToU64s(bytes: number[]) {
+  const paddedBytes = padTo(bytes, 32);
+  return Array.from({ length: 4 }, (_, i) => {
+    let val = 0n;
+    for (let j = 0; j < 8; j++) {
+      val += BigInt(paddedBytes[i * 8 + j]) << BigInt(j * 8);
+    }
+    return val.toString();
+  });
+}
+
+function toBytesAndLen(val: bigint | number) {
+  if (val === 0n || val === 0) {
+    return { bytes: [0], length: 0 };
+  }
+  let hex = val.toString(16);
+  if (hex.length % 2) {
+    hex = '0' + hex;
+  }
+  const bytes = toBytes(`0x${hex}`);
+  return { bytes, length: bytes.length };
+}
+
+function parseNode(rlp: `0x${string}`) {
+  // Should be safe when working with branches and extensions without embedded children.
+  const decoded = fromRlp(rlp) as `0x${string}`[];
+  const node = {
+    rows: Array(16)
+      .fill(0)
+      .map(() => Array(32).fill(0)),
+    row_exist: Array(16).fill(false),
+    node_type: 0,
+  };
+
+  if (decoded.length === 17) {
+    for (let i = 0; i < 16; i++) {
+      if (decoded[i] !== '0x') {
+        node.row_exist[i] = true;
+        node.rows[i] = padTo(toBytes(decoded[i]), 32);
+      }
+    }
+  } else if (decoded.length === 2) {
+    const keyBytes = toBytes(decoded[0]);
+    const prefix = keyBytes[0];
+    if (prefix >> 4 >= 2) {
+      throw new Error('Unsupported: leaf node in proof path');
+    }
+    node.node_type = 1;
+    // Extension header format expected by the noir code: check out storage_proof types.nr.
+    node.rows[0][0] = prefix >> 4;
+    node.rows[0][8] = prefix & 0x0f;
+    node.rows[0][16] = keyBytes.length - 1;
+
+    for (let i = 1; i < keyBytes.length && i < 32; i++) {
+      node.rows[1][i - 1] = keyBytes[i];
+    }
+    node.rows[2] = padTo(toBytes(decoded[1]), 32);
+    node.row_exist[0] = node.row_exist[1] = node.row_exist[2] = true;
+  }
+  return node;
+}
+
+function parseProof(proof: `0x${string}`[], maxLen: number) {
+  const nodes = proof.slice(0, -1).slice(0, maxLen).map(parseNode);
+  while (nodes.length < maxLen) {
+    nodes.push({
+      rows: Array(16)
+        .fill(0)
+        .map(() => Array(32).fill(0)),
+      row_exist: Array(16).fill(false),
+      node_type: 0,
+    });
+  }
+  return nodes;
+}
+
+function nodeToLibFormat(node: { rows: number[][]; row_exist: boolean[]; node_type: number }) {
+  return {
+    rows: node.rows.map(bytesToU64s),
+    row_exist: node.row_exist,
+    node_type: String(node.node_type),
+  };
+}
+
+async function main() {
+  if (!RPC_URL) {
+    throw new Error('RPC_URL is not set');
+  }
+  console.log(`Fetching account proof for ${ADDRESS}`);
+
+  const client = createPublicClient({
+    chain: mainnet,
+    transport: http(RPC_URL),
+  });
+
+  const [blockNumber, proof, block] = await Promise.all([
+    client.getBlockNumber(),
+    client.getProof({
+      address: ADDRESS,
+      storageKeys: [],
+      blockNumber: BLOCK_TAG === 'latest' ? undefined : BLOCK_TAG,
+    }),
+    client.getBlock({
+      blockNumber: BLOCK_TAG === 'latest' ? undefined : BLOCK_TAG,
+    }),
+  ]);
+
+  console.log(`Block: ${blockNumber}, Account nodes: ${proof.accountProof.length}`);
+
+  // The -1 is because the last node in the proof is the leaf, which is excluded from path verification.
+  const accountPathLen = proof.accountProof.length - 1;
+  if (accountPathLen > MAX_ACCOUNT_PATH) {
+    throw new Error(
+      `Account proof path length ${accountPathLen} exceeds MAX_ACCOUNT_PATH ${MAX_ACCOUNT_PATH}. Increase the limit.`,
+    );
+  }
+
+  const nonce = toBytesAndLen(proof.nonce);
+  const balance = toBytesAndLen(proof.balance);
+
+  const data = {
+    block_number: String(blockNumber),
+    node_length: String(accountPathLen),
+    root: bytesToU64s(toBytes(block.stateRoot)),
+    nodes: parseProof(proof.accountProof, MAX_ACCOUNT_PATH).map(nodeToLibFormat),
+    account: {
+      address: toBytes(ADDRESS).map(String),
+      balance: padTo(balance.bytes, 32).map(String),
+      balance_length: String(balance.length),
+      code_hash: bytesToU64s(toBytes(proof.codeHash)),
+      nonce: padTo(nonce.bytes, 8).map(String),
+      nonce_length: String(nonce.length),
+      storage_hash: bytesToU64s(toBytes(proof.storageHash)),
+    },
+  };
+
+  fs.writeFileSync(join(__dirname, 'account_proof.json'), JSON.stringify(data, null, 2));
+  console.log('account_proof.json generated');
+}
+
+main().catch(console.error);

package/src/public/avm/testing/base_avm_simulation_tester.ts

@@ -0,0 +1,162 @@
+import { CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { ProtocolContractAddress } from '@aztec-labs/protocol-contracts';
+import { getCanonicalClassRegistry } from '@aztec-labs/protocol-contracts/class-registry';
+import { computeFeePayerBalanceStorageSlot, getCanonicalFeeJuice } from '@aztec-labs/protocol-contracts/fee-juice';
+import { getCanonicalInstanceRegistry } from '@aztec-labs/protocol-contracts/instance-registry';
+import { getStandardAuthRegistry } from '@aztec-labs/standard-contracts/auth-registry';
+import type { ContractArtifact } from '@aztec-labs/stdlib/abi';
+import { PublicDataWrite } from '@aztec-labs/stdlib/avm';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstanceWithAddress } from '@aztec-labs/stdlib/contract';
+import { computePublicDataTreeLeafSlot, siloNullifier } from '@aztec-labs/stdlib/hash';
+import type { MerkleTreeWriteOperations } from '@aztec-labs/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
+
+import type { SimpleContractDataSource } from '../../fixtures/simple_contract_data_source.js';
+import { createContractClassAndInstance } from './utils.js';
+
+/**
+ * An abstract test class that enables tests of real apps in the AVM without requiring e2e tests.
+ * It enables this by letting us (1) perform pseudo-contract-deployments (and registrations)
+ * that trigger merkle tree operations and (2) maintain a contract data source to store
+ * and retrieve contract classes and instances.
+ *
+ * This class is meant to be extended when writing tests for a specific simulation interface.
+ * For example, has been extended for testing of the core AvmSimulator, and again for the PublicTxSimulator,
+ * both of which benefit from such pseudo-deployments by populating merkle trees and a contract data source
+ * with contract information.
+ */
+export abstract class BaseAvmSimulationTester {
+  public logger = createLogger('avm-simulation-tester');
+
+  constructor(
+    public contractDataSource: SimpleContractDataSource,
+    public merkleTrees: MerkleTreeWriteOperations,
+    private initialFeePayerBalance = new Fr(10 ** 10),
+  ) {}
+
+  async setFeePayerBalance(feePayer: AztecAddress, balance = this.initialFeePayerBalance) {
+    const feeJuiceAddress = ProtocolContractAddress.FeeJuice;
+    const balanceSlot = await computeFeePayerBalanceStorageSlot(feePayer);
+    await this.setPublicStorage(feeJuiceAddress, balanceSlot, balance);
+  }
+
+  async setPublicStorage(address: AztecAddress, slot: Fr, value: Fr) {
+    const leafSlot = await computePublicDataTreeLeafSlot(address, slot);
+    // get existing preimage
+    const publicDataWrite = new PublicDataWrite(leafSlot, value);
+    await this.merkleTrees.sequentialInsert(MerkleTreeId.PUBLIC_DATA_TREE, [publicDataWrite.toBuffer()]);
+  }
+
+  /**
+   * Derive the contract class and instance with some seed.
+   * Add both to the contract data source along with the contract artifact.
+   */
+  async registerAndDeployContract(
+    constructorArgs: any[],
+    deployer: AztecAddress,
+    contractArtifact: ContractArtifact,
+    skipNullifierInsertion = false,
+    seed = 0,
+    contractClassSeed = seed,
+    originalContractClassId?: Fr, // if previously upgraded
+  ): Promise<ContractInstanceWithAddress> {
+    const { contractClass, contractInstance } = await createContractClassAndInstance(
+      constructorArgs,
+      deployer,
+      contractArtifact,
+      seed,
+      contractClassSeed,
+      originalContractClassId,
+    );
+
+    await this.contractDataSource.addNewContract(contractArtifact, contractClass, contractInstance);
+
+    if (!skipNullifierInsertion) {
+      await this.insertContractAddressNullifier(contractInstance.address);
+    }
+    return contractInstance;
+  }
+
+  async registerFeeJuiceContract(): Promise<ContractInstanceWithAddress> {
+    const feeJuice = await getCanonicalFeeJuice();
+    const feeJuiceContractClassPublic = {
+      ...feeJuice.contractClass,
+      privateFunctions: [],
+      utilityFunctions: [],
+    };
+    await this.contractDataSource.addNewContract(feeJuice.artifact, feeJuiceContractClassPublic, feeJuice.instance);
+    return feeJuice.instance;
+  }
+
+  async registerAuthContract(): Promise<ContractInstanceWithAddress> {
+    const authRegistry = await getStandardAuthRegistry();
+    const authRegistryContractClassPublic = {
+      ...authRegistry.contractClass,
+      privateFunctions: [],
+      utilityFunctions: [],
+    };
+    await this.contractDataSource.addNewContract(
+      authRegistry.artifact,
+      authRegistryContractClassPublic,
+      authRegistry.instance,
+    );
+    // AuthRegistry is a standard contract (not a protocol contract), so the AVM enforces a
+    // deployment-nullifier check on every instance retrieval. Insert the nullifier here so
+    // calls to AuthRegistry don't EXCEPTIONAL_HALT during simulation.
+    await this.insertContractAddressNullifier(authRegistry.instance.address);
+    return authRegistry.instance;
+  }
+
+  async registerClassRegistryContract(): Promise<ContractInstanceWithAddress> {
+    const classRegistry = await getCanonicalClassRegistry();
+    const classRegistryContractClassPublic = {
+      ...classRegistry.contractClass,
+      privateFunctions: [],
+      utilityFunctions: [],
+    };
+    await this.contractDataSource.addNewContract(
+      classRegistry.artifact,
+      classRegistryContractClassPublic,
+      classRegistry.instance,
+    );
+    return classRegistry.instance;
+  }
+
+  async registerInstanceRegistryContract(): Promise<ContractInstanceWithAddress> {
+    const instanceRegistry = await getCanonicalInstanceRegistry();
+    const instanceRegistryContractClassPublic = {
+      ...instanceRegistry.contractClass,
+      privateFunctions: [],
+      utilityFunctions: [],
+    };
+    await this.contractDataSource.addNewContract(
+      instanceRegistry.artifact,
+      instanceRegistryContractClassPublic,
+      instanceRegistry.instance,
+    );
+    return instanceRegistry.instance;
+  }
+
+  async addContractInstance(contractInstance: ContractInstanceWithAddress, skipNullifierInsertion = false) {
+    if (!skipNullifierInsertion) {
+      await this.insertContractAddressNullifier(contractInstance.address);
+    }
+    await this.contractDataSource.addContractInstance(contractInstance);
+  }
+
+  private async insertContractAddressNullifier(contractAddress: AztecAddress) {
+    const contractAddressNullifier = await siloNullifier(
+      AztecAddress.fromNumberUnsafe(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS),
+      contractAddress.toField(),
+    );
+    await this.merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [contractAddressNullifier.toBuffer()]);
+  }
+
+  async insertNullifier(contractThatEmitted: AztecAddress, nullifier: Fr) {
+    const siloedNullifier = await siloNullifier(contractThatEmitted, nullifier);
+    await this.merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [siloedNullifier.toBuffer()]);
+  }
+}

package/src/public/avm/testing/utils.ts

@@ -0,0 +1,114 @@
+import { CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS } from '@aztec-labs/constants';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import {
+  type ContractArtifact,
+  type FunctionAbi,
+  type FunctionArtifact,
+  FunctionSelector,
+  getAllFunctionAbis,
+} from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import {
+  type ContractClassPublic,
+  type ContractInstanceWithAddress,
+  computeInitializationHash,
+} from '@aztec-labs/stdlib/contract';
+import { siloNullifier } from '@aztec-labs/stdlib/hash';
+import { deriveKeys } from '@aztec-labs/stdlib/keys';
+import { makeContractClassPublic, makeContractInstanceFromClassId } from '@aztec-labs/stdlib/testing';
+import type { UInt64 } from '@aztec-labs/stdlib/types';
+import { strict as assert } from 'assert';
+import merge from 'lodash.merge';
+
+export const PUBLIC_DISPATCH_FN_NAME = 'public_dispatch';
+export const DEFAULT_TIMESTAMP: UInt64 = 99833n;
+export const DEFAULT_BLOCK_NUMBER = BlockNumber(42);
+
+/**
+ * Create a new object with all the same properties as the original, except for the ones in the overrides object.
+ */
+export function allSameExcept(original: any, overrides: any): any {
+  return merge({}, original, overrides);
+}
+
+export function getFunctionSelector(
+  functionName: string,
+  contractArtifact: ContractArtifact,
+): Promise<FunctionSelector> {
+  const fnArtifact = getAllFunctionAbis(contractArtifact).find(f => f.name === functionName)!;
+  assert(!!fnArtifact, `Function ${functionName} not found in ${contractArtifact.name}`);
+  const params = fnArtifact.parameters;
+  return FunctionSelector.fromNameAndParameters(fnArtifact.name, params);
+}
+
+export function getContractFunctionArtifact(
+  functionName: string,
+  contractArtifact: ContractArtifact,
+): FunctionArtifact | undefined {
+  return contractArtifact.functions.find(f => f.name === functionName);
+}
+
+export function getContractFunctionAbi(
+  functionName: string,
+  contractArtifact: ContractArtifact,
+): FunctionAbi | undefined {
+  return (
+    contractArtifact.functions.find(f => f.name === functionName) ??
+    contractArtifact.nonDispatchPublicFunctions.find(f => f.name === functionName)
+  );
+}
+
+/**
+ * Create a contract class and instance given constructor args, artifact, etc.
+ * NOTE: This is useful for testing real-ish contract class registration and instance deployment TXs (via logs)
+ * @param constructorArgs - The constructor arguments for the contract.
+ * @param deployer - The deployer of the contract.
+ * @param contractArtifact - The contract artifact for the contract.
+ * @param seed - The seed for the contract.
+ * @param originalContractClassId - The original contract class ID (if upgraded)
+ * @returns The contract class, instance, and contract address nullifier.
+ */
+export async function createContractClassAndInstance(
+  constructorArgs: any[],
+  deployer: AztecAddress,
+  contractArtifact: ContractArtifact,
+  seed = 0,
+  contractClassSeed = seed,
+  originalContractClassId?: Fr, // if previously upgraded
+): Promise<{
+  contractClass: ContractClassPublic;
+  contractInstance: ContractInstanceWithAddress;
+  contractAddressNullifier: Fr;
+}> {
+  const bytecode = (getContractFunctionArtifact(PUBLIC_DISPATCH_FN_NAME, contractArtifact) as FunctionArtifact)!
+    .bytecode;
+  const contractClass = await makeContractClassPublic(contractClassSeed, bytecode);
+
+  const constructorAbi = getContractFunctionAbi('constructor', contractArtifact);
+  const { publicKeys } = await deriveKeys(new Fr(seed));
+  const initializationHash = await computeInitializationHash(constructorAbi, constructorArgs);
+  const immutablesHash = new Fr(seed + 1);
+  const contractInstance =
+    originalContractClassId === undefined
+      ? await makeContractInstanceFromClassId(contractClass.id, seed, {
+          deployer,
+          initializationHash,
+          immutablesHash,
+          publicKeys,
+        })
+      : await makeContractInstanceFromClassId(originalContractClassId, seed, {
+          deployer,
+          initializationHash,
+          currentClassId: contractClass.id,
+          immutablesHash,
+          publicKeys,
+        });
+
+  const contractAddressNullifier = await siloNullifier(
+    AztecAddress.fromNumberUnsafe(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS),
+    contractInstance.address.toField(),
+  );
+
+  return { contractClass, contractInstance, contractAddressNullifier };
+}

package/src/public/avm_simulator.ts

@@ -0,0 +1,29 @@
+import type { PublicContractsDB } from './public_db_sources.js';
+
+/**
+ * Identifies the contract data a single simulation reads. The AVM's contract-data lookups during a
+ * `simulate` call are answered from `contractsDB`; `forkId` and `timestamp` scope those lookups to the
+ * world-state fork being simulated against. How this reaches the AVM (in-process call, IPC callback
+ * server, ...) is the implementation's concern — callers only supply the context.
+ */
+export interface AvmContractsDBContext {
+  contractsDB: PublicContractsDB;
+  forkId: number;
+  timestamp: bigint;
+}
+
+/**
+ * Something that can run AVM simulations, independent of how the work is dispatched (a single external
+ * process, a pool of them, or an in-process stub). Callers hold this and never see the underlying transport.
+ */
+export interface AvmSimulator {
+  /**
+   * Run a fast simulation and return the msgpack-encoded result. `context` supplies the contracts DB whose
+   * data the simulation reads. If `signal` aborts, the simulation stops at the next cancellation checkpoint.
+   */
+  simulate(inputBuffer: Uint8Array, context: AvmContractsDBContext, signal?: AbortSignal): Promise<Uint8Array>;
+  /** Run a simulation collecting proving hints and return the msgpack-encoded result. */
+  simulateWithHints(inputBuffer: Uint8Array): Promise<Uint8Array>;
+  /** Release any resources held by the underlying implementation. */
+  destroy?(): Promise<void>;
+}