viem 2.9.2 → 2.9.3

package/op-stack/actions/estimateContractTotalFee.ts

@@ -0,0 +1,144 @@
+import type { Abi } from 'abitype'
+
+import type { Account } from '../../accounts/types.js'
+import {
+  type ParseAccountErrorType,
+  parseAccount,
+} from '../../accounts/utils/parseAccount.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { BaseError } from '../../errors/base.js'
+import type { Chain } from '../../types/chain.js'
+import type {
+  ContractFunctionArgs,
+  ContractFunctionName,
+  ContractFunctionParameters,
+  GetValue,
+} from '../../types/contract.js'
+import type { UnionOmit } from '../../types/utils.js'
+import {
+  type EncodeFunctionDataErrorType,
+  type EncodeFunctionDataParameters,
+  encodeFunctionData,
+} from '../../utils/abi/encodeFunctionData.js'
+import {
+  type GetContractErrorReturnType,
+  getContractError,
+} from '../../utils/errors/getContractError.js'
+import {
+  type EstimateTotalFeeErrorType,
+  type EstimateTotalFeeParameters,
+  estimateTotalFee,
+} from './estimateTotalFee.js'
+
+export type EstimateContractTotalFeeParameters<
+  abi extends Abi | readonly unknown[] = Abi,
+  functionName extends ContractFunctionName<
+    abi,
+    'nonpayable' | 'payable'
+  > = ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+  args extends ContractFunctionArgs<
+    abi,
+    'nonpayable' | 'payable',
+    functionName
+  > = ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+> = ContractFunctionParameters<
+  abi,
+  'nonpayable' | 'payable',
+  functionName,
+  args
+> &
+  UnionOmit<
+    EstimateTotalFeeParameters<chain, account, chainOverride>,
+    'data' | 'to' | 'value'
+  > &
+  GetValue<
+    abi,
+    functionName,
+    EstimateTotalFeeParameters<
+      chain,
+      account,
+      chainOverride
+    > extends EstimateTotalFeeParameters
+      ? EstimateTotalFeeParameters<chain, account, chainOverride>['value']
+      : EstimateTotalFeeParameters['value']
+  >
+
+export type EstimateContractTotalFeeReturnType = bigint
+
+export type EstimateContractTotalFeeErrorType = GetContractErrorReturnType<
+  | EncodeFunctionDataErrorType
+  | EstimateTotalFeeErrorType
+  | ParseAccountErrorType
+>
+
+/**
+ * Estimates the L1 data fee + L2 fee to execute an L2 contract write.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link EstimateContractTotalFeeParameters}
+ * @returns The gas estimate (in wei). {@link EstimateContractTotalFeeReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseAbi } from 'viem'
+ * import { optimism } from 'viem/chains'
+ * import { estimateContractTotalFee } from 'viem/op-stack'
+ *
+ * const client = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ * const totalFee = await estimateContractTotalFee(client, {
+ *   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+ *   abi: parseAbi(['function mint() public']),
+ *   functionName: 'mint',
+ *   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+ * })
+ */
+export async function estimateContractTotalFee<
+  const abi extends Abi | readonly unknown[],
+  functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+  args extends ContractFunctionArgs<abi, 'pure' | 'view', functionName>,
+  chain extends Chain | undefined,
+  account extends Account | undefined = undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: EstimateContractTotalFeeParameters<
+    abi,
+    functionName,
+    args,
+    chain,
+    account,
+    chainOverride
+  >,
+): Promise<EstimateContractTotalFeeReturnType> {
+  const { abi, address, args, functionName, ...request } =
+    parameters as EstimateContractTotalFeeParameters
+  const data = encodeFunctionData({
+    abi,
+    args,
+    functionName,
+  } as EncodeFunctionDataParameters)
+  try {
+    const fee = await estimateTotalFee(client, {
+      data,
+      to: address,
+      ...request,
+    } as unknown as EstimateTotalFeeParameters)
+    return fee
+  } catch (error) {
+    const account = request.account ? parseAccount(request.account) : undefined
+    throw getContractError(error as BaseError, {
+      abi,
+      address,
+      args,
+      docsPath: '/docs/chains/op-stack/estimateTotalFee',
+      functionName,
+      sender: account?.address,
+    })
+  }
+}

package/op-stack/actions/estimateContractTotalGas.ts

@@ -0,0 +1,144 @@
+import type { Abi } from 'abitype'
+
+import type { Account } from '../../accounts/types.js'
+import {
+  type ParseAccountErrorType,
+  parseAccount,
+} from '../../accounts/utils/parseAccount.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { BaseError } from '../../errors/base.js'
+import type { Chain } from '../../types/chain.js'
+import type {
+  ContractFunctionArgs,
+  ContractFunctionName,
+  ContractFunctionParameters,
+  GetValue,
+} from '../../types/contract.js'
+import type { UnionOmit } from '../../types/utils.js'
+import {
+  type EncodeFunctionDataErrorType,
+  type EncodeFunctionDataParameters,
+  encodeFunctionData,
+} from '../../utils/abi/encodeFunctionData.js'
+import {
+  type GetContractErrorReturnType,
+  getContractError,
+} from '../../utils/errors/getContractError.js'
+import {
+  type EstimateTotalGasErrorType,
+  type EstimateTotalGasParameters,
+  estimateTotalGas,
+} from './estimateTotalGas.js'
+
+export type EstimateContractTotalGasParameters<
+  abi extends Abi | readonly unknown[] = Abi,
+  functionName extends ContractFunctionName<
+    abi,
+    'nonpayable' | 'payable'
+  > = ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+  args extends ContractFunctionArgs<
+    abi,
+    'nonpayable' | 'payable',
+    functionName
+  > = ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = undefined,
+  chainOverride extends Chain | undefined = Chain | undefined,
+> = ContractFunctionParameters<
+  abi,
+  'nonpayable' | 'payable',
+  functionName,
+  args
+> &
+  UnionOmit<
+    EstimateTotalGasParameters<chain, account, chainOverride>,
+    'data' | 'to' | 'value'
+  > &
+  GetValue<
+    abi,
+    functionName,
+    EstimateTotalGasParameters<
+      chain,
+      account,
+      chainOverride
+    > extends EstimateTotalGasParameters
+      ? EstimateTotalGasParameters<chain, account, chainOverride>['value']
+      : EstimateTotalGasParameters['value']
+  >
+
+export type EstimateContractTotalGasReturnType = bigint
+
+export type EstimateContractTotalGasErrorType = GetContractErrorReturnType<
+  | EncodeFunctionDataErrorType
+  | EstimateTotalGasErrorType
+  | ParseAccountErrorType
+>
+
+/**
+ * Estimates the L1 data gas + L2 gas required to successfully execute a contract write function call.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link EstimateContractTotalGasParameters}
+ * @returns The gas estimate (in wei). {@link EstimateContractTotalGasReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseAbi } from 'viem'
+ * import { optimism } from 'viem/chains'
+ * import { estimateContractTotalGas } from 'viem/op-stack'
+ *
+ * const client = createPublicClient({
+ *   chain: optimism,
+ *   transport: http(),
+ * })
+ * const totalGas = await estimateContractTotalGas(client, {
+ *   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+ *   abi: parseAbi(['function mint() public']),
+ *   functionName: 'mint',
+ *   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+ * })
+ */
+export async function estimateContractTotalGas<
+  const abi extends Abi | readonly unknown[],
+  functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+  args extends ContractFunctionArgs<abi, 'pure' | 'view', functionName>,
+  chain extends Chain | undefined,
+  account extends Account | undefined = undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: EstimateContractTotalGasParameters<
+    abi,
+    functionName,
+    args,
+    chain,
+    account,
+    chainOverride
+  >,
+): Promise<EstimateContractTotalGasReturnType> {
+  const { abi, address, args, functionName, ...request } =
+    parameters as EstimateContractTotalGasParameters
+  const data = encodeFunctionData({
+    abi,
+    args,
+    functionName,
+  } as EncodeFunctionDataParameters)
+  try {
+    const gas = await estimateTotalGas(client, {
+      data,
+      to: address,
+      ...request,
+    } as unknown as EstimateTotalGasParameters)
+    return gas
+  } catch (error) {
+    const account = request.account ? parseAccount(request.account) : undefined
+    throw getContractError(error as BaseError, {
+      abi,
+      address,
+      args,
+      docsPath: '/docs/chains/op-stack/estimateTotalGas',
+      functionName,
+      sender: account?.address,
+    })
+  }
+}

package/op-stack/actions/estimateDepositTransactionGas.ts

@@ -0,0 +1,138 @@
+import type { Address } from 'abitype'
+import {
+  type EstimateContractGasErrorType,
+  type EstimateContractGasParameters,
+  estimateContractGas,
+} from '../../actions/public/estimateContractGas.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { zeroAddress } from '../../constants/address.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 { 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 { DepositRequest } from '../types/deposit.js'
+
+export type EstimateDepositTransactionGasParameters<
+  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> &
+  GetContractAddressParameter<_derivedChain, 'portal'> & {
+    /** L2 transaction request. */
+    request: DepositRequest
+    /** Gas limit for transaction execution on the L1. */
+    gas?: bigint | null | undefined
+  }
+export type EstimateDepositTransactionGasReturnType = bigint
+export type EstimateDepositTransactionGasErrorType =
+  | EstimateContractGasErrorType
+  | ErrorType
+
+/**
+ * Estimates gas required to initiate a [deposit transaction](https://github.com/ethereum-optimism/optimism/blob/develop/specs/deposits.md) on an L1, which executes a transaction on L2.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/estimateDepositTransactionGas
+ *
+ * @param client - Client to use
+ * @param parameters - {@link EstimateDepositTransactionGasParameters}
+ * @returns The L1 transaction hash. {@link EstimateDepositTransactionGasReturnType}
+ *
+ * @example
+ * import { createPublicClient, custom, parseEther } from 'viem'
+ * import { base, mainnet } from 'viem/chains'
+ * import { estimateDepositTransactionGas } from 'viem/op-stack'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * })
+ *
+ * const gas = await estimateDepositTransactionGas(client, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   args: {
+ *     gas: 21_000n,
+ *     to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *     value: parseEther('1'),
+ *   },
+ *   targetChain: base,
+ * })
+ */
+export async function estimateDepositTransactionGas<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: EstimateDepositTransactionGasParameters<
+    chain,
+    account,
+    chainOverride
+  >,
+) {
+  const {
+    account,
+    chain = client.chain,
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    request: {
+      data = '0x',
+      gas: l2Gas,
+      isCreation = false,
+      mint,
+      to = '0x',
+      value,
+    },
+    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
+  })()
+
+  return estimateContractGas(client, {
+    account,
+    abi: portalAbi,
+    address: portalAddress,
+    chain,
+    functionName: 'depositTransaction',
+    args: [
+      isCreation ? zeroAddress : to,
+      value ?? mint ?? 0n,
+      l2Gas,
+      isCreation,
+      data,
+    ],
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    value: mint,
+  } as EstimateContractGasParameters)
+}

package/op-stack/actions/estimateFinalizeWithdrawalGas.ts

@@ -0,0 +1,118 @@
+import type { Address } from 'abitype'
+import {
+  type EstimateContractGasErrorType,
+  type EstimateContractGasParameters,
+  estimateContractGas,
+} from '../../actions/public/estimateContractGas.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 { 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 { Withdrawal } from '../types/withdrawal.js'
+
+export type EstimateFinalizeWithdrawalGasParameters<
+  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> &
+  GetContractAddressParameter<_derivedChain, 'portal'> & {
+    /** Gas limit for transaction execution on the L2. */
+    gas?: bigint | null | undefined
+    withdrawal: Withdrawal
+  }
+export type EstimateFinalizeWithdrawalGasReturnType = bigint
+export type EstimateFinalizeWithdrawalGasErrorType =
+  | EstimateContractGasErrorType
+  | ErrorType
+
+/**
+ * Estimates gas required to finalize a withdrawal that occurred on an L2.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/estimateFinalizeWithdrawalGas
+ *
+ * @param client - Client to use
+ * @param parameters - {@link EstimateFinalizeWithdrawalGasParameters}
+ * @returns Estimated gas. {@link EstimateFinalizeWithdrawalGasReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseEther } from 'viem'
+ * import { base, mainnet } from 'viem/chains'
+ * import { estimateFinalizeWithdrawalGas } from 'viem/op-stack'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const gas = await estimateFinalizeWithdrawalGas(client, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   targetChain: optimism,
+ *   withdrawal: { ... },
+ * })
+ */
+export async function estimateFinalizeWithdrawalGas<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: EstimateFinalizeWithdrawalGasParameters<
+    chain,
+    account,
+    chainOverride
+  >,
+) {
+  const {
+    account,
+    chain = client.chain,
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    targetChain,
+    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
+  })()
+
+  return estimateContractGas(client, {
+    account,
+    abi: portalAbi,
+    address: portalAddress,
+    chain,
+    functionName: 'finalizeWithdrawalTransaction',
+    args: [withdrawal],
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+  } as EstimateContractGasParameters)
+}

package/op-stack/actions/estimateInitiateWithdrawalGas.ts

@@ -0,0 +1,118 @@
+import type { Address } from 'abitype'
+import {
+  type EstimateContractGasErrorType,
+  type EstimateContractGasParameters,
+  estimateContractGas,
+} from '../../actions/public/estimateContractGas.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 { 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'
+
+export type EstimateInitiateWithdrawalGasParameters<
+  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. */
+    gas?: bigint | null | undefined
+    /**
+     * Withdrawal request.
+     * Supplied to the L2ToL1MessagePasser `initiateWithdrawal` method.
+     */
+    request: WithdrawalRequest
+  }
+export type EstimateInitiateWithdrawalGasReturnType = bigint
+export type EstimateInitiateWithdrawalGasErrorType =
+  | EstimateContractGasErrorType
+  | ErrorType
+
+/**
+ * Estimates gas required to initiate a [withdrawal](https://community.optimism.io/docs/protocol/withdrawal-flow/#withdrawal-initiating-transaction) on an L2 to the L1.
+ *
+ * - Docs: https://viem.sh/op-stack/actions/estimateInitiateWithdrawalGas
+ *
+ * @param client - Client to use
+ * @param parameters - {@link EstimateInitiateWithdrawalGasParameters}
+ * @returns Estimated gas. {@link EstimateInitiateWithdrawalGasReturnType}
+ *
+ * @example
+ * import { createPublicClient, http, parseEther } from 'viem'
+ * import { base, mainnet } from 'viem/chains'
+ * import { estimateInitiateWithdrawalGas } from 'viem/op-stack'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const gas = await estimateInitiateWithdrawalGas(client, {
+ *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+ *   request: {
+ *     gas: 21_000n,
+ *     to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+ *     value: parseEther('1'),
+ *   },
+ * })
+ */
+export async function estimateInitiateWithdrawalGas<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  chainOverride extends Chain | undefined = undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: EstimateInitiateWithdrawalGasParameters<
+    chain,
+    account,
+    chainOverride
+  >,
+) {
+  const {
+    account,
+    chain = client.chain,
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    request: { data = '0x', gas: l1Gas, to, value },
+  } = parameters
+
+  return estimateContractGas(client, {
+    account,
+    abi: l2ToL1MessagePasserAbi,
+    address: contracts.l2ToL1MessagePasser.address,
+    chain,
+    functionName: 'initiateWithdrawal',
+    args: [to, l1Gas, data],
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    value,
+  } as EstimateContractGasParameters)
+}