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

package/src/avm/avm.ts

@@ -1,35 +1,44 @@
+import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/fields';
 import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
-import { schemas } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
 import { AztecAddress } from '../aztec-address/index.js';
+import { AllContractDeploymentData, ContractDeploymentData } from '../contract/index.js';
+import { SimulationError } from '../errors/simulation_error.js';
 import { computeEffectiveGasFees } from '../fees/transaction_fee.js';
 import { Gas } from '../gas/gas.js';
 import { GasFees } from '../gas/gas_fees.js';
 import { GasSettings } from '../gas/gas_settings.js';
+import { GasUsed } from '../gas/gas_used.js';
 import { PublicKeys } from '../keys/public_keys.js';
+import { DebugLog } from '../logs/debug_log.js';
 import { ScopedL2ToL1Message } from '../messaging/l2_to_l1_message.js';
+import { NullishToUndefined, type ZodFor, schemas } from '../schemas/schemas.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
-import { NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
-import { PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
+import { NullifierLeaf, NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
+import { PublicDataTreeLeaf, PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
 import {
   GlobalVariables,
+  NestedProcessReturnValues,
   ProtocolContracts,
   PublicCallRequestWithCalldata,
   TreeSnapshots,
   type Tx,
 } from '../tx/index.js';
+import { WorldStateRevision } from '../world-state/world_state_revision.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
+import { RevertCode } from './revert_code.js';
 
 ////////////////////////////////////////////////////////////////////////////
 // Hints (contracts)
 ////////////////////////////////////////////////////////////////////////////
 export class AvmContractClassHint {
   constructor(
+    public readonly hintKey: number,
     public readonly classId: Fr,
     public readonly artifactHash: Fr,
     public readonly privateFunctionsRoot: Fr,
@@ -39,20 +48,42 @@ export class AvmContractClassHint {
   static get schema() {
     return z
       .object({
+        hintKey: z.number().int().nonnegative(),
         classId: schemas.Fr,
         artifactHash: schemas.Fr,
         privateFunctionsRoot: schemas.Fr,
         packedBytecode: schemas.Buffer,
       })
       .transform(
-        ({ classId, artifactHash, privateFunctionsRoot, packedBytecode }) =>
-          new AvmContractClassHint(classId, artifactHash, privateFunctionsRoot, packedBytecode),
+        ({ hintKey, classId, artifactHash, privateFunctionsRoot, packedBytecode }) =>
+          new AvmContractClassHint(hintKey, classId, artifactHash, privateFunctionsRoot, packedBytecode),
       );
   }
+
+  /**
+   * Creates an AvmContractClassHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmContractClassHint fields
+   * @returns An AvmContractClassHint instance
+   */
+  static fromPlainObject(obj: any): AvmContractClassHint {
+    if (obj instanceof AvmContractClassHint) {
+      return obj;
+    }
+    return new AvmContractClassHint(
+      obj.hintKey,
+      Fr.fromPlainObject(obj.classId),
+      Fr.fromPlainObject(obj.artifactHash),
+      Fr.fromPlainObject(obj.privateFunctionsRoot),
+      obj.packedBytecode instanceof Buffer ? obj.packedBytecode : Buffer.from(obj.packedBytecode),
+    );
+  }
 }
 
 export class AvmBytecodeCommitmentHint {
   constructor(
+    public readonly hintKey: number,
     public readonly classId: Fr,
     public readonly commitment: Fr,
   ) {}
@@ -60,15 +91,35 @@ export class AvmBytecodeCommitmentHint {
   static get schema() {
     return z
       .object({
+        hintKey: z.number().int().nonnegative(),
         classId: schemas.Fr,
         commitment: schemas.Fr,
       })
-      .transform(({ classId, commitment }) => new AvmBytecodeCommitmentHint(classId, commitment));
+      .transform(({ hintKey, classId, commitment }) => new AvmBytecodeCommitmentHint(hintKey, classId, commitment));
+  }
+
+  /**
+   * Creates an AvmBytecodeCommitmentHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmBytecodeCommitmentHint fields
+   * @returns An AvmBytecodeCommitmentHint instance
+   */
+  static fromPlainObject(obj: any): AvmBytecodeCommitmentHint {
+    if (obj instanceof AvmBytecodeCommitmentHint) {
+      return obj;
+    }
+    return new AvmBytecodeCommitmentHint(
+      obj.hintKey,
+      Fr.fromPlainObject(obj.classId),
+      Fr.fromPlainObject(obj.commitment),
+    );
   }
 }
 
 export class AvmContractInstanceHint {
   constructor(
+    public readonly hintKey: number,
     public readonly address: AztecAddress,
     public readonly salt: Fr,
     public readonly deployer: AztecAddress,
@@ -81,6 +132,7 @@ export class AvmContractInstanceHint {
   static get schema() {
     return z
       .object({
+        hintKey: z.number().int().nonnegative(),
         address: AztecAddress.schema,
         salt: schemas.Fr,
         deployer: AztecAddress.schema,
@@ -91,6 +143,7 @@ export class AvmContractInstanceHint {
       })
       .transform(
         ({
+          hintKey,
           address,
           salt,
           deployer,
@@ -100,6 +153,7 @@ export class AvmContractInstanceHint {
           publicKeys,
         }) =>
           new AvmContractInstanceHint(
+            hintKey,
             address,
             salt,
             deployer,
@@ -110,6 +164,65 @@ export class AvmContractInstanceHint {
           ),
       );
   }
+
+  /**
+   * Creates an AvmContractInstanceHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmContractInstanceHint fields
+   * @returns An AvmContractInstanceHint instance
+   */
+  static fromPlainObject(obj: any): AvmContractInstanceHint {
+    if (obj instanceof AvmContractInstanceHint) {
+      return obj;
+    }
+    return new AvmContractInstanceHint(
+      obj.hintKey,
+      AztecAddress.fromPlainObject(obj.address),
+      Fr.fromPlainObject(obj.salt),
+      AztecAddress.fromPlainObject(obj.deployer),
+      Fr.fromPlainObject(obj.currentContractClassId),
+      Fr.fromPlainObject(obj.originalContractClassId),
+      Fr.fromPlainObject(obj.initializationHash),
+      PublicKeys.fromPlainObject(obj.publicKeys),
+    );
+  }
+}
+
+export class AvmDebugFunctionNameHint {
+  constructor(
+    public readonly address: AztecAddress,
+    public readonly selector: Fr,
+    public readonly name: string,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        address: AztecAddress.schema,
+        selector: schemas.Fr,
+        name: z.string(),
+      })
+      .transform(({ address, selector, name }) => new AvmDebugFunctionNameHint(address, selector, name));
+  }
+
+  /**
+   * Creates an AvmDebugFunctionNameHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmDebugFunctionNameHint fields
+   * @returns An AvmDebugFunctionNameHint instance
+   */
+  static fromPlainObject(obj: any): AvmDebugFunctionNameHint {
+    if (obj instanceof AvmDebugFunctionNameHint) {
+      return obj;
+    }
+    return new AvmDebugFunctionNameHint(
+      AztecAddress.fromPlainObject(obj.address),
+      Fr.fromPlainObject(obj.selector),
+      obj.name,
+    );
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////
@@ -136,6 +249,25 @@ export class AvmGetSiblingPathHint {
       })
       .transform(({ hintKey, treeId, index, path }) => new AvmGetSiblingPathHint(hintKey, treeId, index, path));
   }
+
+  /**
+   * Creates an AvmGetSiblingPathHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmGetSiblingPathHint fields
+   * @returns An AvmGetSiblingPathHint instance
+   */
+  static fromPlainObject(obj: any): AvmGetSiblingPathHint {
+    if (obj instanceof AvmGetSiblingPathHint) {
+      return obj;
+    }
+    return new AvmGetSiblingPathHint(
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+      obj.treeId,
+      typeof obj.index === 'bigint' ? obj.index : BigInt(obj.index),
+      obj.path.map((p: any) => Fr.fromPlainObject(p)),
+    );
+  }
 }
 
 // Hint for MerkleTreeDB.getPreviousValueIndex.
@@ -164,6 +296,26 @@ export class AvmGetPreviousValueIndexHint {
           new AvmGetPreviousValueIndexHint(hintKey, treeId, value, index, alreadyPresent),
       );
   }
+
+  /**
+   * Creates an AvmGetPreviousValueIndexHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmGetPreviousValueIndexHint fields
+   * @returns An AvmGetPreviousValueIndexHint instance
+   */
+  static fromPlainObject(obj: any): AvmGetPreviousValueIndexHint {
+    if (obj instanceof AvmGetPreviousValueIndexHint) {
+      return obj;
+    }
+    return new AvmGetPreviousValueIndexHint(
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+      obj.treeId,
+      Fr.fromPlainObject(obj.value),
+      typeof obj.index === 'bigint' ? obj.index : BigInt(obj.index),
+      obj.alreadyPresent,
+    );
+  }
 }
 
 type IndexedTreeLeafPreimages = NullifierLeafPreimage | PublicDataTreeLeafPreimage;
@@ -191,6 +343,24 @@ function AvmGetLeafPreimageHintFactory(klass: IndexedTreeLeafPreimagesClasses) {
         })
         .transform(({ hintKey, index, leafPreimage }) => new this(hintKey, index, leafPreimage));
     }
+
+    /**
+     * Creates an instance from a plain object without Zod validation.
+     * This method is optimized for performance and skips validation, making it suitable
+     * for deserializing trusted data (e.g., from C++ via MessagePack).
+     * @param obj - Plain object containing hint fields
+     * @returns An instance
+     */
+    static fromPlainObject(obj: any): any {
+      if (obj instanceof this) {
+        return obj;
+      }
+      return new this(
+        AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+        typeof obj.index === 'bigint' ? obj.index : BigInt(obj.index),
+        klass.fromPlainObject(obj.leafPreimage),
+      );
+    }
   };
 }
 
@@ -220,6 +390,25 @@ export class AvmGetLeafValueHint {
       })
       .transform(({ hintKey, treeId, index, value }) => new AvmGetLeafValueHint(hintKey, treeId, index, value));
   }
+
+  /**
+   * Creates an AvmGetLeafValueHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmGetLeafValueHint fields
+   * @returns An AvmGetLeafValueHint instance
+   */
+  static fromPlainObject(obj: any): AvmGetLeafValueHint {
+    if (obj instanceof AvmGetLeafValueHint) {
+      return obj;
+    }
+    return new AvmGetLeafValueHint(
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+      obj.treeId,
+      typeof obj.index === 'bigint' ? obj.index : BigInt(obj.index),
+      Fr.fromPlainObject(obj.value),
+    );
+  }
 }
 
 // Hint for MerkleTreeDB.sequentialInsert.
@@ -269,6 +458,43 @@ function AvmSequentialInsertHintFactory(klass: IndexedTreeLeafPreimagesClasses)
             new this(hintKey, stateAfter, treeId, leaf, lowLeavesWitnessData, insertionWitnessData),
         );
     }
+
+    /**
+     * Creates an instance from a plain object without Zod validation.
+     * This method is optimized for performance and skips validation, making it suitable
+     * for deserializing trusted data (e.g., from C++ via MessagePack).
+     * @param obj - Plain object containing hint fields
+     * @returns An instance
+     */
+    static fromPlainObject(obj: any): any {
+      if (obj instanceof this) {
+        return obj;
+      }
+      // Determine the leaf class based on the klass parameter
+      const LeafClass = klass === PublicDataTreeLeafPreimage ? PublicDataTreeLeaf : NullifierLeaf;
+      return new this(
+        AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+        AppendOnlyTreeSnapshot.fromPlainObject(obj.stateAfter),
+        obj.treeId,
+        LeafClass.fromPlainObject(obj.leaf),
+        {
+          leaf: klass.fromPlainObject(obj.lowLeavesWitnessData.leaf),
+          index:
+            typeof obj.lowLeavesWitnessData.index === 'bigint'
+              ? obj.lowLeavesWitnessData.index
+              : BigInt(obj.lowLeavesWitnessData.index),
+          path: obj.lowLeavesWitnessData.path.map((p: any) => Fr.fromPlainObject(p)),
+        },
+        {
+          leaf: klass.fromPlainObject(obj.insertionWitnessData.leaf),
+          index:
+            typeof obj.insertionWitnessData.index === 'bigint'
+              ? obj.insertionWitnessData.index
+              : BigInt(obj.insertionWitnessData.index),
+          path: obj.insertionWitnessData.path.map((p: any) => Fr.fromPlainObject(p)),
+        },
+      );
+    }
   };
 }
 
@@ -299,6 +525,25 @@ export class AvmAppendLeavesHint {
         ({ hintKey, stateAfter, treeId, leaves }) => new AvmAppendLeavesHint(hintKey, stateAfter, treeId, leaves),
       );
   }
+
+  /**
+   * Creates an AvmAppendLeavesHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmAppendLeavesHint fields
+   * @returns An AvmAppendLeavesHint instance
+   */
+  static fromPlainObject(obj: any): AvmAppendLeavesHint {
+    if (obj instanceof AvmAppendLeavesHint) {
+      return obj;
+    }
+    return new AvmAppendLeavesHint(
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.hintKey),
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.stateAfter),
+      obj.treeId,
+      obj.leaves.map((l: any) => Fr.fromPlainObject(l)),
+    );
+  }
 }
 
 // Hint for checkpoint actions that don't change the state.
@@ -323,6 +568,20 @@ class AvmCheckpointActionNoStateChangeHint {
           new this(actionCounter, oldCheckpointId, newCheckpointId),
       );
   }
+
+  /**
+   * Creates an instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing hint fields
+   * @returns An instance
+   */
+  static fromPlainObject(obj: any): any {
+    if (obj instanceof this) {
+      return obj;
+    }
+    return new this(obj.actionCounter, obj.oldCheckpointId, obj.newCheckpointId);
+  }
 }
 
 // Hint for MerkleTreeDB.createCheckpoint.
@@ -385,8 +644,32 @@ export class AvmRevertCheckpointHint {
           new AvmRevertCheckpointHint(actionCounter, oldCheckpointId, newCheckpointId, stateBefore, stateAfter),
       );
   }
+
+  /**
+   * Creates an AvmRevertCheckpointHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmRevertCheckpointHint fields
+   * @returns An AvmRevertCheckpointHint instance
+   */
+  static fromPlainObject(obj: any): AvmRevertCheckpointHint {
+    if (obj instanceof AvmRevertCheckpointHint) {
+      return obj;
+    }
+    return new AvmRevertCheckpointHint(
+      obj.actionCounter,
+      obj.oldCheckpointId,
+      obj.newCheckpointId,
+      TreeSnapshots.fromPlainObject(obj.stateBefore),
+      TreeSnapshots.fromPlainObject(obj.stateAfter),
+    );
+  }
 }
 
+export class AvmContractDbCreateCheckpointHint extends AvmCheckpointActionNoStateChangeHint {}
+export class AvmContractDbCommitCheckpointHint extends AvmCheckpointActionNoStateChangeHint {}
+export class AvmContractDbRevertCheckpointHint extends AvmCheckpointActionNoStateChangeHint {}
+
 ////////////////////////////////////////////////////////////////////////////
 // Hints (other)
 ////////////////////////////////////////////////////////////////////////////
@@ -395,6 +678,8 @@ export class AvmTxHint {
     public readonly hash: string,
     public readonly gasSettings: GasSettings,
     public readonly effectiveGasFees: GasFees,
+    public readonly nonRevertibleContractDeploymentData: ContractDeploymentData,
+    public readonly revertibleContractDeploymentData: ContractDeploymentData,
     public readonly nonRevertibleAccumulatedData: {
       noteHashes: Fr[];
       nullifiers: Fr[];
@@ -420,6 +705,7 @@ export class AvmTxHint {
     const teardownCallRequest = tx.getTeardownPublicCallRequestWithCalldata();
     const gasSettings = tx.data.constants.txContext.gasSettings;
     const effectiveGasFees = computeEffectiveGasFees(gasFees, gasSettings);
+    const allContractDeploymentData = AllContractDeploymentData.fromTx(tx);
 
     // For informational purposes. Assumed quick because it should be cached.
     const txHash = tx.getTxHash();
@@ -428,6 +714,8 @@ export class AvmTxHint {
       txHash.hash.toString(),
       gasSettings,
       effectiveGasFees,
+      allContractDeploymentData.getNonRevertibleContractDeploymentData(),
+      allContractDeploymentData.getRevertibleContractDeploymentData(),
       {
         noteHashes: tx.data.forPublic!.nonRevertibleAccumulatedData.noteHashes.filter(x => !x.isZero()),
         nullifiers: tx.data.forPublic!.nonRevertibleAccumulatedData.nullifiers.filter(x => !x.isZero()),
@@ -451,6 +739,8 @@ export class AvmTxHint {
       '',
       GasSettings.empty(),
       GasFees.empty(),
+      ContractDeploymentData.empty(),
+      ContractDeploymentData.empty(),
       { noteHashes: [], nullifiers: [], l2ToL1Messages: [] },
       { noteHashes: [], nullifiers: [], l2ToL1Messages: [] },
       [],
@@ -461,12 +751,53 @@ export class AvmTxHint {
     );
   }
 
+  /**
+   * Creates an AvmTxHint from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmTxHint fields
+   * @returns An AvmTxHint instance
+   */
+  static fromPlainObject(obj: any): AvmTxHint {
+    if (obj instanceof AvmTxHint) {
+      return obj;
+    }
+    return new AvmTxHint(
+      obj.hash,
+      GasSettings.fromPlainObject(obj.gasSettings),
+      GasFees.fromPlainObject(obj.effectiveGasFees),
+      ContractDeploymentData.fromPlainObject(obj.nonRevertibleContractDeploymentData),
+      ContractDeploymentData.fromPlainObject(obj.revertibleContractDeploymentData),
+      {
+        noteHashes: obj.nonRevertibleAccumulatedData.noteHashes.map((h: any) => Fr.fromPlainObject(h)),
+        nullifiers: obj.nonRevertibleAccumulatedData.nullifiers.map((n: any) => Fr.fromPlainObject(n)),
+        l2ToL1Messages: obj.nonRevertibleAccumulatedData.l2ToL1Messages.map((m: any) =>
+          ScopedL2ToL1Message.fromPlainObject(m),
+        ),
+      },
+      {
+        noteHashes: obj.revertibleAccumulatedData.noteHashes.map((h: any) => Fr.fromPlainObject(h)),
+        nullifiers: obj.revertibleAccumulatedData.nullifiers.map((n: any) => Fr.fromPlainObject(n)),
+        l2ToL1Messages: obj.revertibleAccumulatedData.l2ToL1Messages.map((m: any) =>
+          ScopedL2ToL1Message.fromPlainObject(m),
+        ),
+      },
+      obj.setupEnqueuedCalls.map((c: any) => PublicCallRequestWithCalldata.fromPlainObject(c)),
+      obj.appLogicEnqueuedCalls.map((c: any) => PublicCallRequestWithCalldata.fromPlainObject(c)),
+      obj.teardownEnqueuedCall ? PublicCallRequestWithCalldata.fromPlainObject(obj.teardownEnqueuedCall) : null,
+      Gas.fromPlainObject(obj.gasUsedByPrivate),
+      AztecAddress.fromPlainObject(obj.feePayer),
+    );
+  }
+
   static get schema() {
     return z
       .object({
         hash: z.string(),
         gasSettings: GasSettings.schema,
         effectiveGasFees: GasFees.schema,
+        nonRevertibleContractDeploymentData: ContractDeploymentData.schema,
+        revertibleContractDeploymentData: ContractDeploymentData.schema,
         nonRevertibleAccumulatedData: z.object({
           noteHashes: schemas.Fr.array(),
           nullifiers: schemas.Fr.array(),
@@ -488,6 +819,8 @@ export class AvmTxHint {
           hash,
           gasSettings,
           effectiveGasFees,
+          nonRevertibleContractDeploymentData,
+          revertibleContractDeploymentData,
           nonRevertibleAccumulatedData,
           revertibleAccumulatedData,
           setupEnqueuedCalls,
@@ -500,6 +833,8 @@ export class AvmTxHint {
             hash,
             gasSettings,
             effectiveGasFees,
+            nonRevertibleContractDeploymentData,
+            revertibleContractDeploymentData,
             nonRevertibleAccumulatedData,
             revertibleAccumulatedData,
             setupEnqueuedCalls,
@@ -522,6 +857,10 @@ export class AvmExecutionHints {
     public readonly contractInstances: AvmContractInstanceHint[] = [],
     public readonly contractClasses: AvmContractClassHint[] = [],
     public readonly bytecodeCommitments: AvmBytecodeCommitmentHint[] = [],
+    public readonly debugFunctionNames: AvmDebugFunctionNameHint[] = [],
+    public readonly contractDbCreateCheckpointHints: AvmContractDbCreateCheckpointHint[] = [],
+    public readonly contractDbCommitCheckpointHints: AvmContractDbCommitCheckpointHint[] = [],
+    public readonly contractDbRevertCheckpointHints: AvmContractDbRevertCheckpointHint[] = [],
     // Merkle DB hints.
     public startingTreeRoots: TreeSnapshots = TreeSnapshots.empty(),
     public readonly getSiblingPathHints: AvmGetSiblingPathHint[] = [],
@@ -537,6 +876,50 @@ export class AvmExecutionHints {
     public readonly revertCheckpointHints: AvmRevertCheckpointHint[] = [],
   ) {}
 
+  /**
+   * Creates an AvmExecutionHints from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AvmExecutionHints fields
+   * @returns An AvmExecutionHints instance
+   */
+  static fromPlainObject(obj: any): AvmExecutionHints {
+    if (obj instanceof AvmExecutionHints) {
+      return obj;
+    }
+    return new AvmExecutionHints(
+      GlobalVariables.fromPlainObject(obj.globalVariables),
+      AvmTxHint.fromPlainObject(obj.tx),
+      ProtocolContracts.fromPlainObject(obj.protocolContracts),
+      obj.contractInstances?.map((i: any) => AvmContractInstanceHint.fromPlainObject(i)) || [],
+      obj.contractClasses?.map((c: any) => AvmContractClassHint.fromPlainObject(c)) || [],
+      obj.bytecodeCommitments?.map((b: any) => AvmBytecodeCommitmentHint.fromPlainObject(b)) || [],
+      obj.debugFunctionNames?.map((d: any) => AvmDebugFunctionNameHint.fromPlainObject(d)) || [],
+      obj.contractDbCreateCheckpointHints?.map((h: any) => AvmContractDbCreateCheckpointHint.fromPlainObject(h)) || [],
+      obj.contractDbCommitCheckpointHints?.map((h: any) => AvmContractDbCommitCheckpointHint.fromPlainObject(h)) || [],
+      obj.contractDbRevertCheckpointHints?.map((h: any) => AvmContractDbRevertCheckpointHint.fromPlainObject(h)) || [],
+      obj.startingTreeRoots ? TreeSnapshots.fromPlainObject(obj.startingTreeRoots) : TreeSnapshots.empty(),
+      obj.getSiblingPathHints?.map((h: any) => AvmGetSiblingPathHint.fromPlainObject(h)) || [],
+      obj.getPreviousValueIndexHints?.map((h: any) => AvmGetPreviousValueIndexHint.fromPlainObject(h)) || [],
+      obj.getLeafPreimageHintsPublicDataTree?.map((h: any) =>
+        AvmGetLeafPreimageHintPublicDataTree.fromPlainObject(h),
+      ) || [],
+      obj.getLeafPreimageHintsNullifierTree?.map((h: any) => AvmGetLeafPreimageHintNullifierTree.fromPlainObject(h)) ||
+        [],
+      obj.getLeafValueHints?.map((h: any) => AvmGetLeafValueHint.fromPlainObject(h)) || [],
+      obj.sequentialInsertHintsPublicDataTree?.map((h: any) =>
+        AvmSequentialInsertHintPublicDataTree.fromPlainObject(h),
+      ) || [],
+      obj.sequentialInsertHintsNullifierTree?.map((h: any) =>
+        AvmSequentialInsertHintNullifierTree.fromPlainObject(h),
+      ) || [],
+      obj.appendLeavesHints?.map((h: any) => AvmAppendLeavesHint.fromPlainObject(h)) || [],
+      obj.createCheckpointHints?.map((h: any) => AvmCreateCheckpointHint.fromPlainObject(h)) || [],
+      obj.commitCheckpointHints?.map((h: any) => AvmCommitCheckpointHint.fromPlainObject(h)) || [],
+      obj.revertCheckpointHints?.map((h: any) => AvmRevertCheckpointHint.fromPlainObject(h)) || [],
+    );
+  }
+
   static empty() {
     return new AvmExecutionHints(GlobalVariables.empty(), AvmTxHint.empty(), ProtocolContracts.empty());
   }
@@ -550,6 +933,10 @@ export class AvmExecutionHints {
         contractInstances: AvmContractInstanceHint.schema.array(),
         contractClasses: AvmContractClassHint.schema.array(),
         bytecodeCommitments: AvmBytecodeCommitmentHint.schema.array(),
+        debugFunctionNames: AvmDebugFunctionNameHint.schema.array(),
+        contractDbCreateCheckpointHints: AvmContractDbCreateCheckpointHint.schema.array(),
+        contractDbCommitCheckpointHints: AvmContractDbCommitCheckpointHint.schema.array(),
+        contractDbRevertCheckpointHints: AvmContractDbRevertCheckpointHint.schema.array(),
         startingTreeRoots: TreeSnapshots.schema,
         getSiblingPathHints: AvmGetSiblingPathHint.schema.array(),
         getPreviousValueIndexHints: AvmGetPreviousValueIndexHint.schema.array(),
@@ -571,6 +958,10 @@ export class AvmExecutionHints {
           contractInstances,
           contractClasses,
           bytecodeCommitments,
+          debugFunctionNames,
+          contractDbCreateCheckpointHints,
+          contractDbCommitCheckpointHints,
+          contractDbRevertCheckpointHints,
           startingTreeRoots,
           getSiblingPathHints,
           getPreviousValueIndexHints,
@@ -591,6 +982,10 @@ export class AvmExecutionHints {
             contractInstances,
             contractClasses,
             bytecodeCommitments,
+            debugFunctionNames,
+            contractDbCreateCheckpointHints,
+            contractDbCommitCheckpointHints,
+            contractDbRevertCheckpointHints,
             startingTreeRoots,
             getSiblingPathHints,
             getPreviousValueIndexHints,
@@ -618,6 +1013,13 @@ export class AvmCircuitInputs {
     return new AvmCircuitInputs(AvmExecutionHints.empty(), AvmCircuitPublicInputs.empty());
   }
 
+  static fromPlainObject(obj: any): AvmCircuitInputs {
+    return new AvmCircuitInputs(
+      AvmExecutionHints.fromPlainObject(obj.hints),
+      AvmCircuitPublicInputs.fromPlainObject(obj.publicInputs),
+    );
+  }
+
   static get schema() {
     return z
       .object({
@@ -639,3 +1041,157 @@ export class AvmCircuitInputs {
     return jsonParseWithSchema(buf.toString(), this.schema);
   }
 }
+
+export class PublicTxResult {
+  constructor(
+    // Simulation result.
+    public gasUsed: GasUsed,
+    public revertCode: RevertCode,
+    public revertReason: SimulationError | undefined, // Revert reason, if any
+    // These are only guaranteed to be present if the simulator is configured to collect them.
+    // NOTE: This list will be populated with one NestedProcessReturnValues per app logic enqueued call.
+    // IMPORTANT: The nesting will only be 1 level deep! You will get one result per enqueued call
+    // but no information about nested calls. This can be added later.
+    public appLogicReturnValues: NestedProcessReturnValues[], // One per enqueued call.
+    public logs: DebugLog[] | undefined,
+    // For the proving request.
+    public hints: AvmExecutionHints | undefined,
+    public publicInputs: AvmCircuitPublicInputs,
+  ) {}
+
+  static empty() {
+    return new PublicTxResult(
+      {
+        totalGas: Gas.empty(),
+        teardownGas: Gas.empty(),
+        publicGas: Gas.empty(),
+        billedGas: Gas.empty(),
+      },
+      RevertCode.OK,
+      /*revertReason=*/ undefined,
+      /*appLogicReturnValues=*/ [],
+      /*logs=*/ [],
+      /*hints=*/ AvmExecutionHints.empty(),
+      /*publicInputs=*/ AvmCircuitPublicInputs.empty(),
+    );
+  }
+
+  static get schema(): ZodFor<PublicTxResult> {
+    return z
+      .object({
+        gasUsed: schemas.GasUsed,
+        revertCode: RevertCode.schema,
+        revertReason: NullishToUndefined(SimulationError.schema),
+        appLogicReturnValues: NestedProcessReturnValues.schema.array(),
+        logs: NullishToUndefined(DebugLog.schema.array()),
+        // For the proving request.
+        publicInputs: AvmCircuitPublicInputs.schema,
+        hints: NullishToUndefined(AvmExecutionHints.schema),
+      })
+      .transform(
+        ({ gasUsed, revertCode, revertReason, appLogicReturnValues, logs, hints, publicInputs }) =>
+          new PublicTxResult(
+            gasUsed,
+            revertCode as RevertCode,
+            revertReason,
+            appLogicReturnValues,
+            logs,
+            hints,
+            publicInputs,
+          ),
+      );
+  }
+
+  static fromPlainObject(obj: any): PublicTxResult {
+    return new PublicTxResult(
+      GasUsed.fromPlainObject(obj.gasUsed),
+      RevertCode.fromPlainObject(obj.revertCode),
+      /*revertReason=*/ undefined, // TODO(fcarreiro/mwood): add.
+      /*appLogicReturnValues=*/ obj.appLogicReturnValues.map(NestedProcessReturnValues.fromPlainObject),
+      obj.logs?.map(DebugLog.fromPlainObject),
+      obj.hints ? AvmExecutionHints.fromPlainObject(obj.hints) : undefined,
+      AvmCircuitPublicInputs.fromPlainObject(obj.publicInputs),
+    );
+  }
+}
+
+export class PublicSimulatorConfig {
+  constructor(
+    public readonly proverId: Fr,
+    public readonly skipFeeEnforcement: boolean,
+    public readonly collectCallMetadata: boolean, // appLogicReturnValues.
+    public readonly collectHints: boolean, // hints.
+    public readonly collectDebugLogs: boolean, // logs.
+    public readonly maxDebugLogMemoryReads: number,
+    public readonly collectStatistics: boolean, // timings etc.
+  ) {}
+
+  static from(obj: Partial<PublicSimulatorConfig>): PublicSimulatorConfig {
+    return new PublicSimulatorConfig(
+      obj.proverId ?? Fr.ZERO,
+      obj.skipFeeEnforcement ?? false,
+      obj.collectCallMetadata ?? false,
+      obj.collectHints ?? false,
+      obj.collectDebugLogs ?? false,
+      obj.maxDebugLogMemoryReads ?? DEFAULT_MAX_DEBUG_LOG_MEMORY_READS,
+      obj.collectStatistics ?? false,
+    );
+  }
+
+  static empty() {
+    return PublicSimulatorConfig.from({});
+  }
+
+  static get schema() {
+    return z
+      .object({
+        proverId: Fr.schema,
+        skipFeeEnforcement: z.boolean(),
+        collectCallMetadata: z.boolean(),
+        collectHints: z.boolean(),
+        collectDebugLogs: z.boolean(),
+        maxDebugLogMemoryReads: z.number(),
+        collectStatistics: z.boolean(),
+      })
+      .transform(PublicSimulatorConfig.from);
+  }
+}
+
+export class AvmFastSimulationInputs {
+  constructor(
+    public readonly wsRevision: WorldStateRevision,
+    public readonly config: PublicSimulatorConfig,
+    public tx: AvmTxHint,
+    public globalVariables: GlobalVariables,
+    public protocolContracts: ProtocolContracts,
+  ) {}
+
+  static empty() {
+    return new AvmFastSimulationInputs(
+      WorldStateRevision.empty(),
+      PublicSimulatorConfig.empty(),
+      AvmTxHint.empty(),
+      GlobalVariables.empty(),
+      ProtocolContracts.empty(),
+    );
+  }
+
+  static get schema() {
+    return z
+      .object({
+        wsRevision: WorldStateRevision.schema,
+        config: PublicSimulatorConfig.schema,
+        tx: AvmTxHint.schema,
+        globalVariables: GlobalVariables.schema,
+        protocolContracts: ProtocolContracts.schema,
+      })
+      .transform(
+        ({ wsRevision, config, tx, globalVariables, protocolContracts }) =>
+          new AvmFastSimulationInputs(wsRevision, config, tx, globalVariables, protocolContracts),
+      );
+  }
+
+  public serializeWithMessagePack(): Buffer {
+    return serializeWithMessagePack(this);
+  }
+}