@exodus/ethereum-api 9.0.1 → 9.0.3

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.
 
+## [9.0.3](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@9.0.2...@exodus/ethereum-api@9.0.3) (2026-10-05)
+
+
+### Bug Fixes
+
+* **ethereum-api:** prefer newer tx-log drain over stale token balance ([#8793](https://github.com/ExodusMovement/assets/issues/8793)) ([f6cc0e4](https://github.com/ExodusMovement/assets/commit/f6cc0e4031f89c71951e206c9c09fe042aa9354c))
+
+
+
+## [9.0.2](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@9.0.1...@exodus/ethereum-api@9.0.2) (2026-10-02)
+
+
+### Bug Fixes
+
+* **ethereum-api:** keep balances on truncated refresh when history fails ([#8739](https://github.com/ExodusMovement/assets/issues/8739)) ([2c8bdb5](https://github.com/ExodusMovement/assets/commit/2c8bdb590ae0f91a93eae377c965dda9bda90a74))
+
+
+
 ## [9.0.1](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@9.0.0...@exodus/ethereum-api@9.0.1) (2026-10-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "9.0.1",
+  "version": "9.0.3",
   "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",
@@ -66,5 +66,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "28868209b3e87ea927600231556d6728fc319fcd"
+  "gitHead": "e783e7a31c40807698ae2b9629e1c2dd5c03c228"
 }

package/src/get-balances.js

@@ -38,12 +38,17 @@ const getBaseBalanceFromAccountState = ({ asset, txLog, accountState }) => {
  * Token counterpart of {@link getBaseBalance}. Tokens are sparse — there's no
  * model default for `tokenBalances[name]`, so any value present (including an
  * explicit ZERO from `accountInfo` after the user drained the token) is
- * authoritative and returned as-is. Only when the key is missing entirely do
- * we fall through to the truncated baseline / txLog walk.
+ * authoritative and returned as-is, unless the txLog holds a canonical
+ * `balanceChange` from a newer block than the `account_balance` row (or the
+ * row's block is unknown). Only when the key is missing entirely do we fall
+ * through to the truncated baseline / txLog walk.
  */
-const getTokenBalanceFromAccountState = ({ asset, txLog, accountState }) => {
+const getTokenBalanceFromAccountState = ({ asset, txLog, accountState, latestBalanceTx }) => {
   const balance = getBalanceFromAccountStateIfAny({ asset, accountState })
-  if (balance) return balance
+  const balanceBlockNumber = accountState?.tokenBalanceBlockNumbers?.[asset.name]
+  const isOlderThanTxLog =
+    latestBalanceTx && !(balanceBlockNumber >= latestBalanceTx.data.blockNumber)
+  if (balance && !isOlderThanTxLog) return balance
 
   if (txLog.size === 0) {
     return getTruncatedTokenBalance({ asset, accountState }) ?? asset.currency.ZERO
@@ -96,15 +101,6 @@ export const getAbsoluteBalance = ({ asset, txLog, accountState }) => {
   assert(asset, 'asset is required')
   assert(txLog, 'txLog is required')
 
-  const isBase = asset.name === asset.baseAsset.name
-  const accountStateBalance = isBase
-    ? getBaseBalanceFromAccountState({ asset, txLog, accountState })
-    : getTokenBalanceFromAccountState({ asset, txLog, accountState })
-  if (accountStateBalance) {
-    // Authoritative `accountState` snapshot (or empty-txLog terminal value).
-    return accountStateBalance
-  }
-
   // NOTE: We reverse the `txLog` to prioritize the handling
   //       of the most recent transactions first. The reason
   //       we do this is to terminate early if we find an
@@ -113,6 +109,20 @@ export const getAbsoluteBalance = ({ asset, txLog, accountState }) => {
 
   const maybeLatestAbsoluteBalanceTx = getLatestCanonicalAbsoluteBalanceTx({ reversedTxLog })
 
+  const isBase = asset.name === asset.baseAsset.name
+  const accountStateBalance = isBase
+    ? getBaseBalanceFromAccountState({ asset, txLog, accountState })
+    : getTokenBalanceFromAccountState({
+        asset,
+        txLog,
+        accountState,
+        latestBalanceTx: maybeLatestAbsoluteBalanceTx,
+      })
+  if (accountStateBalance) {
+    // Authoritative `accountState` snapshot (or empty-txLog terminal value).
+    return accountStateBalance
+  }
+
   let balance = asset.currency.ZERO
   let hasAbsoluteBalance = false
 

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

@@ -1,14 +1,23 @@
 import { ClarityMonitor } from './clarity-monitor.js'
+import { isCanonicalAbsoluteBalanceTx } from './clarity-utils/index.js'
 import { extractBalanceFromClarityAccountInfo } from './monitor-utils/index.js'
 
-const omitTokensWithConfirmedBalanceChange = ({ tokenBalances, logItemsByAsset }) => {
-  if (!tokenBalances || !logItemsByAsset) return tokenBalances
-  const result = { ...tokenBalances }
-  for (const [assetName, txs] of Object.entries(logItemsByAsset)) {
-    if (txs.some((tx) => tx.confirmations > 0 && tx.data?.balanceChange)) delete result[assetName]
+const omitTokensWithNewerConfirmedBalanceChange = ({
+  tokenBalances,
+  tokenBalanceBlockNumbers,
+  logItemsByAsset,
+}) => {
+  const balances = { ...tokenBalances }
+  const blockNumbers = { ...tokenBalanceBlockNumbers }
+  for (const [assetName, txs] of Object.entries(logItemsByAsset ?? {})) {
+    const isNewer = (tx) => !(blockNumbers[assetName] >= tx.data.blockNumber)
+    if (txs.some((tx) => tx.confirmations > 0 && isCanonicalAbsoluteBalanceTx(tx) && isNewer(tx))) {
+      delete balances[assetName]
+      delete blockNumbers[assetName]
+    }
   }
 
-  return result
+  return { tokenBalances: tokenBalances && balances, tokenBalanceBlockNumbers: blockNumbers }
 }
 
 /**
@@ -49,11 +58,12 @@ export class ClarityTruncatedHistoryMonitor extends ClarityMonitor {
     // truncated), we must ensure older checkpoints cannot
     // be inadvertently relied upon.
     //
-    if (refresh) {
+    if (refresh && historyResponse) {
       const defaultAccountState = this.asset.api.createAccountState().create()
       resetBalances = {
         balance: defaultAccountState.balance,
         tokenBalances: defaultAccountState.tokenBalances,
+        tokenBalanceBlockNumbers: defaultAccountState.tokenBalanceBlockNumbers,
       }
       currentAccountState = (currentAccountState ?? defaultAccountState).merge(resetBalances)
     }
@@ -64,10 +74,12 @@ export class ClarityTruncatedHistoryMonitor extends ClarityMonitor {
       tokensByAddress,
     })
 
-    const prevTokenBalances = omitTokensWithConfirmedBalanceChange({
-      tokenBalances: currentAccountState?.tokenBalances,
-      logItemsByAsset,
-    })
+    const { tokenBalances: prevTokenBalances, tokenBalanceBlockNumbers: prevBlockNumbers } =
+      omitTokensWithNewerConfirmedBalanceChange({
+        tokenBalances: currentAccountState?.tokenBalances,
+        tokenBalanceBlockNumbers: currentAccountState?.tokenBalanceBlockNumbers,
+        logItemsByAsset,
+      })
 
     const { accountState } = await this.getStateUpdate({
       derivedData,
@@ -92,6 +104,15 @@ export class ClarityTruncatedHistoryMonitor extends ClarityMonitor {
         ...balanceFromAccountInfo.tokenBalances,
         ...accountState.tokenBalances,
       }
+      const tokenBalanceBlockNumbers = { ...prevBlockNumbers }
+      for (const tokenName of Object.keys(balanceFromAccountInfo.tokenBalances ?? {})) {
+        delete tokenBalanceBlockNumbers[tokenName]
+      }
+
+      newData.tokenBalanceBlockNumbers = {
+        ...tokenBalanceBlockNumbers,
+        ...balanceFromAccountInfo.tokenBalanceBlockNumbers,
+      }
     }
 
     if (

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

@@ -131,6 +131,9 @@ Wallet `0x3F80…9164` on Ethereum. Two txs + the one real `accountInfo` row:
   tokenBalances: {
     ousd_ethereum_48fcf72d: NumberUnit('20191.469… OUSD'),   // account_balance row
   },
+  tokenBalanceBlockNumbers: {
+    ousd_ethereum_48fcf72d: 24933420,                         // account_balance row blockNumber
+  },
   truncatedAccountState: {
     balance: ZERO,
     tokenBalances: {},
@@ -162,7 +165,7 @@ Source: `getAbsoluteBalance` in `src/get-balances.js`, ordered branches:
 
 1. Non-zero `accountState` balance → return it.
 2. `txLog.size === 0` → return `truncatedAccountState` balance or `ZERO`.
-3. Token value exists in `accountState.tokenBalances` → return accountState balance, including explicit zero.
+3. Token value exists in `accountState.tokenBalances` → return accountState balance, including explicit zero, unless the txLog's latest canonical `balanceChange` is in a newer block than `tokenBalanceBlockNumbers[token]` (or that block is unknown).
 4. Walk reversed `txLog` for canonical `balanceChange` tx.
 5. If no absolute balance exists, fall back to the txLog-derived balance path.
 
@@ -205,7 +208,8 @@ case 'clarity-truncated-history':  // normalized to clarity-v2
 4. Emit `source: 'truncated'` rows on the initial `cursor=0` fetch for state that existed before the returned history window.
 5. Row shapes: `{ type: 'balance' | 'nonce' | 'token', source: 'account_balance' | 'truncated', value, blockNumber, assetId?, assetName?, decimals? }`. Sorted client-side by `blockNumber` desc; first value per type/assetId wins for `balance`/`token`. `nonce` rows are collapsed via `Math.max` regardless of source.
 6. Unknown `assetId` → client drops the row.
-7. `value` arrives as a decimal string. `null`, `undefined`, and empty-string `""` mean "no value" and the row is skipped.
+7. `blockNumber` on token `account_balance` rows is the block the balance was read at. The client stores it and prefers the txLog when its latest `balanceChange` is newer. So a drained token with no new row falls back to the txLog value.
+8. `value` arrives as a decimal string. `null`, `undefined`, and empty-string `""` mean "no value" and the row is skipped.
 
 If the backend can't emit `accountInfo`, the monitor degrades gracefully to `clarity-v2` behavior (tx-log walk only).
 

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

@@ -3,7 +3,8 @@
  * 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`.
+ * are stored in `truncatedAccountState`. Token `account_balance` rows also record their
+ * `blockNumber` in `tokenBalanceBlockNumbers` so reads can tell whether the tx-log is newer.
  *
  * NOTE: All `row.value` payloads arrive over the wire as decimal strings (e.g. `"0"`,
  * `"20191469428776270391810"`). They're parsed with `currency.baseUnit(...)` for amounts
@@ -28,6 +29,7 @@ export const extractBalanceFromClarityAccountInfo = ({ accountInfo, asset, token
   const result = {}
   const seenAssetIds = new Set()
   const tokenBalances = Object.create(null)
+  const tokenBalanceBlockNumbers = Object.create(null)
   const truncatedTokenBalances = Object.create(null)
   let truncatedBalance
 
@@ -70,6 +72,9 @@ export const extractBalanceFromClarityAccountInfo = ({ accountInfo, asset, token
         const balance = token.currency.baseUnit(row.value)
         if (row.source === ACCOUNT_BALANCE) {
           tokenBalances[token.name] = balance
+          if (Number.isInteger(row.blockNumber)) {
+            tokenBalanceBlockNumbers[token.name] = row.blockNumber
+          }
         } else if (row.source === TRUNCATED) {
           truncatedTokenBalances[token.name] = balance
         } else {
@@ -87,6 +92,7 @@ export const extractBalanceFromClarityAccountInfo = ({ accountInfo, asset, token
 
   if (Object.keys(tokenBalances).length > 0) {
     result.tokenBalances = tokenBalances
+    result.tokenBalanceBlockNumbers = tokenBalanceBlockNumbers
   }
 
   const hasTruncatedTokenBalances = Object.keys(truncatedTokenBalances).length > 0