viem 2.56.8 → 2.57.0

package/actions/public/getStorageValues.ts

@@ -0,0 +1,93 @@
+import type { Address } from 'abitype'
+
+import type { Client } from '../../clients/createClient.js'
+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 { Hash, Hex } from '../../types/misc.js'
+import {
+  type FormatBlockParameterErrorType,
+  formatBlockParameter,
+} from '../../utils/block/formatBlockParameter.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
+
+export type GetStorageValuesParameters = {
+  /** Mapping of contract addresses to storage slot keys. */
+  requests: Record<Address, readonly Hex[]>
+} & (
+  | {
+      blockNumber?: undefined
+      blockTag?: BlockTag | undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: bigint | undefined
+      blockTag?: undefined
+      blockHash?: undefined
+      requireCanonical?: undefined
+    }
+  | {
+      blockNumber?: undefined
+      blockTag?: undefined
+      /** The storage values 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 GetStorageValuesReturnType = Record<Address, Hex[]>
+
+export type GetStorageValuesErrorType =
+  | FormatBlockParameterErrorType
+  | RequestErrorType
+  | ErrorType
+
+/**
+ * Returns values from multiple storage slots for multiple adddresses at a given block.
+ *
+ * - Docs: https://viem.sh/docs/actions/public/getStorageValues
+ * - JSON-RPC Methods: [`eth_getStorageValues`](https://github.com/ethereum/execution-apis/issues/752)
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetStorageValuesParameters}
+ * @returns The values of the requested storage slots. {@link GetStorageValuesReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, toHex } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getStorageValues } from 'viem/actions'
+ *
+ * const client = createPublicClient({ chain: mainnet, transport: http() })
+ * const values = await getStorageValues(client, {
+ *   requests: {
+ *     '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2': [
+ *       toHex(0, { size: 32 }),
+ *       toHex(1, { size: 32 }),
+ *     ],
+ *   },
+ * })
+ */
+export async function getStorageValues<chain extends Chain | undefined>(
+  client: Client<Transport, chain>,
+  {
+    blockHash,
+    blockNumber,
+    blockTag = 'latest',
+    requireCanonical,
+    requests,
+  }: GetStorageValuesParameters,
+): Promise<GetStorageValuesReturnType> {
+  const block = formatBlockParameter({
+    blockHash,
+    blockNumber,
+    blockTag,
+    requireCanonical,
+  })
+  return client.request({
+    method: 'eth_getStorageValues',
+    params: [requests, block],
+  })
+}

package/actions/public/simulateBlocks.ts

@@ -115,6 +115,14 @@ export type SimulateBlocksReturnType<
         data: Hex
         gasUsed: bigint
         logs?: Log[] | undefined
+        /**
+         * Gas used by the call as measured by the node before gas refunds are
+         * applied. `undefined` when the node does not report it.
+         *
+         * Note: this is a measurement of gas usage, not a guaranteed minimum
+         * sufficient gas limit for the call.
+         */
+        maxUsedGas?: bigint | undefined
       }
       error: Error
       mutability: AbiStateMutability
@@ -247,6 +255,8 @@ export async function simulateBlocks<
 
         const data = call.error?.data ?? call.returnData
         const gasUsed = BigInt(call.gasUsed)
+        const maxUsedGas =
+          call.maxUsedGas === undefined ? undefined : BigInt(call.maxUsedGas)
         const logs = call.logs?.map((log) => formatLog(log))
         const status = call.status === '0x1' ? 'success' : 'failure'
 
@@ -279,6 +289,9 @@ export async function simulateBlocks<
           data,
           gasUsed,
           logs,
+          // only present when reported by the node, so existing consumers
+          // (and snapshots) are unaffected on nodes that omit it.
+          ...(maxUsedGas === undefined ? {} : { maxUsedGas }),
           status,
           ...(status === 'success'
             ? {

package/actions/public/waitForTransactionReceipt.ts

@@ -153,8 +153,6 @@ export async function waitForTransactionReceipt<
     timeout = 180_000,
   } = parameters
 
-  const observerId = stringify(['waitForTransactionReceipt', client.uid, hash])
-
   const pollingInterval = (() => {
     if (parameters.pollingInterval) return parameters.pollingInterval
     if (client.chain?.experimental_preconfirmationTime)
@@ -162,6 +160,22 @@ export async function waitForTransactionReceipt<
     return client.pollingInterval
   })()
 
+  const observerId = stringify([
+    'waitForTransactionReceipt',
+    client.uid,
+    hash,
+    // Concurrent calls with different behavior-defining options must not
+    // share an observer: the first call's polling closure decides timeout,
+    // confirmations, polling interval and replacement checks for everyone.
+    {
+      checkReplacement,
+      confirmations,
+      pollingInterval,
+      retryCount,
+      timeout,
+    },
+  ])
+
   let transaction: GetTransactionReturnType<chain> | undefined
   let replacedTransaction: GetTransactionReturnType<chain> | undefined
   let receipt: GetTransactionReceiptReturnType<chain> | undefined

package/chains/definitions/blockdag.ts

@@ -0,0 +1,20 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+
+export const blockdag = /*#__PURE__*/ defineChain({
+  id: 1404,
+  name: 'BlockDAG',
+  nativeCurrency: {
+    decimals: 18,
+    name: 'BlockDAG',
+    symbol: 'BDAG',
+  },
+  rpcUrls: {
+    default: { http: ['https://rpc.bdagexplorer.com/'] },
+  },
+  blockExplorers: {
+    default: {
+      name: 'BDAG Explorer',
+      url: 'https://explorer.bdagexplorer.com',
+    },
+  },
+})

package/chains/definitions/candyChain.ts

@@ -0,0 +1,26 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+
+export const candyChain = /*#__PURE__*/ defineChain({
+  id: 2828,
+  name: 'CandyChain',
+  nativeCurrency: {
+    decimals: 18,
+    name: 'CANDY',
+    symbol: 'CANDY',
+  },
+  rpcUrls: {
+    default: { http: ['https://publicrpc.candychain.io'] },
+  },
+  blockExplorers: {
+    default: {
+      name: 'CandyChain Explorer',
+      url: 'https://streams.candychain.io',
+    },
+  },
+  contracts: {
+    multicall3: {
+      address: '0xca11bde05977b3631167028862be2a173976ca11',
+      blockCreated: 2039339,
+    },
+  },
+})

package/chains/definitions/creditCoin3Devnet.ts

@@ -17,5 +17,11 @@ export const creditCoin3Devnet = /*#__PURE__*/ defineChain({
       apiUrl: 'https://creditcoin3-dev.subscan.io',
     },
   },
+  contracts: {
+    multicall3: {
+      address: '0x47b51dC7b7Bbb3d9eB12080e3DA6E26125e8D75e',
+      blockCreated: 16_352_786,
+    },
+  },
   testnet: true,
 })

package/chains/definitions/creditCoin3Mainnet.ts

@@ -17,5 +17,11 @@ export const creditCoin3Mainnet = /*#__PURE__*/ defineChain({
       apiUrl: 'https://creditcoin.blockscout.com/api',
     },
   },
+  contracts: {
+    multicall3: {
+      address: '0x47b51dC7b7Bbb3d9eB12080e3DA6E26125e8D75e',
+      blockCreated: 4_373_631,
+    },
+  },
   testnet: false,
 })

package/chains/definitions/creditCoin3Testnet.ts

@@ -17,5 +17,11 @@ export const creditCoin3Testnet = /*#__PURE__*/ defineChain({
       apiUrl: 'https://creditcoin-testnet.blockscout.com/api',
     },
   },
+  contracts: {
+    multicall3: {
+      address: '0x47b51dC7b7Bbb3d9eB12080e3DA6E26125e8D75e',
+      blockCreated: 5_566_188,
+    },
+  },
   testnet: true,
 })

package/chains/definitions/kortana.ts

@@ -0,0 +1,20 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+
+export const kortana = /*#__PURE__*/ defineChain({
+  id: 9002,
+  name: 'Kortana',
+  nativeCurrency: {
+    decimals: 18,
+    name: 'Dinar',
+    symbol: 'DNR',
+  },
+  rpcUrls: {
+    default: { http: ['https://zeus-rpc.mainnet.kortana.xyz'] },
+  },
+  blockExplorers: {
+    default: {
+      name: 'Kortana Explorer',
+      url: 'https://explorer.mainnet.kortana.xyz',
+    },
+  },
+})

package/chains/definitions/rabbitChainTestnet.ts

@@ -0,0 +1,21 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+
+export const rabbitChainTestnet = /*#__PURE__*/ defineChain({
+  id: 9280,
+  name: 'Rabbit Chain Testnet',
+  nativeCurrency: {
+    decimals: 18,
+    name: 'Test Rabbit',
+    symbol: 'tRAB',
+  },
+  rpcUrls: {
+    default: { http: ['https://rpc-testnet.rabbitchain.org'] },
+  },
+  blockExplorers: {
+    default: {
+      name: 'Rabbit Chain Testnet Explorer',
+      url: 'https://explorer-testnet.rabbitchain.org',
+    },
+  },
+  testnet: true,
+})

package/chains/index.ts

@@ -86,6 +86,7 @@ export { bitTorrent } from './definitions/bitTorrent.js'
 export { bitTorrentTestnet } from './definitions/bitTorrentTestnet.js'
 export { blast } from './definitions/blast.js'
 export { blastSepolia } from './definitions/blastSepolia.js'
+export { blockdag } from './definitions/blockdag.js'
 export { bob } from './definitions/bob.js'
 export { boba } from './definitions/boba.js'
 export { bobaSepolia } from './definitions/bobaSepolia.js'
@@ -106,6 +107,7 @@ export { btr } from './definitions/btr.js'
 export { btrTestnet } from './definitions/btrTestnet.js'
 export { bxn } from './definitions/bxn.js'
 export { bxnTestnet } from './definitions/bxnTestnet.js'
+export { candyChain } from './definitions/candyChain.js'
 export { cannon } from './definitions/cannon.js'
 export { canto } from './definitions/canto.js'
 export { celo } from './definitions/celo.js'
@@ -353,6 +355,7 @@ export { klaytn } from './definitions/klaytn.js'
 /** @deprecated Use `kairos` instead. */
 export { klaytnBaobab } from './definitions/klaytnBaobab.js'
 export { koi } from './definitions/koi.js'
+export { kortana } from './definitions/kortana.js'
 export { kroma } from './definitions/kroma.js'
 export { kromaSepolia } from './definitions/kromaSepolia.js'
 export { krown } from './definitions/krown.js'
@@ -517,6 +520,7 @@ export { qMainnet } from './definitions/qMainnet.js'
 export { qTestnet } from './definitions/qTestnet.js'
 export { quai } from './definitions/quai.js'
 export { quaiTestnet } from './definitions/quaiTestnet.js'
+export { rabbitChainTestnet } from './definitions/rabbitChainTestnet.js'
 export { radius } from './definitions/radius.js'
 export { radiusTestnet } from './definitions/radiusTestnet.js'
 export { reactiveTestnet } from './definitions/reactiveTestnet.js'

package/clients/createClientResolver.ts

@@ -0,0 +1,191 @@
+import type { Address } from 'abitype'
+
+import type { JsonRpcAccount } from '../accounts/types.js'
+import { BaseError } from '../errors/base.js'
+import type { Tokens } from '../tokens/defineToken.js'
+import type { Account } from '../types/account.js'
+import type { Chain } from '../types/chain.js'
+import type { RpcSchema } from '../types/eip1193.js'
+import type { Prettify } from '../types/utils.js'
+import {
+  type Client,
+  type ClientConfig,
+  type CreateClientErrorType,
+  createClient,
+} from './createClient.js'
+import type { Transport } from './transports/createTransport.js'
+
+/**
+ * Creates a resolver that lazily constructs and caches a Client for each configured chain.
+ *
+ * @example
+ * ```ts
+ * import { createClientResolver, http } from 'viem'
+ * import { mainnet, optimism } from 'viem/chains'
+ *
+ * const resolver = createClientResolver({
+ *   chains: [mainnet, optimism],
+ *   transport: {
+ *     [mainnet.id]: http(),
+ *     [optimism.id]: http(),
+ *   },
+ * })
+ *
+ * const client = resolver.getClient({ chainId: optimism.id })
+ * ```
+ *
+ * @param options - Resolver options, including shared Client configuration.
+ * @returns A resolver for the configured chains.
+ */
+export function createClientResolver<
+  const chains extends Chains,
+  accountOrAddress extends Account | Address | undefined = undefined,
+  const transport extends TransportConfig<NoInfer<chains>> = TransportConfig<
+    NoInfer<chains>
+  >,
+  const tokens extends Tokens | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+>(
+  options: createClientResolver.Options<
+    chains,
+    accountOrAddress,
+    transport,
+    tokens,
+    rpcSchema
+  >,
+): createClientResolver.ReturnType<
+  chains,
+  accountOrAddress,
+  transport,
+  tokens,
+  rpcSchema
+> {
+  const { chains, transport, ...rest } = options
+  const clients = new Map<number, unknown>()
+
+  // The chain and transport are selected from the same chain ID.
+  return {
+    getClient({ chainId }) {
+      const cached = clients.get(chainId)
+      if (cached) return cached
+
+      const chain = chains.find((chain) => chain.id === chainId)
+      if (!chain) throw new ChainNotConfiguredError({ chainId })
+      const transport_ =
+        typeof transport === 'function'
+          ? transport({ chainId })
+          : (transport as TransportMap<chains>)[chainId]
+      if (!transport_) throw new TransportNotConfiguredError({ chainId })
+      const client = createClient({ ...rest, chain, transport: transport_ })
+      clients.set(chainId, client)
+      return client
+    },
+  } as createClientResolver.ReturnType<
+    chains,
+    accountOrAddress,
+    transport,
+    tokens,
+    rpcSchema
+  >
+}
+
+export declare namespace createClientResolver {
+  /** Errors thrown while resolving a Client. */
+  type ErrorType =
+    | ChainNotConfiguredError
+    | CreateClientErrorType
+    | TransportNotConfiguredError
+
+  /** Options for {@link createClientResolver}. */
+  type Options<
+    chains extends Chains = Chains,
+    accountOrAddress extends Account | Address | undefined =
+      | Account
+      | Address
+      | undefined,
+    transport extends TransportConfig<chains> = TransportConfig<chains>,
+    tokens extends Tokens | undefined = Tokens | undefined,
+    rpcSchema extends RpcSchema | undefined = undefined,
+  > = Prettify<
+    Omit<
+      ClientConfig<Transport, undefined, accountOrAddress, rpcSchema, tokens>,
+      'chain' | 'transport'
+    > & {
+      /** Chains available to the resolver. Must contain at least one chain. */
+      chains: chains
+      /** Transports indexed or resolved by chain ID. */
+      transport: transport
+    }
+  >
+
+  /** Return type of {@link createClientResolver}. */
+  type ReturnType<
+    chains extends Chains = Chains,
+    accountOrAddress extends Account | Address | undefined =
+      | Account
+      | Address
+      | undefined,
+    transport extends TransportConfig<chains> = TransportConfig<chains>,
+    tokens extends Tokens | undefined = Tokens | undefined,
+    rpcSchema extends RpcSchema | undefined = undefined,
+  > = {
+    /** Returns the cached Client configured for `chainId`, creating it on first use. */
+    getClient<const chainId extends chains[number]['id']>(options: {
+      /** ID of a configured chain. */
+      chainId: chainId
+    }): Client<
+      ResolvedTransport<chains, transport, chainId>,
+      number extends chains[number]['id']
+        ? chains[number]
+        : Extract<chains[number], { id: chainId }>,
+      accountOrAddress extends Address
+        ? Prettify<JsonRpcAccount<accountOrAddress>>
+        : accountOrAddress,
+      rpcSchema,
+      undefined,
+      tokens
+    >
+  }
+}
+
+type Chains = readonly [Chain, ...Chain[]]
+
+type TransportConfig<chains extends Chains> =
+  | TransportMap<chains>
+  | ((options: { chainId: chains[number]['id'] }) => Transport)
+
+type TransportMap<chains extends Chains> = {
+  readonly [chainId in chains[number]['id']]: Transport
+}
+
+type ResolvedTransport<
+  chains extends Chains,
+  transport extends TransportConfig<chains>,
+  chainId extends chains[number]['id'],
+> = transport extends (...args: never[]) => infer resolved
+  ? resolved extends Transport
+    ? resolved
+    : never
+  : transport extends Record<chainId, infer resolved>
+    ? resolved extends Transport
+      ? resolved
+      : never
+    : never
+
+/** Thrown when a Client is requested for an unconfigured chain. */
+export class ChainNotConfiguredError extends BaseError {
+  constructor({ chainId }: { chainId: number }) {
+    super(`Chain with id ${chainId} is not configured.`, {
+      name: 'createClientResolver.ChainNotConfiguredError',
+    })
+  }
+}
+
+/** Thrown when a configured chain has no transport. */
+export class TransportNotConfiguredError extends BaseError {
+  constructor({ chainId }: { chainId: number }) {
+    super(`Transport for chain with id ${chainId} is not configured.`, {
+      name: 'createClientResolver.TransportNotConfiguredError',
+    })
+  }
+}

package/clients/decorators/public.ts

@@ -170,6 +170,11 @@ import {
   type GetStorageAtReturnType,
   getStorageAt,
 } from '../../actions/public/getStorageAt.js'
+import {
+  type GetStorageValuesParameters,
+  type GetStorageValuesReturnType,
+  getStorageValues,
+} from '../../actions/public/getStorageValues.js'
 import {
   type GetTransactionParameters,
   type GetTransactionReturnType,
@@ -1413,6 +1418,18 @@ export type PublicActions<
   getStorageAt: (
     args: GetStorageAtParameters,
   ) => Promise<GetStorageAtReturnType>
+  /**
+   * Returns values from multiple storage slots at a given address and block.
+   *
+   * - Docs: https://viem.sh/docs/actions/public/getStorageValues
+   * - JSON-RPC Methods: [`eth_getStorageValues`](https://github.com/ethereum/execution-apis/issues/752)
+   *
+   * @param args - {@link GetStorageValuesParameters}
+   * @returns The values of the requested storage slots. {@link GetStorageValuesReturnType}
+   */
+  getStorageValues: (
+    args: GetStorageValuesParameters,
+  ) => Promise<GetStorageValuesReturnType>
   /**
    * Returns information about a [Transaction](https://viem.sh/docs/glossary/terms#transaction) given a hash or block identifier.
    *
@@ -2347,6 +2364,7 @@ export function publicActions<
     fillTransaction: (args) => fillTransaction(client, args),
     getRawTransaction: (args) => getRawTransaction(client, args),
     getStorageAt: (args) => getStorageAt(client, args),
+    getStorageValues: (args) => getStorageValues(client, args),
     getTransaction: (args) => getTransaction(client, args),
     getTransactionConfirmations: (args) =>
       getTransactionConfirmations(client, args),

package/errors/version.ts

@@ -1 +1 @@
-export const version = '2.56.8'
+export const version = '2.57.0'

package/index.ts

@@ -247,6 +247,11 @@ export type {
   GetStorageAtParameters,
   GetStorageAtReturnType,
 } from './actions/public/getStorageAt.js'
+export type {
+  GetStorageValuesErrorType,
+  GetStorageValuesParameters,
+  GetStorageValuesReturnType,
+} from './actions/public/getStorageValues.js'
 export type {
   GetTransactionErrorType,
   GetTransactionParameters,
@@ -604,6 +609,12 @@ export {
   type MulticallBatchOptions,
   rpcSchema,
 } from './clients/createClient.js'
+/** Lazily resolves and caches typed Clients across configured chains. */
+export {
+  ChainNotConfiguredError,
+  createClientResolver,
+  TransportNotConfiguredError,
+} from './clients/createClientResolver.js'
 export {
   type CreatePublicClientErrorType,
   createPublicClient,

package/op-stack/actions/getGame.ts

@@ -93,7 +93,9 @@ export async function getGame<
 
   const latestGames = await getGames(client, parameters)
 
-  const games = latestGames.filter((game) => game.l2BlockNumber > l2BlockNumber)
+  const games = latestGames.filter(
+    (game) => game.l2BlockNumber >= l2BlockNumber,
+  )
 
   const game = (() => {
     if (strategy === 'random')

package/op-stack/actions/getGames.ts

@@ -145,7 +145,7 @@ export async function getGames<
   const games = rawGames
     .map((game, i) => {
       const blockNumber = l2SequenceNumbers[i] as bigint
-      return !l2BlockNumber || blockNumber > l2BlockNumber
+      return !l2BlockNumber || blockNumber >= l2BlockNumber
         ? { ...game, l2BlockNumber: blockNumber, usesSuperRoots }
         : null
     })

package/op-stack/actions/getTimeToNextGame.ts

@@ -133,9 +133,9 @@ export async function getTimeToNextGame<
     // then we assume that the dispute game has already been submitted.
     if (now < latestGameTimestamp) return 0
 
-    // If the latest dispute game block is newer than the provided dispute game block number,
+    // If the latest dispute game covers the provided block number,
     // then we assume that the dispute game has already been submitted.
-    if (latestGame.l2BlockNumber > l2BlockNumber) return 0
+    if (latestGame.l2BlockNumber >= l2BlockNumber) return 0
 
     // If there is only a single game, no interval data
     if (intervalWithBuffer === 0) return 0

package/op-stack/actions/getTimeToNextL2Output.ts

@@ -141,9 +141,9 @@ export async function getTimeToNextL2Output<
     // then we assume that the L2 output has already been submitted.
     if (now < latestOutputTimestamp) return 0
 
-    // If the latest L2 output block is newer than the provided L2 block number,
+    // If the latest L2 output covers the provided L2 block number,
     // then we assume that the L2 output has already been submitted.
-    if (latestOutput.l2BlockNumber > l2BlockNumber) return 0
+    if (latestOutput.l2BlockNumber >= l2BlockNumber) return 0
 
     const elapsedBlocks = Number(l2BlockNumber - latestOutput.l2BlockNumber)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viem",
   "description": "TypeScript Interface for Ethereum",
-  "version": "2.56.8",
+  "version": "2.57.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",