@exodus/ethereum-api 8.71.3 → 8.72.0

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.72.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.71.3...@exodus/ethereum-api@8.72.0) (2026-04-30)
+
+
+### Features
+
+
+* feat: start adding truncated history for clarity evm (#7604)
+
+
+
 ## [8.71.3](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.71.2...@exodus/ethereum-api@8.71.3) (2026-04-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "8.71.3",
+  "version": "8.72.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",
@@ -23,13 +23,13 @@
   },
   "dependencies": {
     "@exodus/asset": "^2.0.4",
-    "@exodus/asset-lib": "^5.8.0",
+    "@exodus/asset-lib": "^5.9.0",
     "@exodus/assets": "^11.4.0",
     "@exodus/basic-utils": "^3.0.1",
     "@exodus/bip44-constants": "^195.0.0",
     "@exodus/crypto": "^1.0.0-rc.26",
     "@exodus/currency": "^6.0.1",
-    "@exodus/ethereum-lib": "^5.22.0",
+    "@exodus/ethereum-lib": "^5.24.0",
     "@exodus/ethereum-meta": "^2.9.1",
     "@exodus/ethereumholesky-meta": "^2.0.5",
     "@exodus/ethereumjs": "^1.11.0",
@@ -68,5 +68,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "9f37c342087c5e2971af624b4067fd36b0d81ed5"
+  "gitHead": "87bf2c314792d465c10789267316e74d7a19301a"
 }

package/src/create-asset-utils.js

@@ -9,6 +9,7 @@ import { createEvmServer, createWsGateway, ValidMonitorTypes } from './exodus-et
 import { createEthereumHooks } from './hooks/index.js'
 import { ClarityMonitor } from './tx-log/clarity-monitor.js'
 import { ClarityMonitorV2 } from './tx-log/clarity-monitor-v2.js'
+import { ClarityTruncatedHistoryMonitor } from './tx-log/clarity-truncated-history-monitor.js'
 import { EthereumMonitor } from './tx-log/ethereum-monitor.js'
 import { EthereumNoHistoryMonitor } from './tx-log/ethereum-no-history-monitor.js'
 import { BLOCK_TAG_LATEST, BLOCK_TAG_PENDING, resolveNonce } from './tx-send/nonce-utils.js'
@@ -169,6 +170,16 @@ export const createHistoryMonitorFactory = ({
           ...args,
         })
         break
+      case 'clarity-truncated-history':
+        monitor = new ClarityTruncatedHistoryMonitor({
+          assetClientInterface,
+          interval: ms(monitorInterval || '5m'),
+          server,
+          eip7702Supported,
+          getBlackListStatus,
+          ...args,
+        })
+        break
       case 'clarity-v3':
         monitor = new ClarityMonitorV2({
           assetClientInterface,
@@ -265,15 +276,22 @@ export const getNonceFactory = ({ assetClientInterface, useAbsoluteBalanceAndNon
     assert(typeof fromAddress === 'string', 'expected fromAddress')
     assert(walletAccount, 'expected walletAccount')
 
-    const txLog = await assetClientInterface.getTxLog({
-      assetName: asset.baseAsset.name,
-      walletAccount,
-    })
+    const [txLog, accountState] = await Promise.all([
+      assetClientInterface.getTxLog({
+        assetName: asset.baseAsset.name,
+        walletAccount,
+      }),
+      assetClientInterface.getAccountState({
+        assetName: asset.baseAsset.name,
+        walletAccount,
+      }),
+    ])
 
     return resolveNonce({
       asset,
       fromAddress,
       txLog,
+      accountState,
       forceFromNode,
       tag,
       useAbsoluteNonce: useAbsoluteBalanceAndNonce,

package/src/create-asset.js

@@ -137,7 +137,11 @@ export const createAssetFactory = ({
       useAbsoluteBalanceAndNonce = overrideUseAbsoluteBalanceAndNonce
     }
 
-    const server = createEvmServer({ assetName: asset.name, serverUrl, monitorType })
+    const server = createEvmServer({
+      assetName: asset.name,
+      serverUrl,
+      monitorType,
+    })
 
     const address = {
       validate: validateFactory({ chainId, useEip1191ChainIdChecksum }),

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

@@ -108,10 +108,18 @@ export default class ClarityServerV2 extends ClarityServer {
     this.updateBaseApiPath(uri) // pass in the uri from remote config to override assets-gateway
   }
 
-  getTransactionsAtBlockNumber = async ({ address, blockNumber, withInput = true }) => {
+  getTransactionsFromBlockNumber = async ({ address, blockNumber, withInput, truncated }) => {
     const url = new URL(`${this.baseApiPath}/addresses/${encodeURIComponent(address)}/transactions`)
-    url.searchParams.set('cursor', blockNumber)
-    url.searchParams.set('withInput', Boolean(withInput).toString())
+    url.searchParams.set('cursor', blockNumber || '0')
+
+    if (withInput) {
+      url.searchParams.set('withInput', 'true')
+    }
+
+    if (truncated) {
+      url.searchParams.set('truncated', 'true')
+    }
+
     return fetchJsonRetry(url)
   }
 
@@ -154,19 +162,37 @@ export default class ClarityServerV2 extends ClarityServer {
     }
   }
 
-  async getAllTransactions({ address, cursor }) {
+  /**
+   * Paginates GET .../addresses/:addr/transactions. Pass `truncated: true` to opt
+   * 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.
+   */
+  async getAllTransactions({ address, cursor, withInput = true, truncated = false }) {
     let { blockNumber } = decodeCursor(cursor)
 
     let transactions = []
 
+    // accountInfo rows carry balance/nonce snapshots for blocks before the
+    // initial cursor — used to derive correct state with truncated history.
+    // Only collected (and returned) when the caller opted into `truncated`.
+    const accountInfo = truncated ? [] : null
+
     while (true) {
-      const { transactions: txs, cursor: nextBlockNumberInteger } =
-        await this.getTransactionsAtBlockNumber({
-          address,
-          blockNumber: blockNumber.toString(),
-        })
+      const result = await this.getTransactionsFromBlockNumber({
+        address,
+        blockNumber: blockNumber.toString(),
+        withInput,
+        truncated,
+      })
+
+      const txs = result.transactions || []
+
+      if (accountInfo && Array.isArray(result.accountInfo)) {
+        accountInfo.push(...result.accountInfo)
+      }
 
-      const nextBlockNumber = BigInt(nextBlockNumberInteger)
+      const nextBlockNumber = BigInt(result.cursor)
 
       if (txs.length === 0) {
         // fetch until no more new transactions
@@ -200,6 +226,7 @@ export default class ClarityServerV2 extends ClarityServer {
     return {
       transactions: { confirmed, pending },
       cursor: newCursor,
+      ...(accountInfo && { accountInfo }),
     }
   }
 

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

@@ -14,18 +14,28 @@ import ClarityServer from './clarity.js'
 import ClarityServerV2 from './clarity-v2.js'
 import WsGateway from './ws-gateway.js'
 
-export const ValidMonitorTypes = ['no-history', 'clarity', 'clarity-v2', 'clarity-v3', 'magnifier']
+export const ValidMonitorTypes = [
+  'no-history',
+  'clarity',
+  'clarity-v2',
+  'clarity-truncated-history',
+  'clarity-v3',
+  'magnifier',
+]
 
 export function createEvmServer({ assetName, serverUrl, monitorType }) {
   assert(assetName, 'assetName is required')
   assert(serverUrl, 'serverUrl is required')
   assert(monitorType, 'monitorType is required')
+
+  // Truncated-history uses the same Clarity v2 HTTP/WS server; only the monitor class differs.
   switch (monitorType) {
     case 'no-history':
       return new ApiCoinNodesServer({ baseAssetName: assetName, uri: serverUrl })
     case 'clarity':
       return new ClarityServer({ baseAssetName: assetName, uri: serverUrl })
     case 'clarity-v2':
+    case 'clarity-truncated-history':
     case 'clarity-v3':
       return new ClarityServerV2({ baseAssetName: assetName, uri: serverUrl })
     case 'magnifier':

package/src/get-balances.js

@@ -1,5 +1,6 @@
 import {
   getBalanceFromAccountState,
+  getBalanceFromAccountStateIfAny,
   getBalanceFromTxLog,
   getUnconfirmedReceivedBalance,
   getUnconfirmedSentBalance,
@@ -34,12 +35,20 @@ import { getLatestCanonicalAbsoluteBalanceTx } from './tx-log/clarity-utils/inde
  *
  * See: docs/balances-model.md for the intended balance model spec.
  */
-export const getAbsoluteBalance = ({ asset, txLog }) => {
+export const getAbsoluteBalance = ({ asset, txLog, accountState }) => {
   assert(asset, 'asset is required')
   assert(txLog, 'txLog is required')
 
+  const accountStateBalance = getBalanceFromAccountStateIfAny({ asset, accountState })
+
   if (txLog.size === 0) {
-    return asset.currency.ZERO
+    return accountStateBalance || asset.currency.ZERO
+  }
+
+  // Prefer an explicit `accountState` snapshot (e.g. populated from Clarity `accountInfo`
+  // in truncated-history mode) over walking a potentially truncated `txLog`.
+  if (accountStateBalance) {
+    return accountStateBalance
   }
 
   // NOTE: We reverse the `txLog` to prioritize the handling
@@ -191,7 +200,8 @@ export const getBalancesFactory = ({ monitorType, useAbsoluteBalance, rpcBalance
       //       pessimistic reading that's safe for consumers.
       spendable = getBalanceFromAccountState({ asset, accountState }).sub(unconfirmedSent)
     } else {
-      const absoluteBalance = useAbsoluteBalance && getAbsoluteBalance({ asset, txLog })
+      const absoluteBalance =
+        useAbsoluteBalance && getAbsoluteBalance({ asset, txLog, accountState })
 
       if (absoluteBalance) {
         // NOTE: The returned `absoluteBalance` returns only confirmed

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

@@ -0,0 +1,207 @@
+import { getAssetAddresses } from '@exodus/ethereum-lib'
+
+import { ClarityMonitor } from './clarity-monitor.js'
+import { getLogItemsFromServerTx, normalizeTransactionsResponse } from './clarity-utils/index.js'
+import {
+  extractBalanceFromClarityAccountInfo,
+  getCurrentBlackListStatus,
+  getCurrentEIP7702Delegation,
+} from './monitor-utils/index.js'
+
+/**
+ * Clarity v2 + HTTP `getAllTransactions` with `truncated: true` so the backend can attach
+ * `accountInfo` (pre-cursor balance/nonce/token snapshots). Merges that data in `tick` before
+ * optional RPC follow-up; does not use `rpcBalanceAssetNames` (forced empty).
+ */
+export class ClarityTruncatedHistoryMonitor extends ClarityMonitor {
+  constructor({ rpcBalanceAssetNames, ...args } = {}) {
+    super({ ...args, rpcBalanceAssetNames: [] })
+  }
+
+  getNewAccountState(_args) {
+    return Object.create(null)
+  }
+
+  async getStateUpdate({ derivedData, tokens, shouldCheckBlacklist, currentTokenBalances }) {
+    const accountState = await this.getNewAccountState({
+      tokens,
+      currentTokenBalances: currentTokenBalances || derivedData.currentAccountState?.tokenBalances,
+      ourWalletAddress: derivedData.ourWalletAddress,
+    })
+
+    const eip7702Delegation = await getCurrentEIP7702Delegation({
+      server: this.server,
+      address: derivedData.ourWalletAddress,
+      eip7702Supported: this.eip7702Supported,
+      currentDelegation: derivedData.currentAccountState?.eip7702Delegation,
+      logger: this.logger,
+    })
+
+    const isBlacklisted = shouldCheckBlacklist
+      ? await getCurrentBlackListStatus({
+          getBlackListStatus: this.getBlackListStatus,
+          address: derivedData.ourWalletAddress,
+          currentIsBlacklisted: derivedData.currentAccountState?.isBlacklisted,
+          logger: this.logger,
+        })
+      : undefined
+
+    return { accountState, eip7702Delegation, isBlacklisted }
+  }
+
+  /**
+   * Apply tx history and `accountInfo` first, then merge `getStateUpdate` (empty RPC snapshot)
+   * and persist — opposite order from {@link ClarityMonitor#tick} on master.
+   */
+  async tick({ walletAccount, refresh }) {
+    await this.subscribeWalletAddresses()
+    const tickCount = this.tickCount[walletAccount]
+    const shouldCheckBlacklist = tickCount === 0
+
+    const assets = await this.aci.getAssetsForNetwork({ baseAssetName: this.asset.name })
+    const tokens = Object.values(assets).filter((asset) => asset.baseAsset.name !== asset.name)
+    const tokensByAddress = tokens.reduce((map, token) => {
+      const addresses = getAssetAddresses(token)
+      for (const address of addresses) map.set(address.toLowerCase(), token)
+      return map
+    }, new Map())
+    const assetName = this.asset.name
+    const derivedData = await this.deriveData({ assetName, walletAccount, tokens })
+    const batch = this.aci.createOperationsBatch()
+    let allTxs = []
+    let hasNewTxs = false
+    let historyError
+    let balanceFromAccountInfo = Object.create(null)
+    let clarityCursor
+
+    try {
+      const response = await this.getHistoryFromServer({ walletAccount, derivedData, refresh })
+
+      ;({ allTxs } = await normalizeTransactionsResponse({
+        asset: this.asset,
+        fromAddress: derivedData.ourWalletAddress,
+        response,
+        walletAccount,
+      }))
+
+      hasNewTxs = allTxs.length > 0
+
+      const logItemsByAsset = this.getAllLogItemsByAsset({
+        getLogItemsFromServerTx,
+        ourWalletAddress: derivedData.ourWalletAddress,
+        allTransactionsFromServer: allTxs,
+        asset: this.asset,
+        tokensByAddress,
+        assets,
+      })
+
+      const { txsToRemove } = await this.checkPendingTransactions({
+        txlist: allTxs,
+        walletAccount,
+        refresh,
+        logItemsByAsset,
+        asset: this.asset,
+        ...derivedData,
+      })
+
+      this.aci.removeTxLogBatch({
+        assetName,
+        walletAccount,
+        txs: txsToRemove,
+        batch,
+      })
+
+      for (const [an, txs] of Object.entries(logItemsByAsset)) {
+        this.aci.updateTxLogAndNotifyBatch({
+          assetName: an,
+          walletAccount,
+          txs,
+          refresh,
+          batch,
+        })
+      }
+
+      balanceFromAccountInfo = extractBalanceFromClarityAccountInfo({
+        accountInfo: response.accountInfo,
+        asset: this.asset,
+        tokensByAddress,
+      })
+      clarityCursor = response.cursor
+    } catch (error) {
+      historyError = error
+    }
+
+    const currentTokenBalances = {
+      ...derivedData.currentAccountState?.tokenBalances,
+      ...balanceFromAccountInfo.tokenBalances,
+    }
+
+    const { accountState, eip7702Delegation, isBlacklisted } = await this.getStateUpdate({
+      derivedData,
+      tokens,
+      shouldCheckBlacklist,
+      currentTokenBalances,
+    })
+
+    // Pre-cursor snapshot from Clarity `accountInfo`, then RPC `accountState` (empty here) overlays.
+    const prevTokenBalances = derivedData.currentAccountState?.tokenBalances
+    const newData = {
+      ...balanceFromAccountInfo,
+      ...accountState,
+      ...(isBlacklisted !== undefined && { isBlacklisted }),
+      ...(eip7702Delegation !== undefined && { eip7702Delegation }),
+      ...(clarityCursor !== undefined && { clarityCursor }),
+    }
+
+    if (prevTokenBalances || balanceFromAccountInfo.tokenBalances || accountState.tokenBalances) {
+      newData.tokenBalances = {
+        ...prevTokenBalances,
+        ...balanceFromAccountInfo.tokenBalances,
+        ...accountState.tokenBalances,
+      }
+    }
+
+    try {
+      this.aci.updateAccountStateBatch({
+        assetName,
+        walletAccount,
+        accountState,
+        newData,
+        batch,
+      })
+
+      await this.aci.executeOperationsBatch(batch)
+    } catch (batchError) {
+      if (!historyError) throw batchError
+      this.logger.warn('error persisting account state after history failure', batchError)
+    }
+
+    if (historyError) {
+      throw historyError
+    }
+
+    if (refresh || hasNewTxs) {
+      const unknownTokenAddresses = this.getUnknownTokenAddresses({
+        transactions: allTxs,
+        tokensByAddress,
+      })
+      if (unknownTokenAddresses.length > 0) {
+        this.emit('unknown-tokens', unknownTokenAddresses)
+      }
+    }
+  }
+
+  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,
+      refresh,
+      withInput: true,
+      truncated: true,
+    })
+  }
+}

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

@@ -0,0 +1,208 @@
+# `clarity-truncated-history` monitor
+
+Extends `ClarityMonitor`. Used when Clarity only serves a **recent window** of txs and attaches pre-cursor snapshots in `accountInfo`.
+
+- Sends `truncated=true` on `getAllTransactions`.
+- Folds `accountInfo` into `accountState`.
+- Forces `rpcBalanceAssetNames = []` (no per-asset RPC `eth_getBalance` batch).
+
+Plugins opting in: `bsc-plugin`, `basemainnet-plugin`, `ethereum-plugin`.
+
+---
+
+## Flow
+
+```mermaid
+flowchart TD
+  A[Clarity HTTP<br/>GET /addresses/:addr/transactions<br/>truncated=true & cursor] --> B[response]
+  B --> B1[transactions.confirmed + .pending]
+  B --> B2[accountInfo rows<br/>rebase/special tokens only]
+  B --> B3[cursor]
+
+  B1 --> C[normalizeTransactionsResponse<br/>filter spam + stale pending]
+  C --> D[getAllLogItemsByAsset<br/>bucket per assetName]
+  D --> E[aci.updateTxLogAndNotifyBatch<br/>per asset]
+
+  B2 --> F[extractBalanceFromClarityAccountInfo<br/>balance? nonce? tokenBalances?]
+
+  E --> G[accountState]
+  F --> G
+  B3 --> G[accountState<br/>balance, nonce, tokenBalances,<br/>clarityCursor]
+
+  G --> H1[getBalances - asset.api.getBalances]
+  G --> H2[resolveNonce - tx send path]
+
+  H1 --> I1{txLog empty?}
+  I1 -- yes --> I2[accountState.balance]
+  I1 -- no --> I3{accountState<br/>balance<br/>non-zero?}
+  I3 -- yes --> I2
+  I3 -- no --> I4[walk txLog for latest<br/>balanceChange]
+
+  H2 --> J1[max - nonceFromTxLog,<br/>accountState.nonce]
+```
+
+Left-to-right: `accountInfo` only writes `accountState` for what Clarity can't derive from `walletChanges` (rebase tokens). Regular ERC-20s and ETH flow through the tx log. `getBalances` and `resolveNonce` then read `accountState` + `txLog` together.
+
+---
+
+## Example response (trimmed)
+
+Wallet `0x3F80…9164` on Ethereum. Two txs + the one real `accountInfo` row:
+
+```json
+{
+  "transactions": [
+    {
+      "blockNumber": 24190233,
+      "hash": "0x7544…35bb",
+      "from": "0xccef06b2…8136c",
+      "to": "0xfa7093cd…fa4b9",
+      "effects": [
+        {
+          "address": "0xa0b86991…0eb48",
+          "effect": "erc20",
+          "from": "0xfa7093cd…fa4b9",
+          "to": "0x3f80…9164",
+          "value": "9668069"
+        }
+      ],
+      "walletChanges": [
+        {
+          "wallet": "0x3f80…9164",
+          "type": "token",
+          "from": "0",
+          "to": "9668069",
+          "contract": "0xa0b86991…0eb48"
+        }
+      ]
+    },
+    {
+      "blockNumber": 24204497,
+      "hash": "0xb5fa…5b23",
+      "from": "0x3f80…9164",
+      "to": "0x2a8e…5e86",
+      "nonce": "0",
+      "effects": [
+        {
+          "address": "0x2a8e…5e86",
+          "effect": "erc20",
+          "from": "0x3f80…9164",
+          "to": "0xcbad…4853",
+          "value": "10000000000000000000"
+        }
+      ],
+      "walletChanges": [
+        {
+          "wallet": "0x3f80…9164",
+          "type": "balance",
+          "from": "254470008324222",
+          "to": "101067364839680"
+        },
+        { "wallet": "0x3f80…9164", "type": "nonce", "from": "0", "to": "1" }
+      ]
+    }
+  ],
+  "cursor": 24211168,
+  "accountInfo": [
+    {
+      "type": "token",
+      "balanceType": "account_balance",
+      "value": "20191469428776270391810",
+      "blockNumber": 24933420,
+      "assetId": "0x2a8e…5e86",
+      "assetName": "ousd_ethereum_48fcf72d",
+      "decimals": 18
+    }
+  ]
+}
+```
+
+- **Tx A** — incoming USDC (9.668069). Balance derivable from `walletChanges`.
+- **Tx B** — first outgoing OUSD send, nonce `0 → 1`, ETH balance delta.
+- **`accountInfo`** — OUSD rebase balance ≈ **20,191.469 OUSD**, authoritative.
+
+---
+
+## `accountState` after this tick
+
+```js
+{
+  clarityCursor: <Buffer LE 24211168>,
+  tokenBalances: {
+    ousd_ethereum_48fcf72d: NumberUnit('20191.469… OUSD'),   // from accountInfo
+  },
+  balance: ZERO,   // unchanged by monitor; derived live by getBalances
+  nonce:   0,      // unchanged by monitor; derived live by resolveNonce
+}
+```
+
+`accountInfo` **only** wrote `tokenBalances.ousd_...` here — no `type: 'balance'` or `type: 'nonce'` rows were sent. Everything else is derived at read time from the tx log.
+
+---
+
+## Read paths
+
+### `getBalances`
+
+```js
+asset                              branch taken                    result
+ethereum (ETH)                     walk txLog → latest             43_326_434_520_430 wei
+                                   balanceChange.to
+usdc                               walk txLog → latest             95_948_474_200 base
+                                   walletChange.to
+ousd_ethereum_48fcf72d             accountState short-circuit      20_191_469_428_… base
+                                   (non-zero tokenBalances)        (from accountInfo)
+```
+
+Source: `getAbsoluteBalance` in `src/get-balances.js`, ordered branches:
+
+1. `txLog.size === 0` → `getBalanceFromAccountState`
+2. `accountState` non-zero → return it (`getBalanceFromAccountStateIfAny` skips default `ZERO` via `NumberUnit.isZero` getter)
+3. Walk reversed `txLog` for canonical `balanceChange` tx
+
+### `resolveNonce` (`src/tx-send/nonce-utils.js`)
+
+```js
+nonce = Math.max(
+  nonceFromTxLog, // latest canonical `type: 'nonce'` walletChange
+  accountState.nonce || 0 // populated from accountInfo row if sent
+)
+```
+
+`accountInfo` `nonce` row patches the gap when truncation hides the latest `nonceChange`.
+
+---
+
+## Monitor + server wiring
+
+```js
+// create-asset-utils.js
+case 'clarity-truncated-history':
+  monitor = new ClarityTruncatedHistoryMonitor({ server, ...args })  // server is ClarityServerV2
+
+// exodus-eth-server/index.js — no new server class
+case 'clarity-v2':
+case 'clarity-truncated-history':  // normalized to clarity-v2
+  return new ClarityServerV2(...)
+```
+
+---
+
+## Backend contract
+
+1. Accept `?truncated=true` on `GET /addresses/:addr/transactions`.
+2. Attach `accountInfo: []` (or omit) when nothing to snapshot.
+3. Emit `accountInfo` **only** for assets that can't be derived from `walletChanges` (rebase / `balanceType: 'account_balance'`).
+4. Row shapes: `{ type: 'balance' | 'nonce' | 'token', value, blockNumber, assetId?, assetName?, decimals? }`. Sorted client-side by `blockNumber` desc; first value per type/assetId wins.
+5. Unknown `assetId` → client drops the row.
+
+If the backend can't emit `accountInfo`, the monitor degrades gracefully to `clarity-v2` behavior (tx-log walk only).
+
+---
+
+## Tests
+
+- `src/tx-log/__tests__/clarity-truncated-history-monitor.test.js` — `truncated: true`, no RPC balance batch, accountInfo → `tokenBalances`.
+- `src/__tests__/create-asset-utils.test.js` — factory → `ClarityTruncatedHistoryMonitor`.
+- `src/__tests__/get-balances.test.js` — accountState short-circuit (truncated history cases).
+- `src/__tests__/balances-model.test.js` — default-ZERO accountState still falls through (regression for `NumberUnit.isZero` getter).

package/src/tx-log/index.js

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

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

@@ -0,0 +1,62 @@
+/**
+ * Maps Clarity `accountInfo` rows (GET .../transactions?truncated=true) into fields aligned
+ * with Ethereum-like account state: `balance`, `tokenBalances`, `nonce` (plus base units
+ * for amounts via `currency.baseUnit`).
+ * Rows are applied newest-first by `blockNumber` so duplicate types resolve like
+ * walletChanges-derived snapshots.
+ */
+export const extractBalanceFromClarityAccountInfo = ({ accountInfo, asset, tokensByAddress }) => {
+  if (!accountInfo || accountInfo.length === 0) return {}
+
+  const sorted = [...accountInfo].sort((a, b) => (b.blockNumber || 0) - (a.blockNumber || 0))
+
+  const result = {}
+  let haveBalance = false
+  let haveNonce = false
+  const seenAssetIds = new Set()
+  const tokenBalances = Object.create(null)
+
+  for (const row of sorted) {
+    switch (row.type) {
+      case 'balance':
+        if (!haveBalance && row.value != null) {
+          result.balance = asset.currency.baseUnit(row.value)
+          haveBalance = true
+        }
+
+        break
+
+      case 'nonce': {
+        if (haveNonce) break
+        const nonce = Number(row.value)
+
+        if (Number.isFinite(nonce) && nonce >= 0) {
+          result.nonce = nonce
+          haveNonce = true
+        }
+
+        break
+      }
+
+      case 'token': {
+        const assetId = row.assetId?.toLowerCase()
+
+        if (!assetId || seenAssetIds.has(assetId) || row.value == null) break
+        const token = tokensByAddress.get(assetId)
+        if (!token) break
+        tokenBalances[token.name] = token.currency.baseUnit(row.value)
+        seenAssetIds.add(assetId)
+        break
+      }
+
+      default:
+        break
+    }
+  }
+
+  if (Object.keys(tokenBalances).length > 0) {
+    result.tokenBalances = tokenBalances
+  }
+
+  return result
+}

package/src/tx-log/monitor-utils/index.js

@@ -8,4 +8,5 @@ export { default as getDeriveTransactionsToCheck } from './get-derive-transactio
 export { default as getCurrentEIP7702Delegation } from './get-current-eip7702-delegation.js'
 export { default as getCurrentBlackListStatus } from './get-current-blacklist-status.js'
 export { default as verifyRpcPendingTxStatusBatch } from './verify-pending-tx-status-rpc.js'
+export { extractBalanceFromClarityAccountInfo } from './extract-balance-from-clarity-account-info.js'
 export * from './exclude-unchanged-token-balances.js'

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

@@ -16,6 +16,7 @@ export const resolveNonce = async ({
   forceFromNode,
   fromAddress,
   txLog = [],
+  accountState,
   tag = BLOCK_TAG_LATEST,
   useAbsoluteNonce,
 }) => {
@@ -25,7 +26,13 @@ export const resolveNonce = async ({
     return getNonce({ asset: asset.baseAsset, address: fromAddress, tag })
   }
 
-  return getNonceFromTxLog({ txLog, useAbsoluteNonce, tag })
+  const nonceFromTxLog = getNonceFromTxLog({ txLog, useAbsoluteNonce, tag })
+
+  // Fallback to accountState nonce when txLog has no nonce info (truncated history).
+  // accountState.nonce is populated from Clarity accountInfo during monitor ticks.
+  const nonceFromAccountState = accountState?.nonce || 0
+
+  return Math.max(nonceFromTxLog, nonceFromAccountState)
 }
 
 const getLatestTxWithNonceChange = ({ reversedTxLog }) => {