Fallback Transport

The fallback Transport consumes multiple Transports. If a Transport request fails, it will fall back to the next one in the list.

Import

import { fallback } from 'viem'

import { fallback } from 'viem'

Usage

import { createPublicClient, fallback, http } from 'viem'
import { mainnet } from 'viem/chains'

const alchemy = http('https://eth-mainnet.g.alchemy.com/v2/...')
const infura = http('https://mainnet.infura.io/v3/...')

const client = createPublicClient({
  chain: mainnet,
  transport: fallback([alchemy, infura]),
})

import { createPublicClient, fallback, http } from 'viem'
import { mainnet } from 'viem/chains'

const alchemy = http('https://eth-mainnet.g.alchemy.com/v2/...')
const infura = http('https://mainnet.infura.io/v3/...')

const client = createPublicClient({
  chain: mainnet,
  transport: fallback([alchemy, infura]),
})

Transport Ranking

Transport Ranking enables each of the Transports passed to the fallback Transport are automatically ranked based on their latency & stability via a weighted moving score algorithm.

Every 10 seconds (interval), the fallback Transport will ping each transport in the list. For the past 10 pings (sampleCount), they will be ranked based on if they responded (stability) and how fast they responded (latency). The algorithm applies a weight of 0.7 to the stability score, and a weight of 0.3 to the latency score to derive the final score which it is ranked on.

The Transport that has the best latency & stability score over the sample period is prioritized first.

You can turn on automated ranking with the rank option:

const client = createPublicClient({
  chain: mainnet,
  transport: fallback(
    [alchemy, infura],
    { rank: true } 
  ),
})

const client = createPublicClient({
  chain: mainnet,
  transport: fallback(
    [alchemy, infura],
    { rank: true } 
  ),
})

You can also modify the default rank config:

const client = createPublicClient({
  chain: mainnet,
  transport: fallback(
    [alchemy, infura],
    { 
      rank: {
        interval: 60_000,
        sampleCount: 5,
        timeout: 500,
        weights: {
          latency: 0.3,
          stability: 0.7
        }
      }
    }
  ),
})

const client = createPublicClient({
  chain: mainnet,
  transport: fallback(
    [alchemy, infura],
    { 
      rank: {
        interval: 60_000,
        sampleCount: 5,
        timeout: 500,
        weights: {
          latency: 0.3,
          stability: 0.7
        }
      }
    }
  ),
})

Parameters

rank (optional)

Type: boolean | RankOptions
Default: false

Whether or not to automatically rank the Transports based on their latency & stability. Set to false to disable automatic ranking.

const transport = fallback([alchemy, infura], {
  rank: false, 
})

const transport = fallback([alchemy, infura], {
  rank: false, 
})

rank.interval (optional)

Type: number
Default: client.pollingInterval

The polling interval (in ms) at which the ranker should ping the RPC URL.

const transport = fallback([alchemy, infura], {
  rank: { 
    interval: 5_000
  },
})

const transport = fallback([alchemy, infura], {
  rank: { 
    interval: 5_000
  },
})

rank.sampleCount (optional)

Type: number
Default: 10

The number of previous samples to perform ranking on.

const transport = fallback([alchemy, infura], {
  rank: { 
    sampleCount: 10
  },
})

const transport = fallback([alchemy, infura], {
  rank: { 
    sampleCount: 10
  },
})

rank.timeout (optional)

Type: number
Default: 1_000

Timeout when sampling transports.

const transport = fallback([alchemy, infura], {
  rank: { 
    timeout: 500
  },
})

const transport = fallback([alchemy, infura], {
  rank: { 
    timeout: 500
  },
})

rank.weights.latency (optional)

Type: number
Default: 0.3

The weight to apply to the latency score. The weight is proportional to the other values in the weights object.

const transport = fallback([alchemy, infura], {
  rank: {
    weights: {
      latency: 0.4, 
      stability: 0.6
    }
  },
})

const transport = fallback([alchemy, infura], {
  rank: {
    weights: {
      latency: 0.4, 
      stability: 0.6
    }
  },
})

rank.weights.stability (optional)

Type: number
Default: 0.7

The weight to apply to the stability score. The weight is proportional to the other values in the weights object.

const transport = fallback([alchemy, infura], {
  rank: {
    weights: {
      latency: 0.4,
      stability: 0.6 
    }
  },
})

const transport = fallback([alchemy, infura], {
  rank: {
    weights: {
      latency: 0.4,
      stability: 0.6 
    }
  },
})

retryCount (optional)

Type: number
Default: 3

The max number of times to retry when a request fails.

Note: The fallback will first try all the Transports before retrying.

const transport = fallback([alchemy, infura], {
  retryCount: 5, 
})

const transport = fallback([alchemy, infura], {
  retryCount: 5, 
})

retryDelay (optional)

Type: number
Default: 150

The base delay (in ms) between retries. By default, the Transport will use exponential backoff (~~(1 << count) * retryDelay), which means the time between retries is not constant.

const transport = fallback([alchemy, infura], {
  retryDelay: 100, 
})

const transport = fallback([alchemy, infura], {
  retryDelay: 100, 
})

Fallback Transport ​

Import ​

Usage ​

Transport Ranking ​

Parameters ​

rank (optional) ​

rank.interval (optional) ​

rank.sampleCount (optional) ​

rank.timeout (optional) ​

rank.weights.latency (optional) ​

rank.weights.stability (optional) ​

retryCount (optional) ​

retryDelay (optional) ​