@exodus/ethereum-api 9.0.0-alpha.2 → 9.0.0

package/src/tx-create.js

@@ -0,0 +1,666 @@
+import {
+  assertValidTxValue,
+  currency2buffer,
+  getHighestIncentiveTxByNonce,
+  isEthereumLikeToken,
+} from '@exodus/ethereum-lib'
+import createEthereumJsTx from '@exodus/ethereum-lib/src/unsigned-tx/create-ethereumjs-tx.js'
+import assert from 'minimalistic-assert'
+
+import { ensureSaneEip1559GasPriceForTipGasPrice } from './fee-utils.js'
+import { fetchGasLimit } from './gas-estimation.js'
+import { getAggregateTransactionPricing, getExtraFeeData } from './get-fee.js'
+import { getNftArguments } from './nft-utils.js'
+import {
+  assertTxAttributes,
+  isValidTxType,
+  resolveTxAttributesByTxType,
+  resolveTxFromAddress,
+  resolveTxNonce,
+  TX_TYPE_TRANSFER,
+} from './tx-type/index.js'
+
+// Thrown by `resolveAmountIncludesFeeTxAttributes` when the fee subtraction
+// implied by `amountIncludesFee` would drive the resulting tx value below
+// zero (i.e. the caller's balance can't cover the computed fee). Exported so
+// callers like MoveFunds can `instanceof`-check and translate it into their
+// own user-facing error type without string-matching the message.
+export class AmountIncludesFeeUnderflowError extends Error {
+  constructor() {
+    super('transaction gas cost exceeds fee-inclusive amount')
+    this.name = 'AmountIncludesFeeUnderflowError'
+  }
+}
+
+async function calculateFee({
+  asset,
+  chainId,
+  eip1559Enabled,
+  gasLimit,
+  gasPrice,
+  tipGasPrice,
+  nonce,
+  txInput,
+  txToAddress,
+  txValue,
+}) {
+  const ethjsTx = createEthereumJsTx({
+    txData: {
+      nonce,
+      gasPrice: currency2buffer(gasPrice),
+      tipGasPrice: tipGasPrice ? currency2buffer(tipGasPrice) : undefined,
+      gasLimit,
+      to: txToAddress,
+      value: currency2buffer(txValue),
+      data: txInput,
+      chainId,
+    },
+    txMeta: {
+      eip1559Enabled,
+    },
+  })
+  const transactionBuffer = ethjsTx.serialize()
+
+  const baseFee = gasPrice.mul(gasLimit)
+  const optimismL1DataFee = asset.baseAsset.estimateL1DataFee
+    ? await asset.baseAsset.estimateL1DataFee({
+        unsignedTx: { txData: { transactionBuffer, chainId } },
+      })
+    : undefined
+
+  const l1DataFee = optimismL1DataFee
+    ? asset.baseAsset.currency.baseUnit(optimismL1DataFee)
+    : asset.baseAsset.currency.ZERO
+
+  const fee = baseFee.add(l1DataFee)
+  return { fee, transactionBuffer }
+}
+
+async function createUnsignedTxWithFees({
+  asset,
+  chainId,
+  gasLimit,
+  eip1559Enabled,
+  gasPrice, // eip 1559: `maxFeePerGas`
+  tipGasPrice, // eip 1559: `maxPriorityPerGas`
+  bumpTxId,
+  /* txAttributes */
+  amount,
+  toAddress,
+  txInput,
+  txToAddress,
+  txType,
+  txValue,
+  fromAddress,
+  nonce,
+  isContractTxToAddress,
+}) {
+  assert(asset, 'asset is required')
+  assert(typeof chainId === 'number', 'chainId is required')
+  assert(gasLimit, 'gasLimit is required')
+  assert(gasPrice, 'gasPrice is required')
+  assert(typeof eip1559Enabled === 'boolean', 'eip1559Enabled is required')
+
+  assertTxAttributes({
+    amount,
+    toAddress,
+    txInput,
+    txToAddress,
+    txType,
+    txValue,
+    fromAddress,
+    nonce,
+    isContractTxToAddress,
+  })
+
+  const { fee, transactionBuffer } = await calculateFee({
+    asset,
+    chainId,
+    eip1559Enabled,
+    gasLimit,
+    gasPrice,
+    tipGasPrice,
+    nonce,
+    txInput,
+    txToAddress,
+    txValue,
+  })
+
+  const extraFeeData = getExtraFeeData({ asset, amount, txValue })
+  const unsignedTx = {
+    txData: { transactionBuffer, chainId },
+    txMeta: {
+      assetName: asset.name,
+      bumpTxId,
+      eip1559Enabled,
+      fromAddress,
+      toAddress,
+      amount: amount.toDefaultString({ unit: true }),
+      fee: fee.toDefaultString({ unit: true }),
+    },
+  }
+  return {
+    unsignedTx,
+    fee,
+    amount,
+    extraFeeData,
+    // exhcange compatibility until the use usignedTx, remove me!
+    gasPrice,
+    tipGasPrice,
+    gasLimit,
+  }
+}
+
+// TODO: Move this into tx attribute resolution once gasLimit is resolved there.
+// `amountIncludesFee` changes the tx value, so the fee subtraction should happen
+// in the same flow that finalizes amount, txValue, txInput, txToAddress, and
+// gasLimit.
+async function resolveAmountIncludesFeeTxAttributes({
+  amountIncludesFee,
+  asset,
+  chainId,
+  eip1559Enabled,
+  gasLimit,
+  gasPrice,
+  tipGasPrice,
+  txAttributes,
+}) {
+  const { amount, nonce, txInput, txToAddress, txValue } = txAttributes
+
+  // `amountIncludesFee` is a hint: subtract any fee that is paid in the same
+  // currency as `amount`. On EVM today, gas is paid in the native asset, so
+  // for ERC-20 sends and zero-value calldata (i.e approve()) flows there is nothing in the
+  // amount's currency to subtract. Pass through silently in those cases, so
+  // consumers can set this flag based on intent without needing to know
+  // whether the asset is a token or whether the call carries zero native
+  // value.
+  if (!amountIncludesFee || isEthereumLikeToken(asset) || amount.isZero) {
+    return { txAttributes }
+  }
+
+  const { fee } = await calculateFee({
+    asset,
+    chainId,
+    eip1559Enabled,
+    gasLimit,
+    gasPrice,
+    tipGasPrice,
+    nonce,
+    txInput,
+    txToAddress,
+    txValue,
+  })
+  const reducedAmount = amount.sub(fee)
+
+  if (!reducedAmount.gte(asset.currency.ZERO)) {
+    throw new AmountIncludesFeeUnderflowError()
+  }
+
+  return {
+    txAttributes: {
+      ...txAttributes,
+      amount: reducedAmount,
+      txValue: reducedAmount,
+    },
+  }
+}
+
+const resolveTxFactoryGasPrices = async ({
+  assetClientInterface,
+  baseAsset,
+  customFee: providedCustomFee,
+  feeData,
+  gasPrice: providedGasPrice,
+  tipGasPrice: providedTipGasPrice,
+  txToReplace,
+  nonce,
+}) => {
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(baseAsset, 'expected baseAsset')
+  assert(feeData, 'expected feeData')
+  assert(Number.isInteger(nonce), 'expected integer nonce')
+
+  const {
+    gasPrice: maybeGasPrice,
+    feeData: { tipGasPrice: maybeTipGasPrice, eip1559Enabled },
+  } = getAggregateTransactionPricing({
+    baseAsset,
+    customFee: providedCustomFee,
+    feeData,
+    txToReplace,
+  })
+
+  // When we determine the `gasPrice` for a transaction, we must be
+  // cognizant of any transactions which are pending for the current
+  // `nonce`, as this may be higher compared to the current `gasPrice`
+  // that we are recommending from the network.
+  //
+  // In this instance, the `gasPrice` we recommend should be
+  // sufficient to avoid `replacement transaction underpriced` errors.
+  const resolvedGasPrice = providedGasPrice ?? maybeGasPrice
+
+  if (!eip1559Enabled) return { eip1559Enabled, resolvedGasPrice }
+
+  const resolvedTipGasPrice = providedTipGasPrice ?? maybeTipGasPrice
+
+  return {
+    eip1559Enabled,
+    resolvedGasPrice: ensureSaneEip1559GasPriceForTipGasPrice({
+      gasPrice: resolvedGasPrice,
+      tipGasPrice: resolvedTipGasPrice,
+    }),
+    resolvedTipGasPrice,
+  }
+}
+
+// Pre-broadcast safety check for RBF replacements.
+//
+// Clarity can lag behind the node: it may still report a tx as pending after
+// the node has evicted it, or show a queued (gapped) tx as acceleratable.
+// Broadcasting an RBF for a gapped tx — one whose predecessor slot is empty in
+// the node's mempool — produces ErrFutureReplacePending.
+//
+// This check is best-effort: if either RPC call fails (network error, unsupported
+// endpoint, etc.) we fall through and let the broadcast surface the error.
+async function verifyBumpTxCanReplace({ baseAsset, bumpTxId, fromAddress, nonce }) {
+  let rpcTx, pendingNonceHex
+
+  try {
+    ;[rpcTx, pendingNonceHex] = await Promise.all([
+      baseAsset.server.getTransactionByHash(bumpTxId),
+      baseAsset.server.getTransactionCount(fromAddress, 'pending'),
+    ])
+  } catch (err) {
+    console.warn(
+      `verifyBumpTxCanReplace: pre-broadcast RPC check failed for ${bumpTxId}, falling through`,
+      err.message
+    )
+    return
+  }
+
+  if (!rpcTx) {
+    // The tx was dropped from the node's mempool — Clarity hasn't caught up yet.
+    // TODO: eagerly mark this tx as dropped in the tx log so the UI updates
+    // immediately instead of waiting for Clarity's next polling cycle.
+    throw new Error(
+      `ERR_BUMP_TX_DROPPED: Cannot bump transaction ${bumpTxId}: transaction was dropped from the network`
+    )
+  }
+
+  // pendingNonce = 4
+  // [0][1][2][3]{4}{5}{6}...
+  //              ^--- next empty slot (pendingNonce)
+  //
+  // Nonce to replace must be < pendingNonce (i.e. slot is already accounted for).
+  // If nonce >= pendingNonce, the slot is empty or gapped — not safe to replace.
+  const pendingNonce = parseInt(pendingNonceHex, 16)
+  if (pendingNonce <= nonce) {
+    // A predecessor tx was dropped by the node, leaving a gap below this tx.
+    // The tx itself is still in the node's queued pool but can't execute until
+    // the missing nonce slot is filled.
+    // TODO: identify the dropped predecessor (scan nonces from pendingNonce to
+    // nonce - 1), mark it as dropped in the tx log, and surface a clear message
+    // to the user: "a previous transaction was dropped — send a new transaction
+    // first, then you'll be able to accelerate this one."
+    throw new Error(
+      `ERR_BUMP_TX_NONCE_GAP: Cannot bump transaction ${bumpTxId}: nonce gap detected — ` +
+        `node's pending nonce (${pendingNonce}) ≤ tx nonce (${nonce}), ` +
+        `broadcasting would produce ErrFutureReplacePending`
+    )
+  }
+}
+
+const createBumpUnsignedTx = async ({
+  fromAddress,
+  chainId,
+  asset,
+  bumpTxId,
+  baseAssetTxLog,
+  assetClientInterface,
+  walletAccount,
+  feeData,
+  nonce: maybeProvidedNonce,
+  txType,
+}) => {
+  assert(isValidTxType(txType), 'invalid txType')
+
+  const baseAsset = asset.baseAsset
+  const replacedTx = baseAssetTxLog.get(bumpTxId)
+  const assets = await assetClientInterface.getAssetsForNetwork({ baseAssetName: baseAsset.name })
+  if (!replacedTx || !replacedTx.pending) {
+    throw new Error(`Cannot bump transaction ${bumpTxId}: not found or confirmed`)
+  }
+
+  let replacedTokenTx
+  if (replacedTx.tokens.length > 0) {
+    const [tokenAssetName] = replacedTx.tokens
+    const tokenTxSet = await assetClientInterface.getTxLog({
+      assetName: tokenAssetName,
+      walletAccount,
+    })
+    replacedTokenTx = tokenTxSet.get(bumpTxId)
+
+    if (replacedTokenTx) {
+      // Attempt to overwrite the asset to reflect the fact that
+      // we're performing a token transaction.
+      asset = assets[tokenAssetName]
+      if (!asset) {
+        throw new Error(
+          `unable to find ${tokenAssetName} during token bump transaction: asset was not available in assetsForNetwork`
+        )
+      }
+    }
+  }
+
+  const sourceTx = replacedTokenTx || replacedTx
+  const toAddress = sourceTx.to
+
+  // For self-sends `coinAmount` is `0` (correct for balance accounting, the
+  // wallet's net delta really is zero), so we can't reconstruct the on-chain
+  // value from it. Recover from `data.rawCoinAmount`, which the tx-log
+  // writers persist alongside `coinAmount` for exactly this purpose.
+  if (sourceTx.selfSend && !sourceTx.data?.rawCoinAmount) {
+    throw new Error(
+      `Cannot bump self-send transaction ${bumpTxId}: original transfer amount is unrecoverable from the tx log (data.rawCoinAmount missing). Re-broadcast the send with a higher fee instead.`
+    )
+  }
+
+  const amount = sourceTx.data?.rawCoinAmount
+    ? asset.currency.baseUnit(sourceTx.data.rawCoinAmount)
+    : sourceTx.coinAmount.negate()
+
+  const txValue = assertValidTxValue({
+    asset,
+    amount,
+    txValue: replacedTx.data?.rawCoinAmount
+      ? baseAsset.currency.baseUnit(replacedTx.data.rawCoinAmount)
+      : replacedTx.coinAmount.negate(),
+  })
+
+  const isDuplex = Boolean(replacedTokenTx && txValue.gt(baseAsset.currency.ZERO))
+
+  const txInput = replacedTx.data.data || '0x'
+
+  const isTokenTx =
+    !isDuplex /* nonpayable */ &&
+    replacedTokenTx &&
+    Object.keys(asset.contract.methodIds).includes(txInput.slice(0, 10))
+
+  const txToAddress = isTokenTx ? asset.contract.address : undefined
+
+  const replacedTxNonce = replacedTx.data.nonce
+
+  assert(
+    Number.isInteger(replacedTxNonce),
+    `Cannot bump transaction ${bumpTxId}: data object seems to be corrupted`
+  )
+
+  // If we have evaluated a bump transaction and the `providedNonce` differs
+  // from the `bumpNonce`, we've encountered a conflict and cannot respect
+  // the caller's request.
+  if (maybeProvidedNonce && maybeProvidedNonce !== replacedTxNonce) {
+    throw new Error('incorrect nonce for replacement transaction')
+  }
+
+  const nonce = maybeProvidedNonce ?? replacedTxNonce
+
+  await verifyBumpTxCanReplace({ baseAsset, bumpTxId, fromAddress, nonce })
+
+  const resolvedTxAttributes = await resolveTxAttributesByTxType({
+    asset,
+    assetClientInterface,
+    fromAddress,
+    amount,
+    nonce,
+    txInput,
+    toAddress,
+    txToAddress,
+    txType,
+    txValue,
+    walletAccount,
+  })
+
+  const gasLimit = replacedTx.data.gasLimit
+
+  const maybeTxToReplace = await getHighestIncentiveTxByNonce({
+    assetClientInterface,
+    asset,
+    nonce: resolvedTxAttributes.nonce,
+    walletAccount,
+  })
+
+  assert(
+    maybeTxToReplace,
+    `unable to resolve pending transaction for nonce ${resolvedTxAttributes.nonce}`
+  )
+
+  const {
+    eip1559Enabled,
+    resolvedGasPrice: gasPrice,
+    resolvedTipGasPrice: tipGasPrice,
+  } = await resolveTxFactoryGasPrices({
+    assetClientInterface,
+    baseAsset,
+    feeData,
+    nonce,
+    txToReplace: maybeTxToReplace,
+  })
+
+  return createUnsignedTxWithFees({
+    ...resolvedTxAttributes,
+    asset,
+    chainId,
+    gasLimit,
+    gasPrice,
+    tipGasPrice,
+    bumpTxId,
+    eip1559Enabled,
+  })
+}
+
+export const createTxFactory = ({ chainId, assetClientInterface, useAbsoluteNonce }) => {
+  assert(assetClientInterface, 'assetClientInterface is required')
+  assert(typeof chainId === 'number', 'chainId is required')
+  return async ({
+    asset,
+    walletAccount,
+    nft, // when sending nfts
+    fromAddress: providedFromAddress, // wallet from address
+    toAddress, // user's to address, not the token or the dex contract
+    address, // same as toAddress
+    txInput: providedTxInput, // Provided when swapping via a DEX contract
+    txType = TX_TYPE_TRANSFER, // Defines what kind of transaction is being performed.
+    txValue: providedTxValue, // Override the native ETH value (e.g. payable contract calls with txInput when specifying a token asset)
+    contractAddress: providedTxToAddress, // Controls the final target address of the transaction.
+    gasLimit: providedGasLimit, // Provided by exchange when known
+    amount: providedAmount, // The NU amount to be sent, to be included in the tx value or tx input
+    nonce: providedNonce,
+    tipGasPrice: providedTipGasPrice,
+    gasPrice: providedGasPrice,
+    bip70,
+    customFee: providedCustomFee,
+    // Intent flag: the user is trying to empty the wallet. Used for send-all-only
+    // dust behavior such as the EIP-1559 tip override.
+    isSendAll,
+    // Amount semantics flag: the provided amount includes the fee budget, so the
+    // final tx value should be reduced by the computed fee.
+    amountIncludesFee = false,
+    bumpTxId,
+  }) => {
+    assert(asset, 'asset is required')
+    assert(walletAccount, 'walletAccount is required')
+    assert(isValidTxType(txType), 'invalid txType')
+
+    const providedToAddress = toAddress ?? address
+
+    const baseAsset = asset.baseAsset
+    const feeData = await assetClientInterface.getFeeConfig({ assetName: baseAsset.name })
+
+    const baseAssetTxLog = await assetClientInterface.getTxLog({
+      assetName: baseAsset.name,
+      walletAccount,
+    })
+
+    const fromAddress = await resolveTxFromAddress({
+      asset,
+      assetClientInterface,
+      fromAddress: providedFromAddress,
+      walletAccount,
+    })
+
+    if (bumpTxId) {
+      assert(!providedTxValue && !providedTxToAddress)
+
+      return createBumpUnsignedTx({
+        chainId,
+        asset,
+        fromAddress,
+        bumpTxId,
+        baseAssetTxLog,
+        assetClientInterface,
+        walletAccount,
+        feeData,
+        nonce: providedNonce,
+        txType,
+      })
+    }
+
+    const nonce = await resolveTxNonce({
+      asset,
+      fromAddress,
+      nonce: providedNonce,
+      walletAccount,
+    })
+
+    const maybeTxToReplace = await getHighestIncentiveTxByNonce({
+      assetClientInterface,
+      asset: baseAsset,
+      nonce,
+      walletAccount,
+    })
+
+    const {
+      eip1559Enabled,
+      resolvedGasPrice: gasPrice,
+      resolvedTipGasPrice: tipGasPrice,
+    } = await resolveTxFactoryGasPrices({
+      assetClientInterface,
+      baseAsset,
+      customFee: providedCustomFee,
+      feeData,
+      gasPrice: providedGasPrice,
+      nonce,
+      tipGasPrice: providedTipGasPrice,
+      txToReplace: maybeTxToReplace,
+    })
+
+    if (nft) {
+      assert(!providedTxValue && !providedTxToAddress)
+
+      const {
+        contractAddress: txToAddress,
+        gasLimit,
+        txInput,
+      } = await getNftArguments({
+        asset,
+        nft,
+        fromAddress,
+        toAddress: providedToAddress,
+      })
+
+      const resolvedTxAttributes = await resolveTxAttributesByTxType({
+        asset: baseAsset,
+        assetClientInterface,
+        fromAddress,
+        nonce,
+        txInput,
+        toAddress: providedToAddress,
+        txToAddress,
+        txType,
+        walletAccount,
+      })
+
+      return createUnsignedTxWithFees({
+        ...resolvedTxAttributes,
+        chainId,
+        asset,
+        gasLimit,
+        gasPrice,
+        tipGasPrice,
+        eip1559Enabled,
+      })
+    }
+
+    const resolvedTxAttributes = await resolveTxAttributesByTxType({
+      asset,
+      assetClientInterface,
+      amount: providedAmount,
+      fromAddress,
+      nonce,
+      txInput: providedTxInput,
+      toAddress: providedToAddress,
+      txToAddress: providedTxToAddress,
+      txType,
+      txValue: providedTxValue,
+      walletAccount,
+    })
+
+    // TODO: `gasLimit` should become `txGasLimit` and returned
+    //       by `resolveTxAttributesByTxType`.
+    const gasLimit =
+      providedGasLimit ??
+      (await fetchGasLimit({
+        asset,
+        feeData,
+        fromAddress,
+        toAddress: resolvedTxAttributes.toAddress,
+        txInput: resolvedTxAttributes.txInput,
+        txValue: resolvedTxAttributes.txValue,
+        contractAddress: resolvedTxAttributes.txToAddress,
+        bip70,
+        amount: resolvedTxAttributes.amount,
+        txType,
+        isSendAll,
+      }))
+
+    // HACK: We cannot ensure the no dust invariant for `isSendAll`
+    //       transactions to contract addresses, since we may be
+    //       performing a raw token transaction and the parameter
+    //       applies to the token and not the native amount.
+    //
+    //       Contracts have nondeterministic gas most of the time
+    //       versus estimations, anyway.
+    const isSendAllBaseAsset =
+      isSendAll && !isEthereumLikeToken(asset) && !resolvedTxAttributes.isContractTxToAddress
+
+    const finalTipGasPrice = isSendAllBaseAsset && eip1559Enabled ? gasPrice : tipGasPrice
+
+    const { txAttributes: finalTxAttributes } = await resolveAmountIncludesFeeTxAttributes({
+      amountIncludesFee,
+      asset,
+      chainId,
+      eip1559Enabled,
+      gasLimit,
+      gasPrice,
+      tipGasPrice: finalTipGasPrice,
+      txAttributes: resolvedTxAttributes,
+    })
+
+    return createUnsignedTxWithFees({
+      ...finalTxAttributes,
+      asset,
+      chainId,
+      gasLimit,
+      gasPrice,
+      // For native send all transactions, we have to make sure that
+      // the `tipGasPrice` is equal to the `gasPrice`, since this is
+      // effectively like saying that the `maxFeePerGas` is equal
+      // to the `maxPriorityFeePerGas`. We do this so that for a
+      // fixed gas cost transaction, no dust balance should remain,
+      // since any deviation in the underlying `baseFeePerGas` will
+      // result only affect the tip for the miner - no dust remains.
+      tipGasPrice: finalTipGasPrice,
+      eip1559Enabled,
+    })
+  }
+}