@exodus/ethereum-api 10.2.2 → 10.3.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.3.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@10.2.3...@exodus/ethereum-api@10.3.0) (2026-10-30)
+
+
+### Features
+
+* **ethereum-api:** self-heal tx log with clarity tip mode ([#9123](https://github.com/ExodusMovement/assets/issues/9123)) ([67cbc64](https://github.com/ExodusMovement/assets/commit/67cbc641606e18f1c4cdf66ee0d76b3e7fdd70fd))
+
+
+
+## [10.2.3](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@10.2.2...@exodus/ethereum-api@10.2.3) (2026-10-23)
+
+
+### Bug Fixes
+
+* **ethereum-api:** allow accelerating a tx parked below the base fee ([#9049](https://github.com/ExodusMovement/assets/issues/9049)) ([2dac03f](https://github.com/ExodusMovement/assets/commit/2dac03f68d1de7cc56a191e82e4e217ad8a5bf07))
+
+
+
 ## [10.2.2](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@10.2.1...@exodus/ethereum-api@10.2.2) (2026-10-22)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "10.2.2",
+  "version": "10.3.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": "8b769034df65590a5fcab8a40d0929c162b117c5"
+  "gitHead": "99c7d9d4aae75358a0269479e056e5785fbad5ed"
 }

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

@@ -63,10 +63,14 @@ export default class ClarityServerV2 extends ClarityServer {
     this.updateBaseApiPath(uri) // pass in the uri from remote config to override assets-gateway
   }
 
-  getTransactionsFromBlockNumber = async ({ address, blockNumber, withInput, truncated }) => {
+  getTransactionsFromBlockNumber = async ({ address, blockNumber, withInput, truncated, tip }) => {
     const url = new URL(`${this.baseApiPath}/addresses/${encodeURIComponent(address)}/transactions`)
     url.searchParams.set('cursor', blockNumber || '0')
 
+    if (tip) {
+      url.searchParams.set('mode', 'tip')
+    }
+
     if (withInput) {
       url.searchParams.set('withInput', 'true')
     }
@@ -122,8 +126,12 @@ export default class ClarityServerV2 extends ClarityServer {
    * into the backend's truncation mode + `accountInfo` pre-cursor snapshots (used by
    * `ClarityTruncatedHistoryMonitor`). For `clarity`/`clarity-v2`/`clarity-v3` flows,
    * leave the default so Clarity returns full history.
+   *
+   * Pass `tip: true` for incremental syncs: Clarity pages like the default mode until the
+   * chain tip, then returns the newest txs with a cursor anchored at the oldest of them and
+   * `hasMore: false`, so each call re-reads that window.
    */
-  async getAllTransactions({ address, cursor, withInput = true, truncated = false }) {
+  async getAllTransactions({ address, cursor, withInput = true, truncated = false, tip = false }) {
     let { blockNumber } = decodeCursor(cursor)
 
     let transactions = []
@@ -139,6 +147,7 @@ export default class ClarityServerV2 extends ClarityServer {
         blockNumber: blockNumber.toString(),
         withInput,
         truncated,
+        tip,
       })
 
       const txs = result.transactions || []
@@ -149,6 +158,23 @@ export default class ClarityServerV2 extends ClarityServer {
 
       const nextBlockNumber = BigInt(result.cursor)
 
+      if (tip) {
+        transactions.push(...txs)
+
+        if (!result.hasMore) {
+          blockNumber = nextBlockNumber
+          break
+        }
+
+        if (nextBlockNumber <= blockNumber) {
+          console.warn(`Tip mode cursor did not advance past ${blockNumber} with hasMore, stopping`)
+          break
+        }
+
+        blockNumber = nextBlockNumber
+        continue
+      }
+
       if (txs.length === 0) {
         // fetch until no more new transactions
         blockNumber = nextBlockNumber

package/src/tx-create.js

@@ -291,10 +291,11 @@ async function verifyBumpTxCanReplace({ baseAsset, bumpTxId, fromAddress, nonce
   // [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.
+  // Nonce to replace must be <= pendingNonce. At pendingNonce the node holds the tx
+  // without counting it, e.g. its fee cap is below the base fee, and it is the next
+  // executable slot. If nonce > pendingNonce, the slots below it are gapped — not safe to replace.
   const pendingNonce = parseInt(pendingNonceHex, 16)
-  if (pendingNonce <= nonce) {
+  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.
@@ -304,7 +305,7 @@ async function verifyBumpTxCanReplace({ baseAsset, bumpTxId, fromAddress, nonce
     // 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}), ` +
+        `node's pending nonce (${pendingNonce}) < tx nonce (${nonce}), ` +
         `broadcasting would produce ErrFutureReplacePending`
     )
   }

package/src/tx-log/clarity-monitor.js

@@ -42,6 +42,7 @@ export class ClarityMonitor extends BaseMonitor {
     this.eip7702Whitelist = eip7702Whitelist ?? createEip7702Whitelist(eip7702Supported)
     this.getBlackListStatus = getBlackListStatus
     this.getAllLogItemsByAsset = getAllLogItemsByAsset
+    this.emittedUnknownTokenAddresses = new Set()
     this.deriveDataNeededForTick = getDeriveDataNeededForTick(this.aci)
     this.deriveTransactionsToCheck = getDeriveTransactionsToCheck({
       getTxLog: (...args) => this.aci.getTxLog(...args),
@@ -240,7 +241,6 @@ export class ClarityMonitor extends BaseMonitor {
 
     const batch = this.aci.createOperationsBatch()
     let allTxs = []
-    let hasNewTxs = false
     let historyResponse
     let historyError
     let processedLogItemsByAsset
@@ -255,8 +255,6 @@ export class ClarityMonitor extends BaseMonitor {
         walletAccount,
       }))
 
-      hasNewTxs = allTxs.length > 0
-
       const logItemsByAsset = this.getAllLogItemsByAsset({
         getLogItemsFromServerTx,
         ourWalletAddress: derivedData.ourWalletAddress,
@@ -266,6 +264,10 @@ export class ClarityMonitor extends BaseMonitor {
         assets,
       })
 
+      if (this.isTipSync({ derivedData, refresh })) {
+        await this.warnReaddedTxs({ walletAccount, logItemsByAsset })
+      }
+
       const { txsToRemove } = await this.checkPendingTransactions({
         txlist: allTxs,
         walletAccount,
@@ -333,13 +335,44 @@ export class ClarityMonitor extends BaseMonitor {
         : new Error(String(historyError), { cause: historyError })
     }
 
-    if (refresh || hasNewTxs) {
-      const unknownTokenAddresses = this.getUnknownTokenAddresses({
-        transactions: allTxs,
-        tokensByAddress,
-      })
-      if (unknownTokenAddresses.length > 0) {
-        this.emit('unknown-tokens', unknownTokenAddresses)
+    const unknownTokenAddresses = this.getUnknownTokenAddresses({
+      transactions: allTxs,
+      tokensByAddress,
+    })
+    const addressesToEmit = refresh
+      ? unknownTokenAddresses
+      : unknownTokenAddresses.filter((address) => !this.emittedUnknownTokenAddresses.has(address))
+    for (const address of unknownTokenAddresses) this.emittedUnknownTokenAddresses.add(address)
+    if (addressesToEmit.length > 0) {
+      this.emit('unknown-tokens', addressesToEmit)
+    }
+  }
+
+  async warnReaddedTxs({ walletAccount, logItemsByAsset }) {
+    const isConfirmed = (tx) => tx.confirmations > 0 && Number.isInteger(tx.data?.blockNumber)
+
+    for (const [assetName, txs] of Object.entries(logItemsByAsset)) {
+      const confirmedTxs = txs.filter(isConfirmed)
+      if (confirmedTxs.length === 0) continue
+
+      const txLog = await this.aci.getTxLog({ assetName, walletAccount })
+      const missingTxs = confirmedTxs.filter((tx) => !txLog.has(tx.txId))
+      if (missingTxs.length === 0) continue
+
+      let newestLoggedBlock = -1
+      for (const tx of txLog) {
+        if (isConfirmed(tx)) newestLoggedBlock = Math.max(newestLoggedBlock, tx.data.blockNumber)
+      }
+
+      const readdedTxIds = missingTxs
+        .filter((tx) => tx.data.blockNumber <= newestLoggedBlock)
+        .map((tx) => tx.txId)
+      if (readdedTxIds.length > 0) {
+        this.logger.warn('clarity tip window re-added txs missing from tx log', {
+          assetName,
+          walletAccount,
+          txIds: readdedTxIds,
+        })
       }
     }
   }
@@ -482,11 +515,15 @@ export class ClarityMonitor extends BaseMonitor {
     this.server.dispose()
   }
 
+  isTipSync({ derivedData, refresh }) {
+    return !refresh && Boolean(derivedData.currentAccountState?.clarityCursor)
+  }
+
   async getHistoryFromServer({ walletAccount, derivedData, refresh }) {
     const address = derivedData.ourWalletAddress
-    const currentCursor = derivedData.currentAccountState?.clarityCursor
-    const cursor = currentCursor && !refresh ? currentCursor : null
-    return this.server.getAllTransactions({ walletAccount, address, cursor })
+    const tip = this.isTipSync({ derivedData, refresh })
+    const cursor = tip ? derivedData.currentAccountState.clarityCursor : null
+    return this.server.getAllTransactions({ walletAccount, address, cursor, tip })
   }
 
   listenToServerEvents() {

package/src/tx-log/clarity-truncated-history-monitor.js

@@ -137,15 +137,15 @@ export class ClarityTruncatedHistoryMonitor extends ClarityMonitor {
 
   async getHistoryFromServer({ walletAccount, derivedData, refresh }) {
     const address = derivedData.ourWalletAddress
-    const currentCursor = derivedData.currentAccountState?.clarityCursor
-    const cursor = currentCursor && !refresh ? currentCursor : null
+    const tip = this.isTipSync({ derivedData, refresh })
+    const cursor = tip ? derivedData.currentAccountState.clarityCursor : null
     return this.server.getAllTransactions({
       walletAccount,
       address,
       cursor,
-      refresh,
       withInput: true,
       truncated: true,
+      tip,
     })
   }
 }

package/src/tx-log/clarity-truncated-history-monitor.md

@@ -3,6 +3,7 @@
 Extends `ClarityMonitor`. Used when Clarity only serves a **recent window** of txs and attaches pre-cursor snapshots in `accountInfo`.
 
 - Sends `truncated=true` on `getAllTransactions`.
+- Incremental ticks use Clarity `mode=tip`, like `clarity-v2`. The tip page carries `accountInfo`, so `account_balance` rows still update rebasing tokens. First sync and refresh use default mode.
 - Folds `accountInfo` into `accountState`, including truncated-history baselines.
 - Forces `rpcBalanceAssetNames = []` (no per-asset RPC `eth_getBalance` batch).
 
@@ -217,6 +218,7 @@ If the backend can't emit `accountInfo`, the monitor degrades gracefully to `cla
 
 ## Tests
 
+- `src/tx-log/__tests__/clarity-tip-mode.test.js` — `clarity-v2` tip mode (dropped tx re-added, stable cursor, default mode on refresh); this monitor's tip ticks send `truncated=true` and `account_balance` rows track a rebase; refresh uses default mode and still collects `accountInfo`.
 - `src/tx-log/__tests__/clarity-truncated-history-monitor.test.js` — `truncated: true`, no RPC balance batch, accountInfo → `balance`, token `tokenBalances`, and `truncatedAccountState`.
 - `src/__tests__/create-asset-utils.test.js` — factory → `ClarityTruncatedHistoryMonitor`.
 - `src/__tests__/get-balances.test.js` — accountState token short-circuit and truncated baseline cases.

package/src/tx-log/clarity-utils/get-log-items-from-server-tx.js

@@ -55,9 +55,8 @@ export default function getLogItemsFromServerTx({
   const toAddress = tryFindExternalRecipient(ethereumTransfers, ourWalletAddress)
   const ourWalletWasSender = serverTx.from === ourWalletAddress
   const METHOD_ID_LENGTH = 10
-  const methodId = serverTx.input && {
-    methodId: serverTx.input.slice(0, Math.max(0, METHOD_ID_LENGTH)),
-  }
+  const serverMethodId = serverTx.methodId ?? serverTx.input?.slice(0, METHOD_ID_LENGTH)
+  const methodId = serverMethodId && { methodId: serverMethodId }
   const data = (ourWalletWasSender ? serverTx.input : methodId?.methodId) || '0x'
   const walletUpdates = getWalletUpdates(ourWalletAddress, serverTx.walletChanges || [])
   const { baseBalanceUpdate, nonceUpdate, tokenBalancesUpdate } = walletUpdates