Configuring Chains

The configureChains function allows you to configure your chains with providers such as: Alchemy, Infura, or something else. This means you don't need to worry about defining RPC URLs and chain configuration in your connector or provider. This is managed internally by wagmi.

import { configureChains } from 'wagmi'

Usage

configureChains accepts an array of chains and an array of providers. It returns:

chains: to pass to your connector(s)
provider: to pass to createClient
webSocketProvider: to optionally pass to createClient

import { configureChains, createClient, defaultChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'
import { InjectedConnector } from 'wagmi/connectors/injected'

const { chains, provider } = configureChains(defaultChains, [
  alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
  publicProvider(),
])

const wagmiClient = createClient({
  autoConnect: true,
  connectors: [new InjectedConnector({ chains })],
  provider,
})

🔗

The publicProvider ensures that your chains always have an RPC URL to fall back on (in case Alchemy does not support the chain).

⚠️

If a user has their wallet connected to a chain that is unsupported by your app, the provider will use the first chain listed in the chains array.

Multiple providers

The configureChains function accepts multiple providers. This is useful if not all your chains support a single provider. For example, you may want to use Alchemy for Ethereum, and avax.network for Avalanche.

configureChains wraps the providers that you provide into an ethers.js FallbackProvider, that comes with support for:

Falling back to another provider if a provider goes down (e.g. If Infura goes down, we can fall back to Alchemy)
Ensuring the responses are legitimate by setting a targetQuorum.

import { Chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { infuraProvider } from 'wagmi/providers/infura'
import { jsonRpcProvider } from 'wagmi/providers/jsonRpc'

const avalancheChain: Chain = {
  id: 43_114,
  name: 'Avalanche',
  network: 'avalanche',
  nativeCurrency: {
    decimals: 18,
    name: 'Avalanche',
    symbol: 'AVAX',
  },
  rpcUrls: {
    default: 'https://api.avax.network/ext/bc/C/rpc',
  },
  blockExplorers: {
    default: { name: 'SnowTrace', url: 'https://snowtrace.io' },
  },
  testnet: false,
}

const { provider } = configureChains(
  [chain.mainnet, avalancheChain],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    jsonRpcProvider({
      rpc: (chain) => {
        if (chain.id !== avalancheChain.id) return null
        return { http: chain.rpcUrls.default }
      },
    }),
  ],
)

Quorum

If the targetQuorum option is set to a value greater than 1, it will dispatch interactions to multiple providers, in which the responses are verified by comparing them to each other. If the quorum is reached, then the result will be returned to the consumer.

const { provider } = configureChains(
  [chain.mainnet, avalancheChain],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    jsonRpcProvider({
      rpc: (chain) => {
        if (chain.id !== avalancheChain.id) return null
        return { http: chain.rpcUrls.default }
      },
    }),
  ],
  { targetQuorum: 2 },
)

By default, for a given chain, it will attempt to set the quorum value, but if the targetQuorum value is greater than the number of providers for the chain, it will default to the number of providers.

For instance, in the example provided above targetQuorum = 2, however there is only 1 available provider for Avalanche (jsonRpcProvider), so the quorum will get set to 1.

To guarentee a static quorum, you can provide a minQuorum as an config option.

Arguments

chains

Chains that need to be configured.

import { chain, configureChains } from 'wagmi'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [publicProvider()],
)

providers

The providers the app supports.

If a provider does not support a chain, it will fall back onto the next one in the array. If no RPC URLs are found, configureChains will throw an error.

import { chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [alchemyProvider({ apiKey: 'yourAlchemyApiKey' }), publicProvider()],
)

Configuration

pollingInterval (optional)

The frequency in milliseconds at which the provider polls. Defaults to 4000.

import { chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    publicProvider(),
  ],
  { pollingInterval: 10_000, targetQuorum: 3 },
)

targetQuorum (optional)

Sets the target quorum. Defaults to 1.

import { chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    publicProvider(),
  ],
  { targetQuorum: 3 },
)

minQuorum (optional)

Sets the minimum quorum that must be accepted by the providers. Defaults to 1.

import { chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    publicProvider(),
  ],
  { targetQuorum: 3, minQuorum: 2 },
)

stallTimeout (optional)

The timeout in milliseconds after which another provider will be attempted.

import { chain, configureChains } from 'wagmi'
import { alchemyProvider } from 'wagmi/providers/alchemy'
import { publicProvider } from 'wagmi/providers/public'

const { chains } = configureChains(
  [chain.mainnet, chain.optimism],
  [
    alchemyProvider({ apiKey: 'yourAlchemyApiKey' }),
    infuraProvider({ apiKey: 'yourInfuraApiKey' }),
    publicProvider(),
  ],
  { stallTimeout: 5000 },
)

Last updated on July 25, 2022