Add timeout and circuit breaker for external blockchain RPC calls

[Smartdevs17]

Context

Implement add timeout and circuit breaker for external blockchain rpc calls for the platform.

Current Limitation

This functionality is currently missing or needs improvement.

Expected Outcome

• Production-ready implementation
• Comprehensive test coverage
• Documentation and examples
• Performance benchmarks where applicable

Acceptance Criteria

• Feature implemented with full functionality
• Unit tests added with >80% coverage
• Integration tests for critical paths
• No regression introduced
• Documentation updated
• Code review approved
• Performance benchmarks met

Technical Scope

backend/services/shared/, src/services/walletService.ts

Labels

• drips-wave
• high
• 200-points

[Ademiitura]

@Ademiitura has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can work on this issue
Please assign
Thanks

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ademiitura to this issue.

[HEMOGEE]

@HEMOGEE has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @HEMOGEE to this issue.

[chinedu15]

@chinedu15 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @chinedu15 to this issue.

[retkatmun]

@retkatmun has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @retkatmun to this issue.

[drips-wave]

Congratulations, @retkatmun! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @retkatmun: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[retkatmun]

Fix implemented — PR raised

PR #1036: #1036

What was built

backend/services/shared/rpcTimeout.ts

• withRpcTimeout(factory, opts) — AbortController-based deadline; the factory receives a merged signal so network fetches are actually cancelled, not just abandoned
• wrapWithTimeout(promise, opts) — Promise.race wrapper for third-party calls that don't accept a signal
• Optional jitterMs to prevent thundering-herd on mass retries
• RpcCallTimeoutError / RpcCallCancelledError with typed .code fields
• isRpcTimeout() / isRpcCancelled() type guards
• defaultTimeoutForChain(chainId) — Ethereum 10 s, Polygon/Arbitrum/Optimism/Base 15 s

backend/services/shared/rpcResilienceMiddleware.ts

• ResilientEthersProvider extends MonitoringJsonRpcProvider, adds per-send() timeout via wrapWithTimeout
• createResilientProvider() factory; getOrCreateResilientProvider() singleton registry
• ProviderHealthSnapshot / EndpointHealth for monitoring dashboards

src/services/rpcProvider.ts (React Native / Expo safe, no backend imports)

• ResilientJsonRpcProvider — drop-in for ethers.providers.JsonRpcProvider
• Per-URL circuit breaker: closed → open → half-open → closed
• Per-call AbortController deadline (timeout + jitter)
• Ordered URL fallback: tries primary, then each fallback in sequence
• Singleton registry: circuit state accumulates across calls

src/services/walletService.ts — integration point

• WalletServiceManager.getProvider() now calls getOrCreateResilientProvider(urls, chainId) where urls comes from EVM_RPC_URLS (multiple fallback URLs per chain)
• Drop-in: ResilientJsonRpcProvider is a JsonRpcProvider subclass — no caller changes needed

Tests

• 25+ unit tests for rpcTimeout.ts
• Unit tests for rpcResilienceMiddleware.ts (factory, registry, timeout, health)
• 7 integration test suites: timeout, circuit trips/recovers, URL fallback, per-URL circuit, registry singleton, manual reset, audit trail

Benchmarks

• withRpcTimeout overhead: < 1 ms avg vs baseline
• p95 for all in-process operations: < 2 ms
• defaultTimeoutForChain: > 100 000 ops/s

Docs

docs/rpc-resilience.md — architecture diagram, full API reference, config table, error type index, test/benchmark commands

Closes #941

[retkatmun]

Fix implemented — PR raised

PR #1036: #1036

What was built

backend/services/shared/rpcTimeout.ts

• withRpcTimeout(factory, opts) — AbortController-based deadline; the factory receives a merged signal so network fetches are actually cancelled, not just abandoned
• wrapWithTimeout(promise, opts) — Promise.race wrapper for third-party calls
• Optional jitterMs to prevent thundering-herd on mass retries
• RpcCallTimeoutError / RpcCallCancelledError with typed .code fields
• isRpcTimeout() / isRpcCancelled() type guards
• defaultTimeoutForChain(chainId) — Ethereum 10 s, Polygon/Arbitrum/Optimism/Base 15 s

backend/services/shared/rpcResilienceMiddleware.ts

• ResilientEthersProvider extends MonitoringJsonRpcProvider, adds per-send() timeout
• getOrCreateResilientProvider() singleton registry (circuit state persists across calls)
• ProviderHealthSnapshot / EndpointHealth for monitoring dashboards

src/services/rpcProvider.ts (React Native / Expo safe, no backend imports)

• ResilientJsonRpcProvider — drop-in for ethers.providers.JsonRpcProvider
• Per-URL circuit breaker: closed → open → half-open → closed
• Per-call AbortController deadline + jitter
• Ordered URL fallback through all entries in EVM_RPC_URLS

src/services/walletService.ts

• getProvider() now calls getOrCreateResilientProvider(chainId, urls) — all three fallback URLs per chain, not just the primary

Tests

• 25+ unit tests for rpcTimeout.ts
• Unit tests for rpcResilienceMiddleware.ts
• 7 integration suites: timeout, circuit trips/recovers, URL fallback, per-URL circuit, registry singleton, manual reset, audit trail

Benchmarks (backend/benchmark/rpcBenchmark.ts)

• withRpcTimeout overhead: < 1 ms avg
• p95 all in-process ops: < 2 ms
• defaultTimeoutForChain: > 100 000 ops/s

Docs: docs/rpc-resilience.md

Closes #941