writeContract

Executes a write function on a contract, and waits for the transaction to be included in a block. Returns the transaction receipt.

A "write" function on a Solidity contract modifies the state of the blockchain. These types of functions require gas to be executed, and hence a Transaction is needed to be broadcast in order to change the state.

Internally, writeContract uses a Wallet Client to call the sendTransaction action with ABI-encoded data.

Usage

Below is a very basic example of how to execute a write function on a contract (with no arguments).

While you can use writeContract by itself, it is highly recommended to pair it with simulateContract to validate that the contract write will execute without errors.

example.ts

import { account, publicClient, walletClient } from './config'
import { wagmiAbi } from './abi'
 
const { request } = await publicClient.simulateContract({
  account,
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
})
const receipt = await walletClient.writeContractSync(request)

Passing Arguments

If your function requires argument(s), you can pass them through with the args attribute.

TypeScript types for args will be inferred from the function name & ABI, to guard you from inserting the wrong values.

For example, the mint function name below requires a tokenId argument, and it is typed as [number].

example.ts

import { account, walletClient } from './client'
import { wagmiAbi } from './abi'
 
const { request } = await publicClient.simulateContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  account
})
const receipt = await walletClient.writeContractSync(request)

Standalone

If you don't need to perform validation on the contract write, you can also use it by itself:

example.ts

import { account, walletClient } from './config'
import { wagmiAbi } from './abi'
 
const receipt = await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  account,
})

Return Value

TransactionReceipt

A Transaction receipt.

Parameters

address

Type: Address

The contract address.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420]
})

abi

Type: Abi

The contract's ABI.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi, 
  functionName: 'mint',
  args: [69420]
})

functionName

Type: string

A function to extract from the ABI.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint', 
  args: [69420]
})

account

Type: Account | Address | null

The Account to write to the contract from.

Accepts a JSON-RPC Account (or Address) or Local Account (Private Key, etc). If set to null, it is assumed that the transport will handle the filling the sender of the transaction.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
})

accessList (optional)

Type: AccessList

The access list.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  accessList: [{ 
    address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
    storageKeys: ['0x1'],
  }],
})

authorizationList (optional)

Type: AuthorizationList

Signed EIP-7702 Authorization list.

const authorization = await walletClient.signAuthorization({ 
  contractAddress: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
}) 
 
await walletClient.writeContractSync({
  address: account.address,
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  authorizationList: [authorization], 
})

args (optional)

Type: Inferred from ABI.

Arguments to pass to function call.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420] 
})

chain (optional)

Type: 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.

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).

import { optimism } from 'viem/chains'
 
await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  chain: optimism, 
})

dataSuffix

Type: Hex

Data to append to the end of the calldata. Useful for adding a "domain" tag.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  dataSuffix: '0xdeadbeef'
})

gas (optional)

Type: bigint

The gas limit for the transaction. Note that passing a gas limit also skips the gas estimation step.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  gas: 69420n, 
})

gasPrice (optional)

Type: bigint

The price (in wei) to pay per gas. Only applies to Legacy Transactions.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  gasPrice: parseGwei('20'), 
})

maxFeePerGas (optional)

Type: bigint

Total fee per gas (in wei), inclusive of maxPriorityFeePerGas. Only applies to EIP-1559 Transactions

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  maxFeePerGas: parseGwei('20'),  
})

maxPriorityFeePerGas (optional)

Type: bigint

Max priority fee per gas (in wei). Only applies to EIP-1559 Transactions

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  maxFeePerGas: parseGwei('20'),
  maxPriorityFeePerGas: parseGwei('2'), 
})

nonce (optional)

Type: number

Unique number identifying this transaction.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  nonce: 69
})

pollingInterval (optional)

Type: number
Default: walletClient.pollingInterval

The polling interval to poll for the transaction receipt.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  pollingInterval: 1_000
})

timeout (optional)

Type: number
Default: chain.blockTime * 3

The timeout to wait for the transaction receipt.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  timeout: 20_000
})

value (optional)

Type: number

Value in wei sent with this transaction.

await walletClient.writeContractSync({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'mint',
  args: [69420],
  value: parseEther('1') 
})