Soroban RPC dual-endpoint failover

[truthixify]

Extra labels: stellar, resilience
Tier: M (2-4 days) | Type: feature

Context. A single Soroban RPC URL is a single point of failure. Users want to configure a primary + fallback and have the client fail over silently if the primary is down.

Scope.

• Client accepts an array of endpoints.
• Health-check on first use; sticky to the healthy one until it fails.
• Circuit breaker: after N consecutive failures, mark endpoint bad for M seconds.
• Emit a endpointFailover event so apps can log it.

Acceptance.

• Test with mock RPC that goes down mid-scan
• Failover verified without dropped events
• Doc'd config shape

Files. src/chains/stellar/rpc.ts, test/chains/stellar/rpc.test.ts.

[Fang0067]

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

Hi! I'd like to work on this issue. Configurable failover for Soroban RPC endpoints is a solid resilience improvement, and the scope here (health-check on first use, circuit breaker with cooldown, failover event emission) is well-defined enough that I can move quickly on it.

I have experience implementing retry/failover logic and health-check patterns for RPC/API clients, so I'm confident I can deliver this within the estimated timeframe. Happy to start right away, let me know if you'd like a quick implementation plan first.

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

[collinsezedike]

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

The critical design detail is that failover has to retry the specific failed operation against the fallback endpoint, not merely redirect subsequent calls, otherwise the acceptance criterion of zero dropped events during a mid-scan failure can't hold.

So for this issue, here's my plan:

• Implement the RPC client in src/chains/stellar/rpc.ts to accept an array of endpoints, performing a health check on first use and remaining sticky to the currently healthy one
• Add a circuit breaker marking an endpoint unhealthy after N consecutive failures, excluding it for M seconds before retrying
• On a request failure, retry the same operation against the next healthy endpoint immediately, ensuring in-flight work completes rather than being lost
• Emit an endpointFailover event capturing the failed and newly active endpoint
• Add a test using a mock RPC that fails mid-scan, asserting all events are still captured with none dropped
• Document the endpoint configuration shape

All acceptance criteria covered.

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

[drips-wave]

Congratulations, @Fang0067! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Fang0067: 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 🌊