@aztec/simulator 0.0.1-commit.24de95ac → 0.0.1-commit.27d773e65

package/src/private/circuit_recording/circuit_recorder.ts

@@ -1,5 +1,5 @@
-import { sha512 } from '@aztec/foundation/crypto';
-import { createLogger } from '@aztec/foundation/log';
+import { sha512 } from '@aztec/foundation/crypto/sha512';
+import { type Logger, type LoggerBindings, resolveLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
 import type { ForeignCallHandler, ForeignCallInput, ForeignCallOutput } from '@aztec/noir-acvm_js';
 
@@ -89,14 +89,16 @@ export class CircuitRecording {
  * ```
  */
 export class CircuitRecorder {
-  protected readonly logger = createLogger('simulator:acvm:recording');
+  protected readonly logger: Logger;
 
   protected recording?: CircuitRecording;
 
   private stackDepth: number = 0;
   private newCircuit: boolean = true;
 
-  protected constructor() {}
+  protected constructor(loggerOrBindings?: Logger | LoggerBindings) {
+    this.logger = resolveLogger('simulator:acvm:recording', loggerOrBindings);
+  }
 
   /**
    * Initializes a new circuit recording session.
@@ -108,16 +110,16 @@ export class CircuitRecorder {
    * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
    */
   start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName: string): Promise<void> {
-    const parentRef = this.recording;
     if (this.newCircuit) {
+      const parentRef = this.recording;
       this.recording = new CircuitRecording(
         circuitName,
         functionName,
         sha512(circuitBytecode).toString('hex'),
         Object.fromEntries(input),
       );
+      this.recording.setParent(parentRef);
     }
-    this.recording!.setParent(parentRef);
 
     return Promise.resolve();
   }
@@ -173,22 +175,22 @@ export class CircuitRecorder {
         if (result instanceof Promise) {
           return result.then(async r => {
             // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-            // since we are going back to the "parent" circuit which can never be new
+            // so that the parent circuit continues with its existing recording
+            // Note: recording restoration is handled by finish()
             if (isExternalCall) {
               this.stackDepth--;
               this.newCircuit = false;
-              this.recording = this.recording!.parent;
             }
             await this.recordCall(name, args, r, timer.ms(), this.stackDepth);
             return r;
           }) as ReturnType<typeof fn>;
         }
         // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-        // since we are going back to the "parent" circuit which can never be new
+        // so that the parent circuit continues with its existing recording
+        // Note: recording restoration is handled by finish()
         if (isExternalCall) {
           this.stackDepth--;
           this.newCircuit = false;
-          this.recording = this.recording!.parent;
         }
         void this.recordCall(name, args, result, timer.ms(), this.stackDepth);
         return result;
@@ -239,6 +241,12 @@ export class CircuitRecorder {
     if (!result!.parent) {
       this.newCircuit = true;
       this.recording = undefined;
+    } else {
+      // For nested circuits (utility calls, nested contract calls), restore to parent recording
+      // Note: we don't set newCircuit=false here because:
+      // - For privateCallPrivateFunction, the callback wrapper will set it to false
+      // - For utility calls, we want newCircuit to remain true so the next circuit creates its own recording
+      this.recording = result!.parent;
     }
     return Promise.resolve(result!);
   }
@@ -247,14 +255,9 @@ export class CircuitRecorder {
    * Finalizes the recording by resetting the state and returning the recording object with an attached error.
    * @param error - The error that occurred during circuit execution
    */
-  finishWithError(error: unknown): Promise<CircuitRecording> {
-    const result = this.recording;
-    // If this is the top-level circuit recording, we reset the state for the next simulator call
-    if (!result!.parent) {
-      this.newCircuit = true;
-      this.recording = undefined;
-    }
-    result!.error = JSON.stringify(error);
-    return Promise.resolve(result!);
+  async finishWithError(error: unknown): Promise<CircuitRecording> {
+    const result = await this.finish();
+    result.error = JSON.stringify(error);
+    return result;
   }
 }

package/src/private/circuit_recording/file_circuit_recorder.ts

@@ -1,3 +1,5 @@
+import type { Logger } from '@aztec/foundation/log';
+
 import fs from 'fs/promises';
 import path from 'path';
 
@@ -7,8 +9,11 @@ import { CircuitRecorder, type CircuitRecording } from './circuit_recorder.js';
 export class FileCircuitRecorder extends CircuitRecorder {
   declare recording?: CircuitRecording & { filePath: string; isFirstCall: boolean };
 
-  constructor(private readonly recordDir: string) {
-    super();
+  constructor(
+    private readonly recordDir: string,
+    logger?: Logger,
+  ) {
+    super(logger);
   }
 
   override async start(

package/src/private/circuit_recording/memory_circuit_recorder.ts

@@ -1,11 +1,13 @@
+import type { Logger } from '@aztec/foundation/log';
+
 import { CircuitRecorder } from './circuit_recorder.js';
 
-/*
+/**
  * In memory circuit recorder uses the default implementation. This is kept
- * while we decide the fate of the FileCircuitRecorder
+ * while we decide the fate of the FileCircuitRecorder.
  */
 export class MemoryCircuitRecorder extends CircuitRecorder {
-  constructor() {
-    super();
+  constructor(logger?: Logger) {
+    super(logger);
   }
 }

package/src/private/factory.ts

@@ -1,4 +1,4 @@
-import { type Logger, createLogger } from '@aztec/foundation/log';
+import { type Logger, type LoggerBindings, resolveLogger } from '@aztec/foundation/log';
 
 import { promises as fs } from 'fs';
 
@@ -21,18 +21,21 @@ export function getSimulatorConfigFromEnv() {
 
 export async function createSimulator(
   config: SimulatorConfig,
-  logger: Logger = createLogger('simulator'),
+  loggerOrBindings?: Logger | LoggerBindings,
 ): Promise<CircuitSimulator> {
+  const logger = resolveLogger('simulator', loggerOrBindings);
   if (config.acvmBinaryPath && config.acvmWorkingDirectory) {
     try {
       await fs.access(config.acvmBinaryPath, fs.constants.R_OK);
       await fs.mkdir(config.acvmWorkingDirectory, { recursive: true });
       logger.info(`Using native ACVM at ${config.acvmBinaryPath} and working directory ${config.acvmWorkingDirectory}`);
-      return new NativeACVMSimulator(config.acvmWorkingDirectory, config.acvmBinaryPath);
+      const acvmLogger = logger.createChild('acvm-native');
+      return new NativeACVMSimulator(config.acvmWorkingDirectory, config.acvmBinaryPath, undefined, acvmLogger);
     } catch {
       logger.warn(`Failed to access ACVM at ${config.acvmBinaryPath}, falling back to WASM`);
     }
   }
   logger.info('Using WASM ACVM simulation');
-  return new WASMSimulator();
+  const wasmLogger = logger.createChild('wasm');
+  return new WASMSimulator(wasmLogger);
 }

package/src/public/avm/avm_context.ts

@@ -1,4 +1,3 @@
-import type { Fr } from '@aztec/foundation/fields';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 import type { PublicPersistableStateManager } from '../state_manager/state_manager.js';
@@ -6,6 +5,7 @@ import type { AvmExecutionEnvironment } from './avm_execution_environment.js';
 import { type Gas, gasToGasLeft } from './avm_gas.js';
 import { AvmMachineState } from './avm_machine_state.js';
 import type { AvmSimulatorInterface } from './avm_simulator_interface.js';
+import type { CallData } from './calldata.js';
 
 /**
  * An execution context includes the information necessary to initiate AVM
@@ -45,7 +45,7 @@ export class AvmContext {
    */
   public async createNestedContractCallContext(
     address: AztecAddress,
-    calldata: Fr[],
+    calldata: CallData,
     allocatedGas: Gas,
     callType: 'CALL' | 'STATICCALL',
   ): Promise<AvmContext> {

package/src/public/avm/avm_contract_call_result.ts

@@ -1,4 +1,3 @@
-import type { Fr } from '@aztec/foundation/fields';
 import type { SimulationError } from '@aztec/stdlib/errors';
 import { Gas } from '@aztec/stdlib/gas';
 
@@ -6,6 +5,7 @@ import { inspect } from 'util';
 
 import { createSimulationError } from '../../common/errors.js';
 import type { Gas as AvmGas } from './avm_gas.js';
+import type { ReturnData } from './calldata.js';
 import type { AvmRevertReason } from './errors.js';
 
 /**
@@ -14,14 +14,14 @@ import type { AvmRevertReason } from './errors.js';
 export class AvmContractCallResult {
   constructor(
     public reverted: boolean,
-    public output: Fr[],
+    public output: ReturnData,
     public gasLeft: AvmGas,
     public revertReason?: AvmRevertReason,
     public totalInstructions: number = 0, // including nested calls
   ) {}
 
   toString(): string {
-    let resultsStr = `reverted: ${this.reverted}, output: ${this.output}, gasLeft: ${inspect(
+    let resultsStr = `reverted: ${this.reverted}, output: ${this.output.bestEffortReadAll(10)}${this.output.length() > 10 ? ' ...' : ''}, gasLeft: ${inspect(
       this.gasLeft,
     )}, totalInstructions: ${this.totalInstructions}`;
     if (this.revertReason) {
@@ -31,7 +31,9 @@ export class AvmContractCallResult {
   }
 
   finalize(): AvmFinalizedCallResult {
-    const revertReason = this.revertReason ? createSimulationError(this.revertReason, this.output) : undefined;
+    const revertReason = this.revertReason
+      ? createSimulationError(this.revertReason, this.output.bestEffortReadAll())
+      : undefined;
     return new AvmFinalizedCallResult(
       this.reverted,
       this.output,
@@ -49,14 +51,14 @@ export class AvmContractCallResult {
 export class AvmFinalizedCallResult {
   constructor(
     public reverted: boolean,
-    public output: Fr[],
+    public output: ReturnData,
     public gasLeft: Gas,
     public revertReason?: SimulationError,
     public totalInstructions: number = 0, // including nested calls
   ) {}
 
   toString(): string {
-    let resultsStr = `reverted: ${this.reverted}, output: ${this.output}, gasLeft: ${inspect(
+    let resultsStr = `reverted: ${this.reverted}, output: ${this.output.bestEffortReadAll(10)}${this.output.length() > 10 ? ' ...' : ''}, gasLeft: ${inspect(
       this.gasLeft,
     )}, totalInstructions: ${this.totalInstructions}`;
     if (this.revertReason) {

package/src/public/avm/avm_execution_environment.ts

@@ -1,8 +1,10 @@
-import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { PublicSimulatorConfig } from '@aztec/stdlib/avm';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { GlobalVariables } from '@aztec/stdlib/tx';
 
+import type { CallData } from './calldata.js';
+
 /**
  * Contains variables that remain constant during AVM execution
  * These variables are provided by the public kernel circuit
@@ -15,14 +17,13 @@ export class AvmExecutionEnvironment {
     public readonly transactionFee: Fr,
     public readonly globals: GlobalVariables,
     public readonly isStaticCall: boolean,
-    public readonly calldata: Fr[],
-    public readonly clientInitiatedSimulation: boolean = false,
-    public readonly maxDebugLogMemoryReads: number = DEFAULT_MAX_DEBUG_LOG_MEMORY_READS,
+    public readonly calldata: CallData,
+    public readonly config: PublicSimulatorConfig,
   ) {}
 
   private deriveEnvironmentForNestedCallInternal(
     targetAddress: AztecAddress,
-    calldata: Fr[],
+    calldata: CallData,
     isStaticCall: boolean,
   ): AvmExecutionEnvironment {
     return new AvmExecutionEnvironment(
@@ -33,16 +34,18 @@ export class AvmExecutionEnvironment {
       this.globals,
       isStaticCall,
       calldata,
-      this.clientInitiatedSimulation,
-      this.maxDebugLogMemoryReads,
+      this.config,
     );
   }
 
-  public deriveEnvironmentForNestedCall(targetAddress: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+  public deriveEnvironmentForNestedCall(targetAddress: AztecAddress, calldata: CallData): AvmExecutionEnvironment {
     return this.deriveEnvironmentForNestedCallInternal(targetAddress, calldata, /*isStaticCall=*/ false);
   }
 
-  public deriveEnvironmentForNestedStaticCall(targetAddress: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+  public deriveEnvironmentForNestedStaticCall(
+    targetAddress: AztecAddress,
+    calldata: CallData,
+  ): AvmExecutionEnvironment {
     return this.deriveEnvironmentForNestedCallInternal(targetAddress, calldata, /*isStaticCall=*/ true);
   }
 }

package/src/public/avm/avm_gas.ts

@@ -26,9 +26,9 @@ export function makeGas(gasCost: Partial<Gas>) {
 }
 
 /** Sums together multiple instances of Gas. */
-export function sumGas(...gases: Partial<Gas>[]) {
-  return gases.reduce(
-    (acc: Gas, gas) => ({
+export function sumGas(...gases: Partial<Gas>[]): Gas {
+  return gases.reduce<Gas>(
+    (acc, gas) => ({
       l2Gas: acc.l2Gas + (gas.l2Gas ?? 0),
       daGas: acc.daGas + (gas.daGas ?? 0),
     }),
@@ -110,7 +110,7 @@ const BASE_GAS_COSTS: Record<Opcode, Gas> = {
   [Opcode.NULLIFIEREXISTS]: makeCost(c.AVM_NULLIFIEREXISTS_BASE_L2_GAS, 0),
   [Opcode.EMITNULLIFIER]: makeCost(c.AVM_EMITNULLIFIER_BASE_L2_GAS, c.AVM_EMITNULLIFIER_BASE_DA_GAS),
   [Opcode.L1TOL2MSGEXISTS]: makeCost(c.AVM_L1TOL2MSGEXISTS_BASE_L2_GAS, 0),
-  [Opcode.EMITUNENCRYPTEDLOG]: makeCost(c.AVM_EMITUNENCRYPTEDLOG_BASE_L2_GAS, c.AVM_EMITUNENCRYPTEDLOG_BASE_DA_GAS),
+  [Opcode.EMITPUBLICLOG]: makeCost(c.AVM_EMITPUBLICLOG_BASE_L2_GAS, c.AVM_EMITPUBLICLOG_BASE_DA_GAS),
   [Opcode.SENDL2TOL1MSG]: makeCost(c.AVM_SENDL2TOL1MSG_BASE_L2_GAS, c.AVM_SENDL2TOL1MSG_BASE_DA_GAS),
   [Opcode.GETCONTRACTINSTANCE]: makeCost(c.AVM_GETCONTRACTINSTANCE_BASE_L2_GAS, 0),
   [Opcode.CALL]: makeCost(c.AVM_CALL_BASE_L2_GAS, 0),
@@ -130,7 +130,7 @@ const DYNAMIC_GAS_COSTS = new Map<Opcode, Gas>([
   [Opcode.CALLDATACOPY, makeCost(c.AVM_CALLDATACOPY_DYN_L2_GAS, 0)],
   [Opcode.RETURNDATACOPY, makeCost(c.AVM_RETURNDATACOPY_DYN_L2_GAS, 0)],
   // TODO: Call and static call based on bytecode length
-  [Opcode.EMITUNENCRYPTEDLOG, makeCost(c.AVM_EMITUNENCRYPTEDLOG_DYN_L2_GAS, c.AVM_EMITUNENCRYPTEDLOG_DYN_DA_GAS)],
+  [Opcode.EMITPUBLICLOG, makeCost(c.AVM_EMITPUBLICLOG_DYN_L2_GAS, c.AVM_EMITPUBLICLOG_DYN_DA_GAS)],
   [Opcode.TORADIXBE, makeCost(c.AVM_TORADIXBE_DYN_L2_GAS, 0)],
   [Opcode.AND_8, makeCost(c.AVM_BITWISE_DYN_L2_GAS, 0)],
   [Opcode.AND_16, makeCost(c.AVM_BITWISE_DYN_L2_GAS, 0)],

package/src/public/avm/avm_machine_state.ts

@@ -1,7 +1,8 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { Gas } from './avm_gas.js';
 import { TaggedMemory } from './avm_memory_types.js';
+import { type ReturnData, ReturnDataArray } from './calldata.js';
 import { type AvmRevertReason, OutOfGasError } from './errors.js';
 
 /**
@@ -39,7 +40,7 @@ export class AvmMachineState {
   /** program counter of the next instruction, byte based */
   public nextPc: number = 0;
   /** return/revertdata of the last nested call. */
-  public nestedReturndata: Fr[] = [];
+  public nestedReturndata: ReturnData = new ReturnDataArray([]);
   /** Tracks whether the last external call was successful */
   public nestedCallSuccess: boolean = false;
   /**
@@ -66,7 +67,7 @@ export class AvmMachineState {
   /** Signals that execution has reverted normally (this does not cover exceptional halts) */
   private reverted: boolean = false;
   /** Output data must NOT be modified once it is set */
-  private output: Fr[] = [];
+  private output: ReturnData = new ReturnDataArray([]);
 
   // Metrics only - not needed for execution
   /** instruction counter, including nested calls */
@@ -129,7 +130,7 @@ export class AvmMachineState {
    * Output data must NOT be modified once it is set
    * @param output
    */
-  public return(output: Fr[]) {
+  public return(output: ReturnData) {
     this.halted = true;
     this.output = output;
   }
@@ -139,7 +140,7 @@ export class AvmMachineState {
    * Output data must NOT be modified once it is set
    * @param output
    */
-  public revert(output: Fr[]) {
+  public revert(output: ReturnData) {
     this.halted = true;
     this.reverted = true;
     this.output = output;
@@ -153,7 +154,7 @@ export class AvmMachineState {
     return this.reverted;
   }
 
-  public getOutput(): Fr[] {
+  public getOutput(): ReturnData {
     return this.output;
   }
 

package/src/public/avm/avm_memory_types.ts

@@ -8,7 +8,7 @@ import {
   MEM_TAG_U128,
 } from '@aztec/constants';
 import { toBufferBE } from '@aztec/foundation/bigint-buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { FunctionsOf } from '@aztec/foundation/types';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -369,6 +369,10 @@ export class TaggedMemory implements TaggedMemoryInterface {
    * Check tags for all memory in the specified range.
    */
   public checkTagsRange(tag: TypeTag, startOffset: number, size: number) {
+    if (startOffset + size > TaggedMemory.MAX_MEMORY_SIZE) {
+      throw new MemorySliceOutOfRangeError(startOffset, size);
+    }
+
     for (let offset = startOffset; offset < startOffset + size; offset++) {
       this.checkTag(tag, offset);
     }

package/src/public/avm/avm_simulator.ts

@@ -1,6 +1,7 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
+import type { PublicSimulatorConfig } from '@aztec/stdlib/avm';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { GlobalVariables } from '@aztec/stdlib/tx';
 
@@ -14,6 +15,7 @@ import { AvmExecutionEnvironment } from './avm_execution_environment.js';
 import type { Gas } from './avm_gas.js';
 import { AvmMachineState } from './avm_machine_state.js';
 import type { AvmSimulatorInterface } from './avm_simulator_interface.js';
+import { type CallData, ReturnDataArray } from './calldata.js';
 import { AvmRevertReason, InvalidProgramCounterError } from './errors.js';
 import type { Instruction } from './opcodes/instruction.js';
 import { revertReasonFromExceptionalHalt, revertReasonFromExplicitRevert } from './revert_reason.js';
@@ -48,7 +50,7 @@ export class AvmSimulator implements AvmSimulatorInterface {
     // This will be used by the CALL opcode to create a new simulator. It is required to
     // avoid a dependency cycle.
     context.provideSimulator = AvmSimulator.build;
-    this.log = createLogger(`simulator:avm(calldata[0]: ${context.environment.calldata[0]})`);
+    this.log = createLogger(`simulator:avm(calldata[0]: ${context.environment.calldata.read(0)})`);
     // Turn on tallying if explicitly enabled or if trace logging
     if (enableTallying || this.log.isLevelEnabled('trace')) {
       this.tallyPrintFunction = this.printOpcodeTallies;
@@ -73,10 +75,9 @@ export class AvmSimulator implements AvmSimulatorInterface {
     transactionFee: Fr,
     globals: GlobalVariables,
     isStaticCall: boolean,
-    calldata: Fr[],
+    calldata: CallData,
     allocatedGas: Gas,
-    clientInitiatedSimulation: boolean = false,
-    maxDebugLogMemoryReads?: number,
+    config: PublicSimulatorConfig,
   ) {
     const avmExecutionEnv = new AvmExecutionEnvironment(
       address,
@@ -86,8 +87,7 @@ export class AvmSimulator implements AvmSimulatorInterface {
       globals,
       isStaticCall,
       calldata,
-      clientInitiatedSimulation,
-      maxDebugLogMemoryReads,
+      config,
     );
 
     const avmMachineState = new AvmMachineState(allocatedGas);
@@ -105,7 +105,7 @@ export class AvmSimulator implements AvmSimulatorInterface {
 
     if (!bytecode) {
       return await this.handleFailureToRetrieveBytecode(
-        `No bytecode found, or limit encountered for max calls to unique contract class IDs. Contract address: ${this.context.environment.address}. Reverting...`,
+        `No bytecode found. Contract is not deployed, or limit encountered for max calls to unique contract class IDs. Contract address: ${this.context.environment.address}. Reverting...`,
       );
     }
 
@@ -178,13 +178,15 @@ export class AvmSimulator implements AvmSimulatorInterface {
 
         if (machineState.pc >= bytecode.length) {
           this.log.warn('Passed end of program');
-          throw new InvalidProgramCounterError(machineState.pc, /*max=*/ bytecode.length);
+          throw new InvalidProgramCounterError(machineState.pc, /*max=*/ bytecode.length - 1);
         }
       }
 
       const output = machineState.getOutput();
       const reverted = machineState.getReverted();
-      const revertReason = reverted ? await revertReasonFromExplicitRevert(output, this.context) : undefined;
+      const revertReason = reverted
+        ? await revertReasonFromExplicitRevert(output.bestEffortReadAll(), this.context)
+        : undefined;
       const results = new AvmContractCallResult(
         reverted,
         output,
@@ -221,7 +223,7 @@ export class AvmSimulator implements AvmSimulatorInterface {
       // Note: "exceptional halts" cannot return data, hence [].
       const results = new AvmContractCallResult(
         /*reverted=*/ true,
-        /*output=*/ [],
+        /*output=*/ new ReturnDataArray([]),
         noGasLeft,
         revertReason,
         machineState.instrCounter,
@@ -236,19 +238,22 @@ export class AvmSimulator implements AvmSimulatorInterface {
 
   private async handleFailureToRetrieveBytecode(message: string): Promise<AvmContractCallResult> {
     // revert, consuming all gas
-    const fnName = await this.context.persistableState.getPublicFunctionDebugName(this.context.environment);
+    const { functionSelector, functionName } = await this.context.persistableState.getPublicFunctionSelectorAndName(
+      this.context.environment,
+    );
     const revertReason = new AvmRevertReason(
       message,
       /*failingFunction=*/ {
         contractAddress: this.context.environment.address,
-        functionName: fnName,
+        functionSelector,
+        functionName,
       },
       /*noirCallStack=*/ [],
     );
     this.log.warn(message);
     return new AvmContractCallResult(
       /*reverted=*/ true,
-      /*output=*/ [],
+      /*output=*/ new ReturnDataArray([]),
       /*gasLeft=*/ { l2Gas: 0, daGas: 0 }, // consumes all allocated gas
       revertReason,
     );

package/src/public/avm/calldata.ts

@@ -0,0 +1,100 @@
+import type { Fr } from '@aztec/foundation/schemas';
+
+import { TaggedMemory } from './avm_memory_types.js';
+
+// Allow reading up to 300 kB of return data when unspecified.
+const DEFAULT_BEST_EFFORT_READ_CAP = 10000;
+
+export interface LazyReader {
+  bestEffortReadAll(readCap?: number): Fr[];
+  readAll(): Fr[];
+  read(idx: number): Fr | undefined;
+  slice(start: number, end: number): Fr[];
+  length(): number;
+}
+
+export class LazyReaderMemory implements LazyReader {
+  constructor(
+    private memory: TaggedMemory,
+    private offset: number,
+    private size: number,
+  ) {}
+
+  public bestEffortReadAll(readCap = DEFAULT_BEST_EFFORT_READ_CAP): Fr[] {
+    const size = Math.min(this.size, readCap, TaggedMemory.MAX_MEMORY_SIZE - this.offset);
+    return this.memory.getSlice(this.offset, size).map(word => word.toFr());
+  }
+
+  public read(idx: number): Fr | undefined {
+    if (idx >= this.size) {
+      return undefined;
+    }
+    return this.memory.get(this.offset + idx).toFr();
+  }
+
+  public slice(start: number, end: number): Fr[] {
+    const clampedEnd = Math.min(end, this.size);
+    const length = Math.max(0, clampedEnd - start);
+    return this.memory.getSlice(this.offset + start, length).map(word => word.toFr());
+  }
+
+  public readAll(): Fr[] {
+    return this.memory.getSlice(this.offset, this.size).map(word => word.toFr());
+  }
+
+  public length(): number {
+    return this.size;
+  }
+}
+
+export class LazyReaderArray implements LazyReader {
+  constructor(private array: Fr[]) {}
+
+  public bestEffortReadAll(readCap = DEFAULT_BEST_EFFORT_READ_CAP): Fr[] {
+    return this.array.slice(0, readCap);
+  }
+
+  public read(idx: number): Fr | undefined {
+    return this.array[idx];
+  }
+
+  public slice(start: number, end: number): Fr[] {
+    return this.array.slice(start, end);
+  }
+
+  public readAll(): Fr[] {
+    return this.array;
+  }
+
+  public length(): number {
+    return this.array.length;
+  }
+}
+
+// Compile time branding to avoid swapping CallData and ReturnData by accident.
+declare const CallDataBrand: unique symbol;
+declare const ReturnDataBrand: unique symbol;
+
+export type CallData = LazyReader & {
+  readonly [CallDataBrand]: true;
+};
+
+export type ReturnData = LazyReader & {
+  readonly [ReturnDataBrand]: true;
+};
+
+export class CallDataArray extends LazyReaderArray implements CallData {
+  declare readonly [CallDataBrand]: true;
+}
+
+export class CallDataMemory extends LazyReaderMemory implements CallData {
+  declare readonly [CallDataBrand]: true;
+}
+
+export class ReturnDataArray extends LazyReaderArray implements ReturnData {
+  declare readonly [ReturnDataBrand]: true;
+}
+
+export class ReturnDataMemory extends LazyReaderMemory implements ReturnData {
+  declare readonly [ReturnDataBrand]: true;
+}

package/src/public/avm/errors.ts

@@ -1,4 +1,4 @@
-import type { Point } from '@aztec/foundation/fields';
+import type { Point } from '@aztec/foundation/curves/grumpkin';
 import type { FailingFunction, NoirCallStack } from '@aztec/stdlib/errors';
 
 import { ExecutionError } from '../../common/errors.js';
@@ -58,7 +58,7 @@ export class AvmParsingError extends AvmExecutionError {
  */
 export class InvalidTagValueError extends AvmExecutionError {
   constructor(tagValue: number) {
-    super(`Tag value ${tagValue} is invalid.`);
+    super(`Tag check failed: Tag value ${tagValue} is invalid.`);
     this.name = 'InvalidTagValueError';
   }
 }
@@ -77,6 +77,12 @@ export class InstructionExecutionError extends AvmExecutionError {
  * Error thrown on failed AVM memory tag check.
  */
 export class TagCheckError extends AvmExecutionError {
+  public static forBaseAddress(gotTag: string): TagCheckError {
+    return new TagCheckError(`Base address (mem[0]) is not a valid address (has tag ${gotTag})`);
+  }
+  public static forIndirectAddress(address: number, gotTag: string): TagCheckError {
+    return new TagCheckError(`Address after indirection is not a valid address (address ${address} has tag ${gotTag})`);
+  }
   public static forOffset(offset: number, gotTag: string, expectedTag: string): TagCheckError {
     return new TagCheckError(`Tag mismatch at offset ${offset}, got ${gotTag}, expected ${expectedTag}`);
   }
@@ -97,7 +103,7 @@ export class TagCheckError extends AvmExecutionError {
  */
 export class RelativeAddressOutOfRangeError extends AvmExecutionError {
   constructor(baseAddr: number, relOffset: number) {
-    super(`Address out of range. Base address ${baseAddr}, relative offset ${relOffset}`);
+    super(`Relative address out of range. Base address ${baseAddr}, relative offset ${relOffset}`);
     this.name = 'RelativeAddressOutOfRangeError';
   }
 }
@@ -161,3 +167,11 @@ export class AvmRevertReason extends ExecutionError {
     super(message, failingFunction, noirCallStack, options);
   }
 }
+
+/**
+ * Helper to annotate errors occurring during instruction fetching.
+ */
+export function duringInstrFetch(error: Error, pc: number) {
+  error.message = `Instruction fetching error at pc ${pc}: ${error.message}`;
+  return error;
+}