feat: addChain

.changeset/fast-cooks-provide.md

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

.changeset/thin-rings-carry.md

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

packages/core/src/actions/addChain.test-d.ts

@@ -0,0 +1,10 @@
+import { config } from '@wagmi/test'
+import { avalanche } from 'viem/chains'
+import { expectTypeOf, test } from 'vitest'
+
+import { addChain } from './addChain.js'
+
+test('return type', async () => {
+  const result = await addChain(config, { chain: avalanche })
+  expectTypeOf(result).toEqualTypeOf<void>()
+})

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

@@ -0,0 +1,70 @@
+import { accounts, config } from '@wagmi/test'
+import { avalanche } from 'viem/chains'
+import { expect, test, vi } from 'vitest'
+
+import { mock } from '../connectors/mock.js'
+import { addChain } from './addChain.js'
+import { connect } from './connect.js'
+import { disconnect } from './disconnect.js'
+
+const connector = config.connectors[0]!
+
+test('default', async () => {
+  await connect(config, { connector })
+  try {
+    await expect(
+      addChain(config, { chain: avalanche }),
+    ).resolves.toBeUndefined()
+  } finally {
+    await disconnect(config, { connector })
+  }
+})
+
+test('parameters: connector and chain', async () => {
+  const connector_ = config._internal.connectors.setup(mock({ accounts }))
+  const provider = await connector_.getProvider()
+  const request = vi.spyOn(provider, 'request')
+  vi.spyOn(connector_, 'getProvider').mockResolvedValue(provider)
+  await connect(config, { connector: connector_ })
+  request.mockClear()
+
+  try {
+    await addChain(config, {
+      chain: { ...avalanche, blockExplorers: undefined },
+      connector: connector_,
+    })
+    expect(request).toHaveBeenCalledWith(
+      {
+        method: 'wallet_addEthereumChain',
+        params: [
+          expect.objectContaining({
+            blockExplorerUrls: undefined,
+            chainId: '0xa86a',
+            chainName: 'Avalanche',
+          }),
+        ],
+      },
+      undefined,
+    )
+  } finally {
+    await disconnect(config, { connector: connector_ })
+  }
+})
+
+test('behavior: connector error', async () => {
+  const error = new Error('Failed to add chain.')
+  const connector_ = config._internal.connectors.setup(
+    mock({ accounts, features: { addChainError: error } }),
+  )
+  await connect(config, { connector: connector_ })
+  try {
+    await expect(
+      addChain(config, { chain: avalanche, connector: connector_ }),
+    ).rejects.toMatchObject({
+      details: error.message,
+      name: 'UnknownRpcError',
+    })
+  } finally {
+    await disconnect(config, { connector: connector_ })
+  }
+})

packages/core/src/actions/addChain.ts

@@ -0,0 +1,43 @@
+import {
+  type AddChainErrorType as viem_AddChainErrorType,
+  type AddChainParameters as viem_AddChainParameters,
+  addChain as viem_addChain,
+} 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 AddChainParameters = Compute<
+  viem_AddChainParameters & ConnectorParameter
+>
+
+export type AddChainReturnType = void
+
+export type AddChainErrorType =
+  // getConnectorClient()
+  | GetConnectorClientErrorType
+  // base
+  | BaseErrorType
+  | ErrorType
+  // viem
+  | viem_AddChainErrorType
+
+/** https://wagmi.sh/core/api/actions/addChain */
+export async function addChain(
+  config: Config,
+  parameters: AddChainParameters,
+): Promise<AddChainReturnType> {
+  const { connector, ...rest } = parameters
+
+  const client = await getConnectorClient(config, { connector })
+
+  const action = getAction(client, viem_addChain, 'addChain')
+  return action(rest)
+}

packages/core/src/connectors/mock.test.ts

@@ -72,6 +72,7 @@ test('behavior: connector.getProvider request errors', async () => {
   const connectorFn = mock({
     accounts,
     features: {
+      addChainError: true,
       signMessageError: true,
       signTypedDataError: true,
       switchChainError: true,
@@ -83,6 +84,18 @@ test('behavior: connector.getProvider request errors', async () => {
   ) as ReturnType<typeof connectorFn>
   const provider = await connector.getProvider()
 
+  await expect(
+    provider.request({
+      method: 'wallet_addEthereumChain',
+      params: [] as any,
+    }),
+  ).rejects.toThrowErrorMatchingInlineSnapshot(`
+    [UserRejectedRequestError: User rejected the request.
+
+    Details: Failed to add chain.
+    Version: viem@2.55.7]
+  `)
+
   await expect(
     provider.request({
       method: 'eth_signTypedData_v4',

packages/core/src/connectors/mock.ts

@@ -30,6 +30,7 @@
     | {
         defaultConnected?: boolean | undefined
         connectError?: boolean | Error | undefined
+        addChainError?: boolean | Error | undefined
         switchChainError?: boolean | Error | undefined
         signMessageError?: boolean | Error | undefined
         signTypedDataError?: boolean | Error | undefined
@@ -176,6 +177,17 @@
           }
 
         // wallet methods
+        if (method === 'wallet_addEthereumChain') {
+          if (features.addChainError) {
+            if (typeof features.addChainError === 'boolean')
+              throw new UserRejectedRequestError(
+                new Error('Failed to add chain.'),
+              )
+            throw features.addChainError
+          }
+          return
+        }
+
         if (method === 'wallet_switchEthereumChain') {
           if (features.switchChainError) {
             if (typeof features.switchChainError === 'boolean')

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

@@ -5,6 +5,7 @@ import * as actions from './actions.js'
 test('exports', () => {
   expect(Object.keys(actions)).toMatchInlineSnapshot(`
     [
+      "addChain",
       "call",
       "connect",
       "deployContract",

packages/core/src/exports/actions.ts

@@ -3,6 +3,13 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 // biome-ignore lint/performance/noBarrelFile: entrypoint module
+export {
+  type AddChainErrorType,
+  type AddChainParameters,
+  type AddChainReturnType,
+  addChain,
+} from '../actions/addChain.js'
+
 export {
   type CallErrorType,
   type CallParameters,

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

@@ -5,6 +5,7 @@ import * as core from './index.js'
 test('exports', () => {
   expect(Object.keys(core)).toMatchInlineSnapshot(`
     [
+      "addChain",
       "call",
       "connect",
       "deployContract",

packages/core/src/exports/index.ts

@@ -3,6 +3,13 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 // biome-ignore lint/performance/noBarrelFile: entrypoint module
+export {
+  type AddChainErrorType,
+  type AddChainParameters,
+  type AddChainReturnType,
+  addChain,
+} from '../actions/addChain.js'
+
 export {
   type CallErrorType,
   type CallParameters,

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

@@ -5,6 +5,7 @@ import * as query from './query.js'
 test('exports', () => {
   expect(Object.keys(query)).toMatchInlineSnapshot(`
     [
+      "addChainMutationOptions",
       "callQueryKey",
       "callQueryOptions",
       "connectMutationOptions",

packages/core/src/exports/query.ts

@@ -3,6 +3,16 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 // biome-ignore lint/performance/noBarrelFile: entrypoint module
+export {
+  type AddChainData,
+  type AddChainMutate,
+  type AddChainMutateAsync,
+  type AddChainMutationOptions,
+  type AddChainOptions,
+  type AddChainVariables,
+  addChainMutationOptions,
+} from '../query/addChain.js'
+
 export {
   type CallData,
   type CallOptions,

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

@@ -0,0 +1,32 @@
+import { config } from '@wagmi/test'
+import { avalanche } from 'viem/chains'
+import { expect, test } from 'vitest'
+
+import { connect } from '../actions/connect.js'
+import { disconnect } from '../actions/disconnect.js'
+import { addChainMutationOptions } from './addChain.js'
+
+const connector = config.connectors[0]!
+
+test('default', () => {
+  expect(addChainMutationOptions(config)).toMatchInlineSnapshot(`
+    {
+      "mutationFn": [Function],
+      "mutationKey": [
+        "addChain",
+      ],
+    }
+  `)
+})
+
+test('mutationFn', async () => {
+  await connect(config, { connector })
+  try {
+    const options = addChainMutationOptions(config)
+    await expect(
+      options.mutationFn?.({ chain: avalanche, connector }),
+    ).resolves.toBeUndefined()
+  } finally {
+    await disconnect(config, { connector })
+  }
+})

packages/core/src/query/addChain.ts

@@ -0,0 +1,56 @@
+import type { MutationOptions } from '@tanstack/query-core'
+
+import {
+  type AddChainErrorType,
+  type AddChainParameters,
+  type AddChainReturnType,
+  addChain,
+} from '../actions/addChain.js'
+import type { Config } from '../createConfig.js'
+import type { MutationParameter } from '../types/query.js'
+import type { Compute } from '../types/utils.js'
+import type { Mutate, MutateAsync } from './types.js'
+
+export type AddChainOptions<context = unknown> = MutationParameter<
+  AddChainData,
+  AddChainErrorType,
+  AddChainVariables,
+  context
+>
+
+export function addChainMutationOptions<context>(
+  config: Config,
+  options: AddChainOptions<context> = {},
+): AddChainMutationOptions {
+  return {
+    ...(options.mutation as any),
+    mutationFn(variables) {
+      return addChain(config, variables)
+    },
+    mutationKey: ['addChain'],
+  }
+}
+
+export type AddChainMutationOptions = MutationOptions<
+  AddChainData,
+  AddChainErrorType,
+  AddChainVariables
+>
+
+export type AddChainData = AddChainReturnType
+
+export type AddChainVariables = Compute<AddChainParameters>
+
+export type AddChainMutate<context = unknown> = Mutate<
+  AddChainData,
+  AddChainErrorType,
+  AddChainVariables,
+  context
+>
+
+export type AddChainMutateAsync<context = unknown> = MutateAsync<
+  AddChainData,
+  AddChainErrorType,
+  AddChainVariables,
+  context
+>

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

@@ -5,6 +5,7 @@ import * as actions from './actions.js'
 test('exports', () => {
   expect(Object.keys(actions)).toMatchInlineSnapshot(`
     [
+      "addChain",
       "call",
       "connect",
       "deployContract",

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

@@ -36,6 +36,7 @@ test('exports', () => {
       "unstable_connector",
       "useAccount",
       "useAccountEffect",
+      "useAddChain",
       "useBalance",
       "useBlobBaseFee",
       "useBlock",

packages/react/src/exports/index.ts

@@ -24,6 +24,12 @@ export {
 // Hooks
 ////////////////////////////////////////////////////////////////////////////////
 
+export {
+  type UseAddChainParameters,
+  type UseAddChainReturnType,
+  useAddChain,
+} from '../hooks/useAddChain.js'
+
 export {
   type UseBalanceParameters,
   type UseBalanceReturnType,

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

@@ -5,6 +5,7 @@ import * as query from './query.js'
 test('exports', () => {
   expect(Object.keys(query)).toMatchInlineSnapshot(`
     [
+      "addChainMutationOptions",
       "callQueryKey",
       "callQueryOptions",
       "connectMutationOptions",