@exodus/ethereum-api 9.0.0-alpha.2 → 9.0.0

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

@@ -0,0 +1,219 @@
+# `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`, including truncated-history baselines.
+- 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/>account_balance or truncated baseline]
+  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? tokenBalances?<br/>truncatedAccountState?]
+
+  E --> G[accountState]
+  F --> G
+  B3 --> G[accountState<br/>balance, tokenBalances,<br/>truncatedAccountState,<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 + token account balance --> I2
+  I3 -- no / native --> I4[walk txLog<br/>use truncated baseline only when no balanceChange exists]
+
+  H2 --> J1[max - nonceFromTxLog,<br/>accountState.nonce]
+```
+
+Left-to-right: `accountInfo` can write native balance baselines, authoritative token balances, and truncated baselines to `accountState`. Native ETH still prioritizes tx history when history exists. Rows with `source: 'account_balance'` go into `balance`/`tokenBalances`; rows with `source: 'truncated'` go into `truncatedAccountState`.
+
+---
+
+## 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",
+      "source": "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'),   // account_balance row
+  },
+  truncatedAccountState: {
+    balance: ZERO,
+    tokenBalances: {},
+  },
+  balance: ZERO,   // no native balance row in this response
+  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
+                                   (account_balance row)           (from accountInfo)
+```
+
+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.
+4. Walk reversed `txLog` for canonical `balanceChange` tx.
+5. If no absolute balance exists, fall back to the txLog-derived balance path.
+
+### `resolveNonce` (`src/tx-send/nonce-utils.js`)
+
+```js
+nonce = Math.max(
+  nonceFromTxLog, // latest canonical `type: 'nonce'` walletChange
+  accountState.nonce || 0 // any `accountInfo` `type: 'nonce'` row, regardless of source
+)
+```
+
+Both `account_balance` and `truncated` source nonce rows collapse into `accountState.nonce`
+(the max wins) — they represent the same chain-known nonce, just at different observation
+points. `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 `source: 'account_balance'` rows for current account/token balances. These may appear on every fetch.
+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.
+
+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 → `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.
+- `src/__tests__/balances-model.test.js` — default-ZERO accountState still falls through (regression for `NumberUnit.isZero` getter).

package/src/tx-log/clarity-utils/absolute.js

@@ -0,0 +1,96 @@
+import assert from 'minimalistic-assert'
+import ms from 'ms'
+
+const DEFAULT_CANONICAL_ABSOLUTE_TX_SEARCH_DEPTH = ms('5m')
+
+const ABSOLUTE_FIELD_NAME_BALANCE_CHANGE = 'balanceChange'
+const ABSOLUTE_FIELD_NAME_NONCE_CHANGE = 'nonceChange'
+
+const ABSOLUTE_BALANCE_FIELDS = new Set([
+  ABSOLUTE_FIELD_NAME_BALANCE_CHANGE,
+  ABSOLUTE_FIELD_NAME_NONCE_CHANGE,
+])
+
+// Defines whether a `Tx` is an absolute balance
+// node that can be sorted in terms of transaction
+// ordering.
+//
+const isCanonicalAbsoluteTx = (tx, fieldName) => {
+  assert(ABSOLUTE_BALANCE_FIELDS.has(fieldName), `unsupported fieldName, "${fieldName}"`)
+
+  return Boolean(
+    tx?.data?.[fieldName] &&
+    typeof tx.data.blockNumber === 'number' &&
+    typeof tx.data.transactionIndex === 'number'
+  )
+}
+
+export const isCanonicalAbsoluteBalanceTx = (tx) =>
+  isCanonicalAbsoluteTx(tx, ABSOLUTE_FIELD_NAME_BALANCE_CHANGE)
+export const isCanonicalAbsoluteNonceTx = (tx) =>
+  isCanonicalAbsoluteTx(tx, ABSOLUTE_FIELD_NAME_NONCE_CHANGE)
+
+// Attempts to find the most recent absolute Tx for a given
+// `txLog`.
+//
+// NOTE: Returns `null` if nothing is found.
+// NOTE: Uses `tx.data.blockNumber` and `tx.data.transactionIndex`,
+//       which are not guaranteed to exist in older transaction
+//       histories.
+const getLatestCanonicalAbsoluteTx = ({
+  // Due to nondeterministic sorting for records in close
+  // proximity to one-another on high TPS chains, the
+  // order of the `reversedTxLog` cannot be trusted to be
+  // exactly precise since two consecutive blocks may share
+  // the same timestamp. Therefore, when finding an absolute
+  // balance node, we use the`searchDepthMs` to take into
+  // account extra nodes chronologically deeper than what we
+  // presume to be the latest to make sure we resolve to the
+  // correct node.
+  searchDepthMs = DEFAULT_CANONICAL_ABSOLUTE_TX_SEARCH_DEPTH,
+  reversedTxLog,
+  fieldName,
+  deadline = Infinity,
+}) => {
+  assert(reversedTxLog, 'expected reversedTxLog')
+
+  let latest = null
+
+  for (const tx of reversedTxLog) {
+    if (+tx.date > deadline) continue
+
+    if (latest) {
+      const diff = +latest.date - +tx.date
+
+      if (diff >= searchDepthMs) break
+    }
+
+    if (!isCanonicalAbsoluteTx(tx, fieldName)) continue
+
+    if (
+      !latest ||
+      tx.data.blockNumber > latest.data.blockNumber ||
+      (tx.data.blockNumber === latest.data.blockNumber &&
+        tx.data.transactionIndex > latest.data.transactionIndex)
+    ) {
+      latest = tx
+    }
+  }
+
+  return latest
+}
+
+export const getLatestCanonicalAbsoluteBalanceTx = ({ searchDepthMs, reversedTxLog, deadline }) =>
+  getLatestCanonicalAbsoluteTx({
+    searchDepthMs,
+    reversedTxLog,
+    deadline,
+    fieldName: ABSOLUTE_FIELD_NAME_BALANCE_CHANGE,
+  })
+
+export const getLatestCanonicalAbsoluteNonceTx = ({ searchDepthMs, reversedTxLog }) =>
+  getLatestCanonicalAbsoluteTx({
+    searchDepthMs,
+    reversedTxLog,
+    fieldName: ABSOLUTE_FIELD_NAME_NONCE_CHANGE,
+  })

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

@@ -1,15 +1,37 @@
-import getValueOfTransfers from '../monitor-utils/get-value-of-transfers'
-import getTransfersByTokenName from '../monitor-utils/get-transfers-by-token-name'
-import getFeeAmount from '../monitor-utils/get-fee-amount'
-import isConsideredSentTokenTx from '../monitor-utils/is-considered-sent-token-tx'
-import isConfirmedServerTx from '../monitor-utils/is-confirmed-server-tx'
-import getNamesOfTokensTransferredByServerTx from './get-names-of-tokens-transferred-by-server-tx'
-import filterEffects from './filter-effects'
 import lodash from 'lodash'
 
-// This function takes a server transaction object fetched from magnifier,
+import { getWalletUpdates } from '../monitor-utils/get-balance-updates.js'
+import getFeeAmount from '../monitor-utils/get-fee-amount.js'
+import getRawTransferAmount from '../monitor-utils/get-raw-transfer-amount.js'
+import getTransfersByTokenName from '../monitor-utils/get-transfers-by-token-name.js'
+import getValueOfTransfers from '../monitor-utils/get-value-of-transfers.js'
+import isConfirmedServerTx from '../monitor-utils/is-confirmed-server-tx.js'
+import isConsideredSentTokenTx from '../monitor-utils/is-considered-sent-token-tx.js'
+import filterEffects from './filter-effects.js'
+import getNamesOfTokensTransferredByServerTx from './get-names-of-tokens-transferred-by-server-tx.js'
+
+const isFiniteInteger = (n) => Number.isFinite(n) && Number.isInteger(n)
+
+// This function takes a server transaction object fetched from clarity,
 // and transforms it into Tx models to update the exodus state.
 
+const tryFindExternalRecipient = (transfers, ourWalletAddress) =>
+  transfers.find(({ to }) => to !== ourWalletAddress)?.to || ourWalletAddress
+
+// If the timestamp is in the future, use the current time.
+const parseServerTxDate = (timestamp) => new Date(Math.min(Date.now(), parseInt(timestamp, 16)))
+
+function isSelfSendTx({
+  coinAmount,
+  ourWalletWasSender,
+  sendingTransferPresent,
+  receivingTransferPresent,
+}) {
+  return (
+    coinAmount.isZero && sendingTransferPresent && receivingTransferPresent && ourWalletWasSender
+  )
+}
+
 export default function getLogItemsFromServerTx({
   serverTx,
   asset,
@@ -22,6 +44,8 @@ export default function getLogItemsFromServerTx({
   const txId = serverTx.hash
   const nonce = parseInt(serverTx.nonce, 10)
   const gasLimit = parseInt(serverTx.gas, 10)
+  const blockNumber = serverTx.blockNumber
+  const transactionIndex = parseInt(serverTx.transactionIndex, 10)
   const error = serverTx.error || (serverTx.status === '0' ? 'Failed' : null)
   const feeAmount = getFeeAmount(asset, serverTx)
   const internalTransfers = filterEffects(serverTx.effects, 'internal') || []
@@ -34,6 +58,9 @@ export default function getLogItemsFromServerTx({
   const methodId = serverTx.input && {
     methodId: serverTx.input.slice(0, Math.max(0, METHOD_ID_LENGTH)),
   }
+  const data = (ourWalletWasSender ? serverTx.input : methodId?.methodId) || '0x'
+  const walletUpdates = getWalletUpdates(ourWalletAddress, serverTx.walletChanges || [])
+  const { baseBalanceUpdate, nonceUpdate, tokenBalancesUpdate } = walletUpdates
 
   const logItemCommonProperties = {
     confirmations,
@@ -49,14 +76,41 @@ export default function getLogItemsFromServerTx({
     const sendingTransferPresent = ethereumTransfers.some(({ from }) => from === ourWalletAddress)
     const receivingTransferPresent = ethereumTransfers.some(({ to }) => to === ourWalletAddress)
 
-    if (sendingTransferPresent || receivingTransferPresent) {
+    const shouldAttachTx =
+      sendingTransferPresent || receivingTransferPresent || baseBalanceUpdate || nonceUpdate // need to also include if there's a base balance change
+
+    if (shouldAttachTx) {
       const coinAmount = getValueOfTransfers(ourWalletAddress, asset, ethereumTransfers)
+      // `rawCoinAmount` mirrors the field written by `getOptimisticTxLogEffects`
+      // and is consumed by the bump path (`tx-create.js`) to recover the
+      // user-signed on-chain `value` when accelerating a self-send (where
+      // `coinAmount` is zero). For the base-asset entry the raw amount is the
+      // top-level `value` field of the tx itself, not the sum of internal
+      // transfers — that's what the user signed and what we must restore on
+      // bump.
+      const rawCoinAmount = getRawTransferAmount({
+        ourWalletAddress,
+        asset,
+        transfers: [serverTx],
+      }).toBaseString()
       const selfSend = isSelfSendTx({
         coinAmount,
         ourWalletWasSender,
         sendingTransferPresent,
         receivingTransferPresent,
       })
+      let sent
+      if (sendingTransferPresent) {
+        sent = internalTransfers
+          .map(({ from, to, value }) => {
+            if (from === ourWalletAddress) {
+              const amount = asset.currency.baseUnit(value).toDefaultString({ unit: true })
+              return { address: to, amount }
+            }
+          })
+          .filter(Boolean)
+      }
+
       logItemsForServerTxEntries.push([
         asset.name,
         {
@@ -64,10 +118,16 @@ export default function getLogItemsFromServerTx({
           coinAmount,
           coinName: asset.name,
           data: {
-            data: serverTx.input || '0x',
+            data,
             nonce,
             gasLimit,
+            rawCoinAmount,
+            balanceChange: baseBalanceUpdate,
+            nonceChange: nonceUpdate,
             ...methodId,
+            ...(sent?.length > 0 ? { sent } : undefined),
+            ...(isFiniteInteger(blockNumber) ? { blockNumber } : null),
+            ...(isFiniteInteger(transactionIndex) ? { transactionIndex } : null),
           },
           ...(ourWalletWasSender
             ? { from: [], to: toAddress, feeAmount, feeCoinName: asset.feeAsset.name }
@@ -94,12 +154,23 @@ export default function getLogItemsFromServerTx({
   Object.entries(tokenTransfersByTokenName).forEach(([tokenName, tokenTransfers]) => {
     const sendingTransferPresent = tokenTransfers.some(({ from }) => from === ourWalletAddress)
     const receivingTransferPresent = tokenTransfers.some(({ to }) => to === ourWalletAddress)
-    if (!sendingTransferPresent && !receivingTransferPresent) return
-
     const token = assets[tokenName]
-    const tokenTransferToAddress = tryFindExternalRecipient(tokenTransfers, ourWalletAddress)
+    const tokenAddress = token.addresses.current.toLowerCase()
+    const balanceChange = tokenBalancesUpdate[tokenAddress]
+
+    if (!sendingTransferPresent && !receivingTransferPresent && !balanceChange) return
 
+    const tokenTransferToAddress = tryFindExternalRecipient(tokenTransfers, ourWalletAddress)
     const coinAmount = getValueOfTransfers(ourWalletAddress, token, tokenTransfers)
+    // See base-entry comment above; for token entries the raw amount is the
+    // absolute total tokens our wallet moved in this tx (sum of outgoing, or
+    // incoming for receive-only entries).
+    const rawCoinAmount = getRawTransferAmount({
+      ourWalletAddress,
+      asset: token,
+      transfers: tokenTransfers,
+    }).toBaseString()
+
     const tokenFromAddresses = lodash.uniq(
       tokenTransfers.filter(({ to }) => to === ourWalletAddress).map(({ from }) => from)
     )
@@ -123,7 +194,16 @@ export default function getLogItemsFromServerTx({
         ...logItemCommonProperties,
         coinAmount,
         coinName: tokenName,
-        data: { nonce, gasLimit },
+        data: {
+          data,
+          nonce,
+          gasLimit,
+          rawCoinAmount,
+          balanceChange,
+          ...methodId,
+          ...(isFiniteInteger(blockNumber) ? { blockNumber } : null),
+          ...(isFiniteInteger(transactionIndex) ? { transactionIndex } : null),
+        },
         ...(isConsideredSent
           ? { from: [], to: tokenTransferToAddress, feeAmount, feeCoinName: token.feeAsset.name }
           : { from: tokenFromAddresses }),
@@ -138,20 +218,3 @@ export default function getLogItemsFromServerTx({
 
   return Object.fromEntries(logItemsForServerTxEntries)
 }
-
-const tryFindExternalRecipient = (transfers, ourWalletAddress) =>
-  transfers.find(({ to }) => to !== ourWalletAddress)?.to || ourWalletAddress
-
-// If the timestamp is in the future, use the current time.
-const parseServerTxDate = (timestamp) => new Date(Math.min(Date.now(), parseInt(timestamp, 16)))
-
-function isSelfSendTx({
-  coinAmount,
-  ourWalletWasSender,
-  sendingTransferPresent,
-  receivingTransferPresent,
-}) {
-  return (
-    coinAmount.isZero && sendingTransferPresent && receivingTransferPresent && ourWalletWasSender
-  )
-}

package/src/tx-log/clarity-utils/get-names-of-tokens-transferred-by-server-tx.js

@@ -1,6 +1,7 @@
-import lodash from 'lodash'
-import getValueOfTransfers from '../monitor-utils/get-value-of-transfers'
 import { FEE_PAYMENT_PREFIX } from '@exodus/ethereum-lib'
+import lodash from 'lodash'
+
+import getValueOfTransfers from '../monitor-utils/get-value-of-transfers.js'
 
 // For ETH transactions, we store an array of token names inside
 // the TX model. This array is used to display text in the UI for

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

@@ -1,3 +1,9 @@
-export { default as getDeriveDataNeededForTick } from './get-derive-data-needed-for-tick'
-export { default as getLogItemsFromServerTx } from './get-log-items-from-server-tx'
-export { default as filterEffects } from './filter-effects'
+export { default as getLogItemsFromServerTx } from './get-log-items-from-server-tx.js'
+export { default as filterEffects } from './filter-effects.js'
+export {
+  isCanonicalAbsoluteBalanceTx,
+  isCanonicalAbsoluteNonceTx,
+  getLatestCanonicalAbsoluteBalanceTx,
+  getLatestCanonicalAbsoluteNonceTx,
+} from './absolute.js'
+export { normalizeTransactionsResponse } from './normalize-transactions-response.js'

package/src/tx-log/clarity-utils/is-spam-pending-tx.js

@@ -0,0 +1,13 @@
+export const isPendingClarityTx = (tx) => tx?.blockNumber == null
+
+const isSpamNote = (note) => {
+  if (!note || typeof note !== 'object') return false
+  if (typeof note.type !== 'string') return false
+  return note.type.toLowerCase() === 'spam'
+}
+
+export const isSpamPendingTx = (tx) => {
+  if (!isPendingClarityTx(tx)) return false
+  if (!Array.isArray(tx?.transactionNotes)) return false
+  return tx.transactionNotes.some((note) => isSpamNote(note))
+}

package/src/tx-log/clarity-utils/normalize-transactions-response.js

@@ -0,0 +1,65 @@
+import assert from 'minimalistic-assert'
+
+import { isPendingClarityTx, isSpamPendingTx } from './is-spam-pending-tx.js'
+
+// Converts the `pending` and `confirmed` transactions returned
+// by Clarity into a single contiguous array of transactions.
+//
+// Since it is possible for Clarity to return very old pending
+// transactions that our own RPC has forgotten (see `--txpool.lifetime`),
+// we ensure that all transactions we expose to the consumer have
+// `nonce`s do not exceed the maximum pending nonce that's currently
+// maintained at the RPC.
+//
+// This avoids the "future transaction replaces pending" error.
+export const normalizeTransactionsResponse = async ({
+  asset,
+  fromAddress,
+  response,
+  walletAccount,
+}) => {
+  assert(asset, 'expected asset')
+  assert(fromAddress, 'expected fromAddress')
+  assert(response, 'expected response')
+  assert(walletAccount, 'expected walletAccount')
+
+  const { baseAsset } = asset
+
+  // NOTE: We query the current pending `nonce` from the RPC
+  //       to sanity check the contents of the `txLog`.
+  const pendingNonce = await baseAsset
+    .getNonce({
+      asset: baseAsset,
+      fromAddress,
+      walletAccount,
+      forceFromNode: true,
+    })
+    .catch(() => null)
+
+  const allTxs = [...response.transactions.pending, ...response.transactions.confirmed].filter(
+    (tx) => {
+      // Pending spam transactions should not enter txlog state at all.
+      if (isSpamPendingTx(tx)) return false
+
+      // If the transaction isn't one we've sent, then ignore.
+      if (tx.from?.toLowerCase() !== fromAddress.toLowerCase()) return true
+
+      const nonce = parseInt(tx.nonce, 10)
+      if (!Number.isFinite(nonce) || !Number.isInteger(nonce)) return false
+
+      // HACK: If we were unable to determine the `pendingNonce`, then
+      //       allow send transactions through by default without
+      //       further validation.
+      // NOTE: If the transaction is already confirmed, ignore RPC pending
+      //       state comparison check since the RPC might be out-of-sync.
+      if (pendingNonce === null || !isPendingClarityTx(tx)) return true
+
+      // NOTE: If the pending `tx` has a nonce that's greater than
+      //       what's considered pending at the RPC, it is no longer
+      //       viable and should be replaced.
+      return nonce < pendingNonce
+    }
+  )
+
+  return { allTxs }
+}