@aztec/simulator 0.0.0-test.0

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

@@ -0,0 +1,254 @@
+import type { AvmContext } from '../avm_context.js';
+import { Field, TaggedMemory, TypeTag, Uint32 } 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 Set extends Instruction {
+  static readonly type: string = 'SET';
+  // Required for gas.
+  static readonly opcode: Opcode = Opcode.SET_8;
+
+  public static readonly wireFormat8: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT8, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.UINT8, // const (value)
+  ];
+  public static readonly wireFormat16: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.UINT16, // const (value)
+  ];
+  public static readonly wireFormat32: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.UINT32, // const (value)
+  ];
+  public static readonly wireFormat64: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.UINT64, // const (value)
+  ];
+  public static readonly wireFormat128: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.UINT128, // const (value)
+  ];
+  public static readonly wireFormatFF: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // tag
+    OperandType.FF, // const (value)
+  ];
+
+  constructor(
+    private indirect: number,
+    private dstOffset: number,
+    private inTag: number,
+    private value: bigint | number,
+  ) {
+    super();
+    TaggedMemory.checkIsValidTag(inTag);
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    // Constructor ensured that this.inTag is a valid tag
+    const res = TaggedMemory.buildFromTagTruncating(this.value, this.inTag);
+
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [dstOffset] = addressing.resolve(operands, memory);
+    memory.set(dstOffset, res);
+  }
+}
+
+export class Cast extends Instruction {
+  static readonly type: string = 'CAST';
+  static readonly opcode = Opcode.CAST_8;
+
+  static readonly wireFormat8 = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+  ];
+  static readonly wireFormat16 = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT8,
+  ];
+
+  constructor(private indirect: number, private srcOffset: number, private dstOffset: number, private dstTag: number) {
+    super();
+    TaggedMemory.checkIsValidTag(dstTag);
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.srcOffset, this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [srcOffset, dstOffset] = addressing.resolve(operands, memory);
+
+    const a = memory.get(srcOffset);
+    // Constructor ensured that this.dstTag is a valid tag
+    const casted = TaggedMemory.buildFromTagTruncating(a.toBigInt(), this.dstTag);
+
+    memory.set(dstOffset, casted);
+  }
+}
+
+export class Mov extends Instruction {
+  static readonly type: string = 'MOV';
+  // FIXME: This is needed for gas.
+  static readonly opcode: Opcode = Opcode.MOV_8;
+
+  static readonly wireFormat8: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+  ];
+  static readonly wireFormat16: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(private indirect: number, private srcOffset: number, private dstOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.srcOffset, this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [srcOffset, dstOffset] = addressing.resolve(operands, memory);
+    const a = memory.get(srcOffset);
+    memory.set(dstOffset, a);
+  }
+}
+
+export class CalldataCopy extends Instruction {
+  static readonly type: string = 'CALLDATACOPY';
+  static readonly opcode: Opcode = Opcode.CALLDATACOPY;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(
+    private indirect: number,
+    private cdStartOffset: number,
+    private copySizeOffset: number,
+    private dstOffset: number,
+  ) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    const operands = [this.cdStartOffset, this.copySizeOffset, this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [cdStartOffset, copySizeOffset, dstOffset] = addressing.resolve(operands, memory);
+
+    memory.checkTags(TypeTag.UINT32, cdStartOffset, copySizeOffset);
+    const cdStart = memory.get(cdStartOffset).toNumber();
+    const copySize = memory.get(copySizeOffset).toNumber();
+    context.machineState.consumeGas(this.gasCost(copySize));
+
+    // Values which are out-of-range of the calldata array will be set with Field(0);
+    const slice = context.environment.calldata.slice(cdStart, cdStart + copySize).map(f => new Field(f));
+    // slice has size = MIN(copySize, calldata.length - cdStart) as TS truncates out-of-range portion
+    const transformedData = [...slice, ...Array(copySize - slice.length).fill(new Field(0))];
+
+    memory.setSlice(dstOffset, transformedData);
+  }
+}
+
+export class ReturndataSize extends Instruction {
+  static readonly type: string = 'RETURNDATASIZE';
+  static readonly opcode: Opcode = Opcode.RETURNDATASIZE;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [OperandType.UINT8, OperandType.UINT8, OperandType.UINT16];
+
+  constructor(private indirect: number, private dstOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    const operands = [this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [dstOffset] = addressing.resolve(operands, memory);
+    context.machineState.consumeGas(this.gasCost());
+
+    memory.set(dstOffset, new Uint32(context.machineState.nestedReturndata.length));
+  }
+}
+
+export class ReturndataCopy extends Instruction {
+  static readonly type: string = 'RETURNDATACOPY';
+  static readonly opcode: Opcode = Opcode.RETURNDATACOPY;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(
+    private indirect: number,
+    private rdStartOffset: number,
+    private copySizeOffset: number,
+    private dstOffset: number,
+  ) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    const operands = [this.rdStartOffset, this.copySizeOffset, this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [rdStartOffset, copySizeOffset, dstOffset] = addressing.resolve(operands, memory);
+
+    memory.checkTags(TypeTag.UINT32, rdStartOffset, copySizeOffset);
+    const rdStart = memory.get(rdStartOffset).toNumber();
+    const copySize = memory.get(copySizeOffset).toNumber();
+    context.machineState.consumeGas(this.gasCost(copySize));
+
+    // Values which are out-of-range of the returndata array will be set with Field(0);
+    const slice = context.machineState.nestedReturndata.slice(rdStart, rdStart + copySize).map(f => new Field(f));
+    // slice has size = MIN(copySize, returndata.length - rdStart) as TS truncates out-of-range portion
+    const transformedData = [...slice, ...Array(copySize - slice.length).fill(new Field(0))];
+
+    memory.setSlice(dstOffset, transformedData);
+  }
+}

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

@@ -0,0 +1,60 @@
+import { applyStringFormatting, createLogger } from '@aztec/foundation/log';
+
+import type { AvmContext } from '../avm_context.js';
+import { TypeTag } 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 DebugLog extends Instruction {
+  static type: string = 'DEBUGLOG';
+  static readonly opcode: Opcode = Opcode.DEBUGLOG;
+  static readonly logger = createLogger('simulator:avm:debug_log');
+
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8, // Opcode
+    OperandType.UINT8, // Indirect
+    OperandType.UINT16, // message memory address
+    OperandType.UINT16, // fields memory address
+    OperandType.UINT16, // fields size address
+    OperandType.UINT16, // message size
+  ];
+
+  constructor(
+    private indirect: number,
+    private messageOffset: number,
+    private fieldsOffset: number,
+    private fieldsSizeOffset: number,
+    private messageSize: number,
+  ) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    const operands = [this.messageOffset, this.fieldsOffset, this.fieldsSizeOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [messageOffset, fieldsOffset, fieldsSizeOffset] = addressing.resolve(operands, memory);
+
+    memory.checkTag(TypeTag.UINT32, fieldsSizeOffset);
+    const fieldsSize = memory.get(fieldsSizeOffset).toNumber();
+
+    const rawMessage = memory.getSlice(messageOffset, this.messageSize);
+    const fields = memory.getSlice(fieldsOffset, fieldsSize);
+
+    memory.checkTagsRange(TypeTag.UINT8, messageOffset, this.messageSize);
+    memory.checkTagsRange(TypeTag.FIELD, fieldsOffset, fieldsSize);
+
+    context.machineState.consumeGas(this.gasCost(this.messageSize + fieldsSize));
+
+    // Interpret str<N> = [u8; N] to string.
+    const messageAsStr = rawMessage.map(field => String.fromCharCode(field.toNumber())).join('');
+    const formattedStr = applyStringFormatting(
+      messageAsStr,
+      fields.map(field => field.toFr()),
+    );
+
+    DebugLog.logger.verbose(formattedStr);
+  }
+}

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

@@ -0,0 +1,71 @@
+import type { AvmContext } from '../avm_context.js';
+import { Field, TypeTag } from '../avm_memory_types.js';
+import { StaticCallAlterationError } from '../errors.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+
+abstract class BaseStorageInstruction extends Instruction {
+  // Informs (de)serialization. See Instruction.deserialize.
+  public static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(protected indirect: number, protected aOffset: number, protected bOffset: 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) {
+      throw new StaticCallAlterationError();
+    }
+
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.aOffset, this.bOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [srcOffset, slotOffset] = addressing.resolve(operands, memory);
+    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 {
+  static readonly type: string = 'SLOAD';
+  static readonly opcode = Opcode.SLOAD;
+
+  constructor(indirect: number, slotOffset: number, dstOffset: number) {
+    super(indirect, slotOffset, dstOffset);
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.aOffset, this.bOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [slotOffset, dstOffset] = addressing.resolve(operands, memory);
+    memory.checkTag(TypeTag.FIELD, slotOffset);
+
+    const slot = memory.get(slotOffset).toFr();
+    const value = await context.persistableState.readStorage(context.environment.address, slot);
+    memory.set(dstOffset, new Field(value));
+  }
+}

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

@@ -0,0 +1,115 @@
+/*
+ * A Buffer-like class that automatically advances the position.
+ */
+export class BufferCursor {
+  constructor(private _buffer: Buffer, private _position: number = 0) {}
+
+  public position(): number {
+    return this._position;
+  }
+
+  public buffer(): Buffer {
+    return this._buffer;
+  }
+
+  public eof(): boolean {
+    return this._position === this._buffer.length;
+  }
+
+  public bufferAtPosition(): Buffer {
+    return this._buffer.subarray(this._position);
+  }
+
+  public advance(n: number): void {
+    this._position += n;
+  }
+
+  public peekUint8(): number {
+    const ret = this._buffer.readUint8(this._position);
+    return ret;
+  }
+
+  public readUint8(): number {
+    const ret = this._buffer.readUint8(this._position);
+    this._position += 1;
+    return ret;
+  }
+
+  public readUint16LE(): number {
+    const ret = this._buffer.readUint16LE(this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public readUint16BE(): number {
+    const ret = this._buffer.readUint16BE(this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public readUint32LE(): number {
+    const ret = this._buffer.readUint32LE(this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public readUint32BE(): number {
+    const ret = this._buffer.readUint32BE(this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public readBigInt64LE(): bigint {
+    const ret = this._buffer.readBigInt64LE(this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public readBigInt64BE(): bigint {
+    const ret = this._buffer.readBigInt64BE(this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public writeUint8(v: number) {
+    const ret = this._buffer.writeUint8(v, this._position);
+    this._position += 1;
+    return ret;
+  }
+
+  public writeUint16LE(v: number) {
+    const ret = this._buffer.writeUint16LE(v, this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public writeUint16BE(v: number) {
+    const ret = this._buffer.writeUint16BE(v, this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public writeUint32LE(v: number) {
+    const ret = this._buffer.writeUint32LE(v, this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public writeUint32BE(v: number) {
+    const ret = this._buffer.writeUint32BE(v, this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public writeBigInt64LE(v: bigint) {
+    const ret = this._buffer.writeBigInt64LE(v, this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public writeBigInt64BE(v: bigint) {
+    const ret = this._buffer.writeBigInt64BE(v, this._position);
+    this._position += 8;
+    return ret;
+  }
+}

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

@@ -0,0 +1,206 @@
+import { AvmExecutionError, AvmParsingError, InvalidOpcodeError, InvalidProgramCounterError } from '../errors.js';
+import {
+  Add,
+  And,
+  Call,
+  CalldataCopy,
+  Cast,
+  DebugLog,
+  Div,
+  EcAdd,
+  EmitNoteHash,
+  EmitNullifier,
+  EmitUnencryptedLog,
+  Eq,
+  FieldDiv,
+  GetContractInstance,
+  GetEnvVar,
+  Instruction,
+  InternalCall,
+  InternalReturn,
+  Jump,
+  JumpI,
+  KeccakF1600,
+  L1ToL2MessageExists,
+  Lt,
+  Lte,
+  Mov,
+  Mul,
+  Not,
+  NoteHashExists,
+  NullifierExists,
+  Or,
+  Poseidon2,
+  Return,
+  ReturndataCopy,
+  ReturndataSize,
+  Revert,
+  SLoad,
+  SStore,
+  SendL2ToL1Message,
+  Set,
+  Sha256Compression,
+  Shl,
+  Shr,
+  StaticCall,
+  Sub,
+  SuccessCopy,
+  ToRadixBE,
+  Xor,
+} from '../opcodes/index.js';
+import { BufferCursor } from './buffer_cursor.js';
+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],
+  // 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)],
+
+  // 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],
+
+  // 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
+
+  // Accrued Substate
+  [EmitUnencryptedLog.opcode, Instruction.deserialize.bind(EmitUnencryptedLog)],
+  [SendL2ToL1Message.opcode, Instruction.deserialize.bind(SendL2ToL1Message)],
+  [GetContractInstance.opcode, Instruction.deserialize.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],
+
+  // Misc
+  [DebugLog.opcode, Instruction.deserialize.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)],
+
+  // Conversions
+  [ToRadixBE.opcode, Instruction.deserialize.bind(ToRadixBE)],
+]);
+
+/**
+ * Serializes an array of instructions to bytecode.
+ */
+export function encodeToBytecode(instructions: Serializable[]): Buffer {
+  return Buffer.concat(instructions.map(i => i.serialize()));
+}
+
+// For testing only
+export function decodeFromBytecode(bytecode: Buffer, instructionSet: InstructionSet = INSTRUCTION_SET): Instruction[] {
+  const instructions: Instruction[] = [];
+  let pc = 0;
+  while (pc < bytecode.length) {
+    const [instruction, bytesConsumed] = decodeInstructionFromBytecode(bytecode, pc, instructionSet);
+    instructions.push(instruction);
+    pc += bytesConsumed;
+  }
+  return instructions;
+}
+
+// Returns the instruction and the number of bytes consumed.
+export function decodeInstructionFromBytecode(
+  bytecode: Buffer,
+  pc: number,
+  instructionSet: InstructionSet = INSTRUCTION_SET,
+): [Instruction, number] {
+  if (pc >= bytecode.length) {
+    throw new InvalidProgramCounterError(pc, bytecode.length);
+  }
+
+  try {
+    const cursor = new BufferCursor(bytecode, pc);
+    const startingPosition = cursor.position();
+    const opcode: number = cursor.bufferAtPosition().readUint8(); // peek.
+
+    if (opcode > MAX_OPCODE_VALUE) {
+      throw new InvalidOpcodeError(
+        `Opcode ${opcode} (0x${opcode.toString(16)}) value is not in the range of valid opcodes.`,
+      );
+    }
+
+    const instructionDeserializerOrUndef = instructionSet.get(opcode);
+    if (instructionDeserializerOrUndef === undefined) {
+      throw new InvalidOpcodeError(`Opcode ${Opcode[opcode]} (0x${opcode.toString(16)}) is not implemented`);
+    }
+
+    const instructionDeserializer: InstructionDeserializer = instructionDeserializerOrUndef;
+    const instruction = instructionDeserializer(cursor);
+    return [instruction, cursor.position() - startingPosition];
+  } catch (error) {
+    if (error instanceof InvalidOpcodeError || error instanceof AvmExecutionError) {
+      throw error;
+    } else {
+      throw new AvmParsingError(`${error}`);
+    }
+  }
+}