feat: writeContract

.changeset/honest-dots-impress.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added `writeContract`.

.changeset/hungry-countries-repeat.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+**Breaking**: Replaced `callContract` with `simulateContract`.

site/.vitepress/sidebar.ts

@@ -392,10 +392,6 @@ export const sidebar: DefaultTheme.Sidebar = {
         {
           text: 'Actions',
           items: [
-            {
-              text: 'callContract',
-              link: '/docs/contract/callContract',
-            },
             {
               text: 'deployContract',
               link: '/docs/contract/deployContract',
@@ -417,7 +413,11 @@ export const sidebar: DefaultTheme.Sidebar = {
               link: '/docs/contract/readContract',
             },
             {
-              text: 'writeContract 🚧',
+              text: 'simulateContract',
+              link: '/docs/contract/simulateContract',
+            },
+            {
+              text: 'writeContract',
               link: '/docs/contract/writeContract',
             },
             {

site/docs/contract/multicall.md

@@ -1,6 +1,6 @@
 # multicall
 
-Similar to [`callContract`](/docs/contract/callContract), but batches up & calls multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall). 
+Similar to [`readContract`](/docs/contract/readContract), but batches up & calls multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall). 
 
 ## Import
 

site/docs/contract/callContract.md → site/docs/contract/simulateContract.md

@@ -1,39 +1,35 @@
-# callContract
+# simulateContract
 
-The `callContract` function allows for the execution of a **read** or **write** function on a contract, and returns the response.
+The `simulateContract` function **simulates**/**validates** a contract interaction. This is useful for retrieving **return data** and **revert reasons** of contract write functions.
 
-It is similar to [`readContract`](/docs/contract/readContract), in that it does not require gas to execute and _**does not**_ change the state of the blockchain, but also supports **contract write** functions. 
+This function does not require gas to execute and _**does not**_ change the state of the blockchain. It is almost identical to [`readContract`](/docs/contracts/readContract), but also supports contract write functions.
 
-It is useful for:
-
-- **simulating** or **validating** a contract interaction.
-- retrieving **return data** (and **revert reasons**) of write functions (via `writeContract`).
-
-Internally, `callContract` uses a [Public Client](/docs/clients/public) to call the [`call` action](/docs/actions/public/call) with [ABI-encoded `data`](/docs/contract/encodeFunctionData).
+Internally, `simulateContract` uses a [Public Client](/docs/clients/public) to call the [`call` action](/docs/actions/public/call) with [ABI-encoded `data`](/docs/contract/encodeFunctionData).
 
 ## Import
 
 ```ts
-import { callContract } from 'viem'
+import { simulateContract } from 'viem'
 ```
 
 ## Usage
 
-Below is a very basic example of how to call a write function on a contract (with no arguments).
+Below is a very basic example of how to simulate a write function on a contract (with no arguments).
 
 The `mint` function accepts no arguments, and returns a token ID.
 
 ::: code-group
 
 ```ts [example.ts]
-import { callContract } from 'viem'
+import { simulateContract } from 'viem'
 import { publicClient } from './client'
 import { wagmiAbi } from './abi'
 
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 // 69420
 ```
@@ -75,15 +71,16 @@ For example, the `mint` function name below requires a **tokenId** argument, and
 ::: code-group
 
 ```ts {9} [example.ts]
-import { callContract } from 'viem'
+import { simulateContract } from 'viem'
 import { publicClient } from './client'
 import { wagmiAbi } from './abi'
 
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
-  args: [69420]
+  args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 // 69420
 ```
@@ -114,6 +111,54 @@ export const publicClient = createPublicClient({
 
 :::
 
+### Pairing with `writeContract`
+
+The `simulateContract` function also pairs well with `writeContract`.
+
+In the example below, we are **validating** if the contract write will be successful via `simulateContract`. If no errors are thrown, then we are all good. After that, we perform a contract write to execute the transaction.
+
+::: code-group
+
+```ts [example.ts]
+import { simulateContract } from 'viem'
+import { walletClient, publicClient } from './client'
+import { wagmiAbi } from './abi'
+
+const { request } = await simulateContract(publicClient, {
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+})
+const hash = await writeContract(walletClient, request)
+```
+
+```ts [abi.ts]
+export const wagmiAbi = [
+  ...
+  {
+    inputs: [],
+    name: "mint",
+    outputs: [{ name: "", type: "uint32" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  ...
+] as const;
+```
+
+```ts [client.ts]
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+export const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: http()
+})
+```
+
+:::
+
 ## Return Value
 
 The response from the contract. Type is inferred.
@@ -127,10 +172,11 @@ The response from the contract. Type is inferred.
 The contract address.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', // [!code focus]
   abi: wagmiAbi,
   functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 ```
 
@@ -141,10 +187,11 @@ const data = await callContract(publicClient, {
 The contract's ABI.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi, // [!code focus]
   functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 ```
 
@@ -155,10 +202,26 @@ const data = await callContract(publicClient, {
 A function to extract from the ABI.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint', // [!code focus]
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+})
+```
+
+### from
+
+- **Type:** `Address`
+
+The sender of the call.
+
+```ts
+const { result } = await simulateContract(publicClient, {
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266' // [!code focus]
 })
 ```
 
@@ -169,7 +232,7 @@ const data = await callContract(publicClient, {
 The access list.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
@@ -178,6 +241,7 @@ const data = await callContract(publicClient, {
     address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
     storageKeys: ['0x1'],
   }], 
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 ```
 
@@ -189,26 +253,12 @@ const data = await callContract(publicClient, {
 Arguments to pass to function call.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0x1dfe7ca09e99d10835bf73044a23b73fc20623df',
   abi: wagmiAbi,
   functionName: 'balanceOf',
-  args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC'] // [!code focus]
-})
-```
-
-### from (optional)
-
-- **Type:** `Address`
-
-Optional sender override.
-
-```ts
-const data = await callContract(publicClient, {
-  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
-  abi: wagmiAbi,
-  functionName: 'mint',
-  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266' // [!code focus]
+  args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC'], // [!code focus]
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 })
 ```
 
@@ -219,11 +269,12 @@ const data = await callContract(publicClient, {
 The price (in wei) to pay per gas. Only applies to [Legacy Transactions](/docs/glossary/terms#TODO).
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
   args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   gasPrice: parseGwei('20'), // [!code focus]
 })
 ```
@@ -235,11 +286,12 @@ const data = await callContract(publicClient, {
 Total fee per gas (in wei), inclusive of `maxPriorityFeePerGas`. Only applies to [EIP-1559 Transactions](/docs/glossary/terms#TODO)
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
   args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   maxFeePerGas: parseGwei('20'),  // [!code focus]
 })
 ```
@@ -251,11 +303,12 @@ const data = await callContract(publicClient, {
 Max priority fee per gas (in wei). Only applies to [EIP-1559 Transactions](/docs/glossary/terms#TODO)
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
   args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   maxFeePerGas: parseGwei('20'),
   maxPriorityFeePerGas: parseGwei('2'), // [!code focus]
 })
@@ -268,11 +321,12 @@ const data = await callContract(publicClient, {
 Unique number identifying this transaction.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
   args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   nonce: 69 // [!code focus]
 })
 ```
@@ -284,11 +338,12 @@ const data = await callContract(publicClient, {
 Value in wei sent with this transaction.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
   args: [69420],
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   value: parseEther('1') // [!code focus]
 })
 ```
@@ -302,10 +357,11 @@ const data = await callContract(publicClient, {
 The block number to perform the read against.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   blockNumber: 15121123n, // [!code focus]
 })
 ```
@@ -318,10 +374,11 @@ const data = await callContract(publicClient, {
 The block tag to perform the read against.
 
 ```ts
-const data = await callContract(publicClient, {
+const { result } = await simulateContract(publicClient, {
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
   abi: wagmiAbi,
   functionName: 'mint',
+  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   blockTag: 'safe', // [!code focus]
 })
 ```