feat: assert that client chain matches wallet's active chain

.changeset/sixty-ties-pump.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added an assertion in `sendTransaction` & `writeContract` to check that the client chain matches the wallet's current chain.

site/docs/actions/wallet/sendTransaction.md

@@ -124,6 +124,7 @@ const hash = await walletClient.sendTransaction({
 ### chain (optional)
 
 - **Type:** [`Chain`](/docs/glossary/types#chain)
+- **Default:** `walletClient.chain`
 
 The target chain. If there is a mismatch between the wallet's current chain & the target chain, an error will be thrown if `assertChain` is truthy.
 

site/docs/clients/wallet.md

@@ -167,6 +167,21 @@ const hash = await client.sendTransaction({ // [!code focus:5]
 
 ## Parameters
 
+### chain (optional)
+
+- **Type:** [Chain](/docs/glossary/types#chain)
+
+The [Chain](/docs/clients/chains) of the Wallet Client. 
+
+Used in the [`sendTransaction`](/docs/actions/wallet/sendTransaction) & [`writeContract`](/docs/contract/writeContract) Actions to assert that the chain matches the wallet's active chain.
+
+```ts
+const client = createWalletClient({
+  chain: mainnet, // [!code focus]
+  transport: custom(window.ethereum)
+})
+```
+
 ### key (optional)
 
 - **Type:** `string`

site/docs/contract/writeContract.md

@@ -270,6 +270,49 @@ await walletClient.writeContract({
 })
 ```
 
+### assertChain (optional)
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Throws an error if `chain` does not match the current wallet chain.
+
+Defaults to `true`, but you can turn this off if your dapp is primarily multi-chain.
+
+```ts
+import { optimism } from 'viem/chains' // [!code focus]
+
+await walletClient.writeContract({
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'mint',
+  args: [69420],
+  assertChain: false, // [!code focus]
+  chain: optimism, // [!code focus]
+})
+```
+
+### chain (optional)
+
+- **Type:** [`Chain`](/docs/glossary/types#chain)
+- **Default:** `walletClient.chain`
+
+The target chain. If there is a mismatch between the wallet's current chain & the target chain, an error will be thrown if `assertChain` is truthy.
+
+The chain is also used to infer its request type (e.g. the Celo chain has a `gatewayFee` that you can pass through to `sendTransaction`).
+
+```ts
+import { optimism } from 'viem/chains' // [!code focus]
+
+await walletClient.writeContract({
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'mint',
+  args: [69420],
+  chain: optimism, // [!code focus]
+})
+```
+
 ### gasPrice (optional)
 
 - **Type:** `bigint`

src/actions/wallet/sendTransaction.test.ts

@@ -1,13 +1,20 @@
 import { describe, expect, test } from 'vitest'
 
-import { accounts, publicClient, testClient, walletClient } from '../../_test'
+import {
+  accounts,
+  localHttpUrl,
+  publicClient,
+  testClient,
+  walletClient,
+} from '../../_test'
 import { celo, defineChain, localhost, mainnet, optimism } from '../../chains'
 import { getAccount, hexToNumber, parseEther, parseGwei } from '../../utils'
 import { getBalance, getBlock, getTransaction } from '..'
 import { mine, setBalance, setNextBlockBaseFeePerGas } from '../test'
 
 import { sendTransaction } from './sendTransaction'
 import { anvilChain, getLocalAccount } from '../../_test/utils'
+import { createWalletClient, http } from '../../clients'
 
 const sourceAccount = accounts[0]
 const targetAccount = accounts[1]
@@ -120,6 +127,32 @@ test.skip('sends transaction w/ no value', async () => {
   ).toBeLessThan(sourceAccount.balance)
 })
 
+test('client chain mismatch', async () => {
+  const walletClient = createWalletClient({
+    chain: optimism,
+    transport: http(localHttpUrl),
+  })
+  await expect(() =>
+    sendTransaction(walletClient, {
+      account: getAccount(sourceAccount.address),
+      to: targetAccount.address,
+      value: parseEther('1'),
+    }),
+  ).rejects.toThrowErrorMatchingInlineSnapshot(`
+    "The current chain of the wallet (id: 1) does not match the target chain for the transaction (id: 10 – Optimism).
+
+    Current Chain ID:  1
+    Expected Chain ID: 10 – Optimism
+
+    Request Arguments:
+      from:   0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
+      to:     0x70997970c51812dc3a010c7d01b50e0d17dc79c8
+      value:  1 ETH
+
+    Version: [email protected]"
+  `)
+})
+
 describe('args: gas', () => {
   test('sends transaction', async () => {
     await setup()
@@ -416,6 +449,21 @@ describe('args: chain', async () => {
     ).toBeDefined
   })
 
+  test('args: assertChain', async () => {
+    const walletClient = createWalletClient({
+      chain: optimism,
+      transport: http(localHttpUrl),
+    })
+    expect(
+      await sendTransaction(walletClient, {
+        assertChain: false,
+        account: getAccount(sourceAccount.address),
+        to: targetAccount.address,
+        value: parseEther('1'),
+      }),
+    ).toBeDefined
+  })
+
   test('chain mismatch', async () => {
     await expect(() =>
       sendTransaction(walletClient, {
@@ -425,7 +473,7 @@ describe('args: chain', async () => {
         value: parseEther('1'),
       }),
     ).rejects.toThrowErrorMatchingInlineSnapshot(`
-      "The current chain (id: 1) does not match the chain passed to the request (id: 10 – Optimism).
+      "The current chain of the wallet (id: 1) does not match the target chain for the transaction (id: 10 – Optimism).
 
       Current Chain ID:  1
       Expected Chain ID: 10 – Optimism

src/actions/wallet/sendTransaction.ts

@@ -44,12 +44,12 @@ export type SendTransactionParameters<TChain extends Chain = Chain> =
 export type SendTransactionReturnType = Hash
 
 export async function sendTransaction<TChain extends Chain>(
-  client: WalletClient,
+  client: WalletClient<any, any>,
   args: SendTransactionParameters<TChain>,
 ): Promise<SendTransactionReturnType> {
   const {
     account,
-    chain,
+    chain = client.chain,
     accessList,
     assertChain = true,
     data,
@@ -62,6 +62,7 @@ export async function sendTransaction<TChain extends Chain>(
     value,
     ...rest
   } = args
+
   try {
     assertRequest(args)
 

src/clients/createWalletClient.test.ts

@@ -150,7 +150,28 @@ describe('transports', () => {
     expect(client).toMatchInlineSnapshot(`
       {
         "addChain": [Function],
-        "chain": undefined,
+        "chain": {
+          "id": 1337,
+          "name": "Localhost",
+          "nativeCurrency": {
+            "decimals": 18,
+            "name": "Ether",
+            "symbol": "ETH",
+          },
+          "network": "localhost",
+          "rpcUrls": {
+            "default": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+            "public": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+          },
+        },
         "deployContract": [Function],
         "getAddresses": [Function],
         "getChainId": [Function],

src/clients/createWalletClient.ts

@@ -32,6 +32,7 @@ export function createWalletClient<
   TTransport extends Transport,
   TChain extends Chain,
 >({
+  chain,
   transport,
   key = 'wallet',
   name = 'Wallet Client',
@@ -42,6 +43,7 @@ export function createWalletClient<
   true
 > {
   const client = createClient({
+    chain,
     key,
     name,
     pollingInterval,

src/errors/chain.ts

@@ -40,7 +40,7 @@ export class ChainMismatchError extends BaseError {
     currentChainId,
   }: { chain: Chain; currentChainId: number }) {
     super(
-      `The current chain (id: ${currentChainId}) does not match the chain passed to the request (id: ${chain.id} – ${chain.name}).`,
+      `The current chain of the wallet (id: ${currentChainId}) does not match the target chain for the transaction (id: ${chain.id} – ${chain.name}).`,
       {
         metaMessages: [
           `Current Chain ID:  ${currentChainId}`,