README.md

HTTP testing instances for Ethereum

Introduction

Prool is a library that provides programmatic HTTP testing instances for Ethereum. It is designed to be used in testing environments (e.g. Vitest) where you need to interact with an Ethereum server instance (e.g. Execution Node, 4337 Bundler, Indexer, etc) over HTTP or WebSocket.

Prool contains a set of pre-configured instances that can be used to simulate Ethereum server environments, being:

• Local Execution Nodes: anvil, tempo
• ERC-4337 Bundler Nodes: alto

You can also create your own custom instances by using the Instance.define function.

Table of Contents

• Install
• Getting Started
  • Anvil (Execution Node)
  • Alto (ERC-4337 Bundler Node)
• Reference
  • Server.create
  • Instance.define
  • Pool.define

Install

npm i prool

pnpm add prool

bun i prool

Getting Started

Anvil (Execution Node)

Requirements

curl -L https://foundry.paradigm.xyz | bash   # Install Foundry

Usage

import { Instance, Server } from 'prool'

const server = Server.create({
  instance: Instance.anvil(),
})

await server.start() 
// Instances accessible at:
// "http://localhost:8545/1"
// "http://localhost:8545/2"
// "http://localhost:8545/3"
// "http://localhost:8545/n"

Tempo (Execution Node)

Requirements

curl -L https://tempo.xyz/install | bash   # Install Tempo

Usage

import { Instance, Server } from 'prool'

const server = Server.create({
  instance: Instance.tempo(),
})

await server.start() 
// Instances accessible at:
// "http://localhost:8545/1"
// "http://localhost:8545/2"
// "http://localhost:8545/3"
// "http://localhost:8545/n"

Alto (Bundler Node)

Requirements

• @pimlico/alto: npm i @pimlico/alto

Usage

import { Instance, Server } from 'prool'

const executionServer = Server.create({
  instance: Instance.anvil(),
  port: 8545
})
await executionServer.start() 
// Instances accessible at:
// "http://localhost:8545/1"
// "http://localhost:8545/2"
// "http://localhost:8545/3"
// "http://localhost:8545/n"

const bundlerServer = Server.create({
  instance: (key) => Instance.alto({
    entrypoints: ['0x0000000071727De22E5E9d8BAf0edAc6f37da032'],
    rpcUrl: `http://localhost:8545/${key}`,
    executorPrivateKeys: ['0x...'],
  })
})
await bundlerServer.start()
// Instances accessible at:
// "http://localhost:3000/1" (→ http://localhost:8545/1)
// "http://localhost:3000/2" (→ http://localhost:8545/2)
// "http://localhost:3000/3" (→ http://localhost:8545/3)
// "http://localhost:3000/n" (→ http://localhost:8545/n)

Reference

Server.create

Creates a server that manages a pool of instances via a proxy.

Usage

import { Instance, Server } from 'prool'

const executionServer = Server.create({
  instance: Instance.anvil(),
})
await executionServer.start() 
// Instances accessible at:
// "http://localhost:8545/1"
// "http://localhost:8545/2"
// "http://localhost:8545/3"
// "http://localhost:8545/n"
// "http://localhost:8545/n/start"
// "http://localhost:8545/n/stop"
// "http://localhost:8545/n/restart"
// "http://localhost:8545/healthcheck"

Endpoints:

• /:key: Proxy to instance at key.
• /:key/start: Start instance at key.
• /:key/stop: Stop instance at key.
• /:key/restart: Restart instance at key.
• /healthcheck: Healthcheck endpoint.

API

Name	Description	Type
instance	Instance for the server.	Instance | (key: number) => Instance
limit	Number of instances that can be instantiated in the pool	number
host	Host for the server.	string
port	Port for the server.	number
returns	Server	Server.Server

Instance.define

Creates an instance definition, that can be used with Server.create or Pool.define.

Usage

import { Instance } from 'prool'

const foo = Instance.define((parameters: FooParameters) => {
 return {
   name: 'foo',
   host: 'localhost',
   port: 3000,
   async start() {
     // ...
   },
   async stop() {
     // ...
   },
 }
})

API

Name	Description	Type
fn	Instance definition.	DefineInstanceFn
returns	Instance.	Instance

Pool.define

Defines a pool of instances. Instances can be started, cached, and stopped against an identifier.

Usage

import { Instance, Pool } from 'prool'

const pool = Pool.define({
 instance: Instance.anvil(),
})
const instance_1 = await pool.start(1)
const instance_2 = await pool.start(2)
const instance_3 = await pool.start(3)

API

Name	Description	Type
instance	Instance for the pool.	Instance
limit	Number of instances that can be instantiated in the pool	number
returns	Pool.	Pool

Authors

• @jxom (jxom.eth, Twitter)
• @tmm (awkweb.eth, Twitter)

License

MIT License