viem 2.9.2 → 2.9.3

package/op-stack/actions/getGame.ts

@@ -0,0 +1,99 @@
+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,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import {
+  GameNotFoundError,
+  type GameNotFoundErrorType,
+} from '../errors/withdrawal.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import type { Game } from '../types/withdrawal.js'
+import { type GetGamesErrorType, getGames } from './getGames.js'
+
+export type GetGameParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = GetChainParameter<chain, chainOverride> &
+  GetContractAddressParameter<
+    _derivedChain,
+    'portal' | 'disputeGameFactory'
+  > & {
+    /**
+     * The minimum block number of the dispute game.
+     */
+    l2BlockNumber: bigint
+    /**
+     * Limit of games to extract.
+     * @default 100
+     */
+    limit?: number | undefined
+    /**
+     * Strategy for extracting a dispute game.
+     *
+     * - `latest` - Returns the latest dispute game.
+     * - `random` - Returns a random dispute game.
+     */
+    strategy?: 'latest' | 'random'
+  }
+export type GetGameReturnType = Game & {
+  l2BlockNumber: bigint
+}
+
+export type GetGameErrorType =
+  | GetGamesErrorType
+  | GameNotFoundErrorType
+  | ErrorType
+
+/**
+ * Retrieves a valid dispute game on an L2 that occurred after a provided L2 block number.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getGame
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetGameParameters}
+ * @returns A valid dispute game. {@link GetGameReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { getGame } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const game = await getGame(publicClientL1, {
+ *   l2BlockNumber: 69420n,
+ *   targetChain: optimism
+ * })
+ */
+export async function getGame<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: GetGameParameters<chain, chainOverride>,
+): Promise<GetGameReturnType> {
+  const { l2BlockNumber, strategy = 'latest' } = parameters
+
+  const latestGames = await getGames(client, parameters)
+
+  const games = latestGames.filter((game) => game.l2BlockNumber > l2BlockNumber)
+
+  const game = (() => {
+    if (strategy === 'random')
+      return games[Math.floor(Math.random() * games.length)]
+    return games[0]
+  })()
+
+  if (!game) throw new GameNotFoundError()
+  return game
+}

package/op-stack/actions/getGames.ts

@@ -0,0 +1,133 @@
+import {
+  type ReadContractErrorType,
+  readContract,
+} from '../../actions/public/readContract.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,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import { decodeAbiParameters } from '../../utils/abi/decodeAbiParameters.js'
+import { disputeGameFactoryAbi, portal2Abi } from '../abis.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import type { Game } from '../types/withdrawal.js'
+
+export type GetGamesParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = GetChainParameter<chain, chainOverride> &
+  GetContractAddressParameter<
+    _derivedChain,
+    'portal' | 'disputeGameFactory'
+  > & {
+    /**
+     * Filter by minimum block number of the dispute games.
+     */
+    l2BlockNumber?: bigint | undefined
+    /**
+     * Limit of games to extract.
+     * @default 100
+     */
+    limit?: number | undefined
+  }
+export type GetGamesReturnType = (Game & {
+  l2BlockNumber: bigint
+})[]
+export type GetGamesErrorType = ReadContractErrorType | ErrorType
+
+/**
+ * Retrieves dispute games for an L2.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getGame
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetGameParameters}
+ * @returns Dispute games. {@link GetGameReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { getGames } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const games = await getGames(publicClientL1, {
+ *   targetChain: optimism
+ * })
+ */
+export async function getGames<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: GetGamesParameters<chain, chainOverride>,
+): Promise<GetGamesReturnType> {
+  const {
+    chain = client.chain,
+    l2BlockNumber,
+    limit = 100,
+    targetChain,
+  } = parameters
+
+  const portalAddress = (() => {
+    if (parameters.portalAddress) return parameters.portalAddress
+    if (chain) return targetChain!.contracts.portal[chain.id].address
+    return Object.values(targetChain!.contracts.portal)[0].address
+  })()
+
+  const disputeGameFactoryAddress = (() => {
+    if (parameters.disputeGameFactoryAddress)
+      return parameters.disputeGameFactoryAddress
+    if (chain)
+      return targetChain!.contracts.disputeGameFactory[chain.id].address
+    return Object.values(targetChain!.contracts.disputeGameFactory)[0].address
+  })()
+
+  const [gameCount, gameType] = await Promise.all([
+    readContract(client, {
+      abi: disputeGameFactoryAbi,
+      functionName: 'gameCount',
+      args: [],
+      address: disputeGameFactoryAddress,
+    }),
+    readContract(client, {
+      abi: portal2Abi,
+      functionName: 'respectedGameType',
+      address: portalAddress,
+    }),
+  ])
+
+  const games = (
+    (await readContract(client, {
+      abi: disputeGameFactoryAbi,
+      functionName: 'findLatestGames',
+      address: disputeGameFactoryAddress,
+      args: [
+        gameType,
+        BigInt(Math.max(0, Number(gameCount - 1n))),
+        BigInt(Math.min(limit, Number(gameCount))),
+      ],
+    })) as Game[]
+  )
+    .map((game) => {
+      const [blockNumber] = decodeAbiParameters(
+        [{ type: 'uint256' }],
+        game.extraData,
+      )
+      return !l2BlockNumber || blockNumber > l2BlockNumber
+        ? { ...game, l2BlockNumber: blockNumber }
+        : null
+    })
+    .filter(Boolean) as GetGamesReturnType
+
+  return games
+}

package/op-stack/actions/getL1BaseFee.ts

@@ -0,0 +1,81 @@
+import type { Address } from 'abitype'
+
+import {
+  type ReadContractErrorType,
+  readContract,
+} from '../../actions/public/readContract.js'
+import { type PrepareTransactionRequestErrorType } from '../../actions/wallet/prepareTransactionRequest.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 Chain, type GetChainParameter } from '../../types/chain.js'
+import type { RequestErrorType } from '../../utils/buildRequest.js'
+import { getChainContractAddress } from '../../utils/chain/getChainContractAddress.js'
+import { type HexToNumberErrorType } from '../../utils/encoding/fromHex.js'
+
+import { gasPriceOracleAbi } from '../abis.js'
+import { contracts } from '../contracts.js'
+
+export type GetL1BaseFeeParameters<
+  TChain extends Chain | undefined = Chain | undefined,
+  TChainOverride extends Chain | undefined = undefined,
+> = GetChainParameter<TChain, TChainOverride> & {
+  /** Gas price oracle address. */
+  gasPriceOracleAddress?: Address | undefined
+}
+
+export type GetL1BaseFeeReturnType = bigint
+
+export type GetL1BaseFeeErrorType =
+  | RequestErrorType
+  | PrepareTransactionRequestErrorType
+  | HexToNumberErrorType
+  | ReadContractErrorType
+  | ErrorType
+
+/**
+ * get the L1 base fee
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetL1BaseFeeParameters}
+ * @returns The basefee (in wei). {@link GetL1BaseFeeReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseEther } from 'viem'
+ * import { optimism } from 'viem/chains'
+ * import { getL1BaseFee } from 'viem/chains/optimism'
+ *
+ * const client = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ * const l1BaseFee = await getL1BaseFee(client)
+ */
+export async function getL1BaseFee<
+  TChain extends Chain | undefined,
+  TChainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, TChain>,
+  args?: GetL1BaseFeeParameters<TChain, TChainOverride> | undefined,
+): Promise<GetL1BaseFeeReturnType> {
+  const {
+    chain = client.chain,
+    gasPriceOracleAddress: gasPriceOracleAddress_,
+  } = args || {}
+
+  const gasPriceOracleAddress = (() => {
+    if (gasPriceOracleAddress_) return gasPriceOracleAddress_
+    if (chain)
+      return getChainContractAddress({
+        chain,
+        contract: 'gasPriceOracle',
+      })
+    return contracts.gasPriceOracle.address
+  })()
+
+  return readContract(client, {
+    abi: gasPriceOracleAbi,
+    address: gasPriceOracleAddress,
+    functionName: 'l1BaseFee',
+  })
+}

package/op-stack/actions/getL2Output.ts

@@ -0,0 +1,130 @@
+import {
+  type ReadContractErrorType,
+  readContract,
+} from '../../actions/public/readContract.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,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import type { Hex } from '../../types/misc.js'
+import type { OneOf } from '../../types/utils.js'
+import { l2OutputOracleAbi } from '../abis.js'
+import type { TargetChain } from '../types/chain.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import { type GetGameParameters, getGame } from './getGame.js'
+import {
+  type GetPortalVersionParameters,
+  getPortalVersion,
+} from './getPortalVersion.js'
+
+export type GetL2OutputParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = GetChainParameter<chain, chainOverride> &
+  OneOf<
+    | GetContractAddressParameter<_derivedChain, 'l2OutputOracle'>
+    | (GetContractAddressParameter<
+        _derivedChain,
+        'portal' | 'disputeGameFactory'
+      > & {
+        /**
+         * Limit of games to extract.
+         * @default 100
+         */
+        limit?: number | undefined
+      })
+  > & {
+    l2BlockNumber: bigint
+  }
+export type GetL2OutputReturnType = {
+  outputIndex: bigint
+  outputRoot: Hex
+  timestamp: bigint
+  l2BlockNumber: bigint
+}
+export type GetL2OutputErrorType = ReadContractErrorType | ErrorType
+
+/**
+ * Retrieves the first L2 output proposal that occurred after a provided block number.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getL2Output
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetL2OutputParameters}
+ * @returns The L2 output. {@link GetL2OutputReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { getL2Output } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const output = await getL2Output(publicClientL1, {
+ *   l2BlockNumber: 69420n,
+ *   targetChain: optimism
+ * })
+ */
+export async function getL2Output<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: GetL2OutputParameters<chain, chainOverride>,
+): Promise<GetL2OutputReturnType> {
+  const { chain = client.chain, l2BlockNumber, targetChain } = parameters
+
+  const version = await getPortalVersion(
+    client,
+    parameters as GetPortalVersionParameters,
+  )
+
+  if (version.major >= 3) {
+    const game = await getGame(client, parameters as GetGameParameters)
+    return {
+      l2BlockNumber: game.l2BlockNumber,
+      outputIndex: game.index,
+      outputRoot: game.rootClaim,
+      timestamp: game.timestamp,
+    }
+  }
+
+  const l2OutputOracleAddress = (() => {
+    if (parameters.l2OutputOracleAddress)
+      return parameters.l2OutputOracleAddress
+    if (chain)
+      return (targetChain as unknown as TargetChain)!.contracts.l2OutputOracle[
+        chain.id
+      ].address
+    return (
+      Object.values(
+        (targetChain as unknown as TargetChain)!.contracts.l2OutputOracle,
+      ) as any
+    )[0].address
+  })()
+
+  const outputIndex = await readContract(client, {
+    address: l2OutputOracleAddress,
+    abi: l2OutputOracleAbi,
+    functionName: 'getL2OutputIndexAfter',
+    args: [l2BlockNumber],
+  })
+  const output = await readContract(client, {
+    address: l2OutputOracleAddress,
+    abi: l2OutputOracleAbi,
+    functionName: 'getL2Output',
+    args: [outputIndex],
+  })
+
+  return { outputIndex, ...output }
+}

package/op-stack/actions/getPortalVersion.ts

@@ -0,0 +1,87 @@
+import {
+  type ReadContractErrorType,
+  readContract,
+} from '../../actions/public/readContract.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 {
+  Chain,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import { withCache } from '../../utils/promise/withCache.js'
+import { portal2Abi } from '../abis.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+
+export type GetPortalVersionParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = GetChainParameter<chain, chainOverride> &
+  GetContractAddressParameter<_derivedChain, 'portal'>
+
+export type GetPortalVersionReturnType = {
+  major: number
+  minor: number
+  patch: number
+}
+
+export type GetPortalVersionErrorType = ReadContractErrorType | ErrorType
+
+/**
+ * Retrieves the current version of the Portal contract.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getPortalVersion
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetPortalVersionParameters}
+ * @returns The version object.
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getPortalVersion } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const version = await getPortalVersion(publicClientL1, {
+ *   targetChain: optimism,
+ * })
+ *
+ * if (version.major > 3)
+ *   console.log('Fault proofs are enabled on this version of optimism')
+ * console.log('Fault proofs are not enabled on this version of optimism')
+ */
+export async function getPortalVersion<
+  chain extends Chain | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain>,
+  parameters: GetPortalVersionParameters<chain, chainOverride>,
+) {
+  const { chain = client.chain, targetChain } = parameters
+
+  const portalAddress = (() => {
+    if (parameters.portalAddress) return parameters.portalAddress
+    if (chain) return targetChain!.contracts.portal[chain.id].address
+    return Object.values(targetChain!.contracts.portal)[0].address
+  })()
+
+  const version = await withCache(
+    () =>
+      readContract(client, {
+        abi: portal2Abi,
+        address: portalAddress,
+        functionName: 'version',
+      }),
+    { cacheKey: ['portalVersion', portalAddress].join('.'), cacheTime: 300 },
+  )
+
+  const [major, minor, patch] = version.split('.').map(Number)
+
+  return { major, minor, patch }
+}

package/op-stack/actions/getTimeToFinalize.ts

@@ -0,0 +1,159 @@
+import {
+  type MulticallErrorType,
+  multicall,
+} from '../../actions/public/multicall.js'
+import { readContract } from '../../actions/public/readContract.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { BaseError } from '../../errors/base.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { Account } from '../../types/account.js'
+import type {
+  Chain,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import { l2OutputOracleAbi, portal2Abi, portalAbi } from '../abis.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import { getPortalVersion } from './getPortalVersion.js'
+
+export type GetTimeToFinalizeParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = GetChainParameter<chain, chainOverride> &
+  GetContractAddressParameter<_derivedChain, 'l2OutputOracle' | 'portal'> & {
+    withdrawalHash: Hash
+  }
+export type GetTimeToFinalizeReturnType = {
+  /** The finalization period (in seconds). */
+  period: number
+  /** Seconds until the withdrawal can be finalized. */
+  seconds: number
+  /** Timestamp of when the withdrawal can be finalized. */
+  timestamp: number
+}
+export type GetTimeToFinalizeErrorType = MulticallErrorType | ErrorType
+
+const buffer = 10
+
+/**
+ * Returns the time until the withdrawal transaction can be finalized. Used for the [Withdrawal](/op-stack/guides/withdrawals) flow.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getTimeToFinalize
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetTimeToFinalizeParameters}
+ * @returns Time until finalize. {@link GetTimeToFinalizeReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { getBlockNumber } from 'viem/actions'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { getTimeToFinalize } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const publicClientL2 = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ *
+ * const receipt = await publicClientL2.getTransactionReceipt({
+ *   hash: '0x9a2f4283636ddeb9ac32382961b22c177c9e86dd3b283735c154f897b1a7ff4a',
+ * })
+ *
+ * const [withdrawal] = getWithdrawals(receipt)
+ *
+ * const { seconds } = await getTimeToFinalize(publicClientL1, {
+ *   withdrawalHash: withdrawal.withdrawalHash,
+ *   targetChain: optimism
+ * })
+ */
+export async function getTimeToFinalize<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: GetTimeToFinalizeParameters<chain, chainOverride>,
+): Promise<GetTimeToFinalizeReturnType> {
+  const { chain = client.chain, withdrawalHash, targetChain } = parameters
+
+  const portalAddress = (() => {
+    if (parameters.portalAddress) return parameters.portalAddress
+    if (chain) return targetChain!.contracts.portal[chain.id].address
+    return Object.values(targetChain!.contracts.portal)[0].address
+  })()
+
+  const portalVersion = await getPortalVersion(client, { portalAddress })
+
+  // Legacy
+  if (portalVersion.major < 3) {
+    const l2OutputOracleAddress = (() => {
+      if (parameters.l2OutputOracleAddress)
+        return parameters.l2OutputOracleAddress
+      if (chain) return targetChain!.contracts.l2OutputOracle[chain.id].address
+      return Object.values(targetChain!.contracts.l2OutputOracle)[0].address
+    })()
+    const [[_outputRoot, proveTimestamp, _l2OutputIndex], period] =
+      await multicall(client, {
+        allowFailure: false,
+        contracts: [
+          {
+            abi: portalAbi,
+            address: portalAddress,
+            functionName: 'provenWithdrawals',
+            args: [withdrawalHash],
+          },
+          {
+            abi: l2OutputOracleAbi,
+            address: l2OutputOracleAddress,
+            functionName: 'FINALIZATION_PERIOD_SECONDS',
+          },
+        ],
+      })
+
+    const secondsSinceProven = Date.now() / 1000 - Number(proveTimestamp)
+    const secondsToFinalize = Number(period) - secondsSinceProven
+
+    const seconds = Math.floor(
+      secondsToFinalize < 0 ? 0 : secondsToFinalize + buffer,
+    )
+    const timestamp = Date.now() + seconds * 1000
+
+    return { period: Number(period), seconds, timestamp }
+  }
+
+  const [[_disputeGameProxy, proveTimestamp], proofMaturityDelaySeconds] =
+    await Promise.all([
+      readContract(client, {
+        abi: portal2Abi,
+        address: portalAddress,
+        functionName: 'provenWithdrawals',
+        args: [withdrawalHash],
+      }),
+      readContract(client, {
+        abi: portal2Abi,
+        address: portalAddress,
+        functionName: 'proofMaturityDelaySeconds',
+      }),
+    ])
+
+  if (proveTimestamp === 0n)
+    throw new BaseError('Withdrawal has not been proven on L1.')
+
+  const secondsSinceProven = Date.now() / 1000 - Number(proveTimestamp)
+  const secondsToFinalize =
+    Number(proofMaturityDelaySeconds) - secondsSinceProven
+
+  const seconds = Math.floor(
+    secondsToFinalize < 0n ? 0 : secondsToFinalize + buffer,
+  )
+  const timestamp = Date.now() + seconds * 1000
+
+  return { period: Number(proofMaturityDelaySeconds), seconds, timestamp }
+}