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

End-to-end transaction handler.

Orchestrates the per-transaction pipeline, deferring each phase to a
sibling module so the layering stays inspectable:

- `EEVM.Handler.Validation`    — decode → recover sender → validate
- `EEVM.Handler.PreExecution`  — charge upfront → intrinsic gas → bump nonce →
  apply EIP-7702 authorizations
- `EEVM.Handler.Execution`     — top-level CALL or CREATE through the EVM
- `EEVM.Handler.PostExecution` — settle refund, credit coinbase, build result

This split mirrors revm's `handler/` crate (`validation.rs`,
`pre_execution.rs`, `execution.rs`, `post_execution.rs`) and keeps each
phase independently testable.

# `opts`

```elixir
@type opts() :: [
  hardfork: EEVM.HardforkConfig.spec_id(),
  chain_id: non_neg_integer(),
  config: EEVM.Config.t()
]
```

# `wire_tx`

```elixir
@type wire_tx() :: EEVM.Handler.Validation.wire_tx()
```

# `execute`

```elixir
@spec execute(wire_tx(), EEVM.Context.Block.t(), EEVM.Database.t(), opts()) ::
  {:ok, EEVM.TransactionResult.t()} | {:error, atom()}
```

Execute a single transaction end-to-end.

`tx_or_bytes` may be either raw wire bytes (legacy RLP or a typed envelope
prefix + RLP) or one of the typed `EEVM.Transaction.*` structs.

## Options

- `:chain_id` — chain id used when recovering the sender and checking
  EIP-7702 authorization tuples (default: `1`).
- `:hardfork` — hardfork spec id governing gas rules and EIP activation
  (default: `:cancun`).
- `:config` — fully assembled `EEVM.Config` to use instead of deriving one
  from `:hardfork`. Takes precedence when both are provided.

## Returns

- `{:ok, %EEVM.TransactionResult{}}` for any transaction that made it past
  validation — including reverted ones. Inspect `result.status` to tell
  success from revert.
- `{:error, reason}` when decoding, sender recovery, validation, or upfront
  balance charging fail. The database is returned unchanged in that case.

---

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