viem 0.0.0-tsc-and-nodenext-20230405154910 → 0.0.0-w-20230711200108

package/src/actions/test/mine.ts

@@ -1,10 +1,11 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain } from '../../types/index.js'
-import { numberToHex } from '../../utils/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 
 export type MineParameters = {
   /** Number of blocks to mine. */
@@ -13,12 +14,41 @@ export type MineParameters = {
   interval?: number
 }
 
-export async function mine<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * Mine a specified number of blocks.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/mine.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link MineParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { mine } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await mine(client, { blocks: 1 })
+ */
+export async function mine<
+  TChain extends Chain | undefined,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { blocks, interval }: MineParameters,
 ) {
-  return await client.request({
-    method: `${client.mode}_mine`,
-    params: [numberToHex(blocks), numberToHex(interval || 0)],
-  })
+  if (client.mode === 'ganache')
+    await client.request({
+      method: 'evm_mine',
+      params: [{ blocks: numberToHex(blocks) }],
+    })
+  else
+    await client.request({
+      method: `${client.mode}_mine`,
+      params: [numberToHex(blocks), numberToHex(interval || 0)],
+    })
 }

package/src/actions/test/removeBlockTimestampInterval.ts

@@ -1,14 +1,35 @@
-import type { Chain } from '@wagmi/chains'
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
 
+/**
+ * Removes [`setBlockTimestampInterval`](https://viem.sh/docs/actions/test/setBlockTimestampInterval.html) if it exists.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/removeBlockTimestampInterval.html
+ *
+ * @param client - Client to use
+ *
+ * @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 removeBlockTimestampInterval(client)
+ */
 export async function removeBlockTimestampInterval<
   TChain extends Chain | undefined,
->(client: TestClient<TestClientMode, Transport, TChain>) {
-  return await client.request({
+  TAccount extends Account | undefined,
+>(client: TestClient<TestClientMode, Transport, TChain, TAccount, false>) {
+  await client.request({
     method: `${client.mode}_removeBlockTimestampInterval`,
   })
 }

package/src/actions/test/reset.ts

@@ -1,9 +1,10 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain } from '../../types/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
 
 export type ResetParameters = {
   /** The block number to reset from. */
@@ -12,11 +13,34 @@ export type ResetParameters = {
   jsonRpcUrl?: string
 }
 
-export async function reset<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * Resets fork back to its original state.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/reset.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link ResetParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { reset } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await reset(client, { blockNumber: 69420n })
+ */
+export async function reset<
+  TChain extends Chain | undefined,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { blockNumber, jsonRpcUrl }: ResetParameters = {},
 ) {
-  return await client.request({
+  await client.request({
     method: `${client.mode}_reset`,
     params: [{ forking: { blockNumber: Number(blockNumber), jsonRpcUrl } }],
   })

package/src/actions/test/revert.ts

@@ -1,20 +1,45 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain, Quantity } from '../../types/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import type { Quantity } from '../../types/rpc.js'
 
 export type RevertParameters = {
   /** The snapshot ID to revert to. */
   id: Quantity
 }
 
-export async function revert<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * Revert the state of the blockchain at the current block.
+ *
+ * - Docs: https://viem.sh/docs/actions/test/revert.html
+ *
+ * @param client - Client to use
+ * @param parameters – {@link RevertParameters}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { revert } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await revert(client, { id: '0x…' })
+ */
+export async function revert<
+  TChain extends Chain | undefined,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { id }: RevertParameters,
 ) {
-  return await client.request({
+  await client.request({
     method: 'evm_revert',
     params: [id],
   })

package/src/actions/test/sendUnsignedTransaction.ts

@@ -1,25 +1,90 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain, Hash, TransactionRequest } from '../../types/index.js'
-import { formatTransactionRequest } from '../../utils/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import type { TransactionRequest } from '../../types/transaction.js'
+import { extract } from '../../utils/formatters/extract.js'
+import {
+  type FormattedTransactionRequest,
+  formatTransactionRequest,
+} from '../../utils/formatters/transactionRequest.js'
 
-export type SendUnsignedTransactionParameters = TransactionRequest
+export type SendUnsignedTransactionParameters<
+  TChain extends Chain | undefined = Chain | undefined,
+> = FormattedTransactionRequest<TChain>
 
 export type SendUnsignedTransactionReturnType = Hash
 
+/**
+ * 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 client - Client to use
+ * @param parameters – {@link SendUnsignedTransactionParameters}
+ * @returns The transaction hash. {@link SendUnsignedTransactionReturnType}
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { sendUnsignedTransaction } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * const hash = await sendUnsignedTransaction(client, {
+ *   from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+ *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *   value: 1000000000000000000n,
+ * })
+ */
 export async function sendUnsignedTransaction<
   TChain extends Chain | undefined,
+  TAccount extends Account | undefined,
 >(
-  client: TestClient<TestClientMode, Transport, TChain>,
-  request: SendUnsignedTransactionParameters,
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
+  args: SendUnsignedTransactionParameters<TChain>,
 ): Promise<SendUnsignedTransactionReturnType> {
-  const request_ = formatTransactionRequest(request)
+  const {
+    accessList,
+    data,
+    from,
+    gas,
+    gasPrice,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    to,
+    value,
+    ...rest
+  } = args
+
+  const format =
+    client.chain?.formatters?.transactionRequest?.format ||
+    formatTransactionRequest
+  const request = format({
+    // Pick out extra data that might exist on the chain's transaction request type.
+    ...extract(rest, { format }),
+    accessList,
+    data,
+    from,
+    gas,
+    gasPrice,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    to,
+    value,
+  } as TransactionRequest)
   const hash = await client.request({
     method: 'eth_sendUnsignedTransaction',
-    params: [request_],
+    params: [request],
   })
   return hash
 }

package/src/actions/test/setAutomine.ts

@@ -1,16 +1,43 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain } from '../../types/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
 
-export async function setAutomine<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * 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
+ *
+ * @param client - Client to use
+ *
+ * @example
+ * import { createTestClient, http } from 'viem'
+ * import { foundry } from 'viem/chains'
+ * import { setAutomine } from 'viem/test'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: 'foundry',
+ *   transport: http(),
+ * })
+ * await setAutomine(client)
+ */
+export async function setAutomine<
+  TChain extends Chain | undefined,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   enabled: boolean,
 ) {
-  return await client.request({
-    method: 'evm_setAutomine',
-    params: [enabled],
-  })
+  if (client.mode === 'ganache') {
+    if (enabled) await client.request({ method: 'miner_start' })
+    else await client.request({ method: 'miner_stop' })
+  } else
+    await client.request({
+      method: 'evm_setAutomine',
+      params: [enabled],
+    })
 }

package/src/actions/test/setBalance.ts

@@ -1,10 +1,13 @@
+import type { Address } from 'abitype'
+
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Address, Chain } from '../../types/index.js'
-import { numberToHex } from '../../utils/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 
 export type SetBalanceParameters = {
   /** The account address. */
@@ -13,12 +16,44 @@ export type SetBalanceParameters = {
   value: bigint
 }
 
-export async function setBalance<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * 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,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { address, value }: SetBalanceParameters,
 ) {
-  return await client.request({
-    method: `${client.mode}_setBalance`,
-    params: [address, numberToHex(value)],
-  })
+  if (client.mode === 'ganache')
+    await client.request({
+      method: 'evm_setAccountBalance',
+      params: [address, numberToHex(value)],
+    })
+  else
+    await client.request({
+      method: `${client.mode}_setBalance`,
+      params: [address, numberToHex(value)],
+    })
 }

package/src/actions/test/setBlockGasLimit.ts

@@ -1,21 +1,45 @@
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Chain } from '../../types/index.js'
-import { numberToHex } from '../../utils/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 
 export type SetBlockGasLimitParameters = {
   /** Gas limit (in wei). */
   gasLimit: bigint
 }
 
-export async function setBlockGasLimit<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * 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,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { gasLimit }: SetBlockGasLimitParameters,
 ) {
-  return await client.request({
+  await client.request({
     method: 'evm_setBlockGasLimit',
     params: [numberToHex(gasLimit)],
   })

package/src/actions/test/setBlockTimestampInterval.ts

@@ -1,22 +1,44 @@
-import type { Chain } from '@wagmi/chains'
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
 
 export type SetBlockTimestampIntervalParameters = {
   /** The interval (in seconds). */
   interval: number
 }
 
+/**
+ * Similar to [`increaseTime`](https://viem.sh/docs/actions/test/increaseTime.html), 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,
+  TAccount extends Account | undefined,
 >(
-  client: TestClient<TestClientMode, Transport, TChain>,
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { interval }: SetBlockTimestampIntervalParameters,
 ) {
-  return await client.request({
+  await client.request({
     method: `${client.mode}_setBlockTimestampInterval`,
     params: [interval],
   })

package/src/actions/test/setCode.ts

@@ -1,9 +1,13 @@
+import type { Address } from 'abitype'
+
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Address, Chain, Hex } from '../../types/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hex } from '../../types/misc.js'
 
 export type SetCodeParameters = {
   /** The account address. */
@@ -12,11 +16,37 @@ export type SetCodeParameters = {
   bytecode: Hex
 }
 
-export async function setCode<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * 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,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { address, bytecode }: SetCodeParameters,
 ) {
-  return await client.request({
+  await client.request({
     method: `${client.mode}_setCode`,
     params: [address, bytecode],
   })

package/src/actions/test/setCoinbase.ts

@@ -1,20 +1,48 @@
+import type { Address } from 'abitype'
+
 import type {
   TestClient,
   TestClientMode,
-  Transport,
-} from '../../clients/index.js'
-import type { Address, Chain } from '../../types/index.js'
+} from '../../clients/createTestClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
 
 export type SetCoinbaseParameters = {
   /** The coinbase address. */
   address: Address
 }
 
-export async function setCoinbase<TChain extends Chain | undefined>(
-  client: TestClient<TestClientMode, Transport, TChain>,
+/**
+ * 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,
+  TAccount extends Account | undefined,
+>(
+  client: TestClient<TestClientMode, Transport, TChain, TAccount, false>,
   { address }: SetCoinbaseParameters,
 ) {
-  return await client.request({
+  await client.request({
     method: `${client.mode}_setCoinbase`,
     params: [address],
   })