@exodus/ethereum-api 8.64.6 → 8.64.7

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.64.7](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.64.5...@exodus/ethereum-api@8.64.7) (2026-02-24)
+
+
+### Bug Fixes
+
+
+* fix: harden EthlikeError and improve error handling in tx-send (#7308)
+
+
+
 ## [8.64.6](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.64.5...@exodus/ethereum-api@8.64.6) (2026-02-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "8.64.6",
+  "version": "8.64.7",
   "description": "Transaction monitors, fee monitors, RPC with the blockchain node, and other networking code for Ethereum and EVM-based blockchains",
   "type": "module",
   "main": "src/index.js",
@@ -35,9 +35,10 @@
     "@exodus/ethereumjs": "^1.8.0",
     "@exodus/fetch": "^1.3.0",
     "@exodus/models": "^12.13.0",
-    "@exodus/safe-string": "^1.2.1",
+    "@exodus/safe-string": "^1.4.0",
     "@exodus/simple-retry": "^0.0.6",
     "@exodus/solidity-contract": "^1.3.0",
+    "@exodus/traceparent": "^3.0.1",
     "@exodus/web3-ethereum-utils": "^4.6.0",
     "bn.js": "^5.2.1",
     "delay": "^4.0.1",
@@ -54,7 +55,7 @@
   "devDependencies": {
     "@exodus/assets-testing": "^1.0.0",
     "@exodus/bsc-meta": "^2.5.1",
-    "@exodus/errors": "^3.3.0",
+    "@exodus/errors": "^3.8.0",
     "@exodus/ethereumarbone-meta": "^2.1.2",
     "@exodus/fantommainnet-meta": "^2.0.5",
     "@exodus/matic-meta": "^2.2.7",
@@ -67,5 +68,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "05a14c42a3963199e2b0b11d0a643884ebae8e46"
+  "gitHead": "7d25477c075c7cef416ffe2c7e6e4c99e2928bdc"
 }

package/src/ens/index.js

@@ -64,4 +64,5 @@ const resolveEnsAddress = async (address, server) => {
   return resolver.decodeOutput({ data, method: 'name' })[0]
 }
 
+// This doesn't seem to be used anywhere.
 export { resolveEnsAddress, resolveEnsName }

package/src/error-wrapper.js

@@ -1,13 +1,277 @@
-export const reasons = {
-  fetchGasLimitFailed: 'Fetch gas limit failed',
-  nonceFetchFailed: 'Nonce fetch failed',
-  balanceFetchFailed: 'Balance fetch failed',
-  broadcastTxFailed: 'Broadcast tx failed',
-  getTransactionByHashFailed: 'Get transaction by hash failed',
-  ethCallErc20Failed: 'Eth call erc20 failed',
-  insufficientFunds: 'Insufficient funds',
-  bumpTxFailed: 'Bump tx failed',
-  transactionUnderpriced: 'Transaction underpriced',
+import { safeString } from '@exodus/safe-string'
+
+// Error types for categorizing EVM errors
+export const EVM_ERROR_TYPES = {
+  NODE_STATE_READ: safeString`NODE_STATE_READ`, // RPC-level read operations
+  CONTRACT_CALL: safeString`CONTRACT_CALL`, // Smart contract calls (eth_call, estimateGas)
+  BROADCAST: safeString`BROADCAST`, // Transaction broadcast errors (includes reverts)
+}
+
+// Operation-specific reasons
+export const EVM_ERROR_REASONS = {
+  // RPC-level read operations
+  balanceFetchFailed: {
+    reason: safeString`balance fetch failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+  nonceFetchFailed: {
+    reason: safeString`nonce fetch failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+  getTransactionByHashFailed: {
+    reason: safeString`get transaction by hash failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+  getCodeFailed: {
+    reason: safeString`get code failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+  getGasPriceFailed: {
+    reason: safeString`get gas price failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+  getBaseFeePerGasFailed: {
+    reason: safeString`get base fee per gas failed`,
+    type: EVM_ERROR_TYPES.NODE_STATE_READ,
+  },
+
+  // Generic smart contract call failure.
+  ethCallFailed: {
+    reason: safeString`eth call failed`,
+    type: EVM_ERROR_TYPES.CONTRACT_CALL,
+  },
+  ethCallErc20Failed: {
+    reason: safeString`eth call erc20 failed`,
+    type: EVM_ERROR_TYPES.CONTRACT_CALL,
+  },
+
+  // Gas Usage Simulation (checks contract reverts)
+  fetchGasLimitFailed: {
+    reason: safeString`fetch gas limit failed`,
+    type: EVM_ERROR_TYPES.CONTRACT_CALL,
+  },
+
+  // Write operations (checks sender account state/ability to transact)
+  // Generic failure, no info about a particular smart contract revert.
+  broadcastTxFailed: {
+    reason: safeString`broadcast tx failed`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+
+  // Reversion reasons
+  executionReverted: {
+    reason: safeString`execution reverted`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  invalidOpcode: {
+    reason: safeString`invalid opcode`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  insufficientFundsForGas: {
+    reason: safeString`insufficient funds for gas * price + value`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  alreadyKnown: {
+    reason: safeString`already known`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  nonceTooLow: {
+    reason: safeString`nonce too low`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  insufficientBalance: {
+    reason: safeString`execution reverted: insufficient balance / transfer exceeds balance`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  replacementTransactionUnderpriced: {
+    reason: safeString`replacement transaction underpriced`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  zeroTransfer: {
+    reason: safeString`execution reverted: transfer amount must be greater than zero`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  mathError: {
+    reason: safeString`execution reverted: arithmetic overflow/underflow`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+
+  transactionUnderpriced: {
+    reason: safeString`transaction underpriced`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  nonceTooHigh: {
+    reason: safeString`nonce too high`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  gasPriceBelowMin: {
+    reason: safeString`transaction gas price below minimum`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  insufficientGas: {
+    reason: safeString`insufficient gas`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  futureTransactionReplace: {
+    reason: safeString`future transaction tries to replace pending`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  eip155Required: {
+    reason: safeString`eip-155 replay protection required`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  invalidRlpSerialization: {
+    reason: safeString`invalid rlp serialization`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  transactionTypeNotSupported: {
+    reason: safeString`transaction type not supported`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  delegatedAccountError: {
+    reason: safeString`delegated account error`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+  invalidJumpDestination: {
+    reason: safeString`invalid jump destination`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
+}
+
+// Patterns to normalize (group similar errors together)
+const EVM_NORMALIZATION_PATTERNS = [
+  // Insufficient funds for gas (native currency, not tokens)
+  {
+    pattern: /(insufficient funds for gas \* price \+ value|insufficient funds(?!.*balance))/i,
+    errorInfo: EVM_ERROR_REASONS.insufficientFundsForGas,
+  },
+  // "nonce too low" or "nonce is too low" - tx nonce already used
+  {
+    pattern: /\bnonce\b.*\btoo low\b/i,
+    errorInfo: EVM_ERROR_REASONS.nonceTooLow,
+  },
+  // Comprehensive insufficient balance / transfer exceeds balance pattern (TOKEN balance issues)
+  // Catches: ERC20/BEP20, 0xe450d38c custom error, insufficient balance, balanceNotEnough,
+  // and token-specific "transfer amount exceeds balance" (BaseToken, SaveYourAssets, XVS, Ondo, FLOKI, etc.)
+  {
+    pattern:
+      /(0xe450d38c|insufficient.?balance|balance.?not.?enough|not enough fund|(erc20|bep20):.*transfer amount exceeds balance|\w+:.*transfer amount exceeds balance)/i,
+    errorInfo: EVM_ERROR_REASONS.insufficientBalance,
+  },
+  // Arithmetic overflow/underflow errors (SafeMath, Solidity 0.8+, etc.)
+  {
+    pattern: /(safemath:.*overflow|arithmetic underflow or overflow)/i,
+    errorInfo: EVM_ERROR_REASONS.mathError,
+  },
+  // Transfer amount must be greater than zero (various phrasings)
+  {
+    pattern:
+      /(transfer amount must be greater than zero|amount must be greater than 0|amt must be over than 0|zero_amount|transfer amount must be positive|transfer amount zero)/i,
+    errorInfo: EVM_ERROR_REASONS.zeroTransfer,
+  },
+  // Gas price below network minimum (not mempool competition, but protocol minimum)
+  // "gas price below minimum", "gas tip cap...minimum", "max fee per gas less than block base fee"
+  {
+    pattern:
+      /gas price below minimum|gas tip cap.*minimum|max fee per gas less than block base fee/i,
+    errorInfo: EVM_ERROR_REASONS.gasPriceBelowMin,
+  },
+  // Gas limit errors
+  // "intrinsic gas too low", "insufficient gas", "floor data gas cost" - gas limit below minimum required
+  {
+    pattern: /intrinsic gas too low|insufficient gas|floor data gas cost/i,
+    errorInfo: EVM_ERROR_REASONS.insufficientGas,
+  },
+  // "nonce too high" or "nonce is too high" - tx nonce too far ahead
+  {
+    pattern: /\bnonce\b.*\btoo high\b/i,
+    errorInfo: EVM_ERROR_REASONS.nonceTooHigh,
+  },
+  // Transaction type not supported
+  // "transaction type not supported", "tx type not supported" - chain doesn't support this tx type (e.g., EIP-1559)
+  {
+    pattern: /transaction type not supported|tx type not supported/i,
+    errorInfo: EVM_ERROR_REASONS.transactionTypeNotSupported,
+  },
+  // Invalid jump destination
+  {
+    pattern: /invalid jump destination/i,
+    errorInfo: EVM_ERROR_REASONS.invalidJumpDestination,
+  },
+  // Transaction already in mempool/chain
+  // "already known", "known transaction", "already imported", "already in mempool"
+  {
+    pattern: /already known|known transaction|already imported|already in mempool/i,
+    errorInfo: EVM_ERROR_REASONS.alreadyKnown,
+  },
+  // Replacement transaction underpriced (must come BEFORE "transaction underpriced")
+  {
+    pattern: /replacement transaction underpriced/i,
+    errorInfo: EVM_ERROR_REASONS.replacementTransactionUnderpriced,
+  },
+  // Transaction underpriced (checked after replacement to avoid double match)
+  {
+    pattern: /transaction underpriced/i,
+    errorInfo: EVM_ERROR_REASONS.transactionUnderpriced,
+  },
+  // Replay-protected transactions required (EIP-155 chain ID signing)
+  // "only replay-protected", "replay-protected transaction/tx required", "not replay protected", "invalid chain id"
+  {
+    pattern:
+      /only replay-protected|replay-protected (transaction|tx) required|not replay protected|invalid chain id/i,
+    errorInfo: EVM_ERROR_REASONS.eip155Required,
+  },
+  // Future transaction tries to replace pending (nonce conflict)
+  {
+    pattern: /future transaction.*replace.*pending/i,
+    errorInfo: EVM_ERROR_REASONS.futureTransactionReplace,
+  },
+  // Serialization/signature errors
+  // "rlp:", "invalid rlp", "decode rlp", "invalid sender", "invalid signature", "bad signature"
+  {
+    pattern: /rlp:|invalid rlp|decode rlp|invalid sender|invalid signature|bad signature/i,
+    errorInfo: EVM_ERROR_REASONS.invalidRlpSerialization,
+  },
+  // EIP-7702 delegation errors
+  // "delegated" (but not "delegatecall"), "eip-7702", "eip7702" - account delegation related errors
+  {
+    pattern: /\bdelegated\b(?!\s*call)|eip-?7702/i,
+    errorInfo: EVM_ERROR_REASONS.delegatedAccountError,
+  },
+  // GENERIC CATCH-ALL PATTERNS (must be last)
+  {
+    pattern: /^execution reverted$/i,
+    errorInfo: EVM_ERROR_REASONS.executionReverted,
+  },
+  {
+    pattern: /\binvalid opcode\b/i,
+    errorInfo: EVM_ERROR_REASONS.invalidOpcode,
+  },
+  {
+    pattern: /^execution reverted: 0x$/i,
+    errorInfo: EVM_ERROR_REASONS.executionReverted,
+  },
+  // Final catch-all for any remaining "execution reverted:" messages
+  {
+    pattern: /execution reverted:/i,
+    errorInfo: EVM_ERROR_REASONS.executionReverted,
+  },
+]
+
+// This should be renamed something better
+export function getEvmErrorReason(errorMessage) {
+  for (const { pattern, errorInfo } of EVM_NORMALIZATION_PATTERNS) {
+    if (pattern.test(errorMessage)) {
+      return {
+        reason: errorInfo.reason,
+        type: errorInfo.type,
+        wasNormalized: true,
+        patternUsed: pattern.toString(),
+      }
+    }
+  }
+
+  return null
 }
 
 const MAX_HINT_LENGTH = 100
@@ -19,15 +283,22 @@ export class EthLikeError extends Error {
    * Creates an instance of EthLikeError.
    *
    * @param {string} message - Standard error message.
-   * @param {string} reason - A constant indicating the generic failure. Must not contain any sensitive information such as private keys, transaction IDs, or wallet addresses.
+   * @param {Object} errorReasonInfo - Object containing reason and type for the error.
+   * @param {string} errorReasonInfo.reason - A constant indicating the generic failure. Must not contain any sensitive information such as private keys, transaction IDs, or wallet addresses.
+   * @param {string} errorReasonInfo.type - A category for the error (e.g., 'NODE_STATE_READ', 'CONTRACT_CALL', 'BROADCAST').
    * @param {string} hint - A hint to help the user understand the error. Must not contain any sensitive information such as private keys, transaction IDs, or wallet addresses.
+   * @param {TraceId} [traceId] - Optional TraceId object from HTTP response 'traceparent' header for debugging.
+   * @param {string} [baseAssetName] - Optional base asset name (e.g. 'ethereum', 'bnbsmartchain') for identifying the network.
    */
-  constructor({ message, reason, hint }) {
+  constructor({ message, errorReasonInfo, hint, traceId, baseAssetName }) {
     super(message)
-    this.name = 'EthLikeError'
+    this.name = safeString`EthLikeError`
     this.#hintStack = [hint] // NOTE: we can add more hints to the stack
-    this.reason = reason
+    this.reason = errorReasonInfo.reason
     this.hint = this.#extractHint(hint)
+    this.type = errorReasonInfo.type
+    this.traceId = traceId
+    this.baseAssetName = baseAssetName
   }
 
   addHint = (hint) => {
@@ -41,6 +312,15 @@ export class EthLikeError extends Error {
     return this
   }
 
+  getContext = () => {
+    return {
+      reason: this.reason,
+      type: this.type,
+      traceId: this.traceId,
+      baseAssetName: this.baseAssetName,
+    }
+  }
+
   // NOTE: a class method for now, if we move this to be a generic error for all assets, each asset will have its own implementation
   #extractHint = (hint) => {
     if (!hint) return ''
@@ -72,7 +352,7 @@ export class EthLikeError extends Error {
   }
 }
 
-export const withErrorReason = async (promise, errorReason, hint) => {
+export const withErrorReason = async ({ promise, errorReasonInfo, hint, baseAssetName }) => {
   try {
     return await promise
   } catch (err) {
@@ -84,8 +364,10 @@ export const withErrorReason = async (promise, errorReason, hint) => {
 
     throw new EthLikeError({
       message: err.message,
-      reason: errorReason,
+      errorReasonInfo,
       hint,
+      traceId: err.traceId,
+      baseAssetName,
     })
   }
 }

package/src/eth-like-util.js

@@ -1,9 +1,10 @@
 import { memoizeLruCache } from '@exodus/asset-lib'
 import { ABI, isEthereumLikeAsset, isEthereumLikeToken, normalizeTxId } from '@exodus/ethereum-lib'
+import { safeString } from '@exodus/safe-string'
 import SolidityContract from '@exodus/solidity-contract'
 import assert from 'minimalistic-assert'
 
-import * as ErrorWrapper from './error-wrapper.js'
+import { EthLikeError, EVM_ERROR_REASONS, withErrorReason } from './error-wrapper.js'
 import { getServer, getServerByName } from './exodus-eth-server/index.js'
 import { fromHexToString } from './number-utils.js'
 
@@ -18,7 +19,12 @@ export async function isContract(baseAssetName, address) {
 }
 
 export async function isContractAddress({ asset, address }) {
-  return getServer(asset).isContract(address)
+  return withErrorReason({
+    promise: getServer(asset).isContract(address),
+    errorReasonInfo: EVM_ERROR_REASONS.getCodeFailed,
+    hint: safeString`isContractAddress`,
+    baseAssetName: asset.baseAsset.name,
+  })
 }
 
 export const isContractAddressCached = memoizeLruCache(
@@ -29,7 +35,12 @@ export const isContractAddressCached = memoizeLruCache(
 
 export async function isForwarderContract({ asset, address }) {
   const server = getServer(asset)
-  const contractCode = await server.getCode(address)
+  const contractCode = await withErrorReason({
+    promise: server.getCode(address),
+    errorReasonInfo: EVM_ERROR_REASONS.getCodeFailed,
+    hint: safeString`isForwarderContract`,
+    baseAssetName: asset.baseAsset.name,
+  })
   return contractCode === FORWARDER_CONTRACT_CODE
 }
 
@@ -41,21 +52,23 @@ export const isForwarderContractCached = memoizeLruCache(
 
 export async function getNonce({ asset, address, tag = 'latest' }) {
   const server = getServer(asset)
-  const nonce = await ErrorWrapper.withErrorReason(
-    server.getTransactionCount(address, tag),
-    ErrorWrapper.reasons.nonceFetchFailed,
-    'getNonce'
-  )
+  const nonce = await withErrorReason({
+    promise: server.getTransactionCount(address, tag),
+    errorReasonInfo: EVM_ERROR_REASONS.nonceFetchFailed,
+    hint: safeString`getNonce`,
+    baseAssetName: asset.baseAsset.name,
+  })
 
   return parseInt(nonce, 16)
 }
 
 export async function estimateGas({ asset, ...args }) {
-  return ErrorWrapper.withErrorReason(
-    getServer(asset).estimateGas(args),
-    ErrorWrapper.reasons.fetchGasLimitFailed,
-    'estimateGas'
-  )
+  return withErrorReason({
+    promise: getServer(asset).estimateGas(args),
+    errorReasonInfo: EVM_ERROR_REASONS.fetchGasLimitFailed,
+    hint: safeString`estimateGas`,
+    baseAssetName: asset.baseAsset.name,
+  })
 }
 
 // Only base assets, not tokens
@@ -63,7 +76,12 @@ export async function getBalance({ asset, address }) {
   if (!isEthereumLikeAsset(asset)) throw new Error(`unsupported asset ${asset.name}`)
 
   const server = getServer(asset)
-  const balances = await server.getBalance(address)
+  const balances = await withErrorReason({
+    promise: server.getBalance(address),
+    errorReasonInfo: EVM_ERROR_REASONS.balanceFetchFailed,
+    hint: safeString`getBalance`,
+    baseAssetName: asset.baseAsset.name,
+  })
   return balances?.confirmed?.value || '0'
 }
 
@@ -71,16 +89,27 @@ export async function getBalance({ asset, address }) {
 export async function getBalanceProxied({ asset, address, tag = 'latest' }) {
   if (!isEthereumLikeAsset(asset)) throw new Error(`unsupported asset ${asset.name}`)
 
-  const result = await getServer(asset).getBalanceProxied(address)
+  const result = await withErrorReason({
+    promise: getServer(asset).getBalanceProxied(address),
+    errorReasonInfo: EVM_ERROR_REASONS.balanceFetchFailed,
+    hint: safeString`getBalanceProxied`,
+    baseAssetName: asset.baseAsset.name,
+  })
   return fromHexToString(result)
 }
 
 // Only ETH-like assets with token support
+// How would this return token balances? It does the same as getBalanceProxied... getting ETH balance
 export async function getTokenBalance({ asset, address }) {
   if (!isEthereumLikeToken(asset)) throw new Error(`unsupported ETH-like token ${asset.name}`)
 
   const server = getServer(asset)
-  const balances = await server.getBalance(address)
+  const balances = await withErrorReason({
+    promise: server.getBalance(address),
+    errorReasonInfo: EVM_ERROR_REASONS.balanceFetchFailed,
+    hint: safeString`getTokenBalance`,
+    baseAssetName: asset.baseAsset.name,
+  })
   const contractAddress = asset.contract.address.toLowerCase()
   return balances?.confirmed?.[contractAddress] || '0'
 }
@@ -90,7 +119,12 @@ export async function getTokenBalanceFromNode({ asset, address }) {
 
   const server = getServer(asset)
   const contractAddress = asset.contract.address.toLowerCase()
-  const balances = await server.balanceOf(address, contractAddress)
+  const balances = await withErrorReason({
+    promise: server.balanceOf(address, contractAddress),
+    errorReasonInfo: EVM_ERROR_REASONS.ethCallErc20Failed,
+    hint: safeString`getTokenBalanceFromNode`,
+    baseAssetName: asset.baseAsset.name,
+  })
   return balances?.confirmed?.[contractAddress] || '0'
 }
 
@@ -102,14 +136,24 @@ export function sendRawTransaction(asset) {
 export async function transactionExists({ asset, txId }) {
   const server = getServer(asset)
   txId = normalizeTxId(txId)
-  const txResult = await server.getTransactionByHash(txId)
+  const txResult = await withErrorReason({
+    promise: server.getTransactionByHash(txId),
+    errorReasonInfo: EVM_ERROR_REASONS.getTransactionByHashFailed,
+    hint: safeString`transactionExists`,
+    baseAssetName: asset.baseAsset.name,
+  })
   return Boolean(txResult && txResult.hash === txId)
 }
 
 export async function getTransaction({ asset, txId }) {
   const server = getServer(asset)
   txId = normalizeTxId(txId)
-  return server.getTransactionByHash(txId)
+  return withErrorReason({
+    promise: server.getTransactionByHash(txId),
+    errorReasonInfo: EVM_ERROR_REASONS.getTransactionByHashFailed,
+    hint: safeString`getTransaction`,
+    baseAssetName: asset.baseAsset.name,
+  })
 }
 
 export const getIsForwarderContract = memoizeLruCache(
@@ -140,18 +184,12 @@ export const getERC20Params = async ({ asset, address, paramNames = DEFAULT_PARA
       try {
         callResponse = await server.ethCall({ to: address, data: ERC20[method].methodId })
       } catch (err) {
-        if (err.message === 'execution reverted') {
-          throw new ErrorWrapper.EthLikeError({
-            message: `Can't find parameters for contract with address ${address}. Are you sure it is a valid ERC20 contract?`,
-            reason: ErrorWrapper.reasons.ethCallErc20Failed,
-            hint: 'ethCall:executionReverted',
-          })
-        }
-
-        throw new ErrorWrapper.EthLikeError({
+        throw new EthLikeError({
           message: err.message,
-          reason: ErrorWrapper.reasons.ethCallErc20Failed,
-          hint: 'ethCall',
+          errorReasonInfo: EVM_ERROR_REASONS.ethCallErc20Failed,
+          hint: safeString`getERC20Params`,
+          traceId: err.traceId,
+          baseAssetName: asset.baseAsset.name,
         })
       }
 
@@ -181,7 +219,12 @@ export const getERC20Params = async ({ asset, address, paramNames = DEFAULT_PARA
 }
 
 export async function getEIP7702Delegation({ address, server }) {
-  const code = await server.getCode(address)
+  const code = await withErrorReason({
+    promise: server.getCode(address),
+    errorReasonInfo: EVM_ERROR_REASONS.getCodeFailed,
+    hint: safeString`getEIP7702Delegation`,
+    baseAssetName: server.baseAssetName,
+  })
 
   // No code at all
   if (!code || code === '0x' || code === '0x0') {

package/src/exodus-eth-server/api-coin-nodes.js

@@ -11,8 +11,9 @@ import { getFallbackGasPriceEstimation } from './utils.js'
 const { isEmpty } = lodash
 
 export default class ApiCoinNodesServer extends EventEmitter {
-  constructor({ uri }) {
+  constructor({ baseAssetName, uri }) {
     super()
+    this.baseAssetName = baseAssetName
     this.uri = uri
     this.defaultUri = uri
     this.id = 0

package/src/exodus-eth-server/clarity-v2.js

@@ -1,4 +1,5 @@
 import { retry } from '@exodus/simple-retry'
+import { TraceId } from '@exodus/traceparent'
 import assert from 'minimalistic-assert'
 
 import ClarityServer, { RPC_REQUEST_TIMEOUT } from './clarity.js'
@@ -43,14 +44,31 @@ const fetchJson = async (url, fetchOptions) => {
   const response = await fetch(url, fetchOptions)
 
   if (!response.ok) {
-    throw new Error(
+    const traceId = TraceId.fromResponse(response)
+    const error = new Error(
       `${url} returned ${response.status}: ${
         response.statusText || 'Unknown Status Text'
       }. Body: ${await getTextFromResponse(response)}`
     )
+    if (traceId) {
+      error.traceId = traceId
+    }
+
+    throw error
+  }
+
+  const json = await response.json()
+
+  // Only capture trace ID if there's an RPC error in the response
+  // (handleJsonRPCResponse will extract it when throwing the error)
+  if (json.error) {
+    const traceId = TraceId.fromResponse(response)
+    if (traceId) {
+      json.__traceId = traceId
+    }
   }
 
-  return response.json()
+  return json
 }
 
 async function fetchJsonRetry(url, fetchOptions) {
@@ -126,9 +144,6 @@ export default class ClarityServerV2 extends ClarityServer {
       //       See: https://github.com/ExodusMovement/clarity/blob/d3c2a7f501a4391da630592bca3bf57c3ddd5e89/src/modules/ethereum-like/gas-price/index.js#L192C5-L219C6
       return await this.getGasPriceEstimation()
     } catch {
-      console.log(
-        `failed to query ${this.baseAssetName} gas-price-estimation endpoint, falling back to websocket`
-      )
       // HACK: The `getGasPriceEstimation` endpoint is not guaranteed
       //       to exist for all assets. In this case, we'll fallback
       //       to legacy behaviour, which is to query via the WebSocket.
@@ -185,8 +200,9 @@ export default class ClarityServerV2 extends ClarityServer {
     }
   }
 
-  fetchRpcHttpRequest = ({ baseApiPath, body }) =>
-    fetchHttpRequest({ baseApiPath, path: '/rpc', method: 'POST', body })
+  fetchRpcHttpRequest = ({ baseApiPath, body }) => {
+    return fetchHttpRequest({ baseApiPath, path: '/rpc', method: 'POST', body })
+  }
 
   async sendRpcRequest(rpcRequest) {
     try {
@@ -201,6 +217,8 @@ export default class ClarityServerV2 extends ClarityServer {
     }
   }
 
+  // Maybe some functions from clarity should be overriden to have handleJsonRPCResponse as well
+
   async sendRawTransaction(...params) {
     const { baseApiPath } = this
     const request = this.sendRawTransactionRequest(...params)

package/src/exodus-eth-server/clarity.js

@@ -1,6 +1,7 @@
 import { bufferToHex } from '@exodus/ethereumjs/util'
 import { safeString } from '@exodus/safe-string'
 import SolidityContract from '@exodus/solidity-contract'
+import { TraceId } from '@exodus/traceparent'
 import EventEmitter from 'events/events.js'
 import io from 'socket.io-client'
 
@@ -104,12 +105,20 @@ export default class ClarityServer extends EventEmitter {
 
       const revisedError = new Error(`Bad rpc response: ${message}`)
       revisedError.hint = safeString`Bad rpc response: ${errorMessageToSafeHint(message)}`
+
+      // Preserve trace ID: from HTTP (__traceId) or WebSocket (traceparent in JSON body)
+      const traceId = response?.__traceId || response?.traceparent
+      if (traceId) {
+        revisedError.traceId = traceId
+      }
+
       throw revisedError
     }
 
     return result
   }
 
+  // Transport: WS only in ClarityServer, HTTP only in ClarityServerV2 (overridden)
   async getAllTransactions(params) {
     const transactions = { pending: [], confirmed: [] }
     const cursor = await this.getTransactions({
@@ -129,6 +138,7 @@ export default class ClarityServer extends EventEmitter {
     return { cursor, transactions }
   }
 
+  // Transport: WS only (uses transactions socket, not RPC socket)
   async getTransactions({ walletAccount, address, cursor, onChunk }) {
     const socket = this.connectTransactions({ walletAccount, address })
     const listener = (isPending, chunk, callback) => {
@@ -149,6 +159,7 @@ export default class ClarityServer extends EventEmitter {
       .finally(() => socket.off('transactionsChunk', listener))
   }
 
+  // Transport: WS only (uses fee socket)
   getFeeFromWebSocket() {
     const socket = this.connectFee()
     return new Promise((resolve, reject) => {
@@ -165,10 +176,12 @@ export default class ClarityServer extends EventEmitter {
     })
   }
 
+  // Transport: WS only in ClarityServer, HTTP first → WS fallback in ClarityServerV2 (overridden)
   async getFee() {
     return this.getFeeFromWebSocket()
   }
 
+  // Transport: Depends on getFee() - WS only in ClarityServer, HTTP first → WS fallback in ClarityServerV2
   // for fee monitors
   async getGasPrice() {
     const fee = await this.getFee()
@@ -185,11 +198,18 @@ export default class ClarityServer extends EventEmitter {
       const timeout = setTimeout(() => reject(new Error(RPC_REQUEST_TIMEOUT)), 3000)
       rpcSocket.emit('request', rpcRequest, (response) => {
         clearTimeout(timeout)
+        const rawTraceparent = response?.traceparent || response?.[0]?.traceparent
+        if (rawTraceparent) {
+          // eslint-disable-next-line @exodus/mutable/no-param-reassign-prop-only
+          response.traceparent = TraceId.fromRawTraceparent(rawTraceparent)
+        }
+
         resolve(response)
       })
     })
   }
 
+  // Transport: WS only in ClarityServer, WS first → HTTP fallback in ClarityServerV2
   async sendBatchRequest(batch) {
     const responses = await this.sendRpcRequest(batch)
     // FIXME: this falls apart if responses is not an array
@@ -206,12 +226,14 @@ export default class ClarityServer extends EventEmitter {
     return batch.map((request) => keyed[`${request.id}`])
   }
 
+  // Transport: Uses sendRpcRequest - WS only in ClarityServer, WS first → HTTP fallback in ClarityServerV2
   async sendRequest(request) {
     const response = await this.sendRpcRequest(request)
 
     return this.handleJsonRPCResponse(response)
   }
 
+  // Transport: Via getCode → sendRequest → WS first → HTTP fallback in ClarityServerV2
   async isContract(address) {
     const code = await this.getCode(address)
     return code.length > 2
@@ -327,11 +349,13 @@ export default class ClarityServer extends EventEmitter {
     })
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async proxyToCoinNode(params) {
     const request = this.buildRequest(params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async balanceOf(address, tokenAddress, tag = 'latest') {
     const request = this.balanceOfRequest(address, tokenAddress, tag)
     const result = await this.sendRequest(request)
@@ -343,69 +367,83 @@ export default class ClarityServer extends EventEmitter {
     }
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBalance(...params) {
-    const request = this.getBalanceRequest(...params)
+    const request = this.getBalanceRequest(...params) // eth_getBalance
     return this.sendRequest(request)
   }
 
+  // Transport: Via getBalance → sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBalanceProxied(...params) {
-    return this.getBalance(...params)
+    return this.getBalance(...params) // eth_getBalance
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async gasPrice(...params) {
     const request = this.gasPriceRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: WS only in ClarityServer, HTTP only in ClarityServerV2 (overridden)
   async estimateGas(...params) {
     const request = this.estimateGasRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: WS only in ClarityServer, HTTP only in ClarityServerV2 (overridden)
   async sendRawTransaction(...params) {
     const request = this.sendRawTransactionRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getCode(...params) {
     const request = this.getCodeRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getStorageAt(...params) {
     const request = this.getStorageAtRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: WS only in ClarityServer, HTTP only in ClarityServerV2 (overridden)
   async getTransactionCount(...params) {
     const request = this.getTransactionCountRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getTransactionByHash(...params) {
     const request = this.getTransactionByHashRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getTransactionReceipt(...params) {
     const request = this.getTransactionReceiptRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async ethCall(...params) {
     const request = this.ethCallRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async blockNumber(...params) {
     const request = this.blockNumberRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via getBlockByNumber → sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getLatestBlock() {
     return this.getBlockByNumber('latest')
   }
 
+  // Transport: Via getLatestBlock → getBlockByNumber → sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBaseFeePerGas() {
     const response = await this.getLatestBlock()
     if (response.baseFeePerGas) {
@@ -413,46 +451,55 @@ export default class ClarityServer extends EventEmitter {
     }
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBlockByHash(...params) {
     const request = this.getBlockByHashRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBlockTransactionCountByNumber(...params) {
     const request = this.getBlockTransactionCountByNumberRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getBlockByNumber(...params) {
     const request = this.getBlockByNumberRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async simulateV1(...params) {
     const request = this.simulateV1Request(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async simulateRawTransaction(...params) {
     const request = this.simulateRawTransactionRequest(...params)
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getCoinbase() {
     const request = this.coinbaseRequest()
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getCompilers() {
     const request = this.getCompilersRequest()
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getNetVersion() {
     const request = this.getNetVersion()
     return this.sendRequest(request)
   }
 
+  // Transport: Via sendRequest → WS first → HTTP fallback in ClarityServerV2
   async getLogs(...params) {
     const request = this.getLogsRequest(...params)
     return this.sendRequest(request)

package/src/exodus-eth-server/index.js

@@ -22,7 +22,7 @@ export function createEvmServer({ assetName, serverUrl, monitorType }) {
   assert(monitorType, 'monitorType is required')
   switch (monitorType) {
     case 'no-history':
-      return new ApiCoinNodesServer({ uri: serverUrl })
+      return new ApiCoinNodesServer({ baseAssetName: assetName, uri: serverUrl })
     case 'clarity':
       return new ClarityServer({ baseAssetName: assetName, uri: serverUrl })
     case 'clarity-v2':

package/src/index.js

@@ -88,7 +88,13 @@ export {
   fromHexToBN,
 } from './number-utils.js'
 
-export { reasons as errorReasons, withErrorReason, EthLikeError } from './error-wrapper.js'
+export {
+  EVM_ERROR_REASONS,
+  EVM_ERROR_TYPES,
+  getEvmErrorReason,
+  withErrorReason,
+  EthLikeError,
+} from './error-wrapper.js'
 
 export { txSendFactory } from './tx-send/index.js'
 

package/src/nft-utils.js

@@ -1,7 +1,8 @@
+import { safeString } from '@exodus/safe-string'
 import SolidityContract from '@exodus/solidity-contract'
 import assert from 'minimalistic-assert'
 
-import * as ErrorWrapper from './error-wrapper.js'
+import { EthLikeError, EVM_ERROR_REASONS } from './error-wrapper.js'
 import { fetchGasLimit } from './gas-estimation.js'
 
 export const getNftArguments = async ({ asset, nft, fromAddress, toAddress }) => {
@@ -44,10 +45,11 @@ export const getNftArguments = async ({ asset, nft, fromAddress, toAddress }) =>
       }
     })
   ).catch((e) => {
-    throw new ErrorWrapper.EthLikeError({
+    throw new EthLikeError({
       message: errors.join('\n'),
-      reason: ErrorWrapper.reasons.fetchGasLimitFailed,
-      hint: 'getNftArguments',
+      errorReasonInfo: EVM_ERROR_REASONS.fetchGasLimitFailed,
+      hint: safeString`getNftArguments`,
+      traceId: e.traceId,
     })
   })
   return {

package/src/optimism-gas/index.js

@@ -1,7 +1,9 @@
 import { createContract, createEthereumJsTx } from '@exodus/ethereum-lib'
 import { bufferToHex } from '@exodus/ethereumjs/util'
+import { safeString } from '@exodus/safe-string'
 import assert from 'minimalistic-assert'
 
+import { EVM_ERROR_REASONS, withErrorReason } from '../error-wrapper.js'
 import { fromHexToBigInt } from '../number-utils.js'
 
 export const estimateL1DataFeeFactory = ({ l1GasOracleAddress, server }) => {
@@ -14,7 +16,12 @@ export const estimateL1DataFeeFactory = ({ l1GasOracleAddress, server }) => {
     const callData = gasContract.getL1Fee.build(serialized)
     const buffer = Buffer.from(callData)
     const data = bufferToHex(buffer)
-    const hex = await server.ethCall({ to: l1GasOracleAddress, data }, 'latest')
+    const hex = await withErrorReason({
+      promise: server.ethCall({ to: l1GasOracleAddress, data }, 'latest'),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallFailed,
+      hint: safeString`estimateL1DataFee`,
+      baseAssetName: server.baseAssetName,
+    })
     const l1DataFee = fromHexToBigInt(hex)
     const padFee = l1DataFee / BigInt(4)
     const maxL1DataFee = l1DataFee + padFee

package/src/staking/ethereum/api.js

@@ -1,7 +1,9 @@
 import { createContract } from '@exodus/ethereum-lib'
 import { bufferToHex } from '@exodus/ethereumjs/util'
+import { safeString } from '@exodus/safe-string'
 import { retry } from '@exodus/simple-retry'
 
+import { EVM_ERROR_REASONS, withErrorReason } from '../../error-wrapper.js'
 import { getServerByName } from '../../exodus-eth-server/index.js'
 
 // TODO: Shouldn't this be a function of `ethereumStakingState.minDelegateAmount`?
@@ -78,7 +80,12 @@ export class EthereumStaking {
     if (typeof from === 'string' && from.length > 0) data.from = from
 
     const eth = this.server || getServerByName(this.asset.name)
-    return retry((...args) => eth.ethCall(...args), { delayTimesMs: RETRY_DELAYS })(data)
+    return withErrorReason({
+      promise: retry((...args) => eth.ethCall(...args), { delayTimesMs: RETRY_DELAYS })(data),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallFailed,
+      hint: safeString`stakingEthReadFunctionContract`,
+      baseAssetName: eth.baseAssetName,
+    })
   }
 
   // === ACCOUNTING ===

package/src/staking/matic/api.js

@@ -1,9 +1,11 @@
 import { createContract } from '@exodus/ethereum-lib'
 import ethAssets from '@exodus/ethereum-meta'
 import { bufferToHex } from '@exodus/ethereumjs/util'
+import { safeString } from '@exodus/safe-string'
 import { retry } from '@exodus/simple-retry'
 import BN from 'bn.js'
 
+import { EVM_ERROR_REASONS, withErrorReason } from '../../error-wrapper.js'
 import { getServerByName } from '../../exodus-eth-server/index.js'
 import { fromHexToBN, fromHexToString, splitIn32BytesArray } from '../../number-utils.js'
 
@@ -43,7 +45,12 @@ export class MaticStakingApi {
     }
 
     const eth = this.server || getServerByName('ethereum')
-    return retry((...args) => eth.ethCall(...args), { delayTimesMs: RETRY_DELAYS })(data)
+    return withErrorReason({
+      promise: retry((...args) => eth.ethCall(...args), { delayTimesMs: RETRY_DELAYS })(data),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallFailed,
+      hint: safeString`stakingMaticReadFunctionContract`,
+      baseAssetName: eth.baseAssetName,
+    })
   }
 
   getWithdrawalDelay = async () => {

package/src/tx-send/broadcast-error-handler.js

@@ -0,0 +1,58 @@
+import { EthLikeError, EVM_ERROR_REASONS, getEvmErrorReason } from '../error-wrapper.js'
+import { transactionExists } from '../eth-like-util.js'
+
+/**
+ * Handles broadcast errors by parsing the error message and either throwing
+ * an appropriate EthLikeError or returning info for retry logic.
+ *
+ * @param {Error} err - The error from broadcastTx.
+ * @param {Object} options - Context for error handling.
+ * @param {Object} options.asset - The asset.
+ * @param {string} options.txId - The transaction ID.
+ * @param {boolean} options.isHardware - Whether this is a hardware wallet.
+ * @param {string} options.hint - Hint for the error.
+ * @returns {Promise<{ shouldRetry: boolean }>} - Returns if nonce too low and can retry.
+ * @throws {EthLikeError} - Throws for all other error cases.
+ */
+export const handleBroadcastError = async (err, { asset, txId, isHardware, hint, isBumpTx }) => {
+  const message = err.message
+
+  const errorInfo = getEvmErrorReason(message) || EVM_ERROR_REASONS.broadcastTxFailed
+
+  const isNonceTooLow = errorInfo.reason === EVM_ERROR_REASONS.nonceTooLow.reason
+  const isAmbiguousError =
+    isNonceTooLow || errorInfo.reason === EVM_ERROR_REASONS.transactionUnderpriced.reason
+
+  if (errorInfo.reason === EVM_ERROR_REASONS.alreadyKnown.reason) {
+    console.info('tx already broadcast')
+    return { shouldRetry: false }
+  }
+
+  let txAlreadyExists = false
+  if (isAmbiguousError) {
+    try {
+      txAlreadyExists = await transactionExists({ asset, txId })
+    } catch (verifyErr) {
+      // Can't verify - fall through to original error handling
+      console.warn('Could not verify tx existence:', verifyErr.message)
+    }
+  }
+
+  if (txAlreadyExists) {
+    console.info('tx already broadcast')
+    return { shouldRetry: false }
+  }
+
+  // NOTE: Don't auto-retry nonce repair for bump/replacement txs.
+  // A replacement must keep the *same nonce* as the tx it's replacing.
+  // If we "fix" a bump tx by advancing the nonce, we create a brand-new tx instead of replacing the pending one.
+  if (isNonceTooLow && !isHardware && !isBumpTx) return { shouldRetry: true }
+
+  throw new EthLikeError({
+    message: err.message,
+    errorReasonInfo: errorInfo,
+    hint,
+    traceId: err.traceId,
+    baseAssetName: asset.baseAsset.name,
+  })
+}

package/src/tx-send/tx-send.js

@@ -1,10 +1,10 @@
 import { normalizeTxId, parseUnsignedTx, updateNonce } from '@exodus/ethereum-lib'
+import { safeString } from '@exodus/safe-string'
 import assert from 'minimalistic-assert'
 
-import * as ErrorWrapper from '../error-wrapper.js'
-import { transactionExists } from '../eth-like-util.js'
 import { getOptimisticTxLogEffects } from '../tx-log/index.js'
 import { ARBITRARY_ADDRESS } from '../tx-type/index.js'
+import { handleBroadcastError } from './broadcast-error-handler.js'
 
 const txSendFactory = ({ assetClientInterface, createTx }) => {
   assert(assetClientInterface, 'assetClientInterface is required')
@@ -38,6 +38,7 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
       `The receiving wallet address must not be ${ARBITRARY_ADDRESS}`
     )
 
+    // Are there any signin-level errors that should be caught here?
     let { txId, rawTx } = await signTx({
       asset,
       unsignedTx,
@@ -47,41 +48,16 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
     try {
       await baseAsset.api.broadcastTx(rawTx.toString('hex'))
     } catch (err) {
-      const transactionUnderpricedErr = err.message.match(/transaction underpriced/i)
-      const nonceTooLowErr = err.message.match(/nonce (is |)too low/i)
-      const insufficientFundsErr = err.message.match(/insufficient funds/i)
-
-      // NOTE: We've found that `geth` can return the following errors
-      //       for transactions which may be already known. In this
-      //       case, we validate that the transaction is known to the
-      //       network.
-      const txAlreadyExists =
-        nonceTooLowErr || transactionUnderpricedErr
-          ? await transactionExists({ asset, txId })
-          : err.message.match(/already known/i) ||
-            err.message.match(/transaction already imported/i)
-
-      if (txAlreadyExists) {
-        console.info('tx already broadcast') // inject logger factory from platform
-      } else if (insufficientFundsErr) {
-        throw new ErrorWrapper.EthLikeError({
-          message: err.message,
-          reason: ErrorWrapper.reasons.insufficientFunds,
-          hint: 'broadcastTx',
-        })
-      } else if (unsignedTx.txMeta.bumpTxId) {
-        throw new ErrorWrapper.EthLikeError({
-          message: err.message,
-          reason: ErrorWrapper.reasons.bumpTxFailed,
-          hint: 'broadcastTx',
-        })
-      } else if (!nonceTooLowErr) {
-        throw new ErrorWrapper.EthLikeError({
-          message: err.message,
-          reason: ErrorWrapper.reasons.broadcastTxFailed,
-          hint: 'otherErr:broadcastTx',
-        })
-      } else if (nonceTooLowErr && !unsignedTx.txMeta.isHardware) {
+      const isBumpTx = !!unsignedTx.txMeta.bumpTxId
+      const { shouldRetry } = await handleBroadcastError(err, {
+        asset,
+        txId,
+        isHardware: !!unsignedTx.txMeta.isHardware,
+        hint: isBumpTx ? safeString`bumpTx` : safeString`broadcastTx`,
+        isBumpTx,
+      })
+
+      if (shouldRetry) {
         console.info('trying to send again...') // inject logger factory from platform
 
         // let's try to fix the nonce issue
@@ -92,10 +68,9 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
           forceFromNode: true,
         })
 
-        // TODO: We should only do this for non-replacement transactions.
         const triedNonce = parsedTx.nonce
-
-        if (typeof triedNonce === 'number') {
+        // Defensive: avoid retrying the same nonce if node nonce is stale (non-replacement sends only).
+        if (!isBumpTx && typeof triedNonce === 'number') {
           newNonce = Math.max(newNonce, triedNonce + 1)
         }
 
@@ -121,29 +96,15 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
 
         try {
           await baseAsset.api.broadcastTx(rawTx.toString('hex'))
-        } catch (err) {
-          const insufficientFundsErr = err.message.match(/insufficient funds/i)
-          if (insufficientFundsErr) {
-            throw new ErrorWrapper.EthLikeError({
-              message: err.message,
-              reason: ErrorWrapper.reasons.insufficientFunds,
-              hint: 'retry:broadcastTx',
-            })
-          }
-
-          throw new ErrorWrapper.EthLikeError({
-            message: err.message,
-            reason: ErrorWrapper.reasons.broadcastTxFailed,
-            hint: 'retry:broadcastTx',
+        } catch (retryErr) {
+          await handleBroadcastError(retryErr, {
+            asset,
+            txId,
+            isHardware: false,
+            hint: safeString`retry:broadcastTx`,
+            isBumpTx: false, // retry path is only for non-bump anyway
           })
         }
-      } else {
-        // If none of the above apply, terminate with a general error.
-        throw new ErrorWrapper.EthLikeError({
-          message: err.message,
-          reason: ErrorWrapper.reasons.broadcastTxFailed,
-          hint: 'broadcastTx',
-        })
       }
     }