# 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 are evm2's. 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 in evm2.

## 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, { envelope, signer })
TxResult.txGasUsed(result)
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.callTx`](/evm/execution/Evm/callTx) | Executes a transaction and discards its state changes. |
| [`Evm.create`](/evm/execution/Evm/create) | Creates an EVM. |
| [`Evm.readAccountInfo`](/evm/execution/Evm/readAccountInfo) | Reads an account through the EVM, including any state it has accepted. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.AbiError`](/evm/execution/Evm/errors#evmabierror) | Thrown when the adapter rejected a request this codec produced. |
| [`Evm.DatabaseError`](/evm/execution/Evm/errors#evmdatabaseerror) | Thrown when a state read failed. Carries the source's own message. |
| [`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 evm2 rejected or aborted the transaction. |
| [`Evm.MissingError`](/evm/execution/Evm/errors#evmmissingerror) | Thrown when an operation runs against a destroyed engine. |
| [`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.UnknownStopError`](/evm/execution/Evm/errors#evmunknownstoperror) | Thrown when the engine reports a stop reason this version does not know. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Evm.Block`](/evm/execution/Evm/types#evmblock) | Block values opcodes read. |
| [`Evm.Evm`](/evm/execution/Evm/types#evmevm) | An EVM. |