viem 2.9.1 → 2.9.3

package/op-stack/actions/getWithdrawalStatus.ts

@@ -0,0 +1,244 @@
+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 { ContractFunctionRevertedError } from '../../errors/contract.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 { TransactionReceipt } from '../../types/transaction.js'
+import type { OneOf } from '../../types/utils.js'
+import { portal2Abi, portalAbi } from '../abis.js'
+import { ReceiptContainsNoWithdrawalsError } from '../errors/withdrawal.js'
+import type { TargetChain } from '../types/chain.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import {
+  type GetWithdrawalsErrorType,
+  getWithdrawals,
+} from '../utils/getWithdrawals.js'
+import {
+  type GetGameErrorType,
+  type GetGameParameters,
+  getGame,
+} from './getGame.js'
+import {
+  type GetL2OutputErrorType,
+  type GetL2OutputParameters,
+  getL2Output,
+} from './getL2Output.js'
+import {
+  type GetPortalVersionParameters,
+  getPortalVersion,
+} from './getPortalVersion.js'
+import {
+  type GetTimeToFinalizeErrorType,
+  type GetTimeToFinalizeParameters,
+  getTimeToFinalize,
+} from './getTimeToFinalize.js'
+
+export type GetWithdrawalStatusParameters<
+  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' | 'portal'>
+    | GetContractAddressParameter<
+        _derivedChain,
+        'disputeGameFactory' | 'portal'
+      >
+  > & {
+    /**
+     * Limit of games to extract to check withdrawal status.
+     * @default 100
+     */
+    gameLimit?: number
+    receipt: TransactionReceipt
+  }
+export type GetWithdrawalStatusReturnType =
+  | 'waiting-to-prove'
+  | 'ready-to-prove'
+  | 'waiting-to-finalize'
+  | 'ready-to-finalize'
+  | 'finalized'
+export type GetWithdrawalStatusErrorType =
+  | GetL2OutputErrorType
+  | GetTimeToFinalizeErrorType
+  | GetWithdrawalsErrorType
+  | ReadContractErrorType
+  | ErrorType
+
+/**
+ * Returns the current status of a withdrawal. Used for the [Withdrawal](/op-stack/guides/withdrawals) flow.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/getWithdrawalStatus
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetWithdrawalStatusParameters}
+ * @returns Status of the withdrawal. {@link GetWithdrawalStatusReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { getBlockNumber } from 'viem/actions'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { getWithdrawalStatus } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const publicClientL2 = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ *
+ * const receipt = await publicClientL2.getTransactionReceipt({ hash: '0x...' })
+ * const status = await getWithdrawalStatus(publicClientL1, {
+ *   receipt,
+ *   targetChain: optimism
+ * })
+ */
+export async function getWithdrawalStatus<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: GetWithdrawalStatusParameters<chain, chainOverride>,
+): Promise<GetWithdrawalStatusReturnType> {
+  const {
+    chain = client.chain,
+    gameLimit = 100,
+    receipt,
+    targetChain: targetChain_,
+  } = parameters
+
+  const targetChain = targetChain_ as unknown as TargetChain
+
+  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 [withdrawal] = getWithdrawals(receipt)
+
+  if (!withdrawal)
+    throw new ReceiptContainsNoWithdrawalsError({
+      hash: receipt.transactionHash,
+    })
+
+  const portalVersion = await getPortalVersion(
+    client,
+    parameters as GetPortalVersionParameters,
+  )
+
+  // Legacy (Portal < v3)
+  if (portalVersion.major < 3) {
+    const [outputResult, proveResult, finalizedResult, timeToFinalizeResult] =
+      await Promise.allSettled([
+        getL2Output(client, {
+          ...parameters,
+          l2BlockNumber: receipt.blockNumber,
+        } as GetL2OutputParameters),
+        readContract(client, {
+          abi: portalAbi,
+          address: portalAddress,
+          functionName: 'provenWithdrawals',
+          args: [withdrawal.withdrawalHash],
+        }),
+        readContract(client, {
+          abi: portalAbi,
+          address: portalAddress,
+          functionName: 'finalizedWithdrawals',
+          args: [withdrawal.withdrawalHash],
+        }),
+        getTimeToFinalize(client, {
+          ...parameters,
+          withdrawalHash: withdrawal.withdrawalHash,
+        } as GetTimeToFinalizeParameters),
+      ])
+
+    // If the L2 Output is not processed yet (ie. the actions throws), this means
+    // that the withdrawal is not ready to prove.
+    if (outputResult.status === 'rejected') {
+      const error = outputResult.reason as GetL2OutputErrorType
+      if (
+        error.cause instanceof ContractFunctionRevertedError &&
+        error.cause.data?.args?.[0] ===
+          'L2OutputOracle: cannot get output for a block that has not been proposed'
+      )
+        return 'waiting-to-prove'
+      throw error
+    }
+    if (proveResult.status === 'rejected') throw proveResult.reason
+    if (finalizedResult.status === 'rejected') throw finalizedResult.reason
+    if (timeToFinalizeResult.status === 'rejected')
+      throw timeToFinalizeResult.reason
+
+    const [_, proveTimestamp] = proveResult.value
+    if (!proveTimestamp) return 'ready-to-prove'
+
+    const finalized = finalizedResult.value
+    if (finalized) return 'finalized'
+
+    const { seconds } = timeToFinalizeResult.value
+    return seconds > 0 ? 'waiting-to-finalize' : 'ready-to-finalize'
+  }
+
+  const [disputeGameResult, checkWithdrawalResult, finalizedResult] =
+    await Promise.allSettled([
+      getGame(client, {
+        ...parameters,
+        l2BlockNumber: receipt.blockNumber,
+        limit: gameLimit,
+      } as GetGameParameters),
+      readContract(client, {
+        abi: portal2Abi,
+        address: portalAddress,
+        functionName: 'checkWithdrawal',
+        args: [withdrawal.withdrawalHash],
+      }),
+      readContract(client, {
+        abi: portal2Abi,
+        address: portalAddress,
+        functionName: 'finalizedWithdrawals',
+        args: [withdrawal.withdrawalHash],
+      }),
+    ])
+
+  if (finalizedResult.status === 'fulfilled' && finalizedResult.value)
+    return 'finalized'
+
+  if (disputeGameResult.status === 'rejected') {
+    const error = disputeGameResult.reason as GetGameErrorType
+    if (error.name === 'GameNotFoundError') return 'waiting-to-prove'
+    throw disputeGameResult.reason
+  }
+  if (checkWithdrawalResult.status === 'rejected') {
+    const error = checkWithdrawalResult.reason as ReadContractErrorType
+    if (error.cause instanceof ContractFunctionRevertedError) {
+      const errorMessage = error.cause.data?.args?.[0]
+      if (errorMessage === 'OptimismPortal: withdrawal has not been proven yet')
+        return 'ready-to-prove'
+      if (
+        errorMessage ===
+          'OptimismPortal: proven withdrawal has not matured yet' ||
+        errorMessage ===
+          'OptimismPortal: output proposal has not been finalized yet' ||
+        errorMessage === 'OptimismPortal: output proposal in air-gap'
+      )
+        return 'waiting-to-finalize'
+    }
+    throw checkWithdrawalResult.reason
+  }
+  if (finalizedResult.status === 'rejected') throw finalizedResult.reason
+
+  return 'ready-to-finalize'
+}

package/op-stack/actions/initiateWithdrawal.ts

@@ -0,0 +1,153 @@
+import type { Address } from 'abitype'
+import {
+  type WriteContractErrorType,
+  type WriteContractParameters,
+  writeContract,
+} from '../../actions/wallet/writeContract.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, GetAccountParameter } from '../../types/account.js'
+import type {
+  Chain,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import type { Hash } from '../../types/misc.js'
+import type { UnionEvaluate, UnionOmit } from '../../types/utils.js'
+import type { FormattedTransactionRequest } from '../../utils/formatters/transactionRequest.js'
+import { l2ToL1MessagePasserAbi } from '../abis.js'
+import { contracts } from '../contracts.js'
+import type { WithdrawalRequest } from '../types/withdrawal.js'
+import {
+  type EstimateInitiateWithdrawalGasErrorType,
+  type EstimateInitiateWithdrawalGasParameters,
+  estimateInitiateWithdrawalGas,
+} from './estimateInitiateWithdrawalGas.js'
+
+export type InitiateWithdrawalParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = UnionEvaluate<
+  UnionOmit<
+    FormattedTransactionRequest<_derivedChain>,
+    | 'accessList'
+    | 'data'
+    | 'from'
+    | 'gas'
+    | 'gasPrice'
+    | 'to'
+    | 'type'
+    | 'value'
+  >
+> &
+  GetAccountParameter<account, Account | Address> &
+  GetChainParameter<chain, chainOverride> & {
+    /**
+     * Gas limit for transaction execution on the L2.
+     * `null` to skip gas estimation & defer calculation to signer.
+     */
+    gas?: bigint | null
+    /** Withdrawal request. Supplied to the L2ToL1MessagePasser `initiateWithdrawal` method. */
+    request: WithdrawalRequest
+  }
+export type InitiateWithdrawalReturnType = Hash
+export type InitiateWithdrawalErrorType =
+  | EstimateInitiateWithdrawalGasErrorType
+  | WriteContractErrorType
+  | ErrorType
+
+/**
+ * Initiates a [withdrawal](https://community.optimism.io/docs/protocol/withdrawal-flow/#withdrawal-initiating-transaction) on an L2 to the L1.
+ *
+ * Internally performs a contract write to the [`initiateWithdrawal` function](https://github.com/ethereum-optimism/optimism/blob/283f0aa2e3358ced30ff7cbd4028c0c0c3faa140/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L73)
+ * on the [Optimism L2ToL1MessagePasser predeploy contract](https://github.com/ethereum-optimism/optimism/blob/283f0aa2e3358ced30ff7cbd4028c0c0c3faa140/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol).
+ *
+ * - Docs: https://viem.sh/op-stack/actions/initiateWithdrawal
+ *
+ * @param client - Client to use
+ * @param parameters - {@link InitiateWithdrawalParameters}
+ * @returns The L2 transaction hash. {@link InitiateWithdrawalReturnType}
+ *
+ * @example
+ * import { createWalletClient, custom, parseEther } from 'viem'
+ * import { base, mainnet } from 'viem/chains'
+ * import { initiateWithdrawal } from 'viem/op-stack'
+ *
+ * const client = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ *
+ * const hash = await initiateWithdrawal(client, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   args: {
+ *     gas: 21_000n,
+ *     to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *     value: parseEther('1'),
+ *   },
+ * })
+ *
+ * @example
+ * // Account Hoisting
+ * import { createWalletClient, http } from 'viem'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ * import { base, mainnet } from 'viem/chains'
+ * import { initiateWithdrawal } from 'viem/op-stack'
+ *
+ * const client = createWalletClient({
+ *   account: privateKeyToAccount('0x…'),
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const hash = await initiateWithdrawal(client, {
+ *   request: {
+ *     gas: 21_000n,
+ *     to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *     value: parseEther('1'),
+ *   },
+ * })
+ */
+export async function initiateWithdrawal<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: InitiateWithdrawalParameters<chain, account, chainOverride>,
+) {
+  const {
+    account,
+    chain = client.chain,
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    request: { data = '0x', gas: l1Gas, to, value },
+  } = parameters
+
+  const gas_ =
+    typeof gas !== 'number' && gas !== null
+      ? await estimateInitiateWithdrawalGas(
+          client,
+          parameters as EstimateInitiateWithdrawalGasParameters,
+        )
+      : undefined
+
+  return writeContract(client, {
+    account: account!,
+    abi: l2ToL1MessagePasserAbi,
+    address: contracts.l2ToL1MessagePasser.address,
+    chain,
+    functionName: 'initiateWithdrawal',
+    args: [to, l1Gas, data],
+    gas: gas_,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    value,
+  } satisfies WriteContractParameters as any)
+}

package/op-stack/actions/proveWithdrawal.ts

@@ -0,0 +1,154 @@
+import type { Address } from 'abitype'
+import {
+  type WriteContractErrorType,
+  type WriteContractParameters,
+  writeContract,
+} from '../../actions/wallet/writeContract.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, GetAccountParameter } from '../../types/account.js'
+import type {
+  Chain,
+  DeriveChain,
+  GetChainParameter,
+} from '../../types/chain.js'
+import type { Hash, Hex } from '../../types/misc.js'
+import type { UnionEvaluate, UnionOmit } from '../../types/utils.js'
+import type { FormattedTransactionRequest } from '../../utils/formatters/transactionRequest.js'
+import { portalAbi } from '../abis.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import {
+  type EstimateProveWithdrawalGasErrorType,
+  type EstimateProveWithdrawalGasParameters,
+  estimateProveWithdrawalGas,
+} from './estimateProveWithdrawalGas.js'
+
+export type ProveWithdrawalParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+  _derivedChain extends Chain | undefined = DeriveChain<chain, chainOverride>,
+> = UnionEvaluate<
+  UnionOmit<
+    FormattedTransactionRequest<_derivedChain>,
+    | 'accessList'
+    | 'blobs'
+    | 'data'
+    | 'from'
+    | 'gas'
+    | 'maxFeePerBlobGas'
+    | 'gasPrice'
+    | 'to'
+    | 'type'
+    | 'value'
+  >
+> &
+  GetAccountParameter<account, Account | Address> &
+  GetChainParameter<chain, chainOverride> &
+  GetContractAddressParameter<_derivedChain, 'portal'> & {
+    /**
+     * Gas limit for transaction execution on the L1.
+     * `null` to skip gas estimation & defer calculation to signer.
+     */
+    gas?: bigint | null | undefined
+    l2OutputIndex: bigint
+    outputRootProof: {
+      version: Hex
+      stateRoot: Hex
+      messagePasserStorageRoot: Hex
+      latestBlockhash: Hex
+    }
+    withdrawalProof: readonly Hex[]
+    withdrawal: {
+      data: Hex
+      gasLimit: bigint
+      nonce: bigint
+      sender: Address
+      target: Address
+      value: bigint
+    }
+  }
+export type ProveWithdrawalReturnType = Hash
+export type ProveWithdrawalErrorType =
+  | EstimateProveWithdrawalGasErrorType
+  | WriteContractErrorType
+  | ErrorType
+
+/**
+ * Proves a withdrawal that occurred on an L2. Used in the Withdrawal flow.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/proveWithdrawal
+ *
+ * @param client - Client to use
+ * @param parameters - {@link ProveWithdrawalParameters}
+ * @returns The prove transaction hash. {@link ProveWithdrawalReturnType}
+ *
+ * @example
+ * import { createWalletClient, http } from 'viem'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { proveWithdrawal } from 'viem/op-stack'
+ *
+ * const walletClientL1 = createWalletClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const request = await proveWithdrawal(walletClientL1, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   l2OutputIndex: 4529n,
+ *   outputRootProof: { ... },
+ *   targetChain: optimism,
+ *   withdrawalProof: [ ... ],
+ *   withdrawal: { ... },
+ * })
+ */
+export async function proveWithdrawal<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: ProveWithdrawalParameters<chain, account, chainOverride>,
+): Promise<ProveWithdrawalReturnType> {
+  const {
+    account,
+    chain = client.chain,
+    gas,
+    l2OutputIndex,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    outputRootProof,
+    targetChain,
+    withdrawalProof,
+    withdrawal,
+  } = 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 gas_ =
+    typeof gas !== 'bigint' && gas !== null
+      ? await estimateProveWithdrawalGas(
+          client,
+          parameters as EstimateProveWithdrawalGasParameters,
+        )
+      : gas ?? undefined
+
+  return writeContract(client, {
+    account: account!,
+    abi: portalAbi,
+    address: portalAddress,
+    chain,
+    functionName: 'proveWithdrawalTransaction',
+    args: [withdrawal, l2OutputIndex, outputRootProof, withdrawalProof],
+    gas: gas_,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+  } satisfies WriteContractParameters as any)
+}

package/op-stack/actions/waitForNextGame.ts

@@ -0,0 +1,122 @@
+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 { poll } from '../../utils/poll.js'
+import { GameNotFoundError } from '../errors/withdrawal.js'
+import type { GetContractAddressParameter } from '../types/contract.js'
+import {
+  type GetGameErrorType,
+  type GetGameReturnType,
+  getGame,
+} from './getGame.js'
+import {
+  type GetTimeToNextGameErrorType,
+  type GetTimeToNextGameParameters,
+  getTimeToNextGame,
+} from './getTimeToNextGame.js'
+
+export type WaitForNextGameParameters<
+  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'
+  > & {
+    /**
+     * Limit of games to extract.
+     * @default 100
+     */
+    limit?: number | undefined
+    /**
+     * The buffer to account for discrepencies between non-deterministic time intervals.
+     * @default 1.1
+     */
+    intervalBuffer?: GetTimeToNextGameParameters['intervalBuffer'] | undefined
+    l2BlockNumber: bigint
+    /**
+     * Polling frequency (in ms). Defaults to Client's pollingInterval config.
+     * @default client.pollingInterval
+     */
+    pollingInterval?: number | undefined
+  }
+export type WaitForNextGameReturnType = GetGameReturnType
+export type WaitForNextGameErrorType =
+  | GetGameErrorType
+  | GetTimeToNextGameErrorType
+  | ErrorType
+
+/**
+ * Waits for the next dispute game (after the provided block number) to be submitted.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/waitForNextGame
+ *
+ * @param client - Client to use
+ * @param parameters - {@link WaitForNextGameParameters}
+ * @returns The L2 transaction hash. {@link WaitForNextGameReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { getBlockNumber } from 'viem/actions'
+ * import { mainnet, optimism } from 'viem/chains'
+ * import { waitForNextGame } from 'viem/op-stack'
+ *
+ * const publicClientL1 = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const publicClientL2 = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ *
+ * const l2BlockNumber = await getBlockNumber(publicClientL2)
+ * await waitForNextGame(publicClientL1, {
+ *   l2BlockNumber,
+ *   targetChain: optimism
+ * })
+ */
+export async function waitForNextGame<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: WaitForNextGameParameters<chain, chainOverride>,
+): Promise<WaitForNextGameReturnType> {
+  const { pollingInterval = client.pollingInterval } = parameters
+
+  const { seconds } = await getTimeToNextGame(client, parameters)
+
+  return new Promise((resolve, reject) => {
+    poll(
+      async ({ unpoll }) => {
+        try {
+          const game = await getGame(client, {
+            ...parameters,
+            strategy: 'random',
+          })
+          unpoll()
+          resolve(game)
+        } catch (e) {
+          const error = e as GetGameErrorType
+          if (!(error instanceof GameNotFoundError)) {
+            unpoll()
+            reject(e)
+          }
+        }
+      },
+      {
+        interval: pollingInterval,
+        initialWaitTime: async () => seconds * 1000,
+      },
+    )
+  })
+}