@exodus/ethereum-api 8.76.7 → 8.77.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.
 
+## [8.77.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.76.7...@exodus/ethereum-api@8.77.0) (2026-06-29)
+
+
+### Features
+
+* **ethereum:** implement getHistoricalBalance via clarity absolute balance ([#8281](https://github.com/ExodusMovement/assets/issues/8281)) ([be202a9](https://github.com/ExodusMovement/assets/commit/be202a94d9734d7af8ed118d11d4cc38c3b5ef10))
+
+
+
 ## [8.76.7](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.76.6...@exodus/ethereum-api@8.76.7) (2026-06-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "8.76.7",
+  "version": "8.77.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",
@@ -69,5 +69,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "c704777d72888bf3a94f3a7ddc1b0e57cda3e6dc"
+  "gitHead": "f156b9209a42ef331625b508a908659fd495c3e4"
 }

package/src/create-asset.js

@@ -41,6 +41,7 @@ import { createFeeData } from './fee-data/index.js'
 import { createGetBalanceForAddress } from './get-balance-for-address.js'
 import { getBalancesFactory } from './get-balances.js'
 import { getFeeFactory } from './get-fee.js'
+import { getHistoricalBalanceFactory } from './get-historical-balance.js'
 import { moveFundsFactory } from './move-funds.js'
 import { estimateL1DataFeeFactory, getL1GetFeeFactory } from './optimism-gas/index.js'
 import { createSendValidations } from './send-validations.js'
@@ -177,12 +178,20 @@ export const createAssetFactory = ({
       rpcBalanceAssetNames,
     })
 
+    const historicalBalanceSupported = monitorType !== 'no-history'
+    const getHistoricalBalance = getHistoricalBalanceFactory({
+      assetClientInterface,
+      getBalances,
+    })
+
     const { createToken, getTokens } = createTokenFactory(
       {
         address,
         bip44,
         keys,
         getBalances,
+        getHistoricalBalance,
+        historicalBalance: historicalBalanceSupported,
         assetClientInterface,
         server,
         stakingConfiguration,
@@ -225,6 +234,7 @@ export const createAssetFactory = ({
       family: ASSET_FAMILY.EVM,
       feeMonitor: true,
       feesApi: true,
+      historicalBalance: historicalBalanceSupported,
       isMaxFeeAsset,
       isTestnet,
       moveFunds: true,
@@ -336,6 +346,7 @@ export const createAssetFactory = ({
       features,
       getActivityTxs,
       getBalances,
+      ...(features.historicalBalance && { getHistoricalBalance }),
       getBalanceForAddress: createGetBalanceForAddress({ asset, server }),
       ...(getBlackListStatus && { getBlackListStatus }),
       getConfirmationsNumber: () => confirmationsNumber,

package/src/create-token-factory.js

@@ -37,6 +37,8 @@ const getActivityTxs = ({ txs }) => txs.filter((tx) => !smallbalanceTx(tx))
 const getCreateBaseToken =
   ({
     getBalances,
+    getHistoricalBalance,
+    historicalBalance,
     assetClientInterface,
     server,
     stakingConfiguration = Object.create(null),
@@ -53,6 +55,7 @@ const getCreateBaseToken =
       features: tokenFeatures,
       hasFeature: (feature) => !!tokenFeatures[feature], // @deprecated use api.features instead
       getBalances,
+      ...(historicalBalance && { getHistoricalBalance }),
       getTxLogFilter: name === 'polygon' ? getPolygonTxLogFilter : getTxLogFilter,
     }
 

package/src/get-historical-balance.js

@@ -0,0 +1,58 @@
+import { TxSet } from '@exodus/models'
+import assert from 'minimalistic-assert'
+
+import { getLatestCanonicalAbsoluteBalanceTx } from './tx-log/clarity-utils/index.js'
+
+const walkBackFromBalance = ({ txLog, deadline, balance }) => {
+  let result = balance
+
+  for (const tx of txLog) {
+    if (new Date(tx.date).getTime() <= deadline) continue
+    if (tx.failed || tx.dropped || tx.pending || tx.data?.replacedBy) continue
+
+    result = result.sub(tx.coinAmount)
+    if (tx.feeAmount?.unitType.equals(tx.coinAmount.unitType)) {
+      result = result.add(tx.feeAmount)
+    }
+  }
+
+  return result.clampLowerZero()
+}
+
+/**
+ * Builds the Ethereum-like balance as of `date`. Anchors on the latest Clarity
+ * absolute-balance snapshot at or before the date, falling back to a walk-back
+ * from the current balance when no snapshot is available.
+ */
+export const getHistoricalBalanceFactory = ({ assetClientInterface, getBalances }) => {
+  assert(assetClientInterface, 'assetClientInterface is required')
+  assert(getBalances, 'getBalances is required')
+
+  return async ({ asset, walletAccount, date }) => {
+    assert(asset, 'asset is required')
+    assert(walletAccount, 'walletAccount is required')
+    assert(date instanceof Date, 'date is required')
+
+    const txLog = await assetClientInterface.getTxLog({ assetName: asset.name, walletAccount })
+    const deadline = date.getTime()
+    const anchor = getLatestCanonicalAbsoluteBalanceTx({ reversedTxLog: txLog.reverse(), deadline })
+
+    if (anchor) {
+      const total = asset.currency.baseUnit(anchor.data.balanceChange.to)
+      return { total, entries: [{ amount: total, date: deadline }] }
+    }
+
+    const accountState = await assetClientInterface.getAccountState({
+      assetName: asset.baseAsset.name,
+      walletAccount,
+    })
+    const confirmedTxLog = TxSet.fromArray([...txLog].filter((tx) => !tx.pending))
+    const balance = getBalances({ asset, accountState, txLog: confirmedTxLog }).spendable
+    const total = walkBackFromBalance({ txLog: confirmedTxLog, deadline, balance })
+
+    return {
+      total,
+      entries: [{ amount: total, date: deadline }],
+    }
+  }
+}

package/src/index.js

@@ -38,6 +38,7 @@ export {
 } from './tx-log/index.js'
 
 export { getStakingHistoryBalance, getBalancesFactory } from './get-balances.js'
+export { getHistoricalBalanceFactory } from './get-historical-balance.js'
 
 export {
   FantomStaking,

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

@@ -50,12 +50,15 @@ const getLatestCanonicalAbsoluteTx = ({
   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
 
@@ -77,10 +80,11 @@ const getLatestCanonicalAbsoluteTx = ({
   return latest
 }
 
-export const getLatestCanonicalAbsoluteBalanceTx = ({ searchDepthMs, reversedTxLog }) =>
+export const getLatestCanonicalAbsoluteBalanceTx = ({ searchDepthMs, reversedTxLog, deadline }) =>
   getLatestCanonicalAbsoluteTx({
     searchDepthMs,
     reversedTxLog,
+    deadline,
     fieldName: ABSOLUTE_FIELD_NAME_BALANCE_CHANGE,
   })