# `Cartouche.VM`
[🔗](https://github.com/zenhive/cartouche/blob/main/lib/cartouche/vm.ex#L1)

An Ethereum VM in Cartouche, that can only execute pure functions.

# `address`

```elixir
@type address() :: <<_::160>>
```

# `code`

```elixir
@type code() :: [opcode()]
```

# `context_result`

```elixir
@type context_result() :: {:ok, Cartouche.VM.Context.t()} | {:error, vm_error()}
```

# `exec_opts`

```elixir
@type exec_opts() :: [callvalue: integer(), ffis: ffis()]
```

# `ffi`

```elixir
@type ffi() :: (binary() -> {:return, binary()} | {:revert, binary()})
```

# `ffis`

```elixir
@type ffis() :: %{required(address()) => ffi()}
```

# `opcode`

```elixir
@type opcode() :: Cartouche.Assembly.opcode()
```

# `signed`

```elixir
@type signed() :: integer()
```

# `unsigned`

```elixir
@type unsigned() :: non_neg_integer()
```

# `vm_error`

```elixir
@type vm_error() ::
  :pc_out_of_bounds
  | :value_overflow
  | :stack_underflow
  | :signed_integer_out_of_bounds
  | :out_of_memory
  | :invalid_operation
  | {:unknown_ffi, address()}
  | {:invalid_push, integer(), binary()}
  | {:impure, opcode()}
  | {:not_implemented, opcode()}
```

# `word`

```elixir
@type word() :: <<_::256>>
```

# `exec`

```elixir
@spec exec(code() | binary(), binary(), exec_opts()) ::
  {:ok, Cartouche.VM.ExecutionResult.t()} | {:error, vm_error()}
```

Executes the Ethereum Virtual Machine (EVM) with the given `code` and `input`.

**Parameters**
  - `code`: The bytecode to be executed, either as a `binary` or decoded.
  - `calldata`: The call data for the execution.
  - `opts`: Execution options (see below)

**Options**
  - `:callvalue`: value passed as callvalue for the execution.
  - `:ffis`: A mapping of address to functions to run as natively implemented ffis

Returns the result of the execution.

# `exec_call`

```elixir
@spec exec_call(code() | binary(), binary(), exec_opts()) ::
  {:ok, binary()} | {:revert, binary()}
```

Runs the given EVM, returning the `RETURN` data or the `REVERT` data.

Raises on any other exceptional state.

**Parameters**
  - `code`: The bytecode to be executed, either as a `binary` or decoded.
  - `calldata`: The call data for the execution.
  - `opts`: Execution options (see below)

**Options**
  - `:callvalue`: value passed as callvalue for the execution.
  - `:ffis`: A mapping of address to functions to run as natively implemented ffis

---

*Consult [api-reference.md](api-reference.md) for complete listing*