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

package/src/actions/ens/getEnsAddress.ts

@@ -17,9 +17,9 @@ import type { ReadContractParameters } from '../public/index.js'
 
 export type GetEnsAddressParameters = Prettify<
   Pick<ReadContractParameters, 'blockNumber' | 'blockTag'> & {
-    /** 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<TChain extends Chain | undefined,>(
   client: PublicClient<Transport, TChain>,

package/src/actions/ens/getEnsAvatar.ts

@@ -6,7 +6,7 @@ import type { GetEnsTextParameters } from './getEnsText.js'
 
 export type GetEnsAvatarParameters = Prettify<
   Omit<GetEnsTextParameters, 'key'> & {
-    /** 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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,

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

package/src/actions/ens/getEnsResolver.ts

@@ -7,9 +7,9 @@ import type { ReadContractParameters } from '../public/index.js'
 
 export type GetEnsResolverParameters = Prettify<
   Pick<ReadContractParameters, 'blockNumber' | 'blockTag'> & {
-    /** 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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,

package/src/actions/ens/getEnsText.ts

@@ -13,9 +13,9 @@ import type { ReadContractParameters } from '../public/index.js'
 
 export type GetEnsTextParameters = Prettify<
   Pick<ReadContractParameters, 'blockNumber' | 'blockTag'> & {
-    /** 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',
  * })

package/src/actions/getContract.ts

@@ -61,9 +61,25 @@ export type GetContractParameters<
   abi: Narrow<TAbi>
   /** 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,

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

package/src/actions/public/createBlockFilter.ts

@@ -1,13 +1,38 @@
 import type { PublicClient, Transport } from '../../clients/index.js'
 import type { Chain, Filter } from '../../types/index.js'
+import { createFilterRequestScope } from '../../utils/filters/createFilterRequestScope.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<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
 ): Promise<CreateBlockFilterReturnType> {
+  const getRequest = createFilterRequestScope(client, {
+    method: 'eth_newBlockFilter',
+  })
   const id = await client.request({
     method: 'eth_newBlockFilter',
   })
-  return { id, type: 'block' }
+  return { id, request: getRequest(id), type: 'block' }
 }

package/src/actions/public/createContractEventFilter.ts

@@ -12,6 +12,7 @@ import type {
 } from '../../types/index.js'
 import { encodeEventTopics, numberToHex } from '../../utils/index.js'
 import type { EncodeEventTopicsParameters } from '../../utils/index.js'
+import { createFilterRequestScope } from '../../utils/filters/createFilterRequestScope.js'
 
 export type CreateContractEventFilterParameters<
   TAbi extends Abi | readonly unknown[] = Abi,
@@ -48,6 +49,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[],
@@ -64,6 +87,10 @@ export async function createContractEventFilter<
     toBlock,
   }: CreateContractEventFilterParameters<TAbi, TEventName, TArgs>,
 ): Promise<CreateContractEventFilterReturnType<TAbi, TEventName, TArgs>> {
+  const getRequest = createFilterRequestScope(client, {
+    method: 'eth_newFilter',
+  })
+
   const topics = eventName
     ? encodeEventTopics({
         abi,
@@ -88,6 +115,7 @@ export async function createContractEventFilter<
     args,
     eventName,
     id,
+    request: getRequest(id),
     type: 'event',
   } as unknown as CreateContractEventFilterReturnType<TAbi, TEventName, TArgs>
 }

package/src/actions/public/createEventFilter.ts

@@ -14,6 +14,7 @@ import type {
 } from '../../types/index.js'
 import { encodeEventTopics, numberToHex } from '../../utils/index.js'
 import type { EncodeEventTopicsParameters } from '../../utils/index.js'
+import { createFilterRequestScope } from '../../utils/filters/createFilterRequestScope.js'
 
 export type CreateEventFilterParameters<
   TAbiEvent extends AbiEvent | undefined = undefined,
@@ -59,6 +60,29 @@ export type CreateEventFilterReturnType<
     | undefined = undefined,
 > = Prettify<Filter<'event', TAbi, TEventName, TArgs>>
 
+/**
+ * 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,
@@ -82,6 +106,10 @@ export async function createEventFilter<
     _Args
   > = {} as any,
 ): Promise<CreateEventFilterReturnType<TAbiEvent, _Abi, _EventName, _Args>> {
+  const getRequest = createFilterRequestScope(client, {
+    method: 'eth_newFilter',
+  })
+
   let topics: LogTopic[] = []
   if (event)
     topics = encodeEventTopics({
@@ -102,11 +130,13 @@ export async function createEventFilter<
       },
     ],
   })
+
   return {
     abi: event ? [event] : undefined,
     args,
     eventName: event ? (event as AbiEvent).name : undefined,
     id,
+    request: getRequest(id),
     type: 'event',
   } as unknown as CreateEventFilterReturnType<
     TAbiEvent,

package/src/actions/public/createPendingTransactionFilter.ts

@@ -1,16 +1,41 @@
 import type { PublicClient, Transport } from '../../clients/index.js'
 import type { Chain, Filter } from '../../types/index.js'
+import { createFilterRequestScope } from '../../utils/filters/createFilterRequestScope.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,
 >(
   client: PublicClient<TTransport, TChain>,
 ): Promise<CreatePendingTransactionFilterReturnType> {
+  const getRequest = createFilterRequestScope(client, {
+    method: 'eth_newPendingTransactionFilter',
+  })
   const id = await client.request({
     method: 'eth_newPendingTransactionFilter',
   })
-  return { id, type: 'transaction' }
+  return { id, request: getRequest(id), type: 'transaction' }
 }

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

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

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