Prool

Common errors

• TypeError: Instance.tempoDocker is not a function

  cause After upgrading to `prool` v0.2.0 or later, the `tempoDocker` instance was moved and renamed.
  fix Update your import statement to `import { Instance } from 'prool/testcontainers'` and change `Instance.tempoDocker` to `Instance.tempo`.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead, change the require of index.js in ... to a dynamic import() call.

  cause Attempting to use CommonJS `require()` syntax with Prool, which is an ESM-first library requiring Node.js >=22.
  fix Switch to ESM `import` statements: `import { Server } from 'prool'` instead of `const { Server } = require('prool')`.

• Error: Tempo container failed to start: Error: connect ECONNREFUSED 127.0.0.1:XXXX

  cause On macOS, prior to `v0.2.4`, containerized instances like Tempo might have issues with port binding and host networking, leading to connection refusals.
  fix Upgrade Prool to `v0.2.4` or newer to leverage the fix for macOS host networking. Ensure Docker Desktop is running and healthy.

• Error: Command failed with exit code 1: foundryup

  cause The `Instance.anvil()` relies on the `anvil` executable from Foundry, which is not found in the system's PATH.
  fix Install Foundry globally by running `curl -L https://foundry.paradigm.xyz | bash` and ensure it's added to your shell's PATH.

Warnings

• breaking The `Instance.tempoDocker` property was removed and its functionality was moved to a new entrypoint `prool/testcontainers`. The method itself was renamed to `Instance.tempo`.
  Fix: Change your import from `import { Instance } from 'prool'` to `import { Instance } from 'prool/testcontainers'` and update `Instance.tempoDocker` to `Instance.tempo`.
• breaking Several pre-configured instances, specifically `silius`, `stackup`, and `rundler`, were removed from the library.
  Fix: If you were using these instances, you will need to migrate to alternative solutions or define a custom instance using `Instance.define` if the underlying service is still supported elsewhere.
• gotcha Prool requires Node.js version 22 or higher due to its use of modern JavaScript features and ESM-first design.
  Fix: Ensure your Node.js environment is updated to version 22 or later. You can use a version manager like `nvm` to switch Node.js versions: `nvm install 22 && nvm use 22`.
• gotcha For containerized instances (e.g., Tempo via `prool/testcontainers`), macOS users might experience connectivity issues if running versions older than `v0.2.4` due to host networking configurations. Prior versions might not correctly bind to `127.0.0.1`.
  Fix: Upgrade Prool to `v0.2.4` or newer. This version fixes the issue by ensuring containers bind to `127.0.0.1` with dynamically mapped exposed ports.
• gotcha Using instances like `Instance.anvil()` or `Instance.tempo()` requires the respective CLI tools (Foundry or Tempo CLI) to be installed globally on your system, or accessible in your PATH.
  Fix: Install Foundry (for Anvil) via `curl -L https://foundry.paradigm.xyz | bash` or Tempo CLI (for Tempo) via `curl -L https://tempo.xyz/install | bash`.

Install

• npm install prool npm
• yarn add prool yarn
• pnpm add prool pnpm

Imports

• Server
  wrong:

  const { Server } = require('prool')

  correct:

  import { Server } from 'prool'

  Prool is an ESM-first library; CommonJS `require` will lead to errors in Node.js environments. Use `import` statements.
• Instance
  wrong:

  const { Instance } = require('prool')

  correct:

  import { Instance } from 'prool'

  The main `Instance` object for common instances like Anvil and Alto. For Tempo (containerized), see the `prool/testcontainers` entrypoint.
• Instance.tempo
  wrong:

  import { Instance } from 'prool'; Instance.tempoDocker

  correct:

  import { Instance } from 'prool/testcontainers'

  Since `v0.2.0`, containerized instances like Tempo were moved to the `prool/testcontainers` entrypoint and `tempoDocker` was renamed to `tempo`.

Quickstart

Demonstrates how to create and manage an Anvil execution node instance using Prool, including starting and stopping the server, and noting required external dependencies.

import { Instance, Server } from 'prool';

// NOTE: Requires Foundry to be installed globally:
// `curl -L https://foundry.paradigm.xyz | bash`

async function runAnvilServer() {
  const server = Server.create({
    instance: Instance.anvil(),
    port: 8545 // Optional, default is 8545
  });

  try {
    console.log('Starting Anvil server...');
    await server.start();
    console.log('Anvil server started successfully!');
    console.log('Instances accessible at:');
    // Access the base URL for instances, e.g., for direct RPC calls
    // `server.url` returns 'http://localhost:8545/'
    // The specific instances are accessed via paths, e.g., 'http://localhost:8545/1'
    console.log(`  Base URL: ${server.url}`);
    console.log('  Example instance URL: http://localhost:8545/1');

    // Simulate some work or keep it running for a test suite
    await new Promise(resolve => setTimeout(resolve, 5000)); // Keep alive for 5 seconds

  } catch (error) {
    console.error('Failed to start Anvil server:', error);
  } finally {
    console.log('Stopping Anvil server...');
    await server.stop();
    console.log('Anvil server stopped.');
  }
}

runAnvilServer();