@aztec/simulator 0.38.0 → 0.39.0

package/src/avm/avm_machine_state.ts

@@ -2,7 +2,6 @@ import { type Fr } from '@aztec/circuits.js';
 
 import { type Gas, GasDimensions } from './avm_gas.js';
 import { TaggedMemory } from './avm_memory_types.js';
-import { AvmContractCallResults } from './avm_message_call_result.js';
 import { OutOfGasError } from './errors.js';
 
 /**
@@ -36,7 +35,7 @@ export class AvmMachineState {
    * Signals that execution should end.
    * AvmContext execution continues executing instructions until the machine state signals "halted"
    */
-  public halted: boolean = false;
+  private halted: boolean = false;
   /** 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 */
@@ -118,34 +117,24 @@ export class AvmMachineState {
     this.output = output;
   }
 
+  public getHalted(): boolean {
+    return this.halted;
+  }
+
+  public getReverted(): boolean {
+    return this.reverted;
+  }
+
+  public getOutput(): Fr[] {
+    return this.output;
+  }
+
   /**
    * Flag an exceptional halt. Clears gas left and sets the reverted flag. No output data.
    */
-  protected exceptionalHalt() {
+  private exceptionalHalt() {
     GasDimensions.forEach(dimension => (this[`${dimension}Left`] = 0));
     this.reverted = true;
     this.halted = true;
   }
-
-  /**
-   * Get a summary of execution results for a halted machine state
-   * @returns summary of execution results
-   */
-  public getResults(): AvmContractCallResults {
-    if (!this.halted) {
-      throw new Error('Execution results are not ready! Execution is ongoing.');
-    }
-    let revertReason = undefined;
-    if (this.reverted && this.output.length > 0) {
-      try {
-        // Try to interpret the output as a text string.
-        revertReason = new Error(
-          'Reverted with output: ' + String.fromCharCode(...this.output.slice(1).map(fr => fr.toNumber())),
-        );
-      } catch (e) {
-        revertReason = new Error('Reverted with non-string output');
-      }
-    }
-    return new AvmContractCallResults(this.reverted, this.output, revertReason);
-  }
 }

package/src/avm/avm_message_call_result.ts

@@ -1,24 +1,13 @@
 import { type Fr } from '@aztec/foundation/fields';
 
+import { type AvmRevertReason } from './errors.js';
+
 /**
  * Results of an contract call's execution in the AVM.
  */
 export class AvmContractCallResults {
-  public readonly reverted: boolean;
-  public readonly output: Fr[];
-
-  /** For exceptional halts */
-  public readonly revertReason: Error | undefined;
-
-  constructor(reverted: boolean, output: Fr[], revertReason?: Error) {
-    this.reverted = reverted;
-    this.output = output;
-    this.revertReason = revertReason;
-  }
+  constructor(public reverted: boolean, public output: Fr[], public revertReason?: AvmRevertReason) {}
 
-  /**
-   * Generate a string representation of call results.
-   */
   toString(): string {
     let resultsStr = `reverted: ${this.reverted}, output: ${this.output}`;
     if (this.revertReason) {

package/src/avm/avm_simulator.ts

@@ -5,7 +5,13 @@ import { strict as assert } from 'assert';
 import { isAvmBytecode } from '../public/transitional_adaptors.js';
 import type { AvmContext } from './avm_context.js';
 import { AvmContractCallResults } from './avm_message_call_result.js';
-import { AvmExecutionError, InvalidProgramCounterError, NoBytecodeForContractError } from './errors.js';
+import {
+  AvmExecutionError,
+  InvalidProgramCounterError,
+  NoBytecodeForContractError,
+  revertReasonFromExceptionalHalt,
+  revertReasonFromExplicitRevert,
+} from './errors.js';
 import type { Instruction } from './opcodes/index.js';
 import { decodeFromBytecode } from './serialization/bytecode_serialization.js';
 
@@ -56,7 +62,7 @@ export class AvmSimulator {
     try {
       // Execute instruction pointed to by the current program counter
       // continuing until the machine state signifies a halt
-      while (!machineState.halted) {
+      while (!machineState.getHalted()) {
         const instruction = instructions[machineState.pc];
         assert(
           !!instruction,
@@ -76,21 +82,25 @@ export class AvmSimulator {
         }
       }
 
-      // Return results for processing by calling context
-      const results = machineState.getResults();
+      const output = machineState.getOutput();
+      const reverted = machineState.getReverted();
+      const revertReason = reverted ? revertReasonFromExplicitRevert(output, this.context) : undefined;
+      const results = new AvmContractCallResults(reverted, output, revertReason);
       this.log.debug(`Context execution results: ${results.toString()}`);
+      // Return results for processing by calling context
       return results;
-    } catch (e) {
-      this.log.verbose('Exceptional halt');
-      if (!(e instanceof AvmExecutionError)) {
-        this.log.verbose(`Unknown error thrown by avm: ${e}`);
-        throw e;
+    } catch (err: any) {
+      this.log.verbose('Exceptional halt (revert by something other than REVERT opcode)');
+      if (!(err instanceof AvmExecutionError)) {
+        this.log.verbose(`Unknown error thrown by AVM: ${err}`);
+        throw err;
       }
 
-      // Return results for processing by calling context
-      // Note: "exceptional halts" cannot return data
-      const results = new AvmContractCallResults(/*reverted=*/ true, /*output=*/ [], /*revertReason=*/ e);
+      const revertReason = revertReasonFromExceptionalHalt(err, this.context);
+      // Note: "exceptional halts" cannot return data, hence []
+      const results = new AvmContractCallResults(/*reverted=*/ true, /*output=*/ [], revertReason);
       this.log.debug(`Context execution results: ${results.toString()}`);
+      // Return results for processing by calling context
       return results;
     }
   }

package/src/avm/errors.ts

@@ -1,12 +1,16 @@
-import { type AztecAddress } from '@aztec/circuits.js';
+import { type FailingFunction, type NoirCallStack } from '@aztec/circuit-types';
+import { type AztecAddress, type Fr } from '@aztec/circuits.js';
+
+import { ExecutionError } from '../common/errors.js';
+import { type AvmContext } from './avm_context.js';
 
 /**
  * Avm-specific errors should derive from this
  */
 export abstract class AvmExecutionError extends Error {
-  constructor(message: string, ...rest: any[]) {
-    super(message, ...rest);
-    this.name = 'AvmInterpreterError';
+  constructor(message: string) {
+    super(message);
+    this.name = 'AvmExecutionError';
   }
 }
 
@@ -63,3 +67,89 @@ export class OutOfGasError extends AvmExecutionError {
     this.name = 'OutOfGasError';
   }
 }
+
+/**
+ * Error thrown to propagate a nested call's revert.
+ * @param message - the error's message
+ * @param nestedError - the revert reason of the nested call
+ */
+export class RethrownError extends AvmExecutionError {
+  constructor(message: string, public nestedError: AvmRevertReason) {
+    super(message);
+    this.name = 'RethrownError';
+  }
+}
+
+/**
+ * Meaningfully named alias for ExecutionError when used in the context of the AVM.
+ * Maintains a recursive structure reflecting the AVM's external callstack/errorstack, where
+ * options.cause is the error that caused this error (if this is not the root-cause itself).
+ */
+export class AvmRevertReason extends ExecutionError {
+  constructor(message: string, failingFunction: FailingFunction, noirCallStack: NoirCallStack, options?: ErrorOptions) {
+    super(message, failingFunction, noirCallStack, options);
+  }
+}
+
+/**
+ * Helper to create a "revert reason" error optionally with a nested error cause.
+ *
+ * @param message - the error message
+ * @param context - the context of the AVM execution used to extract the failingFunction and noirCallStack
+ * @param nestedError - the error that caused this one (if this is not the root-cause itself)
+ */
+function createRevertReason(message: string, context: AvmContext, nestedError?: AvmRevertReason): AvmRevertReason {
+  return new AvmRevertReason(
+    message,
+    /*failingFunction=*/ {
+      contractAddress: context.environment.address,
+      functionSelector: context.environment.temporaryFunctionSelector,
+    },
+    /*noirCallStack=*/ [...context.machineState.internalCallStack, context.machineState.pc].map(pc => `0.${pc}`),
+    /*options=*/ { cause: nestedError },
+  );
+}
+
+/**
+ * Create a "revert reason" error for an exceptional halt,
+ * creating the recursive structure if the halt was a RethrownError.
+ *
+ * @param haltingError - the lower-level error causing the exceptional halt
+ * @param context - the context of the AVM execution used to extract the failingFunction and noirCallStack
+ */
+export function revertReasonFromExceptionalHalt(haltingError: AvmExecutionError, context: AvmContext): AvmRevertReason {
+  // A RethrownError has a nested/child AvmRevertReason
+  const nestedError = haltingError instanceof RethrownError ? haltingError.nestedError : undefined;
+  return createRevertReason(haltingError.message, context, nestedError);
+}
+
+/**
+ * Create a "revert reason" error for an explicit revert (a root cause).
+ *
+ * @param revertData - output data of the explicit REVERT instruction
+ * @param context - the context of the AVM execution used to extract the failingFunction and noirCallStack
+ */
+export function revertReasonFromExplicitRevert(revertData: Fr[], context: AvmContext): AvmRevertReason {
+  const revertMessage = decodeRevertDataAsMessage(revertData);
+  return createRevertReason(revertMessage, context);
+}
+
+/**
+ * Interpret revert data as a message string.
+ *
+ * @param revertData - output data of an explicit REVERT instruction
+ */
+export function decodeRevertDataAsMessage(revertData: Fr[]): string {
+  if (revertData.length === 0) {
+    return 'Assertion failed.';
+  } else {
+    try {
+      // We remove the first element which is the 'error selector'.
+      const revertOutput = revertData.slice(1);
+      // Try to interpret the output as a text string.
+      return 'Assertion failed: ' + String.fromCharCode(...revertOutput.map(fr => fr.toNumber()));
+    } catch (e) {
+      return 'Assertion failed: <cannot interpret as string>';
+    }
+  }
+}

package/src/avm/journal/journal.ts

@@ -119,7 +119,8 @@ export class AvmPersistableStateManager {
       contractStorageUpdateRequests: [],
       unencryptedLogsHashes: [],
       unencryptedLogs: [],
-      unencryptedLogPreimagesLength: new Fr(0),
+      // The length starts at 4 because it will always include the size.
+      unencryptedLogPreimagesLength: new Fr(4),
       allUnencryptedLogs: [],
       nestedExecutions: [],
     };
@@ -285,7 +286,7 @@ export class AvmPersistableStateManager {
   public writeL1Message(recipient: EthAddress | Fr, content: Fr) {
     this.log.debug(`L1Messages(${recipient}) += ${content}.`);
     const recipientAddress = recipient instanceof EthAddress ? recipient : EthAddress.fromField(recipient);
-    const message = new L2ToL1Message(recipientAddress, content);
+    const message = new L2ToL1Message(recipientAddress, content, 0);
     this.newL1Messages.push(message);
 
     // TRANSITIONAL: This should be removed once the kernel handles and entire enqueued call per circuit

package/src/avm/opcodes/conversion.ts

@@ -0,0 +1,59 @@
+import { strict as assert } from 'assert';
+
+import { type AvmContext } from '../avm_context.js';
+import { TypeTag, Uint8 } from '../avm_memory_types.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+
+export class ToRadixLE extends Instruction {
+  static type: string = 'TORADIXLE';
+  static readonly opcode: Opcode = Opcode.TORADIXLE;
+
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8, // Opcode
+    OperandType.UINT8, // Indirect
+    OperandType.UINT32, // src memory address
+    OperandType.UINT32, // dst memory address
+    OperandType.UINT32, // radix (immediate)
+    OperandType.UINT32, // number of limbs (Immediate)
+  ];
+
+  constructor(
+    private indirect: number,
+    private srcOffset: number,
+    private dstOffset: number,
+    private radix: number,
+    private numLimbs: number,
+  ) {
+    assert(radix <= 256, 'Radix cannot be greater than 256');
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory.track(this.type);
+    const [srcOffset, dstOffset] = Addressing.fromWire(this.indirect).resolve([this.srcOffset, this.dstOffset], memory);
+    const memoryOperations = { reads: 1, writes: this.numLimbs, indirect: this.indirect };
+    context.machineState.consumeGas(this.gasCost(memoryOperations));
+
+    // The radix gadget only takes in a Field
+    memory.checkTag(TypeTag.FIELD, srcOffset);
+
+    let value: bigint = memory.get(srcOffset).toBigInt();
+    const radixBN: bigint = BigInt(this.radix);
+    const limbArray = [];
+
+    for (let i = 0; i < this.numLimbs; i++) {
+      const limb = value % radixBN;
+      limbArray.push(limb);
+      value /= radixBN;
+    }
+
+    const res = [...limbArray].map(byte => new Uint8(byte));
+    memory.setSlice(dstOffset, res);
+
+    memory.assert(memoryOperations);
+    context.machineState.incrementPc();
+  }
+}

package/src/avm/opcodes/environment_getters.ts

@@ -1,17 +1,15 @@
-import { type Fr } from '@aztec/circuits.js';
-
 import type { AvmContext } from '../avm_context.js';
 import type { AvmExecutionEnvironment } from '../avm_execution_environment.js';
-import { Field, type MemoryValue } from '../avm_memory_types.js';
+import { Field, type MemoryValue, Uint64 } from '../avm_memory_types.js';
 import { Opcode } from '../serialization/instruction_serialization.js';
 import { GetterInstruction } from './instruction_impl.js';
 
 abstract class EnvironmentGetterInstruction extends GetterInstruction {
   protected getValue(context: AvmContext): MemoryValue {
-    return new Field(this.getEnvironmentValue(context.environment));
+    return this.getEnvironmentValue(context.environment);
   }
 
-  protected abstract getEnvironmentValue(env: AvmExecutionEnvironment): Fr | number | bigint;
+  protected abstract getEnvironmentValue(env: AvmExecutionEnvironment): MemoryValue;
 }
 
 export class Address extends EnvironmentGetterInstruction {
@@ -19,7 +17,7 @@ export class Address extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.ADDRESS;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.address;
+    return new Field(env.address.toField());
   }
 }
 
@@ -28,7 +26,7 @@ export class StorageAddress extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.STORAGEADDRESS;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.storageAddress;
+    return new Field(env.storageAddress.toField());
   }
 }
 
@@ -37,7 +35,7 @@ export class Sender extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.SENDER;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.sender;
+    return new Field(env.sender.toField());
   }
 }
 
@@ -46,7 +44,7 @@ export class FeePerL2Gas extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.FEEPERL2GAS;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.feePerL2Gas;
+    return new Field(env.feePerL2Gas);
   }
 }
 
@@ -55,7 +53,7 @@ export class FeePerDAGas extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.FEEPERDAGAS;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.feePerDaGas;
+    return new Field(env.feePerDaGas);
   }
 }
 
@@ -64,7 +62,7 @@ export class TransactionFee extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.TRANSACTIONFEE;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.transactionFee;
+    return new Field(env.transactionFee);
   }
 }
 
@@ -73,7 +71,7 @@ export class ChainId extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.CHAINID;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.globals.chainId;
+    return new Field(env.globals.chainId);
   }
 }
 
@@ -82,7 +80,7 @@ export class Version extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.VERSION;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.globals.version;
+    return new Field(env.globals.version);
   }
 }
 
@@ -91,7 +89,7 @@ export class BlockNumber extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.BLOCKNUMBER;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.globals.blockNumber;
+    return new Field(env.globals.blockNumber);
   }
 }
 
@@ -100,57 +98,6 @@ export class Timestamp extends EnvironmentGetterInstruction {
   static readonly opcode: Opcode = Opcode.TIMESTAMP;
 
   protected getEnvironmentValue(env: AvmExecutionEnvironment) {
-    return env.globals.timestamp;
+    return new Uint64(env.globals.timestamp.toBigInt());
   }
 }
-
-// export class Coinbase extends EnvironmentGetterInstruction {
-//     static type: string = 'COINBASE';
-//     static numberOfOperands = 1;
-
-//     constructor(private destOffset: number) {
-//         super();
-//     }
-
-//     async execute(machineState: AvmMachineState, _journal: AvmJournal): Promise<void> {
-//         const {coinbase} = machineState.executionEnvironment.globals;
-
-//         machineState.memory.set(this.destOffset, coinbase);
-
-//         this.incrementPc(machineState);
-//     }
-// }
-
-// export class BlockL2GasLimit extends EnvironmentGetterInstruction {
-//     static type: string = 'BLOCKL2GASLIMIT';
-//     static numberOfOperands = 1;
-
-//     constructor(private destOffset: number) {
-//         super();
-//     }
-
-//     async execute(machineState: AvmMachineState, _journal: AvmJournal): Promise<void> {
-//         const {blockL2GasLimit} = machineState.executionEnvironment.globals;
-
-//         machineState.memory.set(this.destOffset, blockL2GasLimit);
-
-//         this.incrementPc(machineState);
-//     }
-// }
-
-// export class BlockDAGasLimit extends EnvironmentGetterInstruction {
-//     static type: string = 'BLOCKDAGASLIMIT';
-//     static numberOfOperands = 1;
-
-//     constructor(private destOffset: number) {
-//         super();
-//     }
-
-//     async execute(machineState: AvmMachineState, _journal: AvmJournal): Promise<void> {
-//         const {blockDAGasLimit} = machineState.executionEnvironment.globals;
-
-//         machineState.memory.set(this.destOffset, blockDAGasLimit);
-
-//         this.incrementPc(machineState);
-//     }
-// }

package/src/avm/opcodes/external_calls.ts

@@ -7,6 +7,7 @@ import { gasLeftToGas, sumGas } from '../avm_gas.js';
 import { Field, Uint8 } from '../avm_memory_types.js';
 import { type AvmContractCallResults } from '../avm_message_call_result.js';
 import { AvmSimulator } from '../avm_simulator.js';
+import { RethrownError } from '../errors.js';
 import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
 import { Addressing } from './addressing_mode.js';
 import { Instruction } from './instruction.js';
@@ -99,6 +100,16 @@ abstract class ExternalCall extends Instruction {
 
     const success = !nestedCallResults.reverted;
 
+    // TRANSITIONAL: We rethrow here so that the MESSAGE gets propagated.
+    //               This means that for now, the caller cannot recover from errors.
+    if (!success) {
+      if (!nestedCallResults.revertReason) {
+        throw new Error('A reverted nested call should be assigned a revert reason in the AVM execution loop');
+      }
+      // The nested call's revertReason will be used to track the stack of error causes down to the root.
+      throw new RethrownError(nestedCallResults.revertReason.message, nestedCallResults.revertReason);
+    }
+
     // We only take as much data as was specified in the return size and pad with zeroes if the return data is smaller
     // than the specified size in order to prevent that memory to be left with garbage
     const returnData = nestedCallResults.output.slice(0, this.retSize);

package/src/avm/serialization/bytecode_serialization.ts

@@ -1,4 +1,5 @@
 import { DAGasLeft, L2GasLeft } from '../opcodes/context_getters.js';
+import { ToRadixLE } from '../opcodes/conversion.js';
 import { Keccak, Pedersen, Poseidon2, Sha256 } from '../opcodes/hashing.js';
 import type { Instruction } from '../opcodes/index.js';
 import {
@@ -136,6 +137,8 @@ const INSTRUCTION_SET = () =>
     [Poseidon2.opcode, Poseidon2],
     [Sha256.opcode, Sha256],
     [Pedersen.opcode, Pedersen],
+    // Conversions
+    [ToRadixLE.opcode, ToRadixLE],
   ]);
 
 interface Serializable {

package/src/avm/serialization/instruction_serialization.ts

@@ -74,6 +74,8 @@ export enum Opcode {
   POSEIDON2,
   SHA256, // temp - may be removed, but alot of contracts rely on it
   PEDERSEN, // temp - may be removed, but alot of contracts rely on it
+  // Conversion
+  TORADIXLE,
 }
 
 // Possible types for an instruction's operand in its wire format. (Keep in sync with CPP code.