@aztec/simulator 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/public/avm/opcodes/storage.ts

@@ -5,7 +5,9 @@ import { Opcode, OperandType } from '../serialization/instruction_serialization.
 import { Addressing } from './addressing_mode.js';
 import { Instruction } from './instruction.js';
 
-abstract class BaseStorageInstruction extends Instruction {
+export class SStore extends Instruction {
+  static readonly type: string = 'SSTORE';
+  static readonly opcode = Opcode.SSTORE;
   // Informs (de)serialization. See Instruction.deserialize.
   public static readonly wireFormat: OperandType[] = [
     OperandType.UINT8,
@@ -14,18 +16,13 @@ abstract class BaseStorageInstruction extends Instruction {
     OperandType.UINT16,
   ];
 
-  constructor(protected indirect: number, protected aOffset: number, protected bOffset: number) {
+  constructor(
+    private addressingMode: number,
+    private srcOffset: number,
+    private slotOffset: number,
+  ) {
     super();
   }
-}
-
-export class SStore extends BaseStorageInstruction {
-  static readonly type: string = 'SSTORE';
-  static readonly opcode = Opcode.SSTORE;
-
-  constructor(indirect: number, srcOffset: number, slotOffset: number) {
-    super(indirect, srcOffset, slotOffset);
-  }
 
   public async execute(context: AvmContext): Promise<void> {
     if (context.environment.isStaticCall) {
@@ -33,39 +30,66 @@ export class SStore extends BaseStorageInstruction {
     }
 
     const memory = context.machineState.memory;
-    context.machineState.consumeGas(this.gasCost());
+    const addressing = Addressing.fromWire(this.addressingMode);
+
+    context.machineState.consumeGas(
+      this.baseGasCost(addressing.indirectOperandsCount(), addressing.relativeOperandsCount()),
+    );
 
-    const operands = [this.aOffset, this.bOffset];
-    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const operands = [this.srcOffset, this.slotOffset];
     const [srcOffset, slotOffset] = addressing.resolve(operands, memory);
+    // We read before tag checking since it's needed for gas cost calculation
+    const slot = memory.get(slotOffset).toFr();
+
+    context.machineState.consumeGas(
+      this.dynamicGasCost(Number(context.persistableState.isStorageCold(context.environment.address, slot))),
+    );
+
     memory.checkTag(TypeTag.FIELD, slotOffset);
     memory.checkTag(TypeTag.FIELD, srcOffset);
 
-    const slot = memory.get(slotOffset).toFr();
     const value = memory.get(srcOffset).toFr();
     await context.persistableState.writeStorage(context.environment.address, slot, value);
   }
 }
 
-export class SLoad extends BaseStorageInstruction {
+export class SLoad extends Instruction {
   static readonly type: string = 'SLOAD';
   static readonly opcode = Opcode.SLOAD;
+  // Informs (de)serialization. See Instruction.deserialize.
+  public static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
 
-  constructor(indirect: number, slotOffset: number, dstOffset: number) {
-    super(indirect, slotOffset, dstOffset);
+  constructor(
+    private addressingMode: number,
+    private slotOffset: number,
+    private contractAddressOffset: number,
+    private dstOffset: number,
+  ) {
+    super();
   }
 
   public async execute(context: AvmContext): Promise<void> {
     const memory = context.machineState.memory;
-    context.machineState.consumeGas(this.gasCost());
+    const addressing = Addressing.fromWire(this.addressingMode);
+
+    context.machineState.consumeGas(
+      this.baseGasCost(addressing.indirectOperandsCount(), addressing.relativeOperandsCount()),
+    );
 
-    const operands = [this.aOffset, this.bOffset];
-    const addressing = Addressing.fromWire(this.indirect, operands.length);
-    const [slotOffset, dstOffset] = addressing.resolve(operands, memory);
+    const operands = [this.slotOffset, this.contractAddressOffset, this.dstOffset];
+    const [slotOffset, contractAddressOffset, dstOffset] = addressing.resolve(operands, memory);
     memory.checkTag(TypeTag.FIELD, slotOffset);
+    memory.checkTag(TypeTag.FIELD, contractAddressOffset);
 
     const slot = memory.get(slotOffset).toFr();
-    const value = await context.persistableState.readStorage(context.environment.address, slot);
+    const contractAddress = memory.get(contractAddressOffset).toAztecAddress();
+    const value = await context.persistableState.readStorage(contractAddress, slot);
     memory.set(dstOffset, new Field(value));
   }
 }

package/src/public/avm/revert_reason.ts

@@ -0,0 +1,58 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { AvmContext } from './avm_context.js';
+import { type AvmExecutionError, AvmRevertReason } from './errors.js';
+
+async function createRevertReason(message: string, revertData: Fr[], context: AvmContext): Promise<AvmRevertReason> {
+  // We drop the returnPc information.
+  const internalCallStack = context.machineState.internalCallStack.map(entry => entry.callPc);
+
+  // If we are reverting due to the same error that we have been tracking, we use the nested error as the cause.
+  let nestedError = undefined;
+  const revertDataEquals = (a: Fr[], b: Fr[]) => a.length === b.length && a.every((v, i) => v.equals(b[i]));
+  if (
+    context.machineState.collectedRevertInfo &&
+    revertDataEquals(context.machineState.collectedRevertInfo.revertDataRepresentative, revertData)
+  ) {
+    nestedError = context.machineState.collectedRevertInfo.recursiveRevertReason;
+    message = context.machineState.collectedRevertInfo.recursiveRevertReason.message;
+  }
+
+  const { functionSelector, functionName } = await context.persistableState.getPublicFunctionSelectorAndName(
+    context.environment,
+  );
+
+  return new AvmRevertReason(
+    message,
+    /*failingFunction=*/ {
+      contractAddress: context.environment.address,
+      functionSelector,
+      functionName,
+    },
+    /*noirCallStack=*/ [...internalCallStack, context.machineState.pc].map(pc => `0.${pc}`),
+    /*options=*/ { cause: nestedError },
+  );
+}
+
+/**
+ * Create a "revert reason" error for an exceptional halt.
+ *
+ * @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 async function revertReasonFromExceptionalHalt(
+  haltingError: AvmExecutionError,
+  context: AvmContext,
+): Promise<AvmRevertReason> {
+  return await createRevertReason(haltingError.message, [], context);
+}
+
+/**
+ * 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 async function revertReasonFromExplicitRevert(revertData: Fr[], context: AvmContext): Promise<AvmRevertReason> {
+  return await createRevertReason('Assertion failed: ', revertData, context);
+}

package/src/public/avm/serialization/buffer_cursor.ts

@@ -2,7 +2,10 @@
  * A Buffer-like class that automatically advances the position.
  */
 export class BufferCursor {
-  constructor(private _buffer: Buffer, private _position: number = 0) {}
+  constructor(
+    private _buffer: Buffer,
+    private _position: number = 0,
+  ) {}
 
   public position(): number {
     return this._position;

package/src/public/avm/serialization/bytecode_serialization.ts

@@ -1,4 +1,13 @@
-import { AvmExecutionError, AvmParsingError, InvalidOpcodeError, InvalidProgramCounterError } from '../errors.js';
+import { type Bufferable, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import {
+  AvmExecutionError,
+  AvmParsingError,
+  InvalidOpcodeError,
+  InvalidProgramCounterError,
+  InvalidTagValueError,
+  duringInstrFetch,
+} from '../errors.js';
 import {
   Add,
   And,
@@ -10,7 +19,7 @@ import {
   EcAdd,
   EmitNoteHash,
   EmitNullifier,
-  EmitUnencryptedLog,
+  EmitPublicLog,
   Eq,
   FieldDiv,
   GetContractInstance,
@@ -53,106 +62,102 @@ import { MAX_OPCODE_VALUE, Opcode } from './instruction_serialization.js';
 
 export type InstructionDeserializer = (buf: BufferCursor | Buffer) => Instruction;
 
-export interface Serializable {
-  serialize(): Buffer;
-}
-
 export interface Deserializable {
   deserialize: InstructionDeserializer;
 }
 
 export type InstructionSet = Map<Opcode, InstructionDeserializer>;
 export const INSTRUCTION_SET = new Map<Opcode, InstructionDeserializer>([
-  [Opcode.ADD_8, Add.as(Add.wireFormat8).deserialize],
-  [Opcode.ADD_16, Add.as(Add.wireFormat16).deserialize],
-  [Opcode.SUB_8, Sub.as(Sub.wireFormat8).deserialize],
-  [Opcode.SUB_16, Sub.as(Sub.wireFormat16).deserialize],
-  [Opcode.MUL_8, Mul.as(Mul.wireFormat8).deserialize],
-  [Opcode.MUL_16, Mul.as(Mul.wireFormat16).deserialize],
-  [Opcode.DIV_8, Div.as(Div.wireFormat8).deserialize],
-  [Opcode.DIV_16, Div.as(Div.wireFormat16).deserialize],
-  [Opcode.FDIV_8, FieldDiv.as(FieldDiv.wireFormat8).deserialize],
-  [Opcode.FDIV_16, FieldDiv.as(FieldDiv.wireFormat16).deserialize],
-  [Opcode.EQ_8, Eq.as(Eq.wireFormat8).deserialize],
-  [Opcode.EQ_16, Eq.as(Eq.wireFormat16).deserialize],
-  [Opcode.LT_8, Lt.as(Lt.wireFormat8).deserialize],
-  [Opcode.LT_16, Lt.as(Lt.wireFormat16).deserialize],
-  [Opcode.LTE_8, Lte.as(Lte.wireFormat8).deserialize],
-  [Opcode.LTE_16, Lte.as(Lte.wireFormat16).deserialize],
-  [Opcode.AND_8, And.as(And.wireFormat8).deserialize],
-  [Opcode.AND_16, And.as(And.wireFormat16).deserialize],
-  [Opcode.OR_8, Or.as(Or.wireFormat8).deserialize],
-  [Opcode.OR_16, Or.as(Or.wireFormat16).deserialize],
-  [Opcode.XOR_8, Xor.as(Xor.wireFormat8).deserialize],
-  [Opcode.XOR_16, Xor.as(Xor.wireFormat16).deserialize],
-  [Opcode.NOT_8, Not.as(Not.wireFormat8).deserialize],
-  [Opcode.NOT_16, Not.as(Not.wireFormat16).deserialize],
-  [Opcode.SHL_8, Shl.as(Shl.wireFormat8).deserialize],
-  [Opcode.SHL_16, Shl.as(Shl.wireFormat16).deserialize],
-  [Opcode.SHR_8, Shr.as(Shr.wireFormat8).deserialize],
-  [Opcode.SHR_16, Shr.as(Shr.wireFormat16).deserialize],
-  [Opcode.CAST_8, Cast.as(Cast.wireFormat8).deserialize],
-  [Opcode.CAST_16, Cast.as(Cast.wireFormat16).deserialize],
+  [Opcode.ADD_8, Add.as(Add.wireFormat8).fromBuffer],
+  [Opcode.ADD_16, Add.as(Add.wireFormat16).fromBuffer],
+  [Opcode.SUB_8, Sub.as(Sub.wireFormat8).fromBuffer],
+  [Opcode.SUB_16, Sub.as(Sub.wireFormat16).fromBuffer],
+  [Opcode.MUL_8, Mul.as(Mul.wireFormat8).fromBuffer],
+  [Opcode.MUL_16, Mul.as(Mul.wireFormat16).fromBuffer],
+  [Opcode.DIV_8, Div.as(Div.wireFormat8).fromBuffer],
+  [Opcode.DIV_16, Div.as(Div.wireFormat16).fromBuffer],
+  [Opcode.FDIV_8, FieldDiv.as(FieldDiv.wireFormat8).fromBuffer],
+  [Opcode.FDIV_16, FieldDiv.as(FieldDiv.wireFormat16).fromBuffer],
+  [Opcode.EQ_8, Eq.as(Eq.wireFormat8).fromBuffer],
+  [Opcode.EQ_16, Eq.as(Eq.wireFormat16).fromBuffer],
+  [Opcode.LT_8, Lt.as(Lt.wireFormat8).fromBuffer],
+  [Opcode.LT_16, Lt.as(Lt.wireFormat16).fromBuffer],
+  [Opcode.LTE_8, Lte.as(Lte.wireFormat8).fromBuffer],
+  [Opcode.LTE_16, Lte.as(Lte.wireFormat16).fromBuffer],
+  [Opcode.AND_8, And.as(And.wireFormat8).fromBuffer],
+  [Opcode.AND_16, And.as(And.wireFormat16).fromBuffer],
+  [Opcode.OR_8, Or.as(Or.wireFormat8).fromBuffer],
+  [Opcode.OR_16, Or.as(Or.wireFormat16).fromBuffer],
+  [Opcode.XOR_8, Xor.as(Xor.wireFormat8).fromBuffer],
+  [Opcode.XOR_16, Xor.as(Xor.wireFormat16).fromBuffer],
+  [Opcode.NOT_8, Not.as(Not.wireFormat8).fromBuffer],
+  [Opcode.NOT_16, Not.as(Not.wireFormat16).fromBuffer],
+  [Opcode.SHL_8, Shl.as(Shl.wireFormat8).fromBuffer],
+  [Opcode.SHL_16, Shl.as(Shl.wireFormat16).fromBuffer],
+  [Opcode.SHR_8, Shr.as(Shr.wireFormat8).fromBuffer],
+  [Opcode.SHR_16, Shr.as(Shr.wireFormat16).fromBuffer],
+  [Opcode.CAST_8, Cast.as(Cast.wireFormat8).fromBuffer],
+  [Opcode.CAST_16, Cast.as(Cast.wireFormat16).fromBuffer],
   // Execution Environment
-  [Opcode.GETENVVAR_16, GetEnvVar.as(GetEnvVar.wireFormat16).deserialize],
-  [CalldataCopy.opcode, Instruction.deserialize.bind(CalldataCopy)],
-  [SuccessCopy.opcode, Instruction.deserialize.bind(SuccessCopy)],
-  [Opcode.RETURNDATASIZE, Instruction.deserialize.bind(ReturndataSize)],
-  [Opcode.RETURNDATACOPY, Instruction.deserialize.bind(ReturndataCopy)],
+  [Opcode.GETENVVAR_16, GetEnvVar.as(GetEnvVar.wireFormat16).fromBuffer],
+  [CalldataCopy.opcode, Instruction.fromBuffer.bind(CalldataCopy)],
+  [SuccessCopy.opcode, Instruction.fromBuffer.bind(SuccessCopy)],
+  [Opcode.RETURNDATASIZE, Instruction.fromBuffer.bind(ReturndataSize)],
+  [Opcode.RETURNDATACOPY, Instruction.fromBuffer.bind(ReturndataCopy)],
 
   // Machine State - Internal Control Flow
-  [Jump.opcode, Instruction.deserialize.bind(Jump)],
-  [JumpI.opcode, Instruction.deserialize.bind(JumpI)],
-  [InternalCall.opcode, Instruction.deserialize.bind(InternalCall)],
-  [InternalReturn.opcode, Instruction.deserialize.bind(InternalReturn)],
-  [Opcode.SET_8, Set.as(Set.wireFormat8).deserialize],
-  [Opcode.SET_16, Set.as(Set.wireFormat16).deserialize],
-  [Opcode.SET_32, Set.as(Set.wireFormat32).deserialize],
-  [Opcode.SET_64, Set.as(Set.wireFormat64).deserialize],
-  [Opcode.SET_128, Set.as(Set.wireFormat128).deserialize],
-  [Opcode.SET_FF, Set.as(Set.wireFormatFF).deserialize],
-  [Opcode.MOV_8, Mov.as(Mov.wireFormat8).deserialize],
-  [Opcode.MOV_16, Mov.as(Mov.wireFormat16).deserialize],
+  [Jump.opcode, Instruction.fromBuffer.bind(Jump)],
+  [JumpI.opcode, Instruction.fromBuffer.bind(JumpI)],
+  [InternalCall.opcode, Instruction.fromBuffer.bind(InternalCall)],
+  [InternalReturn.opcode, Instruction.fromBuffer.bind(InternalReturn)],
+  [Opcode.SET_8, Set.as(Set.wireFormat8).fromBuffer],
+  [Opcode.SET_16, Set.as(Set.wireFormat16).fromBuffer],
+  [Opcode.SET_32, Set.as(Set.wireFormat32).fromBuffer],
+  [Opcode.SET_64, Set.as(Set.wireFormat64).fromBuffer],
+  [Opcode.SET_128, Set.as(Set.wireFormat128).fromBuffer],
+  [Opcode.SET_FF, Set.as(Set.wireFormatFF).fromBuffer],
+  [Opcode.MOV_8, Mov.as(Mov.wireFormat8).fromBuffer],
+  [Opcode.MOV_16, Mov.as(Mov.wireFormat16).fromBuffer],
 
   // World State
-  [SLoad.opcode, Instruction.deserialize.bind(SLoad)], // Public Storage
-  [SStore.opcode, Instruction.deserialize.bind(SStore)], // Public Storage
-  [NoteHashExists.opcode, Instruction.deserialize.bind(NoteHashExists)], // Notes & Nullifiers
-  [EmitNoteHash.opcode, Instruction.deserialize.bind(EmitNoteHash)], // Notes & Nullifiers
-  [NullifierExists.opcode, Instruction.deserialize.bind(NullifierExists)], // Notes & Nullifiers
-  [EmitNullifier.opcode, Instruction.deserialize.bind(EmitNullifier)], // Notes & Nullifiers
-  [L1ToL2MessageExists.opcode, Instruction.deserialize.bind(L1ToL2MessageExists)], // Messages
+  [SLoad.opcode, Instruction.fromBuffer.bind(SLoad)], // Public Storage
+  [SStore.opcode, Instruction.fromBuffer.bind(SStore)], // Public Storage
+  [NoteHashExists.opcode, Instruction.fromBuffer.bind(NoteHashExists)], // Notes & Nullifiers
+  [EmitNoteHash.opcode, Instruction.fromBuffer.bind(EmitNoteHash)], // Notes & Nullifiers
+  [NullifierExists.opcode, Instruction.fromBuffer.bind(NullifierExists)], // Notes & Nullifiers
+  [EmitNullifier.opcode, Instruction.fromBuffer.bind(EmitNullifier)], // Notes & Nullifiers
+  [L1ToL2MessageExists.opcode, Instruction.fromBuffer.bind(L1ToL2MessageExists)], // Messages
 
   // Accrued Substate
-  [EmitUnencryptedLog.opcode, Instruction.deserialize.bind(EmitUnencryptedLog)],
-  [SendL2ToL1Message.opcode, Instruction.deserialize.bind(SendL2ToL1Message)],
-  [GetContractInstance.opcode, Instruction.deserialize.bind(GetContractInstance)],
+  [EmitPublicLog.opcode, Instruction.fromBuffer.bind(EmitPublicLog)],
+  [SendL2ToL1Message.opcode, Instruction.fromBuffer.bind(SendL2ToL1Message)],
+  [GetContractInstance.opcode, Instruction.fromBuffer.bind(GetContractInstance)],
 
   // Control Flow - Contract Calls
-  [Call.opcode, Instruction.deserialize.bind(Call)],
-  [StaticCall.opcode, Instruction.deserialize.bind(StaticCall)],
-  [Return.opcode, Instruction.deserialize.bind(Return)],
-  [Opcode.REVERT_8, Revert.as(Revert.wireFormat8).deserialize],
-  [Opcode.REVERT_16, Revert.as(Revert.wireFormat16).deserialize],
+  [Call.opcode, Instruction.fromBuffer.bind(Call)],
+  [StaticCall.opcode, Instruction.fromBuffer.bind(StaticCall)],
+  [Return.opcode, Instruction.fromBuffer.bind(Return)],
+  [Opcode.REVERT_8, Revert.as(Revert.wireFormat8).fromBuffer],
+  [Opcode.REVERT_16, Revert.as(Revert.wireFormat16).fromBuffer],
 
   // Misc
-  [DebugLog.opcode, Instruction.deserialize.bind(DebugLog)],
+  [DebugLog.opcode, Instruction.fromBuffer.bind(DebugLog)],
 
   // Gadgets
-  [EcAdd.opcode, Instruction.deserialize.bind(EcAdd)],
-  [Poseidon2.opcode, Instruction.deserialize.bind(Poseidon2)],
-  [Sha256Compression.opcode, Instruction.deserialize.bind(Sha256Compression)],
-  [KeccakF1600.opcode, Instruction.deserialize.bind(KeccakF1600)],
+  [EcAdd.opcode, Instruction.fromBuffer.bind(EcAdd)],
+  [Poseidon2.opcode, Instruction.fromBuffer.bind(Poseidon2)],
+  [Sha256Compression.opcode, Instruction.fromBuffer.bind(Sha256Compression)],
+  [KeccakF1600.opcode, Instruction.fromBuffer.bind(KeccakF1600)],
 
   // Conversions
-  [ToRadixBE.opcode, Instruction.deserialize.bind(ToRadixBE)],
+  [ToRadixBE.opcode, Instruction.fromBuffer.bind(ToRadixBE)],
 ]);
 
 /**
  * Serializes an array of instructions to bytecode.
  */
-export function encodeToBytecode(instructions: Serializable[]): Buffer {
-  return Buffer.concat(instructions.map(i => i.serialize()));
+export function encodeToBytecode(instructions: Bufferable[]): Buffer {
+  return serializeToBuffer(instructions);
 }
 
 // For testing only
@@ -174,7 +179,7 @@ export function decodeInstructionFromBytecode(
   instructionSet: InstructionSet = INSTRUCTION_SET,
 ): [Instruction, number] {
   if (pc >= bytecode.length) {
-    throw new InvalidProgramCounterError(pc, bytecode.length);
+    throw new InvalidProgramCounterError(pc, bytecode.length - 1);
   }
 
   try {
@@ -184,7 +189,7 @@ export function decodeInstructionFromBytecode(
 
     if (opcode > MAX_OPCODE_VALUE) {
       throw new InvalidOpcodeError(
-        `Opcode ${opcode} (0x${opcode.toString(16)}) value is not in the range of valid opcodes.`,
+        `Opcode ${opcode} (0x${opcode.toString(16)}) value is not in the range of valid opcodes (at PC ${pc}).`,
       );
     }
 
@@ -194,13 +199,17 @@ export function decodeInstructionFromBytecode(
     }
 
     const instructionDeserializer: InstructionDeserializer = instructionDeserializerOrUndef;
+
     const instruction = instructionDeserializer(cursor);
     return [instruction, cursor.position() - startingPosition];
   } catch (error) {
-    if (error instanceof InvalidOpcodeError || error instanceof AvmExecutionError) {
-      throw error;
+    if (error instanceof InvalidTagValueError || error instanceof InvalidOpcodeError) {
+      throw duringInstrFetch(error, pc);
+    } else if (error instanceof AvmExecutionError) {
+      throw new AvmParsingError(`Instruction parsing error at pc ${pc}: ${error.message}`);
     } else {
-      throw new AvmParsingError(`${error}`);
+      const msg = error instanceof Error ? `: ${error.message}` : '';
+      throw new AvmParsingError(`Instruction fetching error at pc ${pc}${msg}`);
     }
   }
 }

package/src/public/avm/serialization/instruction_serialization.ts

@@ -1,5 +1,8 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+
 import { strict as assert } from 'assert';
 
+import { TaggedMemory } from '../avm_memory_types.js';
 import { BufferCursor } from './buffer_cursor.js';
 
 /**
@@ -67,7 +70,7 @@ export enum Opcode {
   EMITNULLIFIER,
   L1TOL2MSGEXISTS,
   GETCONTRACTINSTANCE,
-  EMITUNENCRYPTEDLOG,
+  EMITPUBLICLOG,
   SENDL2TOL1MSG,
   // External calls
   CALL,
@@ -92,10 +95,8 @@ export const MAX_OPCODE_VALUE = Math.max(
     .filter(k => !isNaN(k)),
 );
 
-// Possible types for an instruction's operand in its wire format. (Keep in sync with CPP code.
-// See vm/avm_trace/deserialization.cpp)
-// Note that cpp code introduced an additional enum value TAG to express the instruction tag. In TS,
-// this one is parsed as UINT8.
+// Possible types for an instruction's operand in its wire format.
+// The counterpart cpp file is: vm2/simulation/lib/serialization.hpp.
 export enum OperandType {
   UINT8,
   UINT16,
@@ -103,8 +104,12 @@ export enum OperandType {
   UINT64,
   UINT128,
   FF,
+  TAG,
 }
 
+// Define a type that represents the possible types of the deserialized values.
+type DeserializedValue = number | bigint;
+
 type OperandNativeType = number | bigint;
 type OperandWriter = (value: any) => void;
 
@@ -113,45 +118,70 @@ const OPERAND_SPEC = new Map<OperandType, [number, (offset: number) => OperandNa
   [OperandType.UINT8, [1, Buffer.prototype.readUint8, Buffer.prototype.writeUint8]],
   [OperandType.UINT16, [2, Buffer.prototype.readUint16BE, Buffer.prototype.writeUint16BE]],
   [OperandType.UINT32, [4, Buffer.prototype.readUint32BE, Buffer.prototype.writeUint32BE]],
-  [OperandType.UINT64, [8, Buffer.prototype.readBigInt64BE, Buffer.prototype.writeBigInt64BE]],
-  [OperandType.UINT128, [16, readBigInt128BE, writeBigInt128BE]],
-  [OperandType.FF, [32, readBigInt254BE, writeBigInt254BE]],
+  [OperandType.UINT64, [8, readUint64BE, writeUint64BE]],
+  [OperandType.UINT128, [16, readUint128BE, writeUint128BE]],
+  [OperandType.FF, [32, readUint254BE, writeUint254BE]],
+  [OperandType.TAG, [1, Buffer.prototype.readUint8, Buffer.prototype.writeUint8]],
 ]);
 
-function readBigInt254BE(this: Buffer, offset: number): bigint {
-  const totalBytes = 32;
-  let ret: bigint = 0n;
+/**
+ * Returns the size of an operand in bytes.
+ * Should not be called with unknown operand types.
+ * @param operandType
+ * @returns number size in bytes
+ * @throws AssertionError if the operand type is unknown
+ */
+export function getOperandSize(operandType: OperandType): number {
+  assert(OPERAND_SPEC.has(operandType), `Unknown operand type: ${operandType}`);
+  return OPERAND_SPEC.get(operandType)![0];
+}
+
+function readUintBE(buf: Buffer, offset: number, totalBytes: number): bigint {
+  let value: bigint = 0n;
   for (let i = 0; i < totalBytes; ++i) {
-    ret <<= 8n;
-    ret |= BigInt(this.readUint8(i + offset));
+    value <<= 8n;
+    value |= BigInt(buf.readUint8(i + offset));
   }
-  return ret;
+  return value;
 }
 
-function writeBigInt254BE(this: Buffer, value: bigint): void {
-  const totalBytes = 32;
+function writeUintBE(buf: Buffer, value: bigint, totalBytes: number): void {
   for (let offset = totalBytes - 1; offset >= 0; --offset) {
-    this.writeUint8(Number(value & 0xffn), offset);
+    buf.writeUint8(Number(value & 0xffn), offset);
     value >>= 8n;
   }
 }
 
-function readBigInt128BE(this: Buffer, offset: number): bigint {
-  const totalBytes = 16;
-  let ret: bigint = 0n;
-  for (let i = 0; i < totalBytes; ++i) {
-    ret <<= 8n;
-    ret |= BigInt(this.readUint8(i + offset));
-  }
-  return ret;
+function readUint64BE(this: Buffer, offset: number): bigint {
+  return readUintBE(this, offset, 8);
 }
 
-function writeBigInt128BE(this: Buffer, value: bigint): void {
-  const totalBytes = 16;
-  for (let offset = totalBytes - 1; offset >= 0; --offset) {
-    this.writeUint8(Number(value & 0xffn), offset);
-    value >>= 8n;
+function writeUint64BE(this: Buffer, value: bigint): void {
+  writeUintBE(this, value, 8);
+}
+
+function readUint254BE(this: Buffer, offset: number): bigint {
+  let value = readUintBE(this, offset, 32);
+
+  // In circuit, we only support values up to Fr.MODULUS and any deserialized value
+  // would naturally undergo a modulus reduction.
+  if (value >= Fr.MODULUS) {
+    value = value % Fr.MODULUS;
   }
+
+  return value;
+}
+
+function writeUint254BE(this: Buffer, value: bigint): void {
+  writeUintBE(this, value, 32);
+}
+
+function readUint128BE(this: Buffer, offset: number): bigint {
+  return readUintBE(this, offset, 16);
+}
+
+function writeUint128BE(this: Buffer, value: bigint): void {
+  writeUintBE(this, value, 16);
 }
 
 /**
@@ -160,19 +190,30 @@ function writeBigInt128BE(this: Buffer, value: bigint): void {
  * @param operands Specification of the operand types.
  * @returns An array as big as {@code operands}, with the converted TS values.
  */
-export function deserialize(cursor: BufferCursor | Buffer, operands: OperandType[]): (number | bigint)[] {
-  const argValues = [];
+export function deserialize(cursor: BufferCursor | Buffer, operands: OperandType[]): DeserializedValue[] {
+  const argValues: DeserializedValue[] = [];
   if (Buffer.isBuffer(cursor)) {
     cursor = new BufferCursor(cursor);
   }
 
-  for (const op of operands) {
-    const opType = op;
+  for (const opType of operands) {
     const [sizeBytes, reader, _writer] = OPERAND_SPEC.get(opType)!;
-    argValues.push(reader.call(cursor.buffer(), cursor.position()));
+    const value = reader.call(cursor.buffer(), cursor.position());
+    argValues.push(value);
     cursor.advance(sizeBytes);
   }
 
+  // We first want to detect other parsing errors (e.g., instruction size
+  // is longer than remaining bytes) first and therefore tag validation is done after completion
+  // of parsing above. Order of errors need to match with circuit.
+  for (let i = 0; i < operands.length; i++) {
+    if (operands[i] === OperandType.TAG) {
+      // We parsed a single byte (readUInt8()) and therefore value is of number type (not bigint)
+      // We need to cast to number because checkIsValidTag expects a number.
+      TaggedMemory.checkIsValidTag(Number(argValues[i] ?? 0));
+    }
+  }
+
   return argValues;
 }