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

package/src/actions/public/getLogs.ts

@@ -1,39 +1,49 @@
-import type { AbiEvent } from 'abitype'
-import type { PublicClient, Transport } from '../../clients/index.js'
+import type { AbiEvent, Address, Narrow } from 'abitype'
+
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import {
+  DecodeLogDataMismatch,
+  DecodeLogTopicsMismatch,
+} from '../../errors/abi.js'
+import type { BlockNumber, BlockTag } from '../../types/block.js'
+import type { Chain } from '../../types/chain.js'
 import type {
-  Address,
-  BlockNumber,
-  BlockTag,
-  Chain,
-  Hash,
-  Log,
-  LogTopic,
   MaybeAbiEventName,
   MaybeExtractEventArgsFromAbi,
-  RpcLog,
-} from '../../types/index.js'
-import type { EncodeEventTopicsParameters } from '../../utils/index.js'
+} from '../../types/contract.js'
+import type { Log } from '../../types/log.js'
+import type { Hash, LogTopic } from '../../types/misc.js'
+import type { RpcLog } from '../../types/rpc.js'
+import { decodeEventLog } from '../../utils/abi/decodeEventLog.js'
 import {
-  decodeEventLog,
+  type EncodeEventTopicsParameters,
   encodeEventTopics,
-  numberToHex,
-} from '../../utils/index.js'
+} from '../../utils/abi/encodeEventTopics.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 import { formatLog } from '../../utils/formatters/log.js'
 
 export type GetLogsParameters<
   TAbiEvent extends AbiEvent | undefined = undefined,
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+  TStrict extends boolean | undefined = undefined,
+  _EventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
 > = {
   /** Address or list of addresses from which logs originated */
   address?: Address | Address[]
 } & (
   | {
-      event: TAbiEvent
-      args?: MaybeExtractEventArgsFromAbi<[TAbiEvent], TEventName>
+      event: Narrow<TAbiEvent>
+      args?: MaybeExtractEventArgsFromAbi<[TAbiEvent], _EventName>
+      /**
+       * Whether or not the logs must match the indexed/non-indexed arguments on `event`.
+       * @default false
+       */
+      strict?: TStrict
     }
   | {
       event?: never
       args?: never
+      strict?: never
     }
 ) &
   (
@@ -54,17 +64,38 @@ export type GetLogsParameters<
 
 export type GetLogsReturnType<
   TAbiEvent extends AbiEvent | undefined = undefined,
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
-> = Log<bigint, number, TAbiEvent, [TAbiEvent], TEventName>[]
+  TStrict extends boolean | undefined = undefined,
+  _EventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+> = Log<bigint, number, TAbiEvent, TStrict, [TAbiEvent], _EventName>[]
 
 /**
- * @description Returns a collection of event logs.
+ * Returns a list of event logs matching the provided parameters.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getLogs.html
+ * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/filters-and-logs/event-logs
+ * - JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetLogsParameters}
+ * @returns A list of event logs. {@link GetLogsReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseAbiItem } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getLogs } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const logs = await getLogs(client)
  */
 export async function getLogs<
   TChain extends Chain | undefined,
   TAbiEvent extends AbiEvent | undefined,
+  TStrict extends boolean | undefined = undefined,
 >(
-  client: PublicClient<Transport, TChain>,
+  client: Client<Transport, TChain>,
   {
     address,
     blockHash,
@@ -72,13 +103,16 @@ export async function getLogs<
     toBlock,
     event,
     args,
-  }: GetLogsParameters<TAbiEvent> = {},
-): Promise<GetLogsReturnType<TAbiEvent>> {
+    strict: strict_,
+  }: GetLogsParameters<TAbiEvent, TStrict> = {},
+): Promise<GetLogsReturnType<TAbiEvent, TStrict>> {
+  const strict = strict_ ?? false
+
   let topics: LogTopic[] = []
   if (event)
     topics = encodeEventTopics({
       abi: [event],
-      eventName: event.name,
+      eventName: (event as AbiEvent).name,
       args,
     } as EncodeEventTopicsParameters)
 
@@ -102,14 +136,35 @@ export async function getLogs<
       ],
     })
   }
-  return logs.map((log) => {
-    const { eventName, args } = event
-      ? decodeEventLog({
-          abi: [event],
-          data: log.data,
-          topics: log.topics as any,
-        })
-      : { eventName: undefined, args: undefined }
-    return formatLog(log, { args, eventName })
-  }) as unknown as GetLogsReturnType<TAbiEvent>
+
+  return logs
+    .map((log) => {
+      try {
+        const { eventName, args } = event
+          ? decodeEventLog({
+              abi: [event] as [AbiEvent],
+              data: log.data,
+              topics: log.topics as any,
+              strict,
+            })
+          : { eventName: undefined, args: undefined }
+        return formatLog(log, { args, eventName })
+      } catch (err) {
+        let eventName
+        let isUnnamed
+        if (
+          err instanceof DecodeLogDataMismatch ||
+          err instanceof DecodeLogTopicsMismatch
+        ) {
+          // If strict mode is on, and log data/topics do not match event definition, skip.
+          if (strict) return
+          eventName = err.abiItem.name
+          isUnnamed = err.abiItem.inputs?.some((x) => !('name' in x && x.name))
+        }
+
+        // Set args to empty if there is an error decoding (e.g. indexed/non-indexed params mismatch).
+        return formatLog(log, { args: isUnnamed ? [] : {}, eventName })
+      }
+    })
+    .filter(Boolean) as unknown as GetLogsReturnType<TAbiEvent, TStrict>
 }

package/src/actions/public/getStorageAt.ts

@@ -1,6 +1,11 @@
-import type { PublicClient, Transport } from '../../clients/index.js'
-import type { Address, BlockTag, Chain, Hex } from '../../types/index.js'
-import { numberToHex } from '../../utils/index.js'
+import type { Address } from 'abitype'
+
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { BlockTag } from '../../types/block.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hex } from '../../types/misc.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 
 export type GetStorageAtParameters = {
   address: Address
@@ -18,8 +23,32 @@ export type GetStorageAtParameters = {
 
 export type GetStorageAtReturnType = Hex | undefined
 
+/**
+ * Returns the value from a storage slot at a given address.
+ *
+ * - Docs: https://viem.sh/docs/contract/getStorageAt.html
+ * - JSON-RPC Methods: [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetStorageAtParameters}
+ * @returns The value of the storage slot. {@link GetStorageAtReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getStorageAt } from 'viem/contract'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const code = await getStorageAt(client, {
+ *   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+ *   slot: toHex(0),
+ * })
+ */
 export async function getStorageAt<TChain extends Chain | undefined>(
-  client: PublicClient<Transport, TChain>,
+  client: Client<Transport, TChain>,
   { address, blockNumber, blockTag = 'latest', slot }: GetStorageAtParameters,
 ): Promise<GetStorageAtReturnType> {
   const blockNumberHex =

package/src/actions/public/getTransaction.ts

@@ -1,17 +1,15 @@
-import type { PublicClient, Transport } from '../../clients/index.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
 import { TransactionNotFoundError } from '../../errors/transaction.js'
-import type {
-  BlockTag,
-  Chain,
-  Hash,
-  RpcTransaction,
-} from '../../types/index.js'
-import { format, numberToHex } from '../../utils/index.js'
-import type {
-  FormattedTransaction,
-  TransactionFormatter,
+import type { BlockTag } from '../../types/block.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import type { RpcTransaction } from '../../types/rpc.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
+import {
+  type FormattedTransaction,
+  formatTransaction,
 } from '../../utils/formatters/transaction.js'
-import { formatTransaction } from '../../utils/formatters/transaction.js'
 
 export type GetTransactionParameters =
   | {
@@ -51,11 +49,34 @@ export type GetTransactionParameters =
     }
 
 export type GetTransactionReturnType<TChain extends Chain | undefined = Chain> =
-  FormattedTransaction<TransactionFormatter<TChain>>
+  FormattedTransaction<TChain>
 
-/** @description Returns information about a transaction given a hash or block identifier. */
+/**
+ * Returns information about a [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) given a hash or block identifier.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getTransaction.html
+ * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions
+ * - JSON-RPC Methods: [`eth_getTransactionByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionByHash)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetTransactionParameters}
+ * @returns The transaction information. {@link GetTransactionReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getTransaction } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const transaction = await getTransaction(client, {
+ *   hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
+ * })
+ */
 export async function getTransaction<TChain extends Chain | undefined>(
-  client: PublicClient<Transport, TChain>,
+  client: Client<Transport, TChain>,
   {
     blockHash,
     blockNumber,
@@ -94,7 +115,7 @@ export async function getTransaction<TChain extends Chain | undefined>(
       index,
     })
 
-  return format(transaction, {
-    formatter: client.chain?.formatters?.transaction || formatTransaction,
-  })
+  const format =
+    client.chain?.formatters?.transaction?.format || formatTransaction
+  return format(transaction)
 }

package/src/actions/public/getTransactionConfirmations.ts

@@ -1,9 +1,9 @@
-import type { PublicClient, Transport } from '../../clients/index.js'
-import type { Chain, Hash } from '../../types/index.js'
-import type {
-  FormattedTransactionReceipt,
-  TransactionReceiptFormatter,
-} from '../../utils/index.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import type { FormattedTransactionReceipt } from '../../utils/formatters/transactionReceipt.js'
+
 import { getBlockNumber } from './getBlockNumber.js'
 import { getTransaction } from './getTransaction.js'
 
@@ -18,17 +18,39 @@ export type GetTransactionConfirmationsParameters<
   | {
       hash?: never
       /** The transaction receipt. */
-      transactionReceipt: FormattedTransactionReceipt<
-        TransactionReceiptFormatter<TChain>
-      >
+      transactionReceipt: FormattedTransactionReceipt<TChain>
     }
 
 export type GetTransactionConfirmationsReturnType = bigint
 
+/**
+ * Returns the number of blocks passed (confirmations) since the transaction was processed on a block.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getTransactionConfirmations.html
+ * - Example: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/fetching-transactions
+ * - JSON-RPC Methods: [`eth_getTransactionConfirmations`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionConfirmations)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetTransactionConfirmationsParameters}
+ * @returns The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. {@link GetTransactionConfirmationsReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getTransactionConfirmations } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const confirmations = await getTransactionConfirmations(client, {
+ *   hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
+ * })
+ */
 export async function getTransactionConfirmations<
   TChain extends Chain | undefined,
 >(
-  client: PublicClient<Transport, TChain>,
+  client: Client<Transport, TChain>,
   { hash, transactionReceipt }: GetTransactionConfirmationsParameters<TChain>,
 ): Promise<GetTransactionConfirmationsReturnType> {
   const [blockNumber, transaction] = await Promise.all([

package/src/actions/public/getTransactionCount.ts

@@ -1,10 +1,12 @@
-import type {
-  PublicClient,
-  Transport,
-  WalletClient,
-} from '../../clients/index.js'
-import type { Account, Address, BlockTag, Chain } from '../../types/index.js'
-import { hexToNumber, numberToHex } from '../../utils/index.js'
+import type { Address } from 'abitype'
+
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { BlockTag } from '../../types/block.js'
+import type { Chain } from '../../types/chain.js'
+import { hexToNumber } from '../../utils/encoding/fromHex.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
 
 export type GetTransactionCountParameters = {
   /** The account address. */
@@ -24,15 +26,33 @@ export type GetTransactionCountParameters = {
 export type GetTransactionCountReturnType = number
 
 /**
- * @description Returns the number of transactions an account has broadcast / sent.
+ * Returns the number of [Transactions](https://viem.sh/docs/glossary/terms.html#transaction) an Account has broadcast / sent.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getTransactionCount.html
+ * - JSON-RPC Methods: [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetTransactionCountParameters}
+ * @returns The number of transactions an account has sent. {@link GetTransactionCountReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getTransactionCount } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const transactionCount = await getTransactionCount(client, {
+ *   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ * })
  */
 export async function getTransactionCount<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined,
 >(
-  client:
-    | PublicClient<Transport, TChain>
-    | WalletClient<Transport, TChain, TAccount>,
+  client: Client<Transport, TChain, TAccount>,
   { address, blockTag = 'latest', blockNumber }: GetTransactionCountParameters,
 ): Promise<GetTransactionCountReturnType> {
   const count = await client.request({

package/src/actions/public/getTransactionReceipt.ts

@@ -1,12 +1,12 @@
-import type { PublicClient, Transport } from '../../clients/index.js'
-import { TransactionReceiptNotFoundError } from '../../errors/index.js'
-import type { Chain, Hash } from '../../types/index.js'
-import { format } from '../../utils/index.js'
-import type {
-  FormattedTransactionReceipt,
-  TransactionReceiptFormatter,
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { TransactionReceiptNotFoundError } from '../../errors/transaction.js'
+import type { Chain } from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import {
+  type FormattedTransactionReceipt,
+  formatTransactionReceipt,
 } from '../../utils/formatters/transactionReceipt.js'
-import { formatTransactionReceipt } from '../../utils/formatters/transactionReceipt.js'
 
 export type GetTransactionReceiptParameters = {
   /** The hash of the transaction. */
@@ -15,10 +15,34 @@ export type GetTransactionReceiptParameters = {
 
 export type GetTransactionReceiptReturnType<
   TChain extends Chain | undefined = Chain | undefined,
-> = FormattedTransactionReceipt<TransactionReceiptFormatter<TChain>>
+> = FormattedTransactionReceipt<TChain>
 
+/**
+ * Returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms.html#transaction-receipt) given a [Transaction](https://viem.sh/docs/glossary/terms.html#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>,
+  client: Client<Transport, TChain>,
   { hash }: GetTransactionReceiptParameters,
 ) {
   const receipt = await client.request({
@@ -28,8 +52,8 @@ export async function getTransactionReceipt<TChain extends Chain | undefined>(
 
   if (!receipt) throw new TransactionReceiptNotFoundError({ hash })
 
-  return format(receipt, {
-    formatter:
-      client.chain?.formatters?.transactionReceipt || formatTransactionReceipt,
-  }) as GetTransactionReceiptReturnType<TChain>
+  const format =
+    client.chain?.formatters?.transactionReceipt?.format ||
+    formatTransactionReceipt
+  return format(receipt) as GetTransactionReceiptReturnType<TChain>
 }