Update wagmi usage docs (#2207)

* Update wagmi usage docs * Refine example imports * Refine wagmi API * Refine docs, examples and use of wallet state to pass wagmiConnector * Merge in develop * Update wagmi docs
blocknative · May 29, 2024 · e00ef35 · e00ef35
1 parent 4bcdc19
commit e00ef35
Show file tree

Hide file tree

Showing 22 changed files with 357 additions and 191 deletions.
diff --git a/docs/src/routes/docs/[...3]modules/[...1]core/+page.md b/docs/src/routes/docs/[...3]modules/[...1]core/+page.md
@@ -108,6 +108,10 @@ type InitOptions {
  wallets: WalletInit[]
  chains: Chain[]
  appMetadata?: AppMetadata
+ /** Web3-Onboard module to add Wagmi support
+ * see https://www.npmjs.com/package/@web3-onboard/wagmi
+ */
+ wagmi?: typeof wagmi
  i18n?: i18nOptions
  accountCenter?: AccountCenterOptions
  apiKey?: string
@@ -388,6 +392,57 @@ It will allow you to customize the look and feel of Web3 Onboard, try different
 
 ---
 
+#### wagmi
+
+To add [WAGMI API](https://wagmi.sh/core/getting-started) support to your project you can simply install `web3-onboard/wagmi` import and pass in the [wagmi package](/docs/modules/wagmi) export directly into your onboard configuration. After doing so you can use all of the native WAGMI API functions directly from `@web3-onboard/wagmi`. This will give access to all WAGMI function available on or before `@wagmi/core` version `2.10.4`.
+After initialization an up-to-date WAGMI config will will be available from the onboard state object `onboard.state.get().wagmiConfig` which will need to be passed as the first prop of most [@wagmi/core](https://wagmi.sh/core/getting-started) methods. Wallets will also have a [wagmiConnector](#state) prop within the onboard state object which will allow you to target specific wallets for interactions. This can also be bi-passed if the primary or most recently connected wallet is the wallet meant for the transactions.
+The config and connectors can be used with the WAGMI API returned from this module or an external WAGMI instance.
+
+Full documentation for the `@web3-onboard/wagmi` module can be found [here](/docs/modules/wagmi).
+
+```typescript
+import Onboard from '@web3-onboard/core'
+import wagmi from '@web3-onboard/wagmi'
+import {
+ sendTransaction as wagmiSendTransaction,
+ switchChain,
+ disconnect,
+ getConnectors
+} from '@web3-onboard/wagmi'
+
+const injected = injectedModule()
+
+const onboard = Onboard({
+ // This javascript object is unordered meaning props do not require a certain order
+ wagmi,
+ wallets: [injected],
+ chains: [
+ {
+ id: '0x1',
+ token: 'ETH',
+ label: 'Ethereum',
+ rpcUrl: 'https://mainnet.infura.io/v3/17c1e1500e384acfb6a72c5d2e67742e'
+ }
+ ]
+ // ... other Onboard options
+})
+
+const sendTransaction = async () => {
+ // current primary wallet - as multiple wallets can connect this value is the currently active
+ const [activeWallet] = onboard.state.get().wallets
+ const { wagmiConnector } = activeWallet
+ const wagmiConfig = onboard.state.get().wagmiConfig
+ const result = await wagmiSendTransaction(wagmiConfig, {
+ to: toAddress,
+ // desired connector to send txn from
+ connector: wagmiConnector,
+ value: parseEther('0.001')
+ })
+ console.log(result)
+}
+```
+---
+
 #### disableFontDownload
 
 If set to `true` the default `Inter` font will not be imported and instead the web based `sans-serif` font will be used if a font is not defined through the `Theme` or exposed css variable.
@@ -845,6 +900,13 @@ type WalletState = {
  accounts: Account[]
  chains: ConnectedChain[]
  instance?: unknown
+ /**
+ * WAGMI Connector object
+ * Can be used to leverage all WAGMI functions from
+ * the @web3-onboard/wagmi module
+ * See https://www.npmjs.com/package/@web3-onboard/wagmi for more details
+ */
+ wagmiConnector?: Connector
 }
 
 type Account = {

diff --git a/docs/src/routes/docs/[...3]modules/[...3]react/+page.md b/docs/src/routes/docs/[...3]modules/[...3]react/+page.md
@@ -137,11 +137,11 @@ function MyApp({ Component, pageProps }) {
 export default MyApp
 ```
 
-## `init`
+## init
 
 The `init` function must be called before any hooks can be used. The `init` function just initializes `web3-onboard` and makes it available for all hooks to use. For reference check out the [initialization docs for `@web3-onboard/core`](../../modules/core.md#initialization)
 
-## `useConnectWallet`
+## useConnectWallet
 
 This hook allows you to connect the user's wallet and track the state of the connection status and the wallet that is connected.
 
@@ -203,7 +203,7 @@ setPrimaryWallet(wallets[1])
 setPrimaryWallet(wallets[1], wallets[1].accounts[2].address)
 ```
 
-## `useSetChain`
+## useSetChain
 
 This hook allows you to set the chain of a user's connected wallet, keep track of the current chain the user is connected to and the status of setting the chain. Passing in a wallet label will operate on that connected wallet, otherwise it will default to the last connected wallet. If a chain was instantiated without an rpcUrl, token, or label, add these options for wallets that require this information for adding a new chain.
 
@@ -243,7 +243,64 @@ const [
 ] = useSetChain()
 ```
 
-## `useNotifications`
+## useWagmiConfig
+
+This hook allows you to get the WagmiConfig (Config from the Wagmi project) from @web3-onboard/core if W3O has been initialized with the [WAGMI property imported and passing into the web3-onboard/core config](../../modules/wagmi.md#usage).
+
+```ts
+import Onboard from '@web3-onboard/core'
+import injectedModule from '@web3-onboard/injected-wallets'
+import wagmi from '@web3-onboard/wagmi'
+import {
+ sendTransaction as wagmiSendTransaction,
+ switchChain,
+ disconnect,
+ getConnectors
+} from '@web3-onboard/wagmi'
+import { parseEther, isHex, fromHex } from 'viem'
+
+const injected = injectedModule()
+
+const onboard = Onboard({
+ wagmi,
+ wallets: [injected],
+ chains: [
+ {
+ id: '0x1',
+ token: 'ETH',
+ label: 'Ethereum',
+ rpcUrl: 'https://mainnet.infura.io/v3/17c1e1500e384acfb6a72c5d2e67742e'
+ }
+ ]
+ // ... other Onboard options
+})
+
+const sendTransaction = async () => {
+ // current primary wallet - as multiple wallets can connect this value is the currently active
+ const [activeWallet] = onboard.state.get().wallets
+ const { wagmiConnector } = activeWallet
+ const wagmiConfig = onboard.state.get().wagmiConfig
+ const result = await wagmiSendTransaction(wagmiConfig, {
+ to: toAddress,
+ // desired connector to send txn from
+ connector: wagmiConnector,
+ value: parseEther('0.001')
+ })
+ console.log(result)
+}
+
+async function signMessage(chainId) {
+ // current primary wallet - as multiple wallets can connect this value is the currently active
+ const [activeWallet] = onboard.state.get().wallets
+ const wagmiConfig = onboard.state.get().wagmiConfig
+ await wagmiSignMessage(wagmiConfig, {
+ message: 'This is my message to you',
+ connector: activeWallet.wagmiConnector
+ })
+}
+```
+
+## useNotifications
 
 This hook allows the dev to access all notifications if enabled, send custom notifications, and update notify <enable/disable & update transactionHandler function>
 **note** This requires an API key be added to the initialization, enabled by default if an API key exists
@@ -410,7 +467,7 @@ const sendTransactionWithPreFlightNotifications = async () => {
 </button>
 ```
 
-## `useWallets`
+## useWallets
 
 This hook allows you to track the state of all the currently connected wallets:
 
@@ -422,7 +479,7 @@ type UseWallets = (): WalletState[]
 const connectedWallets = useWallets()
 ```
 
-## `useAccountCenter`
+## useAccountCenter
 
 This hook allows you to track and update the state of the Account Center:
 
@@ -449,7 +506,7 @@ type AccountCenter = {
 const updateAccountCenter = useAccountCenter()
 ```
 
-## `useSetLocale`
+## useSetLocale
 
 This hook allows you to set the locale of your application to allow language updates associated with the i18n config:
 
@@ -725,31 +782,3 @@ export default {
  }
 }
 ```
-
-## `useWagmiConfig`
-
-This hook allows you to get the WagmiConfig (Config from the Wagmi project) from @web3-onboard/core if W3O has been initialized with the [WAGMI property imported and passing into the web3-onboard/core config](../../modules/wagmi.md#usage).
-
-```typescript
-import { sendTransaction as wagmiSendTransaction } from '@web3-onboard/wagmi'
-import { parseEther } from 'viem'
-import { useWagmiConfig, wallets } from '@web3-onboard/react'
-import type { WagmiConfig } from '@web3-onboard/core'
-
-type useWagmiConfig = (): WagmiConfig
-
-const wagmiConfig = useWagmiConfig()
-const w3OWallets = useWallets()
-
-const sendTransaction = async () => {
- // current primary wallet - as multiple wallets can connect this value is the currently active
- const [currentPrimaryWallet] = w3OWallets
- const result = await wagmiSendTransaction(wagmiConfig, {
- to: toAddress,
- // desired connector to send txn from
- account: currentPrimaryWallet.accounts[0],
- value: parseEther('0.001')
- })
- console.log(result)
-}
-```
diff --git a/docs/src/routes/docs/[...3]modules/[...8]wagmi/+page.md b/docs/src/routes/docs/[...3]modules/[...8]wagmi/+page.md
@@ -1,5 +1,5 @@
 ---
-title: wagmi
+title: WAGMI
 ---
 
 # {$frontmatter.title}
@@ -25,7 +25,21 @@ npm install @web3-onboard/wagmi
  </TabPanel>
 </Tabs>
 
-## Usage
+## WAGMI Usage
+
+To add [WAGMI API](https://wagmi.sh/core/getting-started) support to your project you can simply install `web3-onboard/wagmi` import and pass in the WAGMI package default export directly into your onboard configuration. After doing so you can use all of the native WAGMI API functions directly from `@web3-onboard/wagmi`. This will give access to all WAGMI function available on or before `@wagmi/core` version `2.10.4`.
+
+Full documentation for `wagmi/core` API functions can be found [here](https://wagmi.sh/core/getting-started).
+
+### wagmiConfig
+
+After initialization an up-to-date WAGMI config will will be available from the onboard state object `onboard.state.get().wagmiConfig` which will need to be passed as the first prop of most [@wagmi/core](https://wagmi.sh/core/getting-started) methods. 
+
+### wagmiConnector and Connectors
+Wallets will also have a `wagmiConnector` prop within the onboard state object which will allow you to target specific wallets for interactions. This can also be bi-passed if the primary or most recently connected wallet is the wallet meant for the transactions.
+The config and connectors can be used with the WAGMI API returned from this module or an external WAGMI instance.
+
+## WAGMI Example
 
 This example assumes you have already setup web3-onboard to connect wallets to your dapp.
 For more information see [web3-onboard docs](https://onboard.blocknative.com/docs/modules/core#install).
@@ -34,7 +48,6 @@ For more information see [web3-onboard docs](https://onboard.blocknative.com/doc
 import Onboard from '@web3-onboard/core'
 import injectedModule from '@web3-onboard/injected-wallets'
 import wagmi from '@web3-onboard/wagmi'
-import { parseEther } from 'viem'
 import {
  sendTransaction as wagmiSendTransaction,
  switchChain,
@@ -47,7 +60,6 @@ const injected = injectedModule()
 
 const onboard = Onboard({
  // This javascript object is unordered meaning props do not require a certain order
- // ... other Onboard options
  wagmi,
  wallets: [injected],
  chains: [
@@ -63,18 +75,32 @@ const onboard = Onboard({
 
 const sendTransaction = async () => {
  // current primary wallet - as multiple wallets can connect this value is the currently active
- const [currentPrimaryWallet] = onboard.state.get().wallets
+ const [activeWallet] = onboard.state.get().wallets
+ const { wagmiConnector } = activeWallet
  const wagmiConfig = onboard.state.get().wagmiConfig
  const result = await wagmiSendTransaction(wagmiConfig, {
  to: toAddress,
  // desired connector to send txn from
- account: currentPrimaryWallet.accounts[0],
+ connector: wagmiConnector,
  value: parseEther('0.001')
  })
  console.log(result)
 }
 
+async function signMessage(chainId) {
+ // current primary wallet - as multiple wallets can connect this value is the currently active
+ const [activeWallet] = onboard.state.get().wallets
+ const wagmiConfig = onboard.state.get().wagmiConfig
+ await wagmiSignMessage(wagmiConfig, {
+ message: 'This is my message to you',
+ connector: activeWallet.wagmiConnector
+ })
+}
+
 async function switchWagmiChain(chainId) {
+ // current primary wallet - as multiple wallets can connect this value is the currently active
+ const [activeWallet] = onboard.state.get().wallets
+ const { wagmiConnector } = activeWallet
  let chainAsNumber
  if (isHex(chainId)) {
  chainAsNumber = fromHex(chainId, 'number')
@@ -84,14 +110,16 @@ async function switchWagmiChain(chainId) {
  throw new Error('Invalid chainId')
  }
  const wagmiConfig = onboard.state.get().wagmiConfig
- await switchChain(wagmiConfig, { chainId: chainAsNumber })
+ await switchChain(wagmiConfig, {
+ chainId: chainAsNumber,
+ connector: wagmiConnector
+ })
 }
 
 async function disconnectWallet() {
  const wagmiConfig = onboard.state.get().wagmiConfig
- const disconnectThisWallet = getConnectors(wagmiConfig).find(
- (connector) => connector.name === label
- )
- disconnect(wagmiConfig, { connector: disconnectThisWallet })
+ const [activeWallet] = onboard.state.get().wallets
+ const { wagmiConnector } = activeWallet
+ disconnect(wagmiConfig, { connector: wagmiConnector })
 }
 ```