@aztec/simulator 0.22.0 → 0.24.0

package/src/acvm/oracle/oracle.ts

@@ -0,0 +1,332 @@
+import { MerkleTreeId, UnencryptedL2Log } from '@aztec/circuit-types';
+import { RETURN_VALUES_LENGTH } from '@aztec/circuits.js';
+import { EventSelector, FunctionSelector } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr, Point } from '@aztec/foundation/fields';
+import { createDebugLogger } from '@aztec/foundation/log';
+
+import { ACVMField } from '../acvm_types.js';
+import { frToNumber, fromACVMField } from '../deserialize.js';
+import { toACVMField, toAcvmEnqueuePublicFunctionResult } from '../serialize.js';
+import { acvmFieldMessageToString, oracleDebugCallToFormattedStr } from './debug.js';
+import { TypedOracle } from './typed_oracle.js';
+
+/**
+ * A data source that has all the apis required by Aztec.nr.
+ */
+export class Oracle {
+  constructor(private typedOracle: TypedOracle, private log = createDebugLogger('aztec:simulator:oracle')) {}
+
+  getRandomField(): ACVMField {
+    const val = this.typedOracle.getRandomField();
+    return toACVMField(val);
+  }
+
+  async packArguments(args: ACVMField[]): Promise<ACVMField> {
+    const packed = await this.typedOracle.packArguments(args.map(fromACVMField));
+    return toACVMField(packed);
+  }
+
+  async getNullifierKeyPair([accountAddress]: ACVMField[]): Promise<ACVMField[]> {
+    const { publicKey, secretKey } = await this.typedOracle.getNullifierKeyPair(fromACVMField(accountAddress));
+    return [
+      toACVMField(publicKey.x),
+      toACVMField(publicKey.y),
+      toACVMField(secretKey.high),
+      toACVMField(secretKey.low),
+    ];
+  }
+
+  async getPublicKeyAndPartialAddress([address]: ACVMField[]) {
+    const { publicKey, partialAddress } = await this.typedOracle.getCompleteAddress(
+      AztecAddress.fromField(fromACVMField(address)),
+    );
+    return [publicKey.x, publicKey.y, partialAddress].map(toACVMField);
+  }
+
+  async getMembershipWitness(
+    [blockNumber]: ACVMField[],
+    [treeId]: ACVMField[],
+    [leafValue]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+    const parsedTreeId = frToNumber(fromACVMField(treeId));
+    const parsedLeafValue = fromACVMField(leafValue);
+
+    const witness = await this.typedOracle.getMembershipWitness(parsedBlockNumber, parsedTreeId, parsedLeafValue);
+    if (!witness) {
+      throw new Error(
+        `Leaf ${leafValue} not found in the tree ${MerkleTreeId[parsedTreeId]} at block ${parsedBlockNumber}.`,
+      );
+    }
+    return witness.map(toACVMField);
+  }
+
+  async getSiblingPath(
+    [blockNumber]: ACVMField[],
+    [treeId]: ACVMField[],
+    [leafIndex]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+    const parsedTreeId = frToNumber(fromACVMField(treeId));
+    const parsedLeafIndex = fromACVMField(leafIndex);
+
+    const path = await this.typedOracle.getSiblingPath(parsedBlockNumber, parsedTreeId, parsedLeafIndex);
+    return path.map(toACVMField);
+  }
+
+  async getNullifierMembershipWitness(
+    [blockNumber]: ACVMField[],
+    [nullifier]: ACVMField[], // nullifier, we try to find the witness for (to prove inclusion)
+  ): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+    const parsedNullifier = fromACVMField(nullifier);
+
+    const witness = await this.typedOracle.getNullifierMembershipWitness(parsedBlockNumber, parsedNullifier);
+    if (!witness) {
+      throw new Error(
+        `Low nullifier witness not found for nullifier ${parsedNullifier} at block ${parsedBlockNumber}.`,
+      );
+    }
+    return witness.toFields().map(toACVMField);
+  }
+
+  async getLowNullifierMembershipWitness(
+    [blockNumber]: ACVMField[],
+    [nullifier]: ACVMField[], // nullifier, we try to find the low nullifier witness for (to prove non-inclusion)
+  ): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+    const parsedNullifier = fromACVMField(nullifier);
+
+    const witness = await this.typedOracle.getLowNullifierMembershipWitness(parsedBlockNumber, parsedNullifier);
+    if (!witness) {
+      throw new Error(
+        `Low nullifier witness not found for nullifier ${parsedNullifier} at block ${parsedBlockNumber}.`,
+      );
+    }
+    return witness.toFields().map(toACVMField);
+  }
+
+  async getPublicDataTreeWitness([blockNumber]: ACVMField[], [leafSlot]: ACVMField[]): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+    const parsedLeafSlot = fromACVMField(leafSlot);
+
+    const witness = await this.typedOracle.getPublicDataTreeWitness(parsedBlockNumber, parsedLeafSlot);
+    if (!witness) {
+      throw new Error(`Public data witness not found for slot ${parsedLeafSlot} at block ${parsedBlockNumber}.`);
+    }
+    return witness.toFields().map(toACVMField);
+  }
+
+  async getHeader([blockNumber]: ACVMField[]): Promise<ACVMField[]> {
+    const parsedBlockNumber = frToNumber(fromACVMField(blockNumber));
+
+    const header = await this.typedOracle.getHeader(parsedBlockNumber);
+    if (!header) {
+      throw new Error(`Block header not found for block ${parsedBlockNumber}.`);
+    }
+    return header.toFields().map(toACVMField);
+  }
+
+  async getAuthWitness([messageHash]: ACVMField[]): Promise<ACVMField[]> {
+    const messageHashField = fromACVMField(messageHash);
+    const witness = await this.typedOracle.getAuthWitness(messageHashField);
+    if (!witness) {
+      throw new Error(`Authorization not found for message hash ${messageHashField}`);
+    }
+    return witness.map(toACVMField);
+  }
+
+  async popCapsule(): Promise<ACVMField[]> {
+    const capsule = await this.typedOracle.popCapsule();
+    if (!capsule) {
+      throw new Error(`No capsules available`);
+    }
+    return capsule.map(toACVMField);
+  }
+
+  async getNotes(
+    [storageSlot]: ACVMField[],
+    [numSelects]: ACVMField[],
+    selectBy: ACVMField[],
+    selectValues: ACVMField[],
+    selectComparators: ACVMField[],
+    sortBy: ACVMField[],
+    sortOrder: ACVMField[],
+    [limit]: ACVMField[],
+    [offset]: ACVMField[],
+    [status]: ACVMField[],
+    [returnSize]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const noteDatas = await this.typedOracle.getNotes(
+      fromACVMField(storageSlot),
+      +numSelects,
+      selectBy.map(s => +s),
+      selectValues.map(fromACVMField),
+      selectComparators.map(s => +s),
+      sortBy.map(s => +s),
+      sortOrder.map(s => +s),
+      +limit,
+      +offset,
+      +status,
+    );
+
+    const noteLength = noteDatas?.[0]?.note.items.length ?? 0;
+    if (!noteDatas.every(({ note }) => noteLength === note.items.length)) {
+      throw new Error('Notes should all be the same length.');
+    }
+
+    const contractAddress = noteDatas[0]?.contractAddress ?? Fr.ZERO;
+
+    // Values indicates whether the note is settled or transient.
+    const noteTypes = {
+      isSettled: new Fr(0),
+      isTransient: new Fr(1),
+    };
+    const flattenData = noteDatas.flatMap(({ nonce, note, index }) => [
+      nonce,
+      index === undefined ? noteTypes.isTransient : noteTypes.isSettled,
+      ...note.items,
+    ]);
+
+    const returnFieldSize = +returnSize;
+    const returnData = [noteDatas.length, contractAddress, ...flattenData].map(v => toACVMField(v));
+    if (returnData.length > returnFieldSize) {
+      throw new Error(`Return data size too big. Maximum ${returnFieldSize} fields. Got ${flattenData.length}.`);
+    }
+
+    const paddedZeros = Array(returnFieldSize - returnData.length).fill(toACVMField(0));
+    return returnData.concat(paddedZeros);
+  }
+
+  notifyCreatedNote(
+    [storageSlot]: ACVMField[],
+    [noteTypeId]: ACVMField[],
+    note: ACVMField[],
+    [innerNoteHash]: ACVMField[],
+  ): ACVMField {
+    this.typedOracle.notifyCreatedNote(
+      fromACVMField(storageSlot),
+      fromACVMField(noteTypeId),
+      note.map(fromACVMField),
+      fromACVMField(innerNoteHash),
+    );
+    return toACVMField(0);
+  }
+
+  async notifyNullifiedNote([innerNullifier]: ACVMField[], [innerNoteHash]: ACVMField[]): Promise<ACVMField> {
+    await this.typedOracle.notifyNullifiedNote(fromACVMField(innerNullifier), fromACVMField(innerNoteHash));
+    return toACVMField(0);
+  }
+
+  async checkNullifierExists([innerNullifier]: ACVMField[]): Promise<ACVMField> {
+    const exists = await this.typedOracle.checkNullifierExists(fromACVMField(innerNullifier));
+    return toACVMField(exists);
+  }
+
+  async getL1ToL2Message([msgKey]: ACVMField[]): Promise<ACVMField[]> {
+    const message = await this.typedOracle.getL1ToL2Message(fromACVMField(msgKey));
+    return message.toFields().map(toACVMField);
+  }
+
+  async getPortalContractAddress([aztecAddress]: ACVMField[]): Promise<ACVMField> {
+    const contractAddress = AztecAddress.fromString(aztecAddress);
+    const portalContactAddress = await this.typedOracle.getPortalContractAddress(contractAddress);
+    return toACVMField(portalContactAddress);
+  }
+
+  async storageRead([startStorageSlot]: ACVMField[], [numberOfElements]: ACVMField[]): Promise<ACVMField[]> {
+    const values = await this.typedOracle.storageRead(fromACVMField(startStorageSlot), +numberOfElements);
+    return values.map(toACVMField);
+  }
+
+  async storageWrite([startStorageSlot]: ACVMField[], values: ACVMField[]): Promise<ACVMField[]> {
+    const newValues = await this.typedOracle.storageWrite(fromACVMField(startStorageSlot), values.map(fromACVMField));
+    return newValues.map(toACVMField);
+  }
+
+  emitEncryptedLog(
+    [contractAddress]: ACVMField[],
+    [storageSlot]: ACVMField[],
+    [noteTypeId]: ACVMField[],
+    [publicKeyX]: ACVMField[],
+    [publicKeyY]: ACVMField[],
+    log: ACVMField[],
+  ): ACVMField {
+    const publicKey = new Point(fromACVMField(publicKeyX), fromACVMField(publicKeyY));
+    this.typedOracle.emitEncryptedLog(
+      AztecAddress.fromString(contractAddress),
+      Fr.fromString(storageSlot),
+      Fr.fromString(noteTypeId),
+      publicKey,
+      log.map(fromACVMField),
+    );
+    return toACVMField(0);
+  }
+
+  emitUnencryptedLog([contractAddress]: ACVMField[], [eventSelector]: ACVMField[], message: ACVMField[]): ACVMField {
+    const logPayload = Buffer.concat(message.map(fromACVMField).map(f => f.toBuffer()));
+    const log = new UnencryptedL2Log(
+      AztecAddress.fromString(contractAddress),
+      EventSelector.fromField(fromACVMField(eventSelector)),
+      logPayload,
+    );
+
+    this.typedOracle.emitUnencryptedLog(log);
+    return toACVMField(0);
+  }
+
+  debugLog(...args: ACVMField[][]): ACVMField {
+    this.log(oracleDebugCallToFormattedStr(args));
+    return toACVMField(0);
+  }
+
+  debugLogWithPrefix(arg0: ACVMField[], ...args: ACVMField[][]): ACVMField {
+    this.log(`${acvmFieldMessageToString(arg0)}: ${oracleDebugCallToFormattedStr(args)}`);
+    return toACVMField(0);
+  }
+
+  async callPrivateFunction(
+    [contractAddress]: ACVMField[],
+    [functionSelector]: ACVMField[],
+    [argsHash]: ACVMField[],
+    [sideffectCounter]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const callStackItem = await this.typedOracle.callPrivateFunction(
+      AztecAddress.fromField(fromACVMField(contractAddress)),
+      FunctionSelector.fromField(fromACVMField(functionSelector)),
+      fromACVMField(argsHash),
+      frToNumber(fromACVMField(sideffectCounter)),
+    );
+    return callStackItem.toFields().map(toACVMField);
+  }
+
+  async callPublicFunction(
+    [contractAddress]: ACVMField[],
+    [functionSelector]: ACVMField[],
+    [argsHash]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const returnValues = await this.typedOracle.callPublicFunction(
+      AztecAddress.fromField(fromACVMField(contractAddress)),
+      FunctionSelector.fromField(fromACVMField(functionSelector)),
+      fromACVMField(argsHash),
+    );
+    return padArrayEnd(returnValues, Fr.ZERO, RETURN_VALUES_LENGTH).map(toACVMField);
+  }
+
+  async enqueuePublicFunctionCall(
+    [contractAddress]: ACVMField[],
+    [functionSelector]: ACVMField[],
+    [argsHash]: ACVMField[],
+    [sideffectCounter]: ACVMField[],
+  ) {
+    const enqueuedRequest = await this.typedOracle.enqueuePublicFunctionCall(
+      AztecAddress.fromString(contractAddress),
+      FunctionSelector.fromField(fromACVMField(functionSelector)),
+      fromACVMField(argsHash),
+      frToNumber(fromACVMField(sideffectCounter)),
+    );
+    return toAcvmEnqueuePublicFunctionResult(enqueuedRequest);
+  }
+}

package/src/acvm/oracle/typed_oracle.ts

@@ -0,0 +1,217 @@
+import {
+  CompleteAddress,
+  L1ToL2Message,
+  MerkleTreeId,
+  Note,
+  NoteStatus,
+  NullifierMembershipWitness,
+  PublicDataWitness,
+  PublicKey,
+  SiblingPath,
+  UnencryptedL2Log,
+} from '@aztec/circuit-types';
+import {
+  GrumpkinPrivateKey,
+  Header,
+  L1_TO_L2_MSG_TREE_HEIGHT,
+  PrivateCallStackItem,
+  PublicCallRequest,
+} from '@aztec/circuits.js';
+import { FunctionSelector } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * A pair of public key and secret key.
+ */
+export interface KeyPair {
+  /**
+   * Public key.
+   */
+  publicKey: PublicKey;
+  /**
+   * Secret Key.
+   */
+  secretKey: GrumpkinPrivateKey;
+}
+
+/**
+ * Information about a note needed during execution.
+ */
+export interface NoteData {
+  /** The note. */
+  note: Note;
+  /** The contract address of the note. */
+  contractAddress: AztecAddress;
+  /** The storage slot of the note. */
+  storageSlot: Fr;
+  /** The nonce of the note. */
+  nonce: Fr;
+  /** The inner note hash of the note. */
+  innerNoteHash: Fr;
+  /** The corresponding nullifier of the note. Undefined for pending notes. */
+  siloedNullifier?: Fr;
+  /** The note's leaf index in the note hash tree. Undefined for pending notes. */
+  index?: bigint;
+}
+
+export class MessageLoadOracleInputs<N extends number> {
+  constructor(
+    /** The message. */
+    public message: L1ToL2Message,
+    /** The index of the message commitment in the merkle tree. */
+    public index: bigint,
+    /** The path in the merkle tree to the message. */
+    public siblingPath: SiblingPath<N>,
+  ) {}
+
+  toFields(): Fr[] {
+    return [...this.message.toFields(), new Fr(this.index), ...this.siblingPath.toFields()];
+  }
+}
+
+/**
+ * Oracle with typed parameters and typed return values.
+ * Methods that require read and/or write will have to be implemented based on the context (public, private, or view)
+ * and are unavailable by default.
+ */
+export abstract class TypedOracle {
+  getRandomField(): Fr {
+    return Fr.random();
+  }
+
+  packArguments(_args: Fr[]): Promise<Fr> {
+    throw new Error('Not available.');
+  }
+
+  getNullifierKeyPair(_accountAddress: AztecAddress): Promise<KeyPair> {
+    throw new Error('Not available.');
+  }
+
+  getPublicKeyAndPartialAddress(_address: AztecAddress): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getMembershipWitness(_blockNumber: number, _treeId: MerkleTreeId, _leafValue: Fr): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getSiblingPath(_blockNumber: number, _treeId: MerkleTreeId, _leafIndex: Fr): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  getNullifierMembershipWitness(_blockNumber: number, _nullifier: Fr): Promise<NullifierMembershipWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getPublicDataTreeWitness(_blockNumber: number, _leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getLowNullifierMembershipWitness(
+    _blockNumber: number,
+    _nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getHeader(_blockNumber: number): Promise<Header | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getCompleteAddress(_address: AztecAddress): Promise<CompleteAddress> {
+    throw new Error('Not available.');
+  }
+
+  getAuthWitness(_messageHash: Fr): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  popCapsule(): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  getNotes(
+    _storageSlot: Fr,
+    _numSelects: number,
+    _selectBy: number[],
+    _selectValues: Fr[],
+    _selectComparators: number[],
+    _sortBy: number[],
+    _sortOrder: number[],
+    _limit: number,
+    _offset: number,
+    _status: NoteStatus,
+  ): Promise<NoteData[]> {
+    throw new Error('Not available.');
+  }
+
+  notifyCreatedNote(_storageSlot: Fr, _noteTypeId: Fr, _note: Fr[], _innerNoteHash: Fr): void {
+    throw new Error('Not available.');
+  }
+
+  notifyNullifiedNote(_innerNullifier: Fr, _innerNoteHash: Fr): Promise<void> {
+    throw new Error('Not available.');
+  }
+
+  checkNullifierExists(_innerNullifier: Fr): Promise<boolean> {
+    throw new Error('Not available.');
+  }
+
+  getL1ToL2Message(_msgKey: Fr): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>> {
+    throw new Error('Not available.');
+  }
+
+  getPortalContractAddress(_contractAddress: AztecAddress): Promise<EthAddress> {
+    throw new Error('Not available.');
+  }
+
+  storageRead(_startStorageSlot: Fr, _numberOfElements: number): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  storageWrite(_startStorageSlot: Fr, _values: Fr[]): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  emitEncryptedLog(
+    _contractAddress: AztecAddress,
+    _storageSlot: Fr,
+    _noteTypeId: Fr,
+    _publicKey: PublicKey,
+    _log: Fr[],
+  ): void {
+    throw new Error('Not available.');
+  }
+
+  emitUnencryptedLog(_log: UnencryptedL2Log): void {
+    throw new Error('Not available.');
+  }
+
+  callPrivateFunction(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+    _sideffectCounter: number,
+  ): Promise<PrivateCallStackItem> {
+    throw new Error('Not available.');
+  }
+
+  callPublicFunction(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+  ): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  enqueuePublicFunctionCall(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+    _sideffectCounter: number,
+  ): Promise<PublicCallRequest> {
+    throw new Error('Not available.');
+  }
+}

package/src/acvm/serialize.ts

@@ -0,0 +1,75 @@
+import { PublicCallRequest } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { ACVMField } from './acvm_types.js';
+
+/**
+ * Adapts the buffer to the field size.
+ * @param originalBuf - The buffer to adapt.
+ * @returns The adapted buffer.
+ */
+function adaptBufferSize(originalBuf: Buffer) {
+  const buffer = Buffer.alloc(Fr.SIZE_IN_BYTES);
+  if (originalBuf.length > buffer.length) {
+    throw new Error('Buffer does not fit in field');
+  }
+  originalBuf.copy(buffer, buffer.length - originalBuf.length);
+  return buffer;
+}
+
+/**
+ * Converts a value to an ACVM field.
+ * @param value - The value to convert.
+ * @returns The ACVM field.
+ */
+export function toACVMField(
+  value: AztecAddress | EthAddress | Fr | Buffer | boolean | number | bigint | ACVMField,
+): ACVMField {
+  let buffer;
+  if (Buffer.isBuffer(value)) {
+    buffer = value;
+  } else if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'bigint') {
+    buffer = new Fr(value).toBuffer();
+  } else if (typeof value === 'string') {
+    buffer = Fr.fromString(value).toBuffer();
+  } else {
+    buffer = value.toBuffer();
+  }
+  return `0x${adaptBufferSize(buffer).toString('hex')}`;
+}
+
+// Utilities to write TS classes to ACVM Field arrays
+// In the order that the ACVM expects them
+
+/**
+ * Converts a public call stack item with the request for executing a public function to
+ * a set of ACVM fields accepted by the enqueue_public_function_call_oracle Aztec.nr function.
+ * Note that only the fields related to the request are serialized: those related to the result
+ * are empty since this is just an execution request, so we don't send them to the circuit.
+ * @param item - The public call stack item to serialize to be passed onto Noir.
+ * @returns The fields expected by the enqueue_public_function_call_oracle Aztec.nr function.
+ * TODO(#4380): Nuke this and replace it with PublicCallRequest.toFields()
+ */
+export function toAcvmEnqueuePublicFunctionResult(item: PublicCallRequest): ACVMField[] {
+  return [
+    item.contractAddress.toField(),
+    ...item.functionData.toFields(),
+    ...item.callContext.toFields(),
+    item.getArgsHash(),
+  ].map(toACVMField);
+}
+
+/**
+ * Inserts a list of ACVM fields to a witness.
+ * @param witnessStartIndex - The index where to start inserting the fields.
+ * @param fields - The fields to insert.
+ * @returns The witness.
+ */
+export function toACVMWitness(witnessStartIndex: number, fields: Parameters<typeof toACVMField>[0][]) {
+  return fields.reduce((witness, field, index) => {
+    witness.set(index + witnessStartIndex, toACVMField(field));
+    return witness;
+  }, new Map<number, ACVMField>());
+}

package/src/avm/avm_context.ts

@@ -0,0 +1,63 @@
+import { AztecAddress } from '@aztec/circuits.js';
+import { Fr } from '@aztec/foundation/fields';
+
+import { AvmExecutionEnvironment } from './avm_execution_environment.js';
+import { AvmMachineState } from './avm_machine_state.js';
+import { AvmWorldStateJournal } from './journal/journal.js';
+
+/**
+ * An execution context includes the information necessary to initiate AVM
+ * execution along with all state maintained by the AVM throughout execution.
+ */
+export class AvmContext {
+  /**
+   * Create a new AVM context
+   * @param worldState - Manages mutable state during execution - (caching, fetching)
+   * @param environment - Contains constant variables provided by the kernel
+   * @param machineState - VM state that is modified on an instruction-by-instruction basis
+   * @returns new AvmContext instance
+   */
+  constructor(
+    public worldState: AvmWorldStateJournal,
+    public environment: AvmExecutionEnvironment,
+    public machineState: AvmMachineState,
+  ) {}
+
+  /**
+   * Prepare a new AVM context that will be ready for an external/nested call
+   * - Fork the world state journal
+   * - Derive a machine state from the current state
+   *   - E.g., gas metering is preserved but pc is reset
+   * - Derive an execution environment from the caller/parent
+   *   - Alter both address and storageAddress
+   *
+   * @param address - The contract instance to initialize a context for
+   * @param calldata - Data/arguments for nested call
+   * @returns new AvmContext instance
+   */
+  public createNestedContractCallContext(address: AztecAddress, calldata: Fr[]): AvmContext {
+    const newExecutionEnvironment = this.environment.deriveEnvironmentForNestedCall(address, calldata);
+    const forkedWorldState = this.worldState.fork();
+    const machineState = AvmMachineState.fromState(this.machineState);
+    return new AvmContext(forkedWorldState, newExecutionEnvironment, machineState);
+  }
+
+  /**
+   * Prepare a new AVM context that will be ready for an external/nested static call
+   * - Fork the world state journal
+   * - Derive a machine state from the current state
+   *   - E.g., gas metering is preserved but pc is reset
+   * - Derive an execution environment from the caller/parent
+   *   - Alter both address and storageAddress
+   *
+   * @param address - The contract instance to initialize a context for
+   * @param calldata - Data/arguments for nested call
+   * @returns new AvmContext instance
+   */
+  public createNestedContractStaticCallContext(address: AztecAddress, calldata: Fr[]): AvmContext {
+    const newExecutionEnvironment = this.environment.deriveEnvironmentForNestedStaticCall(address, calldata);
+    const forkedWorldState = this.worldState.fork();
+    const machineState = AvmMachineState.fromState(this.machineState);
+    return new AvmContext(forkedWorldState, newExecutionEnvironment, machineState);
+  }
+}