@viem/anvil NPM

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";