viem 0.2.11 → 0.2.13

package/src/actions/public/readContract.ts

@@ -0,0 +1,73 @@
+import type { Abi } from 'abitype'
+
+import type { PublicClient, Transport } from '../../clients/index.js'
+import type { BaseError } from '../../errors/index.js'
+import type {
+  Chain,
+  ContractFunctionConfig,
+  ContractFunctionResult,
+} from '../../types/index.js'
+import {
+  decodeFunctionResult,
+  encodeFunctionData,
+  getContractError,
+} from '../../utils/index.js'
+import type {
+  DecodeFunctionResultParameters,
+  EncodeFunctionDataParameters,
+} from '../../utils/index.js'
+import { call } from './call.js'
+import type { CallParameters } from './call.js'
+
+export type ReadContractParameters<
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TFunctionName extends string = string,
+> = Pick<CallParameters, 'blockNumber' | 'blockTag'> &
+  ContractFunctionConfig<TAbi, TFunctionName, 'view' | 'pure'>
+
+export type ReadContractReturnType<
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TFunctionName extends string = string,
+> = ContractFunctionResult<TAbi, TFunctionName>
+
+export async function readContract<
+  TChain extends Chain | undefined,
+  TAbi extends Abi | readonly unknown[],
+  TFunctionName extends string,
+>(
+  client: PublicClient<Transport, TChain>,
+  {
+    abi,
+    address,
+    args,
+    functionName,
+    ...callRequest
+  }: ReadContractParameters<TAbi, TFunctionName>,
+): Promise<ReadContractReturnType<TAbi, TFunctionName>> {
+  const calldata = encodeFunctionData({
+    abi,
+    args,
+    functionName,
+  } as unknown as EncodeFunctionDataParameters<TAbi, TFunctionName>)
+  try {
+    const { data } = await call(client, {
+      data: calldata,
+      to: address,
+      ...callRequest,
+    } as unknown as CallParameters)
+    return decodeFunctionResult({
+      abi,
+      args,
+      functionName,
+      data: data || '0x',
+    } as DecodeFunctionResultParameters<TAbi, TFunctionName>)
+  } catch (err) {
+    throw getContractError(err as BaseError, {
+      abi: abi as Abi,
+      address,
+      args,
+      docsPath: '/docs/contract/readContract',
+      functionName,
+    })
+  }
+}

package/src/actions/public/simulateContract.ts

@@ -0,0 +1,122 @@
+import type { Abi } from 'abitype'
+
+import type { PublicClient, Transport } from '../../clients/index.js'
+import type { BaseError } from '../../errors/index.js'
+import type {
+  Chain,
+  ContractFunctionConfig,
+  ContractFunctionResult,
+  GetValue,
+} from '../../types/index.js'
+import {
+  decodeFunctionResult,
+  encodeFunctionData,
+  getContractError,
+  parseAccount,
+} from '../../utils/index.js'
+import type {
+  DecodeFunctionResultParameters,
+  EncodeFunctionDataParameters,
+} from '../../utils/index.js'
+import type { WriteContractParameters } from '../wallet/index.js'
+import { call } from './call.js'
+import type { CallParameters } from './call.js'
+
+export type SimulateContractParameters<
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TFunctionName extends string = any,
+  TChain extends Chain | undefined = Chain | undefined,
+  TChainOverride extends Chain | undefined = undefined,
+> = {
+  chain?: TChainOverride
+} & ContractFunctionConfig<TAbi, TFunctionName, 'payable' | 'nonpayable'> &
+  Omit<
+    CallParameters<TChainOverride extends Chain ? TChainOverride : TChain>,
+    'to' | 'data' | 'value'
+  > &
+  GetValue<TAbi, TFunctionName, CallParameters<TChain>['value']>
+
+export type SimulateContractReturnType<
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TFunctionName extends string = string,
+  TChain extends Chain | undefined = Chain | undefined,
+  TChainOverride extends Chain | undefined = undefined,
+> = {
+  result: ContractFunctionResult<TAbi, TFunctionName>
+  request: Omit<
+    WriteContractParameters<
+      TAbi,
+      TFunctionName,
+      TChain,
+      undefined,
+      TChainOverride
+    >,
+    'chain'
+  > & {
+    chain: TChainOverride
+  } & ContractFunctionConfig<TAbi, TFunctionName, 'payable' | 'nonpayable'>
+}
+
+export async function simulateContract<
+  TChain extends Chain | undefined,
+  TAbi extends Abi | readonly unknown[],
+  TFunctionName extends string,
+  TChainOverride extends Chain | undefined,
+>(
+  client: PublicClient<Transport, TChain>,
+  {
+    abi,
+    address,
+    args,
+    functionName,
+    ...callRequest
+  }: SimulateContractParameters<TAbi, TFunctionName, TChain, TChainOverride>,
+): Promise<
+  SimulateContractReturnType<TAbi, TFunctionName, TChain, TChainOverride>
+> {
+  const account = callRequest.account
+    ? parseAccount(callRequest.account)
+    : undefined
+  const calldata = encodeFunctionData({
+    abi,
+    args,
+    functionName,
+  } as unknown as EncodeFunctionDataParameters<TAbi, TFunctionName>)
+  try {
+    const { data } = await call(client, {
+      data: calldata,
+      to: address,
+      ...callRequest,
+    } as unknown as CallParameters<TChain>)
+    const result = decodeFunctionResult({
+      abi,
+      args,
+      functionName,
+      data: data || '0x',
+    } as DecodeFunctionResultParameters)
+    return {
+      result,
+      request: {
+        abi,
+        address,
+        args,
+        functionName,
+        ...callRequest,
+      },
+    } as unknown as SimulateContractReturnType<
+      TAbi,
+      TFunctionName,
+      TChain,
+      TChainOverride
+    >
+  } catch (err) {
+    throw getContractError(err as BaseError, {
+      abi: abi as Abi,
+      address,
+      args,
+      docsPath: '/docs/contract/simulateContract',
+      functionName,
+      sender: account?.address,
+    })
+  }
+}

package/src/actions/public/uninstallFilter.ts

@@ -0,0 +1,20 @@
+import type { PublicClient, Transport } from '../../clients/index.js'
+import type { Chain, Filter } from '../../types/index.js'
+
+export type UninstallFilterParameters = {
+  filter: Filter<any>
+}
+export type UninstallFilterReturnType = boolean
+
+export async function uninstallFilter<
+  TTransport extends Transport,
+  TChain extends Chain | undefined,
+>(
+  client: PublicClient<TTransport, TChain>,
+  { filter }: UninstallFilterParameters,
+): Promise<UninstallFilterReturnType> {
+  return client.request({
+    method: 'eth_uninstallFilter',
+    params: [filter.id],
+  })
+}

package/src/actions/public/waitForTransactionReceipt.ts

@@ -0,0 +1,178 @@
+import type { PublicClient, Transport } from '../../clients/index.js'
+import {
+  TransactionNotFoundError,
+  TransactionReceiptNotFoundError,
+  WaitForTransactionReceiptTimeoutError,
+} from '../../errors/index.js'
+import type { Chain, Hash, Transaction } from '../../types/index.js'
+import { observe } from '../../utils/observe.js'
+import { getBlock, watchBlockNumber } from './index.js'
+
+import type { GetTransactionReturnType } from './getTransaction.js'
+import { getTransaction } from './getTransaction.js'
+import type { GetTransactionReceiptReturnType } from './getTransactionReceipt.js'
+import { getTransactionReceipt } from './getTransactionReceipt.js'
+
+export type ReplacementReason = 'cancelled' | 'replaced' | 'repriced'
+export type ReplacementReturnType<
+  TChain extends Chain | undefined = Chain | undefined,
+> = {
+  reason: ReplacementReason
+  replacedTransaction: Transaction
+  transaction: Transaction
+  transactionReceipt: GetTransactionReceiptReturnType<TChain>
+}
+
+export type WaitForTransactionReceiptReturnType<
+  TChain extends Chain | undefined = Chain | undefined,
+> = GetTransactionReceiptReturnType<TChain>
+
+export type WaitForTransactionReceiptParameters<
+  TChain extends Chain | undefined = Chain | undefined,
+> = {
+  /** The number of confirmations (blocks that have passed) to wait before resolving. */
+  confirmations?: number
+  /** The hash of the transaction. */
+  hash: Hash
+  onReplaced?: (response: ReplacementReturnType<TChain>) => void
+  /** Polling frequency (in ms). Defaults to the client's pollingInterval config. */
+  pollingInterval?: number
+  /** Optional timeout (in milliseconds) to wait before stopping polling. */
+  timeout?: number
+}
+
+export async function waitForTransactionReceipt<
+  TChain extends Chain | undefined,
+>(
+  client: PublicClient<Transport, TChain>,
+  {
+    confirmations = 1,
+    hash,
+    onReplaced,
+    pollingInterval = client.pollingInterval,
+    timeout,
+  }: WaitForTransactionReceiptParameters<TChain>,
+): Promise<WaitForTransactionReceiptReturnType<TChain>> {
+  const observerId = JSON.stringify([
+    'waitForTransactionReceipt',
+    client.uid,
+    hash,
+  ])
+
+  let transaction: GetTransactionReturnType<TChain> | undefined
+  let replacedTransaction: GetTransactionReturnType<TChain> | undefined
+  let receipt: GetTransactionReceiptReturnType<TChain>
+
+  return new Promise((resolve, reject) => {
+    if (timeout)
+      setTimeout(
+        () => reject(new WaitForTransactionReceiptTimeoutError({ hash })),
+        timeout,
+      )
+
+    const _unobserve = observe(
+      observerId,
+      { onReplaced, resolve, reject },
+      (emit) => {
+        const unwatch = watchBlockNumber(client, {
+          emitMissed: true,
+          emitOnBegin: true,
+          poll: true,
+          pollingInterval,
+          async onBlockNumber(blockNumber) {
+            const done = async (fn: () => void) => {
+              unwatch()
+              fn()
+              _unobserve()
+            }
+
+            try {
+              // If we already have a valid receipt, let's check if we have enough
+              // confirmations. If we do, then we can resolve.
+              if (receipt) {
+                if (blockNumber - receipt.blockNumber + 1n < confirmations)
+                  return
+
+                done(() => emit.resolve(receipt))
+                return
+              }
+
+              // Get the transaction to check if it's been replaced.
+              transaction = await getTransaction(client, { hash })
+
+              // Get the receipt to check if it's been processed.
+              receipt = await getTransactionReceipt(client, { hash })
+
+              // Check if we have enough confirmations. If not, continue polling.
+              if (blockNumber - receipt.blockNumber + 1n < confirmations) return
+
+              done(() => emit.resolve(receipt))
+            } catch (err) {
+              // If the receipt is not found, the transaction will be pending.
+              // We need to check if it has potentially been replaced.
+              if (
+                transaction &&
+                (err instanceof TransactionNotFoundError ||
+                  err instanceof TransactionReceiptNotFoundError)
+              ) {
+                replacedTransaction = transaction
+
+                // Let's retrieve the transactions from the current block.
+                const block = await getBlock(client, {
+                  blockNumber,
+                  includeTransactions: true,
+                })
+
+                const replacementTransaction = (
+                  block.transactions as Transaction[]
+                ).find(
+                  ({ from, nonce }) =>
+                    from === replacedTransaction!.from &&
+                    nonce === replacedTransaction!.nonce,
+                )
+
+                // If we couldn't find a replacement transaction, continue polling.
+                if (!replacementTransaction) return
+
+                // If we found a replacement transaction, return it's receipt.
+                receipt = await getTransactionReceipt(client, {
+                  hash: replacementTransaction.hash,
+                })
+
+                // Check if we have enough confirmations. If not, continue polling.
+                if (blockNumber - receipt.blockNumber + 1n < confirmations)
+                  return
+
+                let reason: ReplacementReason = 'replaced'
+                if (
+                  replacementTransaction.to === replacedTransaction.to &&
+                  replacementTransaction.value === replacedTransaction.value
+                ) {
+                  reason = 'repriced'
+                } else if (
+                  replacementTransaction.from === replacementTransaction.to &&
+                  replacementTransaction.value === 0n
+                ) {
+                  reason = 'cancelled'
+                }
+
+                done(() => {
+                  emit.onReplaced?.({
+                    reason,
+                    replacedTransaction: replacedTransaction!,
+                    transaction: replacementTransaction,
+                    transactionReceipt: receipt,
+                  })
+                  emit.resolve(receipt)
+                })
+              } else {
+                done(() => emit.reject(err))
+              }
+            }
+          },
+        })
+        return unwatch
+      },
+    )
+  })
+}

package/src/actions/public/watchBlockNumber.ts

@@ -0,0 +1,140 @@
+import type { PublicClient, Transport } from '../../clients/index.js'
+import type { Chain, GetTransportConfig } from '../../types/index.js'
+import { hexToBigInt } from '../../utils/index.js'
+import { observe } from '../../utils/observe.js'
+import { poll } from '../../utils/poll.js'
+import type { GetBlockNumberReturnType } from './getBlockNumber.js'
+import { getBlockNumber } from './getBlockNumber.js'
+
+export type OnBlockNumberParameter = GetBlockNumberReturnType
+export type OnBlockNumberFn = (
+  blockNumber: OnBlockNumberParameter,
+  prevBlockNumber: OnBlockNumberParameter | undefined,
+) => void
+
+export type PollOptions = {
+  /** Whether or not to emit the missed block numbers to the callback. */
+  emitMissed?: boolean
+  /** Whether or not to emit the latest block number to the callback when the subscription opens. */
+  emitOnBegin?: boolean
+  /** Polling frequency (in ms). Defaults to Client's pollingInterval config. */
+  pollingInterval?: number
+}
+
+export type WatchBlockNumberParameters<
+  TTransport extends Transport = Transport,
+> = {
+  /** The callback to call when a new block number is received. */
+  onBlockNumber: OnBlockNumberFn
+  /** The callback to call when an error occurred when trying to get for a new block. */
+  onError?: (error: Error) => void
+} & (GetTransportConfig<TTransport>['type'] extends 'webSocket'
+  ?
+      | {
+          emitMissed?: never
+          emitOnBegin?: never
+          /** Whether or not the WebSocket Transport should poll the JSON-RPC, rather than using `eth_subscribe`. */
+          poll?: false
+          pollingInterval?: never
+        }
+      | (PollOptions & { poll: true })
+  : PollOptions & { poll?: true })
+
+export type WatchBlockNumberReturnType = () => void
+
+/** @description Watches and returns incoming block numbers. */
+export function watchBlockNumber<
+  TChain extends Chain | undefined,
+  TTransport extends Transport,
+>(
+  client: PublicClient<TTransport, TChain>,
+  {
+    emitOnBegin = false,
+    emitMissed = false,
+    onBlockNumber,
+    onError,
+    poll: poll_,
+    pollingInterval = client.pollingInterval,
+  }: WatchBlockNumberParameters<TTransport>,
+): WatchBlockNumberReturnType {
+  const enablePolling =
+    typeof poll_ !== 'undefined' ? poll_ : client.transport.type !== 'webSocket'
+
+  let prevBlockNumber: GetBlockNumberReturnType | undefined
+
+  const pollBlockNumber = () => {
+    const observerId = JSON.stringify([
+      'watchBlockNumber',
+      client.uid,
+      emitOnBegin,
+      emitMissed,
+      pollingInterval,
+    ])
+
+    return observe(observerId, { onBlockNumber, onError }, (emit) =>
+      poll(
+        async () => {
+          try {
+            const blockNumber = await getBlockNumber(client, { maxAge: 0 })
+
+            if (prevBlockNumber) {
+              // If the current block number is the same as the previous,
+              // we can skip.
+              if (blockNumber === prevBlockNumber) return
+
+              // If we have missed out on some previous blocks, and the
+              // `emitMissed` flag is truthy, let's emit those blocks.
+              if (blockNumber - prevBlockNumber > 1 && emitMissed) {
+                for (let i = prevBlockNumber + 1n; i < blockNumber; i++) {
+                  emit.onBlockNumber(i, prevBlockNumber)
+                  prevBlockNumber = i
+                }
+              }
+            }
+
+            // If the next block number is greater than the previous,
+            // it is not in the past, and we can emit the new block number.
+            if (!prevBlockNumber || blockNumber > prevBlockNumber) {
+              emit.onBlockNumber(blockNumber, prevBlockNumber)
+              prevBlockNumber = blockNumber
+            }
+          } catch (err) {
+            emit.onError?.(err as Error)
+          }
+        },
+        {
+          emitOnBegin,
+          interval: pollingInterval,
+        },
+      ),
+    )
+  }
+
+  const subscribeBlockNumber = () => {
+    let active = true
+    let unsubscribe = () => (active = false)
+    ;(async () => {
+      try {
+        const { unsubscribe: unsubscribe_ } = await client.transport.subscribe({
+          params: ['newHeads'],
+          onData(data: any) {
+            if (!active) return
+            const blockNumber = hexToBigInt(data.result?.number)
+            onBlockNumber(blockNumber, prevBlockNumber)
+            prevBlockNumber = blockNumber
+          },
+          onError(error: Error) {
+            onError?.(error)
+          },
+        })
+        unsubscribe = unsubscribe_
+        if (!active) unsubscribe()
+      } catch (err) {
+        onError?.(err as Error)
+      }
+    })()
+    return unsubscribe
+  }
+
+  return enablePolling ? pollBlockNumber() : subscribeBlockNumber()
+}

package/src/actions/public/watchBlocks.ts

@@ -0,0 +1,165 @@
+import type { PublicClient, Transport } from '../../clients/index.js'
+import type { BlockTag, Chain, GetTransportConfig } from '../../types/index.js'
+import { observe } from '../../utils/observe.js'
+import { poll } from '../../utils/poll.js'
+import type { GetBlockReturnType } from './getBlock.js'
+import { getBlock } from './getBlock.js'
+
+export type OnBlockParameter<TChain extends Chain | undefined = Chain> =
+  GetBlockReturnType<TChain>
+
+export type OnBlock<TChain extends Chain | undefined = Chain> = (
+  block: OnBlockParameter<TChain>,
+  prevBlock: OnBlockParameter<TChain> | undefined,
+) => void
+
+type PollOptions = {
+  /** The block tag. Defaults to "latest". */
+  blockTag?: BlockTag
+  /** Whether or not to emit the missed blocks to the callback. */
+  emitMissed?: boolean
+  /** Whether or not to emit the block to the callback when the subscription opens. */
+  emitOnBegin?: boolean
+  /** Whether or not to include transaction data in the response. */
+  includeTransactions?: boolean
+  /** Polling frequency (in ms). Defaults to the client's pollingInterval config. */
+  pollingInterval?: number
+}
+
+export type WatchBlocksParameters<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain,
+> = {
+  /** The callback to call when a new block is received. */
+  onBlock: OnBlock<TChain>
+  /** The callback to call when an error occurred when trying to get for a new block. */
+  onError?: (error: Error) => void
+} & (GetTransportConfig<TTransport>['type'] extends 'webSocket'
+  ?
+      | {
+          blockTag?: never
+          emitMissed?: never
+          emitOnBegin?: never
+          includeTransactions?: never
+          /** Whether or not the WebSocket Transport should poll the JSON-RPC, rather than using `eth_subscribe`. */
+          poll?: false
+          pollingInterval?: never
+        }
+      | (PollOptions & { poll?: true })
+  : PollOptions & { poll?: true })
+
+export type WatchBlocksReturnType = () => void
+
+/**
+ * @description Watches and returns information for incoming blocks.
+ */
+export function watchBlocks<
+  TTransport extends Transport,
+  TChain extends Chain | undefined,
+>(
+  client: PublicClient<TTransport, TChain>,
+  {
+    blockTag = 'latest',
+    emitMissed = false,
+    emitOnBegin = false,
+    onBlock,
+    onError,
+    includeTransactions = false,
+    poll: poll_,
+    pollingInterval = client.pollingInterval,
+  }: WatchBlocksParameters<TTransport, TChain>,
+): WatchBlocksReturnType {
+  const enablePolling =
+    typeof poll_ !== 'undefined' ? poll_ : client.transport.type !== 'webSocket'
+
+  let prevBlock: GetBlockReturnType<TChain> | undefined
+
+  const pollBlocks = () => {
+    const observerId = JSON.stringify([
+      'watchBlocks',
+      client.uid,
+      emitMissed,
+      emitOnBegin,
+      includeTransactions,
+      pollingInterval,
+    ])
+
+    return observe(observerId, { onBlock, onError }, (emit) =>
+      poll(
+        async () => {
+          try {
+            const block = await getBlock(client, {
+              blockTag,
+              includeTransactions,
+            })
+            if (block.number && prevBlock?.number) {
+              // If the current block number is the same as the previous,
+              // we can skip.
+              if (block.number === prevBlock.number) return
+
+              // If we have missed out on some previous blocks, and the
+              // `emitMissed` flag is truthy, let's emit those blocks.
+              if (block.number - prevBlock.number > 1 && emitMissed) {
+                for (let i = prevBlock?.number + 1n; i < block.number; i++) {
+                  const block = await getBlock(client, {
+                    blockNumber: i,
+                    includeTransactions,
+                  })
+                  emit.onBlock(block, prevBlock)
+                  prevBlock = block
+                }
+              }
+            }
+
+            if (
+              // If no previous block exists, emit.
+              !prevBlock?.number ||
+              // If the block tag is "pending" with no block number, emit.
+              (blockTag === 'pending' && !block?.number) ||
+              // If the next block number is greater than the previous block number, emit.
+              // We don't want to emit blocks in the past.
+              (block.number && block.number > prevBlock.number)
+            ) {
+              emit.onBlock(block, prevBlock)
+              prevBlock = block
+            }
+          } catch (err) {
+            emit.onError?.(err as Error)
+          }
+        },
+        {
+          emitOnBegin,
+          interval: pollingInterval,
+        },
+      ),
+    )
+  }
+
+  const subscribeBlocks = () => {
+    let active = true
+    let unsubscribe = () => (active = false)
+    ;(async () => {
+      try {
+        const { unsubscribe: unsubscribe_ } = await client.transport.subscribe({
+          params: ['newHeads'],
+          onData(data: any) {
+            if (!active) return
+            const block = data.result
+            onBlock(block, prevBlock)
+            prevBlock = block
+          },
+          onError(error: Error) {
+            onError?.(error)
+          },
+        })
+        unsubscribe = unsubscribe_
+        if (!active) unsubscribe()
+      } catch (err) {
+        onError?.(err as Error)
+      }
+    })()
+    return unsubscribe
+  }
+
+  return enablePolling ? pollBlocks() : subscribeBlocks()
+}