viem 2.49.3 → 2.50.3

package/actions/public/call.ts

@@ -33,8 +33,11 @@ import {
 import type { BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
 import type { EIP1193RequestOptions } from '../../types/eip1193.js'
-import type { Hex } from '../../types/misc.js'
-import type { RpcTransactionRequest } from '../../types/rpc.js'
+import type { Hash, Hex } from '../../types/misc.js'
+import type {
+  RpcStateOverride,
+  RpcTransactionRequest,
+} from '../../types/rpc.js'
 import type { StateOverride } from '../../types/stateOverride.js'
 import type { TransactionRequest } from '../../types/transaction.js'
 import type { ExactPartial, UnionOmit } from '../../types/utils.js'
@@ -50,15 +53,16 @@ import {
   type EncodeFunctionDataErrorType,
   encodeFunctionData,
 } from '../../utils/abi/encodeFunctionData.js'
+import { isAddressEqual } from '../../utils/address/isAddressEqual.js'
+import {
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
 import type { RequestErrorType } from '../../utils/buildRequest.js'
 import {
   type GetChainContractAddressErrorType,
   getChainContractAddress,
 } from '../../utils/chain/getChainContractAddress.js'
-import {
-  type NumberToHexErrorType,
-  numberToHex,
-} from '../../utils/encoding/toHex.js'
 import {
   type GetCallErrorReturnType,
   getCallError,
@@ -104,17 +108,29 @@ export type CallParameters<
   stateOverride?: StateOverride | undefined
 } & (
     | {
-        /** The balance of the account at a block number. */
+        /** The block number to perform the call against. */
         blockNumber?: bigint | undefined
         blockTag?: undefined
+        blockHash?: undefined
+        requireCanonical?: undefined
       }
     | {
         blockNumber?: undefined
         /**
-         * The balance of the account at a block tag.
+         * The block tag to perform the call against.
          * @default 'latest'
          */
         blockTag?: BlockTag | undefined
+        blockHash?: undefined
+        requireCanonical?: undefined
+      }
+    | {
+        blockNumber?: undefined
+        blockTag?: undefined
+        /** The block hash to perform the call against. */
+        blockHash: Hash
+        /** Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. */
+        requireCanonical?: boolean | undefined
       }
   )
 type FormattedCall<chain extends Chain | undefined = Chain | undefined> =
@@ -126,7 +142,7 @@ export type CallErrorType = GetCallErrorReturnType<
   | ParseAccountErrorType
   | SerializeStateOverrideErrorType
   | AssertRequestErrorType
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | FormatTransactionRequestErrorType
   | ScheduleMulticallErrorType
   | RequestErrorType
@@ -167,8 +183,10 @@ export async function call<chain extends Chain | undefined>(
     account: account_ = client.account,
     authorizationList,
     batch = Boolean(client.batch?.multicall),
+    blockHash,
     blockNumber,
     blockTag = client.experimental_blockTag ?? 'latest',
+    requireCanonical,
     accessList,
     blobs,
     blockOverrides,
@@ -222,9 +240,12 @@ export async function call<chain extends Chain | undefined>(
   try {
     assertRequest(args as AssertRequestParameters)
 
-    const blockNumberHex =
-      typeof blockNumber === 'bigint' ? numberToHex(blockNumber) : undefined
-    const block = blockNumberHex || blockTag
+    const block = formatBlockParameter({
+      blockHash,
+      blockNumber,
+      blockTag,
+      requireCanonical,
+    })
 
     const rpcBlockOverrides = blockOverrides
       ? BlockOverrides.toRpc(blockOverrides)
@@ -258,16 +279,33 @@ export async function call<chain extends Chain | undefined>(
     if (
       batch &&
       shouldPerformMulticall({ request }) &&
-      !rpcStateOverride &&
-      !rpcBlockOverrides
+      !rpcBlockOverrides &&
+      blockHash === undefined
     ) {
       try {
-        return await scheduleMulticall(client, {
-          ...request,
+        const { deployless = false } =
+          typeof client.batch?.multicall === 'object'
+            ? client.batch.multicall
+            : {}
+        const multicallAddress = getMulticallAddress(client, {
           blockNumber,
-          blockTag,
-          requestOptions,
-        } as unknown as ScheduleMulticallParameters<chain>)
+          deployless,
+        })
+
+        if (
+          !multicallAddress ||
+          !hasStateOverrideForAddress(rpcStateOverride, multicallAddress)
+        )
+          return await scheduleMulticall(client, {
+            ...request,
+            blockHash,
+            blockNumber,
+            blockTag,
+            multicallAddress,
+            requestOptions,
+            requireCanonical,
+            rpcStateOverride,
+          } as unknown as ScheduleMulticallParameters<chain>)
       } catch (err) {
         if (
           !(err instanceof ClientChainNotConfiguredError) &&
@@ -362,17 +400,18 @@ function getRequestOptionsId(
 
 type ScheduleMulticallParameters<chain extends Chain | undefined> = Pick<
   CallParameters<chain>,
-  'blockNumber' | 'blockTag'
+  'blockHash' | 'blockNumber' | 'blockTag' | 'requireCanonical'
 > & {
   data: Hex
-  multicallAddress?: Address | undefined
+  multicallAddress?: Address | null | undefined
   requestOptions?: EIP1193RequestOptions | undefined
   to: Address
+  rpcStateOverride?: RpcStateOverride | undefined
 }
 
 type ScheduleMulticallErrorType =
   | GetChainContractAddressErrorType
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | CreateBatchSchedulerErrorType
   | EncodeFunctionDataErrorType
   | DecodeFunctionResultErrorType
@@ -389,32 +428,39 @@ async function scheduleMulticall<chain extends Chain | undefined>(
     wait = 0,
   } = typeof client.batch?.multicall === 'object' ? client.batch.multicall : {}
   const {
+    blockHash,
     blockNumber,
     blockTag = client.experimental_blockTag ?? 'latest',
+    requireCanonical,
     data,
+    multicallAddress: multicallAddress_,
     requestOptions,
+    rpcStateOverride,
     to,
   } = args
 
-  const multicallAddress = (() => {
-    if (deployless) return null
-    if (args.multicallAddress) return args.multicallAddress
-    if (client.chain) {
-      return getChainContractAddress({
-        blockNumber,
-        chain: client.chain,
-        contract: 'multicall3',
-      })
-    }
-    throw new ClientChainNotConfiguredError()
-  })()
+  const multicallAddress =
+    multicallAddress_ !== undefined
+      ? multicallAddress_
+      : getMulticallAddress(client, {
+          blockNumber,
+          deployless,
+        })
+
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
+  const blockId = typeof block === 'string' ? block : JSON.stringify(block)
 
-  const blockNumberHex =
-    typeof blockNumber === 'bigint' ? numberToHex(blockNumber) : undefined
-  const block = blockNumberHex || blockTag
+  const stateOverrideKey = rpcStateOverride
+    ? `.${JSON.stringify(rpcStateOverride)}`
+    : ''
 
   const { schedule } = createBatchScheduler({
-    id: `${client.uid}.${block}.${getRequestOptionsId(requestOptions)}`,
+    id: `${client.uid}.${blockId}.${getRequestOptionsId(requestOptions)}${stateOverrideKey}`,
     wait,
     shouldSplitBatch(args) {
       const size = args.reduce((size, { data }) => size + (data.length - 2), 0)
@@ -438,22 +484,22 @@ async function scheduleMulticall<chain extends Chain | undefined>(
         functionName: 'aggregate3',
       })
 
+      const multicallRequest = {
+        ...(multicallAddress === null
+          ? {
+              data: toDeploylessCallViaBytecodeData({
+                code: multicall3Bytecode,
+                data: calldata,
+              }),
+            }
+          : { to: multicallAddress, data: calldata }),
+      }
       const data = await client.request(
         {
           method: 'eth_call',
-          params: [
-            {
-              ...(multicallAddress === null
-                ? {
-                    data: toDeploylessCallViaBytecodeData({
-                      code: multicall3Bytecode,
-                      data: calldata,
-                    }),
-                  }
-                : { to: multicallAddress, data: calldata }),
-            },
-            block,
-          ],
+          params: rpcStateOverride
+            ? [multicallRequest, block, rpcStateOverride]
+            : [multicallRequest, block],
         },
         requestOptions,
       )
@@ -474,6 +520,34 @@ async function scheduleMulticall<chain extends Chain | undefined>(
   return { data: returnData }
 }
 
+function getMulticallAddress(
+  client: Client<Transport>,
+  parameters: {
+    blockNumber?: bigint | undefined
+    deployless?: boolean | undefined
+  },
+): Address | null {
+  const { blockNumber, deployless } = parameters
+  if (deployless) return null
+  if (client.chain)
+    return getChainContractAddress({
+      blockNumber,
+      chain: client.chain,
+      contract: 'multicall3',
+    })
+  throw new ClientChainNotConfiguredError()
+}
+
+function hasStateOverrideForAddress(
+  rpcStateOverride: RpcStateOverride | undefined,
+  address: Address,
+) {
+  if (!rpcStateOverride) return false
+  return Object.keys(rpcStateOverride).some((stateOverrideAddress) =>
+    isAddressEqual(stateOverrideAddress as Address, address),
+  )
+}
+
 type ToDeploylessCallViaBytecodeDataErrorType =
   | EncodeDeployDataErrorType
   | ErrorType

package/actions/public/getBalance.ts

@@ -6,13 +6,14 @@ import { multicall3Abi } from '../../constants/abis.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
 import { decodeFunctionResult } from '../../utils/abi/decodeFunctionResult.js'
 import { encodeFunctionData } from '../../utils/abi/encodeFunctionData.js'
-import type { RequestErrorType } from '../../utils/buildRequest.js'
 import {
-  type NumberToHexErrorType,
-  numberToHex,
-} from '../../utils/encoding/toHex.js'
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
 import { getAction } from '../../utils/getAction.js'
 import { type CallParameters, call } from './call.js'
 
@@ -24,18 +25,30 @@ export type GetBalanceParameters = {
       /** The balance of the account at a block number. */
       blockNumber?: bigint | undefined
       blockTag?: undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
     }
   | {
       blockNumber?: undefined
       /** The balance of the account at a block tag. */
       blockTag?: BlockTag | undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: undefined
+      blockTag?: undefined
+      /** The balance of the account at a block specified by block hash. */
+      blockHash: Hash
+      /** Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. */
+      requireCanonical?: boolean | undefined
     }
 )
 
 export type GetBalanceReturnType = bigint
 
 export type GetBalanceErrorType =
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | RequestErrorType
   | ErrorType
 
@@ -78,10 +91,19 @@ export async function getBalance<chain extends Chain | undefined>(
   client: Client<Transport, chain>,
   {
     address,
+    blockHash,
     blockNumber,
     blockTag = client.experimental_blockTag ?? 'latest',
+    requireCanonical,
   }: GetBalanceParameters,
 ): Promise<GetBalanceReturnType> {
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
+
   if (client.batch?.multicall && client.chain?.contracts?.multicall3) {
     const multicall3Address = client.chain.contracts.multicall3.address
 
@@ -98,8 +120,10 @@ export async function getBalance<chain extends Chain | undefined>(
     )({
       to: multicall3Address,
       data: calldata,
+      blockHash,
       blockNumber,
       blockTag,
+      requireCanonical,
     } as unknown as CallParameters<chain>)
 
     return decodeFunctionResult({
@@ -110,12 +134,9 @@ export async function getBalance<chain extends Chain | undefined>(
     })
   }
 
-  const blockNumberHex =
-    typeof blockNumber === 'bigint' ? numberToHex(blockNumber) : undefined
-
   const balance = await client.request({
     method: 'eth_getBalance',
-    params: [address, blockNumberHex || blockTag],
+    params: [address, block],
   })
   return BigInt(balance)
 }

package/actions/public/getCode.ts

@@ -5,12 +5,12 @@ import type { Transport } from '../../clients/transports/createTransport.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
-import type { Hex } from '../../types/misc.js'
-import type { RequestErrorType } from '../../utils/buildRequest.js'
+import type { Hash, Hex } from '../../types/misc.js'
 import {
-  type NumberToHexErrorType,
-  numberToHex,
-} from '../../utils/encoding/toHex.js'
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
 
 export type GetCodeParameters = {
   address: Address
@@ -18,17 +18,29 @@ export type GetCodeParameters = {
   | {
       blockNumber?: undefined
       blockTag?: BlockTag | undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
     }
   | {
       blockNumber?: bigint | undefined
       blockTag?: undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: undefined
+      blockTag?: undefined
+      /** The bytecode at a block specified by block hash. */
+      blockHash: Hash
+      /** Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. */
+      requireCanonical?: boolean | undefined
     }
 )
 
 export type GetCodeReturnType = Hex | undefined
 
 export type GetCodeErrorType =
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | RequestErrorType
   | ErrorType
 
@@ -57,16 +69,28 @@ export type GetCodeErrorType =
  */
 export async function getCode<chain extends Chain | undefined>(
   client: Client<Transport, chain>,
-  { address, blockNumber, blockTag = 'latest' }: GetCodeParameters,
+  {
+    address,
+    blockHash,
+    blockNumber,
+    blockTag = 'latest',
+    requireCanonical,
+  }: GetCodeParameters,
 ): Promise<GetCodeReturnType> {
-  const blockNumberHex =
-    blockNumber !== undefined ? numberToHex(blockNumber) : undefined
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
   const hex = await client.request(
     {
       method: 'eth_getCode',
-      params: [address, blockNumberHex || blockTag],
+      params: [address, block],
+    },
+    {
+      dedupe: typeof blockNumber === 'bigint' || blockHash !== undefined,
     },
-    { dedupe: Boolean(blockNumberHex) },
   )
   if (hex === '0x') return undefined
   return hex

package/actions/public/getProof.ts

@@ -6,11 +6,11 @@ import type { BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
 import type { Hash } from '../../types/misc.js'
 import type { Proof } from '../../types/proof.js'
-import type { RequestErrorType } from '../../utils/buildRequest.js'
 import {
-  type NumberToHexErrorType,
-  numberToHex,
-} from '../../utils/encoding/toHex.js'
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
 import {
   type FormatProofErrorType,
   formatProof,
@@ -26,6 +26,8 @@ export type GetProofParameters = {
       /** The block number. */
       blockNumber?: bigint | undefined
       blockTag?: undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
     }
   | {
       blockNumber?: undefined
@@ -34,13 +36,23 @@ export type GetProofParameters = {
        * @default 'latest'
        */
       blockTag?: BlockTag | undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: undefined
+      blockTag?: undefined
+      /** The proof at a block specified by block hash. */
+      blockHash: Hash
+      /** Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. */
+      requireCanonical?: boolean | undefined
     }
 )
 
 export type GetProofReturnType = Proof
 
 export type GetProofErrorType =
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | FormatProofErrorType
   | RequestErrorType
   | ErrorType
@@ -74,19 +86,23 @@ export async function getProof<chain extends Chain | undefined>(
   client: Client<Transport, chain>,
   {
     address,
+    blockHash,
     blockNumber,
-    blockTag: blockTag_,
+    blockTag = 'latest',
+    requireCanonical,
     storageKeys,
   }: GetProofParameters,
 ): Promise<GetProofReturnType> {
-  const blockTag = blockTag_ ?? 'latest'
-
-  const blockNumberHex =
-    blockNumber !== undefined ? numberToHex(blockNumber) : undefined
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
 
   const proof = await client.request({
     method: 'eth_getProof',
-    params: [address, storageKeys, blockNumberHex || blockTag],
+    params: [address, storageKeys, block],
   })
 
   return formatProof(proof)

package/actions/public/getStorageAt.ts

@@ -5,12 +5,12 @@ import type { Transport } from '../../clients/transports/createTransport.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { BlockTag } from '../../types/block.js'
 import type { Chain } from '../../types/chain.js'
-import type { Hex } from '../../types/misc.js'
-import type { RequestErrorType } from '../../utils/buildRequest.js'
+import type { Hash, Hex } from '../../types/misc.js'
 import {
-  type NumberToHexErrorType,
-  numberToHex,
-} from '../../utils/encoding/toHex.js'
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
 
 export type GetStorageAtParameters = {
   address: Address
@@ -19,17 +19,29 @@ export type GetStorageAtParameters = {
   | {
       blockNumber?: undefined
       blockTag?: BlockTag | undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
     }
   | {
       blockNumber?: bigint | undefined
       blockTag?: undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: undefined
+      blockTag?: undefined
+      /** The storage value at a block specified by block hash. */
+      blockHash: Hash
+      /** Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. */
+      requireCanonical?: boolean | undefined
     }
 )
 
 export type GetStorageAtReturnType = Hex | undefined
 
 export type GetStorageAtErrorType =
-  | NumberToHexErrorType
+  | FormatBlockParameterErrorType
   | RequestErrorType
   | ErrorType
 
@@ -59,13 +71,24 @@ export type GetStorageAtErrorType =
  */
 export async function getStorageAt<chain extends Chain | undefined>(
   client: Client<Transport, chain>,
-  { address, blockNumber, blockTag = 'latest', slot }: GetStorageAtParameters,
+  {
+    address,
+    blockHash,
+    blockNumber,
+    blockTag = 'latest',
+    requireCanonical,
+    slot,
+  }: GetStorageAtParameters,
 ): Promise<GetStorageAtReturnType> {
-  const blockNumberHex =
-    blockNumber !== undefined ? numberToHex(blockNumber) : undefined
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
   const data = await client.request({
     method: 'eth_getStorageAt',
-    params: [address, slot, blockNumberHex || blockTag],
+    params: [address, slot, block],
   })
   return data
 }