viem 0.3.0-tsc-nodenext-2.20230407T050527 → 0.4.0-main.20230412T020839

package/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<BlockFormatter<TChain>>
 
+/**
+ * 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,

package/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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,

package/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,
 >(

package/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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   { address, blockNumber, blockTag = 'latest' }: GetBytecodeParameters,

package/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,

package/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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,

package/src/actions/public/getFilterChanges.ts

@@ -30,6 +30,89 @@ export type GetFilterChangesReturnType<
   ? Log<bigint, number, TAbiEvent, TAbi, TEventName>[]
   : 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,
@@ -38,12 +121,12 @@ export async function getFilterChanges<
   TAbi extends Abi | readonly unknown[],
   TEventName extends string | undefined,
 >(
-  client: PublicClient<TTransport, TChain>,
+  _client: PublicClient<TTransport, TChain>,
   {
     filter,
   }: GetFilterChangesParameters<TFilterType, TAbiEvent, TAbi, TEventName>,
 ) {
-  const logs = await client.request({
+  const logs = await filter.request({
     method: 'eth_getFilterChanges',
     params: [filter.id],
   })

package/src/actions/public/getFilterLogs.ts

@@ -23,16 +23,44 @@ export type GetFilterLogsReturnType<
   TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
 > = Log<bigint, number, TAbiEvent, TAbi, TEventName>[]
 
+/**
+ * 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,
   TAbi extends Abi | readonly unknown[],
   TEventName extends string | undefined,
 >(
-  client: PublicClient<Transport, TChain>,
+  _client: PublicClient<Transport, TChain>,
   { filter }: GetFilterLogsParameters<TAbiEvent, TAbi, TEventName>,
 ): Promise<GetFilterLogsReturnType<TAbiEvent, TAbi, TEventName>> {
-  const logs = await client.request({
+  const logs = await filter.request({
     method: 'eth_getFilterLogs',
     params: [filter.id],
   })

package/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,

package/src/actions/public/getLogs.ts

@@ -58,7 +58,26 @@ export type GetLogsReturnType<
 > = Log<bigint, number, TAbiEvent, [TAbiEvent], TEventName>[]
 
 /**
- * @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,

package/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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   { address, blockNumber, blockTag = 'latest', slot }: GetStorageAtParameters,

package/src/actions/public/getTransaction.ts

@@ -53,7 +53,30 @@ export type GetTransactionParameters =
 export type GetTransactionReturnType<TChain extends Chain | undefined = Chain> =
   FormattedTransaction<TransactionFormatter<TChain>>
 
-/** @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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

package/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,
 >(

package/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,

package/src/actions/public/getTransactionReceipt.ts

@@ -17,6 +17,30 @@ export type GetTransactionReceiptReturnType<
   TChain extends Chain | undefined = Chain | undefined,
 > = FormattedTransactionReceipt<TransactionReceiptFormatter<TChain>>
 
+/**
+ * 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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   { hash }: GetTransactionReceiptParameters,

package/src/actions/public/multicall.ts

@@ -38,6 +38,45 @@ export type MulticallReturnType<
   TAllowFailure extends boolean = true,
 > = MulticallResults<TContracts, TAllowFailure>
 
+/**
+ * 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[],

package/src/actions/public/readContract.ts

@@ -30,6 +30,38 @@ export type ReadContractReturnType<
   TFunctionName extends string = string,
 > = ContractFunctionResult<TAbi, TFunctionName>
 
+/**
+ * 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[],