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

package/src/actions/public/getChainId.ts

@@ -1,21 +1,38 @@
-import type {
-  PublicClient,
-  Transport,
-  WalletClient,
-} from '../../clients/index.js'
-import type { Account, Chain } from '../../types/index.js'
-import { hexToNumber } from '../../utils/index.js'
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Chain } from '../../types/chain.js'
+import { hexToNumber } from '../../utils/encoding/fromHex.js'
 
 export type GetChainIdReturnType = number
 
+/**
+ * Returns the chain ID associated with the current network.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getChainId.html
+ * - JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid)
+ *
+ * @param client - Client to use
+ * @returns The current chain ID. {@link GetChainIdReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getChainId } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const chainId = await getChainId(client)
+ * // 1
+ */
 export async function getChainId<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined,
->(
-  client:
-    | PublicClient<Transport, TChain>
-    | WalletClient<Transport, TChain, TAccount>,
-): Promise<GetChainIdReturnType> {
-  const chainIdHex = await client.request({ method: 'eth_chainId' })
+>(client: Client<Transport, TChain, TAccount>): Promise<GetChainIdReturnType> {
+  const chainIdHex = await client.request({
+    method: 'eth_chainId',
+  })
   return hexToNumber(chainIdHex)
 }

package/src/actions/public/getFeeHistory.ts

@@ -1,18 +1,31 @@
-import type { PublicClient, Transport } from '../../clients/index.js'
-import type { BlockTag, Chain, FeeHistory } from '../../types/index.js'
-
-import { numberToHex } from '../../utils/index.js'
-import { formatFeeHistory } from '../../utils/formatters/index.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 type { FeeHistory } from '../../types/fee.js'
+import { numberToHex } from '../../utils/encoding/toHex.js'
+import { formatFeeHistory } from '../../utils/formatters/feeHistory.js'
 
 export type GetFeeHistoryParameters = {
+  /**
+   * Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. Less than requested may be returned if not all blocks are available.
+   */
   blockCount: number
+  /**
+   * A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas in ascending order, weighted by gas used.
+   */
   rewardPercentiles: number[]
 } & (
   | {
       blockNumber?: never
+      /**
+       * Highest number block of the requested range.
+       * @default 'latest'
+       */
       blockTag?: BlockTag
     }
   | {
+      /** Highest number block of the requested range. */
       blockNumber?: bigint
       blockTag?: never
     }
@@ -20,10 +33,31 @@ export type GetFeeHistoryParameters = {
 export type GetFeeHistoryReturnType = FeeHistory
 
 /**
- * @description Returns a collection of historical gas information.
+ * Returns a collection of historical gas information.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getFeeHistory.html
+ * - JSON-RPC Methods: [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetFeeHistoryParameters}
+ * @returns The gas estimate (in wei). {@link GetFeeHistoryReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getFeeHistory } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const feeHistory = await getFeeHistory(client, {
+ *   blockCount: 4,
+ *   rewardPercentiles: [25, 75],
+ * })
  */
 export async function getFeeHistory<TChain extends Chain | undefined>(
-  client: PublicClient<Transport, TChain>,
+  client: Client<Transport, TChain>,
   {
     blockCount,
     blockNumber,

package/src/actions/public/getFilterChanges.ts

@@ -1,62 +1,177 @@
-import type { Abi, AbiEvent } from 'abitype'
-import type { PublicClient, Transport } from '../../clients/index.js'
-import type {
-  Chain,
-  Filter,
-  FilterType,
-  Hash,
-  Log,
-  MaybeAbiEventName,
-} from '../../types/index.js'
-import { decodeEventLog } from '../../utils/index.js'
+import type { Abi, AbiEvent, ExtractAbiEvent } 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 { Chain } from '../../types/chain.js'
+import type { Filter, FilterType } from '../../types/filter.js'
+import type { Log } from '../../types/log.js'
+import type { Hash } from '../../types/misc.js'
+import { decodeEventLog } from '../../utils/abi/decodeEventLog.js'
 import { formatLog } from '../../utils/formatters/log.js'
 
 export type GetFilterChangesParameters<
   TFilterType extends FilterType = FilterType,
-  TAbiEvent extends AbiEvent | undefined = undefined,
-  TAbi extends Abi | readonly unknown[] = [TAbiEvent],
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TEventName extends string | undefined = string,
+  TStrict extends boolean | undefined = undefined,
 > = {
-  filter: Filter<TFilterType, TAbi, TEventName, any>
+  filter: Filter<TFilterType, TAbi, TEventName, any, TStrict>
 }
 
 export type GetFilterChangesReturnType<
   TFilterType extends FilterType = FilterType,
-  TAbiEvent extends AbiEvent | undefined = undefined,
-  TAbi extends Abi | readonly unknown[] = [TAbiEvent],
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TEventName extends string | undefined = string,
+  TStrict extends boolean | undefined = undefined,
+  _AbiEvent extends AbiEvent | undefined = TAbi extends Abi
+    ? TEventName extends string
+      ? ExtractAbiEvent<TAbi, TEventName>
+      : undefined
+    : undefined,
 > = TFilterType extends 'event'
-  ? Log<bigint, number, TAbiEvent, TAbi, TEventName>[]
+  ? Log<bigint, number, _AbiEvent, TStrict, TAbi, TEventName>[]
   : Hash[]
 
+/**
+ * Returns a list of logs or hashes based on a [Filter](/docs/glossary/terms#filter) since the last time it was called.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getFilterChanges.html
+ * - JSON-RPC Methods: [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges)
+ *
+ * A Filter can be created from the following actions:
+ *
+ * - [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter.html)
+ * - [`createContractEventFilter`](https://viem.sh/docs/contract/createContractEventFilter.html)
+ * - [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter.html)
+ * - [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter.html)
+ *
+ * Depending on the type of filter, the return value will be different:
+ *
+ * - If the filter was created with `createContractEventFilter` or `createEventFilter`, it returns a list of logs.
+ * - If the filter was created with `createPendingTransactionFilter`, it returns a list of transaction hashes.
+ * - If the filter was created with `createBlockFilter`, it returns a list of block hashes.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetFilterChangesParameters}
+ * @returns Logs or hashes. {@link GetFilterChangesReturnType}
+ *
+ * @example
+ * // Blocks
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { createBlockFilter, getFilterChanges } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const filter = await createBlockFilter(client)
+ * const hashes = await getFilterChanges(client, { filter })
+ *
+ * @example
+ * // Contract Events
+ * import { createPublicClient, http, parseAbi } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { createContractEventFilter, getFilterChanges } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const filter = await createContractEventFilter(client, {
+ *   address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
+ *   eventName: 'Transfer',
+ * })
+ * const logs = await getFilterChanges(client, { filter })
+ *
+ * @example
+ * // Raw Events
+ * import { createPublicClient, http, parseAbiItem } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { createEventFilter, getFilterChanges } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const filter = await createEventFilter(client, {
+ *   address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
+ * })
+ * const logs = await getFilterChanges(client, { filter })
+ *
+ * @example
+ * // Transactions
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { createPendingTransactionFilter, getFilterChanges } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const filter = await createPendingTransactionFilter(client)
+ * const hashes = await getFilterChanges(client, { filter })
+ */
 export async function getFilterChanges<
   TTransport extends Transport,
   TChain extends Chain | undefined,
   TFilterType extends FilterType,
-  TAbiEvent extends AbiEvent | undefined,
   TAbi extends Abi | readonly unknown[],
   TEventName extends string | undefined,
+  TStrict extends boolean | undefined = undefined,
 >(
-  client: PublicClient<TTransport, TChain>,
+  _client: Client<TTransport, TChain>,
   {
     filter,
-  }: GetFilterChangesParameters<TFilterType, TAbiEvent, TAbi, TEventName>,
+  }: GetFilterChangesParameters<TFilterType, TAbi, TEventName, TStrict>,
 ) {
-  const logs = await client.request({
+  const strict = 'strict' in filter && filter.strict
+
+  const logs = await filter.request({
     method: 'eth_getFilterChanges',
     params: [filter.id],
   })
-  return logs.map((log) => {
-    if (typeof log === 'string') return log
-    const { eventName, args } =
-      'abi' in filter && filter.abi
-        ? decodeEventLog({
-            abi: filter.abi,
-            data: log.data,
-            topics: log.topics as any,
-          })
-        : { eventName: undefined, args: undefined }
-    return formatLog(log, { args, eventName })
-  }) as GetFilterChangesReturnType<TFilterType, TAbiEvent, TAbi, TEventName>
+  return logs
+    .map((log) => {
+      if (typeof log === 'string') return log
+      try {
+        const { eventName, args } =
+          'abi' in filter && filter.abi
+            ? decodeEventLog({
+                abi: filter.abi,
+                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' in filter && filter.strict) return
+          eventName = err.abiItem.name
+          isUnnamed = err.abiItem.inputs?.some((x) => !('name' in x && x.name))
+        }
+
+        // Set args undefined if there is an error decoding (e.g. indexed/non-indexed params mismatch).
+        return formatLog(log, { args: isUnnamed ? [] : {}, eventName })
+      }
+    })
+    .filter(Boolean) as GetFilterChangesReturnType<
+    TFilterType,
+    TAbi,
+    TEventName,
+    TStrict
+  >
 }

package/src/actions/public/getFilterLogs.ts

@@ -1,50 +1,110 @@
-import type { Abi, AbiEvent } from 'abitype'
-import type { PublicClient, Transport } from '../../clients/index.js'
-import type {
-  Chain,
-  Filter,
-  Log,
-  MaybeAbiEventName,
-} from '../../types/index.js'
-import { decodeEventLog } from '../../utils/index.js'
+import type { Abi, AbiEvent, ExtractAbiEvent } 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 { Chain } from '../../types/chain.js'
+import type { Filter } from '../../types/filter.js'
+import type { Log } from '../../types/log.js'
+import { decodeEventLog } from '../../utils/abi/decodeEventLog.js'
 import { formatLog } from '../../utils/formatters/log.js'
 
 export type GetFilterLogsParameters<
-  TAbiEvent extends AbiEvent | undefined = undefined,
-  TAbi extends Abi | readonly unknown[] = [TAbiEvent],
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TEventName extends string | undefined = string,
+  TStrict extends boolean | undefined = undefined,
 > = {
-  filter: Filter<'event', TAbi, TEventName, any>
+  filter: Filter<'event', TAbi, TEventName, any, TStrict>
 }
 export type GetFilterLogsReturnType<
-  TAbiEvent extends AbiEvent | undefined = undefined,
-  TAbi extends Abi | readonly unknown[] = [TAbiEvent],
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
-> = Log<bigint, number, TAbiEvent, TAbi, TEventName>[]
+  TAbi extends Abi | readonly unknown[] = Abi,
+  TEventName extends string | undefined = string,
+  TStrict extends boolean | undefined = undefined,
+  _AbiEvent extends AbiEvent | undefined = TAbi extends Abi
+    ? TEventName extends string
+      ? ExtractAbiEvent<TAbi, TEventName>
+      : undefined
+    : undefined,
+> = Log<bigint, number, _AbiEvent, TStrict, TAbi, TEventName>[]
 
+/**
+ * Returns a list of event logs since the filter was created.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getFilterLogs.html
+ * - JSON-RPC Methods: [`eth_getFilterLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterlogs)
+ *
+ * `getFilterLogs` is only compatible with **event filters**.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetFilterLogsParameters}
+ * @returns A list of event logs. {@link GetFilterLogsReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseAbiItem } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { createEventFilter, getFilterLogs } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const filter = await createEventFilter(client, {
+ *   address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
+ * })
+ * const logs = await getFilterLogs(client, { filter })
+ */
 export async function getFilterLogs<
   TChain extends Chain | undefined,
-  TAbiEvent extends AbiEvent | undefined,
   TAbi extends Abi | readonly unknown[],
   TEventName extends string | undefined,
+  TStrict extends boolean | undefined = undefined,
 >(
-  client: PublicClient<Transport, TChain>,
-  { filter }: GetFilterLogsParameters<TAbiEvent, TAbi, TEventName>,
-): Promise<GetFilterLogsReturnType<TAbiEvent, TAbi, TEventName>> {
-  const logs = await client.request({
+  _client: Client<Transport, TChain>,
+  { filter }: GetFilterLogsParameters<TAbi, TEventName, TStrict>,
+): Promise<GetFilterLogsReturnType<TAbi, TEventName, TStrict>> {
+  const strict = filter.strict ?? false
+
+  const logs = await filter.request({
     method: 'eth_getFilterLogs',
     params: [filter.id],
   })
-  return logs.map((log) => {
-    const { eventName, args } =
-      'abi' in filter && filter.abi
-        ? decodeEventLog({
-            abi: filter.abi,
-            data: log.data,
-            topics: log.topics as any,
-          })
-        : { eventName: undefined, args: undefined }
-    return formatLog(log, { args, eventName })
-  }) as unknown as GetFilterLogsReturnType<TAbiEvent, TAbi, TEventName>
+  return logs
+    .map((log) => {
+      try {
+        const { eventName, args } =
+          'abi' in filter && filter.abi
+            ? decodeEventLog({
+                abi: filter.abi,
+                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' in filter && filter.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 GetFilterLogsReturnType<
+    TAbi,
+    TEventName,
+    TStrict
+  >
 }

package/src/actions/public/getGasPrice.ts

@@ -1,23 +1,34 @@
-import type {
-  PublicClient,
-  Transport,
-  WalletClient,
-} from '../../clients/index.js'
-import type { Account, Chain } from '../../types/index.js'
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { Chain } from '../../types/chain.js'
 
 export type GetGasPriceReturnType = bigint
 
 /**
- * @description Returns the current price of gas (in wei).
+ * Returns the current price of gas (in wei).
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getGasPrice.html
+ * - JSON-RPC Methods: [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice)
+ *
+ * @param client - Client to use
+ * @returns The gas price (in wei). {@link GetGasPriceReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getGasPrice } from 'viem/public'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const gasPrice = await getGasPrice(client)
  */
 export async function getGasPrice<
   TChain extends Chain | undefined,
   TAccount extends Account | undefined,
->(
-  client:
-    | PublicClient<Transport, TChain>
-    | WalletClient<Transport, TChain, TAccount>,
-): Promise<GetGasPriceReturnType> {
+>(client: Client<Transport, TChain, TAccount>): Promise<GetGasPriceReturnType> {
   const gasPrice = await client.request({
     method: 'eth_gasPrice',
   })