# Evm

An EVM, backed by [`alloy-rs/evm2`](https://github.com/alloy-rs/evm2)
compiled to WebAssembly.

Execution, gas accounting, transaction validation, precompiles, and fork
behavior come from the engine. Ox supplies the TypeScript representation of
its API and the runtime packaging.

Creation is asynchronous because WebAssembly must be compiled asynchronously.
Execution is synchronous, as it is natively.

## Examples

```ts twoslash
// @noErrors
import { Database, Evm, TxResult } from 'ox/evm'

const evm = await Evm.create({
  database: Database.fromMemory({
    accounts: {
      '0x0000000000000000000000000000000000000001': {
        balance: 1n
      }
    }
  })
})

const result = Evm.callTx(evm, {
  from: '0x0000000000000000000000000000000000000001',
  gas: 100_000n,
  to: '0x0000000000000000000000000000000000000002',
  value: 1n
})
TxResult.txGasUsed(result)
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.callTx`](/evm/execution/Evm/callTx) | Executes a transaction and discards its state changes. |
| [`Evm.clearBal`](/evm/execution/Evm/clearBal) | Removes the attached block access list, so reads go to the database again. |
| [`Evm.clearBalBuilder`](/evm/execution/Evm/clearBalBuilder) | Discards the block access list being built, without reading it. |
| [`Evm.clearInspector`](/evm/execution/Evm/clearInspector) | Removes the inspector. |
| [`Evm.commitSource`](/evm/execution/Evm/commitSource) | Applies state a caller holds to the EVM. |
| [`Evm.create`](/evm/execution/Evm/create) | Creates an EVM. |
| [`Evm.enableBalBuilder`](/evm/execution/Evm/enableBalBuilder) | Starts building a block access list from what executions touch. |
| [`Evm.readAccountInfo`](/evm/execution/Evm/readAccountInfo) | Reads an account through the EVM, including any state it has accepted. |
| [`Evm.setBal`](/evm/execution/Evm/setBal) | Attaches a block access list, which covered reads are served from. |
| [`Evm.setBalIndex`](/evm/execution/Evm/setBalIndex) | Sets the block access index reads resolve at and writes record under. |
| [`Evm.setBlock`](/evm/execution/Evm/setBlock) | Replaces the block environment. |
| [`Evm.setBlockAndExecutionConfig`](/evm/execution/Evm/setBlockAndExecutionConfig) | Replaces the block environment, the specification, and its version together. |
| [`Evm.setExecutionConfig`](/evm/execution/Evm/setExecutionConfig) | Replaces the specification and its version overrides. |
| [`Evm.setInspector`](/evm/execution/Evm/setInspector) | Installs an inspector, so executions record what they did. |
| [`Evm.startBlockState`](/evm/execution/Evm/startBlockState) | Starts gathering what a block's transactions change. |
| [`Evm.systemCall`](/evm/execution/Evm/systemCall) | Executes a protocol system call. |
| [`Evm.takeBal`](/evm/execution/Evm/takeBal) | Takes the built block access list, resetting the index. |
| [`Evm.takeBlockState`](/evm/execution/Evm/takeBlockState) | Takes what the block changed, consuming the token. |
| [`Evm.transact`](/evm/execution/Evm/transact) | Executes a transaction and leaves its state changes pending. |
| [`Evm.warmPrecompiles`](/evm/execution/Evm/warmPrecompiles) | Marks the precompile addresses warm. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.AbiError`](/evm/execution/Evm/errors#evmabierror) | Thrown when the adapter rejected a request this codec produced. |
| [`Evm.BorrowedError`](/evm/execution/Evm/errors#evmborrowederror) | Thrown when an unresolved executed transaction still holds the engine. |
| [`Evm.DatabaseError`](/evm/execution/Evm/errors#evmdatabaseerror) | Thrown when a state read failed. Carries the source's own message. |
| [`Evm.DecodeError`](/evm/execution/Evm/errors#evmdecodeerror) | Thrown when a response does not match the ABI the codec expects. |
| [`Evm.EncodeError`](/evm/execution/Evm/errors#evmencodeerror) | Thrown when a value does not fit the wire width the ABI declares. |
| [`Evm.HandlerError`](/evm/execution/Evm/errors#evmhandlererror) | Thrown when the engine rejected or aborted the transaction. |
| [`Evm.MissingError`](/evm/execution/Evm/errors#evmmissingerror) | Thrown when an operation runs against a destroyed engine. |
| [`Evm.NoBlockStateError`](/evm/execution/Evm/errors#evmnoblockstateerror) | Thrown when a state-change sink refused a record. |
| [`Evm.NotCoveredError`](/evm/execution/Evm/errors#evmnotcoverederror) |  |
| [`Evm.NotExecutedError`](/evm/execution/Evm/errors#evmnotexecutederror) | Thrown when a resolution named no outstanding executed transaction. |
| [`Evm.ReentrancyError`](/evm/execution/Evm/errors#evmreentrancyerror) | Thrown when a host read reenters the engine that is calling it. |
| [`Evm.RequestTooLargeError`](/evm/execution/Evm/errors#evmrequesttoolargeerror) | Thrown when a request exceeds what the adapter accepts. |
| [`Evm.TrapError`](/evm/execution/Evm/errors#evmtraperror) | Thrown when the engine trapped. |
| [`Evm.UnknownStopError`](/evm/execution/Evm/errors#evmunknownstoperror) | Thrown when the engine reports a stop reason this version does not know. |
| [`Evm.VersionError`](/evm/execution/Evm/errors#evmversionerror) | Thrown when the compiled artifact implements a different ABI version. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.Awaitable`](/evm/execution/Evm/types#evmawaitable) | A value an operation returns, wrapped in a promise when reads are asynchronous. |
| [`Evm.Block`](/evm/execution/Evm/types#evmblock) | Block values opcodes read. |
| [`Evm.Evm`](/evm/execution/Evm/types#evmevm) | An EVM. |
| [`Evm.Feature`](/evm/execution/Evm/types#evmfeature) | Feature flags a version can turn on or off. |
| [`Evm.GasId`](/evm/execution/Evm/types#evmgasid) | Gas parameters a version can replace. |
| [`Evm.Version`](/evm/execution/Evm/types#evmversion) | Version values an execution runs under. |