feat(rpc): add timeout and circuit breaker for blockchain RPC calls

[retkatmun]

Summary

Closes #941

Implements production-ready timeout and circuit breaker protection for all external blockchain RPC calls in SubTrackr.

---

Problem

Without this fix, any slow or unreachable RPC endpoint causes:

• Indefinite hangs — provider.getBalance() / getGasPrice() never rejects; the caller waits forever
• Cascading failures — one bad node blocks gas estimation, balance checks, stream creation
• No fallback — a single URL was hard-coded with no secondary provider

---

What changed

New files

File	Purpose
backend/services/shared/rpcTimeout.ts	withRpcTimeout (AbortController+jitter), wrapWithTimeout (Promise.race), typed errors, type guards, defaultTimeoutForChain
backend/services/shared/rpcResilienceMiddleware.ts	ResilientEthersProvider (extends MonitoringJsonRpcProvider) + factory + singleton registry
src/services/rpcProvider.ts	Client-side (React Native) ResilientJsonRpcProvider — per-URL circuit breaker + timeout + ordered URL fallback
backend/services/shared/__tests__/rpcTimeout.test.ts	Unit tests — 25+ cases
backend/services/shared/__tests__/rpcResilienceMiddleware.test.ts	Unit tests — factory, registry, send override
backend/services/shared/__tests__/walletServiceRpc.integration.test.ts	Integration tests — 7 suites
backend/benchmark/rpcBenchmark.ts	9 benchmarks with budget gating
docs/rpc-resilience.md	Architecture, API reference, config, error types, test commands

Modified files

File	Change
src/services/walletService.ts	getProvider() now calls getOrCreateResilientProvider() instead of new JsonRpcProvider()
backend/services/shared/index.ts	Export rpcTimeout and rpcResilienceMiddleware public API

---

Architecture

walletService.getProvider(chainId)
    │
    └─► ResilientJsonRpcProvider        [src/services/rpcProvider.ts]
          ├─ All fallback URLs from EVM_RPC_URLS (primary + 1–2 backups)
          ├─ Per-URL circuit breaker  (closed → open → half-open → closed)
          └─ Per-call AbortController deadline (timeout + jitter)

---

Circuit breaker states

  CLOSED ──[N consecutive failures]──► OPEN
     ▲                                  │ recoveryTimeoutMs
     │ probe succeeds           ◄────── HALF-OPEN
     │                                  │
     └──────────────────────────────────┘ probe fails → back to OPEN

---

Key API

// Timeout with AbortController (signal-aware, no leaked Promises)
const block = await withRpcTimeout(
  (signal) => fetch(url, { signal }).then(r => r.json()),
  { timeoutMs: 10_000, jitterMs: 500, endpointUrl: url }
);

// Wrap third-party Promise (not signal-aware)
const gasPrice = await wrapWithTimeout(
  provider.getGasPrice(),
  { timeoutMs: 10_000 }
);

// Client-side resilient provider (walletService)
const provider = getOrCreateResilientProvider(1, [
  'https://cloudflare-eth.com',
  'https://rpc.ankr.com/eth',
  'https://eth.llamarpc.com',
]);
const balance = await provider.getBalance(address); // protected

---

Tests

• Unit (rpcTimeout.test.ts): withRpcTimeout, wrapWithTimeout, type guards, defaultTimeoutForChain, error types — 25+ cases
• Unit (rpcResilienceMiddleware.test.ts): factory, registry, send timeout, health snapshot, resetCircuits
• Integration (walletServiceRpc.integration.test.ts): 7 suites
  • Timeout fires and bubbles as typed error
  • Circuit breaker trips after threshold, recovers after window
  • Ordered URL fallback — primary fails, secondary succeeds
  • Per-URL circuit state in ResilientJsonRpcProvider
  • Registry singleton preserves circuit state across calls
  • Manual operator reset
  • Audit log and dashboard correctness

Performance benchmarks

Metric	Budget	Result
withRpcTimeout overhead	< 1 ms avg	✓
wrapWithTimeout overhead	< 1 ms avg	✓
Circuit breaker closed-path	< 1 ms avg	✓
p95 all in-process operations	< 2 ms	✓
defaultTimeoutForChain	> 100 000 ops/s	✓

---

Acceptance criteria

• Feature implemented with full functionality
• Unit tests with >80% coverage of new code
• Integration tests for critical paths
• No regression (walletService public API unchanged; ResilientJsonRpcProvider is a drop-in for JsonRpcProvider)
• Documentation updated (docs/rpc-resilience.md)
• Performance benchmarks met

[drips-wave]

@retkatmun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits