Skip to content
This repository has been archived by the owner on Jun 13, 2024. It is now read-only.

wevm/anvil.js

Repository files navigation

Warning

This library is deprecated. We recommend consumers to use Prool.

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

License

MIT License