# `EEVM.Tracer`
[🔗](https://github.com/mw2000/eevm/blob/main/lib/eevm/tracer.ex#L1)

Opt-in opcode-level execution tracer.

A tracer is attached to a `MachineState` (via `MachineState.new/2` with
`tracer: EEVM.Tracer.new()`). When present, the executor records one
`TraceStep` per opcode with pre-execution PC, stack, memory size, and
depth plus the actual gas cost charged by that step.

Output is compatible with the `evm --json` format defined by EIP-3155,
so traces can be diffed against geth/revm reference runs.

## Performance

When the `tracer` field is `nil` (default), the executor skips all trace
bookkeeping — no snapshot is taken and the tracer branch is a single
pattern-match-and-return. Trace capture is opt-in at the call site.

# `snapshot`

```elixir
@type snapshot() :: %{
  pc: non_neg_integer(),
  op_byte: non_neg_integer(),
  op: atom(),
  gas: non_neg_integer(),
  stack: [non_neg_integer()],
  memory_size: non_neg_integer(),
  depth: non_neg_integer(),
  refund: non_neg_integer()
}
```

# `t`

```elixir
@type t() :: %EEVM.Tracer{steps: [EEVM.Tracer.TraceStep.t()]}
```

# `new`

```elixir
@spec new() :: t()
```

# `op_name`

```elixir
@spec op_name(non_neg_integer()) :: atom()
```

Returns the opcode name atom for a byte (e.g. `0x01` -> `:ADD`).

# `record`

```elixir
@spec record(t(), EEVM.Tracer.TraceStep.t()) :: t()
```

# `set_last_error`

```elixir
@spec set_last_error(t(), atom()) :: t()
```

Marks the most recently recorded step with an error reason.

# `steps`

```elixir
@spec steps(t()) :: [EEVM.Tracer.TraceStep.t()]
```

Returns the recorded steps in execution order.

# `to_json`

```elixir
@spec to_json(t()) :: String.t()
```

Renders the trace as a single newline-joined JSON string.

# `to_json_lines`

```elixir
@spec to_json_lines(t()) :: [String.t()]
```

Renders the trace as EIP-3155 / geth `--json` compatible JSON lines.

Returns a list of JSON-encoded strings, one per step. Join with newlines
for geth-style output.

---

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