ethers-rpc-pool 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Karasev
+
+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.

package/README.md

@@ -0,0 +1,283 @@
+# ethers-rpc-pool
+
+Multi-endpoint RPC pool provider for **ethers.js** with built-in load balancing, per-endpoint concurrency limits, retry with exponential backoff, and instrumentation.
+
+Designed for production backends and dApps that need:
+
+- Better reliability than a single RPC endpoint
+- Protection against rate limits (429) and timeouts
+- Controlled concurrency per RPC
+- Automatic failover between endpoints
+- Observability via structured RPC events
+
+---
+
+## Why ethers-rpc-pool?
+
+Most production apps rely on a single RPC provider. This creates:
+
+- Single point of failure
+- Hard rate limits (RPS / in-flight)
+- Increased timeout risk during traffic spikes
+- Cascading retry storms
+
+`ethers-rpc-pool` solves this by introducing:
+
+- Multi-provider routing
+- Per-endpoint concurrency limiting
+- Intelligent failover
+- Retry with exponential backoff + jitter
+- Built-in request instrumentation
+
+---
+
+## Features
+
+- 🔀 Load balancing across multiple RPC endpoints
+- 🚦 Per-endpoint concurrency limit (`inFlight`)
+- 🔁 Retry with exponential backoff and jitter
+- ⚡ Automatic failover on retryable errors
+- 📊 Built-in request statistics
+- 🧩 Drop-in replacement for `JsonRpcProvider`
+
+---
+
+## Installation
+
+```bash
+npm install ethers-rpc-pool
+```
+
+---
+
+## Quick Start
+
+```ts
+import { RPCPoolProvider } from 'ethers-rpc-pool';
+
+const pool = new RPCPoolProvider({
+  chainId: 1,
+  urls: ['http://rpc1.invalid', 'http://rpc2.invalid'],
+  perUrl: { inFlight: 1 },
+  retry: { attempts: 2 },
+});
+
+// Use it like a regular `JsonRpcProvider`:
+
+const blockNumber = await pool.getBlockNumber();
+const balance = await pool.getBalance('0x...');
+```
+
+---
+
+## Configuration
+
+### RPCPoolProviderParams
+
+```ts
+interface RPCPoolProviderParams {
+  chainId: number;
+  urls: string[];
+  perUrl: {
+    inFlight: number;
+  };
+  retry: {
+    attempts: number;
+  };
+  hooks?: {
+    onEvent(e: RpcEvent): void;
+  };
+}
+```
+
+### Options Explained
+
+| Option            | Description                               |
+| ----------------- | ----------------------------------------- |
+| `chainId`         | Target chain ID                           |
+| `urls`            | List of RPC endpoints                     |
+| `perUrl.inFlight` | Max concurrent requests per endpoint      |
+| `retry.attempts`  | Maximum number of unique endpoints to try |
+| `hooks.onEvent`   | Optional instrumentation hook             |
+
+---
+
+## How It Works
+
+### 1. Routing
+
+Requests are routed through an internal `Router`, which selects an available endpoint.
+
+### 2. Concurrency Control
+
+Each endpoint has its own semaphore limiter:
+
+```ts
+perUrl: {
+  inFlight: number;
+}
+```
+
+This prevents:
+
+- Overloading a single RPC
+- Triggering provider-side throttling
+- Self-induced retry storms
+
+### 3. Retry Strategy
+
+If a retryable error occurs:
+
+- A different endpoint is selected
+- Exponential backoff is applied
+- Jitter is added to prevent synchronization spikes
+
+Example retry timing:
+
+```
+Attempt 1 → immediate
+Attempt 2 → random(0..1000ms)
+Attempt 3 → random(0..2000ms)
+...
+```
+
+Retries only happen on errors considered failover-safe.
+
+---
+
+## Instrumentation & Metrics
+
+You can subscribe to RPC lifecycle events:
+
+```typescript
+const pool = new RPCPoolProvider({
+  // ...
+  hooks: {
+    onEvent(event) {
+      console.log(event);
+    },
+  },
+});
+```
+
+This allows integration with:
+
+- Prometheus
+- OpenTelemetry
+- Custom logging pipelines
+
+### Access Stats Snapshot
+
+```ts
+const stats = pool.getStats();
+console.log(status.snapshot());
+```
+
+### Example output:
+```json
+{
+  "total": 105,
+  "inFlight": 0,
+  "perMethodTotal": {
+    "eth_getBlockByNumber": 1,
+    "eth_gasPrice": 1,
+    "eth_maxPriorityFeePerGas": 1,
+    "eth_chainId": 1,
+    "eth_blockNumber": 101
+  },
+  "rateLimitedTotal": 0,
+  "timeoutTotal": 0,
+  "perProviderRateLimited": {},
+  "perProviderTimeout": {},
+  "providerCooldownUntil": {},
+  "perProviderInFlight": {
+    "rpc#1-chainId:1-https://eth.drpc.org": 0,
+    "rpc#2-chainId:1-https://eth1.lava.build": 0,
+    "rpc#3-chainId:1-https://rpc.mevblocker.io": 0,
+    "rpc#4-chainId:1-https://eth.blockrazor.xyz": 0,
+    "rpc#5-chainId:1-https://public-eth.nownodes.io": 0
+  },
+  "perProviderTotal": {
+    "rpc#1-chainId:1-https://eth.drpc.org": 21,
+    "rpc#2-chainId:1-https://eth1.lava.build": 21,
+    "rpc#3-chainId:1-https://rpc.mevblocker.io": 21,
+    "rpc#4-chainId:1-https://eth.blockrazor.xyz": 21,
+    "rpc#5-chainId:1-https://public-eth.nownodes.io": 21
+  }
+}
+```
+
+Useful for:
+
+- Request counters
+- Per-method stats
+- Per-provider metrics
+- Timeout tracking
+- Rate limit detection
+
+---
+
+## Production Considerations
+
+### Recommended Settings
+
+- `inFlight`: 1–2 depending on rpc provider limits
+- `retry.attempts`: 2–3
+- Use at least 2–3 independent RPC providers
+
+### Known Limitations
+
+- No circuit breaker yet
+- No sticky session/blockTag consistency yet
+- No built-in JSON-RPC batching
+- Archive/debug/trace methods depend on underlying RPC support
+
+---
+
+## When To Use
+
+Good fit for:
+
+- Backend services aggregating on-chain data
+- dApps with moderate traffic
+- Systems using free-tier RPC plans
+- Environments needing failover protection
+
+Not intended for:
+
+- High-frequency trading systems
+- Archive-heavy indexing pipelines
+- Trace/debug intensive workloads
+
+---
+
+## Example Architecture
+
+```
+                 ┌──────────────┐
+                 │ Application  │
+                 └──────┬───────┘
+                        │
+                ┌───────▼────────┐
+                │ RPCPoolProvider │
+                └───────┬────────┘
+        ┌───────────────┼────────────────┐
+        ▼               ▼                ▼
+   RPC Endpoint 1   RPC Endpoint 2   RPC Endpoint 3
+```
+
+---
+
+## Roadmap
+
+- Circuit breaker + health scoring
+- Sticky session / blockTag consistency
+- Adaptive latency-based routing
+- JSON-RPC batch support
+- Singleflight request deduplication
+
+---
+
+## License
+
+MIT