# 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.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. |
| [`Evm.transact`](/evm/execution/Evm/transact) | Executes a transaction and leaves its state changes pending. |

## 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.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. |