viem 1.4.1 → 1.5.0

package/src/actions/public/getTransaction.ts

@@ -11,7 +11,7 @@ import {
   formatTransaction,
 } from '../../utils/formatters/transaction.js'
 
-export type GetTransactionParameters =
+export type GetTransactionParameters<TBlockTag extends BlockTag = 'latest'> =
   | {
       /** The block hash */
       blockHash: Hash
@@ -34,7 +34,7 @@ export type GetTransactionParameters =
       blockHash?: never
       blockNumber?: never
       /** The block tag. */
-      blockTag: BlockTag
+      blockTag: TBlockTag | BlockTag
       hash?: never
       /** The index of the transaction on the block. */
       index: number
@@ -48,8 +48,10 @@ export type GetTransactionParameters =
       index?: number
     }
 
-export type GetTransactionReturnType<TChain extends Chain | undefined = Chain> =
-  FormattedTransaction<TChain>
+export type GetTransactionReturnType<
+  TChain extends Chain | undefined = Chain,
+  TBlockTag extends BlockTag = 'latest',
+> = FormattedTransaction<TChain, TBlockTag>
 
 /**
  * Returns information about a [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) given a hash or block identifier.
@@ -75,16 +77,21 @@ export type GetTransactionReturnType<TChain extends Chain | undefined = Chain> =
  *   hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  * })
  */
-export async function getTransaction<TChain extends Chain | undefined>(
+export async function getTransaction<
+  TChain extends Chain | undefined,
+  TBlockTag extends BlockTag = 'latest',
+>(
   client: Client<Transport, TChain>,
   {
     blockHash,
     blockNumber,
-    blockTag = 'latest',
+    blockTag: blockTag_,
     hash,
     index,
-  }: GetTransactionParameters,
-): Promise<GetTransactionReturnType<TChain>> {
+  }: GetTransactionParameters<TBlockTag>,
+): Promise<GetTransactionReturnType<TChain, TBlockTag>> {
+  const blockTag = blockTag_ || 'latest'
+
   const blockNumberHex =
     blockNumber !== undefined ? numberToHex(blockNumber) : undefined
 

package/src/actions/public/watchBlockNumber.ts

@@ -105,7 +105,7 @@ export function watchBlockNumber<
       poll(
         async () => {
           try {
-            const blockNumber = await getBlockNumber(client, { maxAge: 0 })
+            const blockNumber = await getBlockNumber(client, { cacheTime: 0 })
 
             if (prevBlockNumber) {
               // If the current block number is the same as the previous,

package/src/actions/public/watchBlocks.ts

@@ -10,23 +10,35 @@ import { stringify } from '../../utils/stringify.js'
 
 import { type GetBlockReturnType, getBlock } from './getBlock.js'
 
-export type OnBlockParameter<TChain extends Chain | undefined = Chain> =
-  GetBlockReturnType<TChain>
+export type OnBlockParameter<
+  TChain extends Chain | undefined = Chain,
+  TIncludeTransactions extends boolean = false,
+  TBlockTag extends BlockTag = 'latest',
+> = GetBlockReturnType<TChain, TIncludeTransactions, TBlockTag>
 
-export type OnBlock<TChain extends Chain | undefined = Chain> = (
-  block: OnBlockParameter<TChain>,
-  prevBlock: OnBlockParameter<TChain> | undefined,
+export type OnBlock<
+  TChain extends Chain | undefined = Chain,
+  TIncludeTransactions extends boolean = false,
+  TBlockTag extends BlockTag = 'latest',
+> = (
+  block: OnBlockParameter<TChain, TIncludeTransactions, TBlockTag>,
+  prevBlock:
+    | OnBlockParameter<TChain, TIncludeTransactions, TBlockTag>
+    | undefined,
 ) => void
 
-type PollOptions = {
+type PollOptions<
+  TIncludeTransactions extends boolean = false,
+  TBlockTag extends BlockTag = 'latest',
+> = {
   /** The block tag. Defaults to "latest". */
-  blockTag?: BlockTag
+  blockTag?: TBlockTag | 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
+  includeTransactions?: TIncludeTransactions
   /** Polling frequency (in ms). Defaults to the client's pollingInterval config. */
   pollingInterval?: number
 }
@@ -34,9 +46,11 @@ type PollOptions = {
 export type WatchBlocksParameters<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain,
+  TIncludeTransactions extends boolean = false,
+  TBlockTag extends BlockTag = 'latest',
 > = {
   /** The callback to call when a new block is received. */
-  onBlock: OnBlock<TChain>
+  onBlock: OnBlock<TChain, TIncludeTransactions, TBlockTag>
   /** 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'
@@ -50,8 +64,8 @@ export type WatchBlocksParameters<
           poll?: false
           pollingInterval?: never
         }
-      | (PollOptions & { poll?: true })
-  : PollOptions & { poll?: true })
+      | (PollOptions<TIncludeTransactions, TBlockTag> & { poll?: true })
+  : PollOptions<TIncludeTransactions, TBlockTag> & { poll?: true })
 
 export type WatchBlocksReturnType = () => void
 
@@ -83,6 +97,8 @@ export type WatchBlocksReturnType = () => void
 export function watchBlocks<
   TTransport extends Transport,
   TChain extends Chain | undefined,
+  TIncludeTransactions extends boolean = false,
+  TBlockTag extends BlockTag = 'latest',
 >(
   client: Client<TTransport, TChain>,
   {
@@ -91,15 +107,18 @@ export function watchBlocks<
     emitOnBegin = false,
     onBlock,
     onError,
-    includeTransactions = false,
+    includeTransactions: includeTransactions_,
     poll: poll_,
     pollingInterval = client.pollingInterval,
-  }: WatchBlocksParameters<TTransport, TChain>,
+  }: WatchBlocksParameters<TTransport, TChain, TIncludeTransactions, TBlockTag>,
 ): WatchBlocksReturnType {
   const enablePolling =
     typeof poll_ !== 'undefined' ? poll_ : client.transport.type !== 'webSocket'
+  const includeTransactions = includeTransactions_ ?? false
 
-  let prevBlock: GetBlockReturnType<TChain> | undefined
+  let prevBlock:
+    | GetBlockReturnType<TChain, false | TIncludeTransactions, 'latest'>
+    | undefined
 
   const pollBlocks = () => {
     const observerId = stringify([
@@ -132,7 +151,7 @@ export function watchBlocks<
                     blockNumber: i,
                     includeTransactions,
                   })
-                  emit.onBlock(block, prevBlock)
+                  emit.onBlock(block as any, prevBlock as any)
                   prevBlock = block
                 }
               }
@@ -147,8 +166,8 @@ export function watchBlocks<
               // We don't want to emit blocks in the past.
               (block.number && block.number > prevBlock.number)
             ) {
-              emit.onBlock(block, prevBlock)
-              prevBlock = block
+              emit.onBlock(block as any, prevBlock as any)
+              prevBlock = block as any
             }
           } catch (err) {
             emit.onError?.(err as Error)
@@ -174,7 +193,7 @@ export function watchBlocks<
             const format =
               client.chain?.formatters?.block?.format || formatBlock
             const block = format(data.result)
-            onBlock(block, prevBlock)
+            onBlock(block, prevBlock as any)
             prevBlock = block
           },
           onError(error: Error) {

package/src/actions/public/watchContractEvent.ts

@@ -1,4 +1,4 @@
-import type { Abi, Address, ExtractAbiEvent, Narrow } from 'abitype'
+import type { Abi, AbiEvent, Address, ExtractAbiEvent, Narrow } from 'abitype'
 
 import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
@@ -20,21 +20,21 @@ import {
 } from './createContractEventFilter.js'
 import { getBlockNumber } from './getBlockNumber.js'
 import { getFilterChanges } from './getFilterChanges.js'
-import { type GetLogsParameters, getLogs } from './getLogs.js'
+import { getLogs } from './getLogs.js'
 import { uninstallFilter } from './uninstallFilter.js'
 
-export type OnLogsParameter<
+export type WatchContractEventOnLogsParameter<
   TAbi extends Abi | readonly unknown[] = readonly unknown[],
   TEventName extends string = string,
   TStrict extends boolean | undefined = undefined,
 > = TAbi extends Abi
-  ? Log<bigint, number, ExtractAbiEvent<TAbi, TEventName>, TStrict>[]
+  ? Log<bigint, number, false, ExtractAbiEvent<TAbi, TEventName>, TStrict>[]
   : Log[]
-export type OnLogsFn<
+export type WatchContractEventOnLogsFn<
   TAbi extends Abi | readonly unknown[] = readonly unknown[],
   TEventName extends string = string,
   TStrict extends boolean | undefined = undefined,
-> = (logs: OnLogsParameter<TAbi, TEventName, TStrict>) => void
+> = (logs: WatchContractEventOnLogsParameter<TAbi, TEventName, TStrict>) => void
 
 export type WatchContractEventParameters<
   TAbi extends Abi | readonly unknown[] = readonly unknown[],
@@ -53,7 +53,7 @@ export type WatchContractEventParameters<
   /** The callback to call when an error occurred when trying to get for a new block. */
   onError?: (error: Error) => void
   /** The callback to call when new event logs are received. */
-  onLogs: OnLogsFn<TAbi, TEventName, TStrict>
+  onLogs: WatchContractEventOnLogsFn<TAbi, TEventName, TStrict>
   /** Polling frequency (in ms). Defaults to Client's pollingInterval config. */
   pollingInterval?: number
   /**
@@ -173,8 +173,8 @@ export function watchContractEvent<
                 event: getAbiItem({
                   abi,
                   name: eventName,
-                } as unknown as GetAbiItemParameters),
-              } as unknown as GetLogsParameters)
+                } as unknown as GetAbiItemParameters) as AbiEvent,
+              })
             } else {
               logs = []
             }

package/src/actions/public/watchEvent.ts

@@ -1,4 +1,4 @@
-import type { AbiEvent, Address } from 'abitype'
+import type { AbiEvent, Address, Narrow } from 'abitype'
 
 import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
@@ -19,24 +19,38 @@ import {
 } from './createEventFilter.js'
 import { getBlockNumber } from './getBlockNumber.js'
 import { getFilterChanges } from './getFilterChanges.js'
-import { getLogs } from './getLogs.js'
+import { type GetLogsParameters, getLogs } from './getLogs.js'
 import { uninstallFilter } from './uninstallFilter.js'
 
-export type OnLogsParameter<
+export type WatchEventOnLogsParameter<
   TAbiEvent extends AbiEvent | undefined = undefined,
+  TAbiEvents extends
+    | readonly AbiEvent[]
+    | readonly unknown[]
+    | undefined = TAbiEvent extends AbiEvent ? [TAbiEvent] : undefined,
   TStrict extends boolean | undefined = undefined,
   TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
-> = Log<bigint, number, TAbiEvent, TStrict, [TAbiEvent], TEventName>[]
-export type OnLogsFn<
+> = Log<bigint, number, false, TAbiEvent, TStrict, TAbiEvents, TEventName>[]
+export type WatchEventOnLogsFn<
   TAbiEvent extends AbiEvent | undefined = undefined,
+  TAbiEvents extends
+    | readonly AbiEvent[]
+    | readonly unknown[]
+    | undefined = TAbiEvent extends AbiEvent ? [TAbiEvent] : undefined,
   TStrict extends boolean | undefined = undefined,
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
-> = (logs: OnLogsParameter<TAbiEvent, TStrict, TEventName>) => void
+  _EventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+> = (
+  logs: WatchEventOnLogsParameter<TAbiEvent, TAbiEvents, TStrict, _EventName>,
+) => void
 
 export type WatchEventParameters<
   TAbiEvent extends AbiEvent | undefined = undefined,
+  TAbiEvents extends
+    | readonly AbiEvent[]
+    | readonly unknown[]
+    | undefined = TAbiEvent extends AbiEvent ? [TAbiEvent] : undefined,
   TStrict extends boolean | undefined = undefined,
-  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
+  _EventName extends string | undefined = MaybeAbiEventName<TAbiEvent>,
 > = {
   /** The address of the contract. */
   address?: Address | Address[]
@@ -48,13 +62,24 @@ export type WatchEventParameters<
   /** The callback to call when an error occurred when trying to get for a new block. */
   onError?: (error: Error) => void
   /** The callback to call when new event logs are received. */
-  onLogs: OnLogsFn<TAbiEvent, TStrict, TEventName>
+  onLogs: WatchEventOnLogsFn<TAbiEvent, TAbiEvents, TStrict, _EventName>
   /** Polling frequency (in ms). Defaults to Client's pollingInterval config. */
   pollingInterval?: number
 } & (
   | {
-      event: TAbiEvent
-      args?: MaybeExtractEventArgsFromAbi<[TAbiEvent], TEventName>
+      event: Narrow<TAbiEvent>
+      events?: never
+      args?: MaybeExtractEventArgsFromAbi<TAbiEvents, _EventName>
+      /**
+       * Whether or not the logs must match the indexed/non-indexed arguments on `event`.
+       * @default false
+       */
+      strict?: TStrict
+    }
+  | {
+      event?: never
+      events?: Narrow<TAbiEvents>
+      args?: never
       /**
        * Whether or not the logs must match the indexed/non-indexed arguments on `event`.
        * @default false
@@ -63,6 +88,7 @@ export type WatchEventParameters<
     }
   | {
       event?: never
+      events?: never
       args?: never
       strict?: never
     }
@@ -104,9 +130,13 @@ export type WatchEventReturnType = () => void
  */
 export function watchEvent<
   TChain extends Chain | undefined,
-  TAbiEvent extends AbiEvent | undefined,
-  TEventName extends string | undefined,
+  TAbiEvent extends AbiEvent | undefined = undefined,
+  TAbiEvents extends
+    | readonly AbiEvent[]
+    | readonly unknown[]
+    | undefined = TAbiEvent extends AbiEvent ? [TAbiEvent] : undefined,
   TStrict extends boolean | undefined = undefined,
+  _EventName extends string | undefined = undefined,
 >(
   client: Client<Transport, TChain>,
   {
@@ -114,11 +144,12 @@ export function watchEvent<
     args,
     batch = true,
     event,
+    events,
     onError,
     onLogs,
     pollingInterval = client.pollingInterval,
     strict: strict_,
-  }: WatchEventParameters<TAbiEvent, TStrict>,
+  }: WatchEventParameters<TAbiEvent, TAbiEvents, TStrict>,
 ): WatchEventReturnType {
   const observerId = stringify([
     'watchEvent',
@@ -133,7 +164,7 @@ export function watchEvent<
 
   return observe(observerId, { onLogs, onError }, (emit) => {
     let previousBlockNumber: bigint
-    let filter: Filter<'event', [TAbiEvent], TEventName, any>
+    let filter: Filter<'event', TAbiEvents, _EventName, any>
     let initialized = false
 
     const unwatch = poll(
@@ -144,11 +175,12 @@ export function watchEvent<
               address,
               args,
               event: event!,
+              events,
               strict,
             } as unknown as CreateEventFilterParameters)) as unknown as Filter<
               'event',
-              [TAbiEvent],
-              TEventName
+              TAbiEvents,
+              _EventName
             >
           } catch {}
           initialized = true
@@ -173,10 +205,11 @@ export function watchEvent<
               logs = await getLogs(client, {
                 address,
                 args,
+                event: event!,
+                events,
                 fromBlock: previousBlockNumber + 1n,
                 toBlock: blockNumber,
-                event: event!,
-              })
+              } as unknown as GetLogsParameters)
             } else {
               logs = []
             }

package/src/clients/createClient.ts

@@ -29,6 +29,11 @@ export type ClientConfig<
         multicall?: boolean | Prettify<MulticallBatchOptions> | undefined
       }
     | undefined
+  /**
+   * Time (in ms) that cached data will remain in memory.
+   * @default 4_000
+   */
+  cacheTime?: number | undefined
   /** Chain for the client. */
   chain?: Chain | undefined | chain
   /** A key for the client. */
@@ -79,6 +84,8 @@ type Client_Base<
   account: account
   /** Flags for batch settings. */
   batch?: ClientConfig['batch']
+  /** Time (in ms) that cached data will remain in memory. */
+  cacheTime: number
   /** Chain for the client. */
   chain: chain
   /** A key for the client. */
@@ -135,6 +142,7 @@ export function createClient<
 export function createClient(parameters: ClientConfig): Client {
   const {
     batch,
+    cacheTime = parameters.pollingInterval ?? 4_000,
     key = 'base',
     name = 'Base Client',
     pollingInterval = 4_000,
@@ -154,6 +162,7 @@ export function createClient(parameters: ClientConfig): Client {
   const client = {
     account,
     batch,
+    cacheTime,
     chain,
     key,
     name,

package/src/clients/createPublicClient.ts

@@ -11,7 +11,13 @@ export type PublicClientConfig<
 > = Prettify<
   Pick<
     ClientConfig<transport, chain>,
-    'batch' | 'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+    | 'batch'
+    | 'cacheTime'
+    | 'chain'
+    | 'key'
+    | 'name'
+    | 'pollingInterval'
+    | 'transport'
   >
 >
 

package/src/clients/createTestClient.ts

@@ -21,7 +21,13 @@ export type TestClientConfig<
 > = Prettify<
   Pick<
     ClientConfig<transport, chain, accountOrAddress>,
-    'account' | 'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+    | 'account'
+    | 'cacheTime'
+    | 'chain'
+    | 'key'
+    | 'name'
+    | 'pollingInterval'
+    | 'transport'
   > & {
     /** Mode of the test client. */
     mode: mode | ('anvil' | 'hardhat' | 'ganache') // TODO: Type utility that expands `TestClientMode`

package/src/clients/createWalletClient.ts

@@ -19,7 +19,13 @@ export type WalletClientConfig<
 > = Prettify<
   Pick<
     ClientConfig<transport, chain, accountOrAddress>,
-    'account' | 'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+    | 'account'
+    | 'cacheTime'
+    | 'chain'
+    | 'key'
+    | 'name'
+    | 'pollingInterval'
+    | 'transport'
   >
 >