VirtualPool - High-Performance Ethereum Testing Framework

A high-performance Ethereum testing framework with advanced provider pooling, adaptive load balancing, and comprehensive monitoring.

Features

• Provider Pooling: Manage multiple Anvil instances efficiently
• Load Balancing: Distribute requests across available providers
• Health Monitoring: Automatic health checks and provider recovery
• Resource Management: Efficient allocation and release of providers
• Performance Metrics: Comprehensive monitoring and statistics
• Graceful Shutdown: Clean resource cleanup and process management

Installation

npm install @bcoders.gr/virtualpool

Quick Start

import { AnvilProviderPool } from '@bcoders.gr/virtualpool';

// Initialize pool with 3 providers (ports 8550-8552)
const pool = new AnvilProviderPool(8550, 8552);

// Initialize and get a provider
await pool.initialize();
const { provider, port } = await pool.getAvailableProvider();

// Use the provider
const blockNumber = await provider.request('eth_blockNumber');
console.log(`Current block: ${parseInt(blockNumber, 16)}`);

// Release the provider back to pool
pool.releaseProvider(port);

// Shutdown when done
await pool.shutdown();

API Reference

AnvilProviderPool

Constructor

new AnvilProviderPool(portStart, portEnd, options)

• portStart: Starting port number (default: 8550)
• portEnd: Ending port number (default: 8560)
• options: Configuration options
  • timeout: Provider startup timeout (default: 30000ms)
  • maxRetries: Max retry attempts (default: 5)
  • healthCheckInterval: Health check frequency (default: 30000ms)
  • maxParallelStarts: Max concurrent provider starts (default: 5)

Methods

initialize()

Initialize the provider pool. Returns pool statistics.

getAvailableProvider()

Get an available provider from the pool.

• Returns: { provider, port } or null if none available

releaseProvider(port)

Release a provider back to the pool.

• port: Port number of the provider to release

getStats()

Get comprehensive pool statistics.

• Returns: Object containing metrics like:
  • Total providers
  • Available/busy providers
  • Health status
  • Utilization rate
  • Request metrics

shutdown()

Gracefully shutdown the pool and cleanup resources.

withProvider(fn)

Execute a function with an automatically managed provider.

await pool.withProvider(async (provider) => {
    const block = await provider.request('eth_blockNumber');
    return block;
});

withProviderStrategy(fn, strategy)

Execute a function with a provider selected by strategy.

• Strategies: 'random', 'roundRobin', 'leastUsed', 'fastest'

Health Monitoring

The pool automatically:

• Monitors provider health
• Restarts unhealthy providers
• Implements circuit breaker patterns
• Collects performance metrics
• Manages provider lifecycle

Performance Features

• Concurrent provider initialization
• Request batching and caching
• Adaptive load balancing
• Resource pooling
• Connection management
• Error recovery
• Performance metrics

Example

See examples/basic-usage.js for a complete example.

Testing

Run the comprehensive test suite:

npm test

License

MIT