Wallet Developer Integration Guide

const DEFAULT_GAS_LIMIT_MARGIN_BPS = 15_000n // 1.5x

const GAS_LIMIT_MARGIN_BPS_BY_CHAIN: Record<number, bigint> = {
  // 7.5% buffer. Measure against your wallet's transaction mix.
  143: 10_750n,
  10143: 10_750n,
}

export const applyGasLimitMargin = ({
  chainId,
  estimatedGas,
}: {
  chainId: number
  estimatedGas: bigint
}) => {
  const margin = GAS_LIMIT_MARGIN_BPS_BY_CHAIN[chainId] ?? DEFAULT_GAS_LIMIT_MARGIN_BPS
  return (estimatedGas * margin + 9_999n) / 10_000n
}

const CHAINS_CHARGING_GAS_LIMIT = new Set([143, 10143])
// Warn only on egregious overrides — not normal 1.5–2x safety buffers.
const OVERSPEND_WARNING_MULTIPLIER = 10n

export const shouldWarnGasLimitOverspend = ({
  chainId,
  gasLimit,
  recommendedGasLimit,
}: {
  chainId: number
  gasLimit: bigint
  recommendedGasLimit: bigint
}) => {
  if (!CHAINS_CHARGING_GAS_LIMIT.has(chainId)) return false
  if (recommendedGasLimit <= 0n || gasLimit < 21_000n) return false

  return gasLimit > recommendedGasLimit * OVERSPEND_WARNING_MULTIPLIER
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

const hexToBigInt = (hex: string) => BigInt(hex)

export const waitForReceipt = async (provider: EIP1193Provider, txHash: string) => {
  while (true) {
    // A receipt means the transaction has executed locally on this RPC node.
    const receipt = await provider.request({
      method: "eth_getTransactionReceipt",
      params: [txHash],
    })

    if (receipt) return receipt
    await sleep(400)
  }
}

export const waitUntilFinalized = async (provider: EIP1193Provider, receiptBlockNumber: string) => {
  while (true) {
    // Compare the receipt's block with the node's finalized commitment level.
    const finalizedBlock = await provider.request({
      method: "eth_getBlockByNumber",
      params: ["finalized", false],
    })

    if (hexToBigInt(finalizedBlock.number) >= hexToBigInt(receiptBlockNumber)) return
    await sleep(400)
  }
}