Implement health-based adaptive multi-provider failover

[Lakes41]

Difficulty: Expert
Type: Performance
Recommended labels (if available in this repo): enhancement, reliability, performance

Background

src/contracts/providers/adaptiveContractProvider.ts and healthTracker.ts exist as scaffolding for adaptive provider selection across jsonRpcProvider.ts, webSocketProvider.ts, and multicall3Provider.ts, but the routing logic may be minimal or incomplete relative to a full health-scored failover system.

Problem

Without robust health-based routing, a single degraded (slow, erroring, or rate-limited) RPC provider can silently degrade the whole SDK's reliability instead of the adaptive layer routing around it.

Expected Outcome

adaptiveContractProvider.ts maintains a rolling health score per configured provider (based on latency, error rate, and timeout frequency from healthTracker.ts) and routes calls to the best-scoring healthy provider, with automatic recovery detection when a degraded provider improves.

Suggested Implementation

Extend healthTracker.ts to maintain a decaying-weighted score per provider (e.g. exponential moving average of success/latency/timeout signals). Implement selection logic in adaptiveContractProvider.ts that picks the best-scoring provider per call, with periodic health-check probes to degraded providers so they can recover into rotation without requiring a full app restart.

Acceptance Criteria

• Health score incorporates latency, error rate, and timeout frequency with configurable weighting
• A provider with a consistently high error rate is deprioritized in routing within a bounded number of calls
• A previously-degraded provider automatically recovers into normal rotation once its health score improves
• Unit tests simulate multi-provider scenarios: one healthy/one degraded, all degraded, and recovery over time
• pnpm test:run passes

Likely Affected Files/Directories

• src/contracts/providers/adaptiveContractProvider.ts
• src/contracts/providers/healthTracker.ts
• src/contracts/providers/adaptive.types.ts
• src/contracts/providers/provider.types.ts

[peter-j23]

Hi maintainer,
I’m particularly interested in tackling this issue as it aligns well with my experience.

A bit about myself, I have 4 years of experience building production-grade software, so I’m comfortable with strict testing, CI pipelines, and writing clean, documented code. And i will like to resolve this issue if assigned

[Lspnjr1]

Hello maintainers,
I’m Lspnjr1
I would like to be assigned to this issue. After reviewing the requirements, I’m confident that I understand the scope of the task and the project’s contribution criteria. I believe I can deliver a clean, maintainable implementation that aligns with the project’s standards.

[grantfox-oss]

🦊 GrantFox — @peter-j23 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #430)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[peter-j23]

@Lakes41 PR #438 is ready for review: #438