From c15bcf1d54b07517e074c30758e24d92df108bf0 Mon Sep 17 00:00:00 2001 From: awkweb Date: Mon, 10 Apr 2023 21:45:12 -0400 Subject: [PATCH] docs: tsdoc - public actions (#347) * docs: tsdoc * wip: public actions * build: strip comments from source * wip: public actions * docs: finish public actions * docs: finish tsdoc for public actions * build: split esm and types --- .gitignore | 2 +- package.json | 7 +- site/docs/actions/public/createEventFilter.md | 2 +- .../actions/public/getTransactionCount.md | 8 +- site/docs/actions/public/uninstallFilter.md | 2 +- .../public/waitForTransactionReceipt.md | 2 +- site/docs/actions/public/watchEvent.md | 2 +- site/docs/contract/deployContract.md | 18 +- site/docs/contract/estimateContractGas.md | 2 + site/docs/contract/getBytecode.md | 6 +- site/docs/contract/getContract.md | 4 +- site/docs/contract/getStorageAt.md | 3 + site/docs/contract/simulateContract.md | 4 +- site/docs/ens/actions/getEnsAvatar.md | 2 + site/docs/ens/actions/getEnsText.md | 2 + src/actions/ens/getEnsAddress.ts | 33 +- src/actions/ens/getEnsAvatar.ts | 30 +- src/actions/ens/getEnsName.ts | 22 +- src/actions/ens/getEnsResolver.ts | 32 +- src/actions/ens/getEnsText.ts | 29 +- src/actions/getContract.ts | 45 +- src/actions/public/call.ts | 30 +- src/actions/public/createBlockFilter.ts | 21 + .../public/createContractEventFilter.ts | 22 + src/actions/public/createEventFilter.ts | 23 + .../public/createPendingTransactionFilter.ts | 21 + src/actions/public/estimateContractGas.ts | 28 + src/actions/public/estimateGas.ts | 29 +- src/actions/public/getBalance.ts | 35 +- src/actions/public/getBlock.ts | 29 +- src/actions/public/getBlockNumber.ts | 22 +- .../public/getBlockTransactionCount.ts | 23 + src/actions/public/getBytecode.ts | 23 + src/actions/public/getChainId.ts | 21 + src/actions/public/getFeeHistory.ts | 34 +- src/actions/public/getFilterChanges.ts | 83 ++ src/actions/public/getFilterLogs.ts | 28 + src/actions/public/getGasPrice.ts | 19 +- src/actions/public/getLogs.ts | 21 +- src/actions/public/getStorageAt.ts | 24 + src/actions/public/getTransaction.ts | 25 +- .../public/getTransactionConfirmations.ts | 24 + src/actions/public/getTransactionCount.ts | 22 +- src/actions/public/getTransactionReceipt.ts | 24 + src/actions/public/multicall.ts | 39 + src/actions/public/readContract.ts | 32 + src/actions/public/simulateContract.ts | 32 + src/actions/public/uninstallFilter.ts | 25 + .../public/waitForTransactionReceipt.ts | 50 +- src/actions/public/watchBlockNumber.ts | 26 +- src/actions/public/watchBlocks.ts | 24 +- src/actions/public/watchContractEvent.ts | 31 + src/actions/public/watchEvent.ts | 38 +- .../public/watchPendingTransactions.ts | 53 +- src/actions/wallet/deployContract.ts | 27 + src/clients/decorators/public.ts | 997 +++++++++++++++++- src/clients/decorators/wallet.ts | 25 + 57 files changed, 2219 insertions(+), 68 deletions(-) diff --git a/.gitignore b/.gitignore index a782e9b568..6552caaecd 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,7 @@ cache coverage dist node_modules -tsconfig.tsbuildinfo +tsconfig*.tsbuildinfo # local env files .env diff --git a/package.json b/package.json index 23ee236824..ff73d92c97 100644 --- a/package.json +++ b/package.json @@ -6,9 +6,10 @@ "anvil": "dotenv -- sh -c 'anvil --fork-url $VITE_ANVIL_FORK_URL --fork-block-number $VITE_ANVIL_BLOCK_NUMBER --block-time $VITE_ANVIL_BLOCK_TIME'", "bench": "vitest bench --no-threads", "bench:ci": "CI=true vitest bench --no-threads", - "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm+types && size-limit", - "build:cjs": "tsc --project tsconfig.build.json --module commonjs --outDir ./dist/cjs && echo > ./dist/cjs/package.json '{\"type\":\"commonjs\"}'", - "build:esm+types": "tsc --project tsconfig.build.json --module es2015 --verbatimModuleSyntax --outDir ./dist/esm --declaration --declarationMap --declarationDir ./dist/types && echo > ./dist/esm/package.json '{\"type\":\"module\"}'", + "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm && pnpm run build:types && size-limit", + "build:cjs": "tsc --project tsconfig.build.json --module commonjs --outDir ./dist/cjs --removeComments && echo > ./dist/cjs/package.json '{\"type\":\"commonjs\"}'", + "build:esm": "tsc --project tsconfig.build.json --module es2015 --outDir ./dist/esm --removeComments --verbatimModuleSyntax && echo > ./dist/esm/package.json '{\"type\":\"module\"}'", + "build:types": "tsc --project tsconfig.build.json --module esnext --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap --verbatimModuleSyntax", "changeset": "changeset", "changeset:release": "pnpm build && changeset publish", "changeset:version": "changeset version && pnpm install --lockfile-only && pnpm bun scripts/updateVersion.ts", diff --git a/site/docs/actions/public/createEventFilter.md b/site/docs/actions/public/createEventFilter.md index 36cdaad338..a7ecd59ea4 100644 --- a/site/docs/actions/public/createEventFilter.md +++ b/site/docs/actions/public/createEventFilter.md @@ -258,4 +258,4 @@ const filter = await publicClient.createEventFilter({ ## JSON-RPC Methods -[`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newFilter) \ No newline at end of file +[`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) \ No newline at end of file diff --git a/site/docs/actions/public/getTransactionCount.md b/site/docs/actions/public/getTransactionCount.md index 007af54014..46f3286465 100644 --- a/site/docs/actions/public/getTransactionCount.md +++ b/site/docs/actions/public/getTransactionCount.md @@ -23,7 +23,7 @@ Returns the number of [Transactions](/docs/glossary/terms#transaction) an Accoun ```ts [example.ts] import { publicClient } from './client' -const block = await publicClient.getTransactionCount({ // [!code focus:99] +const transactionCount = await publicClient.getTransactionCount({ // [!code focus:99] address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', }) // 420 @@ -56,7 +56,7 @@ The number of transactions an account has sent. The address of the account. ```ts -const balance = await publicClient.getTransactionCount({ +const transactionCount = await publicClient.getTransactionCount({ address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', // [!code focus] }) ``` @@ -68,7 +68,7 @@ const balance = await publicClient.getTransactionCount({ Get the count at a block number. ```ts -const balance = await publicClient.getTransactionCount({ +const transactionCount = await publicClient.getTransactionCount({ address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', blockNumber: 69420n // [!code focus] }) @@ -81,7 +81,7 @@ const balance = await publicClient.getTransactionCount({ Get the count at a block tag. ```ts -const balance = await publicClient.getTransactionCount({ +const transactionCount = await publicClient.getTransactionCount({ address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', blockTag: 'safe' // [!code focus] }) diff --git a/site/docs/actions/public/uninstallFilter.md b/site/docs/actions/public/uninstallFilter.md index bf90562b5b..e4aba7dbbf 100644 --- a/site/docs/actions/public/uninstallFilter.md +++ b/site/docs/actions/public/uninstallFilter.md @@ -14,7 +14,7 @@ head: # uninstallFilter -Destroys a Filter that was created from one of the following Actions: +Destroys a [`Filter`](/docs/glossary/types.html#filter) that was created from one of the following Actions: - [`createBlockFilter`](/docs/actions/public/createBlockFilter) - [`createEventFilter`](/docs/actions/public/createEventFilter) diff --git a/site/docs/actions/public/waitForTransactionReceipt.md b/site/docs/actions/public/waitForTransactionReceipt.md index 6f5f6948a0..b7f7bd2cc8 100644 --- a/site/docs/actions/public/waitForTransactionReceipt.md +++ b/site/docs/actions/public/waitForTransactionReceipt.md @@ -16,7 +16,7 @@ head: Waits for the [Transaction](/docs/glossary/terms#transaction) to be included on a [Block](/docs/glossary/terms#block) (one confirmation), and then returns the [Transaction Receipt](/docs/glossary/terms#transaction-receipt). If the Transaction reverts, then the action will throw an error. -The `waitForTransactionReceipt` action additionally supports Replacement detection (ie. sped up Transactions). +The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions). ## Usage diff --git a/site/docs/actions/public/watchEvent.md b/site/docs/actions/public/watchEvent.md index 413b3ce081..b74d219b70 100644 --- a/site/docs/actions/public/watchEvent.md +++ b/site/docs/actions/public/watchEvent.md @@ -18,7 +18,7 @@ Watches and returns emitted [Event Logs](/docs/glossary/terms#event-log). This Action will batch up all the Event Logs found within the [`pollingInterval`](#pollinginterval-optional), and invoke them via [`onLogs`](#onLogs). -`watchEvent` will attempt to create an [Event Filter](/docs/actions/public/watchEvent) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (ie. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](/docs/actions/public/getLogs) instead. +`watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter.html) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (ie. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](/docs/actions/public/getLogs) instead. ## Usage diff --git a/site/docs/contract/deployContract.md b/site/docs/contract/deployContract.md index eee1255027..cdc17b6cd5 100644 --- a/site/docs/contract/deployContract.md +++ b/site/docs/contract/deployContract.md @@ -24,7 +24,7 @@ Deploys a contract to the network, given bytecode & constructor arguments. import { wagmiAbi } from './abi' import { account, walletClient } from './config' -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi, account, bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', @@ -70,7 +70,7 @@ import { deployContract } from 'viem' import { wagmiAbi } from './abi' import { account, walletClient } from './config' -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi, account, args: [69420], @@ -108,6 +108,12 @@ export const account = privateKeyToAccount(...) ::: +## Returns + +[`Hash`](/docs/glossary/types#hash) + +The [Transaction](/docs/glossary/terms#transaction) hash. + ## Parameters ### abi @@ -117,7 +123,7 @@ export const account = privateKeyToAccount(...) The contract's ABI. ```ts -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi: wagmiAbi, // [!code focus] account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', @@ -133,7 +139,7 @@ The Account to deploy the contract from. Accepts a [JSON-RPC Account](/docs/clients/wallet#json-rpc-accounts) or [Local Account (Private Key, etc)](/docs/clients/wallet#local-accounts-private-key-mnemonic-etc). ```ts -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi: wagmiAbi, account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', // [!code focus] bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', @@ -147,7 +153,7 @@ await walletClient.deployContract({ The contract's bytecode. ```ts -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi: wagmiAbi, account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', // [!code focus] @@ -161,7 +167,7 @@ await walletClient.deployContract({ Constructor arguments to call upon deployment. ```ts -await walletClient.deployContract({ +const hash = await walletClient.deployContract({ abi: wagmiAbi, account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', diff --git a/site/docs/contract/estimateContractGas.md b/site/docs/contract/estimateContractGas.md index c9e836754f..2e1f6539ee 100644 --- a/site/docs/contract/estimateContractGas.md +++ b/site/docs/contract/estimateContractGas.md @@ -16,6 +16,8 @@ head: Estimates the gas required to successfully execute a contract write function call. +Internally, `estimateContractGas` uses a [Public Client](/docs/clients/public) to call the [`estimateGas` action](/docs/actions/public/estimateGas) with [ABI-encoded `data`](/docs/contract/encodeFunctionData). + ## Usage Below is a very basic example of how to estimate gas (with no arguments). diff --git a/site/docs/contract/getBytecode.md b/site/docs/contract/getBytecode.md index 7a6c97dff8..e09ed9b52c 100644 --- a/site/docs/contract/getBytecode.md +++ b/site/docs/contract/getBytecode.md @@ -58,4 +58,8 @@ The contract address. const bytecode = await publicClient.getBytecode({ address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', // [!code focus] }) -``` \ No newline at end of file +``` + +## JSON-RPC Method + +[`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode) \ No newline at end of file diff --git a/site/docs/contract/getContract.md b/site/docs/contract/getContract.md index c148a34d16..6c0b6ce3a2 100644 --- a/site/docs/contract/getContract.md +++ b/site/docs/contract/getContract.md @@ -155,7 +155,7 @@ Depending on if you create a contract instance with a Public Client, Wallet Clie #### With Public Client -If you pass in a [`publicClient`](/docs/contract/getContract#publicclient), the following methods are available: +If you pass in a [`publicClient`](https://viem.sh/docs/clients/public.html), the following methods are available: - [`createEventFilter`](/docs/contract/createContractEventFilter.html) - [`estimateGas`](/docs/contract/estimateContractGas.html) @@ -165,7 +165,7 @@ If you pass in a [`publicClient`](/docs/contract/getContract#publicclient), the #### With Wallet Client -If you pass in a [`walletClient`](/docs/contract/getContract#walletclient), the following methods are available: +If you pass in a [`walletClient`](/docs/clients/wallet.html), the following methods are available: - [`write`](/docs/contract/writeContract.html) diff --git a/site/docs/contract/getStorageAt.md b/site/docs/contract/getStorageAt.md index 2a2c07350f..63b823eefb 100644 --- a/site/docs/contract/getStorageAt.md +++ b/site/docs/contract/getStorageAt.md @@ -77,3 +77,6 @@ const data = await publicClient.getStorageAt({ }) ``` +## JSON-RPC Method + +[`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat) \ No newline at end of file diff --git a/site/docs/contract/simulateContract.md b/site/docs/contract/simulateContract.md index 380b069c2d..1c97b1125a 100644 --- a/site/docs/contract/simulateContract.md +++ b/site/docs/contract/simulateContract.md @@ -38,7 +38,6 @@ const { result } = await publicClient.simulateContract({ functionName: 'mint', account, }) -// 69420 ``` ```ts [abi.ts] @@ -94,7 +93,6 @@ const { result } = await publicClient.simulateContract({ args: [69420], account, }) -// 69420 ``` ```ts [abi.ts] @@ -184,7 +182,7 @@ export const publicClient = createPublicClient({ ## Return Value -The response from the contract. Type is inferred. +The simulation result and write request. Type is inferred. ## Parameters diff --git a/site/docs/ens/actions/getEnsAvatar.md b/site/docs/ens/actions/getEnsAvatar.md index 373c244405..63842544c1 100644 --- a/site/docs/ens/actions/getEnsAvatar.md +++ b/site/docs/ens/actions/getEnsAvatar.md @@ -16,6 +16,8 @@ head: Gets the avatar of an ENS name. +Calls [`getEnsText`](/docs/ens/actions/getEnsText.html) with `key` set to `'avatar'`. + ## Usage ::: code-group diff --git a/site/docs/ens/actions/getEnsText.md b/site/docs/ens/actions/getEnsText.md index 3a55bf7e9a..4f81877437 100644 --- a/site/docs/ens/actions/getEnsText.md +++ b/site/docs/ens/actions/getEnsText.md @@ -16,6 +16,8 @@ head: Gets a text record for specified ENS name. +Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. + ## Usage ::: code-group diff --git a/src/actions/ens/getEnsAddress.ts b/src/actions/ens/getEnsAddress.ts index 601494ea77..cd4e0e0f36 100644 --- a/src/actions/ens/getEnsAddress.ts +++ b/src/actions/ens/getEnsAddress.ts @@ -17,9 +17,9 @@ import type { ReadContractParameters } from '../public/index.js' export type GetEnsAddressParameters = Prettify< Pick & { - /** ENS name to get address. */ + /** Name to get the address for. */ name: string - /** Address of ENS Universal Resolver Contract */ + /** Address of ENS Universal Resolver Contract. */ universalResolverAddress?: Address } > @@ -27,10 +27,33 @@ export type GetEnsAddressParameters = Prettify< export type GetEnsAddressReturnType = Address | null /** - * @description Gets address for ENS name. + * Gets address for ENS name. * - * - Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. - * - Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * - Docs: https://viem.sh/docs/ens/actions/getEnsAddress.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param client - Client to use + * @param parameters - {@link GetEnsAddressParameters} + * @returns Address for ENS name or `null` if not found. {@link GetEnsAddressReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getEnsAddress, normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensAddress = await getEnsAddress(client, { + * name: normalize('wagmi-dev.eth'), + * }) + * // '0xd2135CfB216b74109775236E36d4b433F1DF507B' */ export async function getEnsAddress( client: PublicClient, diff --git a/src/actions/ens/getEnsAvatar.ts b/src/actions/ens/getEnsAvatar.ts index 14afaf852a..9c74520853 100644 --- a/src/actions/ens/getEnsAvatar.ts +++ b/src/actions/ens/getEnsAvatar.ts @@ -6,7 +6,7 @@ import type { GetEnsTextParameters } from './getEnsText.js' export type GetEnsAvatarParameters = Prettify< Omit & { - /** Custom gateways to use */ + /** Gateway urls to resolve IPFS and/or Arweave assets. */ gatewayUrls?: AssetGatewayUrls } > @@ -14,7 +14,33 @@ export type GetEnsAvatarParameters = Prettify< export type GetEnsAvatarReturnType = string | null /** - * @description Gets avatar URI for ENS name. + * Gets the avatar of an ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsAvatar.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls [`getEnsText`](https://viem.sh/docs/ens/actions/getEnsText.html) with `key` set to `'avatar'`. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param client - Client to use + * @param parameters - {@link GetEnsAvatarParameters} + * @returns Avatar URI or `null` if not found. {@link GetEnsAvatarReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getEnsAvatar, normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensAvatar = await getEnsAvatar(client, { + * name: normalize('wagmi-dev.eth'), + * }) + * // 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio' */ export async function getEnsAvatar( client: PublicClient, diff --git a/src/actions/ens/getEnsName.ts b/src/actions/ens/getEnsName.ts index f71ddf19f9..d24d757c31 100644 --- a/src/actions/ens/getEnsName.ts +++ b/src/actions/ens/getEnsName.ts @@ -20,12 +20,28 @@ export type GetEnsNameParameters = Prettify< export type GetEnsNameReturnType = string | null /** - * @description Gets primary name for specified address. + * Gets primary name for specified address. * - * - Calls `reverse(bytes)` on ENS Universal Resolver Contract. + * - Docs: https://viem.sh/docs/ens/actions/getEnsName.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `reverse(bytes)` on ENS Universal Resolver Contract to "reverse resolve" the address to the primary ENS name. + * + * @param client - Client to use + * @param parameters - {@link GetEnsNameParameters} + * @returns Name or `null` if not found. {@link GetEnsNameReturnType} * * @example - * const ensName = await getEnsName(publicClient, { + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getEnsName } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensName = await getEnsName(client, { * address: '0xd2135CfB216b74109775236E36d4b433F1DF507B', * }) * // 'wagmi-dev.eth' diff --git a/src/actions/ens/getEnsResolver.ts b/src/actions/ens/getEnsResolver.ts index 0760e9f0fd..3f2a6d06f3 100644 --- a/src/actions/ens/getEnsResolver.ts +++ b/src/actions/ens/getEnsResolver.ts @@ -7,9 +7,9 @@ import type { ReadContractParameters } from '../public/index.js' export type GetEnsResolverParameters = Prettify< Pick & { - /** ENS name to get resolver. */ + /** Name to get the address for. */ name: string - /** Address of ENS Universal Resolver Contract */ + /** Address of ENS Universal Resolver Contract. */ universalResolverAddress?: Address } > @@ -17,7 +17,33 @@ export type GetEnsResolverParameters = Prettify< export type GetEnsResolverReturnType = Address /** - * @description Gets resolver for ENS name. + * Gets resolver for ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsResolver.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `findResolver(bytes)` on ENS Universal Resolver Contract to retrieve the resolver of an ENS name. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param client - Client to use + * @param parameters - {@link GetEnsResolverParameters} + * @returns Address for ENS resolver. {@link GetEnsResolverReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getEnsResolver, normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const resolverAddress = await getEnsResolver(client, { + * name: normalize('wagmi-dev.eth'), + * }) + * // '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41' */ export async function getEnsResolver( client: PublicClient, diff --git a/src/actions/ens/getEnsText.ts b/src/actions/ens/getEnsText.ts index c269b42e31..47db34b7a6 100644 --- a/src/actions/ens/getEnsText.ts +++ b/src/actions/ens/getEnsText.ts @@ -13,9 +13,9 @@ import type { ReadContractParameters } from '../public/index.js' export type GetEnsTextParameters = Prettify< Pick & { - /** ENS name to get ENS avatar for. */ + /** ENS name to get Text for. */ name: string - /** Text record to retrieve */ + /** Text record to retrieve. */ key: string /** Address of ENS Universal Resolver Contract. */ universalResolverAddress?: Address @@ -25,15 +25,30 @@ export type GetEnsTextParameters = Prettify< export type GetEnsTextReturnType = string | null /** - * @description Gets text record for ENS name. + * Gets a text record for specified ENS name. * - * - Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. - * - Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * - Docs: https://viem.sh/docs/ens/actions/getEnsResolver.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param client - Client to use + * @param parameters - {@link GetEnsTextParameters} + * @returns Address for ENS resolver. {@link GetEnsTextReturnType} * * @example - * import { normalize } from 'viem/ens' + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getEnsText, normalize } from 'viem/ens' * - * const twitterRecord = await getEnsText(publicClient, { + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const twitterRecord = await getEnsText(client, { * name: normalize('wagmi-dev.eth'), * key: 'com.twitter', * }) diff --git a/src/actions/getContract.ts b/src/actions/getContract.ts index 9f2c6ef5df..c813c4917e 100644 --- a/src/actions/getContract.ts +++ b/src/actions/getContract.ts @@ -61,9 +61,25 @@ export type GetContractParameters< abi: Narrow /** Contract address */ address: Address - /** Public client */ + /** + * Public client + * + * If you pass in a [`publicClient`](https://viem.sh/docs/clients/public.html), the following methods are available: + * + * - [`createEventFilter`](https://viem.sh/docs/contract/createContractEventFilter.html) + * - [`estimateGas`](https://viem.sh/docs/contract/estimateContractGas.html) + * - [`read`](https://viem.sh/docs/contract/readContract.html) + * - [`simulate`](https://viem.sh/docs/contract/simulateContract.html) + * - [`watchEvent`](https://viem.sh/docs/contract/watchContractEvent.html) + */ publicClient?: TPublicClient - /** Wallet client */ + /** + * Wallet client + * + * If you pass in a [`walletClient`](https://viem.sh/docs/clients/wallet.html), the following methods are available: + * + * - [`write`](https://viem.sh/docs/contract/writeContract.html) + */ walletClient?: TWalletClient } @@ -201,7 +217,30 @@ export type GetContractReturnType< > /** - * Gets type-safe contract instance. + * Gets type-safe interface for performing contract-related actions with a specific `abi` and `address`. + * + * - Docs https://viem.sh/docs/contract/getContract.html + * + * @remarks + * Using Contract Instances can make it easier to work with contracts if you don't want to pass the `abi` and `address` properites every time you perform contract actions, e.g. [`readContract`](https://viem.sh/docs/contract/readContract.html), [`writeContract`](https://viem.sh/docs/contract/writeContract.html), [`estimateContractGas`](https://viem.sh/docs/contract/estimateContractGas.html), etc. + * + * @example + * import { createPublicClient, getContract, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const publicClient = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const contract = getContract({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi([ + * 'function balanceOf(address owner) view returns (uint256)', + * 'function ownerOf(uint256 tokenId) view returns (address)', + * 'function totalSupply() view returns (uint256)', + * ]), + * publicClient, + * }) */ export function getContract< TTransport extends Transport, diff --git a/src/actions/public/call.ts b/src/actions/public/call.ts index 0d06a0f878..d664b413ad 100644 --- a/src/actions/public/call.ts +++ b/src/actions/public/call.ts @@ -43,13 +43,41 @@ export type CallParameters< } | { blockNumber?: never - /** The balance of the account at a block tag. */ + /** + * The balance of the account at a block tag. + * @default 'latest' + */ blockTag?: BlockTag } ) export type CallReturnType = { data: Hex | undefined } +/** + * Executes a new message call immediately without submitting a transaction to the network. + * + * - Docs: https://viem.sh/docs/actions/public/call.html + * - JSON-RPC Methods: [`eth_call`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call) + * + * @param client - Client to use + * @param parameters - {@link CallParameters} + * @returns The call data. {@link CallReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { call } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const data = await call(client, { + * account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', + * data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', + * to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + * }) + */ export async function call( client: PublicClient, args: CallParameters, diff --git a/src/actions/public/createBlockFilter.ts b/src/actions/public/createBlockFilter.ts index a5d706eaf7..9a6c085e3f 100644 --- a/src/actions/public/createBlockFilter.ts +++ b/src/actions/public/createBlockFilter.ts @@ -3,6 +3,27 @@ import type { Chain, Filter } from '../../types/index.js' export type CreateBlockFilterReturnType = Filter<'block'> +/** + * Creates a [`Filter`](https://viem.sh/docs/glossary/types.html#filter) to listen for new block hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createBlockFilter.html + * - JSON-RPC Methods: [`eth_newBlockFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newBlockFilter) + * + * @param client - Client to use + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateBlockFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createBlockFilter } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createBlockFilter(client) + * // { id: "0x345a6572337856574a76364e457a4366", type: 'block' } + */ export async function createBlockFilter( client: PublicClient, ): Promise { diff --git a/src/actions/public/createContractEventFilter.ts b/src/actions/public/createContractEventFilter.ts index 43ce230aa0..b5c4999145 100644 --- a/src/actions/public/createContractEventFilter.ts +++ b/src/actions/public/createContractEventFilter.ts @@ -48,6 +48,28 @@ export type CreateContractEventFilterReturnType< | undefined = undefined, > = Filter<'event', TAbi, TEventName, TArgs> +/** + * Creates a Filter to retrieve event logs that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges) or [`getFilterLogs`](https://viem.sh/docs/actions/public/getFilterLogs). + * + * - Docs: https://viem.sh/docs/contract/createContractEventFilter.html + * + * @param client - Client to use + * @param parameters - {@link CreateContractEventFilterParameters} + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateContractEventFilterReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createContractEventFilter } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createContractEventFilter(client, { + * abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']), + * }) + */ export async function createContractEventFilter< TChain extends Chain | undefined, TAbi extends Abi | readonly unknown[], diff --git a/src/actions/public/createEventFilter.ts b/src/actions/public/createEventFilter.ts index 5b0a7ea717..7146cab72d 100644 --- a/src/actions/public/createEventFilter.ts +++ b/src/actions/public/createEventFilter.ts @@ -59,6 +59,29 @@ export type CreateEventFilterReturnType< | undefined = undefined, > = Prettify> +/** + * Creates a [`Filter`](https://viem.sh/docs/glossary/types.html#filter) to listen for new events that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createEventFilter.html + * - JSON-RPC Methods: [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) + * + * @param client - Client to use + * @param parameters - {@link CreateEventFilterParameters} + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateEventFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createEventFilter } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createEventFilter(client, { + * address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2', + * }) + */ export async function createEventFilter< TChain extends Chain | undefined, TAbiEvent extends AbiEvent | undefined, diff --git a/src/actions/public/createPendingTransactionFilter.ts b/src/actions/public/createPendingTransactionFilter.ts index 2d3b88662b..5556727f94 100644 --- a/src/actions/public/createPendingTransactionFilter.ts +++ b/src/actions/public/createPendingTransactionFilter.ts @@ -3,6 +3,27 @@ import type { Chain, Filter } from '../../types/index.js' export type CreatePendingTransactionFilterReturnType = Filter<'transaction'> +/** + * Creates a Filter to listen for new pending transaction hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createPendingTransactionFilter.html + * - JSON-RPC Methods: [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) + * + * @param client - Client to use + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateBlockFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createPendingTransactionFilter } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createPendingTransactionFilter(client) + * // { id: "0x345a6572337856574a76364e457a4366", type: 'transaction' } + */ export async function createPendingTransactionFilter< TTransport extends Transport, TChain extends Chain | undefined, diff --git a/src/actions/public/estimateContractGas.ts b/src/actions/public/estimateContractGas.ts index 07cbcfb8f4..d8bd2b9b41 100644 --- a/src/actions/public/estimateContractGas.ts +++ b/src/actions/public/estimateContractGas.ts @@ -26,6 +26,34 @@ export type EstimateContractGasParameters< export type EstimateContractGasReturnType = bigint +/** + * Estimates the gas required to successfully execute a contract write function call. + * + * - Docs: https://viem.sh/docs/contract/estimateContractGas.html + * + * @remarks + * Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`estimateGas` action](https://viem.sh/docs/actions/public/estimateGas) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param client - Client to use + * @param parameters - {@link EstimateContractGasParameters} + * @returns The gas estimate (in wei). {@link EstimateContractGasReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { estimateContractGas } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gas = await estimateContractGas(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function mint() public']), + * functionName: 'mint', + * account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', + * }) + */ export async function estimateContractGas< TAbi extends Abi | readonly unknown[], TFunctionName extends string, diff --git a/src/actions/public/estimateGas.ts b/src/actions/public/estimateGas.ts index 3569f33cb0..dd198fbb55 100644 --- a/src/actions/public/estimateGas.ts +++ b/src/actions/public/estimateGas.ts @@ -49,7 +49,10 @@ export type EstimateGasParameters< } | { blockNumber?: never - /** The balance of the account at a block tag. */ + /** + * The balance of the account at a block tag. + * @default 'latest' + */ blockTag?: BlockTag } ) @@ -57,7 +60,29 @@ export type EstimateGasParameters< export type EstimateGasReturnType = bigint /** - * @description Estimates the gas necessary to complete a transaction without submitting it to the network. + * Estimates the gas necessary to complete a transaction without submitting it to the network. + * + * - Docs: https://viem.sh/docs/actions/public/estimateGas.html + * - JSON-RPC Methods: [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas) + * + * @param client - Client to use + * @param parameters - {@link EstimateGasParameters} + * @returns The gas estimate (in wei). {@link EstimateGasReturnType} + * + * @example + * import { createPublicClient, http, parseEther } from 'viem' + * import { mainnet } from 'viem/chains' + * import { estimateGas } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gasEstimate = await estimateGas(client, { + * account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + * value: parseEther('1'), + * }) */ export async function estimateGas< TChain extends Chain | undefined, diff --git a/src/actions/public/getBalance.ts b/src/actions/public/getBalance.ts index fbef1ba50e..f5eb379808 100644 --- a/src/actions/public/getBalance.ts +++ b/src/actions/public/getBalance.ts @@ -21,7 +21,40 @@ export type GetBalanceParameters = { export type GetBalanceReturnType = bigint /** - * @description Returns the balance of an address in wei. + * Returns the balance of an address in wei. + * + * - Docs: https://viem.sh/docs/actions/public/getBalance.html + * - JSON-RPC Methods: [`eth_getBalance`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance) + * + * @remarks + * You can convert the balance to ether units with [`formatEther`](https://viem.sh/docs/utilities/formatEther.html). + * + * ```ts + * const balance = await getBalance(client, { + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * blockTag: 'safe' + * }) + * const balanceAsEther = formatEther(balance) + * // "6.942" + * ``` + * + * @param client - Client to use + * @param parameters - {@link GetBalanceParameters} + * @returns The balance of the address in wei. {@link GetBalanceReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getBalance } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const balance = await getBalance(client, { + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) + * // 10000000000000000000000n (wei) */ export async function getBalance( client: PublicClient, diff --git a/src/actions/public/getBlock.ts b/src/actions/public/getBlock.ts index 85563268bb..668ec542a1 100644 --- a/src/actions/public/getBlock.ts +++ b/src/actions/public/getBlock.ts @@ -33,7 +33,10 @@ export type GetBlockParameters = { | { blockHash?: never blockNumber?: never - /** The block tag. Defaults to 'latest'. */ + /** + * The block tag. + * @default 'latest' + */ blockTag?: BlockTag } ) @@ -42,6 +45,30 @@ export type GetBlockReturnType< TChain extends Chain | undefined = Chain | undefined, > = FormattedBlock> +/** + * Returns information about a block at a block number, hash, or tag. + * + * - Docs: https://viem.sh/docs/actions/public/getBlock.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/fetching-blocks + * - JSON-RPC Methods: + * - Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) for `blockNumber` & `blockTag`. + * - Calls [`eth_getBlockByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash) for `blockHash`. + * + * @param client - Client to use + * @param parameters - {@link GetBlockParameters} + * @returns Information about the block. {@link GetBlockReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getBlock } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const block = await getBlock(client) + */ export async function getBlock< TChain extends Chain | undefined, TAccount extends Account | undefined, diff --git a/src/actions/public/getBlockNumber.ts b/src/actions/public/getBlockNumber.ts index a142f75b39..2dd1e98e33 100644 --- a/src/actions/public/getBlockNumber.ts +++ b/src/actions/public/getBlockNumber.ts @@ -16,7 +16,27 @@ export function getBlockNumberCache(id: string) { } /** - * @description Returns the number of the most recent block seen. + * Returns the number of the most recent block seen. + * + * - Docs: https://viem.sh/docs/actions/public/getBlockNumber.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/fetching-blocks + * - JSON-RPC Methods: [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) + * + * @param client - Client to use + * @param parameters - {@link GetBlockNumberParameters} + * @returns The number of the block. {@link GetBlockNumberReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getBlockNumber } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const blockNumber = await getBlockNumber(client) + * // 69420n */ export async function getBlockNumber( client: PublicClient, diff --git a/src/actions/public/getBlockTransactionCount.ts b/src/actions/public/getBlockTransactionCount.ts index 174762cbc1..bb98789c9c 100644 --- a/src/actions/public/getBlockTransactionCount.ts +++ b/src/actions/public/getBlockTransactionCount.ts @@ -24,6 +24,29 @@ export type GetBlockTransactionCountParameters = export type GetBlockTransactionCountReturnType = number +/** + * Returns the number of Transactions at a block number, hash, or tag. + * + * - Docs: https://viem.sh/docs/actions/public/getBlockTransactionCount.html + * - JSON-RPC Methods: + * - Calls [`eth_getBlockTransactionCountByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) for `blockNumber` & `blockTag`. + * - Calls [`eth_getBlockTransactionCountByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) for `blockHash`. + * + * @param client - Client to use + * @param parameters - {@link GetBlockTransactionCountParameters} + * @returns The block transaction count. {@link GetBlockTransactionCountReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getBlockTransactionCount } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const count = await getBlockTransactionCount(client) + */ export async function getBlockTransactionCount< TChain extends Chain | undefined, >( diff --git a/src/actions/public/getBytecode.ts b/src/actions/public/getBytecode.ts index f281bd0c8d..4da27a43f6 100644 --- a/src/actions/public/getBytecode.ts +++ b/src/actions/public/getBytecode.ts @@ -17,6 +17,29 @@ export type GetBytecodeParameters = { export type GetBytecodeReturnType = Hex | undefined +/** + * Retrieves the bytecode at an address. + * + * - Docs: https://viem.sh/docs/contract/getBytecode.html + * - JSON-RPC Methods: [`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode) + * + * @param client - Client to use + * @param parameters - {@link GetBytecodeParameters} + * @returns The contract's bytecode. {@link GetBytecodeReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getBytecode } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const code = await getBytecode(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * }) + */ export async function getBytecode( client: PublicClient, { address, blockNumber, blockTag = 'latest' }: GetBytecodeParameters, diff --git a/src/actions/public/getChainId.ts b/src/actions/public/getChainId.ts index b2282733c0..563526dd5c 100644 --- a/src/actions/public/getChainId.ts +++ b/src/actions/public/getChainId.ts @@ -8,6 +8,27 @@ import { hexToNumber } from '../../utils/index.js' export type GetChainIdReturnType = number +/** + * Returns the chain ID associated with the current network. + * + * - Docs: https://viem.sh/docs/actions/public/getChainId.html + * - JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid) + * + * @param client - Client to use + * @returns The current chain ID. {@link GetChainIdReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getChainId } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const chainId = await getChainId(client) + * // 1 + */ export async function getChainId< TChain extends Chain | undefined, TAccount extends Account | undefined, diff --git a/src/actions/public/getFeeHistory.ts b/src/actions/public/getFeeHistory.ts index 923b0a1ea4..3baa273679 100644 --- a/src/actions/public/getFeeHistory.ts +++ b/src/actions/public/getFeeHistory.ts @@ -5,14 +5,25 @@ import { numberToHex } from '../../utils/index.js' import { formatFeeHistory } from '../../utils/formatters/index.js' export type GetFeeHistoryParameters = { + /** + * Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. Less than requested may be returned if not all blocks are available. + */ blockCount: number + /** + * A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas in ascending order, weighted by gas used. + */ rewardPercentiles: number[] } & ( | { blockNumber?: never + /** + * Highest number block of the requested range. + * @default 'latest' + */ blockTag?: BlockTag } | { + /** Highest number block of the requested range. */ blockNumber?: bigint blockTag?: never } @@ -20,7 +31,28 @@ export type GetFeeHistoryParameters = { export type GetFeeHistoryReturnType = FeeHistory /** - * @description Returns a collection of historical gas information. + * Returns a collection of historical gas information. + * + * - Docs: https://viem.sh/docs/actions/public/getFeeHistory.html + * - JSON-RPC Methods: [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory) + * + * @param client - Client to use + * @param parameters - {@link GetFeeHistoryParameters} + * @returns The gas estimate (in wei). {@link GetFeeHistoryReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getFeeHistory } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const feeHistory = await getFeeHistory(client, { + * blockCount: 4, + * rewardPercentiles: [25, 75], + * }) */ export async function getFeeHistory( client: PublicClient, diff --git a/src/actions/public/getFilterChanges.ts b/src/actions/public/getFilterChanges.ts index f937b8ea40..10a21ef540 100644 --- a/src/actions/public/getFilterChanges.ts +++ b/src/actions/public/getFilterChanges.ts @@ -30,6 +30,89 @@ export type GetFilterChangesReturnType< ? Log[] : Hash[] +/** + * Returns a list of logs or hashes based on a [Filter](/docs/glossary/terms#filter) since the last time it was called. + * + * - Docs: https://viem.sh/docs/actions/public/getFilterChanges.html + * - JSON-RPC Methods: [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges) + * + * @remarks + * A Filter can be created from the following actions: + * + * - [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter) + * - [`createContractEventFilter`](https://viem.sh/docs/contract/createContractEventFilter) + * - [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter) + * - [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter) + * + * Depending on the type of filter, the return value will be different: + * + * - If the filter was created with `createContractEventFilter` or `createEventFilter`, it returns a list of logs. + * - If the filter was created with `createPendingTransactionFilter`, it returns a list of transaction hashes. + * - If the filter was created with `createBlockFilter`, it returns a list of block hashes. + * + * @param client - Client to use + * @param parameters - {@link GetFilterChangesParameters} + * @returns Logs or hashes. {@link GetFilterChangesReturnType} + * + * @example + * // Blocks + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createBlockFilter, getFilterChanges } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createBlockFilter(client) + * const hashes = await getFilterChanges(client, { filter }) + * + * @example + * // Contract Events + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createContractEventFilter, getFilterChanges } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createContractEventFilter(client, { + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']), + * eventName: 'Transfer', + * }) + * const logs = await getFilterChanges(client, { filter }) + * + * @example + * // Raw Events + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createEventFilter, getFilterChanges } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createEventFilter(client, { + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'), + * }) + * const logs = await getFilterChanges(client, { filter }) + * + * @example + * // Transactions + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createPendingTransactionFilter, getFilterChanges } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createPendingTransactionFilter(client) + * const hashes = await getFilterChanges(client, { filter }) + */ export async function getFilterChanges< TTransport extends Transport, TChain extends Chain | undefined, diff --git a/src/actions/public/getFilterLogs.ts b/src/actions/public/getFilterLogs.ts index 6402c7f204..35df823f76 100644 --- a/src/actions/public/getFilterLogs.ts +++ b/src/actions/public/getFilterLogs.ts @@ -23,6 +23,34 @@ export type GetFilterLogsReturnType< TEventName extends string | undefined = MaybeAbiEventName, > = Log[] +/** + * Returns a list of event logs since the filter was created. + * + * - Docs: https://viem.sh/docs/actions/public/getFilterLogs.html + * - JSON-RPC Methods: [`eth_getFilterLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterlogs) + * + * @remarks + * `getFilterLogs` is only compatible with **event filters**. + * + * @param client - Client to use + * @param parameters - {@link GetFilterLogsParameters} + * @returns A list of event logs. {@link GetFilterLogsReturnType} + * + * @example + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createEventFilter, getFilterLogs } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createEventFilter(client, { + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'), + * }) + * const logs = await getFilterLogs(client, { filter }) + */ export async function getFilterLogs< TChain extends Chain | undefined, TAbiEvent extends AbiEvent | undefined, diff --git a/src/actions/public/getGasPrice.ts b/src/actions/public/getGasPrice.ts index bcfc3f7529..68cce7aedf 100644 --- a/src/actions/public/getGasPrice.ts +++ b/src/actions/public/getGasPrice.ts @@ -8,7 +8,24 @@ import type { Account, Chain } from '../../types/index.js' export type GetGasPriceReturnType = bigint /** - * @description Returns the current price of gas (in wei). + * Returns the current price of gas (in wei). + * + * - Docs: https://viem.sh/docs/actions/public/getGasPrice.html + * - JSON-RPC Methods: [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) + * + * @param client - Client to use + * @returns The gas price (in wei). {@link GetGasPriceReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getGasPrice } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gasPrice = await getGasPrice(client) */ export async function getGasPrice< TChain extends Chain | undefined, diff --git a/src/actions/public/getLogs.ts b/src/actions/public/getLogs.ts index 15d5dadb01..6bfc94088c 100644 --- a/src/actions/public/getLogs.ts +++ b/src/actions/public/getLogs.ts @@ -58,7 +58,26 @@ export type GetLogsReturnType< > = Log[] /** - * @description Returns a collection of event logs. + * Returns a list of event logs matching the provided parameters. + * + * - Docs: https://viem.sh/docs/actions/public/getLogs.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/filters-and-logs/event-logs + * - JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) + * + * @param client - Client to use + * @param parameters - {@link GetLogsParameters} + * @returns A list of event logs. {@link GetLogsReturnType} + * + * @example + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getLogs } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const logs = await getLogs(client) */ export async function getLogs< TChain extends Chain | undefined, diff --git a/src/actions/public/getStorageAt.ts b/src/actions/public/getStorageAt.ts index 78fb7709b4..3e8807725b 100644 --- a/src/actions/public/getStorageAt.ts +++ b/src/actions/public/getStorageAt.ts @@ -18,6 +18,30 @@ export type GetStorageAtParameters = { export type GetStorageAtReturnType = Hex | undefined +/** + * Returns the value from a storage slot at a given address. + * + * - Docs: https://viem.sh/docs/contract/getStorageAt.html + * - JSON-RPC Methods: [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat) + * + * @param client - Client to use + * @param parameters - {@link GetStorageAtParameters} + * @returns The value of the storage slot. {@link GetStorageAtReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getStorageAt } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const code = await getStorageAt(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * slot: toHex(0), + * }) + */ export async function getStorageAt( client: PublicClient, { address, blockNumber, blockTag = 'latest', slot }: GetStorageAtParameters, diff --git a/src/actions/public/getTransaction.ts b/src/actions/public/getTransaction.ts index 3c67bf9c40..dcbf6fa5fe 100644 --- a/src/actions/public/getTransaction.ts +++ b/src/actions/public/getTransaction.ts @@ -53,7 +53,30 @@ export type GetTransactionParameters = export type GetTransactionReturnType = FormattedTransaction> -/** @description Returns information about a transaction given a hash or block identifier. */ +/** + * Returns information about a [Transaction](https://viem.sh/docs/glossary/terms#transaction) given a hash or block identifier. + * + * - Docs: https://viem.sh/docs/actions/public/getTransaction.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionByHash) + * + * @param client - Client to use + * @param parameters - {@link GetTransactionParameters} + * @returns The transaction information. {@link GetTransactionReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getTransaction } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transaction = await getTransaction(client, { + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ export async function getTransaction( client: PublicClient, { diff --git a/src/actions/public/getTransactionConfirmations.ts b/src/actions/public/getTransactionConfirmations.ts index 03877d8ff0..115f84739e 100644 --- a/src/actions/public/getTransactionConfirmations.ts +++ b/src/actions/public/getTransactionConfirmations.ts @@ -25,6 +25,30 @@ export type GetTransactionConfirmationsParameters< export type GetTransactionConfirmationsReturnType = bigint +/** + * Returns the number of blocks passed (confirmations) since the transaction was processed on a block. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionConfirmations.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionConfirmations`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionConfirmations) + * + * @param client - Client to use + * @param parameters - {@link GetTransactionConfirmationsParameters} + * @returns The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. {@link GetTransactionConfirmationsReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getTransactionConfirmations } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const confirmations = await getTransactionConfirmations(client, { + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ export async function getTransactionConfirmations< TChain extends Chain | undefined, >( diff --git a/src/actions/public/getTransactionCount.ts b/src/actions/public/getTransactionCount.ts index 9697d45568..b47525aea6 100644 --- a/src/actions/public/getTransactionCount.ts +++ b/src/actions/public/getTransactionCount.ts @@ -24,7 +24,27 @@ export type GetTransactionCountParameters = { export type GetTransactionCountReturnType = number /** - * @description Returns the number of transactions an account has broadcast / sent. + * Returns the number of [Transactions](https://viem.sh/docs/glossary/terms#transaction) an Account has broadcast / sent. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionCount.html + * - JSON-RPC Methods: [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount) + * + * @param client - Client to use + * @param parameters - {@link GetTransactionCountParameters} + * @returns The number of transactions an account has sent. {@link GetTransactionCountReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getTransactionCount } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionCount = await getTransactionCount(client, { + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) */ export async function getTransactionCount< TChain extends Chain | undefined, diff --git a/src/actions/public/getTransactionReceipt.ts b/src/actions/public/getTransactionReceipt.ts index 0c13fefcb3..d30d06435d 100644 --- a/src/actions/public/getTransactionReceipt.ts +++ b/src/actions/public/getTransactionReceipt.ts @@ -17,6 +17,30 @@ export type GetTransactionReceiptReturnType< TChain extends Chain | undefined = Chain | undefined, > = FormattedTransactionReceipt> +/** + * Returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt) given a [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionReceipt.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) + * + * @param client - Client to use + * @param parameters - {@link GetTransactionReceiptParameters} + * @returns The transaction receipt. {@link GetTransactionReceiptReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getTransactionReceipt } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionReceipt = await getTransactionReceipt(client, { + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ export async function getTransactionReceipt( client: PublicClient, { hash }: GetTransactionReceiptParameters, diff --git a/src/actions/public/multicall.ts b/src/actions/public/multicall.ts index 7b69302897..0f8b502bc7 100644 --- a/src/actions/public/multicall.ts +++ b/src/actions/public/multicall.ts @@ -38,6 +38,45 @@ export type MulticallReturnType< TAllowFailure extends boolean = true, > = MulticallResults +/** + * Similar to [`readContract`](https://viem.sh/docs/contract/readContract), but batches up multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall). + * + * - Docs: https://viem.sh/docs/contract/multicall.html + * + * @param client - Client to use + * @param parameters - {@link MulticallParameters} + * @returns An array of results with accompanying status. {@link MulticallReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { multicall } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const abi = parseAbi([ + * 'function balanceOf(address) view returns (uint256)', + * 'function totalSupply() view returns (uint256)', + * ]) + * const results = await multicall(client, { + * contracts: [ + * { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi, + * functionName: 'balanceOf', + * args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'], + * }, + * { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi, + * functionName: 'totalSupply', + * }, + * ], + * }) + * // [{ result: 424122n, status: 'success' }, { result: 1000000n, status: 'success' }] + */ export async function multicall< TChain extends Chain | undefined, TContracts extends ContractFunctionConfig[], diff --git a/src/actions/public/readContract.ts b/src/actions/public/readContract.ts index ca055d8031..265eb09c99 100644 --- a/src/actions/public/readContract.ts +++ b/src/actions/public/readContract.ts @@ -30,6 +30,38 @@ export type ReadContractReturnType< TFunctionName extends string = string, > = ContractFunctionResult +/** + * Calls a read-only function on a contract, and returns the response. + * + * - Docs: https://viem.sh/docs/contract/readContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/reading-contracts + * + * @remarks + * 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, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param client - Client to use + * @param parameters - {@link ReadContractParameters} + * @returns The response from the contract. Type is inferred. {@link ReadContractReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { readContract } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const results = await readContract(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function balanceOf(address) view returns (uint256)']), + * functionName: 'balanceOf', + * args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'], + * }) + * // 424122n + */ export async function readContract< TChain extends Chain | undefined, TAbi extends Abi | readonly unknown[], diff --git a/src/actions/public/simulateContract.ts b/src/actions/public/simulateContract.ts index 47ac1f2a54..99bad14cde 100644 --- a/src/actions/public/simulateContract.ts +++ b/src/actions/public/simulateContract.ts @@ -57,6 +57,38 @@ export type SimulateContractReturnType< } & ContractFunctionConfig } +/** + * Simulates/validates a contract interaction. This is useful for retrieving **return data** and **revert reasons** of contract write functions. + * + * - Docs: https://viem.sh/docs/contract/simulateContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/writing-to-contracts + * + * @remarks + * This function does not require gas to execute and _**does not**_ change the state of the blockchain. It is almost identical to [`readContract`](https://viem.sh/docs/contract/readContract), but also supports contract write functions. + * + * Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param client - Client to use + * @param parameters - {@link SimulateContractParameters} + * @returns The simulation result and write request. {@link SimulateContractReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { simulateContract } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const results = await simulateContract(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function mint(uint32) view returns (uint32)']), + * functionName: 'mint', + * args: ['69420'], + * account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) + */ export async function simulateContract< TChain extends Chain | undefined, TAbi extends Abi | readonly unknown[], diff --git a/src/actions/public/uninstallFilter.ts b/src/actions/public/uninstallFilter.ts index e0db98311a..7e3abcf55e 100644 --- a/src/actions/public/uninstallFilter.ts +++ b/src/actions/public/uninstallFilter.ts @@ -6,6 +6,31 @@ export type UninstallFilterParameters = { } export type UninstallFilterReturnType = boolean +/** + * Destroys a [`Filter`](https://viem.sh/docs/glossary/types.html#filter). + * + * - Docs: https://viem.sh/docs/actions/public/uninstallFilter.html + * - JSON-RPC Methods: [`eth_uninstallFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_uninstallFilter) + * + * @remarks + * Destroys a Filter that was created from one of the following Actions: + * - [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter) + * - [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter) + * - [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter) + * + * @param client - Client to use + * @param parameters - {@link UninstallFilterParameters} + * @returns A boolean indicating if the Filter was successfully uninstalled. {@link UninstallFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createPendingTransactionFilter, uninstallFilter } from 'viem/public' + * + * const filter = await createPendingTransactionFilter(client) + * const uninstalled = await uninstallFilter(client, { filter }) + * // true + */ export async function uninstallFilter< TTransport extends Transport, TChain extends Chain | undefined, diff --git a/src/actions/public/waitForTransactionReceipt.ts b/src/actions/public/waitForTransactionReceipt.ts index 57c17452e5..4db8c78113 100644 --- a/src/actions/public/waitForTransactionReceipt.ts +++ b/src/actions/public/waitForTransactionReceipt.ts @@ -30,17 +30,63 @@ export type WaitForTransactionReceiptReturnType< export type WaitForTransactionReceiptParameters< TChain extends Chain | undefined = Chain | undefined, > = { - /** The number of confirmations (blocks that have passed) to wait before resolving. */ + /** + * The number of confirmations (blocks that have passed) to wait before resolving. + * @default 1 + */ confirmations?: number /** The hash of the transaction. */ hash: Hash + /** Optional callback to emit if the transaction has been replaced. */ onReplaced?: (response: ReplacementReturnType) => void - /** Polling frequency (in ms). Defaults to the client's pollingInterval config. */ + /** + * Polling frequency (in ms). Defaults to the client's pollingInterval config. + * @default client.pollingInterval + */ pollingInterval?: number /** Optional timeout (in milliseconds) to wait before stopping polling. */ timeout?: number } +/** + * Waits for the [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) to be included on a [Block](https://viem.sh/docs/glossary/terms.html#block) (one confirmation), and then returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms.html#transaction-receipt). If the Transaction reverts, then the action will throw an error. + * + * - Docs: https://viem.sh/docs/actions/public/waitForTransactionReceipt.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/sending-transactions + * - JSON-RPC Methods: + * - Polls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) on each block until it has been processed. + * - If a Transaction has been replaced: + * - Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) and extracts the transactions + * - Checks if one of the Transactions is a replacement + * - If so, calls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt). + * + * @remarks + * The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions). + * + * Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce. + * + * There are 3 types of Transaction Replacement reasons: + * + * - `repriced`: The gas price has been modified (e.g. different `maxFeePerGas`) + * - `cancelled`: The Transaction has been cancelled (e.g. `value === 0n`) + * - `replaced`: The Transaction has been replaced (e.g. different `value` or `data`) + * + * @param client - Client to use + * @param parameters - {@link WaitForTransactionReceiptParameters} + * @returns The transaction receipt. {@link WaitForTransactionReceiptReturnType} + * + * @example + * import { createPublicClient, waitForTransactionReceipt, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionReceipt = await waitForTransactionReceipt(client, { + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ export async function waitForTransactionReceipt< TChain extends Chain | undefined, >( diff --git a/src/actions/public/watchBlockNumber.ts b/src/actions/public/watchBlockNumber.ts index a598c96dfc..83fee94ed6 100644 --- a/src/actions/public/watchBlockNumber.ts +++ b/src/actions/public/watchBlockNumber.ts @@ -42,7 +42,31 @@ export type WatchBlockNumberParameters< export type WatchBlockNumberReturnType = () => void -/** @description Watches and returns incoming block numbers. */ +/** + * Watches and returns incoming block numbers. + * + * - Docs: https://viem.sh/docs/actions/public/watchBlockNumber.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/watching-blocks + * - JSON-RPC Methods: + * - When `poll: true`, calls [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event. + * + * @param client - Client to use + * @param parameters - {@link WatchBlockNumberParameters} + * @returns A function that can be invoked to stop watching for new block numbers. {@link WatchBlockNumberReturnType} + * + * @example + * import { createPublicClient, watchBlockNumber, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await watchBlockNumber(client, { + * onBlockNumber: (blockNumber) => console.log(blockNumber), + * }) + */ export function watchBlockNumber< TChain extends Chain | undefined, TTransport extends Transport, diff --git a/src/actions/public/watchBlocks.ts b/src/actions/public/watchBlocks.ts index b6a57cf41a..267bfa2162 100644 --- a/src/actions/public/watchBlocks.ts +++ b/src/actions/public/watchBlocks.ts @@ -51,7 +51,29 @@ export type WatchBlocksParameters< export type WatchBlocksReturnType = () => void /** - * @description Watches and returns information for incoming blocks. + * Watches and returns information for incoming blocks. + * + * - Docs: https://viem.sh/docs/actions/public/watchBlocks.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/watching-blocks + * - JSON-RPC Methods: + * - When `poll: true`, calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getBlockByNumber) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event. + * + * @param client - Client to use + * @param parameters - {@link WatchBlocksParameters} + * @returns A function that can be invoked to stop watching for new block numbers. {@link WatchBlocksReturnType} + * + * @example + * import { createPublicClient, watchBlocks, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await watchBlocks(client, { + * onBlock: (block) => console.log(block), + * }) */ export function watchBlocks< TTransport extends Transport, diff --git a/src/actions/public/watchContractEvent.ts b/src/actions/public/watchContractEvent.ts index 6181b60a1d..df6e1dd7c7 100644 --- a/src/actions/public/watchContractEvent.ts +++ b/src/actions/public/watchContractEvent.ts @@ -54,6 +54,37 @@ export type WatchContractEventParameters< export type WatchContractEventReturnType = () => void +/** + * Watches and returns emitted contract event logs. + * + * - Docs: https://viem.sh/docs/contract/watchContractEvent.html + * + * @remarks + * This Action will batch up all the event logs found within the [`pollingInterval`](https://viem.sh/docs/contract/watchContractEvent.html#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/contract/watchContractEvent.html#onLogs). + * + * `watchContractEvent` will attempt to create an [Event Filter](https://viem.sh/docs/contract/createContractEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchContractEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead. + * + * @param client - Client to use + * @param parameters - {@link WatchContractEventParameters} + * @returns A function that can be invoked to stop watching for new event logs. {@link WatchContractEventReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { watchContractEvent } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = watchContractEvent(client, { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']), + * eventName: 'Transfer', + * args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' }, + * onLogs: (logs) => console.log(logs), + * }) + */ export function watchContractEvent< TChain extends Chain | undefined, TAbi extends Abi | readonly unknown[], diff --git a/src/actions/public/watchEvent.ts b/src/actions/public/watchEvent.ts index 89576a8390..d7f94c64cb 100644 --- a/src/actions/public/watchEvent.ts +++ b/src/actions/public/watchEvent.ts @@ -32,7 +32,10 @@ export type WatchEventParameters< > = { /** The address of the contract. */ address?: Address | Address[] - /** Whether or not the event logs should be batched on each invocation. */ + /** + * Whether or not the event logs should be batched on each invocation. + * @default true + */ batch?: boolean /** The callback to call when an error occurred when trying to get for a new block. */ onError?: (error: Error) => void @@ -53,6 +56,39 @@ export type WatchEventParameters< export type WatchEventReturnType = () => void +/** + * Watches and returns emitted [Event Logs](https://viem.sh/docs/glossary/terms#event-log). + * + * - Docs: https://viem.sh/docs/actions/public/watchEvent.html + * - JSON-RPC Methods: + * - **RPC Provider supports `eth_newFilter`:** + * - Calls [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) to create a filter (called on initialize). + * - On a polling interval, it will call [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges). + * - **RPC Provider does not support `eth_newFilter`:** + * - Calls [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) for each block between the polling interval. + * + * @remarks + * This Action will batch up all the Event Logs found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchEvent.html#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/actions/public/watchEvent.html#onLogs). + * + * `watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter.html) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead. + * + * @param client - Client to use + * @param parameters - {@link WatchEventParameters} + * @returns A function that can be invoked to stop watching for new Event Logs. {@link WatchEventReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { watchEvent } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = watchEvent(client, { + * onLogs: (logs) => console.log(logs), + * }) + */ export function watchEvent< TChain extends Chain | undefined, TAbiEvent extends AbiEvent | undefined, diff --git a/src/actions/public/watchPendingTransactions.ts b/src/actions/public/watchPendingTransactions.ts index e0762f373f..aecb26f225 100644 --- a/src/actions/public/watchPendingTransactions.ts +++ b/src/actions/public/watchPendingTransactions.ts @@ -15,9 +15,15 @@ export type OnTransactionsParameter = Hash[] export type OnTransactionsFn = (transactions: OnTransactionsParameter) => void type PollOptions = { - /** Whether or not the transaction hashes should be batched on each invocation. */ + /** + * Whether or not the transaction hashes should be batched on each invocation. + * @default true + */ batch?: boolean - /** Polling frequency (in ms). Defaults to Client's pollingInterval config. */ + /** + * Polling frequency (in ms). Defaults to Client's pollingInterval config. + * @default client.pollingInterval + */ pollingInterval?: number } @@ -32,17 +38,56 @@ export type WatchPendingTransactionsParameters< ? | { batch?: never - /** Whether or not the WebSocket Transport should poll the JSON-RPC, rather than using `eth_subscribe`. */ + /** + * Whether or not the WebSocket Transport should poll the JSON-RPC, rather than using `eth_subscribe`. + * @default false + */ poll?: false pollingInterval?: never } - | (PollOptions & { poll?: true }) + | (PollOptions & { + /** + * Whether or not the WebSocket Transport should poll the JSON-RPC, rather than using `eth_subscribe`. + * @default true + */ + poll?: true + }) : PollOptions & { poll?: true }) export type WatchPendingTransactionsReturnType = () => void +/** + * Watches and returns pending transaction hashes. + * + * - Docs: https://viem.sh/docs/actions/public/watchPendingTransactions.html + * - JSON-RPC Methods: + * - When `poll: true` + * - Calls [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) to initialize the filter. + * - Calls [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getFilterChanges) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newPendingTransactions"` event. + * + * @remarks + * This Action will batch up all the pending transactions found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchPendingTransactions.html#pollinginterval-optional), and invoke them via [`onTransactions`](https://viem.sh/docs/actions/public/watchPendingTransactions.html#ontransactions). + * + * @param client - Client to use + * @param parameters - {@link WatchPendingTransactionsParameters} + * @returns A function that can be invoked to stop watching for new pending transaction hashes. {@link WatchPendingTransactionsReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { watchPendingTransactions } from 'viem/public' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await watchPendingTransactions(client, { + * onTransactions: (hashes) => console.log(hashes), + * }) + */ export function watchPendingTransactions< TTransport extends Transport, TChain extends Chain | undefined, diff --git a/src/actions/wallet/deployContract.ts b/src/actions/wallet/deployContract.ts index 34987276f7..a5551210f0 100644 --- a/src/actions/wallet/deployContract.ts +++ b/src/actions/wallet/deployContract.ts @@ -30,6 +30,33 @@ export type DeployContractParameters< export type DeployContractReturnType = SendTransactionReturnType +/** + * Deploys a contract to the network, given bytecode and constructor arguments. + * + * - Docs: https://viem.sh/docs/contract/deployContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/deploying-contracts + * + * @param client - Client to use + * @param parameters - {@link DeployContractParameters} + * @returns The [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash. {@link DeployContractReturnType} + * + * @example + * import { createWalletClient, http } from 'viem' + * import { privateKeyToAccount } from 'viem/accounts' + * import { mainnet } from 'viem/chains' + * import { deployContract } from 'viem/contract' + * + * const client = createWalletClient({ + * account = privateKeyToAccount('0x…'), + * chain: mainnet, + * transport: http(), + * }) + * const hash = await deployContract(client, { + * abi: [], + * account: '0x…, + * bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', + * }) + */ export function deployContract< TAbi extends Abi | readonly unknown[], TChain extends Chain | undefined, diff --git a/src/clients/decorators/public.ts b/src/clients/decorators/public.ts index 0a857cf309..78790ac710 100644 --- a/src/clients/decorators/public.ts +++ b/src/clients/decorators/public.ts @@ -130,8 +130,70 @@ export type PublicActions< TTransport extends Transport = Transport, TChain extends Chain | undefined = Chain | undefined, > = { - call: (args: CallParameters) => Promise + /** + * Executes a new message call immediately without submitting a transaction to the network. + * + * - Docs: https://viem.sh/docs/actions/public/call.html + * - JSON-RPC Methods: [`eth_call`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call) + * + * @param parameters - {@link CallParameters} + * @returns The call data. {@link CallReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const data = await client.call({ + * account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', + * data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', + * to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + * }) + */ + call: (parameters: CallParameters) => Promise + /** + * Creates a Filter to listen for new block hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createBlockFilter.html + * - JSON-RPC Methods: [`eth_newBlockFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newBlockFilter) + * + * @returns Filter. {@link CreateBlockFilterReturnType} + * + * @example + * import { createPublicClient, createBlockFilter, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await createBlockFilter(client) + * // { id: "0x345a6572337856574a76364e457a4366", type: 'block' } + */ createBlockFilter: () => Promise + /** + * Creates a Filter to retrieve event logs that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges) or [`getFilterLogs`](https://viem.sh/docs/actions/public/getFilterLogs). + * + * - Docs: https://viem.sh/docs/contract/createContractEventFilter.html + * + * @param parameters - {@link CreateContractEventFilterParameters} + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateContractEventFilterReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createContractEventFilter({ + * abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']), + * }) + */ createContractEventFilter: < TAbi extends Abi | readonly unknown[], TEventName extends string | undefined, @@ -139,6 +201,27 @@ export type PublicActions< >( args: CreateContractEventFilterParameters, ) => Promise> + /** + * Creates a [`Filter`](https://viem.sh/docs/glossary/types.html#filter) to listen for new events that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createEventFilter.html + * - JSON-RPC Methods: [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) + * + * @param parameters - {@link CreateEventFilterParameters} + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateEventFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createEventFilter({ + * address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2', + * }) + */ createEventFilter: < TAbiEvent extends AbiEvent | undefined, TAbi extends Abi | readonly unknown[], @@ -147,7 +230,52 @@ export type PublicActions< >( args?: CreateEventFilterParameters, ) => Promise> + /** + * Creates a Filter to listen for new pending transaction hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges). + * + * - Docs: https://viem.sh/docs/actions/public/createPendingTransactionFilter.html + * - JSON-RPC Methods: [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) + * + * @returns [`Filter`](https://viem.sh/docs/glossary/types.html#filter). {@link CreateBlockFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createPendingTransactionFilter() + * // { id: "0x345a6572337856574a76364e457a4366", type: 'transaction' } + */ createPendingTransactionFilter: () => Promise + /** + * Estimates the gas required to successfully execute a contract write function call. + * + * - Docs: https://viem.sh/docs/contract/estimateContractGas.html + * + * @remarks + * Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`estimateGas` action](https://viem.sh/docs/actions/public/estimateGas) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param parameters - {@link EstimateContractGasParameters} + * @returns The gas estimate (in wei). {@link EstimateContractGasReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gas = await client.estimateContractGas({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function mint() public']), + * functionName: 'mint', + * account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', + * }) + */ estimateContractGas: < TChain extends Chain | undefined, TAbi extends Abi | readonly unknown[], @@ -155,33 +283,432 @@ export type PublicActions< >( args: EstimateContractGasParameters, ) => Promise + /** + * Estimates the gas necessary to complete a transaction without submitting it to the network. + * + * - Docs: https://viem.sh/docs/actions/public/estimateGas.html + * - JSON-RPC Methods: [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas) + * + * @param parameters - {@link EstimateGasParameters} + * @returns The gas estimate (in wei). {@link EstimateGasReturnType} + * + * @example + * import { createPublicClient, http, parseEther } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gasEstimate = await client.estimateGas({ + * account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + * value: parseEther('1'), + * }) + */ estimateGas: ( args: EstimateGasParameters, ) => Promise + /** + * Returns the balance of an address in wei. + * + * - Docs: https://viem.sh/docs/actions/public/getBalance.html + * - JSON-RPC Methods: [`eth_getBalance`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance) + * + * @remarks + * You can convert the balance to ether units with [`formatEther`](https://viem.sh/docs/utilities/formatEther.html). + * + * ```ts + * const balance = await getBalance(client, { + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * blockTag: 'safe' + * }) + * const balanceAsEther = formatEther(balance) + * // "6.942" + * ``` + * + * @param parameters - {@link GetBalanceParameters} + * @returns The balance of the address in wei. {@link GetBalanceReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const balance = await client.getBalance({ + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) + * // 10000000000000000000000n (wei) + */ getBalance: (args: GetBalanceParameters) => Promise + /** + * Returns information about a block at a block number, hash, or tag. + * + * - Docs: https://viem.sh/docs/actions/public/getBlock.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/fetching-blocks + * - JSON-RPC Methods: + * - Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) for `blockNumber` & `blockTag`. + * - Calls [`eth_getBlockByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash) for `blockHash`. + * + * @param parameters - {@link GetBlockParameters} + * @returns Information about the block. {@link GetBlockReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const block = await client.getBlock() + */ getBlock: (args?: GetBlockParameters) => Promise> + /** + * Returns the number of the most recent block seen. + * + * - Docs: https://viem.sh/docs/actions/public/getBlockNumber.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/fetching-blocks + * - JSON-RPC Methods: [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) + * + * @param parameters - {@link GetBlockNumberParameters} + * @returns The number of the block. {@link GetBlockNumberReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const blockNumber = await client.getBlockNumber() + * // 69420n + */ getBlockNumber: ( args?: GetBlockNumberParameters, ) => Promise + /** + * Returns the number of Transactions at a block number, hash, or tag. + * + * - Docs: https://viem.sh/docs/actions/public/getBlockTransactionCount.html + * - JSON-RPC Methods: + * - Calls [`eth_getBlockTransactionCountByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) for `blockNumber` & `blockTag`. + * - Calls [`eth_getBlockTransactionCountByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) for `blockHash`. + * + * @param parameters - {@link GetBlockTransactionCountParameters} + * @returns The block transaction count. {@link GetBlockTransactionCountReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const count = await client.getBlockTransactionCount() + */ getBlockTransactionCount: ( args?: GetBlockTransactionCountParameters, ) => Promise + /** + * Retrieves the bytecode at an address. + * + * - Docs: https://viem.sh/docs/contract/getBytecode.html + * - JSON-RPC Methods: [`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode) + * + * @param parameters - {@link GetBytecodeParameters} + * @returns The contract's bytecode. {@link GetBytecodeReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const code = await client.getBytecode({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * }) + */ getBytecode: (args: GetBytecodeParameters) => Promise + /** + * Returns the chain ID associated with the current network. + * + * - Docs: https://viem.sh/docs/actions/public/getChainId.html + * - JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid) + * + * @returns The current chain ID. {@link GetChainIdReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const chainId = await client.getChainId() + * // 1 + */ getChainId: () => Promise + /** + * Gets address for ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsAddress.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param parameters - {@link GetEnsAddressParameters} + * @returns Address for ENS name or `null` if not found. {@link GetEnsAddressReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensAddress = await client.getEnsAddress({ + * name: normalize('wagmi-dev.eth'), + * }) + * // '0xd2135CfB216b74109775236E36d4b433F1DF507B' + */ getEnsAddress: ( args: GetEnsAddressParameters, ) => Promise + /** + * Gets the avatar of an ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsAvatar.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls [`getEnsText`](https://viem.sh/docs/ens/actions/getEnsText.html) with `key` set to `'avatar'`. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param parameters - {@link GetEnsAvatarParameters} + * @returns Avatar URI or `null` if not found. {@link GetEnsAvatarReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensAvatar = await client.getEnsAvatar({ + * name: normalize('wagmi-dev.eth'), + * }) + * // 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio' + */ getEnsAvatar: ( args: GetEnsAvatarParameters, ) => Promise + /** + * Gets primary name for specified address. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsName.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `reverse(bytes)` on ENS Universal Resolver Contract to "reverse resolve" the address to the primary ENS name. + * + * @param parameters - {@link GetEnsNameParameters} + * @returns Name or `null` if not found. {@link GetEnsNameReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const ensName = await client.getEnsName({ + * address: '0xd2135CfB216b74109775236E36d4b433F1DF507B', + * }) + * // 'wagmi-dev.eth' + */ getEnsName: (args: GetEnsNameParameters) => Promise + /** + * Gets resolver for ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsResolver.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `findResolver(bytes)` on ENS Universal Resolver Contract to retrieve the resolver of an ENS name. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param parameters - {@link GetEnsResolverParameters} + * @returns Address for ENS resolver. {@link GetEnsResolverReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const resolverAddress = await client.getEnsResolver({ + * name: normalize('wagmi-dev.eth'), + * }) + * // '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41' + */ getEnsResolver: ( args: GetEnsResolverParameters, ) => Promise + /** + * Gets a text record for specified ENS name. + * + * - Docs: https://viem.sh/docs/ens/actions/getEnsResolver.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens + * + * @remarks + * Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract. + * + * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this. + * + * @param parameters - {@link GetEnsTextParameters} + * @returns Address for ENS resolver. {@link GetEnsTextReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { normalize } from 'viem/ens' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const twitterRecord = await client.getEnsText({ + * name: normalize('wagmi-dev.eth'), + * key: 'com.twitter', + * }) + * // 'wagmi_sh' + */ getEnsText: (args: GetEnsTextParameters) => Promise + /** + * Returns a collection of historical gas information. + * + * - Docs: https://viem.sh/docs/actions/public/getFeeHistory.html + * - JSON-RPC Methods: [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory) + * + * @param parameters - {@link GetFeeHistoryParameters} + * @returns The gas estimate (in wei). {@link GetFeeHistoryReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const feeHistory = await client.getFeeHistory({ + * blockCount: 4, + * rewardPercentiles: [25, 75], + * }) + */ getFeeHistory: ( args: GetFeeHistoryParameters, ) => Promise + /** + * Returns a list of logs or hashes based on a [Filter](/docs/glossary/terms#filter) since the last time it was called. + * + * - Docs: https://viem.sh/docs/actions/public/getFilterChanges.html + * - JSON-RPC Methods: [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges) + * + * @remarks + * A Filter can be created from the following actions: + * + * - [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter) + * - [`createContractEventFilter`](https://viem.sh/docs/contract/createContractEventFilter) + * - [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter) + * - [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter) + * + * Depending on the type of filter, the return value will be different: + * + * - If the filter was created with `createContractEventFilter` or `createEventFilter`, it returns a list of logs. + * - If the filter was created with `createPendingTransactionFilter`, it returns a list of transaction hashes. + * - If the filter was created with `createBlockFilter`, it returns a list of block hashes. + * + * @param parameters - {@link GetFilterChangesParameters} + * @returns Logs or hashes. {@link GetFilterChangesReturnType} + * + * @example + * // Blocks + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createBlockFilter() + * const hashes = await client.getFilterChanges({ filter }) + * + * @example + * // Contract Events + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createContractEventFilter({ + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']), + * eventName: 'Transfer', + * }) + * const logs = await client.getFilterChanges({ filter }) + * + * @example + * // Raw Events + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createEventFilter({ + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'), + * }) + * const logs = await client.getFilterChanges({ filter }) + * + * @example + * // Transactions + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createPendingTransactionFilter() + * const hashes = await client.getFilterChanges({ filter }) + */ getFilterChanges: < TFilterType extends FilterType, TAbiEvent extends AbiEvent | undefined, @@ -192,6 +719,32 @@ export type PublicActions< ) => Promise< GetFilterChangesReturnType > + /** + * Returns a list of event logs since the filter was created. + * + * - Docs: https://viem.sh/docs/actions/public/getFilterLogs.html + * - JSON-RPC Methods: [`eth_getFilterLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterlogs) + * + * @remarks + * `getFilterLogs` is only compatible with **event filters**. + * + * @param parameters - {@link GetFilterLogsParameters} + * @returns A list of event logs. {@link GetFilterLogsReturnType} + * + * @example + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const filter = await client.createEventFilter({ + * address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + * event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'), + * }) + * const logs = await client.getFilterLogs({ filter }) + */ getFilterLogs: < TAbiEvent extends AbiEvent | undefined, TAbi extends Abi | readonly unknown[], @@ -199,37 +752,283 @@ export type PublicActions< >( args: GetFilterLogsParameters, ) => Promise> + /** + * Returns the current price of gas (in wei). + * + * - Docs: https://viem.sh/docs/actions/public/getGasPrice.html + * - JSON-RPC Methods: [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) + * + * @returns The gas price (in wei). {@link GetGasPriceReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const gasPrice = await client.getGasPrice() + */ getGasPrice: () => Promise + /** + * Returns a list of event logs matching the provided parameters. + * + * - Docs: https://viem.sh/docs/actions/public/getLogs.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/filters-and-logs/event-logs + * - JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) + * + * @param parameters - {@link GetLogsParameters} + * @returns A list of event logs. {@link GetLogsReturnType} + * + * @example + * import { createPublicClient, http, parseAbiItem } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const logs = await client.getLogs() + */ getLogs: ( args?: GetLogsParameters, ) => Promise> + /** + * Returns the value from a storage slot at a given address. + * + * - Docs: https://viem.sh/docs/contract/getStorageAt.html + * - JSON-RPC Methods: [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat) + * + * @param parameters - {@link GetStorageAtParameters} + * @returns The value of the storage slot. {@link GetStorageAtReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { getStorageAt } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const code = await client.getStorageAt({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * slot: toHex(0), + * }) + */ getStorageAt: ( args: GetStorageAtParameters, ) => Promise + /** + * Returns information about a [Transaction](https://viem.sh/docs/glossary/terms#transaction) given a hash or block identifier. + * + * - Docs: https://viem.sh/docs/actions/public/getTransaction.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionByHash) + * + * @param parameters - {@link GetTransactionParameters} + * @returns The transaction information. {@link GetTransactionReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transaction = await client.getTransaction({ + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ getTransaction: ( args: GetTransactionParameters, ) => Promise> + /** + * Returns the number of blocks passed (confirmations) since the transaction was processed on a block. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionConfirmations.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionConfirmations`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionConfirmations) + * + * @param parameters - {@link GetTransactionConfirmationsParameters} + * @returns The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. {@link GetTransactionConfirmationsReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const confirmations = await client.getTransactionConfirmations({ + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ getTransactionConfirmations: ( args: GetTransactionConfirmationsParameters, ) => Promise + /** + * Returns the number of [Transactions](https://viem.sh/docs/glossary/terms#transaction) an Account has broadcast / sent. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionCount.html + * - JSON-RPC Methods: [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount) + * + * @param parameters - {@link GetTransactionCountParameters} + * @returns The number of transactions an account has sent. {@link GetTransactionCountReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionCount = await client.getTransactionCount({ + * address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) + */ getTransactionCount: ( args: GetTransactionCountParameters, ) => Promise + /** + * Returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt) given a [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash. + * + * - Docs: https://viem.sh/docs/actions/public/getTransactionReceipt.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions + * - JSON-RPC Methods: [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) + * + * @param parameters - {@link GetTransactionReceiptParameters} + * @returns The transaction receipt. {@link GetTransactionReceiptReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionReceipt = await client.getTransactionReceipt({ + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ getTransactionReceipt: ( args: GetTransactionReceiptParameters, ) => Promise> + /** + * Similar to [`readContract`](https://viem.sh/docs/contract/readContract), but batches up multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall). + * + * - Docs: https://viem.sh/docs/contract/multicall.html + * + * @param parameters - {@link MulticallParameters} + * @returns An array of results with accompanying status. {@link MulticallReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const abi = parseAbi([ + * 'function balanceOf(address) view returns (uint256)', + * 'function totalSupply() view returns (uint256)', + * ]) + * const results = await client.multicall({ + * contracts: [ + * { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi, + * functionName: 'balanceOf', + * args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'], + * }, + * { + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi, + * functionName: 'totalSupply', + * }, + * ], + * }) + * // [{ result: 424122n, status: 'success' }, { result: 1000000n, status: 'success' }] + */ multicall: < TContracts extends ContractFunctionConfig[], TAllowFailure extends boolean = true, >( args: MulticallParameters, ) => Promise> + /** + * Calls a read-only function on a contract, and returns the response. + * + * - Docs: https://viem.sh/docs/contract/readContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/reading-contracts + * + * @remarks + * 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, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param parameters - {@link ReadContractParameters} + * @returns The response from the contract. Type is inferred. {@link ReadContractReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * import { readContract } from 'viem/contract' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const results = await client.readContract({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function balanceOf(address) view returns (uint256)']), + * functionName: 'balanceOf', + * args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'], + * }) + * // 424122n + */ readContract: < TAbi extends Abi | readonly unknown[], TFunctionName extends string, >( args: ReadContractParameters, ) => Promise> + /** + * Simulates/validates a contract interaction. This is useful for retrieving **return data** and **revert reasons** of contract write functions. + * + * - Docs: https://viem.sh/docs/contract/simulateContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/writing-to-contracts + * + * @remarks + * This function does not require gas to execute and _**does not**_ change the state of the blockchain. It is almost identical to [`readContract`](https://viem.sh/docs/contract/readContract), but also supports contract write functions. + * + * Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData). + * + * @param parameters - {@link SimulateContractParameters} + * @returns The simulation result and write request. {@link SimulateContractReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const results = await client.simulateContract({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['function mint(uint32) view returns (uint32)']), + * functionName: 'mint', + * args: ['69420'], + * account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', + * }) + */ simulateContract: < TAbi extends Abi | readonly unknown[] = Abi, TFunctionName extends string = any, @@ -244,27 +1043,223 @@ export type PublicActions< ) => Promise< SimulateContractReturnType > + /** + * Destroys a Filter that was created from one of the following Actions: + * + * - [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter) + * - [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter) + * - [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter) + * + * - Docs: https://viem.sh/docs/actions/public/uninstallFilter.html + * - JSON-RPC Methods: [`eth_uninstallFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_uninstallFilter) + * + * @param parameters - {@link UninstallFilterParameters} + * @returns A boolean indicating if the Filter was successfully uninstalled. {@link UninstallFilterReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * import { createPendingTransactionFilter, uninstallFilter } from 'viem/public' + * + * const filter = await client.createPendingTransactionFilter() + * const uninstalled = await client.uninstallFilter({ filter }) + * // true + */ uninstallFilter: ( args: UninstallFilterParameters, ) => Promise + /** + * Waits for the [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) to be included on a [Block](https://viem.sh/docs/glossary/terms.html#block) (one confirmation), and then returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms.html#transaction-receipt). If the Transaction reverts, then the action will throw an error. + * + * - Docs: https://viem.sh/docs/actions/public/waitForTransactionReceipt.html + * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/sending-transactions + * - JSON-RPC Methods: + * - Polls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) on each block until it has been processed. + * - If a Transaction has been replaced: + * - Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) and extracts the transactions + * - Checks if one of the Transactions is a replacement + * - If so, calls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt). + * + * @remarks + * The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions). + * + * Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce. + * + * There are 3 types of Transaction Replacement reasons: + * + * - `repriced`: The gas price has been modified (e.g. different `maxFeePerGas`) + * - `cancelled`: The Transaction has been cancelled (e.g. `value === 0n`) + * - `replaced`: The Transaction has been replaced (e.g. different `value` or `data`) + * + * @param parameters - {@link WaitForTransactionReceiptParameters} + * @returns The transaction receipt. {@link WaitForTransactionReceiptReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const transactionReceipt = await client.waitForTransactionReceipt({ + * hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', + * }) + */ waitForTransactionReceipt: ( args: WaitForTransactionReceiptParameters, ) => Promise> + /** + * Watches and returns incoming block numbers. + * + * - Docs: https://viem.sh/docs/actions/public/watchBlockNumber.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/watching-blocks + * - JSON-RPC Methods: + * - When `poll: true`, calls [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event. + * + * @param parameters - {@link WatchBlockNumberParameters} + * @returns A function that can be invoked to stop watching for new block numbers. {@link WatchBlockNumberReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await client.watchBlockNumber({ + * onBlockNumber: (blockNumber) => console.log(blockNumber), + * }) + */ watchBlockNumber: ( args: WatchBlockNumberParameters, ) => WatchBlockNumberReturnType + /** + * Watches and returns information for incoming blocks. + * + * - Docs: https://viem.sh/docs/actions/public/watchBlocks.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/blocks/watching-blocks + * - JSON-RPC Methods: + * - When `poll: true`, calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getBlockByNumber) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event. + * + * @param parameters - {@link WatchBlocksParameters} + * @returns A function that can be invoked to stop watching for new block numbers. {@link WatchBlocksReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await client.watchBlocks({ + * onBlock: (block) => console.log(block), + * }) + */ watchBlocks: ( args: WatchBlocksParameters, ) => WatchBlocksReturnType + /** + * Watches and returns emitted contract event logs. + * + * - Docs: https://viem.sh/docs/contract/watchContractEvent.html + * + * @remarks + * This Action will batch up all the event logs found within the [`pollingInterval`](https://viem.sh/docs/contract/watchContractEvent.html#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/contract/watchContractEvent.html#onLogs). + * + * `watchContractEvent` will attempt to create an [Event Filter](https://viem.sh/docs/contract/createContractEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchContractEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead. + * + * @param parameters - {@link WatchContractEventParameters} + * @returns A function that can be invoked to stop watching for new event logs. {@link WatchContractEventReturnType} + * + * @example + * import { createPublicClient, http, parseAbi } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = client.watchContractEvent({ + * address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', + * abi: parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']), + * eventName: 'Transfer', + * args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' }, + * onLogs: (logs) => console.log(logs), + * }) + */ watchContractEvent: < TAbi extends Abi | readonly unknown[], TEventName extends string, >( args: WatchContractEventParameters, ) => WatchContractEventReturnType + /** + * Watches and returns emitted [Event Logs](https://viem.sh/docs/glossary/terms#event-log). + * + * - Docs: https://viem.sh/docs/actions/public/watchEvent.html + * - JSON-RPC Methods: + * - **RPC Provider supports `eth_newFilter`:** + * - Calls [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) to create a filter (called on initialize). + * - On a polling interval, it will call [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges). + * - **RPC Provider does not support `eth_newFilter`:** + * - Calls [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) for each block between the polling interval. + * + * @remarks + * This Action will batch up all the Event Logs found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchEvent.html#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/actions/public/watchEvent.html#onLogs). + * + * `watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter.html) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead. + * + * @param parameters - {@link WatchEventParameters} + * @returns A function that can be invoked to stop watching for new Event Logs. {@link WatchEventReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = client.watchEvent({ + * onLogs: (logs) => console.log(logs), + * }) + */ watchEvent: ( args: WatchEventParameters, ) => WatchEventReturnType + /** + * Watches and returns pending transaction hashes. + * + * - Docs: https://viem.sh/docs/actions/public/watchPendingTransactions.html + * - JSON-RPC Methods: + * - When `poll: true` + * - Calls [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) to initialize the filter. + * - Calls [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getFilterChanges) on a polling interval. + * - When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newPendingTransactions"` event. + * + * @remarks + * This Action will batch up all the pending transactions found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchPendingTransactions.html#pollinginterval-optional), and invoke them via [`onTransactions`](https://viem.sh/docs/actions/public/watchPendingTransactions.html#ontransactions). + * + * @param parameters - {@link WatchPendingTransactionsParameters} + * @returns A function that can be invoked to stop watching for new pending transaction hashes. {@link WatchPendingTransactionsReturnType} + * + * @example + * import { createPublicClient, http } from 'viem' + * import { mainnet } from 'viem/chains' + * + * const client = createPublicClient({ + * chain: mainnet, + * transport: http(), + * }) + * const unwatch = await client.watchPendingTransactions({ + * onTransactions: (hashes) => console.log(hashes), + * }) + */ watchPendingTransactions: ( args: WatchPendingTransactionsParameters, ) => WatchPendingTransactionsReturnType diff --git a/src/clients/decorators/wallet.ts b/src/clients/decorators/wallet.ts index 0989086b13..0c610c2774 100644 --- a/src/clients/decorators/wallet.ts +++ b/src/clients/decorators/wallet.ts @@ -45,6 +45,31 @@ export type WalletActions< TAccount extends Account | undefined = Account | undefined, > = { addChain: (args: AddChainParameters) => Promise + /** + * Deploys a contract to the network, given bytecode and constructor arguments. + * + * - Docs: https://viem.sh/docs/contract/deployContract.html + * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/deploying-contracts + * + * @param parameters - {@link DeployContractParameters} + * @returns The [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash. {@link DeployContractReturnType} + * + * @example + * import { createWalletClient, http } from 'viem' + * import { privateKeyToAccount } from 'viem/accounts' + * import { mainnet } from 'viem/chains' + * + * const client = createWalletClient({ + * account = privateKeyToAccount('0x…'), + * chain: mainnet, + * transport: http(), + * }) + * const hash = await client.deployContract({ + * abi: [], + * account: '0x…, + * bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', + * }) + */ deployContract: < TAbi extends Abi | readonly unknown[], TChainOverride extends Chain | undefined,