From 83cb03a7edb9512085045b5a62783d958e4c4d55 Mon Sep 17 00:00:00 2001 From: Tom Meagher Date: Tue, 11 Jun 2024 19:30:14 -0400 Subject: [PATCH] chore: add readme/license to src for publishing --- LICENSE | 22 +--- README.md | 293 +------------------------------------------------ src/LICENSE | 21 ++++ src/README.md | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 321 insertions(+), 313 deletions(-) mode change 100644 => 120000 LICENSE mode change 100644 => 120000 README.md create mode 100644 src/LICENSE create mode 100644 src/README.md diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 4116d58..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2024-present weth, LLC - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/LICENSE b/LICENSE new file mode 120000 index 0000000..da348fc --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +src/LICENSE \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 39580b2..0000000 --- a/README.md +++ /dev/null @@ -1,292 +0,0 @@ -
- -

- - - mipd logo - -

- -

- HTTP testing instances for Ethereum -

- -

- - - - Version - - - - - - MIT License - - -

- -## 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](https://vitest.dev/)) 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`](#anvil-execution-node) -- **Bundler Nodes:** [`alto`](#alto-bundler-node), `rundler`⚠️, `silius`⚠️, [`stackup`](#stackup-bundler-node) -- **Indexer Nodes:** `ponder`⚠️ - -⚠️ = soon - -You can also create your own custom instances by using the [`defineInstance` function](#defineinstance). - -## Table of Contents - -- [Install](#install) -- [Getting Started](#getting-started) - - [Anvil (Execution Node)](#anvil-execution-node) - - [Alto (Bundler Node)](#alto-bundler-node) - - [Stackup (Bundler Node)](#stackup-bundler-node) -- [Reference](#reference) - - [`createServer`](#createserver) - - [`defineInstance`](#defineinstance) - - [`definePool`](#definepool) - - -## Install - -```bash -npm i prool -``` - -```bash -pnpm add prool -``` - -```bash -bun i prool -``` - -## Getting Started - -### Anvil (Execution Node) - -#### Requirements - -- [Foundry](https://getfoundry.sh/): `curl -L https://foundry.paradigm.xyz | bash` - -#### Usage - -```ts -import { createServer } from 'prool' -import { anvil } from 'prool/instances' - -const server = createServer({ - instance: anvil(), -}) - -await server.start() -// Instances accessible at: -// "http://localhost:8545/1" -// "http://localhost:8545/2" -// "http://localhost:8545/3" -// "http://localhost:8545/n" -``` - -#### Parameters - -See [`AnvilParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/anvil.ts#L5). - -### Alto (Bundler Node) - -#### Requirements - -- [`@pimlico/alto`](npm.im/@pimlico/alto): `npm i @pimlico/alto` - -#### Usage - -```ts -import { createServer } from 'prool' -import { anvil, alto } from 'prool/instances' - -const executionServer = createServer({ - 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 = createServer({ - instance: (key) => 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) -``` - -#### Parameters - -See [`AltoParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/alto.ts#L7). - -### Stackup (Bundler Node) - -#### Requirements - -- [Docker](https://docs.docker.com/get-docker/) -- Stackup Docker Image: `docker pull stackupwallet/stackup-bundler:latest` - -#### Usage - -```ts -import { createServer } from 'prool' -import { anvil, stackup } from 'prool/instances' - -const executionServer = createServer({ - 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 = createServer({ - instance: (key) => stackup({ - ethClientUrl: `http://localhost:8545/${key}`, - privateKey: '0x...', - }) -}) -await bundlerServer.start() -// Instances accessible at: -// "http://localhost:4337/1" (→ http://localhost:8545/1) -// "http://localhost:4337/2" (→ http://localhost:8545/2) -// "http://localhost:4337/3" (→ http://localhost:8545/3) -// "http://localhost:4337/n" (→ http://localhost:8545/n) -``` - -#### Parameters - -See [`StackupParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/stackup.ts#L5). - -## Reference - -### `createServer` - -Creates a server that manages a pool of instances via a proxy. - -#### Usage - -```ts -import { createServer } from 'prool' -import { anvil } from 'prool/instances' - -const executionServer = createServer({ - 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 | `CreateServerReturnType` | - -### `defineInstance` - -Creates an instance definition, that can be used with [`createServer`](#createserver) or [`definePool`](#definepool). - -#### Usage - -```ts -import { defineInstance } from 'prool' - -const foo = defineInstance((parameters: FooParameters) => { - return { - name: 'foo', - host: 'localhost', - port: 3000, - async start() { - // ... - }, - async stop() { - // ... - }, - } -}) -``` - -#### API - -| Name | Description | Type | -| ------- | -------------------- | ------------------ | -| `fn` | Instance definition. | `DefineInstanceFn` | -| returns | Instance. | `Instance` | - -### `definePool` - -Defines a pool of instances. Instances can be started, cached, and stopped against an identifier. - -#### Usage - -```ts -import { definePool } from 'prool' -import { anvil } from 'prool/instances' - -const pool = definePool({ - 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](https://github.com/jxom) (jxom.eth, [Twitter](https://twitter.com/jakemoxey)) -- [@tmm](https://github.com/tmm) (awkweb.eth, [Twitter](https://twitter.com/awkweb)) - -## License - -[MIT](/LICENSE) License diff --git a/README.md b/README.md new file mode 120000 index 0000000..351df1d --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +src/README.md \ No newline at end of file diff --git a/src/LICENSE b/src/LICENSE new file mode 100644 index 0000000..4116d58 --- /dev/null +++ b/src/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024-present weth, LLC + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..c433a9a --- /dev/null +++ b/src/README.md @@ -0,0 +1,298 @@ +
+ +

+ + + mipd logo + +

+ +

+ HTTP testing instances for Ethereum +

+ +

+ + + + Version + + + + + + MIT License + + + + + + Downloads per month + + +

+ +## 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](https://vitest.dev/)) 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`](#anvil-execution-node) +- **Bundler Nodes:** [`alto`](#alto-bundler-node), `rundler`⚠️, `silius`⚠️, [`stackup`](#stackup-bundler-node) +- **Indexer Nodes:** `ponder`⚠️ + +⚠️ = soon + +You can also create your own custom instances by using the [`defineInstance` function](#defineinstance). + +## Table of Contents + +- [Install](#install) +- [Getting Started](#getting-started) + - [Anvil (Execution Node)](#anvil-execution-node) + - [Alto (Bundler Node)](#alto-bundler-node) + - [Stackup (Bundler Node)](#stackup-bundler-node) +- [Reference](#reference) + - [`createServer`](#createserver) + - [`defineInstance`](#defineinstance) + - [`definePool`](#definepool) + + +## Install + +```bash +npm i prool +``` + +```bash +pnpm add prool +``` + +```bash +bun i prool +``` + +## Getting Started + +### Anvil (Execution Node) + +#### Requirements + +- [Foundry](https://getfoundry.sh/): `curl -L https://foundry.paradigm.xyz | bash` + +#### Usage + +```ts +import { createServer } from 'prool' +import { anvil } from 'prool/instances' + +const server = createServer({ + instance: anvil(), +}) + +await server.start() +// Instances accessible at: +// "http://localhost:8545/1" +// "http://localhost:8545/2" +// "http://localhost:8545/3" +// "http://localhost:8545/n" +``` + +#### Parameters + +See [`AnvilParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/anvil.ts#L5). + +### Alto (Bundler Node) + +#### Requirements + +- [`@pimlico/alto`](npm.im/@pimlico/alto): `npm i @pimlico/alto` + +#### Usage + +```ts +import { createServer } from 'prool' +import { anvil, alto } from 'prool/instances' + +const executionServer = createServer({ + 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 = createServer({ + instance: (key) => 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) +``` + +#### Parameters + +See [`AltoParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/alto.ts#L7). + +### Stackup (Bundler Node) + +#### Requirements + +- [Docker](https://docs.docker.com/get-docker/) +- Stackup Docker Image: `docker pull stackupwallet/stackup-bundler:latest` + +#### Usage + +```ts +import { createServer } from 'prool' +import { anvil, stackup } from 'prool/instances' + +const executionServer = createServer({ + 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 = createServer({ + instance: (key) => stackup({ + ethClientUrl: `http://localhost:8545/${key}`, + privateKey: '0x...', + }) +}) +await bundlerServer.start() +// Instances accessible at: +// "http://localhost:4337/1" (→ http://localhost:8545/1) +// "http://localhost:4337/2" (→ http://localhost:8545/2) +// "http://localhost:4337/3" (→ http://localhost:8545/3) +// "http://localhost:4337/n" (→ http://localhost:8545/n) +``` + +#### Parameters + +See [`StackupParameters`](https://github.com/wevm/prool/blob/801ede06ded8b2cb2d59c95294aae795e548897c/src/instances/stackup.ts#L5). + +## Reference + +### `createServer` + +Creates a server that manages a pool of instances via a proxy. + +#### Usage + +```ts +import { createServer } from 'prool' +import { anvil } from 'prool/instances' + +const executionServer = createServer({ + 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 | `CreateServerReturnType` | + +### `defineInstance` + +Creates an instance definition, that can be used with [`createServer`](#createserver) or [`definePool`](#definepool). + +#### Usage + +```ts +import { defineInstance } from 'prool' + +const foo = defineInstance((parameters: FooParameters) => { + return { + name: 'foo', + host: 'localhost', + port: 3000, + async start() { + // ... + }, + async stop() { + // ... + }, + } +}) +``` + +#### API + +| Name | Description | Type | +| ------- | -------------------- | ------------------ | +| `fn` | Instance definition. | `DefineInstanceFn` | +| returns | Instance. | `Instance` | + +### `definePool` + +Defines a pool of instances. Instances can be started, cached, and stopped against an identifier. + +#### Usage + +```ts +import { definePool } from 'prool' +import { anvil } from 'prool/instances' + +const pool = definePool({ + 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](https://github.com/jxom) (jxom.eth, [Twitter](https://twitter.com/jakemoxey)) +- [@tmm](https://github.com/tmm) (awkweb.eth, [Twitter](https://twitter.com/awkweb)) + +## License + +[MIT](/LICENSE) License