Search documentation of Cartouche

# Cartouche.VM.Context (Cartouche v0.1.2)

Copy Markdown View Source

Runtime execution state of a `Cartouche.VM` step: program counter, stack, memory, transient storage, halt/revert flags, return data, and the FFI table available to the VM.

## Summary

### Types

op_map()
t()

### Functions

fetch_ffi(context, address)

Looks up the FFI registered at `address` in the context's FFI table. Returns `{:error, {:unknown_ffi, address}}` when no FFI is registered.

init_from(code, ffis)

Builds a fresh `Context` for executing `code` with the given FFI table. Pre-computes the program-counter-keyed `op_map` from the assembled bytecode so subsequent steps can resolve operations in O(1).

show(context)

Renders the context as a multi-line string showing the program counter and stack contents. Used for verbose VM tracing.

show_stack(stack)

Renders the EVM stack as a debugger-style multi-line string with descending offsets and word values in hex.

## Types

# op_map()

    @type op_map() :: %{required(integer()) => Cartouche.VM.opcode()}

# t()

    @type t() :: %Cartouche.VM.Context{
      code: Cartouche.VM.code(),
      code_encoded: binary(),
      ffis: Cartouche.VM.ffis(),
      halted: boolean(),
      memory: binary(),
      op_map: op_map(),
      pc: integer(),
      return_data: binary(),
      reverted: boolean(),
      stack: [binary()],
      tstorage: %{required(binary()) => binary()}
    }

## Functions

# fetch_ffi(context, address)

    @spec fetch_ffi(t(), Cartouche.VM.address()) ::
      {:ok, Cartouche.VM.ffi()} | {:error, Cartouche.VM.vm_error()}

Looks up the FFI registered at `address` in the context's FFI table. Returns `{:error, {:unknown_ffi, address}}` when no FFI is registered.

# init_from(code, ffis)

    @spec init_from(Cartouche.VM.code(), Cartouche.VM.ffis()) :: t()

Builds a fresh `Context` for executing `code` with the given FFI table. Pre-computes the program-counter-keyed `op_map` from the assembled bytecode so subsequent steps can resolve operations in O(1).

# show(context)

    @spec show(t()) :: String.t()

Renders the context as a multi-line string showing the program counter and stack contents. Used for verbose VM tracing.

# show_stack(stack)

    @spec show_stack([binary()]) :: String.t()

Renders the EVM stack as a debugger-style multi-line string with descending offsets and word values in hex.