Migration Guide

If you are coming from an earlier version of @wagmi/core, you will need to make sure to update the following APIs listed below.

0.9.x Breaking changes

Upgrade to typescript@>=4.9.4

TypeScript 5.0 is coming soon and has some great features we are excited to bring into wagmi. To prepare for this, update your TypeScript version to 4.9.4 or higher. There are likely no breaking changes if you are coming from typescript@4.7.x || typescript@4.8.x.

0.8.x Breaking changes

Chain exports

With the introduction of the @wagmi/core/chains entrypoint, @wagmi/core no longer exports the following:

chain
allChains
defaultChains
defaultL2Chains
chainId
etherscanBlockExplorers
alchemyRpcUrls, infuraRpcUrls, publicRpcUrls

Read below for migration steps.

Removed `chain`

The chain export has been removed. @wagmi/core now only exports the mainnet & goerli chains. If you need to use an alternative chain (polygon, optimism, etc), you will need to import it from the @wagmi/core/chains entrypoint.

import {
- chain
  configureChains
} from '@wagmi/core'
+ import { mainnet, polygon, optimism } from '@wagmi/core/chains'
 
const { ... } = configureChains(
- [chain.mainnet, chain.polygon, chain.optimism],
+ [mainnet, polygon, optimism],
  {
    ...
  }
)

Removed `allChains`

The allChains export has been removed. If you need a list of all chains, you can utilize @wagmi/core/chains entrypoint.

- import { allChains } from '@wagmi/core'
+ import * as allChains from '@wagmi/core/chains'
 
const { ... } = configureChains(allChains, ...)

Removed `defaultChains` & `defaultL2Chains`

The defaultChains & defaultL2Chains exports have been removed. If you still need the defaultChains or defaultL2Chains exports, you can build them yourself:

- import { defaultChains } from '@wagmi/core'
+ import { mainnet, goerli } from '@wagmi/core/chains'
 
+ const defaultChains = [mainnet, goerli]

The defaultChains export was previously populated with mainnet & goerli.

- import { defaultL2Chains } from '@wagmi/core'
+ import {
+   arbitrum,
+   arbitrumGoerli,
+   polygon,
+   polygonMumbai,
+   optimism,
+   optimismGoerli
+ } from '@wagmi/core/chains'
 
+ const defaultL2Chains = [
+  arbitrum,
+  arbitrumGoerli,
+  polygon,
+  polygonMumbai,
+  optimism
+  optimismGoerli
+ ]

The defaultL2Chains export was previously populated with arbitrum & optimism.

Removed `chainId`

The chainId export has been removed. You can extract a chain ID from the chain itself.

- import { chainId } from '@wagmi/core'
+ import { mainnet, polygon, optimism } from '@wagmi/core/chains'
 
-const mainnetChainId = chainId.mainnet
-const polygonChainId = chainId.polygon
-const optimismChainId = chainId.optimism
+const mainnetChainId = mainnet.chainId
+const polygonChainId = polygon.chainId
+const optimismChainId = optimism.chainId

Removed `etherscanBlockExplorers`

The etherscanBlockExplorers export has been removed. You can extract a block explorer from the chain itself.

- import { etherscanBlockExplorers } from '@wagmi/core'
+ import { mainnet, polygon, optimism } from '@wagmi/core/chains'
 
-const mainnetEtherscanBlockExplorer = etherscanBlockExplorers.mainnet
-const polygonEtherscanBlockExplorer = etherscanBlockExplorers.polygon
-const optimismEtherscanBlockExplorer = etherscanBlockExplorers.optimism
+const mainnetEtherscanBlockExplorer = mainnet.blockExplorers.default
+const polygonEtherscanBlockExplorer = polygon.blockExplorers.default
+const optimismEtherscanBlockExplorer = optimism.blockExplorers.default

Removed `alchemyRpcUrls`, `infuraRpcUrls` & `publicRpcUrls`

The alchemyRpcUrls, infuraRpcUrls & publicRpcUrls exports have been removed. You can extract a RPC URL from the chain itself.

- import { alchemyRpcUrls, infuraRpcUrls, publicRpcUrls } from '@wagmi/core'
+ import { mainnet } from '@wagmi/core/chains'
 
-const mainnetAlchemyRpcUrl = alchemyRpcUrls.mainnet
-const mainnetInfuraRpcUrl = infuraRpcUrls.mainnet
-const mainnetOptimismRpcUrl = publicRpcUrls.mainnet
+const mainnetAlchemyRpcUrl = mainnet.rpcUrls.alchemy
+const mainnetInfuraRpcUrl = mainnet.rpcUrls.infura
+const mainnetOptimismRpcUrl = mainnet.rpcUrls.optimism

`Chain` type

RPC URLs

The rpcUrls shape has changed to include an array of URLs, and also the transport method (http or webSocket):

type Chain = {
  ...
  rpcUrls: {
-   [key: string]: string
+   [key: string]: {
+     http: string[]
+     webSocket: string[]
+   }
  }
  ...
}

Note that you will also need to ensure that usage is migrated:

- const rpcUrl = mainnet.rpcUrls.alchemy
+ const rpcUrl = mainnet.rpcUrls.alchemy.http[0]

Contracts

The multicall and ens attributes have been moved into the contracts object:

type Contract = {
  address: Address
  blockCreated?: number
}
 
type Chain = {
  ...
- multicall: Contract
- ens: Contract
+ contracts: {
+   multicall3: Contract
+   ensRegistry: Contract
+ }
  ...
}

Note that you will also need to ensure that usage is migrated:

- const multicallContract = mainnet.multicall
+ const multicallContract = mainnet.contracts.multicall3

waitForTransaction

Behavioral changes

waitForTransaction will throw an error if the transaction has been reverted or cancelled.

Configuration changes

Removed the wait config option on waitForTransaction. Use the transaction hash instead.

const { data } = await waitForTransaction({
- wait: transaction.wait
+ hash: transaction.hash
})

Getting Started TypeScript