Skip to content
LogoLogo

Fallback Transport

A function to create a Fallback Transport for a Client

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

Import

import {  } from 'viem'

Usage

import { , ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : ([ 
    ('https://1.rpc.thirdweb.com/...'), 
    ('https://mainnet.infura.io/v3/...') 
  ]), 
})

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  = ({
  : ,
  : ([ 
    ('https://1.rpc.thirdweb.com/...'), 
    ('https://mainnet.infura.io/v3/...') 
  ], { : true }), 
})

You can also modify the default rank config:

const  = ({
  : ,
  : (
    [
      ('https://1.rpc.thirdweb.com/...'), 
      ('https://mainnet.infura.io/v3/...') 
    ],
    { 
      : {
        : 60_000,
        : 5,
        : 500,
        : {
          : 0.3,
          : 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  = ([, ], {
  : false, 
})

rank.interval (optional)

  • Type: number
  • Default: client.pollingInterval

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

const  = ([, ], {
  : { 
    : 5_000
  },
})

rank.ping (optional)

  • Type: ({ transport }: { transport: Transport }) => Promise<unknown>
  • Default: ({ transport }) => transport.request({ method: 'net_listening' })

Function to call to ping the Transport. Defaults to calling the net_listening method to check if the Transport is online.

const  = ([, ], {
  : { 
    : ({  }) => .({ : 'eth_blockNumber' })
  },
})

rank.sampleCount (optional)

  • Type: number
  • Default: 10

The number of previous samples to perform ranking on.

const  = ([, ], {
  : { 
    : 10
  },
})

rank.timeout (optional)

  • Type: number
  • Default: 1_000

Timeout when sampling transports.

const  = ([, ], {
  : { 
    : 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  = ([, ], {
  : {
    : {
      : 0.4, 
      : 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  = ([, ], {
  : {
    : {
      : 0.4,
      : 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  = ([, ], {
  : 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  = ([, ], {
  : 100, 
})

shouldThrow (optional)

  • Type: function

Whether the fallback Transport should immediately throw an error, or continue and try the next Transport.

const  = ([, ], {
  : (: Error) => { 
    return ..('sad times') 
  }, 
})
Suggest changes to this page