prool 0.0.24 → 0.1.0

package/src/instances/alto.ts

@@ -0,0 +1,289 @@
+import { resolve } from 'node:path'
+import * as Instance from '../Instance.js'
+import { toArgs } from '../internal/utils.js'
+import { execa } from '../processes/execa.js'
+
+/**
+ * Defines an Alto instance.
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.alto({
+ *  entrypoints: ['0x0000000071727De22E5E9d8BAf0edAc6f37da032'],
+ *  rpcUrl: `http://localhost:8545`,
+ *  executorPrivateKeys: ['0x...'],
+ * })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const alto = Instance.define((parameters?: alto.Parameters) => {
+  const { ...args } = (parameters || {}) as alto.Parameters
+
+  const name = 'alto'
+  const process = execa({ name })
+
+  return {
+    _internal: {
+      args,
+      get process() {
+        return process._internal.process
+      },
+    },
+    host: 'localhost',
+    name,
+    port: args.port ?? 3000,
+    async start({ port = args.port ?? 3000 }, options) {
+      const binary = (() => {
+        if (args.binary) return [args.binary]
+        const libPath = (
+          'resolve' in import.meta
+            ? import.meta.resolve('@pimlico/alto').split('file:')[1]
+            : require.resolve('@pimlico/alto')
+        )!
+        return ['node', resolve(libPath, '../cli/alto.js')]
+      })()
+
+      await process.start(($) => $`${binary} ${toArgs({ port, ...args })}`, {
+        ...options,
+        // Resolve when the process is listening via a "Server listening at" message.
+        resolver({ process, reject, resolve }) {
+          process.stdout.on('data', (data) => {
+            const message = data.toString()
+            if (message.includes('Server listening at')) resolve()
+          })
+          process.stderr.on('data', reject)
+        },
+      })
+    },
+    async stop() {
+      await process.stop()
+    },
+  }
+})
+
+export declare namespace alto {
+  export type Parameters = {
+    /**
+     * API version (used for internal Pimlico versioning compatibility).
+     */
+    apiVersion?: readonly string[] | undefined
+    /**
+     * Override the sender native token balance during estimation
+     */
+    balanceOverride?: boolean | undefined
+    /**
+     * Binary path of the `alto` executable.
+     */
+    binary?: string | undefined
+    /**
+     * Address of the `BundleBulker` contract.
+     */
+    bundleBulkerAddress?: `0x${string}` | undefined
+    /**
+     * Set if the bundler bundle user operations automatically or only when calling `debug_bundler_sendBundleNow`.
+     * @default "auto"
+     */
+    bundleMode?: 'auto' | 'manual' | undefined
+    /**
+     * Indicates weather the chain is a OP stack chain, arbitrum chain, or default EVM chain.
+     */
+    chainType?: 'default' | 'op-stack' | 'arbitrum' | undefined
+    /**
+     * Path to JSON config file.
+     */
+    config?: string | undefined
+    /**
+     * Skip user operation validation, use with caution.
+     */
+    dangerousSkipUserOperationValidation?: boolean | undefined
+    /**
+     * Default API version.
+     */
+    defaultApiVersion?: string | undefined
+    /**
+     * Enable debug endpoints.
+     * @default false
+     */
+    enableDebugEndpoints?: boolean | undefined
+    /**
+     * Include user ops with the same sender in the single bundle.
+     * @default true
+     */
+    enforceUniqueSendersPerBundle?: boolean | undefined
+    /**
+     * EntryPoint contract addresses.
+     */
+    entrypoints: readonly `0x${string}`[]
+    /**
+     * Address of the EntryPoint simulations contract.
+     */
+    entrypointSimulationContract?: `0x${string}` | undefined
+    /**
+     * Private keys of the executor accounts.
+     */
+    executorPrivateKeys?: readonly `0x${string}`[]
+    /**
+     * Interval to refill the signer balance (seconds).
+     * @default 1200
+     */
+    executorRefillInterval?: number | undefined
+    /**
+     * Should the node make expiration checks.
+     * @default true
+     */
+    expirationCheck?: boolean | undefined
+    /**
+     * Amount to multiply the gas prices fetched from the node.
+     * @default "100"
+     */
+    gasPriceBump?: string | undefined
+    /**
+     * Maximum that the gas prices fetched using pimlico_getUserOperationGasPrice will be accepted for (seconds).
+     * @default 10
+     */
+    gasPriceExpiry?: number | undefined
+    /**
+     * The minimum percentage of incoming user operation gas prices compared to the gas price used by the bundler to submit bundles.
+     * @default 101
+     */
+    gasPriceFloorPercent?: number | undefined
+    /**
+     * Amount to multiply the gas prices fetched using `pimlico_getUserOperationGasPrice`.
+     * @default "105,110,115"
+     */
+    gasPriceMultipliers?: readonly string[] | undefined
+    /**
+     * Use a fixed value for gas limits during bundle transaction gas limit estimations
+     */
+    fixedGasLimitForEstimation?: string | undefined
+    /**
+     * Flush stuck transactions with old nonces during bundler startup.
+     */
+    flushStuckTransactionsDuringStartup?: boolean | undefined
+    /**
+     * Log in JSON format.
+     */
+    json?: boolean | undefined
+    /**
+     * Send legacy transactions instead of an EIP-1559 transactions.
+     * @default false
+     */
+    legacyTransactions?: boolean | undefined
+    /**
+     * Calculate the bundle transaction gas limits locally instead of using the RPC gas limit estimation.
+     */
+    localGasLimitCalculation?: boolean | undefined
+    /**
+     * Default log level.
+     */
+    logLevel?:
+      | 'trace'
+      | 'debug'
+      | 'info'
+      | 'warn'
+      | 'error'
+      | 'fatal'
+      | undefined
+    /**
+     * Max block range for `eth_getLogs` calls.
+     */
+    maxBlockRange?: number | undefined
+    /**
+     * Maximum number of operations allowed in the mempool before a bundle is submitted.
+     * @default 10
+     */
+    maxBundleSize?: number | undefined
+    /**
+     * Maximum time to wait for a bundle to be submitted (ms).
+     * @default 1000
+     */
+    maxBundleWait?: number | undefined
+    /**
+     * Maximum amount of gas per bundle.
+     * @default "5000000"
+     */
+    maxGasPerBundle?: string | undefined
+    /**
+     * Maximum number of executor accounts to use from the list of executor private keys.
+     */
+    maxExecutors?: number | undefined
+    /**
+     * Maximum amount of parallel user ops to keep in the meempool (same sender, different nonce keys).
+     * @default 10
+     */
+    mempoolMaxParallelOps?: number | undefined
+    /**
+     * Maximum amount of sequential user ops to keep in the mempool (same sender and nonce key, different nonce values).
+     * @default 0
+     */
+    mempoolMaxQueuedOps?: number | undefined
+    /**
+     * Minimum stake required for a relay (in 10e18).
+     * @default 1
+     */
+    minEntityStake?: number | undefined
+    /**
+     * Minimum unstake delay (seconds).
+     * @default 1
+     */
+    minEntityUnstakeDelay?: number | undefined
+    /**
+     * Minimum balance required for each executor account (below which the utility account will refill).
+     */
+    minExecutorBalance?: string | undefined
+    /**
+     * Name of the network (used for metrics).
+     * @default "localhost"
+     */
+    networkName?: string | undefined
+    /**
+     * Amount to multiply the paymaster gas limits fetched from simulations.
+     */
+    paymasterGasLimitMultiplier?: string | undefined
+    /**
+     * Address of the `PerOpInflator` contract.
+     */
+    perOpInflatorAddress?: `0x${string}` | undefined
+    /**
+     * Polling interval for querying for new blocks (ms).
+     * @default 1000
+     */
+    pollingInterval?: number | undefined
+    /**
+     * Port to listen on.
+     * @default 3000
+     */
+    port?: number | undefined
+    /**
+     * RPC url to connect to.
+     */
+    rpcUrl: string
+    /**
+     * Enable safe mode (enforcing all ERC-4337 rules).
+     * @default true
+     */
+    safeMode?: boolean | undefined
+    /**
+     * RPC url to send transactions to (e.g. flashbots relay).
+     */
+    sendTransactionRpcUrl?: string | undefined
+    /**
+     * Timeout for incoming requests (in ms).
+     */
+    timeout?: number | undefined
+    /**
+     * Private key of the utility account.
+     */
+    utilityPrivateKey?: string | undefined
+    /**
+     * Maximum payload size for websocket messages in bytes (default to 1MB).
+     */
+    websocketMaxPayloadSize?: number | undefined
+    /**
+     * Enable websocket server.
+     */
+    websocket?: boolean | undefined
+  }
+}

package/{instances → src/instances}/anvil.test.ts

@@ -1,12 +1,11 @@
+import { Instance } from 'prool'
 import { afterEach, expect, test } from 'vitest'
-import type { Instance } from '../instance.js'
-import { type AnvilParameters, anvil } from './anvil.js'
 
-const instances: Instance[] = []
+const instances: Instance.Instance[] = []
 const timestamp = 1717114065
 
-const defineInstance = (parameters: AnvilParameters = {}) => {
-  const instance = anvil(parameters)
+const defineInstance = (parameters: Instance.anvil.Parameters = {}) => {
+  const instance = Instance.anvil(parameters)
   instances.push(instance)
   return instance
 }
@@ -100,7 +99,7 @@ test.skip('behavior: starts anvil with custom options', async () => {
 test('behavior: exit', async () => {
   const instance = defineInstance({ timestamp })
 
-  let exitCode: number | null | undefined = undefined
+  let exitCode: number | null | undefined
   instance.on('exit', (code) => {
     exitCode = code
   })

package/src/instances/anvil.ts

@@ -0,0 +1,306 @@
+import * as Instance from '../Instance.js'
+import { toArgs } from '../internal/utils.js'
+import { execa } from '../processes/execa.js'
+
+/**
+ * Defines an Anvil instance.
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.anvil({ forkRpcUrl: 'https://cloudflare-eth.com', port: 8546 })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const anvil = Instance.define((parameters?: anvil.Parameters) => {
+  const { binary = 'anvil', ...args } = parameters || {}
+
+  const name = 'anvil'
+  const process = execa({ name })
+
+  return {
+    _internal: {
+      args,
+      get process() {
+        return process._internal.process
+      },
+    },
+    host: args.host ?? 'localhost',
+    name,
+    port: args.port ?? 8545,
+    async start({ port = args.port }, options) {
+      return await process.start(
+        ($) =>
+          $({
+            env: {
+              FOUNDRY_DISABLE_NIGHTLY_WARNING: 'true',
+            },
+          })`${binary} ${toArgs({ ...args, port })}`,
+        {
+          ...options,
+          // Resolve when the process is listening via a "Listening on" message.
+          resolver({ process, reject, resolve }) {
+            process.stdout.on('data', (data) => {
+              const message = data.toString()
+              if (message.includes('Listening on')) resolve()
+            })
+            process.stderr.on('data', (data) => {
+              const message = data.toString()
+              if (message.includes('Warning')) return
+              reject(message)
+            })
+          },
+        },
+      )
+    },
+    async stop() {
+      await process.stop()
+    },
+  }
+})
+
+export declare namespace anvil {
+  export type Parameters = {
+    /**
+     * Number of dev accounts to generate and configure.
+     *
+     * @defaultValue 10
+     */
+    accounts?: number | undefined
+    /**
+     * Set the Access-Control-Allow-Origin response header (CORS).
+     *
+     * @defaultValue *
+     */
+    allowOrigin?: string | undefined
+    /**
+     * Enable autoImpersonate on startup
+     */
+    autoImpersonate?: boolean | undefined
+    /**
+     * The balance of every dev account in Ether.
+     *
+     * @defaultValue 10000
+     */
+    balance?: number | bigint | undefined
+    /**
+     * The base fee in a block.
+     */
+    blockBaseFeePerGas?: number | bigint | undefined
+    /**
+     * Block time in seconds for interval mining.
+     */
+    blockTime?: number | undefined
+    /**
+     * Path or alias to the Anvil binary.
+     */
+    binary?: string | undefined
+    /**
+     * The chain id.
+     */
+    chainId?: number | undefined
+    /**
+     * EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
+     *
+     * @defaultValue 0x6000 (~25kb)
+     */
+    codeSizeLimit?: number | undefined
+    /**
+     * Sets the number of assumed available compute units per second for this fork provider.
+     *
+     * @defaultValue 350
+     * @see https://github.com/alchemyplatform/alchemy-docs/blob/master/documentation/compute-units.md#rate-limits-cups
+     */
+    computeUnitsPerSecond?: number | undefined
+    /**
+     * Writes output of `anvil` as json to user-specified file.
+     */
+    configOut?: string | undefined
+    /**
+     * Sets the derivation path of the child key to be derived.
+     *
+     * @defaultValue m/44'/60'/0'/0/
+     */
+    derivationPath?: string | undefined
+    /**
+     * Disable the `call.gas_limit <= block.gas_limit` constraint.
+     */
+    disableBlockGasLimit?: boolean | undefined
+    /**
+     * Dump the state of chain on exit to the given file. If the value is a directory, the state will be
+     * written to `<VALUE>/state.json`.
+     */
+    dumpState?: string | undefined
+    /**
+     * Fetch state over a remote endpoint instead of starting from an empty state.
+     *
+     * If you want to fetch state from a specific block number, add a block number like `http://localhost:8545@1400000`
+     * or use the `forkBlockNumber` option.
+     */
+    forkUrl?: string | undefined
+    /**
+     * Fetch state from a specific block number over a remote endpoint.
+     *
+     * Requires `forkUrl` to be set.
+     */
+    forkBlockNumber?: number | bigint | undefined
+    /**
+     * Specify chain id to skip fetching it from remote endpoint. This enables offline-start mode.
+     *
+     * You still must pass both `forkUrl` and `forkBlockNumber`, and already have your required state cached
+     * on disk, anything missing locally would be fetched from the remote.
+     */
+    forkChainId?: number | undefined
+    /**
+     * Specify headers to send along with any request to the remote JSON-RPC server in forking mode.
+     *
+     * e.g. "User-Agent: test-agent"
+     *
+     * Requires `forkUrl` to be set.
+     */
+    forkHeader?: Record<string, string> | undefined
+    /**
+     * Initial retry backoff on encountering errors.
+     */
+    forkRetryBackoff?: number | undefined
+    /**
+     * The block gas limit.
+     */
+    gasLimit?: number | bigint | undefined
+    /**
+     * The gas price.
+     */
+    gasPrice?: number | bigint | undefined
+    /**
+     * The EVM hardfork to use.
+     */
+    hardfork?:
+      | 'Frontier'
+      | 'Homestead'
+      | 'Dao'
+      | 'Tangerine'
+      | 'SpuriousDragon'
+      | 'Byzantium'
+      | 'Constantinople'
+      | 'Petersburg'
+      | 'Istanbul'
+      | 'Muirglacier'
+      | 'Berlin'
+      | 'London'
+      | 'ArrowGlacier'
+      | 'GrayGlacier'
+      | 'Paris'
+      | 'Shanghai'
+      | 'Cancun'
+      | 'Prague'
+      | 'Latest'
+      | undefined
+    /**
+     * The host the server will listen on.
+     */
+    host?: string | undefined
+    /**
+     * Initialize the genesis block with the given `genesis.json` file.
+     */
+    init?: string | undefined
+    /**
+     * Launch an ipc server at the given path or default path = `/tmp/anvil.ipc`.
+     */
+    ipc?: string | undefined
+    /**
+     * Initialize the chain from a previously saved state snapshot.
+     */
+    loadState?: string | undefined
+    /**
+     * BIP39 mnemonic phrase used for generating accounts.
+     */
+    mnemonic?: string | undefined
+    /**
+     * Automatically generates a BIP39 mnemonic phrase, and derives accounts from it.
+     */
+    mnemonicRandom?: boolean | undefined
+    /**
+     * Disable CORS.
+     */
+    noCors?: boolean | undefined
+    /**
+     * Disable auto and interval mining, and mine on demand instead.
+     */
+    noMining?: boolean | undefined
+    /**
+     * Disables rate limiting for this node's provider.
+     *
+     * @defaultValue false
+     * @see https://github.com/alchemyplatform/alchemy-docs/blob/master/documentation/compute-units.md#rate-limits-cups
+     */
+    noRateLimit?: boolean | undefined
+    /**
+     * Explicitly disables the use of RPC caching.
+     *
+     * All storage slots are read entirely from the endpoint.
+     */
+    noStorageCaching?: boolean | undefined
+    /**
+     * How transactions are sorted in the mempool.
+     *
+     * @defaultValue fees
+     */
+    order?: string | undefined
+    /**
+     * Run an Optimism chain.
+     */
+    optimism?: boolean | undefined
+    /**
+     * Port number to listen on.
+     *
+     * @defaultValue 8545
+     */
+    port?: number | undefined
+    /**
+     * Don't keep full chain history. If a number argument is specified, at most this number of states is kept in memory.
+     */
+    pruneHistory?: number | undefined | boolean
+    /**
+     * Number of retry requests for spurious networks (timed out requests).
+     *
+     * @defaultValue 5
+     */
+    retries?: number | undefined
+    /**
+     * Don't print anything on startup and don't print logs.
+     */
+    silent?: boolean | undefined
+    /**
+     * Slots in an epoch.
+     */
+    slotsInAnEpoch?: number | undefined
+    /**
+     * Enable steps tracing used for debug calls returning geth-style traces.
+     */
+    stepsTracing?: boolean | undefined
+    /**
+     * Interval in seconds at which the status is to be dumped to disk.
+     */
+    stateInterval?: number | undefined
+    /**
+     * This is an alias for both `loadState` and `dumpState`. It initializes the chain with the state stored at the
+     * file, if it exists, and dumps the chain's state on exit
+     */
+    state?: string | undefined
+    /**
+     * Timeout in ms for requests sent to remote JSON-RPC server in forking mode.
+     *
+     * @defaultValue 45000
+     */
+    timeout?: number | undefined
+    /**
+     * The timestamp of the genesis block.
+     */
+    timestamp?: number | bigint | undefined
+    /**
+     * Number of blocks with transactions to keep in memory.
+     */
+    transactionBlockKeeper?: number | undefined
+  }
+}