viem 2.50.4 → 2.51.2

package/op-stack/actions/getGame.ts

@@ -42,7 +42,14 @@ export type GetGameParameters<
     strategy?: 'latest' | 'random'
   }
 export type GetGameReturnType = Game & {
+  /**
+   * L2 block number anchored by the dispute game. For super-root games, this
+   * value is the L2 timestamp instead. Check `usesSuperRoots` to distinguish
+   * the unit.
+   */
   l2BlockNumber: bigint
+  /** Whether the dispute game anchors on super roots. */
+  usesSuperRoots: boolean
 }
 
 export type GetGameErrorType =

package/op-stack/actions/getGames.ts

@@ -17,6 +17,7 @@ import type {
   GetChainParameter,
 } from '../../types/chain.js'
 import { disputeGameAbi, disputeGameFactoryAbi, portal2Abi } from '../abis.js'
+import { isSuperGameType } from '../gameTypes.js'
 import type { GetContractAddressParameter } from '../types/contract.js'
 import type { Game } from '../types/withdrawal.js'
 
@@ -40,7 +41,14 @@ export type GetGamesParameters<
     limit?: number | undefined
   }
 export type GetGamesReturnType = (Game & {
+  /**
+   * L2 block number anchored by the dispute game. For super-root games, this
+   * value is the L2 timestamp instead. Check `usesSuperRoots` to distinguish
+   * the unit.
+   */
   l2BlockNumber: bigint
+  /** Whether the dispute game anchors on super roots. */
+  usesSuperRoots: boolean
 })[]
 export type GetGamesErrorType =
   | ReadContractErrorType
@@ -133,11 +141,12 @@ export async function getGames<
     })),
   })
 
+  const usesSuperRoots = isSuperGameType(gameType)
   const games = rawGames
     .map((game, i) => {
       const blockNumber = l2SequenceNumbers[i] as bigint
       return !l2BlockNumber || blockNumber > l2BlockNumber
-        ? { ...game, l2BlockNumber: blockNumber }
+        ? { ...game, l2BlockNumber: blockNumber, usesSuperRoots }
         : null
     })
     .filter(Boolean) as GetGamesReturnType

package/op-stack/actions/getTimeToProve.ts

@@ -47,6 +47,10 @@ export type GetTimeToProveParameters<
     intervalBuffer?:
       | GetTimeToNextL2OutputParameters['intervalBuffer']
       | undefined
+    /**
+     * L2 timestamp of the withdrawal. Required for super-root dispute games.
+     */
+    l2Timestamp?: bigint | undefined
     receipt: TransactionReceipt
   }
 
@@ -98,7 +102,7 @@ export async function getTimeToProve<
   client: Client<Transport, chain, account>,
   parameters: GetTimeToProveParameters<chain, chainOverride>,
 ): Promise<GetTimeToProveReturnType> {
-  const { receipt } = parameters
+  const { l2Timestamp, receipt } = parameters
 
   const portalVersion = await getPortalVersion(
     client,
@@ -109,11 +113,11 @@ export async function getTimeToProve<
   if (portalVersion.major < 3)
     return getTimeToNextL2Output(client, {
       ...parameters,
-      l2BlockNumber: receipt.blockNumber,
+      l2BlockNumber: l2Timestamp ?? receipt.blockNumber,
     } as GetTimeToNextL2OutputParameters)
 
   return getTimeToNextGame(client, {
     ...parameters,
-    l2BlockNumber: receipt.blockNumber,
+    l2BlockNumber: l2Timestamp ?? receipt.blockNumber,
   } as GetTimeToNextGameParameters)
 }

package/op-stack/actions/getWithdrawalStatus.ts

@@ -64,6 +64,10 @@ export type GetWithdrawalStatusParameters<
      * @default 100
      */
     gameLimit?: number
+    /**
+     * L2 timestamp of the withdrawal. Required for super-root dispute games.
+     */
+    l2Timestamp?: bigint | undefined
   } & OneOf<
     | {
         /**
@@ -160,7 +164,8 @@ export async function getWithdrawalStatus<
     return Object.values(targetChain.contracts.portal)[0].address
   })()
 
-  const l2BlockNumber = receipt?.blockNumber ?? parameters.l2BlockNumber
+  const l2BlockNumber =
+    parameters.l2Timestamp ?? receipt?.blockNumber ?? parameters.l2BlockNumber
 
   const withdrawal = (() => {
     if (receipt) {

package/op-stack/actions/waitToProve.ts

@@ -49,6 +49,10 @@ export type WaitToProveParameters<
      * @default 100
      */
     gameLimit?: number | undefined
+    /**
+     * L2 timestamp of the withdrawal. Required for super-root dispute games.
+     */
+    l2Timestamp?: bigint | undefined
     receipt: TransactionReceipt
     /**
      * Polling frequency (in ms). Defaults to Client's pollingInterval config.
@@ -105,7 +109,7 @@ export async function waitToProve<
   client: Client<Transport, chain, account>,
   parameters: WaitToProveParameters<chain, chainOverride>,
 ): Promise<WaitToProveReturnType> {
-  const { gameLimit, receipt } = parameters
+  const { gameLimit, l2Timestamp, receipt } = parameters
 
   const [withdrawal] = getWithdrawals(receipt)
 
@@ -123,7 +127,7 @@ export async function waitToProve<
   if (portalVersion.major < 3) {
     const output = await waitForNextL2Output(client, {
       ...parameters,
-      l2BlockNumber: receipt.blockNumber,
+      l2BlockNumber: l2Timestamp ?? receipt.blockNumber,
     } as WaitForNextL2OutputParameters)
     return {
       game: {
@@ -133,6 +137,7 @@ export async function waitToProve<
         metadata: '0x',
         rootClaim: output.outputRoot,
         timestamp: output.timestamp,
+        usesSuperRoots: false,
       },
       output,
       withdrawal,
@@ -142,7 +147,7 @@ export async function waitToProve<
   const game = await waitForNextGame(client, {
     ...parameters,
     limit: gameLimit,
-    l2BlockNumber: receipt.blockNumber,
+    l2BlockNumber: l2Timestamp ?? receipt.blockNumber,
   } as WaitForNextGameParameters)
   return {
     game,

package/op-stack/gameTypes.ts

@@ -0,0 +1,9 @@
+/**
+ * Super dispute game type IDs from the OP Stack contracts
+ * (`contracts-bedrock/src/dispute/lib/Types.sol:99-103`).
+ */
+export const superGameTypes = new Set([4, 5, 7, 9]) as ReadonlySet<number>
+
+export function isSuperGameType(gameType: number): boolean {
+  return superGameTypes.has(gameType)
+}

package/op-stack/index.ts

@@ -207,7 +207,6 @@ export {
 export { chainConfig } from './chainConfig.js'
 
 export * from './chains.js'
-
 export {
   type PublicActionsL1,
   publicActionsL1,
@@ -224,6 +223,7 @@ export {
   type WalletActionsL2,
   walletActionsL2,
 } from './decorators/walletL2.js'
+export { isSuperGameType, superGameTypes } from './gameTypes.js'
 
 export {
   type ParseTransactionErrorType,
@@ -266,6 +266,12 @@ export {
   type ExtractWithdrawalMessageLogsReturnType,
   extractWithdrawalMessageLogs,
 } from './utils/extractWithdrawalMessageLogs.js'
+export {
+  type GetL2BlockNumberAtTimestampErrorType,
+  type GetL2BlockNumberAtTimestampParameters,
+  type GetL2BlockNumberAtTimestampReturnType,
+  getL2BlockNumberAtTimestamp,
+} from './utils/getL2BlockNumberAtTimestamp.js'
 export {
   type GetL2TransactionHashErrorType,
   type GetL2TransactionHashParameters,

package/op-stack/utils/getL2BlockNumberAtTimestamp.ts

@@ -0,0 +1,57 @@
+import {
+  type GetBlockErrorType,
+  getBlock,
+} from '../../actions/public/getBlock.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { Account } from '../../types/account.js'
+import type { Chain } from '../../types/chain.js'
+
+export type GetL2BlockNumberAtTimestampParameters = {
+  /** L2 block timestamp. */
+  timestamp: bigint
+}
+
+export type GetL2BlockNumberAtTimestampReturnType = bigint
+
+export type GetL2BlockNumberAtTimestampErrorType = GetBlockErrorType | ErrorType
+
+/**
+ * Gets the L2 block number for a timestamp using the latest L2 block and its parent.
+ *
+ * @param client - Client to use.
+ * @param parameters - {@link GetL2BlockNumberAtTimestampParameters}
+ * @returns L2 block number.
+ */
+export async function getL2BlockNumberAtTimestamp(
+  client: Client<Transport, Chain | undefined, Account | undefined>,
+  parameters: GetL2BlockNumberAtTimestampParameters,
+): Promise<GetL2BlockNumberAtTimestampReturnType> {
+  const latest = await getBlock(client)
+  if (latest.number === null)
+    throw new Error('Latest L2 block number is unavailable.')
+  if (latest.timestamp === undefined)
+    throw new Error('Latest L2 block timestamp is unavailable.')
+  if (latest.number === 0n)
+    throw new Error('Cannot derive L2 block time from genesis block.')
+
+  const parent = await getBlock(client, { blockNumber: latest.number - 1n })
+  if (parent.timestamp === undefined)
+    throw new Error('Parent L2 block timestamp is unavailable.')
+
+  const blockTime = latest.timestamp - parent.timestamp
+  if (blockTime === 0n) throw new Error('L2 block time is zero.')
+
+  const timeDiff = latest.timestamp - parameters.timestamp
+  if (timeDiff < 0n)
+    throw new Error('Timestamp is in the future relative to L2 head.')
+  if (timeDiff % blockTime !== 0n)
+    throw new Error('Timestamp does not align with the L2 block time.')
+
+  const blocksToLookBack = timeDiff / blockTime
+  if (blocksToLookBack > latest.number)
+    throw new Error('Timestamp predates L2 genesis.')
+
+  return latest.number - blocksToLookBack
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viem",
   "description": "TypeScript Interface for Ethereum",
-  "version": "2.50.4",
+  "version": "2.51.2",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -230,7 +230,7 @@
     "@scure/bip39": "1.6.0",
     "abitype": "1.2.3",
     "isows": "1.0.7",
-    "ox": "0.14.22",
+    "ox": "0.14.25",
     "ws": "8.20.1"
   },
   "license": "MIT",