feat: useWatchAsset hook (#4128)

* feat: `useWatchAsset` hook

* test: add tests

* docs: add docs

* nit: use `getConnectorClient`

* fix: types

* test: fix

* test: fix

* test: fix

* chore: tweaks

* chore: changeset

---------

Co-authored-by: Tom Meagher <tom@meagher.co>

.changeset/modern-dots-sniff.md

@@ -0,0 +1,5 @@
+---
+"@wagmi/core": minor
+---
+
+Added `watchAsset` action.

.changeset/stupid-beds-mate.md

@@ -0,0 +1,5 @@
+---
+"wagmi": minor
+---
+
+Added `useWatchAsset` hook.

packages/core/src/actions/watchAsset.test.ts

@@ -0,0 +1,23 @@
+import { config } from '@wagmi/test'
+import { expect, test } from 'vitest'
+
+import { connect } from './connect.js'
+import { disconnect } from './disconnect.js'
+import { watchAsset } from './watchAsset.js'
+
+const connector = config.connectors[0]!
+
+test('default', async () => {
+  await connect(config, { connector })
+  await expect(
+    watchAsset(config, {
+      type: 'ERC20',
+      options: {
+        address: '0x0000000000000000000000000000000000000000',
+        symbol: 'NULL',
+        decimals: 18,
+      },
+    }),
+  ).resolves.toMatchInlineSnapshot('true')
+  await disconnect(config, { connector })
+})

packages/core/src/actions/watchAsset.ts

@@ -0,0 +1,44 @@
+import {
+  type WatchAssetErrorType as viem_WatchAssetErrorType,
+  type WatchAssetParameters as viem_WatchAssetParameters,
+  type WatchAssetReturnType as viem_WatchAssetReturnType,
+  watchAsset as viem_watchAsset,
+} from 'viem/actions'
+
+import type { Config } from '../createConfig.js'
+import type { BaseErrorType, ErrorType } from '../errors/base.js'
+import type { ConnectorParameter } from '../types/properties.js'
+import type { Compute } from '../types/utils.js'
+import { getAction } from '../utils/getAction.js'
+import {
+  type GetConnectorClientErrorType,
+  getConnectorClient,
+} from './getConnectorClient.js'
+
+export type WatchAssetParameters = Compute<
+  viem_WatchAssetParameters & ConnectorParameter
+>
+
+export type WatchAssetReturnType = viem_WatchAssetReturnType
+
+export type WatchAssetErrorType =
+  // getConnectorClient()
+  | GetConnectorClientErrorType
+  // base
+  | BaseErrorType
+  | ErrorType
+  // viem
+  | viem_WatchAssetErrorType
+
+/** https://wagmi.sh/core/api/actions/watchAsset */
+export async function watchAsset(
+  config: Config,
+  parameters: WatchAssetParameters,
+): Promise<WatchAssetReturnType> {
+  const { connector, ...rest } = parameters
+
+  const client = await getConnectorClient(config, { connector })
+
+  const action = getAction(client, viem_watchAsset, 'watchAsset')
+  return action(rest as viem_WatchAssetParameters)
+}

packages/core/src/connectors/mock.ts

@@ -32,6 +32,7 @@ export type MockParameters = {
         signMessageError?: boolean | Error | undefined
         signTypedDataError?: boolean | Error | undefined
         reconnect?: boolean | undefined
+        watchAssetError?: boolean | Error | undefined
       }
     | undefined
 }
@@ -158,6 +159,17 @@ export function mock(parameters: MockParameters) {
           return
         }
 
+        if (method === 'wallet_watchAsset') {
+          if (features.watchAssetError) {
+            if (typeof features.watchAssetError === 'boolean')
+              throw new UserRejectedRequestError(
+                new Error('Failed to switch chain.'),
+              )
+            throw features.watchAssetError
+          }
+          return connected
+        }
+
         if (method === 'wallet_getCapabilities')
           return {
             '0x2105': {

packages/core/src/exports/actions.test.ts

@@ -63,6 +63,7 @@ test('exports', () => {
       "verifyMessage",
       "verifyTypedData",
       "watchAccount",
+      "watchAsset",
       "watchBlocks",
       "watchBlockNumber",
       "watchChainId",

packages/core/src/exports/actions.ts

@@ -348,6 +348,12 @@ export {
   watchAccount,
 } from '../actions/watchAccount.js'
 
+export {
+  type WatchAssetParameters,
+  type WatchAssetReturnType,
+  watchAsset,
+} from '../actions/watchAsset.js'
+
 export {
   type WatchBlocksParameters,
   type WatchBlocksReturnType,

packages/core/src/exports/index.test.ts

@@ -63,6 +63,7 @@ test('exports', () => {
       "verifyMessage",
       "verifyTypedData",
       "watchAccount",
+      "watchAsset",
       "watchBlocks",
       "watchBlockNumber",
       "watchChainId",

packages/core/src/exports/index.ts

@@ -350,6 +350,13 @@ export {
   watchAccount,
 } from '../actions/watchAccount.js'
 
+export {
+  type WatchAssetParameters,
+  type WatchAssetErrorType,
+  type WatchAssetReturnType,
+  watchAsset,
+} from '../actions/watchAsset.js'
+
 export {
   type WatchBlocksParameters,
   type WatchBlocksReturnType,

packages/core/src/exports/query.test.ts

@@ -80,6 +80,7 @@ test('exports', () => {
       "verifyTypedDataQueryOptions",
       "waitForTransactionReceiptQueryKey",
       "waitForTransactionReceiptQueryOptions",
+      "watchAssetMutationOptions",
       "writeContractMutationOptions",
       "hashFn",
       "structuralSharing",

packages/core/src/exports/query.ts

@@ -372,6 +372,14 @@ export {
   waitForTransactionReceiptQueryOptions,
 } from '../query/waitForTransactionReceipt.js'
 
+export {
+  type WatchAssetData,
+  type WatchAssetVariables,
+  type WatchAssetMutate,
+  type WatchAssetMutateAsync,
+  watchAssetMutationOptions,
+} from '../query/watchAsset.js'
+
 export {
   type WriteContractData,
   type WriteContractVariables,

packages/core/src/query/watchAsset.test.ts

@@ -0,0 +1,15 @@
+import { config } from '@wagmi/test'
+import { expect, test } from 'vitest'
+
+import { watchAssetMutationOptions } from './watchAsset.js'
+
+test('default', () => {
+  expect(watchAssetMutationOptions(config)).toMatchInlineSnapshot(`
+    {
+      "mutationFn": [Function],
+      "mutationKey": [
+        "watchAsset",
+      ],
+    }
+  `)
+})

packages/core/src/query/watchAsset.ts

@@ -0,0 +1,42 @@
+import type { MutationOptions } from '@tanstack/query-core'
+
+import {
+  type WatchAssetErrorType,
+  type WatchAssetParameters,
+  type WatchAssetReturnType,
+  watchAsset,
+} from '../actions/watchAsset.js'
+import type { Config } from '../createConfig.js'
+import type { Compute } from '../types/utils.js'
+import type { Mutate, MutateAsync } from './types.js'
+
+export function watchAssetMutationOptions(config: Config) {
+  return {
+    mutationFn(variables) {
+      return watchAsset(config, variables)
+    },
+    mutationKey: ['watchAsset'],
+  } as const satisfies MutationOptions<
+    WatchAssetData,
+    WatchAssetErrorType,
+    WatchAssetVariables
+  >
+}
+
+export type WatchAssetData = WatchAssetReturnType
+
+export type WatchAssetVariables = Compute<WatchAssetParameters>
+
+export type WatchAssetMutate<context = unknown> = Mutate<
+  WatchAssetData,
+  WatchAssetErrorType,
+  WatchAssetVariables,
+  context
+>
+
+export type WatchAssetMutateAsync<context = unknown> = MutateAsync<
+  WatchAssetData,
+  WatchAssetErrorType,
+  WatchAssetVariables,
+  context
+>

packages/react/src/exports/actions.test.ts

@@ -63,6 +63,7 @@ test('exports', () => {
       "verifyMessage",
       "verifyTypedData",
       "watchAccount",
+      "watchAsset",
       "watchBlocks",
       "watchBlockNumber",
       "watchChainId",

packages/react/src/exports/index.test.ts

@@ -66,6 +66,7 @@ test('exports', () => {
       "useVerifyTypedData",
       "useWalletClient",
       "useWaitForTransactionReceipt",
+      "useWatchAsset",
       "useWatchBlocks",
       "useWatchBlockNumber",
       "useWatchContractEvent",

packages/react/src/exports/index.ts

@@ -342,6 +342,12 @@ export {
   useWaitForTransactionReceipt,
 } from '../hooks/useWaitForTransactionReceipt.js'
 
+export {
+  type UseWatchAssetParameters,
+  type UseWatchAssetReturnType,
+  useWatchAsset,
+} from '../hooks/useWatchAsset.js'
+
 export {
   type UseWatchBlocksParameters,
   type UseWatchBlocksReturnType,

packages/react/src/exports/query.test.ts

@@ -80,6 +80,7 @@ test('exports', () => {
       "verifyTypedDataQueryOptions",
       "waitForTransactionReceiptQueryKey",
       "waitForTransactionReceiptQueryOptions",
+      "watchAssetMutationOptions",
       "writeContractMutationOptions",
       "hashFn",
       "structuralSharing",

packages/react/src/hooks/useWatchAsset.test-d.ts

@@ -0,0 +1,66 @@
+import type { WatchAssetErrorType } from '@wagmi/core'
+import type { WatchAssetVariables } from '@wagmi/core/query'
+import { expectTypeOf, test } from 'vitest'
+
+import { useWatchAsset } from './useWatchAsset.js'
+
+const tokenInfo = {
+  address: '0x0000000000000000000000000000000000000000',
+  symbol: 'NULL',
+  decimals: 18,
+}
+const contextValue = { foo: 'bar' } as const
+
+test('context', () => {
+  const { context, data, error, watchAsset, variables } = useWatchAsset({
+    mutation: {
+      onMutate(variables) {
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        return contextValue
+      },
+      onError(error, variables, context) {
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(error).toEqualTypeOf<WatchAssetErrorType>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue | undefined>()
+      },
+      onSuccess(data, variables, context) {
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(data).toEqualTypeOf<boolean>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue>()
+      },
+      onSettled(data, error, variables, context) {
+        expectTypeOf(data).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(error).toEqualTypeOf<WatchAssetErrorType | null>()
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue | undefined>()
+      },
+    },
+  })
+
+  expectTypeOf(data).toEqualTypeOf<boolean | undefined>()
+  expectTypeOf(error).toEqualTypeOf<WatchAssetErrorType | null>()
+  expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables | undefined>()
+  expectTypeOf(context).toEqualTypeOf<typeof contextValue | undefined>()
+
+  watchAsset(
+    { type: 'ERC20', options: tokenInfo },
+    {
+      onError(error, variables, context) {
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(error).toEqualTypeOf<WatchAssetErrorType>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue | undefined>()
+      },
+      onSuccess(data, variables, context) {
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(data).toEqualTypeOf<boolean>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue>()
+      },
+      onSettled(data, error, variables, context) {
+        expectTypeOf(data).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(error).toEqualTypeOf<WatchAssetErrorType | null>()
+        expectTypeOf(variables).toEqualTypeOf<WatchAssetVariables>()
+        expectTypeOf(context).toEqualTypeOf<typeof contextValue | undefined>()
+      },
+    },
+  )
+})

packages/react/src/hooks/useWatchAsset.test.ts

@@ -0,0 +1,27 @@
+import { connect, disconnect } from '@wagmi/core'
+import { config } from '@wagmi/test'
+import { renderHook, waitFor } from '@wagmi/test/react'
+import { expect, test } from 'vitest'
+
+import { useWatchAsset } from './useWatchAsset.js'
+
+const connector = config.connectors[0]!
+
+const tokenInfo = {
+  address: '0x0000000000000000000000000000000000000000',
+  symbol: 'NULL',
+  decimals: 18,
+}
+
+test('default', async () => {
+  await connect(config, { connector })
+
+  const { result } = renderHook(() => useWatchAsset())
+
+  result.current.watchAsset({ type: 'ERC20', options: tokenInfo })
+  await waitFor(() => expect(result.current.isSuccess).toBeTruthy())
+
+  expect(result.current.data).toEqual(true)
+
+  await disconnect(config, { connector })
+})