prool

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

``bash
npm i prool
`

`bash
pnpm add prool
`

`bash
bun i prool
`

Getting Started

$3

#### Requirements

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

#### Usage

`ts
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"
`

$3

#### Requirements

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

#### Usage

`ts
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"
`

$3

#### Requirements

- @pimlico/alto: npm i @pimlico/alto

#### Usage

`ts
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

$3

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

#### Usage

`ts
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 |

$3

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

#### Usage

`ts
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 |

$3

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

#### Usage

`ts
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