@tetherto/wdk-provider-failover

A resilient wrapper for WDK wallet instances that provides automatic failover across multiple provider configurations with configurable retry logic.

Features

• Automatic failover - Cascades through multiple provider configurations when failures occur
• Configurable retries - Retry failed operations with exponential backoff and jitter
• Lazy instantiation - Wallet instances are created only when needed
• Proxy-based - Transparent wrapper that preserves the original wallet API
• Lifecycle management - Proper cleanup of resources via dispose()

Installation

npm install @tetherto/wdk-provider-failover

Usage

Basic Example

import { createFallbackWallet } from '@tetherto/wdk-provider-failover'
import { WalletAccountReadOnlyEvm } from '@tetherto/wdk-wallet-evm'

const wallet = createFallbackWallet(
  WalletAccountReadOnlyEvm,
  ['0x742d35Cc6634C0532925a3b844Bc9e7595f...'], // constructor args
  {
    primary: { provider: 'https://mainnet.infura.io/v3/YOUR_KEY' },
    fallbacks: [
      { provider: 'https://eth.llamarpc.com' },
      { provider: 'https://ethereum.publicnode.com' }
    ]
  }
)

// Use the wallet as normal - failover is automatic
const balance = await wallet.getBalance()

// Clean up when done
await wallet.dispose()

With Custom Options

const wallet = createFallbackWallet(
  WalletAccountReadOnlyEvm,
  [address],
  {
    primary: { provider: primaryRpcUrl },
    fallbacks: [
      { provider: fallbackRpcUrl1 },
      { provider: fallbackRpcUrl2 }
    ],
    fallbackOptions: {
      timeout: 5000,              // 5 second timeout per call
      maxRetries: 3,              // Retry current provider 3 times before switching
      retryDelay: 1000,           // Base delay between retries (ms)
      exponentialBackoff: true,   // Double delay on each retry
      jitter: true,               // Add randomness to prevent thundering herd
      fallbackMethods: ['getBalance', 'getTransactions'], // Only wrap specific methods
      logger: customLogger,       // Custom logging function
      onFallback: (index, config) => {
        console.log(`Switching to provider ${index}`)
      },
      onConfigSwitch: (index, config) => {
        console.log(`Successfully using provider ${index}`)
      }
    }
  }
)

API

createFallbackWallet(WalletClass, constructorArgs, config)

Factory function that creates a failover-wrapped wallet instance.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | WalletClass | class | The wallet class to instantiate | | constructorArgs | array | Arguments passed to the wallet constructor (before config) | | config | object | Configuration object (see below) |

Config Object:

| Property | Type | Description | |----------|------|-------------| | primary | object | Primary provider configuration | | fallbacks | array | Array of fallback provider configurations | | fallbackOptions | object | Options for failover behavior (see below) |

Fallback Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeout | number | 10000 | Timeout per method call (ms) | | maxRetries | number | 3 | Retries per provider before switching | | retryDelay | number | 1000 | Base delay between retries (ms) | | exponentialBackoff | boolean | true | Double delay on each retry | | jitter | boolean | true | Add ±15% randomness to delays | | fallbackMethods | string[] | [] | Methods to wrap (empty = all methods) | | logger | function | console | Custom logger function | | onFallback | function | - | Called when switching to a fallback provider | | onConfigSwitch | function | - | Called on successful operation after retries |

Proxy Methods

The returned proxy exposes additional utility methods:

| Method | Returns | Description | |--------|---------|-------------| | dispose() | Promise<void> | Disposes all wallet instances | | getActiveIndex() | number | Current active provider index | | getActiveConfig() | object | Current active provider config | | getInstancesCount() | number | Total number of configured providers | | switchTo(index) | number | Manually switch to a specific provider | | getInstanceUnsafe() | object | Get the current wallet instance directly |

How It Works

1. When a method is called on the proxy, it attempts the operation on the current provider
2. If the call fails or times out, it retries up to maxRetries times with backoff
3. After exhausting retries, it switches to the next provider in the cascade
4. This continues until success or all providers have been exhausted
5. On success, callbacks are invoked to notify of the active configuration

┌─────────────┐     fail      ┌─────────────┐     fail      ┌─────────────┐
│   Primary   │──── retry ───▶│  Fallback 1 │──── retry ───▶│  Fallback 2 │
│  Provider   │   (3 times)   │   Provider  │   (3 times)   │   Provider  │
└─────────────┘               └─────────────┘               └─────────────┘

Custom Logger

The logger function receives structured log data:

const logger = (level, message, meta) => {
  // level: 'debug' | 'info' | 'warn' | 'error'
  // message: string description
  // meta: object with additional context
  console.log(`[${level}] ${message}`, meta)
}

License

Apache-2.0