viem 0.3.0 → 0.3.2

package/src/clients/decorators/test.ts

@@ -59,41 +59,577 @@ import type { TestClient, TestClientMode } from '../createTestClient.js'
 import type { Transport } from '../transports/index.js'
 
 export type TestActions = {
+  /**
+   * Removes a transaction from the mempool.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/dropTransaction.html
+   *
+   * @param args - {@link DropTransactionParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.dropTransaction({
+   *   hash: '0xe58dceb6b20b03965bb678e27d141e151d7d4efc2334c2d6a49b9fac523f7364'
+   * })
+   */
   dropTransaction: (args: DropTransactionParameters) => Promise<void>
+  /**
+   * Returns the automatic mining status of the node.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/getAutomine.html
+   *
+   * @returns Whether or not the node is auto mining. {@link GetAutomineReturnType}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * const isAutomining = await client.getAutomine()
+   */
   getAutomine: () => Promise<GetAutomineReturnType>
+  /**
+   * Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/getTxpoolContent.html
+   *
+   * @returns Transaction pool content. {@link GetTxpoolContentReturnType}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * const content = await client.getTxpoolContent()
+   */
   getTxpoolContent: () => Promise<GetTxpoolContentReturnType>
+  /**
+   * Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/getTxpoolStatus.html
+   *
+   * @returns Transaction pool status. {@link GetTxpoolStatusReturnType}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * const status = await client.getTxpoolStatus()
+   */
   getTxpoolStatus: () => Promise<GetTxpoolStatusReturnType>
+  /**
+   * Impersonate an account or contract address. This lets you send transactions from that account even if you don't have access to its private key.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/impersonateAccount.html
+   *
+   * @param args - {@link ImpersonateAccountParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.impersonateAccount({
+   *   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+   * })
+   */
   impersonateAccount: (args: ImpersonateAccountParameters) => Promise<void>
+  /**
+   * Jump forward in time by the given amount of time, in seconds.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/increaseTime.html
+   *
+   * @param args – {@link IncreaseTimeParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.increaseTime({
+   *   seconds: 420,
+   * })
+   */
   increaseTime: (args: IncreaseTimeParameters) => Promise<Quantity>
+  /**
+   * Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/inspectTxpool.html
+   *
+   * @returns Transaction pool inspection data. {@link InspectTxpoolReturnType}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * const data = await client.inspectTxpool()
+   */
   inspectTxpool: () => Promise<InspectTxpoolReturnType>
+  /**
+   * Mine a specified number of blocks.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/mine.html
+   *
+   * @param client - Client to use
+   * @param args – {@link MineParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.mine({ blocks: 1 })
+   */
   mine: (args: MineParameters) => Promise<void>
+  /**
+   * Removes [`setBlockTimestampInterval`](https://viem.sh/docs/actions/test/setBlockTimestampInterval.html) if it exists.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/removeBlockTimestampInterval.html
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   * import { removeBlockTimestampInterval } from 'viem/test'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.removeBlockTimestampInterval()
+   */
   removeBlockTimestampInterval: () => Promise<void>
+  /**
+   * Resets fork back to its original state.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/reset.html
+   *
+   * @param args – {@link ResetParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.reset({ blockNumber: 69420n })
+   */
   reset: (args?: ResetParameters) => Promise<void>
+  /**
+   * Revert the state of the blockchain at the current block.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/revert.html
+   *
+   * @param args – {@link RevertParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.revert({ id: '0x…' })
+   */
   revert: (args: RevertParameters) => Promise<void>
+  /**
+   * Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/getTxpoolContent.html
+   *
+   * @param args – {@link SendUnsignedTransactionParameters}
+   * @returns The transaction hash. {@link SendUnsignedTransactionReturnType}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * const hash = await client.sendUnsignedTransaction({
+   *   from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+   *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+   *   value: 1000000000000000000n,
+   * })
+   */
   sendUnsignedTransaction: (
     args: SendUnsignedTransactionParameters,
   ) => Promise<SendUnsignedTransactionReturnType>
+  /**
+   * Enables or disables the automatic mining of new blocks with each new transaction submitted to the network.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setAutomine.html
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setAutomine()
+   */
   setAutomine: (args: boolean) => Promise<void>
+  /**
+   * Modifies the balance of an account.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setBalance.html
+   *
+   * @param args – {@link SetBalanceParameters}
+   *
+   * @example
+   * import { createTestClient, http, parseEther } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setBalance({
+   *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+   *   value: parseEther('1'),
+   * })
+   */
   setBalance: (args: SetBalanceParameters) => Promise<void>
+  /**
+   * Sets the block's gas limit.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setBlockGasLimit.html
+   *
+   * @param args – {@link SetBlockGasLimitParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setBlockGasLimit({ gasLimit: 420_000n })
+   */
   setBlockGasLimit: (args: SetBlockGasLimitParameters) => Promise<void>
+  /**
+   * Similar to [`increaseTime`](https://viem.sh/docs/actions/test/increaseTime), but sets a block timestamp `interval`. The timestamp of future blocks will be computed as `lastBlock_timestamp` + `interval`.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setBlockTimestampInterval.html
+   *
+   * @param args – {@link SetBlockTimestampIntervalParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setBlockTimestampInterval({ interval: 5 })
+   */
   setBlockTimestampInterval: (
     args: SetBlockTimestampIntervalParameters,
   ) => Promise<void>
+  /**
+   * Modifies the bytecode stored at an account's address.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setCode.html
+   *
+   * @param args – {@link SetCodeParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setCode({
+   *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+   *   bytecode: '0x60806040526000600355600019600955600c80546001600160a01b031916737a250d5630b4cf539739df…',
+   * })
+   */
   setCode: (args: SetCodeParameters) => Promise<void>
+  /**
+   * Sets the coinbase address to be used in new blocks.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setCoinbase.html
+   *
+   * @param args – {@link SetCoinbaseParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setCoinbase({
+   *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+   * })
+   */
   setCoinbase: (args: SetCoinbaseParameters) => Promise<void>
+  /**
+   * Sets the automatic mining interval (in seconds) of blocks. Setting the interval to 0 will disable automatic mining.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setIntervalMining.html
+   *
+   * @param args – {@link SetIntervalMiningParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setIntervalMining({ interval: 5 })
+   */
   setIntervalMining: (args: SetIntervalMiningParameters) => Promise<void>
+  /**
+   * Enable or disable logging on the test node network.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setLoggingEnabled.html
+   *
+   * @param client - Client to use
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setLoggingEnabled()
+   */
   setLoggingEnabled: (args: boolean) => Promise<void>
+  /**
+   * Change the minimum gas price accepted by the network (in wei).
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setMinGasPrice.html
+   *
+   * Note: `setMinGasPrice` can only be used on clients that do not have EIP-1559 enabled.
+   *
+   * @param args – {@link SetBlockGasLimitParameters}
+   *
+   * @example
+   * import { createTestClient, http, parseGwei } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setMinGasPrice({
+   *   gasPrice: parseGwei('20'),
+   * })
+   */
   setMinGasPrice: (args: SetMinGasPriceParameters) => Promise<void>
+  /**
+   * Sets the next block's base fee per gas.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setNextBlockBaseFeePerGas.html
+   *
+   * @param args – {@link SetNextBlockBaseFeePerGasParameters}
+   *
+   * @example
+   * import { createTestClient, http, parseGwei } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setNextBlockBaseFeePerGas({
+   *   baseFeePerGas: parseGwei('20'),
+   * })
+   */
   setNextBlockBaseFeePerGas: (
     args: SetNextBlockBaseFeePerGasParameters,
   ) => Promise<void>
+  /**
+   * Sets the next block's timestamp.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setNextBlockTimestamp.html
+   *
+   * @param args – {@link SetNextBlockTimestampParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setNextBlockTimestamp({ timestamp: 1671744314n })
+   */
   setNextBlockTimestamp: (
     args: SetNextBlockTimestampParameters,
   ) => Promise<void>
+  /**
+   * Modifies (overrides) the nonce of an account.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setNonce.html
+   *
+   * @param args – {@link SetNonceParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setNonce({
+   *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+   *   nonce: 420,
+   * })
+   */
   setNonce: (args: SetNonceParameters) => Promise<void>
+  /**
+   * Sets the backend RPC URL.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setRpcUrl.html
+   *
+   * @param jsonRpcUrl – RPC URL
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setRpcUrl('https://eth-mainnet.g.alchemy.com/v2')
+   */
   setRpcUrl: (args: string) => Promise<void>
+  /**
+   * Writes to a slot of an account's storage.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/setStorageAt.html
+   *
+   * @param args – {@link SetStorageAtParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.setStorageAt({
+   *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+   *   index: 2,
+   *   value: '0x0000000000000000000000000000000000000000000000000000000000000069',
+   * })
+   */
   setStorageAt: (args: SetStorageAtParameters) => Promise<void>
+  /**
+   * Snapshot the state of the blockchain at the current block.
+   *
+   * - Docs: https://viem.sh/docs/actions/test/snapshot.html
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   * import { snapshot } from 'viem/test'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.snapshot()
+   */
   snapshot: () => Promise<Quantity>
+  /**
+   * Stop impersonating an account after having previously used [`impersonateAccount`](https://viem.sh/docs/actions/test/impersonateAccount).
+   *
+   * - Docs: https://viem.sh/docs/actions/test/stopImpersonatingAccount.html
+   *
+   * @param args – {@link StopImpersonatingAccountParameters}
+   *
+   * @example
+   * import { createTestClient, http } from 'viem'
+   * import { foundry } from 'viem/chains'
+   * import { stopImpersonatingAccount } from 'viem/test'
+   *
+   * const client = createTestClient({
+   *   mode: 'anvil',
+   *   chain: 'foundry',
+   *   transport: http(),
+   * })
+   * await client.stopImpersonatingAccount({
+   *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+   * })
+   */
   stopImpersonatingAccount: (
     args: StopImpersonatingAccountParameters,
   ) => Promise<void>