AnvilJS

TypeScript wrapper for Foundry Anvil. AnvilJS provides a simple API to create and manage Anvil instances programmatically.

import { createAnvil } from "@viem/anvil";

const anvil = createAnvil({
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

await anvil.start();
await anvil.stop();

Install

pnpm add @viem/anvil

npm i @viem/anvil

yarn add @viem/anvil

Note Anvil is required to use @viem/anvil. Please refer to the foundry book for Anvil installation instructions.

API

createAnvil

Creates anvil instance.

| Name | Description | Type | | ------------ | --------------------------------------- | ---------------------- | | options | Options used to create anvil instance | CreateAnvilOptions | | returns | Anvil instance | Anvil |

Usage

import { createAnvil } from "@viem/anvil";

const anvil = createAnvil({
  // All anvil options are supported & typed.
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

await anvil.start();
await anvil.stop();

getVersion

Get anvil version.

| Name | Description | Type | | ------------ | --------------------------------------- | ---------- | | command | Path to anvil command. Default anvil. | string | | returns | anvil version | string |

Usage

import { getVersion } from "@viem/anvil";

const version = await getVersion();

createProxy

Creates and starts a proxy server that spawns anvil instance on demand (e.g. per test file or per test case).

| Name | Description | Type | | --------- | -------------------------------------- | -------------------- | | options | Options used to create proxy server. | CreateProxyOptions | | returns | Server instance | Server |

Usage

import { createProxy, createPool } from "@viem/anvil";

const server = await createProxy({
  pool: createPool(),
  options: {
    forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
    forkBlockNumber: 12345678n,
  },
});

server.listen(8545, "::", () => {
  console.log("Proxy server listening on http://0.0.0.0:8545");
});

createPool

Creates pool of anvil instances.

| Name | Description | Type | | --------- | --------------------------------- | -------------------- | | options | Options used to create pool. | CreatePoolOptions | | returns | Pool | Pool |

Usage

import { createPool } from "@viem/anvil";

const pool = createPool();
await pool.start(1, {
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});
await pool.start(2, {
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

startProxy

Creates and starts a proxy server that spawns anvil instance on demand (e.g. per test file or per test case).

| Name | Description | Type | | --------- | ---------------------------------------------------------------- | ------------------------- | | options | Options used to spawn anvil instance. | StartProxyOptions | | returns | Function to shut down the proxy and all spawned anvil instances. | () => Awaitable<void> |

Usage

import { startProxy } from "@viem/anvil";

// Returns a function to shut down the proxy and all spawned anvil instances.
const shutdown = await startProxy({
  port: 8555,
  options: {
    forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
    forkBlockNumber: 12345678n,
  },
});

// Shut down the proxy and all spawned anvil instances.
await shutdown();

fetchLogs

Fetches logs for anvil instances.

| Name | Description | Type | | -------- | ----------------------- | ------------------- | | url | URL to anvil proxy. | string | | id | ID of test worker. | number | | returns | Logs of anvil instance. | string[] |

Usage

import { fetchLogs } from "@viem/anvil";

const logs = await fetchLogs("http://localhost:8545", 1);
// Only print the 20 most recent log messages.
console.log(...logs.slice(-20));

Types

import type {
  Anvil,
  AnvilOptions,
  AnvilProxyOptions,
  AnvilProxyOptionsFn,
  CreateAnvilOptions,
  CreateProxyOptions,
  CreatePoolOptions,
  Pool,
  ProxyRequestContext,
  ProxyRequestHandler,
  ProxyResponse,
  ProxyResponseFailure,
  ProxyResponseSuccess,
  StartProxyOptions,
} from "@viem/anvil";

Contributing

If you're interested in contributing, please read the contributing docs before submitting a pull request.

Authors

• @fubhy (fubhy.eth, Twitter)

License

MIT License