The Future of wagmi

[jxom]

Over the past couple of months, the wagmi core team have actively been planning and designing the future of wagmi, including: the migration to viem, refactor of surface APIs, docs polish, internal library upgrades (TypeScript 5, React Query 5, etc), and more.

The future of wagmi will come in two phases: v1 and v2. This discussion outlines the timeline of the v1 and v2 rollout, and what to expect from from each phase (general overview & breaking changes).

The largest notable change is that wagmi v1 will no longer be built on top of Ethers.js. We will be migrating to viem.

wagmi v2 will include other API refactors, unrelated to viem, to improve the general developer experience of wagmi.

---

v1

Release Date: May 2023
NPM: npm i wagmi@1

The v1 release will only include the migration from ethers.js to viem, and nothing else. v1 will be wagmi how it is today, and the APIs will still be & feel very similar to 0.x. However, we will need to introduce some small breaking changes to escape "ethers" terminology. We expect these breaking changes will make the API more clear though.

v1 will be a stable release.

Below, we have listed the approximated breaking changes, so you can start thinking ahead.

Breaking Changes Overview

General

• Migrated from Ethers v5 to viem
• BigNumber will be removed in favor of native BigInt
• gasLimit is now gas (still means the same, but aligns closer to Ethereum terminology / EIP-1474)
• Ethers v5 "Provider" & "Signer" terminology is now known as viem's "Public Client" & "Wallet Client" terminology. Meaning:
  • provider / webSocketProvider is now publicClient / webSocketPublicClient
  • signer is now walletClient

Actions & Hooks

Many of the Actions & Hooks below map one-to-one and share a similar API to viem's Actions.

connect / useConnect

• No longer returns the provider property. Use connector.getProvider() instead.

fetchBalance / useBalance

• Returns a bigint instead of BigNumber for value
• Maps to viem's getBalance

fetchBlockNumber / useBlockNumber

• Returns a bigint instead of a number
• Maps to viem's getBlockNumber

fetchEnsAvatar / useEnsAvatar

• Replaced address with name
• Maps to viem's getEnsAvatar

fetchFeeData / useFeeData

• Returns bigint instead of a BigNumber for gasPrice , maxFeePerGas , maxPriorityFeePerGas

fetchSigner / useSigner / watchSigner

• Returns viem's Wallet Client (with account ) instead of Ethers JsonRpcSigner

fetchToken / useToken

• Returns bigint instead of a BigNumber for totalSupply.value

fetchTransaction / useTransaction

• Returns viem Transaction instead of an ethers Transaction
• Maps to viem's getTransaction

getContract

• Returns viem Contract Instance instead of Ethers Contract Instance.

getProvider / useProvider / watchProvider

• Renamed to getPublicClient / usePublicClient
• Returns viem's Public Client instad of Ethers Provider

getWebSocketProvider / useWebSocketProvider / watchWebSocketProvider

• Renamed to getWebSocketPublicClient / useWebSocketPublicClient
• Returns viem's Public Client instad of Ethers Provider

multicall

• Changed structure of return type:
  • When allowFailure: true (default), returns { error, result, status }[] shape instead of an array of results Result[]
  • When allowFailure: false , returns array of results Result[]
  • Why? We are including error and status so a consumer can inspect and retrieve error data without it being silently disposed of.
• Removed console.warn logs for thrown errors when allowFailure: true
  • Why? These errors can be obtained from the returned array now.
  • Maps to viem's readContract parameters
• Maps to viem's multicall.

prepareSendTransaction / usePrepareSendTransaction

• Removed the overrides option in favor top-level account, gas, maxFeePerGas , etc options.
  • Maps to viem's sendTransaction parameters

prepareWriteContract / usePrepareContractWrite

• Removed abi, address, functionName from the return value, they now belong in request
• The returned request now returns the shape of viem's WriteContractParameters instead of Ethers' TransactionRequest
• Removed the overrides option in favor top-level account, gas, maxFeePerGas , etc options.
  • Maps to viem's simulateContract parameters
  • Why? The "overrides" concept is a bit ambiguous. Some consumers thought that "overrides" applies to the contract function implementation, when it actually is just an JSON-RPC eth_sendTransaction parameter.
• Maps to viem's simulateContract

readContract / useContractRead

• Removed the overrides option in favor top-level blockNumber & blockTag options.
  • Maps to viem's readContract parameters
  • Why? The "overrides" concept is a bit ambiguous. Some consumers thought that "overrides" applies to the contract function implementation, when it actually is just an JSON-RPC eth_call parameter.
• Maps to viem's readContract

readContracts / useContractReads / useContractInfiniteReads

• Removed the overrides option in favor top-level blockNumber & blockTag options.
  • Maps to viem's readContract parameters
  • Why? The "overrides" concept is a bit ambiguous. Some consumers thought that "overrides" applies to the contract function implementation, when it actually is just an JSON-RPC eth_call parameter.
• Changed structure of return type:
  • When allowFailure: true (default), returns { error, result, status }[] shape instead of an array of results Result[]
  • When allowFailure: false , returns array of results Result[]
  • Why? We are including error and status so a consumer can inspect and retrieve error data without it being silently disposed of.
• Removed console.warn logs for thrown errors when allowFailure: true
  • Why? These errors can be obtained from the returned array now.
• Maps to viem's multicall

signMessage / useSignMessage

• message no longer accepts a byte array, only a string value.
• Maps to viem's signMessage

signTypedData

• value has been renamed to message
  • Why? Aligns closer to Ethereum & EIP-712 terminology.
• primaryType is now required.
  • Why? Aligns closer to EIP-712, and allows consumers to specify an alternative primary type. Previously, Ethers.js did some internal stuff to figure out the primary type. But it's not hard for a consumer to just provide that – and we believe it is more clear.
• Maps to viem's signTypedData

useContract

• Hook Removed. Use the getContract Action instead.

waitForTransaction/useWaitForTransaction

• Renamed onSpeedUp to onReplaced
• Now returns a viem TransactionReceipt instead of an Ethers TransactionReceipt

watchPendingTransactions / useWatchPendingTransactions

• Callback now returns a batched array of transaction hashes, instead of callback being emitted several times with singular hashes.
• Maps to viem's watchPendingTransactions

writeContract / useContractWrite

• wait has been removed from the return type, favor waitForTransaction / useWaitForTransaction instead.
• Removed the overrides option in favor top-level account, gas, maxFeePerGas , etc options.
  • Maps to viem's writeContract parameters
  • Why? The "overrides" concept is a bit ambiguous. Some consumers thought that "overrides" applies to the contract function implementation, when it actually is just an JSON-RPC eth_sendTransaction parameter.
• Maps to viem's writeContract

watchContractEvent / useContractEvent

• Callback now returns an array of Event Logs (w/ included decoded args), instead of positional decoded args with the log.
• Removed the once config option.
• Maps to viem's watchContractEvent

configureChains

• Removed quorum support – priority , minQuorum and targetQuorum (for now). viem does not support quorum in the fallback Transport yet, but will in the future!

Connectors

• getSigner now returns a viem WalletClient instead of an Ethers Signer
• Removed Signer generic.

Errors

• Removed ChainDoesNotSupportMulticallError, ContractMethodDoesNotExistError, ContractMethodNoResultError, ContractMethodRevertedError, ContractResultDecodeError, ProviderRpcError, ResourceUnavailableError
• Can use viem aligned errors instead – will include a migration guide for that.

---

v2

Release Date: June 2023

NPM: npm i wagmi@2

Approximately a month after the v1 release, we will be releasing v2. This phase will include other API refactors, unrelated to viem, that we have been meaning to do. These include: upgrading to React Query 5 + more flexible React Query patterns, TypeScript 5, consolidating configureChains into createConfig, removing/repurposing Prepare Hooks (!!), and more.

Features Overview

Renaming the wagmi "Client" to the wagmi "Config"

To remove ambiguity between the wagmi Client and the viem Clients, we are going to be renaming the wagmi "Client" to the wagmi "Config".

- import { createClient } from 'wagmi'
+ import { createConfig } from 'wagmi'

- const client = createClient(...)
+ const config = createConfig(...)

Remove configureChains & RPC Provider (alchemyProvider, etc) utilities

We will be removing the configureChains utility and be directly integrating it into createConfig. This means that consumers will import less and have less code to set up a wagmi project, while still having the flexibility to configure chains, connectors & RPC URLS.

We will also most likely removing the RPC Provider utilties (alchemyProvider, infuraProvider, etc) in favor of the consumer directly passing the RPC URL themselves for each chain. We understand this may be more verbose, but it is much a "set & forget" kind of thing.

By default, we will recommend consumers to provide a "high-level" config to createClient, which will internally create a multi-chain viem Public Client to use in wagmi.

import { http, fallback } from 'viem'
import { createConfig } from 'wagmi'
import { mainnet, goerli } from 'wagmi/chains'
import { injected } from 'wagmi/connectors/injected'

createConfig({
  chains: [mainnet, goerli],
  connectors: [injected()],
  transports: {
    // Keys inferred by TypeScript. `transports` will error if you have not specified all `chains`.
    [mainnet.id]: fallback([
      http('https://eth-mainnet.g.alchemy.com/v2/...'), // a la. alchemyProvider()
      http('https://mainnet.infura.io/v3/...'), // a la. infuraProvider()
      http() // a la. publicProvider()
    ]),
    [goerli.id]: http(),
  },
})

Consumers will also be able to pass in a "low-level" config (escape hatch), where they will be able to directly pass through a viem Public Client instead of wagmi doing it under-the-hood (as seen in the "high-level" config above).

import { createPublicClient } from 'viem'
import { createConfig } from 'wagmi'
import { mainnet, goerli } from 'wagmi/chains'
import { injected } from 'wagmi/connectors/injected'

// Multi-chain
createConfig({
  chains: [mainnet, goerli],
  connectors: [injected()],
  publicClient: (chain) =>
    createPublicClient({
      chain,
      transport: http(),
    }),
})

// Single-chain
// Note that we do not accept `chains` here, it is inferred from Client.
createConfig({
  connectors: [injected()],
  publicClient: createPublicClient({
    chain: mainnet,
    transport: http(),
  }),
})

The removal of the global wagmi Client

The global wagmi Client has deemed to be problematic for @wagmi/core (and some wagmi) consumers, and caused some issues around "No wagmi client found.". This was mostly a side-effect from the "dual-package hazard" when wagmi published CJS + ESM packages. We will be removing the global wagmi Client in favour of a Client in which the consumer will have to inject (only applies to @wagmi/core).

Regardless, we think that setting global variables in a JavaScript library is an anti-pattern anyway, so we are going to remove it.

As the global Client will be removed, this will mean that consumers will need to provide Client context to @wagmi/core Actions. We think injecting the Client (or Config) as a first parameter might be the way to go (subject to change):

import { fetchBlockNumber } from 'wagmi'
import { config } from './config'

const blockNumber = await fetchBlockNumber(config)

Repurpose Prepare Hooks

One of the main reasons why we introduced Prepare Hooks was to mitigate iOS universal link issues seen when performing long-running asynchronous tasks in an event handler (ie. you would be redirected to a wallet app store or fallback page if you pressed an action). However, WalletConnect is now prioritizing deep links over universal links which come with the advantage that end-users will no longer be unexpectedly redirected – they will instead see a prompt to open the app.

As a result, this means that consumers no longer need to use Prepare Hooks. We aren't going to be completely removing them, as they are still useful for reducing the "time-to-open-wallet" and for contract/transaction simulation, but we may rename them to useSimulateContract & useSimulateTransaction. This means that imperatively passing dynamic arguments will be easier, and also means we will be removing all the "recklessly" terminology.

If you were familiar with useContractWrite & useSendTransaction before Prepare Hooks were introduced, the API will be very similar.

Upgrade to React (TanStack) Query 5

We will be upgrading to React (TanStack) Query to version 5. This comes with it's own list of features & breaking changes: TanStack/query#4252

Export Query Keys/Functions from @wagmi/core

We will be moving the React Query (TanStack Query) query keys & functions from the React entrypoint (wagmi), to the Vanilla JS core @wagmi/core . We will also be exporting them!

This means that consumers will be able to use native TanStack Query functionality like prefetchQuery, setQueryData , etc with wagmi's Query Keys & Functions.

This also means that consumers will easily be able to extend wagmi onto other frameworks such as Vue, Svelte & Solid by utilizing TanStack Query's framework adapters (Vue, Solid, Svelte, etc).

You could imagine that @wagmi/core will have a "Query Options" API: https://twitter.com/tkdodo/status/1628453270401294337?s=46&t=JT6DdzO0r2xvkFHm1auj1w

Rename autoConnect to reconnect and make it default truthy

autoConnect will be renamed to reconnect

Most of the wagmi usages (and the docs) set autoConnect: true , and it generally accompanies a better user experience, so we are going to default reconnect to true .

Function-based Connectors

Currently, our Connectors are class-based. We plan to migrate Connectors to be function-based for better internal config currying DX.

[WiseMrMusa]

Keep up the great work. WAGMI

[lochie]

🫡

[ECBSJ]

What's the purpose of transitioning to viem?

[jxom]

https://viem.sh/docs/introduction.html

[sammdec]

🫡

[roninjin10]

Removing infuraProvider and alchemyProvider is good for everybody. Using rpc urls is a general practic everybody should follow so you can more quickly swap to a different provider at any moment with a simple env variable change without a code change

[orionsolidified]

Keep up the great work.

[brendanjryan]

Have no FUD on the above and excited for both of these releases!

Am a strong +1 to removal of provider-specific RPC utilities and new changes to wagmi config to make injecting a custom viem config easier.

[garrettparris]

I would say more of a focus on SSR and integration with next js. Right now if you look at the wagmi example you see that the example waits until we are client side to render anything and provide access to hooks, if youre using a next.js app and try and display an account address using the useAccount() hook it spits a hydration error and you have to abstract the hook to use it. I see that React Query may be able to help this, another option I like is swr. In my opinion swr is the better choice since its SSR first, and for all use cases of dapps, the extra bells and whistles on react query arent that necessary since dapps in general are quite simple.

[roninjin10]

I agree but would caution that the best long term strategy here is to make sure wagmi stays aligned with react query’s ssr story (which may be in massive flux as they figure out server components)

[jxom]

tbh, i'd recommend suppressHydrationWarning if you don't want to wrap things around isMounted variables. For 95% of cases, you probably don't need to render persisted wagmi data on the server, and for the cases in which you do, you might want to use a React Server Component with @wagmi/core instead.

[glitch-txs]

What are the downside of that one? I'm currently using dynamic import with ssr:false I think it's similar to isMounted but it avoids an extra render right?

[t0rbik]

I wonder if RainbowKit will work with Wagmi 1.0 out of the box? Are they synced about switching to viem?

[jxom]

We work very closely with the RainbowKit, ConnectKit, and Web3Modal teams (we constantly communicate), and they should support v1 from launch (or closely after)!

[t0rbik]

awesome!

[DanielSinclair]

We'll be migrating and will keep version parity to ensure a smooth transition 🫡

[dionysuzx]

that’s great to hear. i use svelte with web3modal—excited for this!

[DannyDelott]

fetchBlockNumber / useBlockNumber

Returns a bigint instead of a number
Maps to viem's getBlockNumber

Curious why this is a bigint now. Is number insufficient? We do stuff with blocknumbers and haven't run into issues w/ precision.

[roninjin10]

Not sure the reason but BigInt is more futureproof. Numbers work today but aren’t guaranteed to work in future

[DannyDelott]

Hmm, the max safe integer is 9007199254740991. Even if blocks are mined every second that is still 285.6M years before overflow.

[roninjin10]

Haha true but superchains

[DannyDelott]

After thinking about it some more, I reckon bigint is the way to go. It's safer than number because it only deals with whole numbers, which is what we need for block numbers.

[kyscott18]

Exporting query keys from @wagmi/core will be super helpful. Right now I had to manually copy the functions over to do things like invalidate data when a user sends a transaction. I am also wondering if the full react-query api will be supported? Specifically refetchInterval is not being used right now and makes updating data somewhat difficult.

[tmm]

Yup! The full API will be supported as well.

[kyscott18]

Is there a reason it isn't fully supported right now?

Also, is it possible to support the react-query devtools?

[tmm]

Is there a reason it isn't fully supported right now?

Wanted to keep our options open at the time so we created our own useQuery hooks on top of the core React Query observer. We feel good about the future of Tanstack Query now so going to remove our custom code and make it much easier to pass through options.

Also, is it possible to support the react-query devtools?

Yup!

[kyscott18]

Cool, I was just wondering. Thanks, excited to use the new wagmi!

[styopaiv]

wait has been removed from the return type, favor waitForTransaction / useWaitForTransaction instead.

I might be missing something, but i had a use case when i needed to use wait instead of waitForTransaction. I'm not sure about the internal details, but onSettled from useWaitForTransaction fires way earlier than promise resolve of wait. In my case subgraph wasn't synching fast enough with onSettled, the sync was ready only with a resolve of wait promise.

[firnprotocol]

I just had an unusual case in which waitForTransaction fired "transaction not found", even though it was (soon) successfully mined.

this behavior seems wrong: the thing's whole point is to wait till the thing is confirmed. if the transaction isn't spotted in the mempool yet, the thing shouldn't throw, it should be patient until it finds it.

any explanation? thanks in advance.

[tmm]

What RPC provider are you using? Can you create a minimal example? Could be an issue there.

[firnprotocol]

this was on Optimism, using an Alchemy provider (with API key). i'm on wagmi 1.0.5 and viem 0.3.26. unfortunately i am not able to reproduce this at the moment.

[jxom]

Latest version of viem should have more robust txn waiting.

[firnprotocol]

hmm, k. upgraded to 0.3.31. will let you know if i see it again

[firnprotocol]

hi all, just would like to broadcast this here: is there any way we get the ability to retrieve blocks in wagmi v1? does anyone else have this need? please see this discussion. huge thanks in advance.

[kasparkallas]

The removal of the global wagmi Client

Thanks for this attention to detail! I have interest in wrapping the contract interaction part of @wagmi/core with RTK Query similar to how wagmi wraps with React Query. Not having the global client (an ambient context) would make the design easier to follow.

[flymauntains]

Thank for article. wagmi2.0, give me writecontract example vs wagmi1.0 writecontract example.