@defisaver/positions-sdk 2.1.161-portfolio-api-1-dev → 2.1.161-portfolio-api-3-dev

package/esm/types/portfolio.d.ts

@@ -1,20 +1,47 @@
-import { AaveV2MarketData, AaveV2PositionData, AaveV3MarketData, AaveV3PositionData, AaveVersions } from './aave';
+import { AaveV2MarketData, AaveV2PositionData, AaveV3MarketData, AaveV3PositionData, AaveVersions, StakeAaveData, UmbrellaStakingData } from './aave';
 import { AaveV4AccountData, AaveV4SpokeData, AaveV4SpokesType } from './aaveV4';
+import { AaveRewardsClaimableToken, EthenaAirdropClaimableToken, KingRewardsClaimableToken, MerklRewardsClaimableToken, SparkAirdropClaimableToken, SparkRewardsClaimableToken, UniswapAirdropClaimableToken } from './claiming';
 import { EthAddress } from './common';
 import { CompoundV2MarketsData, CompoundV2PositionData, CompoundV3MarketsData, CompoundV3PositionData, CompoundVersions } from './compound';
 import { CrvUSDGlobalMarketData, CrvUSDUserData, CrvUSDVersions } from './curveUsd';
-import { FluidVaultData } from './fluid';
-import { LiquityTroveInfo } from './liquity';
-import { LiquityV2MarketData } from './liquityV2';
+import { FluidEarnPositionData, FluidMarketData, FluidVaultData } from './fluid';
+import { LiquityStakingData, LiquityTroveInfo } from './liquity';
+import { LiquityV2MarketData, LiquityV2SBoldYBoldData, LiquityV2StakingData, LiquityV2TroveData, LiquityV2Versions } from './liquityV2';
 import { LlamaLendGlobalMarketData, LlamaLendUserData, LlamaLendVersionsType } from './llamaLend';
-import { CdpData } from './maker';
-import { MorphoBlueMarketInfo, MorphoBluePositionData, MorphoBlueVersions } from './morphoBlue';
+import { CdpData, IlkInfo } from './maker';
+import { MorphoBlueEarnData, MorphoBlueMarketInfo, MorphoBluePositionData, MorphoBlueVersions } from './morphoBlue';
 import { MorphoMidnightMarketInfo, MorphoMidnightPositionData, MorphoMidnightVersions } from './morphoMidnight';
 import { SparkMarketsData, SparkPositionData, SparkVersions } from './spark';
 export interface PortfolioProtocolData<T> {
     error: string;
     data: T | null;
 }
+/** A failed fetch of a protocol that, when it succeeds, getPortfolioData returns unwrapped rather than as `{ error, data }`. */
+export interface PortfolioProtocolError {
+    error: string;
+    data: null;
+}
+/** What getPortfolioData reads besides markets. */
+export interface PortfolioDataOptions {
+    /** positions (lending); default true. With false it comes back as {} and no lending position is read. */
+    positions?: boolean;
+    /** stakingPositions; default true. With false it comes back as {} and no staking source is read. */
+    staking?: boolean;
+    /** rewardsData; default true. With false it comes back as {} and no rewards source is read. */
+    rewards?: boolean;
+    /**
+     * Liquity V2 troves in positions[address].liquityV2; default false, as the DeFi Saver app reads them on its own.
+     * Mainnet only: elsewhere liquityV2 is {}. Needs positions.
+     */
+    liquityV2?: boolean;
+}
+/** One Liquity V2 market's troves of an address, by trove id — with an error when the ids or any trove failed to load. */
+export interface PortfolioLiquityV2Troves {
+    error: string;
+    data: {
+        [troveId: string]: LiquityV2TroveData;
+    };
+}
 export interface PortfolioPositionsDataForAddress {
     aaveV3: {
         [key in AaveVersions]?: PortfolioProtocolData<AaveV3PositionData>;
@@ -56,10 +83,64 @@ export interface PortfolioPositionsDataForAddress {
     aaveV4: {
         [key in AaveV4SpokesType]?: PortfolioProtocolData<AaveV4AccountData>;
     };
+    /** Only with the liquityV2 option. Every trove the address holds, by market. */
+    liquityV2?: {
+        [key in LiquityV2Versions]?: PortfolioLiquityV2Troves;
+    };
 }
 export interface PortfolioPositionsData {
     [key: EthAddress]: PortfolioPositionsDataForAddress;
 }
+/**
+ * The staking positions getPortfolioData returns for an address. The shapes are uneven, and the DeFi Saver app
+ * parses them as they are: a protocol read once per address comes back unwrapped on success, as
+ * `{ error, data: null }` on failure, and as {} (or Fluid's `{ error: '', data: {} }`) on a network it is not read on.
+ */
+export interface PortfolioStakingPositionsDataForAddress {
+    /** stkAAVE, stkGHO and sGHO; mainnet only. */
+    aaveV3: StakeAaveData | PortfolioProtocolError | {};
+    /** Morpho Blue supply without a borrow (Earn), by market; only markets with a deposit or an error. */
+    morphoBlue: {
+        [key in MorphoBlueVersions]?: PortfolioProtocolData<MorphoBlueEarnData>;
+    };
+    compoundV3: Record<string, never>;
+    spark: Record<string, never>;
+    aaveV2: Record<string, never>;
+    compoundV2: Record<string, never>;
+    /** LQTY staking and the LUSD stability pool; mainnet only. */
+    liquity: LiquityStakingData | PortfolioProtocolError | {};
+    /** Stability pool deposits, by market; mainnet only, legacy markets left out. */
+    liquityV2: {
+        [key in LiquityV2Versions]?: PortfolioProtocolData<LiquityV2StakingData>;
+    };
+    /** Fluid lending (fToken) deposits; `{ error: '', data: {} }` on a network without Fluid. */
+    fluid: FluidEarnPositionData[] | PortfolioProtocolError | {
+        error: string;
+        data: Record<string, never>;
+    };
+    /** Umbrella stakes; absent off mainnet. */
+    umbrella?: UmbrellaStakingData | PortfolioProtocolError;
+    /** sBOLD, yBOLD and stYBOLD; data is null off mainnet. */
+    liquityV2SBoldYBold: PortfolioProtocolData<LiquityV2SBoldYBoldData>;
+}
+export type PortfolioStakingPositionsData = Record<EthAddress, PortfolioStakingPositionsDataForAddress>;
+/** The claimable rewards getPortfolioData returns for an address. Off mainnet only Merkl and Aave V3 are read. */
+export interface PortfolioRewardsDataForAddress {
+    merkl: PortfolioProtocolData<MerklRewardsClaimableToken[]>;
+    aaveV3: {
+        [key in AaveVersions]?: PortfolioProtocolData<AaveRewardsClaimableToken[]>;
+    };
+    spark: {
+        [key in SparkVersions]?: PortfolioProtocolData<SparkRewardsClaimableToken[]>;
+    };
+    /** The SPK airdrop. */
+    spk: PortfolioProtocolData<SparkAirdropClaimableToken[]>;
+    king: PortfolioProtocolData<KingRewardsClaimableToken[]>;
+    /** {} off mainnet. */
+    ethena: PortfolioProtocolData<EthenaAirdropClaimableToken[]> | {};
+    uniswap: PortfolioProtocolData<UniswapAirdropClaimableToken[]>;
+}
+export type PortfolioRewardsData = Record<EthAddress, PortfolioRewardsDataForAddress>;
 /** The `markets` getPortfolioData returns: every market it read, by protocol, keyed by market or spoke. */
 export interface PortfolioMarketsData {
     morphoMarketsData: Record<string, MorphoBlueMarketInfo>;
@@ -74,3 +155,43 @@ export interface PortfolioMarketsData {
     liquityV2MarketsData: Record<string, LiquityV2MarketData>;
     aaveV4SpokesData: Record<string, AaveV4SpokeData>;
 }
+/**
+ * The `markets` getShifterPortfolioData returns: the portfolio's markets, plus Fluid's and Maker's, which the shifter
+ * offers as destinations. Kept apart from PortfolioMarketsData, which getPortfolioData does not fill these into.
+ */
+export interface ShifterPortfolioMarketsData extends PortfolioMarketsData {
+    fluidMarketsData: Record<string, FluidMarketData>;
+    makerMarketsData: Record<string, IlkInfo>;
+}
+/** The markets that could not be read, by their key in PortfolioMarketsData, then by market or spoke: the error. */
+export type PortfolioMarketsErrors = {
+    [key in keyof PortfolioMarketsData]?: Record<string, string>;
+};
+/**
+ * What the portfolio fetch could not read and has no `{ error, data }` entry of its own to report it in. A key is
+ * present only when something under it failed; {} when everything was read.
+ */
+export interface PortfolioErrors {
+    /** Markets missing from `markets`; every position on such a market is an entry with an error. */
+    markets?: PortfolioMarketsErrors;
+    /** Addresses whose Maker vault list could not be read: their `maker` is {}, which would otherwise read as "no vaults". */
+    makerCdps?: Record<EthAddress, string>;
+}
+/** getPortfolioMarketsData's result. */
+export interface PortfolioMarketsResult {
+    /** Every market read; one that failed is missing and named in `errors`. */
+    markets: PortfolioMarketsData;
+    errors: PortfolioMarketsErrors;
+}
+/** getPortfolioUserData's result: what is read per address. */
+export interface PortfolioUserData {
+    positions: PortfolioPositionsData;
+    stakingPositions: PortfolioStakingPositionsData;
+    rewardsData: PortfolioRewardsData;
+    errors: Pick<PortfolioErrors, 'makerCdps'>;
+}
+/** getPortfolioData's result. */
+export interface PortfolioData extends Omit<PortfolioUserData, 'errors'> {
+    markets: PortfolioMarketsData;
+    errors: PortfolioErrors;
+}

package/esm/types/savings/index.d.ts

@@ -20,4 +20,12 @@ export interface SavingsVaultData {
     asset: string;
     optionType: string;
 }
-export type SavingsData = Partial<Record<MorphoVaultType | YearnVaultType | MakerDsrType | SkySavingsType | SparkSavingsVaultType | SummerVaultType | YearnV3VaultType, SavingsVaultData>>;
+/** The key of every savings vault getSavingsData reads. */
+export type SavingsVaultKey = MorphoVaultType | YearnVaultType | MakerDsrType | SkySavingsType | SparkSavingsVaultType | SummerVaultType | YearnV3VaultType;
+export type SavingsData = Partial<Record<SavingsVaultKey, SavingsVaultData>>;
+/** Why each vault that was read for a network came back without data. */
+export type SavingsErrors = Partial<Record<SavingsVaultKey, string>>;
+export interface SavingsDataWithErrors {
+    data: SavingsData;
+    errors: SavingsErrors;
+}

package/esm/types/savings/morphoVaults.d.ts

@@ -1,4 +1,4 @@
-import { EthAddress } from '../common';
+import { EthAddress, NetworkNumber } from '../common';
 export declare enum MorphoVaultType {
     MorphoVaultFlagshipEth = "morpho_vault_flagship_eth",
     MorphoVaultGauntletUSDCCore = "morpho_vault_gauntlet_usdc_core",
@@ -17,13 +17,21 @@ export declare enum MorphoVaultType {
     MorphoVaultSteakhousePYUSD = "morpho_vault_steakhouse_pyusd",
     MorphoVaultSmokehouseUSDT = "morpho_vault_smokehouse_usdt",
     MorphoVaultSmokehouseUSDC = "morpho_vault_smokehouse_usdc",
-    MorphoVaultSmokehouseDAI = "morpho_vault_smokehouse_dai"
+    MorphoVaultSmokehouseDAI = "morpho_vault_smokehouse_dai",
+    MorphoVaultGauntletUSDGPremium = "morpho_vault_gauntlet_usdg_premium",
+    MorphoVaultSteakhouseUSDGPro = "morpho_vault_steakhouse_usdg_pro"
+}
+export declare enum MorphoVaultVersion {
+    V1 = 1,
+    V2 = 2
 }
 export interface MorphoVault {
     type: MorphoVaultType;
     name: string;
     address: EthAddress;
     asset: string;
+    network: NetworkNumber;
+    version: MorphoVaultVersion;
     deploymentBlock: number;
     isLegacy: boolean;
 }

package/esm/types/savings/morphoVaults.js

@@ -20,4 +20,12 @@ export var MorphoVaultType;
     MorphoVaultType["MorphoVaultSmokehouseUSDT"] = "morpho_vault_smokehouse_usdt";
     MorphoVaultType["MorphoVaultSmokehouseUSDC"] = "morpho_vault_smokehouse_usdc";
     MorphoVaultType["MorphoVaultSmokehouseDAI"] = "morpho_vault_smokehouse_dai";
+    // Vault V2
+    MorphoVaultType["MorphoVaultGauntletUSDGPremium"] = "morpho_vault_gauntlet_usdg_premium";
+    MorphoVaultType["MorphoVaultSteakhouseUSDGPro"] = "morpho_vault_steakhouse_usdg_pro";
 })(MorphoVaultType || (MorphoVaultType = {}));
+export var MorphoVaultVersion;
+(function (MorphoVaultVersion) {
+    MorphoVaultVersion[MorphoVaultVersion["V1"] = 1] = "V1";
+    MorphoVaultVersion[MorphoVaultVersion["V2"] = 2] = "V2";
+})(MorphoVaultVersion || (MorphoVaultVersion = {}));

package/esm/types/spark.d.ts

@@ -100,6 +100,7 @@ export interface SparkAggregatedPositionData {
     leftToBorrowUsd: string;
     ratio: string;
     collRatio: string;
+    safetyRatio: string;
     netApy: string;
     incentiveUsd: string;
     totalInterestUsd: string;
@@ -124,6 +125,7 @@ export interface SparkPositionData extends MMPositionData, SparkPositionAggregat
     ratio: string;
     minRatio: string;
     collRatio: string;
+    safetyRatio?: string;
     suppliedUsd: string;
     borrowedUsd: string;
     borrowLimitUsd: string;

package/esm/umbrella/index.d.ts

@@ -1,5 +1,4 @@
 import { Client } from 'viem';
 import { EthAddress, NetworkNumber } from '../types/common';
-export declare const getUmbrellaData: (provider: Client, network: NetworkNumber, address: EthAddress) => Promise<{
-    [k: string]: any;
-}>;
+import { UmbrellaStakingData } from '../types/aave';
+export declare const getUmbrellaData: (provider: Client, network: NetworkNumber, address: EthAddress) => Promise<UmbrellaStakingData>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defisaver/positions-sdk",
-  "version": "2.1.161-portfolio-api-1-dev",
+  "version": "2.1.161-portfolio-api-3-dev",
   "description": "",
   "main": "./cjs/index.js",
   "module": "./esm/index.js",
@@ -18,7 +18,8 @@
     "version-bump": "git commit -am \"Version bump to $(npm version patch | cut -c 2-)\""
   },
   "keywords": [],
-  "author": "",
+  "author": "DeFi Saver",
+  "repository": "https://github.com/defisaver/defisaver-positions-sdk",
   "license": "ISC",
   "dependencies": {
     "@defisaver/tokens": "^1.7.45",

package/src/aaveV2/index.ts

@@ -210,6 +210,8 @@ export const _getAaveV2AccountData = async (provider: Client, network: NetworkNu
   payload.collRatio = payload.borrowedUsd && payload.borrowedUsd !== '0'
     ? new Dec(payload.suppliedCollateralUsd).div(payload.borrowedUsd).mul(100).toString()
     : '0';
+  // Aave v2 has no LTV-0 fallback (AaveV3View only), so its safety ratio is the plain ratio.
+  payload.safetyRatio = payload.ratio;
 
   // Calculate borrow limits per asset
   Object.values(payload.usedAssets).forEach((item) => {

package/src/aaveV3/index.ts

@@ -6,6 +6,7 @@ import {
   AaveIncentivesControllerViem,
   AaveV3ViewContractViem,
   createViemContractFromConfigFunc,
+  getConfigContractAbi,
   StkAAVEViem,
 } from '../contracts';
 import { aaveAnyGetAggregatedPositionData, aaveV3IsInIsolationMode, aaveV3IsInSiloedMode } from '../helpers/aaveHelpers';
@@ -30,6 +31,7 @@ import {
   EModeCategoriesData,
   EModeCategoryData,
   EModeCategoryDataMapping,
+  StakeAaveData,
 } from '../types';
 import {
   Blockish,
@@ -61,7 +63,10 @@ export const aaveV3EmodeCategoriesMapping = (extractedState: any, usedAssets: Aa
       ...extractedState, usedAssets, eModeCategory: e.id,
     });
     const willStayOverCollateralized = new Dec(afterEnteringCategory.ratio === 'NaN' ? '0' : afterEnteringCategory.ratio).eq(0) || new Dec(afterEnteringCategory.ratio).gt(afterEnteringCategory.liqPercent);
-    const enteringTerms = [borrowingOnlyFromCategory, willStayOverCollateralized];
+    const collateralOnlyFromCategory = e.id === 0 || !e.isolated
+      ? true
+      : !usedAssetsValues.filter(u => u.isSupplied && u.collateral && !e.collateralAssets.includes(u.symbol)).length;
+    const enteringTerms = [borrowingOnlyFromCategory, willStayOverCollateralized, collateralOnlyFromCategory];
     categoriesMapping[e.id] = {
       enteringTerms,
       canEnterCategory: !enteringTerms.includes(false),
@@ -118,6 +123,7 @@ export async function _getAaveV3MarketData(provider: Client, network: NetworkNum
         borrowableBitmap: eModesInfo[i].borrowableBitmap.toString(),
         collateralBitmap: eModesInfo[i].collateralBitmap.toString(),
         ltvzeroBitmap: eModesInfo[i].ltvzeroBitmap.toString(),
+        isolated: eModesInfo[i].isolated ?? false,
         borrowAssets: [],
         collateralAssets: [],
         ltvZeroAssets: [],
@@ -345,6 +351,7 @@ export async function _getAaveV3MarketData(provider: Client, network: NetworkNum
     collateralAssets: assetsData.map((a) => a.symbol),
     borrowAssets: assetsData.map((a) => a.symbol),
     ltvZeroAssets: [],
+    isolated: false,
   };
 
   return { assetsData: payload, eModeCategoriesData };
@@ -430,6 +437,290 @@ export const _getAaveV3AccountBalances = async (provider: Client, network: Netwo
 
 export const getAaveV3AccountBalances = async (provider: EthereumProvider, network: NetworkNumber, block: Blockish, addressMapping: boolean, address: EthAddress): Promise<PositionBalances> => _getAaveV3AccountBalances(getViemProvider(provider, network), network, block, addressMapping, address);
 
+/**
+ * Historical net-balance helpers that bypass the AaveV3View contract.
+ *
+ * The View contract (and therefore `getAaveV3AccountData` / `getAaveV3AccountBalances`) can only be
+ * queried from its deployment block onwards, so it cannot read balances for positions older than that.
+ * The aTokens/debt tokens, the ProtocolDataProvider and the Aave price oracle all exist from Aave v3
+ * launch, so reading `balanceOf` on those tokens + the oracle price directly reaches much further back
+ * and costs ~1 multicall per point. Used to build a position balance-history chart.
+ */
+
+// matches morphoVaults' batchSize; stays under the 500k portfolio discovery allows on simulation fork RPCs
+const HISTORICAL_MULTICALL_BATCH_SIZE = 250_000;
+
+// Minimal Aave price oracle ABI (getAssetPrice returns the asset price in the market base currency).
+const AAVE_ORACLE_ABI = [
+  {
+    inputs: [{ internalType: 'address', name: 'asset', type: 'address' }],
+    name: 'getAssetPrice',
+    outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+export interface AaveV3ReserveTokenAddresses {
+  [symbol: string]: {
+    symbol: string,
+    underlyingAddress: EthAddress,
+    aTokenAddress: EthAddress,
+    stableDebtTokenAddress: EthAddress,
+    variableDebtTokenAddress: EthAddress,
+  };
+}
+
+export interface AaveV3HistoricalBalance {
+  block: number,
+  suppliedUsd: string,
+  borrowedUsd: string,
+  netUsd: string,
+}
+
+/**
+ * Fetches the aToken / stable-debt / variable-debt token addresses for every asset in the market.
+ * These are effectively immutable per reserve, so fetch once and reuse across all history points.
+ */
+export const _getAaveV3ReserveTokenAddresses = async (provider: Client, network: NetworkNumber, market: AaveMarketInfo): Promise<AaveV3ReserveTokenAddresses> => {
+  const symbols = market.assets;
+  const underlyingAddresses = symbols.map((a: string) => getAssetInfo(getWrappedNativeAssetFromUnwrapped(a), network).address as EthAddress);
+  // @ts-ignore market.protocolData is a valid config key at runtime
+  const dataProviderAbi = getConfigContractAbi(market.protocolData, network);
+
+  const contracts = underlyingAddresses.map((underlying) => ({
+    address: market.protocolDataAddress as EthAddress,
+    abi: dataProviderAbi,
+    functionName: 'getReserveTokensAddresses',
+    args: [underlying],
+  }));
+
+  // @ts-ignore
+  const results = await provider.multicall({ contracts, allowFailure: true, batchSize: HISTORICAL_MULTICALL_BATCH_SIZE });
+
+  const mapping: AaveV3ReserveTokenAddresses = {};
+  results.forEach((res: any, i: number) => {
+    if (res.status !== 'success' || !res.result) return;
+    // outputs order: [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress]
+    const [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress] = res.result as [EthAddress, EthAddress, EthAddress];
+    mapping[symbols[i]] = {
+      symbol: symbols[i],
+      underlyingAddress: underlyingAddresses[i],
+      aTokenAddress,
+      stableDebtTokenAddress,
+      variableDebtTokenAddress,
+    };
+  });
+
+  return mapping;
+};
+
+export const getAaveV3ReserveTokenAddresses = async (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo): Promise<AaveV3ReserveTokenAddresses> => _getAaveV3ReserveTokenAddresses(getViemProvider(provider, network, { batch: { multicall: true } }), network, market);
+
+/**
+ * Resolves the price oracle the market's addresses provider points at (at `block`, or latest).
+ * Aave can rotate the oracle over time, so a caller hoisting one address across many historical
+ * points must resolve it at both ends of its block range and only reuse it when the two agree —
+ * otherwise leave `oracleAddress` unset on _getAaveV3HistoricalBalance and it resolves per block.
+ */
+export const _getAaveV3OracleAddress = async (provider: Client, network: NetworkNumber, market: AaveMarketInfo, block: Blockish = 'latest'): Promise<EthAddress> => {
+  // @ts-ignore market.provider is a valid config key at runtime
+  const providerAbi = getConfigContractAbi(market.provider, network);
+  // @ts-ignore readContract exists on the public client returned by getViemProvider
+  const oracleAddress = await provider.readContract({
+    address: market.providerAddress as EthAddress,
+    abi: providerAbi as any,
+    functionName: 'getPriceOracle',
+    ...setViemBlockNumber(block),
+  });
+  if (!oracleAddress) throw new Error(`AaveV3 oracle unavailable at block ${block}`);
+  return oracleAddress as EthAddress;
+};
+
+export const getAaveV3OracleAddress = async (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo, block: Blockish = 'latest'): Promise<EthAddress> => _getAaveV3OracleAddress(getViemProvider(provider, network, { batch: { multicall: true } }), network, market, block);
+
+type AaveV3ReserveTokenEntry = AaveV3ReserveTokenAddresses[string];
+type AaveV3ActiveHistoricalAsset = AaveV3ReserveTokenEntry & { supplied: string, debt: string };
+// raw getAssetPrice multicall result per asset symbol
+type AaveV3PriceResultsBySymbol = Record<string, any>;
+
+// supply = aToken.balanceOf, debt = variableDebtToken.balanceOf + stableDebtToken.balanceOf — three reads per reserve
+const getHistoricalBalanceContracts = (entries: AaveV3ReserveTokenEntry[], address: EthAddress) => {
+  const erc20Abi = getConfigContractAbi('Erc20');
+  return entries.flatMap((e) => ([
+    {
+      address: e.aTokenAddress, abi: erc20Abi, functionName: 'balanceOf', args: [address],
+    },
+    {
+      address: e.variableDebtTokenAddress, abi: erc20Abi, functionName: 'balanceOf', args: [address],
+    },
+    {
+      address: e.stableDebtTokenAddress, abi: erc20Abi, functionName: 'balanceOf', args: [address],
+    },
+  ]));
+};
+
+const getAssetPriceContract = (oracle: EthAddress, underlyingAddress: EthAddress) => ({
+  address: oracle,
+  abi: AAVE_ORACLE_ABI,
+  functionName: 'getAssetPrice',
+  args: [underlyingAddress],
+});
+
+/**
+ * Pairs each reserve with its three balance reads and keeps the assets the wallet actually held.
+ * Throws when every read failed — a totally failed fetch must not masquerade as a real $0 balance,
+ * so the caller can distinguish "fetch failed" (gap) from "position was empty" (genuine 0).
+ */
+const toActiveHistoricalAssets = (entries: AaveV3ReserveTokenEntry[], balanceResults: any[], block: number): AaveV3ActiveHistoricalAsset[] => {
+  const anyBalanceRead = balanceResults.some((r) => r?.status === 'success');
+  if (!anyBalanceRead) throw new Error(`AaveV3 historical balance: all balance reads failed at block ${block}`);
+
+  return entries.map((e, i) => {
+    const supplyRes = balanceResults[i * 3];
+    const varDebtRes = balanceResults[(i * 3) + 1];
+    const stableDebtRes = balanceResults[(i * 3) + 2];
+    const supplied = supplyRes?.status === 'success' ? (supplyRes.result as bigint).toString() : '0';
+    const varDebt = varDebtRes?.status === 'success' ? (varDebtRes.result as bigint).toString() : '0';
+    const stableDebt = stableDebtRes?.status === 'success' ? (stableDebtRes.result as bigint).toString() : '0';
+    const debt = new Dec(varDebt).add(stableDebt).toString();
+    return { ...e, supplied, debt };
+  }).filter((a) => a.supplied !== '0' || a.debt !== '0');
+};
+
+/**
+ * Sums the active assets into the point's USD totals. Throws when every price read failed — the
+ * oracle couldn't serve this block (pruned state, or a hoisted oracle that wasn't deployed yet back
+ * then), and totalling it up anyway would return a fake near-$0 balance. A single asset's price
+ * failure still just skips that asset, matching the live data path.
+ */
+const sumHistoricalUsd = (activeAssets: AaveV3ActiveHistoricalAsset[], priceResBySymbol: AaveV3PriceResultsBySymbol, block: number): AaveV3HistoricalBalance => {
+  const anyPriceRead = activeAssets.some((a) => priceResBySymbol[a.symbol]?.status === 'success');
+  if (!anyPriceRead) throw new Error(`AaveV3 historical balance: all price reads failed at block ${block}`);
+
+  let suppliedUsd = new Dec(0);
+  let borrowedUsd = new Dec(0);
+  activeAssets.forEach((a) => {
+    const priceRes = priceResBySymbol[a.symbol];
+    if (priceRes?.status !== 'success') return;
+    const priceUsd = new Dec((priceRes.result as bigint).toString()).div(1e8); // Aave v3 base currency is USD with 8 decimals
+    if (a.supplied !== '0') suppliedUsd = suppliedUsd.add(new Dec(assetAmountInEth(a.supplied, a.symbol)).mul(priceUsd));
+    if (a.debt !== '0') borrowedUsd = borrowedUsd.add(new Dec(assetAmountInEth(a.debt, a.symbol)).mul(priceUsd));
+  });
+
+  return {
+    block,
+    suppliedUsd: suppliedUsd.toString(),
+    borrowedUsd: borrowedUsd.toString(),
+    netUsd: suppliedUsd.minus(borrowedUsd).toString(),
+  };
+};
+
+/**
+ * Fast path, ONE multicall: balances plus a price read for every reserve through the caller-hoisted
+ * oracle. Prices are read for all reserves because which assets are active isn't known until the
+ * balances come back — extra reads inside an already-paid multicall are nearly free.
+ */
+const fetchHistoricalPointWithOracle = async (provider: Client, entries: AaveV3ReserveTokenEntry[], address: EthAddress, block: number, oracleAddress: EthAddress) => {
+  const balanceContracts = getHistoricalBalanceContracts(entries, address);
+  const priceContracts = entries.map((e) => getAssetPriceContract(oracleAddress, e.underlyingAddress));
+
+  // @ts-ignore
+  const results = await provider.multicall({
+    contracts: [...balanceContracts, ...priceContracts], allowFailure: true, blockNumber: BigInt(block), batchSize: HISTORICAL_MULTICALL_BATCH_SIZE,
+  });
+
+  const activeAssets = toActiveHistoricalAssets(entries, results.slice(0, balanceContracts.length), block);
+  const priceResBySymbol: AaveV3PriceResultsBySymbol = {};
+  results.slice(balanceContracts.length).forEach((res: any, i: number) => {
+    priceResBySymbol[entries[i].symbol] = res;
+  });
+  return { activeAssets, priceResBySymbol };
+};
+
+/**
+ * Fallback path, TWO multicalls: balances plus getPriceOracle (resolving the oracle that was active
+ * AT the block — Aave can rotate it over time), then prices for just the active assets. The oracle
+ * read has no fallback: if it fails (bad archive node, rate limit, ...) the failure must surface
+ * rather than silently returning $0 — the caller renders a gap instead of a misleading zero.
+ */
+const fetchHistoricalPointResolvingOracle = async (provider: Client, network: NetworkNumber, market: AaveMarketInfo, entries: AaveV3ReserveTokenEntry[], address: EthAddress, block: number) => {
+  const balanceContracts = getHistoricalBalanceContracts(entries, address);
+  // @ts-ignore market.provider is a valid config key at runtime
+  const providerAbi = getConfigContractAbi(market.provider, network);
+  const oracleContract = {
+    address: market.providerAddress as EthAddress,
+    abi: providerAbi,
+    functionName: 'getPriceOracle',
+  };
+  const blockNumber = BigInt(block);
+
+  // @ts-ignore
+  const results = await provider.multicall({
+    contracts: [...balanceContracts, oracleContract], allowFailure: true, blockNumber, batchSize: HISTORICAL_MULTICALL_BATCH_SIZE,
+  });
+  const oracleRes = results[balanceContracts.length];
+  if (oracleRes?.status !== 'success' || !oracleRes.result) throw new Error(`AaveV3 historical balance: oracle unavailable at block ${block}`);
+
+  const activeAssets = toActiveHistoricalAssets(entries, results.slice(0, balanceContracts.length), block);
+  if (!activeAssets.length) return { activeAssets, priceResBySymbol: {} };
+
+  const priceContracts = activeAssets.map((a) => getAssetPriceContract(oracleRes.result as EthAddress, a.underlyingAddress));
+  // @ts-ignore
+  const priceResults = await provider.multicall({
+    contracts: priceContracts, allowFailure: true, blockNumber, batchSize: HISTORICAL_MULTICALL_BATCH_SIZE,
+  });
+  const priceResBySymbol: AaveV3PriceResultsBySymbol = {};
+  priceResults.forEach((res: any, i: number) => {
+    priceResBySymbol[activeAssets[i].symbol] = res;
+  });
+  return { activeAssets, priceResBySymbol };
+};
+
+/**
+ * Computes a user's Aave v3 net USD balance (supplied collateral - borrowed debt) at a historical block,
+ * without touching the AaveV3View contract. Pass `reserveTokens` (from getAaveV3ReserveTokenAddresses)
+ * to avoid refetching token addresses for every point, and `oracleAddress` (from getAaveV3OracleAddress,
+ * verified identical at both ends of the sampled range) to collapse the point into a single multicall —
+ * with it the balances and all prices ride one request; without it the oracle is resolved at the block
+ * inside the balance multicall and the active assets are priced in a second one.
+ */
+export const _getAaveV3HistoricalBalance = async (
+  provider: Client,
+  network: NetworkNumber,
+  market: AaveMarketInfo,
+  address: EthAddress,
+  block: number,
+  reserveTokens?: AaveV3ReserveTokenAddresses,
+  oracleAddress?: EthAddress,
+): Promise<AaveV3HistoricalBalance> => {
+  const empty: AaveV3HistoricalBalance = {
+    block, suppliedUsd: '0', borrowedUsd: '0', netUsd: '0',
+  };
+  if (!address) return empty;
+
+  const tokens = reserveTokens || await _getAaveV3ReserveTokenAddresses(provider, network, market);
+  const entries = Object.values(tokens);
+  if (!entries.length) return empty;
+
+  const { activeAssets, priceResBySymbol } = oracleAddress
+    ? await fetchHistoricalPointWithOracle(provider, entries, address, block, oracleAddress)
+    : await fetchHistoricalPointResolvingOracle(provider, network, market, entries, address, block);
+
+  if (!activeAssets.length) return empty;
+  return sumHistoricalUsd(activeAssets, priceResBySymbol, block);
+};
+
+export const getAaveV3HistoricalBalance = async (
+  provider: EthereumProvider,
+  network: NetworkNumber,
+  market: AaveMarketInfo,
+  address: EthAddress,
+  block: number,
+  reserveTokens?: AaveV3ReserveTokenAddresses,
+  oracleAddress?: EthAddress,
+): Promise<AaveV3HistoricalBalance> => _getAaveV3HistoricalBalance(getViemProvider(provider, network, { batch: { multicall: true } }), network, market, address, block, reserveTokens, oracleAddress);
+
 export const _getAaveV3AccountData = async (provider: Client, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber: 'latest' | number = 'latest'): Promise<AaveV3PositionData> => {
   const {
     selectedMarket: market, assetsData, eModeCategoriesData,
@@ -608,7 +899,7 @@ export const fetchYearlyMeritApyForStakingGho = async () => {
   }
 };
 
-export const getStakeAaveData = async (provider: Client, network: NetworkNumber, address: EthAddress) => {
+export const getStakeAaveData = async (provider: Client, network: NetworkNumber, address: EthAddress): Promise<StakeAaveData> => {
   const stkGhoAddress = getAssetInfo('stkGHO').address as HexString;
   const stkAaveAddress = getAssetInfo('stkAAVE').address as HexString;
 

package/src/aaveV3/sgho.ts

@@ -1,25 +1,10 @@
 import Dec from 'decimal.js';
 import { EthAddress, NetworkNumber } from '../types/common';
+import { SghoData } from '../types/aave';
 import { DEFAULT_TIMEOUT } from '../services/utils';
 import { ZERO_ADDRESS } from '../constants';
 
-export interface SghoUserData {
-  shares: string;
-  balance: string;
-  maxDeposit: string;
-  maxWithdraw: string;
-  underlyingBalance: string;
-}
-
-export interface SghoData {
-  totalAssets: string;
-  totalSupply: string;
-  supplyCap: string;
-  /** Target savings rate as an APY percent (e.g. "4.25" for 4.25%). */
-  targetRate: string;
-  paused: boolean;
-  user: SghoUserData;
-}
+export type { SghoData, SghoUserData } from '../types/aave';
 
 const EMPTY_SGHO_DATA: SghoData = {
   totalAssets: '0',