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

package/src/tx-log/get-optimistic-txlog-effects.js

@@ -0,0 +1,379 @@
+import { SynchronizedTime } from '@exodus/basic-utils'
+import NumberUnit from '@exodus/currency'
+import {
+  getHighestIncentiveTxByNonce,
+  isEthereumLikeToken,
+  parseUnsignedTx,
+} from '@exodus/ethereum-lib'
+import { bufferToHex } from '@exodus/ethereumjs/util'
+import assert from 'minimalistic-assert'
+
+import { EthereumStaking } from '../staking/ethereum/api.js'
+import {
+  ethereumUnstakeOptimisticSideEffectTxLogs,
+  ethereumUnstakePendingOptimisticSideEffectTxLogs,
+  isEthereumStakingPoolContract,
+} from '../staking/ethereum/staking-utils.js'
+import { MaticStakingApi } from '../staking/matic/api.js'
+import {
+  DELEGATE,
+  maticDelegateOptimisticSideEffectTxLogs,
+} from '../staking/matic/matic-staking-utils.js'
+
+export const getOptimisticTxLogEffects = async ({
+  asset,
+  assetClientInterface,
+  bundleId,
+  confirmations = 0,
+  date = SynchronizedTime.now(),
+  fromAddress,
+  txId,
+  unsignedTx,
+  walletAccount,
+}) => {
+  assert(asset, 'expected asset')
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(Number.isInteger(confirmations), 'expected integer confirmations')
+  assert(typeof fromAddress === 'string', 'expected string fromAddress')
+  assert(txId, 'expected txId')
+  assert(unsignedTx, 'expected unsignedTx')
+  assert(walletAccount, 'expected walletAccount')
+
+  // this converts an transactionBuffer to values we can use when creating the tx logs
+  const parsedTx = parseUnsignedTx({ asset, unsignedTx })
+
+  const { nonce, to, txToAddress } = parsedTx
+  assert(Number.isInteger(nonce), 'expected integer nonce')
+
+  const amount = parsedTx.amount || asset.currency.ZERO
+  assert(amount instanceof NumberUnit, 'expected NumberUnit amount')
+
+  const feeAmount = parsedTx.fee
+  assert(feeAmount instanceof NumberUnit, 'expected feeAmount')
+
+  const txValue = parsedTx.value
+  assert(txValue instanceof NumberUnit, 'expected txValue')
+
+  const maybeTipGasPrice = parsedTx.tipGasPrice
+  if (maybeTipGasPrice) {
+    assert(maybeTipGasPrice instanceof NumberUnit, 'expected NumberUnit tipGasPrice')
+  }
+
+  const gasLimit = parsedTx.gasLimit
+  assert(Number.isInteger(gasLimit), 'expected integer gasLimit')
+
+  if (to) assert(typeof to === 'string', 'expected string toAddress')
+
+  const data = parsedTx.data
+  const methodId = data ? bufferToHex(data).slice(0, 10) : undefined
+
+  const selfSend = fromAddress.toLowerCase() === to?.toLowerCase()
+
+  const baseAsset = asset.baseAsset
+
+  const maybeTxToReplace = await getHighestIncentiveTxByNonce({
+    asset,
+    assetClientInterface,
+    nonce,
+    walletAccount,
+  })
+
+  const replacedTxId =
+    maybeTxToReplace && maybeTxToReplace.feeAmount.lt(feeAmount) ? maybeTxToReplace.txId : undefined
+
+  if (!replacedTxId && maybeTxToReplace) {
+    console.debug('Attempting to replace a transaction using an insufficient fee!')
+  }
+
+  // Contains effects for smart-contract initiated token movements.
+  const methodOptimisticSideEffects = await operationTxLogSideEffects({
+    txToAddress,
+    methodId,
+    asset,
+    walletAccount,
+    feeAmount,
+    txId,
+    nonce,
+    gasLimit,
+    tipGasPrice: maybeTipGasPrice,
+    data,
+    date,
+    bundleId,
+    fromAddress,
+  })
+
+  // Fallback to basic logic that only handles transfers + fee decoding
+  const sharedProps = {
+    confirmations,
+    date,
+    feeAmount,
+    feeCoinName: asset.feeAsset.name,
+    selfSend,
+    from: [],
+    to,
+    txId,
+    data: {
+      gasLimit,
+      replacedTxId,
+      nonce,
+      ...(maybeTipGasPrice ? { tipGasPrice: maybeTipGasPrice.toBaseString() } : null),
+      ...(methodId ? { methodId } : null),
+      ...(bundleId ? { bundleId } : null),
+      ...(data ? { data: bufferToHex(data) } : null),
+    },
+  }
+
+  const receiveWalletAccount = await findOtherPortfolioReceiveWalletAccount({
+    amount,
+    asset,
+    assetClientInterface,
+    methodId,
+    selfSend,
+    to,
+    txToAddress,
+    walletAccount,
+  })
+
+  const receiveSideEffects = receiveWalletAccount
+    ? getOtherPortfolioReceiveEffects({
+        amount,
+        asset,
+        confirmations,
+        date,
+        fromAddress,
+        gasLimit,
+        methodId,
+        maybeTipGasPrice,
+        nonce,
+        receiveWalletAccount,
+        txId,
+        data,
+      })
+    : []
+
+  const optimisticTxLogEffects = [
+    {
+      assetName: asset.name,
+      walletAccount,
+      txs: [
+        {
+          ...sharedProps,
+          data: { ...sharedProps.data, rawCoinAmount: amount.abs().toBaseString() },
+          coinAmount: selfSend ? asset.currency.ZERO : amount.abs().negate(),
+          coinName: asset.name,
+          currencies: {
+            [asset.name]: asset.currency,
+            [asset.feeAsset.name]: asset.feeAsset.currency,
+          },
+        },
+      ],
+    },
+    isEthereumLikeToken(asset) && {
+      assetName: baseAsset.name,
+      walletAccount,
+      txs: [
+        {
+          ...sharedProps,
+          data: { ...sharedProps.data, rawCoinAmount: txValue.abs().toBaseString() },
+          coinAmount: selfSend ? baseAsset.currency.ZERO : txValue.abs().negate(),
+          coinName: baseAsset.name,
+          currencies: {
+            [baseAsset.name]: baseAsset.currency,
+            [asset.feeAsset.name]: asset.feeAsset.currency,
+          },
+          tokens: [asset.name],
+        },
+      ],
+    },
+    ...methodOptimisticSideEffects,
+    ...receiveSideEffects,
+  ].filter(Boolean)
+
+  return { optimisticTxLogEffects, nonce }
+}
+
+const findOtherPortfolioReceiveWalletAccount = async ({
+  amount,
+  asset,
+  assetClientInterface,
+  methodId,
+  selfSend,
+  to,
+  txToAddress,
+  walletAccount,
+}) => {
+  // Exclude cases where another-portfolio receive logs would be misleading:
+  // history-backed assets, self-sends, incomplete/zero-value transfers, and
+  // token approvals/swaps/router calls that are not plain ERC-20 transfers.
+  if (!asset.baseAsset.api.features.noHistory || selfSend || !to || amount.isZero) return
+
+  if (isEthereumLikeToken(asset)) {
+    const isPlainTransfer =
+      txToAddress?.toLowerCase() === asset.contract.address.toLowerCase() &&
+      methodId === asset.contract.transfer.methodId
+    if (!isPlainTransfer) return
+  }
+
+  try {
+    return await getWalletAccountForReceiveAddress({
+      assetClientInterface,
+      baseAsset: asset.baseAsset,
+      sendingWalletAccount: walletAccount,
+      to,
+    })
+  } catch {}
+}
+
+const getOtherPortfolioReceiveEffects = ({
+  amount,
+  asset,
+  confirmations,
+  date,
+  fromAddress,
+  gasLimit,
+  methodId,
+  maybeTipGasPrice,
+  nonce,
+  receiveWalletAccount,
+  txId,
+  data,
+}) => {
+  const receiveProps = {
+    confirmations,
+    date,
+    selfSend: false,
+    from: [fromAddress],
+    txId,
+    data: {
+      gasLimit,
+      nonce,
+      ...(maybeTipGasPrice ? { tipGasPrice: maybeTipGasPrice.toBaseString() } : null),
+      ...(methodId ? { methodId } : null),
+      ...(data ? { data: bufferToHex(data) } : null),
+    },
+  }
+
+  return [
+    {
+      assetName: asset.name,
+      walletAccount: receiveWalletAccount,
+      txs: [
+        {
+          ...receiveProps,
+          coinAmount: amount.abs(),
+          coinName: asset.name,
+          currencies: {
+            [asset.name]: asset.currency,
+            [asset.feeAsset.name]: asset.feeAsset.currency,
+          },
+        },
+      ],
+    },
+  ]
+}
+
+const getWalletAccountForReceiveAddress = async ({
+  assetClientInterface,
+  baseAsset,
+  sendingWalletAccount,
+  to,
+}) => {
+  const normalizedTo = to.toLowerCase()
+  const walletAccounts = await assetClientInterface.getWalletAccounts({ assetName: baseAsset.name })
+
+  for (const walletAccount of walletAccounts) {
+    if (walletAccount === sendingWalletAccount) continue
+
+    const receiveAddresses = await assetClientInterface.getReceiveAddresses({
+      assetName: baseAsset.name,
+      walletAccount,
+      useCache: true,
+    })
+
+    if (receiveAddresses.some((address) => String(address).toLowerCase() === normalizedTo)) {
+      return walletAccount
+    }
+  }
+}
+
+const operationTxLogSideEffects = async ({
+  txToAddress,
+  methodId,
+  asset,
+  walletAccount,
+  feeAmount,
+  txId,
+  nonce,
+  gasLimit,
+  tipGasPrice,
+  data,
+  date,
+  bundleId,
+  fromAddress,
+}) => {
+  // Matic Delegate
+  if (
+    txToAddress?.toLowerCase() ===
+      MaticStakingApi.EVERSTAKE_VALIDATOR_CONTRACT_ADDR.toLowerCase() &&
+    methodId === DELEGATE
+  ) {
+    return maticDelegateOptimisticSideEffectTxLogs({
+      asset,
+      walletAccount,
+      feeAmount,
+      delegateTxId: txId,
+      nonce,
+      estimatedDelegateGasLimit: gasLimit,
+      tipGasPrice,
+      transactionData: data,
+      date,
+      bundleId,
+    })
+  }
+
+  // Ethereum Undelegate
+  if (
+    isEthereumStakingPoolContract(txToAddress) &&
+    methodId === EthereumStaking.METHODS_IDS.UNSTAKE_PENDING
+  ) {
+    return ethereumUnstakePendingOptimisticSideEffectTxLogs({
+      asset,
+      walletAccount,
+      feeAmount,
+      unstakePendingTxId: txId,
+      nonce,
+      estimatedUnstakePendingGasLimit: gasLimit,
+      tipGasPrice,
+      transactionData: data,
+      txToAddress,
+      date,
+      bundleId,
+    })
+  }
+
+  // Ethereum Undelegate (unstake from active validator)
+  if (
+    isEthereumStakingPoolContract(txToAddress) &&
+    methodId === EthereumStaking.METHODS_IDS.UNSTAKE
+  ) {
+    return ethereumUnstakeOptimisticSideEffectTxLogs({
+      asset,
+      walletAccount,
+      feeAmount,
+      unstakeTxId: txId,
+      nonce,
+      estimatedUnstakeGasLimit: gasLimit,
+      tipGasPrice,
+      transactionData: data,
+      txToAddress,
+      fromAddress,
+      date,
+      bundleId,
+    })
+  }
+
+  // Add other officially supported operations here
+  // Then can fallback to simulation results (TODO)
+  // Then finally to the default basic logic
+  return []
+}

package/src/tx-log/index.js

@@ -1,3 +1,5 @@
-export * from './ethereum-monitor'
-export * from './ethereum-no-history-monitor'
-export { ClarityMonitor } from './clarity-monitor'
+export { EthereumMonitor } from './ethereum-monitor.js'
+export { EthereumNoHistoryMonitor } from './ethereum-no-history-monitor.js'
+export { ClarityMonitor } from './clarity-monitor.js'
+export { ClarityTruncatedHistoryMonitor } from './clarity-truncated-history-monitor.js'
+export { getOptimisticTxLogEffects } from './get-optimistic-txlog-effects.js'

package/src/tx-log/monitor-utils/check-pending-transactions.js

@@ -1,16 +1,21 @@
-import getSenderNonceKey from './get-sender-nonce-key'
-import getFeeAmount from './get-fee-amount'
+import getFeeAmount from './get-fee-amount.js'
+import getSenderNonceKey from './get-sender-nonce-key.js'
 
 export default function checkPendingTransactions({
   pendingTransactionsGroupedByAddressAndNonce = {},
   pendingTransactionsToCheck = {},
+  recentPendingTransactions = {},
   txlist,
   ourWalletAddress,
   asset,
 }) {
   for (const tx of txlist) {
-    // eslint-disable-next-line @exodus/mutable/no-param-reassign-prop-only
-    delete pendingTransactionsToCheck[tx.txId || tx.hash] // Found this transaction, do not mark it as dropped
+    const txId = tx.txId || tx.hash
+    // Found this transaction on the server, do not mark it as dropped or re-add it
+    // eslint-disable-next-line @exodus/hydra/no-param-reassign-prop-only
+    delete pendingTransactionsToCheck[txId]
+    // eslint-disable-next-line @exodus/hydra/no-param-reassign-prop-only
+    delete recentPendingTransactions[txId]
 
     // check if this TX replaces another pending TX
     const replacedTx =
@@ -29,5 +34,9 @@ export default function checkPendingTransactions({
     }
   }
 
-  return { pendingTransactionsGroupedByAddressAndNonce, pendingTransactionsToCheck }
+  return {
+    pendingTransactionsGroupedByAddressAndNonce,
+    pendingTransactionsToCheck,
+    recentPendingTransactions,
+  }
 }

package/src/tx-log/monitor-utils/exclude-unchanged-token-balances.js

@@ -8,5 +8,5 @@ export function excludeUnchangedTokenBalances(currentTokenBalances, newTokenBala
     }
 
     return tokenBalancesAcc
-  }, {})
+  }, Object.create(null))
 }

package/src/tx-log/monitor-utils/extract-balance-from-clarity-account-info.js

@@ -0,0 +1,108 @@
+/**
+ * Maps Clarity `accountInfo` rows (GET .../transactions?truncated=true) into fields aligned
+ * with Ethereum-like account state: `balance`, `tokenBalances`, `nonce` (plus base units
+ * for amounts via `currency.baseUnit`).
+ * `account_balance` source rows are stored in `balance`/`tokenBalances`; truncated source rows
+ * are stored in `truncatedAccountState`.
+ *
+ * NOTE: All `row.value` payloads arrive over the wire as decimal strings (e.g. `"0"`,
+ * `"20191469428776270391810"`). They're parsed with `currency.baseUnit(...)` for amounts
+ * and `Number(...)` for nonce. `null`, `undefined`, and empty-string `""` all mean "row
+ * carries no value" and the row is skipped — `currency.baseUnit("")` throws and `Number("")`
+ * returns 0, both of which would silently corrupt accountState.
+ */
+const ACCOUNT_BALANCE = 'account_balance'
+const TRUNCATED = 'truncated'
+
+const hasValue = (value) => value !== null && value !== undefined && value !== ''
+
+const warnUnknownSource = (row) => {
+  console.warn('Unknown accountInfo source', row)
+}
+
+export const extractBalanceFromClarityAccountInfo = ({ accountInfo, asset, tokensByAddress }) => {
+  if (!accountInfo || accountInfo.length === 0) return {}
+
+  const sorted = [...accountInfo].sort((a, b) => (b.blockNumber || 0) - (a.blockNumber || 0))
+
+  const result = {}
+  const seenAssetIds = new Set()
+  const tokenBalances = Object.create(null)
+  const truncatedTokenBalances = Object.create(null)
+  let truncatedBalance
+
+  for (const row of sorted) {
+    switch (row.type) {
+      case 'balance':
+        if (hasValue(row.value)) {
+          const balance = asset.currency.baseUnit(row.value)
+          if (row.source === ACCOUNT_BALANCE) {
+            result.balance = balance
+          } else if (row.source === TRUNCATED) {
+            truncatedBalance = balance
+          } else {
+            warnUnknownSource(row)
+          }
+        }
+
+        break
+
+      case 'nonce': {
+        // Nonce collapses regardless of source — both `account_balance` and
+        // `truncated` rows represent the latest chain-known nonce; max wins
+        // for safety against out-of-order rows.
+        if (!hasValue(row.value)) break
+        const nonce = Number(row.value)
+        if (!Number.isFinite(nonce) || nonce < 0) break
+
+        result.nonce = Math.max(result.nonce ?? 0, nonce)
+
+        break
+      }
+
+      case 'token': {
+        const assetId = row.assetId?.toLowerCase()
+
+        if (!assetId || seenAssetIds.has(assetId) || !hasValue(row.value)) break
+        const token = tokensByAddress.get(assetId)
+        if (!token) break
+
+        const balance = token.currency.baseUnit(row.value)
+        if (row.source === ACCOUNT_BALANCE) {
+          tokenBalances[token.name] = balance
+        } else if (row.source === TRUNCATED) {
+          truncatedTokenBalances[token.name] = balance
+        } else {
+          warnUnknownSource(row)
+        }
+
+        seenAssetIds.add(assetId)
+        break
+      }
+
+      default:
+        break
+    }
+  }
+
+  if (Object.keys(tokenBalances).length > 0) {
+    result.tokenBalances = tokenBalances
+  }
+
+  const hasTruncatedTokenBalances = Object.keys(truncatedTokenBalances).length > 0
+  if (truncatedBalance || hasTruncatedTokenBalances) {
+    const truncatedAccountState = Object.create(null)
+
+    if (truncatedBalance) {
+      truncatedAccountState.balance = truncatedBalance
+    }
+
+    if (hasTruncatedTokenBalances) {
+      truncatedAccountState.tokenBalances = truncatedTokenBalances
+    }
+
+    result.truncatedAccountState = truncatedAccountState
+  }
+
+  return result
+}

package/src/tx-log/monitor-utils/get-balance-updates.js

@@ -0,0 +1,44 @@
+export const getWalletUpdates = (ourWalletAddress, walletChanges) => {
+  return walletChanges.reduce(
+    (acc, walletChange) => {
+      const { wallet: walletAddress, type, from, to, contract: contractAddress } = walletChange
+
+      if (walletAddress !== ourWalletAddress) {
+        return acc
+      }
+
+      switch (type) {
+        case 'balance':
+          acc.baseBalanceUpdate = {
+            from,
+            to,
+          }
+          break
+        case 'nonce':
+          acc.nonceUpdate = {
+            from,
+            to,
+          }
+          break
+        case 'token':
+          acc.tokenBalancesUpdate = {
+            ...acc.tokenBalancesUpdate,
+            [contractAddress]: {
+              from,
+              to,
+            },
+          }
+          break
+        default:
+          break
+      }
+
+      return acc
+    },
+    {
+      baseBalanceUpdate: undefined,
+      nonceUpdate: undefined,
+      tokenBalancesUpdate: Object.create(null),
+    }
+  )
+}

package/src/tx-log/monitor-utils/get-batched-rpc-balances.js

@@ -0,0 +1,47 @@
+import assert from 'minimalistic-assert'
+
+import { fromHexToString } from '../../number-utils.js'
+
+export const getBatchedRpcBalances = async ({
+  baseAsset,
+  tokens,
+  ourWalletAddress,
+  rpcBalanceAssetNames,
+}) => {
+  assert(baseAsset, 'expected baseAsset')
+  assert(Array.isArray(tokens), 'expected array tokens')
+  assert(ourWalletAddress, 'expected ourWalletAddress')
+
+  const batch = (assetName) =>
+    !Array.isArray(rpcBalanceAssetNames) || rpcBalanceAssetNames.includes(assetName)
+
+  const isBaseAssetBatched = batch(baseAsset.name)
+
+  const rpcRequestAccumulator = tokens
+    .filter(({ name, contract }) => batch(name) && contract?.address)
+    .reduce(
+      (acc, { contract: { address: tokenAddress } }) =>
+        acc.balanceOfRequest(ourWalletAddress, tokenAddress),
+      isBaseAssetBatched
+        ? baseAsset.createRpcRequestAccumulator().getBalanceRequest(ourWalletAddress)
+        : baseAsset.createRpcRequestAccumulator()
+    )
+
+  if (rpcRequestAccumulator.length() === 0) return Object.create(null)
+
+  const results = await rpcRequestAccumulator.flush(baseAsset.server)
+
+  return {
+    ...(isBaseAssetBatched && { [baseAsset.name]: fromHexToString(results[0]) }),
+    ...Object.fromEntries(
+      tokens
+        .filter(({ name, contract }) => batch(name) && contract?.address)
+        .map(({ name, contract: { address: tokenAddress } }, i) => {
+          const tokenBalance = results[i + (isBaseAssetBatched ? 1 : 0)]?.confirmed?.[tokenAddress]
+
+          assert(tokenBalance != null, `missing token balance for ${name} (${tokenAddress})`)
+          return [name, tokenBalance]
+        })
+    ),
+  }
+}

package/src/tx-log/monitor-utils/get-current-blacklist-status.js

@@ -0,0 +1,38 @@
+/**
+ * Checks the current blacklist status for an address and returns the state to use.
+ * Returns the new state if changed, undefined if unchanged.
+ * On error, resets to null (unknown) to avoid showing a stale blacklist warning —
+ * preferring a false negative over a false positive.
+ *
+ * @param {Object} params
+ * @param {Function} [params.getBlackListStatus] - Asset blacklist status checker
+ * @param {string} params.address - Wallet address to check
+ * @param {boolean|null} [params.currentIsBlacklisted] - Current blacklist flag from accountState
+ * @param {Object} [params.logger] - Optional logger for warnings
+ * @returns {Promise<boolean|null|undefined>} The new blacklist flag, or undefined if unchanged
+ */
+export async function getCurrentBlackListStatus({
+  getBlackListStatus,
+  address,
+  currentIsBlacklisted,
+  logger,
+}) {
+  if (typeof getBlackListStatus !== 'function') return
+
+  try {
+    const { isBlacklisted } = await getBlackListStatus({ address })
+
+    if (currentIsBlacklisted !== isBlacklisted) {
+      return isBlacklisted
+    }
+  } catch (error) {
+    if (logger) {
+      logger.warn('Failed to check blacklist status:', error)
+    }
+
+    // Reset to null (unknown) on error — only a confirmed check should show the blacklist warning.
+    return null
+  }
+}
+
+export default getCurrentBlackListStatus