@exodus/ethereum-api 10.3.4 → 10.4.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.4.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@10.3.4...@exodus/ethereum-api@10.4.0) (2026-11-14)
+
+
+### Features
+
+* **ethereum-api:** add EXOD send error codes and user hints ([#9205](https://github.com/ExodusMovement/assets/issues/9205)) ([ebdbd9e](https://github.com/ExodusMovement/assets/commit/ebdbd9e778107182c3e0b7d0fd12866f30d384e2))
+
+
+
 ## [10.3.4](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@10.3.3...@exodus/ethereum-api@10.3.4) (2026-11-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "10.3.4",
+  "version": "10.4.0",
   "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",
@@ -65,5 +65,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "1fd2892211fff5bd625be197de9533daa746cd67"
+  "gitHead": "e646d8655bc613c1f188e7d7187498d82700ae90"
 }

package/src/error-wrapper.js

@@ -58,6 +58,10 @@ export const EVM_ERROR_REASONS = {
     reason: safeString`broadcast tx failed`,
     type: EVM_ERROR_TYPES.BROADCAST,
   },
+  broadcastNodeUnavailable: {
+    reason: safeString`broadcast node unavailable`,
+    type: EVM_ERROR_TYPES.BROADCAST,
+  },
 
   // Reversion reasons
   executionReverted: {
@@ -303,9 +307,10 @@ export class EthLikeError extends Error {
    * @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.
+   * @param {Error} [cause] - Optional original error, kept so its name and code stay readable.
    */
-  constructor({ message, errorReasonInfo, hint, traceId, baseAssetName }) {
-    super(message)
+  constructor({ message, errorReasonInfo, hint, traceId, baseAssetName, cause }) {
+    super(message, cause === undefined ? undefined : { cause })
     this.name = safeString`EthLikeError`
     const filteredHint = this.#extractHint(hint)
     // Only filtered hints are kept on the stack so that subsequent joins via
@@ -335,6 +340,7 @@ export class EthLikeError extends Error {
       type: this.type,
       traceId: this.traceId,
       baseAssetName: this.baseAssetName,
+      sourceHint: this.sourceHint,
     }
   }
 
@@ -386,6 +392,7 @@ export const withErrorReason = async ({ promise, errorReasonInfo, hint, baseAsse
       hint,
       traceId: err.traceId,
       baseAssetName,
+      cause: err,
     })
   }
 }

package/src/errors.js

@@ -0,0 +1,250 @@
+import { safeString } from '@exodus/safe-string'
+
+import { EVM_ERROR_REASONS, EVM_ERROR_TYPES, getEvmErrorReason } from './error-wrapper.js'
+
+const freezeTable = (table) => {
+  for (const entry of Object.values(table)) {
+    for (const value of Object.values(entry)) {
+      if (Array.isArray(value)) Object.freeze(value)
+    }
+
+    Object.freeze(entry)
+  }
+
+  return Object.freeze(table)
+}
+
+export const EVM_ERRORS = freezeTable({
+  INSUFFICIENT_FUNDS_FOR_FEE: {
+    code: 'EXOD-3000',
+    hint: safeString`Not enough funds to pay the network fee`,
+    action: 'add-funds',
+    reasons: [EVM_ERROR_REASONS.insufficientFundsForGas.reason],
+  },
+  INSUFFICIENT_BALANCE: {
+    code: 'EXOD-3001',
+    hint: safeString`Not enough balance to send this amount`,
+    action: 'add-funds',
+    reasons: [EVM_ERROR_REASONS.insufficientBalance.reason],
+  },
+  FEE_EXCEEDS_AMOUNT: {
+    code: 'EXOD-3002',
+    hint: safeString`The network fee is higher than the amount to send`,
+    action: 'edit-transaction',
+    names: ['AmountIncludesFeeUnderflowError'],
+  },
+  FEE_TOO_LOW: {
+    code: 'EXOD-3003',
+    hint: safeString`The network fee is too low, try again with a higher fee`,
+    action: 'edit-transaction',
+    reasons: [
+      EVM_ERROR_REASONS.gasPriceBelowMin.reason,
+      EVM_ERROR_REASONS.transactionUnderpriced.reason,
+    ],
+  },
+  REPLACEMENT_FEE_TOO_LOW: {
+    code: 'EXOD-3004',
+    hint: safeString`The fee is too low to replace the pending transaction`,
+    action: 'edit-transaction',
+    reasons: [EVM_ERROR_REASONS.replacementTransactionUnderpriced.reason],
+  },
+  GAS_LIMIT_TOO_LOW: {
+    code: 'EXOD-3005',
+    hint: safeString`The gas limit is too low for this transaction`,
+    action: 'edit-transaction',
+    reasons: [EVM_ERROR_REASONS.insufficientGas.reason],
+  },
+
+  INVALID_RECIPIENT: {
+    code: 'EXOD-3020',
+    hint: safeString`This recipient address is not allowed`,
+    action: 'edit-transaction',
+    patterns: [/^The receiving wallet address must not be\b/],
+  },
+
+  NONCE_TOO_LOW: {
+    code: 'EXOD-3040',
+    hint: safeString`This transaction conflicts with an earlier one, please try again`,
+    action: 'refresh-and-retry',
+    reasons: [EVM_ERROR_REASONS.nonceTooLow.reason],
+  },
+  NONCE_TOO_HIGH: {
+    code: 'EXOD-3041',
+    hint: safeString`An earlier transaction is still pending, try again once it confirms`,
+    action: 'retry-later',
+    reasons: [EVM_ERROR_REASONS.nonceTooHigh.reason],
+  },
+  NONCE_GAP: {
+    code: 'EXOD-3042',
+    hint: safeString`An earlier transaction was dropped, send a new transaction first`,
+    action: 'refresh-and-retry',
+    patterns: [/ERR_BUMP_TX_NONCE_GAP/],
+    reasons: [EVM_ERROR_REASONS.futureTransactionReplace.reason],
+  },
+  BUMP_TX_UNAVAILABLE: {
+    code: 'EXOD-3043',
+    hint: safeString`This transaction can no longer be sped up`,
+    action: 'edit-transaction',
+    patterns: [/ERR_BUMP_TX_DROPPED|^Cannot bump transaction\b/],
+  },
+  INVALID_SIGNATURE: {
+    code: 'EXOD-3044',
+    hint: safeString`The network rejected the transaction signature`,
+    action: 'contact-support',
+    reasons: [EVM_ERROR_REASONS.invalidRlpSerialization.reason],
+  },
+  REPLAY_PROTECTION_REQUIRED: {
+    code: 'EXOD-3045',
+    hint: safeString`This network requires replay-protected transactions`,
+    action: 'contact-support',
+    reasons: [EVM_ERROR_REASONS.eip155Required.reason],
+  },
+  TX_TYPE_NOT_SUPPORTED: {
+    code: 'EXOD-3046',
+    hint: safeString`This network does not support this transaction type`,
+    action: 'contact-support',
+    reasons: [EVM_ERROR_REASONS.transactionTypeNotSupported.reason],
+  },
+  CONTRACT_REVERTED: {
+    code: 'EXOD-3047',
+    hint: safeString`The contract rejected this transaction`,
+    action: 'edit-transaction',
+    reasons: [
+      EVM_ERROR_REASONS.executionReverted.reason,
+      EVM_ERROR_REASONS.invalidOpcode.reason,
+      EVM_ERROR_REASONS.invalidJumpDestination.reason,
+      EVM_ERROR_REASONS.mathError.reason,
+    ],
+  },
+  ZERO_AMOUNT: {
+    code: 'EXOD-3048',
+    hint: safeString`The amount must be greater than zero`,
+    action: 'edit-transaction',
+    reasons: [EVM_ERROR_REASONS.zeroTransfer.reason],
+  },
+  GAS_ESTIMATION_FAILED: {
+    code: 'EXOD-3049',
+    hint: safeString`Could not estimate the network fee for this transaction`,
+    action: 'retry',
+    reasons: [EVM_ERROR_REASONS.fetchGasLimitFailed.reason],
+  },
+
+  RATE_LIMITED: {
+    code: 'EXOD-3061',
+    hint: safeString`The network is busy, try again later`,
+    action: 'retry-later',
+    patterns: [/\breturned 429\b|too many requests|rate.?limit/i],
+  },
+  NODE_REQUEST_FAILED: {
+    code: 'EXOD-3062',
+    hint: safeString`The network node returned an error, try again later`,
+    action: 'retry',
+    reasons: [EVM_ERROR_REASONS.broadcastNodeUnavailable.reason],
+    types: [EVM_ERROR_TYPES.NODE_STATE_READ, EVM_ERROR_TYPES.CONTRACT_CALL],
+    patterns: [/\breturned 50[03]\b/],
+    prefixes: ['Bad rpc response'],
+  },
+  NETWORK_UNREACHABLE: {
+    code: 'EXOD-3060',
+    hint: safeString`Could not reach the network, check your connection and try again`,
+    action: 'retry',
+    names: ['AbortError', 'TimeoutError'],
+    patterns: [
+      /failed to fetch|fetch failed|network ?request failed|networkerror|socket hang up|\be(?:conn(?:refused|reset|aborted)|timedout|notfound|ai_again|hostunreach|netunreach)\b|\btimeout\b|rpc_request_timeout|timed out|\breturned 50[24]\b/i,
+    ],
+  },
+  BROADCAST_OUTCOME_UNKNOWN: {
+    code: 'EXOD-3063',
+    hint: safeString`The transaction may not have been sent, check your history before retrying`,
+    action: 'check-history',
+    reasons: [EVM_ERROR_REASONS.broadcastTxFailed.reason],
+  },
+  TX_RECORD_FAILED: {
+    code: 'EXOD-3064',
+    hint: safeString`The transaction was sent but could not be saved, check your history before sending again`,
+    action: 'check-history',
+  },
+
+  DELEGATED_ACCOUNT: {
+    code: 'EXOD-3080',
+    hint: safeString`This account's delegation does not allow this transaction`,
+    action: 'contact-support',
+    reasons: [EVM_ERROR_REASONS.delegatedAccountError.reason],
+  },
+
+  UNKNOWN_SEND_FAILURE: {
+    code: 'EXOD-3099',
+    hint: safeString`The transaction failed, please try again`,
+    action: 'refresh-and-retry',
+  },
+})
+
+const ENTRIES = Object.entries(EVM_ERRORS)
+
+const EVM_CODES = new Set(ENTRIES.map(([, { code }]) => code))
+
+const findKey = (field, matches) => ENTRIES.find(([, entry]) => entry[field]?.some(matches))?.[0]
+
+const REASON_TO_ERROR_KEY = new Map(
+  ENTRIES.flatMap(([key, { reasons = [] }]) => reasons.map((reason) => [reason, key]))
+)
+
+const MAX_MESSAGE_LENGTH = 1000
+
+const getErrorKey = (error) => {
+  const nameKey = findKey('names', (name) => name === error.name || name === error.cause?.name)
+  if (nameKey) return nameKey
+  if (error.reason === EVM_ERROR_REASONS.broadcastTxFailed.reason) {
+    return 'BROADCAST_OUTCOME_UNKNOWN'
+  }
+
+  const message =
+    typeof error.message === 'string' ? error.message.slice(0, MAX_MESSAGE_LENGTH) : ''
+
+  const messageReasonKey = REASON_TO_ERROR_KEY.get(getEvmErrorReason(message)?.reason)
+  if (messageReasonKey) return messageReasonKey
+
+  const patternKey = findKey('patterns', (pattern) => pattern.test(message))
+  if (patternKey) return patternKey
+
+  const reasonKey = REASON_TO_ERROR_KEY.get(error.reason)
+  if (reasonKey) return reasonKey
+
+  const nodeKey =
+    findKey('types', (type) => type === error.type) ??
+    findKey('prefixes', (prefix) => message.startsWith(prefix))
+  if (nodeKey) return nodeKey
+
+  return 'UNKNOWN_SEND_FAILURE'
+}
+
+const defineField = (error, field, value) =>
+  Object.defineProperty(error, field, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  })
+
+const setErrorCode = (error, key) => {
+  const { code, hint, action } = EVM_ERRORS[key]
+  const sourceCode = error.code ?? error.cause?.code
+  if (sourceCode !== undefined) defineField(error, 'sourceCode', sourceCode)
+  if (error.hint !== undefined) defineField(error, 'sourceHint', error.hint)
+  defineField(error, 'code', code)
+  defineField(error, 'hint', hint)
+  return defineField(error, 'recommendedAction', action)
+}
+
+export const withTxRecordErrorCode = (error) => {
+  if (!error || typeof error !== 'object') return error
+
+  return setErrorCode(error, 'TX_RECORD_FAILED')
+}
+
+export const withSendErrorCode = (error) => {
+  if (!error || typeof error !== 'object') return error
+  if (EVM_CODES.has(error.code)) return error
+
+  return setErrorCode(error, getErrorKey(error))
+}

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

@@ -56,6 +56,10 @@ export default class ApiCoinNodesServer extends EthLikeServer {
         revisedError.traceId = traceId
       }
 
+      if (response?.__errorChain) {
+        revisedError.errorChain = response.__errorChain
+      }
+
       throw revisedError
     }
 

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

@@ -114,6 +114,10 @@ export default class ClarityServer extends EthLikeServer {
         revisedError.traceId = traceId
       }
 
+      if (response?.__errorChain) {
+        revisedError.errorChain = response.__errorChain
+      }
+
       throw revisedError
     }
 

package/src/exodus-eth-server/fetch-json.js

@@ -41,8 +41,22 @@ export const fetchJson = async (url, fetchOptions) => {
   return json
 }
 
-export const fetchJsonRetry = (url, fetchOptions) => {
+export const fetchJsonRetry = async (url, fetchOptions) => {
   const waitTimes = ['3s']
-  const fetchWithRetry = retry(fetchJson, { delayTimesMs: waitTimes })
-  return fetchWithRetry(url, fetchOptions)
+  const errorChain = []
+  const fetchAttempt = async () => {
+    try {
+      return await fetchJson(url, fetchOptions)
+    } catch (err) {
+      errorChain.push(err)
+      throw err
+    }
+  }
+
+  const json = await retry(fetchAttempt, { delayTimesMs: waitTimes })()
+  if (errorChain.length > 0 && json?.error) {
+    json.__errorChain = errorChain
+  }
+
+  return json
 }

package/src/index.js

@@ -120,6 +120,8 @@ export {
   EthLikeError,
 } from './error-wrapper.js'
 
+export { EVM_ERRORS } from './errors.js'
+
 export { txSendFactory } from './tx-send/index.js'
 
 export { createAssetFactory } from './create-asset.js'

package/src/staking/ethereum/everstake.js

@@ -30,7 +30,7 @@ const fetch = async (path, config = Object.create(null)) => {
 const isFiniteInteger = (e) => Number.isInteger(e) && Number.isFinite(e)
 
 // Simulate an unstake to predict how much ETH the interchange pool returns instantly.
-// https://wallet-sdk-api.everstake.one/swagger/#/Ethereum/post_ethereum_pool_simulate_unstake
+// https://wallet-sdk-api.everstake.com/swagger/#/Ethereum/post_ethereum_pool_simulate_unstake
 // Routed through the Exodus Everstake proxy rather than calling Everstake directly from the client.
 //
 // Inputs:
@@ -87,7 +87,7 @@ export const getCachedEverstakeValidatorsQueue = createCachedStakingRead({
 })
 
 export const getEverstakeValidatorsQueue = async () => {
-  // https://swagger.eth-api-b2c.everstake.one/#/Staking/validatorsQueue
+  // https://swagger.eth-api-b2c.everstake.com/#/Staking/validatorsQueue
   const result = await fetch('v1/validators/queue')
 
   const {

package/src/tx-create.js

@@ -6,6 +6,7 @@ import {
 import createEthereumJsTx from '@exodus/ethereum-lib/src/unsigned-tx/create-ethereumjs-tx.js'
 import assert from 'minimalistic-assert'
 
+import { withSendErrorCode } from './errors.js'
 import { authenticateReplacement } from './transaction-authentication.js'
 import { ensureSaneEip1559GasPriceForTipGasPrice } from './fee-utils.js'
 import { fetchGasLimit } from './gas-estimation.js'
@@ -432,7 +433,7 @@ const createBumpUnsignedTx = async ({
 export const createTxFactory = ({ chainId, assetClientInterface, useAbsoluteNonce }) => {
   assert(assetClientInterface, 'assetClientInterface is required')
   assert(typeof chainId === 'number', 'chainId is required')
-  return async ({
+  const createTx = async ({
     asset,
     walletAccount,
     nft, // when sending nfts
@@ -652,4 +653,12 @@ export const createTxFactory = ({ chainId, assetClientInterface, useAbsoluteNonc
       eip1559Enabled,
     })
   }
+
+  return async (params) => {
+    try {
+      return await createTx(params)
+    } catch (err) {
+      throw withSendErrorCode(err)
+    }
+  }
 }

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

@@ -1,6 +1,25 @@
 import { EthLikeError, EVM_ERROR_REASONS, getEvmErrorReason } from '../error-wrapper.js'
 import { transactionExists } from '../eth-like-util.js'
 
+const NODE_UNAVAILABLE_MESSAGE = /\breturned (?:429|50[03])\b/
+
+const isNodeUnavailable = (attempt) => NODE_UNAVAILABLE_MESSAGE.test(attempt?.message ?? '')
+
+const isOutcomeUnknownAttempt = (attempt) =>
+  !isNodeUnavailable(attempt) && !getEvmErrorReason(attempt?.message ?? '')
+
+const getReplyReason = (err) =>
+  getEvmErrorReason(err.message) ??
+  (isNodeUnavailable(err)
+    ? EVM_ERROR_REASONS.broadcastNodeUnavailable
+    : EVM_ERROR_REASONS.broadcastTxFailed)
+
+const getAttemptReason = (err, replyInfo) => {
+  if (replyInfo.reason === EVM_ERROR_REASONS.alreadyKnown.reason) return replyInfo
+  if (!err.errorChain?.some(isOutcomeUnknownAttempt)) return replyInfo
+  return EVM_ERROR_REASONS.broadcastTxFailed
+}
+
 /**
  * Handles broadcast errors by parsing the error message and either throwing
  * an appropriate EthLikeError or returning info for retry logic.
@@ -20,13 +39,13 @@ export const handleBroadcastError = async (
   err,
   { asset, txId, isHardware, hint, isBumpTx, isRetryNonceTx }
 ) => {
-  const message = err.message
-
-  const errorInfo = getEvmErrorReason(message) || EVM_ERROR_REASONS.broadcastTxFailed
+  const replyInfo = getReplyReason(err)
+  const errorInfo = getAttemptReason(err, replyInfo)
 
   const isNonceTooLow = errorInfo.reason === EVM_ERROR_REASONS.nonceTooLow.reason
   const isAmbiguousError =
-    isNonceTooLow || errorInfo.reason === EVM_ERROR_REASONS.transactionUnderpriced.reason
+    replyInfo.reason === EVM_ERROR_REASONS.nonceTooLow.reason ||
+    replyInfo.reason === EVM_ERROR_REASONS.transactionUnderpriced.reason
 
   if (errorInfo.reason === EVM_ERROR_REASONS.alreadyKnown.reason) {
     console.debug('tx already broadcast')

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

@@ -5,6 +5,7 @@ import assert from 'minimalistic-assert'
 import ms from 'ms'
 
 import { EthLikeError, EVM_ERROR_REASONS } from '../error-wrapper.js'
+import { withSendErrorCode, withTxRecordErrorCode } from '../errors.js'
 import { getOptimisticTxLogEffects } from '../tx-log/index.js'
 import { signTx } from '../tx-sign/index.js'
 import { ARBITRARY_ADDRESS } from '../tx-type/index.js'
@@ -17,6 +18,10 @@ const isOutcomeUnknown = (error) =>
 
 const isRejectedByNode = (error) => error instanceof EthLikeError && !isOutcomeUnknown(error)
 
+const isNodeUnavailable = (error) =>
+  error instanceof EthLikeError &&
+  error.reason === EVM_ERROR_REASONS.broadcastNodeUnavailable.reason
+
 const omitNonce = (optimisticTxLogEffects) =>
   optimisticTxLogEffects.map(({ txs, ...optimisticTxLogEffect }) => ({
     ...optimisticTxLogEffect,
@@ -60,7 +65,12 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
     }
   }
 
-  return async ({ asset, walletAccount, unsignedTx: providedUnsignedTx, ...legacyParams }) => {
+  const sendTx = async ({
+    asset,
+    walletAccount,
+    unsignedTx: providedUnsignedTx,
+    ...legacyParams
+  }) => {
     const baseAsset = asset.baseAsset
 
     const { unsignedTx } = providedUnsignedTx
@@ -118,7 +128,7 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
             })
             return true
           } catch (error) {
-            if (!isOutcomeUnknown(error)) return false
+            if (!isOutcomeUnknown(error) && !isNodeUnavailable(error)) return false
           }
         }
       }
@@ -224,10 +234,22 @@ const txSendFactory = ({ assetClientInterface, createTx }) => {
       })
     }
 
-    await writeTxLog(optimisticTxLogEffects)
+    try {
+      await writeTxLog(optimisticTxLogEffects)
+    } catch (err) {
+      throw withTxRecordErrorCode(err)
+    }
 
     return { txId, nonce }
   }
+
+  return async (params) => {
+    try {
+      return await sendTx(params)
+    } catch (err) {
+      throw withSendErrorCode(err)
+    }
+  }
 }
 
 export default txSendFactory