viem 0.3.0-tsc-nodenext-2.20230407T050527 → 0.3.1

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[],

package/src/actions/public/simulateContract.ts

@@ -57,6 +57,38 @@ export type SimulateContractReturnType<
   } & ContractFunctionConfig<TAbi, TFunctionName, 'payable' | 'nonpayable'>
 }
 
+/**
+ * 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[],

package/src/actions/public/uninstallFilter.ts

@@ -6,14 +6,39 @@ 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,
 >(
-  client: PublicClient<TTransport, TChain>,
+  _client: PublicClient<TTransport, TChain>,
   { filter }: UninstallFilterParameters,
 ): Promise<UninstallFilterReturnType> {
-  return client.request({
+  return filter.request({
     method: 'eth_uninstallFilter',
     params: [filter.id],
   })

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

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

package/src/actions/public/watchBlocks.ts

@@ -45,13 +45,35 @@ export type WatchBlocksParameters<
           poll?: false
           pollingInterval?: never
         }
-      | (PollOptions & { poll: true })
+      | (PollOptions & { poll?: true })
   : PollOptions & { poll?: true })
 
 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,

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

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

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

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