ethers-rpc-pool 1.1.4 → 3.2.0

package/README.md

@@ -1,5 +1,7 @@
 [![npm (tag)](https://img.shields.io/npm/v/ethers-rpc-pool)](https://www.npmjs.com/package/ethers-rpc-pool)
 ![license](https://img.shields.io/npm/l/ethers-rpc-pool)
+[![CI](https://github.com/ahiipsa/ethers-rpc-pool/actions/workflows/ci.yml/badge.svg)](https://github.com/ahiipsa/ethers-rpc-pool/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ahiipsa/ethers-rpc-pool/branch/main/graph/badge.svg)](https://codecov.io/gh/ahiipsa/ethers-rpc-pool)
 
 # ethers-rpc-pool
 
@@ -18,23 +20,30 @@ Designed for production backends and dApps that need:
 ## Table of Contents
 
 - [Why ethers-rpc-pool](#why-ethers-rpc-pool)
+- [vs FallbackProvider](#vs-fallbackprovider)
 - [Features](#features)
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
-- - [Interfaces](#interfaces)
-- - [RPCPoolProvider Options](#rpcpoolprovider-options)
-- - [JsonRpcProvider Options](#jsonrpcprovider-options)
+  - [Interfaces](#interfaces)
+  - [RPCPoolProvider Options](#rpcpoolprovider-options)
+  - [Per-Endpoint Options](#per-endpoint-options)
 - [How It Works](#how-it-works)
-- - [Routing](#1-routing)
-- - [Concurrency Control](#2-concurrency-control)
-- - [Rate Limiting](#3-rate-limiting)
-- - [Retry Strategy](#4-retry-strategy)
+  - [Routing](#1-routing)
+  - [Concurrency Control](#2-concurrency-control)
+  - [Rate Limiting](#3-rate-limiting)
+  - [Retry Strategy](#4-retry-strategy)
+  - [Circuit Breaker](#5-circuit-breaker)
+  - [Pinned Provider](#6-pinned-provider)
 - [Instrumentation & Metrics](#instrumentation--metrics)
+  - [RpcEvent](#rpcevent)
+  - [Stats Snapshot](#stats-snapshot)
+  - [Prometheus Example](#prometheus-example)
+  - [OpenTelemetry Example](#opentelemetry-example)
 - [Production Considerations](#production-considerations)
-- - [Recommended Settings](#recommended-settings)
-- - [Known Limitations](#known-limitations)
+  - [Recommended Settings](#recommended-settings)
+  - [Known Limitations](#known-limitations)
 - [When To Use](#when-to-use)
 - [Example Architecture](#example-architecture)
 - [Roadmap](#roadmap)
@@ -43,31 +52,60 @@ Designed for production backends and dApps that need:
 
 ## Why ethers-rpc-pool?
 
-Most production apps rely on a single RPC provider. This creates:
+Most production apps rely on a single RPC provider. This creates a single point of failure, hard concurrency limits, and cascading retry storms during traffic spikes.
 
-- Single point of failure
-- Hard concurrency limits (RPS / in-flight)
-- Increased timeout risk during traffic spikes
-- Cascading retry storms
+`ethers-rpc-pool` distributes traffic across multiple endpoints, applies per-endpoint rate limiting and concurrency control, and automatically fails over to healthy providers — all behind the familiar `JsonRpcProvider` API.
 
-`ethers-rpc-pool` solves this by introducing:
+---
+
+## vs FallbackProvider
+
+ethers.js ships with a built-in `FallbackProvider`. Here is how the two compare:
+
+| Capability                                               | ethers-rpc-pool |       FallbackProvider        |
+| -------------------------------------------------------- | :-------------: | :---------------------------: |
+| Per-endpoint token-bucket RPS limiting                   |       ✅        |              ❌               |
+| Per-endpoint concurrency control (`inFlight`)            |       ✅        |              ❌               |
+| Respects `Retry-After` header on 429                     |       ✅        |              ❌               |
+| Graduated cooldown (rate limit / timeout / 5xx)          |       ✅        |              ❌               |
+| Circuit breaker with half-open probe                     |       ✅        |              ❌               |
+| Retries on transport errors only (not on logical errors) |       ✅        |              ❌               |
+| Structured observability events (`RpcEvent`)             |       ✅        |              ❌               |
+| Per-provider stats snapshot                              |       ✅        |              ❌               |
+| EWMA latency-based routing (P2C)                         |       ✅        |              ❌               |
+| Sequential failover (one endpoint at a time)             |       ✅        | ❌ (fires all simultaneously) |
+| ethers.js v6 compatible                                  |       ✅        |              ✅               |
+| Drop-in library (no extra infra)                         |       ✅        |              ✅               |
+| Quorum / consensus across backends                       |       ❌        |              ✅               |
+
+**When FallbackProvider is the right choice:** you need result consensus across multiple nodes (e.g. reading from multiple archive nodes and comparing answers).
+
+**When ethers-rpc-pool is the right choice:** you need high-throughput, rate-limit-aware, observable RPC access from a backend service — and you don't care which node answers, only that _someone_ does quickly and reliably.
+
+### Known FallbackProvider issues in production
 
-- Multi-provider routing
-- Per-endpoint concurrency limiting
-- Intelligent failover
-- Retry with exponential backoff + jitter
-- Built-in request instrumentation
+Several recurring problems are documented in the ethers.js issue tracker:
+
+- **Hangs on slow RPCs** — if one backend stalls, the entire provider can stall even when others are healthy ([#2030](https://github.com/ethers-io/ethers.js/issues/2030))
+- **Fires all backends simultaneously** — even with `quorum: 1`, every request is sent to all backends, wasting RPC quota ([#3118](https://github.com/ethers-io/ethers.js/issues/3118))
+- **No rate-limit awareness** — no concept of per-endpoint RPS limits or `Retry-After` headers
+- **Broken error handling for non-ETH errors** — a 401 Unauthorized can be reported as contract reversion ([discussion #3500](https://github.com/ethers-io/ethers.js/discussions/3500))
+
+`ethers-rpc-pool` addresses all of these.
 
 ---
 
 ## Features
 
-- 🔀 Load balancing across multiple RPC endpoints
+- 🔀 Load balancing with EWMA latency-based routing (P2C) across multiple RPC endpoints
 - 🚦 Per-endpoint concurrency limit (`inFlight`)
 - 🔁 Retry with exponential backoff and jitter
 - ⚡ Automatic failover on retryable errors
+- 🔒 Circuit breaker with half-open probe per endpoint
+- 📍 Pinned provider for consistent chain-state reads across multiple calls
 - 📊 Built-in request statistics
 - 🧩 Drop-in replacement for `JsonRpcProvider`
+- ✅ 100 % test coverage (lines, statements, functions)
 
 ---
 
@@ -92,19 +130,21 @@ npm install ethers-rpc-pool
 import { RPCPoolProvider } from 'ethers-rpc-pool';
 
 const poolProvider = new RPCPoolProvider({
-  chainId: 1,
+  network: 1,
   rpc: [
     { url: 'https://eth.drpc.org' },
     { url: 'https://eth1.lava.build' },
     { url: 'https://rpc.mevblocker.io' },
     { url: 'https://eth.blockrazor.xyz' },
-    { url: 'https://public-eth.nownodes.io' },
+    // Override defaults for a specific endpoint:
+    { url: 'https://public-eth.nownodes.io', rps: 5, inFlight: 2 },
   ],
+  // Applied to every endpoint unless overridden per-item above:
   defaultRpcOptions: { inFlight: 1, timeout: 3000, rps: 2, rpsBurst: 5 },
   retry: { attempts: 3 },
 });
 
-// Use it like a regular `JsonRpcProvider`:
+// Drop-in replacement for JsonRpcProvider:
 const blockNumber = await poolProvider.getBlockNumber();
 const balance = await poolProvider.getBalance('0x...');
 ```
@@ -116,18 +156,38 @@ const balance = await poolProvider.getBalance('0x...');
 ### Interfaces
 
 ```ts
-interface RPCParameters {
+interface RPCPoolProviderParams {
+  network: Networkish; // chain ID number, name string, or ethers Network object
+  rpc: RpcEndpointOptions[]; // list of RPC endpoints
+  defaultRpcOptions: {
+    inFlight: number; // required; other fields are optional
+    timeout?: number;
+    rps?: number;
+    rpsBurst?: number;
+  };
+  retry: {
+    attempts: number; // max number of unique endpoints to try
+  };
+  hooks?: {
+    onEvent(e: RpcEvent): void;
+  };
+}
+```
+
+```ts
+// Options for a single RPC endpoint.
+// Per-endpoint values override defaultRpcOptions.
+interface RpcEndpointOptions {
+  url: string | FetchRequest; // endpoint URL
+  priority?: number; // routing tier (default 0, higher = tried first)
+
+  // ethers-rpc-pool options (all optional; fall back to defaultRpcOptions):
   inFlight?: number;
   timeout?: number;
   rps?: number;
   rpsBurst?: number;
 
-  // Optional instrumentation hook for provider-level events
-  stats?: Stats;
-  onEvent?: (e: RpcEvent) => void;
-  providerId: string;
-
-  // Optional JsonRpcProvider options for compatibility
+  // Optional ethers.js JsonRpcApiProviderOptions:
   // https://docs.ethers.org/v6/api/providers/jsonrpc/#JsonRpcApiProviderOptions
   batchStallTime?: number;
   batchMaxSize?: number;
@@ -139,39 +199,27 @@ interface RPCParameters {
 }
 ```
 
-```ts
-interface PoolProviderParameters {
-  network: number;
-  rpc: RpcProviderOptions[];
-  defaultRpcOptions?: RpcProviderOptions;
-  retry: {
-    attempts: number;
-  };
-  hooks?: {
-    onEvent(e: RpcEvent): void;
-  };
-}
-```
-
 ### RPCPoolProvider Options
 
-| Option              | Description                               |
-| ------------------- | ----------------------------------------- |
-| `network`           | Target chain ID                           |
-| `rpc`               | List of RPC endpoints                     |
-| `retry.attempts`    | Maximum number of unique endpoints to try |
-| `defaultRpcOptions` | Default options for all RPC endpoints     |
-| `hooks.onEvent`     | Optional instrumentation hook             |
-
-### JsonRpcProvider Options
-
-| Option     | Description                                                                                                                                  |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `inFlight` | Max concurrent requests per endpoint                                                                                                         |
-| `timeout`  | Timeout in ms for each request to this URL, default 10s                                                                                      |
-| `rps`      | Maximum number of requests per second allowed for a single RPC endpoint. Enforced using a token bucket rate limiter.                         |
-| `rpsBurst` | Maximum burst capacity for the rate limiter. Allows short spikes above the sustained rate by accumulating tokens during idle periods.        |
-| ...        | Also allows customization of [ethers.JsonRpcApiProviderOptions](https://docs.ethers.org/v6/api/providers/jsonrpc/#JsonRpcApiProviderOptions) |
+| Option              | Description                                                                               |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `network`           | Chain identifier (`Networkish`: chain ID number, name string, or ethers `Network` object) |
+| `rpc`               | List of RPC endpoints (see `RpcEndpointOptions` above)                                    |
+| `retry.attempts`    | Maximum number of unique endpoints to try before giving up                                |
+| `defaultRpcOptions` | Default options applied to every endpoint; per-endpoint values override these             |
+| `hooks.onEvent`     | Optional callback fired on every request, response, and error (see `RpcEvent` below)      |
+
+### Per-Endpoint Options
+
+| Option     | Default | Description                                                                                                                            |
+| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`      | —       | RPC endpoint URL (required)                                                                                                            |
+| `priority` | `0`     | Routing tier. Higher value = tried first. When all endpoints in a tier are unavailable, routing falls through to the next tier.        |
+| `inFlight` | `1`     | Max concurrent in-flight requests                                                                                                      |
+| `timeout`  | `10000` | HTTP timeout in ms                                                                                                                     |
+| `rps`      | `10`    | Sustained request rate (requests/sec). Enforced by a token bucket.                                                                     |
+| `rpsBurst` | `= rps` | Burst capacity. Allows short spikes above `rps` by consuming tokens accumulated during idle time.                                      |
+| `...`      | —       | Any [ethers.JsonRpcApiProviderOptions](https://docs.ethers.org/v6/api/providers/jsonrpc/#JsonRpcApiProviderOptions) are also accepted. |
 
 ---
 
@@ -179,7 +227,17 @@ interface PoolProviderParameters {
 
 ### 1. Routing
 
-Requests are routed through an internal `Router`, which selects an available endpoint.
+Endpoints are grouped by `priority` and tried high→low. Within each priority tier, the router uses **EWMA latency + Power of Two Choices (P2C)**: two candidates are drawn at random from the available pool and the one with the lower exponentially-weighted moving average latency (α = 0.2) is picked. Unsampled endpoints start at EWMA = 0 and are naturally explored before measured ones. Both successful responses and errors contribute to the EWMA, so a slow or failing endpoint is progressively deprioritised even before its circuit opens.
+
+If every endpoint in a tier is unavailable, routing falls through to the next tier. If every endpoint across all tiers is unavailable, the pool falls back to round-robin over the highest-priority group — it never deadlocks.
+
+```ts
+rpc: [
+  { url: 'https://alchemy.com/...', priority: 1 }, // tried first
+  { url: 'https://eth.drpc.org', priority: 0 }, // fallback tier
+  { url: 'https://eth1.lava.build', priority: 0 }, // shares fallback tier; EWMA decides the split
+];
+```
 
 ### 2. Concurrency Control
 
@@ -239,38 +297,225 @@ Attempt 3 → random(0..2000ms)
 ...
 ```
 
-Retries only happen on errors considered failover-safe.
+Retries happen only on failover-safe transport errors: **rate limit (429/402)**, **timeout (504, ETIMEDOUT)**, and **server errors (5xx)**. RPC logical errors (execution reverted, invalid params, method not supported) are not retried.
+
+### 5. Circuit Breaker
+
+Each endpoint has an independent three-state circuit breaker managed by `CooldownManager`:
+
+```
+closed ──(error threshold)──▶ open ──(cooldown expires)──▶ half-open
+  ▲                                                              │
+  └──────────────(probe success)────────────────────────────────┘
+  ▲
+  └──────────────(probe failure)────────────────────────── open (escalated cooldown)
+```
+
+| State       | Behaviour                                               |
+| ----------- | ------------------------------------------------------- |
+| `closed`    | Normal operation — all requests pass through            |
+| `open`      | Endpoint is in cooldown — router skips it               |
+| `half-open` | Cooldown expired — one probe request is allowed through |
+
+When the probe succeeds the circuit closes and traffic resumes normally. When the probe fails the circuit re-opens with an escalated cooldown (exponential backoff for 5xx/timeout; `Retry-After` for rate-limits).
+
+The current circuit state for each endpoint is included in `getSnapshot()` under `providerCircuitState`.
+
+### 6. Pinned Provider
+
+Different RPC nodes may lag behind by different numbers of blocks. When requests from the same logical flow go to different endpoints, the client can observe inconsistent state — `eth_getBalance` returns data from block 100, but the next `eth_call` lands on a node at block 99. This is especially dangerous in DeFi: read state → build transaction → node doesn't "see" the previous block yet.
+
+`pinnedProvider()` selects the best available endpoint at call time and returns its `InstrumentedJsonRpcProvider` directly. All subsequent calls through that provider go to the same node.
+
+```ts
+const pinned = pool.pinnedProvider();
+
+// All three calls go to the same RPC node:
+const balance = await pinned.getBalance('0x...');
+const nonce = await pinned.getTransactionCount('0x...');
+const code = await pinned.getCode('0x...');
+```
+
+The endpoint is selected using the same P2C/EWMA routing as `pool.send()`. Since the returned provider is a plain `InstrumentedJsonRpcProvider`, there is no automatic failover — if the pinned node goes down mid-session, call `pinnedProvider()` again to re-pin to a healthy endpoint.
 
 ---
 
 ## Instrumentation & Metrics
 
-You can subscribe to RPC lifecycle events:
+### RpcEvent
+
+Every request, successful response, and error fires an `RpcEvent` through the optional `hooks.onEvent` callback:
+
+```ts
+type RpcEvent =
+  | {
+      type: 'request';
+      chainId: bigint;
+      providerId: string; // e.g. "rpc#1-chainId:1-https://eth.drpc.org"
+      method: string; // e.g. "eth_blockNumber"
+      startedAt: number; // Unix timestamp (ms)
+    }
+  | {
+      type: 'response';
+      chainId: bigint;
+      providerId: string;
+      method: string;
+      startedAt: number;
+      endedAt: number;
+      ms: number; // round-trip time in ms
+    }
+  | {
+      type: 'error';
+      chainId: bigint;
+      providerId: string;
+      method: string;
+      startedAt: number;
+      endedAt: number;
+      ms: number;
+      isRateLimit: boolean;
+      isTimeout: boolean;
+      status?: number; // HTTP status code if available
+      retryAfterMs?: number; // from Retry-After header
+      code?: string; // ethers error code
+      message: string;
+      errorKind?: 'transport' | 'rpc';
+    };
+```
 
-```typescript
+Use `hooks.onEvent` to feed events into Prometheus, OpenTelemetry, or custom logging:
+
+```ts
 const poolProvider = new RPCPoolProvider({
   // ...
   hooks: {
     onEvent(event) {
-      console.log(event);
+      if (event.type === 'error' && event.isRateLimit) {
+        rateLimitCounter.inc({ provider: event.providerId });
+      }
     },
   },
 });
 ```
 
-This allows integration with:
+### Prometheus Example
+
+Uses [`prom-client`](https://github.com/siimon/prom-client):
+
+```ts
+import { Counter, Histogram, Registry } from 'prom-client';
+import { RPCPoolProvider } from 'ethers-rpc-pool';
 
-- Prometheus
-- OpenTelemetry
-- Custom logging pipelines
+const registry = new Registry();
 
-### Access Stats Snapshot
+const rpcRequests = new Counter({
+  name: 'rpc_requests_total',
+  help: 'Total RPC requests sent',
+  labelNames: ['provider', 'method'],
+  registers: [registry],
+});
+
+const rpcDuration = new Histogram({
+  name: 'rpc_request_duration_ms',
+  help: 'RPC round-trip time in milliseconds',
+  labelNames: ['provider', 'method'],
+  buckets: [50, 100, 250, 500, 1000, 2500, 5000],
+  registers: [registry],
+});
+
+const rpcErrors = new Counter({
+  name: 'rpc_errors_total',
+  help: 'Total RPC errors',
+  labelNames: ['provider', 'method', 'kind'],
+  registers: [registry],
+});
+
+const pool = new RPCPoolProvider({
+  network: 1,
+  rpc: [{ url: 'https://eth.drpc.org' }, { url: 'https://eth1.lava.build' }],
+  defaultRpcOptions: { inFlight: 1, rps: 10 },
+  retry: { attempts: 3 },
+  hooks: {
+    onEvent(e) {
+      if (e.type === 'request') {
+        rpcRequests.inc({ provider: e.providerId, method: e.method });
+      } else if (e.type === 'response') {
+        rpcDuration.observe({ provider: e.providerId, method: e.method }, e.ms);
+      } else if (e.type === 'error') {
+        const kind = e.isRateLimit ? 'rate_limit' : e.isTimeout ? 'timeout' : 'server';
+        rpcErrors.inc({ provider: e.providerId, method: e.method, kind });
+      }
+    },
+  },
+});
+```
+
+### OpenTelemetry Example
+
+Uses `@opentelemetry/api`:
+
+```ts
+import { metrics } from '@opentelemetry/api';
+import { RPCPoolProvider } from 'ethers-rpc-pool';
+
+const meter = metrics.getMeter('ethers-rpc-pool');
+
+const rpcDuration = meter.createHistogram('rpc.request.duration', {
+  description: 'RPC round-trip time in milliseconds',
+  unit: 'ms',
+});
+
+const rpcErrors = meter.createCounter('rpc.errors', {
+  description: 'Total RPC errors by kind',
+});
+
+const pool = new RPCPoolProvider({
+  network: 1,
+  rpc: [{ url: 'https://eth.drpc.org' }, { url: 'https://eth1.lava.build' }],
+  defaultRpcOptions: { inFlight: 1, rps: 10 },
+  retry: { attempts: 3 },
+  hooks: {
+    onEvent(e) {
+      const attrs = { 'rpc.provider': e.providerId, 'rpc.method': e.method };
+      if (e.type === 'response') {
+        rpcDuration.record(e.ms, attrs);
+      } else if (e.type === 'error') {
+        const kind = e.isRateLimit ? 'rate_limit' : e.isTimeout ? 'timeout' : 'server';
+        rpcErrors.add(1, { ...attrs, 'rpc.error.kind': kind });
+      }
+    },
+  },
+});
+```
+
+### Stats Snapshot
+
+`getSnapshot()` returns a point-in-time copy of all counters:
 
 ```ts
-const stats = pool.getStats();
-console.log(stats.snapshot());
+const snapshot = pool.getSnapshot();
 ```
 
+| Field                    | Description                                                                                                                              |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `total`                  | Total requests sent (counts each retry attempt)                                                                                          |
+| `inFlight`               | Currently in-flight requests across all endpoints                                                                                        |
+| `perMethodTotal`         | Request count per JSON-RPC method                                                                                                        |
+| `rateLimitedTotal`       | Total 429/rate-limit errors                                                                                                              |
+| `perProviderRateLimited` | Rate-limit errors per endpoint                                                                                                           |
+| `timeoutTotal`           | Total timeout errors                                                                                                                     |
+| `perProviderTimeout`     | Timeout errors per endpoint                                                                                                              |
+| `serverErrorTotal`       | Total 5xx server errors                                                                                                                  |
+| `perProviderTotal`       | Total requests per endpoint                                                                                                              |
+| `perProviderInFlight`    | Currently in-flight requests per endpoint                                                                                                |
+| `perProviderError`       | Transport errors (5xx, network) per endpoint                                                                                             |
+| `rpcErrorTotal`          | Total RPC logical errors (revert, invalid params, etc.)                                                                                  |
+| `perProviderRpcError`    | RPC logical errors per endpoint, broken down by method                                                                                   |
+| `perMethodRpcError`      | RPC logical errors per method                                                                                                            |
+| `perProviderMethod`      | Request count per endpoint per method                                                                                                    |
+| `providerCooldownUntil`  | Unix timestamp (ms) when each endpoint's cooldown ends                                                                                   |
+| `providerCircuitState`   | Circuit breaker state per endpoint (`'open'` or `'half-open'`; absent when `'closed'`)                                                   |
+| `perProviderLatencyEwma` | EWMA latency in ms (α = 0.2) per endpoint, as used by the router for P2C decisions. Absent for endpoints that have not yet been sampled. |
+
 ### Example output:
 
 ```json
@@ -286,9 +531,15 @@ console.log(stats.snapshot());
   },
   "rateLimitedTotal": 0,
   "timeoutTotal": 0,
+  "serverErrorTotal": 0,
+  "rpcErrorTotal": 0,
   "perProviderRateLimited": {},
   "perProviderTimeout": {},
+  "perProviderError": {},
+  "perProviderRpcError": {},
+  "perMethodRpcError": {},
   "providerCooldownUntil": {},
+  "providerCircuitState": {},
   "perProviderInFlight": {
     "rpc#1-chainId:1-https://eth.drpc.org": 0,
     "rpc#2-chainId:1-https://eth1.lava.build": 0,
@@ -302,18 +553,18 @@ console.log(stats.snapshot());
     "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
+  },
+  "perProviderMethod": {
+    "rpc#1-chainId:1-https://eth.drpc.org": { "eth_blockNumber": 21 }
+  },
+  "perProviderLatencyEwma": {
+    "rpc#1-chainId:1-https://eth.drpc.org": 142.3,
+    "rpc#2-chainId:1-https://eth1.lava.build": 98.7,
+    "rpc#3-chainId:1-https://rpc.mevblocker.io": 201.5
   }
 }
 ```
 
-Useful for:
-
-- Request counters
-- Per-method stats
-- Per-provider metrics
-- Timeout tracking
-- Rate limit detection
-
 ---
 
 ## Production Considerations
@@ -326,9 +577,8 @@ Useful for:
 
 ### Known Limitations
 
-- Basic circuit breaker/cooldown
-- No sticky session/blockTag consistency yet
-- Archive/debug/trace methods depend on underlying RPC support
+- `pinnedProvider()` has no automatic failover — if the pinned node goes down, call it again to re-pin
+- Archive, debug, and trace methods work only if the underlying RPC supports them
 
 ---
 
@@ -380,9 +630,6 @@ Not intended for:
 
 ## Roadmap
 
-- Circuit breaker + health scoring
-- Sticky session / blockTag consistency
-- Adaptive latency-based routing
 - Singleflight request deduplication
 
 ---
@@ -391,7 +638,7 @@ Not intended for:
 
 Read the engineering story behind this library:
 
-(How I solved Ethereum RPC rate limits without paying $250/month)[https://dev.to/ahiipsa/how-i-solved-ethereum-rpc-rate-limits-with-traffic-engineering-instead-of-paying-250month-30ed]
+[How I solved Ethereum RPC rate limits without paying $250/month](https://dev.to/ahiipsa/how-i-solved-ethereum-rpc-rate-limits-with-traffic-engineering-instead-of-paying-250month-30ed)
 
 ---