feat: decodeFunctionData

.changeset/rare-cats-unite.md

@@ -2,4 +2,4 @@
 "viem": patch
 ---
 
-Added `encodeFunctionParams`.
+Added `encodeFunctionData`.

.changeset/tame-flies-refuse.md

@@ -0,0 +1,6 @@
+---
+"viem": patch
+---
+
+- **Breaking**: Renamed `encodeFunctionParams` to `encodeFunctionData`.
+- Added `decodeFunctionData`.

site/.vitepress/sidebar.ts

@@ -430,24 +430,24 @@ export const sidebar: DefaultTheme.Sidebar = {
           text: 'Encoding',
           items: [
             {
-              text: 'decodeAbi 🚧',
+              text: 'decodeAbi',
               link: '/docs/contract/decodeAbi',
             },
             {
-              text: 'decodeConstructorParams 🚧',
-              link: '/docs/contract/decodeConstructorParams',
+              text: 'decodeConstructorData 🚧',
+              link: '/docs/contract/decodeConstructorData',
             },
             {
-              text: 'decodeErrorParams 🚧',
-              link: '/docs/contract/decodeErrorParams',
+              text: 'decodeErrorData 🚧',
+              link: '/docs/contract/decodeErrorData',
             },
             {
               text: 'decodeEventTopics 🚧',
               link: '/docs/contract/decodeEventTopics',
             },
             {
-              text: 'decodeFunctionParams 🚧',
-              link: '/docs/contract/decodeFunctionParams',
+              text: 'decodeFunctionData',
+              link: '/docs/contract/decodeFunctionData',
             },
             {
               text: 'decodeFunctionResult 🚧',
@@ -458,24 +458,24 @@ export const sidebar: DefaultTheme.Sidebar = {
               link: '/docs/contract/encodeAbi',
             },
             {
-              text: 'encodeConstructorParams 🚧',
-              link: '/docs/contract/encodeConstructorParams',
+              text: 'encodeConstructorData 🚧',
+              link: '/docs/contract/encodeConstructorData',
             },
             {
-              text: 'encodeErrorParams 🚧',
-              link: '/docs/contract/encodeErrorParams',
+              text: 'encodeErrorData 🚧',
+              link: '/docs/contract/encodeErrorData',
             },
             {
               text: 'encodeEventTopics 🚧',
               link: '/docs/contract/encodeEventTopics',
             },
             {
-              text: 'encodeFunctionParams 🚧',
-              link: '/docs/contract/encodeFunctionParams',
+              text: 'encodeFunctionData',
+              link: '/docs/contract/encodeFunctionData',
             },
             {
               text: 'encodeFunctionResult 🚧',
-              link: '/docs/contract/encodeFunctionArgs',
+              link: '/docs/contract/encodeFunctionData',
             },
           ],
         },

site/docs/contract/callContract.md

@@ -9,7 +9,7 @@ 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/encodeFunctionParams).
+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).
 
 ## Import
 

site/docs/contract/decodeConstructorData.md

@@ -0,0 +1,3 @@
+# decodeConstructorData
+
+TODO

site/docs/contract/decodeErrorData.md

@@ -0,0 +1,3 @@
+# decodeErrorData
+
+TODO

site/docs/contract/decodeFunctionData.md

@@ -0,0 +1,148 @@
+# decodeFunctionData
+
+Decodes ABI encoded data (4byte selector & arguments) into a function name and arguments.
+
+The opposite of [`encodeFunctionData`](/docs/contract/encodeFunctionData).
+
+## Install
+
+```ts
+import { decodeFunctionData } from 'viem'
+```
+
+## Usage
+
+Below is a very basic example of how to encode a function to calldata.
+
+::: code-group
+
+```ts [example.ts]
+import { decodeFunctionData } from 'viem'
+
+const { functionName } = decodeFunctionData({
+  abi: wagmiAbi,
+  data: '0xc2985578'
+})
+// { functionName: 'totalSupply' }
+```
+
+```ts
+export const wagmiAbi = [
+  ...
+  {
+    inputs: [],
+    name: "totalSupply",
+    outputs: [{ name: "", type: "uint256" }],
+    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()
+})
+```
+
+:::
+
+### Extracting Arguments
+
+If your calldata includes argument(s) after the 4byte function signature, you can extract them with the `args` return value.
+
+::: code-group
+
+```ts {7} [example.ts]
+import { decodeFunctionData } from 'viem'
+import { publicClient } from './client'
+import { wagmiAbi } from './abi'
+
+const { functionName, args } = decodeFunctionData({
+  abi: wagmiAbi,
+  data: '0x0423a1320000000000000000000000000000000000000000000000000000000000000001'
+})
+// { functionName: 'balanceOf', args: [1n] }
+```
+
+```ts [abi.ts]
+export const wagmiAbi = [
+  ...
+  {
+    inputs: [{ name: "owner", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    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
+
+```ts
+{
+  functionName: string;
+  args: unknown[] | undefined;
+}
+```
+
+Decoded ABI function data.
+
+### functionName
+
+- **Type**: `string`
+
+The decoded function name.
+
+### args
+
+- **Type**: `unknown[] | undefined`
+
+The decoded function arguments.
+
+## Parameters
+
+### abi
+
+- **Type:** [`Abi`](/docs/glossary/types#TODO)
+
+The contract's ABI.
+
+```ts
+const { functionName } = decodeFunctionData({
+  abi: wagmiAbi, // [!code focus]
+  data: '0xc2985578'
+})
+```
+
+### data
+
+- **Type:** `Hex`
+
+The encoded calldata.
+
+```ts
+const { functionName } = decodeFunctionData({
+  abi: wagmiAbi,
+  data: '0xc2985578' // [!code focus]
+})
+```

site/docs/contract/encodeConstructorData.md

@@ -0,0 +1,3 @@
+# encodeConstructorData
+
+TODO

site/docs/contract/encodeErrorData.md

@@ -0,0 +1,3 @@
+# encodeErrorData
+
+TODO

site/docs/contract/encodeFunctionParams.md → site/docs/contract/encodeFunctionData.md

@@ -1,11 +1,11 @@
-# encodeFunctionParams
+# encodeFunctionData
 
 Encodes the function name and parameters into an ABI encoded value (4byte selector & arguments).
 
 ## Install
 
 ```ts
-import { encodeFunctionParams } from 'viem'
+import { encodeFunctionData } from 'viem'
 ```
 
 ## Usage
@@ -15,9 +15,9 @@ Below is a very basic example of how to encode a function to calldata.
 ::: code-group
 
 ```ts [example.ts]
-import { encodeFunctionParams } from 'viem'
+import { encodeFunctionData } from 'viem'
 
-const data = encodeFunctionParams({
+const data = encodeFunctionData({
   abi: wagmiAbi,
   functionName: 'totalSupply'
 })
@@ -60,11 +60,11 @@ For example, the `balanceOf` function name below requires an **address** argumen
 ::: code-group
 
 ```ts {8} [example.ts]
-import { encodeFunctionParams } from 'viem'
+import { encodeFunctionData } from 'viem'
 import { publicClient } from './client'
 import { wagmiAbi } from './abi'
 
-const data = encodeFunctionParams({
+const data = encodeFunctionData({
   abi: wagmiAbi,
   functionName: 'balanceOf',
   args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC']
@@ -112,7 +112,7 @@ ABI encoded data (4byte function selector & arguments).
 The contract's ABI.
 
 ```ts
-const data = encodeFunctionParams({
+const data = encodeFunctionData({
   abi: wagmiAbi, // [!code focus]
   functionName: 'totalSupply',
 })
@@ -125,7 +125,7 @@ const data = encodeFunctionParams({
 The function to encode from the ABI.
 
 ```ts
-const data = encodeFunctionParams({
+const data = encodeFunctionData({
   abi: wagmiAbi,
   functionName: 'totalSupply', // [!code focus]
 })
@@ -138,7 +138,7 @@ const data = encodeFunctionParams({
 Arguments to pass to function call.
 
 ```ts
-const data = encodeFunctionParams({
+const data = encodeFunctionData({
   abi: wagmiAbi,
   functionName: 'balanceOf',
   args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC'] // [!code focus]

site/docs/contract/readContract.md

@@ -4,7 +4,7 @@ Calls a read-only function on a contract, and returns the response.
 
 A "read-only" function (constant function) on a Solidity contract is denoted by a `view` or `pure` keyword. They can only read the state of the contract, and cannot make any changes to it. Since read-only methods do not change the state of the contract, they do not require any gas to be executed, and can be called by any user without the need to pay for gas.
 
-Internally, `readContract` uses a [Public Client](/docs/clients/public) to call the [`call` action](/docs/actions/public/call) with [ABI-encoded `data`](/docs/contract/encodeFunctionParams).
+Internally, `readContract` uses a [Public Client](/docs/clients/public) to call the [`call` action](/docs/actions/public/call) with [ABI-encoded `data`](/docs/contract/encodeFunctionData).
 
 ## Import
 

site/docs/contract/writeContract.md

@@ -4,7 +4,7 @@ Calls a write function on a contract.
 
 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](/docs/glossary/terms) is needed to be broadcast in order to change the state. 
 
-Internally, `writeContract` uses a [Wallet Client](/docs/clients/wallet) to call the [`sendTransaction` action](/docs/actions/wallet/sendTransaction) with [ABI-encoded `data`](/docs/contract/encodeFunctionParams).
+Internally, `writeContract` uses a [Wallet Client](/docs/clients/wallet) to call the [`sendTransaction` action](/docs/actions/wallet/sendTransaction) with [ABI-encoded `data`](/docs/contract/encodeFunctionData).
 
 ## Import
 

src/actions/public/call.ts

@@ -1,5 +1,6 @@
 import type { Chain, Formatter } from '../../chains'
 import type { PublicClient } from '../../clients'
+import { InvalidGasArgumentsError } from '../../errors'
 import type {
   BlockTag,
   Hex,
@@ -8,7 +9,6 @@ import type {
 } from '../../types'
 import type { Formatted, TransactionRequestFormatter } from '../../utils'
 import { format, formatTransactionRequest, numberToHex } from '../../utils'
-import { InvalidGasArgumentsError } from '../../errors'
 
 export type FormattedCall<
   TFormatter extends Formatter | undefined = Formatter,