https://github.com/tetherto/wdk-failover-provider
https://github.com/tetherto/wdk-failover-provider
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/tetherto/wdk-failover-provider
- Owner: tetherto
- License: apache-2.0
- Created: 2026-01-27T10:44:16.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-05-07T12:56:37.000Z (3 months ago)
- Last Synced: 2026-05-07T14:47:46.759Z (3 months ago)
- Language: JavaScript
- Size: 150 KB
- Stars: 0
- Watchers: 0
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WDK Failover Provider
Zero-dependency failover mechanism for seamless fallback when providers break.
## 🔍 About WDK
This module is part of the [**WDK (Wallet Development Kit)**](https://wallet.tether.io/) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.
For detailed documentation about the complete WDK ecosystem, visit [docs.wallet.tether.io](https://docs.wallet.tether.io).
## ⬇️ Installation
```bash
npm install @tetherto/wdk-failover-provider
```
## 🚀 Quick Start
```ts
import FailoverProvider from '@tetherto/wdk-failover-provider'
import { type AbstractProvider, JsonRpcProvider, BrowserProvider } from 'ethers'
const RPC_PROVIDER = 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY'
// Create a failover provider that will try the BrowserProvider first,
// then fallback to a JSON-RPC provider on errors.
const provider = new FailoverProvider()
.addProvider(new BrowserProvider(window.ethereum))
.addProvider(new JsonRpcProvider(RPC_PROVIDER))
.initialize()
// Calls are proxied and will failover according to the configured retries
;(async () => {
const blockNumber = await provider.getBlockNumber()
console.log('block number', blockNumber)
})()
```
## 📚 API Reference
This package exposes a single default export: the `FailoverProvider` factory.
- `new FailoverProvider(config?)` — Create a factory.
- `config.retries` (number, default `3`): The number of additional retry attempts after the initial call fails. Total attempts = `1 + retries`. For example, `retries: 3` with 4 providers will try each provider once before throwing. If `retries` exceeds the number of providers, the failover will loop back and retry already-failed providers in round-robin order.
- `config.shouldRetryOn` (function, default: `error => error instanceof Error`): predicate to determine whether to retry on a given error.
- `instance.addProvider(provider)` — Add a provider candidate. `provider` can be any object (sync or async methods).
- `instance.initialize()` — Return a proxied provider. Calls to methods are intercepted and automatically retried/failover according to the configuration.
Behavior notes:
- The returned proxied provider forwards non-function properties from the currently active provider.
- When a method throws exceptions and `shouldRetryOn(error)` returns `true`, the proxy switches to the next provider (round-robin) and retries until retries are exhausted.
## 📜 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 🆘 Support
For support, please open an issue on the GitHub repository.