World state: a read-only backend plus eevm's own write overlay.

It inspects as its backend and a count of pending writes, such as #EEVM.Database<EEVM.Database.InMemory, pending writes to 2 accounts and 1 storage slot>; read state with this module's functions, list the writes with changes/1, or pass structs: false to inspect/2 to see every field.

A backend implements this behaviour's read callbacks, account/2, code/2, storage/3, and block_hash/2. eevm never writes to it during execution: every balance, nonce, code, and storage write lands in the overlay this struct carries. Because a %EEVM.Database{} is an immutable value, reverting a call frame is just dropping its copy.

When a transaction or block finishes, changes/1 returns the overlay as an EEVM.StateChanges. EEVM.transact/4 and EEVM.Block.execute/4 hand it to the backend's commit/2 and return the committed database. When commit/2 returns {:error, :unsupported}, the result keeps the overlay and the caller applies result.changes itself. EEVM.run/2 never commits.

EEVM.StateRoot also needs to enumerate the backend, through accounts/1 and storage_slots/2. A backend that can't, such as one over JSON-RPC, returns {:error, :unsupported} from them and still executes transactions; the EIP-7610 check that a CREATE target has no storage then sees only the overlay.

Every callback is required, so what a backend can do is stated in its code: eevm never asks the code server which functions a module exports. use EEVM.Database declares the behaviour and defines commit/2, accounts/1, and storage_slots/2 to return {:error, :unsupported} until the module overrides them, so a read-only backend implements only the four reads.

EEVM.Database.InMemory implements every callback. This read-only backend serves a fixed map of accounts, so a call's writes stay in the overlay and commit/1 reports that the backend can't commit:

iex> defmodule MyApp.FixedDatabase do
...>   use EEVM.Database
...>   @impl true
...>   def account(accounts, address), do: {:ok, Map.get(accounts, address)}
...>   @impl true
...>   def code(_accounts, _code_hash), do: {:ok, <<>>}
...>   @impl true
...>   def storage(_accounts, _address, _slot), do: {:ok, 0}
...>   @impl true
...>   def block_hash(_accounts, _number), do: {:ok, nil}
...> end
iex> db = EEVM.Database.new(MyApp.FixedDatabase, %{0xA11CE => %{balance: 100, nonce: 0, code: <<>>}})
iex> {:ok, result} = EEVM.call(db, 0xB0B, <<>>, caller: 0xA11CE, value: 40)
iex> {EEVM.Database.get_balance(result.db, 0xA11CE), EEVM.Database.get_balance(result.db, 0xB0B)}
{60, 40}
iex> EEVM.Database.commit(result.db)
{:error, :commit_not_supported}

Read errors

A callback that returns {:error, reason} aborts execution: the entry point (EEVM.run/2, EEVM.transact/4, EEVM.Block.execute/4, or EEVM.Block.build/4) returns {:error, {:database, reason}}. Called directly, the functions in this module raise EEVM.Database.ReadError.

Deprecated backends

These still work for one minor version:

• A backend that leaves out commit/2, accounts/1, or storage_slots/2 (optional before #204) is treated as returning {:error, :unsupported}, and a bare enumerable from accounts/1 or storage_slots/2 is accepted.
• A commit/2, accounts/1, or storage_slots/2 that returns {:error, :not_supported}, the atom earlier docs used, is treated as returning {:error, :unsupported}.
• A module that implements only the pre-1.0 write and query callbacks (get_account/2, set_balance/3, storage_store/4, and so on) is wrapped in EEVM.Database.Legacy by new/2.