viem 0.3.1 → 0.3.2

package/src/actions/test/setBalance.ts

@@ -13,6 +13,29 @@ export type SetBalanceParameters = {
   value: bigint
 }
 
+/**
+ * Modifies the balance of an account.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setBalance.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetBalanceParameters}
+ *
+ * @example
+ * import { createTestClient, http, parseEther } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setBalance } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setBalance(client, {
+ *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+ *   value: parseEther('1'),
+ * })
+ */
 export async function setBalance<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { address, value }: SetBalanceParameters,

package/src/actions/test/setBlockGasLimit.ts

@@ -11,6 +11,26 @@ export type SetBlockGasLimitParameters = {
   gasLimit: bigint
 }
 
+/**
+ * Sets the block's gas limit.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setBlockGasLimit.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetBlockGasLimitParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setBlockGasLimit } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setBlockGasLimit(client, { gasLimit: 420_000n })
+ */
 export async function setBlockGasLimit<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { gasLimit }: SetBlockGasLimitParameters,

package/src/actions/test/setBlockTimestampInterval.ts

@@ -10,6 +10,26 @@ export type SetBlockTimestampIntervalParameters = {
   interval: number
 }
 
+/**
+ * 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 client - Client to use
+ * @param parameters – {@link SetBlockTimestampIntervalParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setBlockTimestampInterval } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setBlockTimestampInterval(client, { interval: 5 })
+ */
 export async function setBlockTimestampInterval<
   TChain extends Chain | undefined,
 >(

package/src/actions/test/setCode.ts

@@ -12,6 +12,29 @@ export type SetCodeParameters = {
   bytecode: Hex
 }
 
+/**
+ * Modifies the bytecode stored at an account's address.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setCode.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetCodeParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setCode } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setCode(client, {
+ *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+ *   bytecode: '0x60806040526000600355600019600955600c80546001600160a01b031916737a250d5630b4cf539739df…',
+ * })
+ */
 export async function setCode<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { address, bytecode }: SetCodeParameters,

package/src/actions/test/setCoinbase.ts

@@ -10,6 +10,28 @@ export type SetCoinbaseParameters = {
   address: Address
 }
 
+/**
+ * Sets the coinbase address to be used in new blocks.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setCoinbase.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetCoinbaseParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setCoinbase } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setCoinbase(client, {
+ *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+ * })
+ */
 export async function setCoinbase<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { address }: SetCoinbaseParameters,

package/src/actions/test/setIntervalMining.ts

@@ -10,6 +10,26 @@ export type SetIntervalMiningParameters = {
   interval: number
 }
 
+/**
+ * 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 client - Client to use
+ * @param parameters – {@link SetIntervalMiningParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setIntervalMining } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setIntervalMining(client, { interval: 5 })
+ */
 export async function setIntervalMining<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { interval }: SetIntervalMiningParameters,

package/src/actions/test/setLoggingEnabled.ts

@@ -5,6 +5,25 @@ import type {
 } from '../../clients/index.js'
 import type { Chain } from '../../types/index.js'
 
+/**
+ * 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'
+ * import { setLoggingEnabled } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setLoggingEnabled(client)
+ */
 export async function setLoggingEnabled<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   enabled: boolean,

package/src/actions/test/setMinGasPrice.ts

@@ -11,6 +11,30 @@ export type SetMinGasPriceParameters = {
   gasPrice: bigint
 }
 
+/**
+ * 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 client - Client to use
+ * @param parameters – {@link SetBlockGasLimitParameters}
+ *
+ * @example
+ * import { createTestClient, http, parseGwei } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setMinGasPrice } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setMinGasPrice(client, {
+ *   gasPrice: parseGwei('20'),
+ * })
+ */
 export async function setMinGasPrice<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { gasPrice }: SetMinGasPriceParameters,

package/src/actions/test/setNextBlockBaseFeePerGas.ts

@@ -11,6 +11,28 @@ export type SetNextBlockBaseFeePerGasParameters = {
   baseFeePerGas: bigint
 }
 
+/**
+ * Sets the next block's base fee per gas.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setNextBlockBaseFeePerGas.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetNextBlockBaseFeePerGasParameters}
+ *
+ * @example
+ * import { createTestClient, http, parseGwei } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setNextBlockBaseFeePerGas } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setNextBlockBaseFeePerGas(client, {
+ *   baseFeePerGas: parseGwei('20'),
+ * })
+ */
 export async function setNextBlockBaseFeePerGas<
   TChain extends Chain | undefined,
 >(

package/src/actions/test/setNextBlockTimestamp.ts

@@ -11,6 +11,26 @@ export type SetNextBlockTimestampParameters = {
   timestamp: bigint
 }
 
+/**
+ * Sets the next block's timestamp.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setNextBlockTimestamp.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetNextBlockTimestampParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setNextBlockTimestamp } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setNextBlockTimestamp(client, { timestamp: 1671744314n })
+ */
 export async function setNextBlockTimestamp<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { timestamp }: SetNextBlockTimestampParameters,

package/src/actions/test/setNonce.ts

@@ -13,6 +13,29 @@ export type SetNonceParameters = {
   nonce: number
 }
 
+/**
+ * Modifies (overrides) the nonce of an account.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setNonce.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetNonceParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setNonce } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setNonce(client, {
+ *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+ *   nonce: 420,
+ * })
+ */
 export async function setNonce<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { address, nonce }: SetNonceParameters,

package/src/actions/test/setRpcUrl.ts

@@ -5,6 +5,26 @@ import type {
 } from '../../clients/index.js'
 import type { Chain } from '../../types/index.js'
 
+/**
+ * Sets the backend RPC URL.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setRpcUrl.html
+ *
+ * @param client - Client to use
+ * @param jsonRpcUrl – RPC URL
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setRpcUrl } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setRpcUrl(client, 'https://eth-mainnet.g.alchemy.com/v2')
+ */
 export async function setRpcUrl<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   jsonRpcUrl: string,

package/src/actions/test/setStorageAt.ts

@@ -15,6 +15,30 @@ export type SetStorageAtParameters = {
   value: Hex
 }
 
+/**
+ * Writes to a slot of an account's storage.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/setStorageAt.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link SetStorageAtParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setStorageAt } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setStorageAt(client, {
+ *   address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
+ *   index: 2,
+ *   value: '0x0000000000000000000000000000000000000000000000000000000000000069',
+ * })
+ */
 export async function setStorageAt<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
   { address, index, value }: SetStorageAtParameters,

package/src/actions/test/snapshot.ts

@@ -5,6 +5,25 @@ import type {
 } from '../../clients/index.js'
 import type { Chain } from '../../types/index.js'
 
+/**
+ * Snapshot the state of the blockchain at the current block.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/snapshot.html
+ *
+ * @param client - Client to use
+ *
+ * @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 snapshot(client)
+ */
 export async function snapshot<TChain extends Chain | undefined>(
   client: TestClient<TestClientMode, Transport, TChain>,
 ) {

package/src/actions/test/stopImpersonatingAccount.ts

@@ -10,6 +10,28 @@ export type StopImpersonatingAccountParameters = {
   address: Address
 }
 
+/**
+ * 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 client - Client to use
+ * @param parameters – {@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 stopImpersonatingAccount(client, {
+ *   address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
+ * })
+ */
 export async function stopImpersonatingAccount<
   TChain extends Chain | undefined,
 >(

package/src/actions/wallet/addChain.ts

@@ -3,9 +3,29 @@ import type { Account, Chain } from '../../types/index.js'
 import { numberToHex } from '../../utils/index.js'
 
 export type AddChainParameters = {
+  /** The chain to add to the wallet. */
   chain: Chain
 }
 
+/**
+ * Adds an EVM chain to the wallet.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/addChain.html
+ * - JSON-RPC Methods: [`eth_addEthereumChain`](https://eips.ethereum.org/EIPS/eip-3085)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link AddChainParameters}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { optimism } from 'viem/chains'
+ * import { addChain } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   transport: custom(window.ethereum),
+ * })
+ * await addChain(client, { chain: optimism })
+ */
 export async function addChain<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined,

package/src/actions/wallet/deployContract.ts

@@ -47,7 +47,7 @@ export type DeployContractReturnType = SendTransactionReturnType
  * import { deployContract } from 'viem/contract'
  *
  * const client = createWalletClient({
- *   account = privateKeyToAccount('0x…'),
+ *   account: privateKeyToAccount('0x…'),
  *   chain: mainnet,
  *   transport: http(),
  * })

package/src/actions/wallet/getAddresses.ts

@@ -6,6 +6,26 @@ import { checksumAddress } from '../../utils/address/index.js'
 
 export type GetAddressesReturnType = Address[]
 
+/**
+ * Returns a list of account addresses owned by the wallet or client.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/getAddresses.html
+ * - JSON-RPC Methods: [`eth_accounts`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_accounts)
+ *
+ * @param client - Client to use
+ * @returns List of account addresses owned by the wallet or client. {@link GetAddressesReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getAddresses } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ * const accounts = await getAddresses(client)
+ */
 export async function getAddresses<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined = undefined,

package/src/actions/wallet/getPermissions.ts

@@ -4,6 +4,26 @@ import type { WalletPermission } from '../../types/eip1193.js'
 
 export type GetPermissionsReturnType = WalletPermission[]
 
+/**
+ * Gets the wallets current permissions.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/getPermissions.html
+ * - JSON-RPC Methods: [`wallet_getPermissions`](https://eips.ethereum.org/EIPS/eip-2255)
+ *
+ * @param client - Client to use
+ * @returns The wallet permissions. {@link GetPermissionsReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getPermissions } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ * const permissions = await getPermissions(client)
+ */
 export async function getPermissions<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined = undefined,

package/src/actions/wallet/requestAddresses.ts

@@ -6,6 +6,30 @@ import { getAddress } from '../../utils/index.js'
 
 export type RequestAddressesReturnType = Address[]
 
+/**
+ * Requests a list of accounts managed by a wallet.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/requestAddresses.html
+ * - JSON-RPC Methods: [`eth_requestAccounts`](https://eips.ethereum.org/EIPS/eip-1102)
+ *
+ * Sends a request to the wallet, asking for permission to access the user's accounts. After the user accepts the request, it will return a list of accounts (addresses).
+ *
+ * This API can be useful for dapps that need to access the user's accounts in order to execute transactions or interact with smart contracts.
+ *
+ * @param client - Client to use
+ * @returns List of accounts managed by a wallet {@link RequestAddressesReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { requestAddresses } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ * const accounts = await requestAddresses(client)
+ */
 export async function requestAddresses<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined = undefined,

package/src/actions/wallet/requestPermissions.ts

@@ -1,14 +1,39 @@
 import type { Transport, WalletClient } from '../../clients/index.js'
-import type { Account, Chain } from '../../types/index.js'
+import type { Account, Chain, Prettify } from '../../types/index.js'
 import type { WalletPermission } from '../../types/eip1193.js'
 
-export type RequestPermissionsParameters = {
-  eth_accounts: Record<string, any>
-} & {
-  [key: string]: Record<string, any>
-}
+export type RequestPermissionsParameters = Prettify<
+  {
+    eth_accounts: Record<string, any>
+  } & {
+    [key: string]: Record<string, any>
+  }
+>
 export type RequestPermissionsReturnType = WalletPermission[]
 
+/**
+ * Requests permissions for a wallet.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/requestPermissions.html
+ * - JSON-RPC Methods: [`wallet_requestPermissions`](https://eips.ethereum.org/EIPS/eip-2255)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link RequestPermissionsParameters}
+ * @returns The wallet permissions. {@link RequestPermissionsReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { requestPermissions } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ * const permissions = await requestPermissions(client, {
+ *   eth_accounts: {}
+ * })
+ */
 export async function requestPermissions<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined = undefined,

package/src/actions/wallet/sendTransaction.ts

@@ -48,6 +48,51 @@ export type SendTransactionParameters<
 
 export type SendTransactionReturnType = Hash
 
+/**
+ * Creates, signs, and sends a new transaction to the network.
+ *
+ * - Docs: https://viem.sh/docs/actions/wallet/sendTransaction.html
+ * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/sending-transactions
+ * - JSON-RPC Methods:
+ *   - JSON-RPC Accounts: [`eth_sendTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction)
+ *   - Local Accounts: [`eth_sendRawTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link SendTransactionParameters}
+ * @returns The [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) hash. {@link SendTransactionReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { sendTransaction } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ * const hash = await sendTransaction(client, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *   value: 1000000000000000000n,
+ * })
+ *
+ * @example
+ * // Account Hoisting
+ * import { createWalletClient, http } from 'viem'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ * import { mainnet } from 'viem/chains'
+ * import { sendTransaction } from 'viem/wallet'
+ *
+ * const client = createWalletClient({
+ *   account: privateKeyToAccount('0x…'),
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const hash = await sendTransaction(client, {
+ *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *   value: 1000000000000000000n,
+ * })
+ */
 export async function sendTransaction<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined,