@defisaver/positions-sdk 2.1.156 → 2.1.157-pos-history-dev

package/cjs/aaveV3/index.d.ts

@@ -32,6 +32,34 @@ export declare const EMPTY_AAVE_DATA: {
 };
 export declare const _getAaveV3AccountBalances: (provider: Client, network: NetworkNumber, block: Blockish, addressMapping: boolean, address: EthAddress) => Promise<PositionBalances>;
 export declare const getAaveV3AccountBalances: (provider: EthereumProvider, network: NetworkNumber, block: Blockish, addressMapping: boolean, address: EthAddress) => Promise<PositionBalances>;
+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 declare const _getAaveV3ReserveTokenAddresses: (provider: Client, network: NetworkNumber, market: AaveMarketInfo) => Promise<AaveV3ReserveTokenAddresses>;
+export declare const getAaveV3ReserveTokenAddresses: (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo) => Promise<AaveV3ReserveTokenAddresses>;
+/**
+ * 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.
+ */
+export declare const _getAaveV3HistoricalBalance: (provider: Client, network: NetworkNumber, market: AaveMarketInfo, address: EthAddress, block: number, reserveTokens?: AaveV3ReserveTokenAddresses) => Promise<AaveV3HistoricalBalance>;
+export declare const getAaveV3HistoricalBalance: (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo, address: EthAddress, block: number, reserveTokens?: AaveV3ReserveTokenAddresses) => Promise<AaveV3HistoricalBalance>;
 export declare const _getAaveV3AccountData: (provider: Client, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber?: "latest" | number) => Promise<AaveV3PositionData>;
 export declare const getAaveV3AccountData: (provider: EthereumProvider, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber?: "latest" | number) => Promise<AaveV3PositionData>;
 export declare const getAaveV3FullPositionData: (provider: EthereumProvider, network: NetworkNumber, address: EthAddress, market: AaveMarketInfo) => Promise<AaveV3PositionData>;

package/cjs/aaveV3/index.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSghoData = exports.getMerkleCampaigns = exports.getMeritCampaigns = exports.getStakeAaveData = exports.fetchYearlyMeritApyForStakingGho = exports.REWARDABLE_ASSETS = exports.getAaveV3FullPositionData = exports.getAaveV3AccountData = exports._getAaveV3AccountData = exports.getAaveV3AccountBalances = exports._getAaveV3AccountBalances = exports.EMPTY_AAVE_DATA = exports.aaveV3EmodeCategoriesMapping = void 0;
+exports.getSghoData = exports.getMerkleCampaigns = exports.getMeritCampaigns = exports.getStakeAaveData = exports.fetchYearlyMeritApyForStakingGho = exports.REWARDABLE_ASSETS = exports.getAaveV3FullPositionData = exports.getAaveV3AccountData = exports._getAaveV3AccountData = exports.getAaveV3HistoricalBalance = exports._getAaveV3HistoricalBalance = exports.getAaveV3ReserveTokenAddresses = exports._getAaveV3ReserveTokenAddresses = exports.getAaveV3AccountBalances = exports._getAaveV3AccountBalances = exports.EMPTY_AAVE_DATA = exports.aaveV3EmodeCategoriesMapping = void 0;
 exports._getAaveV3MarketData = _getAaveV3MarketData;
 exports.getAaveV3MarketData = getAaveV3MarketData;
 const tokens_1 = require("@defisaver/tokens");
@@ -375,6 +375,155 @@ const _getAaveV3AccountBalances = (provider, network, block, addressMapping, add
 exports._getAaveV3AccountBalances = _getAaveV3AccountBalances;
 const getAaveV3AccountBalances = (provider, network, block, addressMapping, address) => __awaiter(void 0, void 0, void 0, function* () { return (0, exports._getAaveV3AccountBalances)((0, viem_1.getViemProvider)(provider, network), network, block, addressMapping, address); });
 exports.getAaveV3AccountBalances = getAaveV3AccountBalances;
+/**
+ * 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.
+ */
+// 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',
+    },
+];
+/**
+ * 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.
+ */
+const _getAaveV3ReserveTokenAddresses = (provider, network, market) => __awaiter(void 0, void 0, void 0, function* () {
+    const symbols = market.assets;
+    const underlyingAddresses = symbols.map((a) => (0, tokens_1.getAssetInfo)((0, utils_1.getWrappedNativeAssetFromUnwrapped)(a), network).address);
+    // @ts-ignore market.protocolData is a valid config key at runtime
+    const dataProviderAbi = (0, contracts_1.getConfigContractAbi)(market.protocolData, network);
+    const contracts = underlyingAddresses.map((underlying) => ({
+        address: market.protocolDataAddress,
+        abi: dataProviderAbi,
+        functionName: 'getReserveTokensAddresses',
+        args: [underlying],
+    }));
+    // @ts-ignore
+    const results = yield provider.multicall({ contracts, allowFailure: true });
+    const mapping = {};
+    results.forEach((res, i) => {
+        if (res.status !== 'success' || !res.result)
+            return;
+        // outputs order: [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress]
+        const [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress] = res.result;
+        mapping[symbols[i]] = {
+            symbol: symbols[i],
+            underlyingAddress: underlyingAddresses[i],
+            aTokenAddress,
+            stableDebtTokenAddress,
+            variableDebtTokenAddress,
+        };
+    });
+    return mapping;
+});
+exports._getAaveV3ReserveTokenAddresses = _getAaveV3ReserveTokenAddresses;
+const getAaveV3ReserveTokenAddresses = (provider, network, market) => __awaiter(void 0, void 0, void 0, function* () { return (0, exports._getAaveV3ReserveTokenAddresses)((0, viem_1.getViemProvider)(provider, network, { batch: { multicall: true } }), network, market); });
+exports.getAaveV3ReserveTokenAddresses = getAaveV3ReserveTokenAddresses;
+/**
+ * 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.
+ */
+const _getAaveV3HistoricalBalance = (provider, network, market, address, block, reserveTokens) => __awaiter(void 0, void 0, void 0, function* () {
+    const empty = {
+        block, suppliedUsd: '0', borrowedUsd: '0', netUsd: '0',
+    };
+    if (!address)
+        return empty;
+    const tokens = reserveTokens || (yield (0, exports._getAaveV3ReserveTokenAddresses)(provider, network, market));
+    const entries = Object.values(tokens);
+    if (!entries.length)
+        return empty;
+    const erc20Abi = (0, contracts_1.getConfigContractAbi)('Erc20');
+    const blockNumber = BigInt(block);
+    // supply = aToken.balanceOf, debt = variableDebtToken.balanceOf + stableDebtToken.balanceOf, all at the block.
+    const balanceContracts = 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],
+        },
+    ]));
+    // @ts-ignore market.provider is a valid config key at runtime
+    const providerAbi = (0, contracts_1.getConfigContractAbi)(market.provider, network);
+    const [balanceResults, oracleAddress] = yield Promise.all([
+        // @ts-ignore
+        provider.multicall({ contracts: balanceContracts, allowFailure: true, blockNumber }),
+        // resolve the oracle that was active at the block (Aave can rotate the oracle over time).
+        // No catch: if this read fails (bad archive node, rate limit, ...) we must surface the failure
+        // rather than silently returning $0 — the caller renders a gap instead of a misleading zero.
+        // @ts-ignore readContract exists on the public client returned by getViemProvider
+        provider.readContract({
+            address: market.providerAddress,
+            abi: providerAbi,
+            functionName: 'getPriceOracle',
+            blockNumber,
+        }),
+    ]);
+    // A totally failed balance read must not masquerade as a real $0 balance — throw so the caller
+    // can distinguish "fetch failed" (gap) from "position was empty" (genuine 0).
+    const anyBalanceRead = balanceResults.some((r) => (r === null || r === void 0 ? void 0 : r.status) === 'success');
+    if (!anyBalanceRead)
+        throw new Error(`AaveV3 historical balance: all balance reads failed at block ${block}`);
+    if (!oracleAddress)
+        throw new Error(`AaveV3 historical balance: oracle unavailable at block ${block}`);
+    const activeAssets = entries.map((e, i) => {
+        const supplyRes = balanceResults[i * 3];
+        const varDebtRes = balanceResults[(i * 3) + 1];
+        const stableDebtRes = balanceResults[(i * 3) + 2];
+        const supplied = (supplyRes === null || supplyRes === void 0 ? void 0 : supplyRes.status) === 'success' ? supplyRes.result.toString() : '0';
+        const varDebt = (varDebtRes === null || varDebtRes === void 0 ? void 0 : varDebtRes.status) === 'success' ? varDebtRes.result.toString() : '0';
+        const stableDebt = (stableDebtRes === null || stableDebtRes === void 0 ? void 0 : stableDebtRes.status) === 'success' ? stableDebtRes.result.toString() : '0';
+        const debt = new decimal_js_1.default(varDebt).add(stableDebt).toString();
+        return Object.assign(Object.assign({}, e), { supplied, debt });
+    }).filter((a) => a.supplied !== '0' || a.debt !== '0');
+    if (!activeAssets.length)
+        return empty;
+    const priceContracts = activeAssets.map((a) => ({
+        address: oracleAddress,
+        abi: AAVE_ORACLE_ABI,
+        functionName: 'getAssetPrice',
+        args: [a.underlyingAddress],
+    }));
+    // @ts-ignore
+    const priceResults = yield provider.multicall({ contracts: priceContracts, allowFailure: true, blockNumber });
+    let suppliedUsd = new decimal_js_1.default(0);
+    let borrowedUsd = new decimal_js_1.default(0);
+    activeAssets.forEach((a, i) => {
+        const priceRes = priceResults[i];
+        if ((priceRes === null || priceRes === void 0 ? void 0 : priceRes.status) !== 'success')
+            return;
+        const priceUsd = new decimal_js_1.default(priceRes.result.toString()).div(1e8); // Aave v3 base currency is USD with 8 decimals
+        if (a.supplied !== '0')
+            suppliedUsd = suppliedUsd.add(new decimal_js_1.default((0, tokens_1.assetAmountInEth)(a.supplied, a.symbol)).mul(priceUsd));
+        if (a.debt !== '0')
+            borrowedUsd = borrowedUsd.add(new decimal_js_1.default((0, tokens_1.assetAmountInEth)(a.debt, a.symbol)).mul(priceUsd));
+    });
+    return {
+        block,
+        suppliedUsd: suppliedUsd.toString(),
+        borrowedUsd: borrowedUsd.toString(),
+        netUsd: suppliedUsd.minus(borrowedUsd).toString(),
+    };
+});
+exports._getAaveV3HistoricalBalance = _getAaveV3HistoricalBalance;
+const getAaveV3HistoricalBalance = (provider, network, market, address, block, reserveTokens) => __awaiter(void 0, void 0, void 0, function* () { return (0, exports._getAaveV3HistoricalBalance)((0, viem_1.getViemProvider)(provider, network, { batch: { multicall: true } }), network, market, address, block, reserveTokens); });
+exports.getAaveV3HistoricalBalance = getAaveV3HistoricalBalance;
 const _getAaveV3AccountData = (provider_1, network_1, address_1, extractedState_1, ...args_1) => __awaiter(void 0, [provider_1, network_1, address_1, extractedState_1, ...args_1], void 0, function* (provider, network, address, extractedState, blockNumber = 'latest') {
     const { selectedMarket: market, assetsData, eModeCategoriesData, } = extractedState;
     let payload = Object.assign(Object.assign({}, exports.EMPTY_AAVE_DATA), { lastUpdated: Date.now() });

package/cjs/aaveV4/merkl.js

@@ -8,14 +8,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.attachAaveV4MerklIncentives = exports.getAaveV4MerkleCampaigns = exports.buildAaveV4MerklRewardMap = void 0;
+const decimal_js_1 = __importDefault(require("decimal.js"));
 const moneymarket_1 = require("../moneymarket");
 const merkl_1 = require("../services/merkl");
 const types_1 = require("../types");
 /**
  * Merkl tags Aave V4 reward campaigns by scope via the `type` field:
- *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW   → reward tied to a hub asset
+ *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW / AAVE_V4_HUB_NET_LENDING → hub asset
  *   - AAVE_V4_SPOKE_SUPPLY / AAVE_V4_SPOKE_BORROW → reward tied to a spoke reserve
  * Embedded campaign params provide the exact on-chain identifiers. Token addresses cannot safely
  * identify Aave V4 rewards because one spoke can expose the same underlying from multiple hubs.
@@ -42,9 +46,19 @@ const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
         .filter((o) => o.status === types_1.OpportunityStatus.LIVE)
         .filter((o) => typeof o.type === 'string' && o.type.startsWith('AAVE_V4_'))
         .forEach((o) => {
-        var _a, _b;
+        var _a, _b, _c;
         const side = o.action === types_1.OpportunityAction.BORROW ? types_1.IncentiveSide.Borrow : types_1.IncentiveSide.Supply;
-        const incentive = buildIncentive(o);
+        const now = Date.now() / 1000;
+        const methods = (_a = o.campaigns) === null || _a === void 0 ? void 0 : _a.filter((c) => (c.startTimestamp === undefined || c.startTimestamp <= now)
+            && (c.endTimestamp === undefined || c.endTimestamp > now)).map((c) => { var _a, _b; return (_b = (_a = c.params) === null || _a === void 0 ? void 0 : _a.distributionMethodParameters) === null || _b === void 0 ? void 0 : _b.distributionMethod; });
+        // An opportunity-level APR cannot be split between simultaneous net and additive campaigns.
+        if (side === types_1.IncentiveSide.Supply && (methods === null || methods === void 0 ? void 0 : methods.includes('AAVE_V4_NET_APR'))
+            && methods.some((method) => !!method && method !== 'AAVE_V4_NET_APR'))
+            return;
+        const incentive = Object.assign(Object.assign({}, buildIncentive(o)), { 
+            // Missing methods keep the existing target-yield behavior.
+            isAdditiveReward: side === types_1.IncentiveSide.Supply && !!(methods === null || methods === void 0 ? void 0 : methods.length)
+                && methods.every((method) => !!method && method !== 'AAVE_V4_NET_APR') });
         // one opportunity can span several campaigns (e.g. renewed periods), so campaign identity is
         // collected per scope key before the reward entries are written
         const idsByKey = {};
@@ -57,11 +71,13 @@ const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
                 idsByKey[key].parentCampaignIds.add(campaign.parentCampaignId);
         };
         if (o.type.includes('HUB')) {
-            (_a = o.campaigns) === null || _a === void 0 ? void 0 : _a.forEach((c) => {
-                var _a;
-                if (!((_a = c.params) === null || _a === void 0 ? void 0 : _a.hubAddress) || c.params.assetId === undefined || c.params.assetId === null)
+            (_b = o.campaigns) === null || _b === void 0 ? void 0 : _b.forEach((c) => {
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+                const hubAddress = (_b = (_a = c.params) === null || _a === void 0 ? void 0 : _a.hubAddress) !== null && _b !== void 0 ? _b : (_e = (_d = (_c = c.params) === null || _c === void 0 ? void 0 : _c.distributionMethodParameters) === null || _d === void 0 ? void 0 : _d.distributionSettings) === null || _e === void 0 ? void 0 : _e.hubAddress;
+                const assetId = (_g = (_f = c.params) === null || _f === void 0 ? void 0 : _f.assetId) !== null && _g !== void 0 ? _g : (_k = (_j = (_h = c.params) === null || _h === void 0 ? void 0 : _h.distributionMethodParameters) === null || _j === void 0 ? void 0 : _j.distributionSettings) === null || _k === void 0 ? void 0 : _k.assetId;
+                if (!hubAddress || assetId === undefined || assetId === null)
                     return;
-                collect(scopeKey(c.params.hubAddress, c.params.assetId), c);
+                collect(scopeKey(hubAddress, assetId), c);
             });
             Object.entries(idsByKey).forEach(([key, ids]) => {
                 if (!result.hub[key])
@@ -70,7 +86,7 @@ const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
             });
         }
         else if (o.type.includes('SPOKE')) {
-            (_b = o.campaigns) === null || _b === void 0 ? void 0 : _b.forEach((c) => {
+            (_c = o.campaigns) === null || _c === void 0 ? void 0 : _c.forEach((c) => {
                 var _a;
                 if (!((_a = c.params) === null || _a === void 0 ? void 0 : _a.spokeAddress) || c.params.reserveId === undefined || c.params.reserveId === null)
                     return;
@@ -90,7 +106,7 @@ const getAaveV4MerkleCampaigns = (chainId) => __awaiter(void 0, void 0, void 0,
     try {
         const opportunities = yield (0, merkl_1.fetchAllMerklOpportunities)({
             mainProtocolId: 'aave',
-            type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
+            type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_HUB_NET_LENDING,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
             status: types_1.OpportunityStatus.LIVE,
             campaigns: 'true',
         });
@@ -112,6 +128,8 @@ const attachAaveV4MerklIncentives = (asset, spokeAddress, campaigns) => {
     const baseBorrow = asset.borrowIncentives || [];
     const spokeScoped = spokeAddress ? campaigns.spoke[scopeKey(spokeAddress, asset.reserveId)] : undefined;
     const hubScoped = asset.hub ? campaigns.hub[scopeKey(asset.hub, asset.assetId)] : undefined;
-    return Object.assign(Object.assign({}, asset), { spokeSupplyIncentives: ((_a = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.supply) === null || _a === void 0 ? void 0 : _a.length) ? [...baseSupply, ...spokeScoped.supply] : baseSupply, spokeBorrowIncentives: ((_b = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.borrow) === null || _b === void 0 ? void 0 : _b.length) ? [...baseBorrow, ...spokeScoped.borrow] : baseBorrow, hubSupplyIncentives: ((_c = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.supply) === null || _c === void 0 ? void 0 : _c.length) ? [...baseSupply, ...hubScoped.supply] : baseSupply, hubBorrowIncentives: ((_d = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.borrow) === null || _d === void 0 ? void 0 : _d.length) ? [...baseBorrow, ...hubScoped.borrow] : baseBorrow });
+    // Net-APR campaigns top up native yield; additive campaigns pay their APR on top.
+    const supplyRewards = (rewards = []) => rewards.map((reward) => (Object.assign(Object.assign({}, reward), { apy: reward.isAdditiveReward ? reward.apy : decimal_js_1.default.max(0, new decimal_js_1.default(reward.apy).minus(asset.supplyRate || 0)).toString() })));
+    return Object.assign(Object.assign({}, asset), { spokeSupplyIncentives: ((_a = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.supply) === null || _a === void 0 ? void 0 : _a.length) ? [...baseSupply, ...supplyRewards(spokeScoped.supply)] : baseSupply, spokeBorrowIncentives: ((_b = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.borrow) === null || _b === void 0 ? void 0 : _b.length) ? [...baseBorrow, ...spokeScoped.borrow] : baseBorrow, hubSupplyIncentives: ((_c = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.supply) === null || _c === void 0 ? void 0 : _c.length) ? [...baseSupply, ...supplyRewards(hubScoped.supply)] : baseSupply, hubBorrowIncentives: ((_d = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.borrow) === null || _d === void 0 ? void 0 : _d.length) ? [...baseBorrow, ...hubScoped.borrow] : baseBorrow });
 };
 exports.attachAaveV4MerklIncentives = attachAaveV4MerklIncentives;

package/cjs/types/merkl.d.ts

@@ -11,6 +11,8 @@ export declare enum OpportunityStatus {
 export type MerklCampaign = {
     id: string;
     campaignId: string;
+    startTimestamp?: number;
+    endTimestamp?: number;
     /**
      * Merkl-internal `id` of the parent campaign — set on child campaigns, which re-publish a hub
      * (parent) campaign's reward scoped to a single spoke reserve. Absent on standalone campaigns,
@@ -24,6 +26,13 @@ export type MerklCampaign = {
         hubAddress?: EthAddress;
         hubAssetId?: string | number;
         assetId?: string | number;
+        distributionMethodParameters?: {
+            distributionMethod?: string;
+            distributionSettings?: {
+                hubAddress?: EthAddress;
+                assetId?: string | number;
+            };
+        };
     };
 };
 export type MerklOpportunity = {
@@ -102,6 +111,7 @@ export type MerkleRewardMap = Record<EthAddress, {
 export type AaveV4MerklIncentive = IncentiveData & {
     campaignIds?: string[];
     parentCampaignIds?: string[];
+    isAdditiveReward?: boolean;
 };
 export type AaveV4MerklScopedReward = {
     [side in IncentiveSide]?: AaveV4MerklIncentive[];

package/esm/aaveV3/index.d.ts

@@ -32,6 +32,34 @@ export declare const EMPTY_AAVE_DATA: {
 };
 export declare const _getAaveV3AccountBalances: (provider: Client, network: NetworkNumber, block: Blockish, addressMapping: boolean, address: EthAddress) => Promise<PositionBalances>;
 export declare const getAaveV3AccountBalances: (provider: EthereumProvider, network: NetworkNumber, block: Blockish, addressMapping: boolean, address: EthAddress) => Promise<PositionBalances>;
+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 declare const _getAaveV3ReserveTokenAddresses: (provider: Client, network: NetworkNumber, market: AaveMarketInfo) => Promise<AaveV3ReserveTokenAddresses>;
+export declare const getAaveV3ReserveTokenAddresses: (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo) => Promise<AaveV3ReserveTokenAddresses>;
+/**
+ * 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.
+ */
+export declare const _getAaveV3HistoricalBalance: (provider: Client, network: NetworkNumber, market: AaveMarketInfo, address: EthAddress, block: number, reserveTokens?: AaveV3ReserveTokenAddresses) => Promise<AaveV3HistoricalBalance>;
+export declare const getAaveV3HistoricalBalance: (provider: EthereumProvider, network: NetworkNumber, market: AaveMarketInfo, address: EthAddress, block: number, reserveTokens?: AaveV3ReserveTokenAddresses) => Promise<AaveV3HistoricalBalance>;
 export declare const _getAaveV3AccountData: (provider: Client, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber?: "latest" | number) => Promise<AaveV3PositionData>;
 export declare const getAaveV3AccountData: (provider: EthereumProvider, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber?: "latest" | number) => Promise<AaveV3PositionData>;
 export declare const getAaveV3FullPositionData: (provider: EthereumProvider, network: NetworkNumber, address: EthAddress, market: AaveMarketInfo) => Promise<AaveV3PositionData>;

package/esm/aaveV3/index.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { assetAmountInEth, assetAmountInWei, getAssetInfo } from '@defisaver/tokens';
 import Dec from 'decimal.js';
-import { AaveIncentiveDataProviderV3ContractViem, AaveIncentivesControllerViem, AaveV3ViewContractViem, createViemContractFromConfigFunc, StkAAVEViem, } from '../contracts';
+import { AaveIncentiveDataProviderV3ContractViem, AaveIncentivesControllerViem, AaveV3ViewContractViem, createViemContractFromConfigFunc, getConfigContractAbi, StkAAVEViem, } from '../contracts';
 import { aaveAnyGetAggregatedPositionData, aaveV3IsInIsolationMode, aaveV3IsInSiloedMode } from '../helpers/aaveHelpers';
 import { AAVE_V3 } from '../markets/aave';
 import { aprToApy, calculateBorrowingAssetLimit } from '../moneymarket';
@@ -362,6 +362,151 @@ export const _getAaveV3AccountBalances = (provider, network, block, addressMappi
     return balances;
 });
 export const getAaveV3AccountBalances = (provider, network, block, addressMapping, address) => __awaiter(void 0, void 0, void 0, function* () { return _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.
+ */
+// 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',
+    },
+];
+/**
+ * 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 = (provider, network, market) => __awaiter(void 0, void 0, void 0, function* () {
+    const symbols = market.assets;
+    const underlyingAddresses = symbols.map((a) => getAssetInfo(getWrappedNativeAssetFromUnwrapped(a), network).address);
+    // @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,
+        abi: dataProviderAbi,
+        functionName: 'getReserveTokensAddresses',
+        args: [underlying],
+    }));
+    // @ts-ignore
+    const results = yield provider.multicall({ contracts, allowFailure: true });
+    const mapping = {};
+    results.forEach((res, i) => {
+        if (res.status !== 'success' || !res.result)
+            return;
+        // outputs order: [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress]
+        const [aTokenAddress, stableDebtTokenAddress, variableDebtTokenAddress] = res.result;
+        mapping[symbols[i]] = {
+            symbol: symbols[i],
+            underlyingAddress: underlyingAddresses[i],
+            aTokenAddress,
+            stableDebtTokenAddress,
+            variableDebtTokenAddress,
+        };
+    });
+    return mapping;
+});
+export const getAaveV3ReserveTokenAddresses = (provider, network, market) => __awaiter(void 0, void 0, void 0, function* () { return _getAaveV3ReserveTokenAddresses(getViemProvider(provider, network, { batch: { multicall: true } }), network, market); });
+/**
+ * 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.
+ */
+export const _getAaveV3HistoricalBalance = (provider, network, market, address, block, reserveTokens) => __awaiter(void 0, void 0, void 0, function* () {
+    const empty = {
+        block, suppliedUsd: '0', borrowedUsd: '0', netUsd: '0',
+    };
+    if (!address)
+        return empty;
+    const tokens = reserveTokens || (yield _getAaveV3ReserveTokenAddresses(provider, network, market));
+    const entries = Object.values(tokens);
+    if (!entries.length)
+        return empty;
+    const erc20Abi = getConfigContractAbi('Erc20');
+    const blockNumber = BigInt(block);
+    // supply = aToken.balanceOf, debt = variableDebtToken.balanceOf + stableDebtToken.balanceOf, all at the block.
+    const balanceContracts = 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],
+        },
+    ]));
+    // @ts-ignore market.provider is a valid config key at runtime
+    const providerAbi = getConfigContractAbi(market.provider, network);
+    const [balanceResults, oracleAddress] = yield Promise.all([
+        // @ts-ignore
+        provider.multicall({ contracts: balanceContracts, allowFailure: true, blockNumber }),
+        // resolve the oracle that was active at the block (Aave can rotate the oracle over time).
+        // No catch: if this read fails (bad archive node, rate limit, ...) we must surface the failure
+        // rather than silently returning $0 — the caller renders a gap instead of a misleading zero.
+        // @ts-ignore readContract exists on the public client returned by getViemProvider
+        provider.readContract({
+            address: market.providerAddress,
+            abi: providerAbi,
+            functionName: 'getPriceOracle',
+            blockNumber,
+        }),
+    ]);
+    // A totally failed balance read must not masquerade as a real $0 balance — throw so the caller
+    // can distinguish "fetch failed" (gap) from "position was empty" (genuine 0).
+    const anyBalanceRead = balanceResults.some((r) => (r === null || r === void 0 ? void 0 : r.status) === 'success');
+    if (!anyBalanceRead)
+        throw new Error(`AaveV3 historical balance: all balance reads failed at block ${block}`);
+    if (!oracleAddress)
+        throw new Error(`AaveV3 historical balance: oracle unavailable at block ${block}`);
+    const activeAssets = entries.map((e, i) => {
+        const supplyRes = balanceResults[i * 3];
+        const varDebtRes = balanceResults[(i * 3) + 1];
+        const stableDebtRes = balanceResults[(i * 3) + 2];
+        const supplied = (supplyRes === null || supplyRes === void 0 ? void 0 : supplyRes.status) === 'success' ? supplyRes.result.toString() : '0';
+        const varDebt = (varDebtRes === null || varDebtRes === void 0 ? void 0 : varDebtRes.status) === 'success' ? varDebtRes.result.toString() : '0';
+        const stableDebt = (stableDebtRes === null || stableDebtRes === void 0 ? void 0 : stableDebtRes.status) === 'success' ? stableDebtRes.result.toString() : '0';
+        const debt = new Dec(varDebt).add(stableDebt).toString();
+        return Object.assign(Object.assign({}, e), { supplied, debt });
+    }).filter((a) => a.supplied !== '0' || a.debt !== '0');
+    if (!activeAssets.length)
+        return empty;
+    const priceContracts = activeAssets.map((a) => ({
+        address: oracleAddress,
+        abi: AAVE_ORACLE_ABI,
+        functionName: 'getAssetPrice',
+        args: [a.underlyingAddress],
+    }));
+    // @ts-ignore
+    const priceResults = yield provider.multicall({ contracts: priceContracts, allowFailure: true, blockNumber });
+    let suppliedUsd = new Dec(0);
+    let borrowedUsd = new Dec(0);
+    activeAssets.forEach((a, i) => {
+        const priceRes = priceResults[i];
+        if ((priceRes === null || priceRes === void 0 ? void 0 : priceRes.status) !== 'success')
+            return;
+        const priceUsd = new Dec(priceRes.result.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(),
+    };
+});
+export const getAaveV3HistoricalBalance = (provider, network, market, address, block, reserveTokens) => __awaiter(void 0, void 0, void 0, function* () { return _getAaveV3HistoricalBalance(getViemProvider(provider, network, { batch: { multicall: true } }), network, market, address, block, reserveTokens); });
 export const _getAaveV3AccountData = (provider_1, network_1, address_1, extractedState_1, ...args_1) => __awaiter(void 0, [provider_1, network_1, address_1, extractedState_1, ...args_1], void 0, function* (provider, network, address, extractedState, blockNumber = 'latest') {
     const { selectedMarket: market, assetsData, eModeCategoriesData, } = extractedState;
     let payload = Object.assign(Object.assign({}, EMPTY_AAVE_DATA), { lastUpdated: Date.now() });

package/esm/aaveV4/merkl.js

@@ -7,12 +7,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import Dec from 'decimal.js';
 import { aprToApy } from '../moneymarket';
 import { fetchAllMerklOpportunities } from '../services/merkl';
 import { IncentiveKind, IncentiveSide, OpportunityAction, OpportunityStatus, } from '../types';
 /**
  * Merkl tags Aave V4 reward campaigns by scope via the `type` field:
- *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW   → reward tied to a hub asset
+ *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW / AAVE_V4_HUB_NET_LENDING → hub asset
  *   - AAVE_V4_SPOKE_SUPPLY / AAVE_V4_SPOKE_BORROW → reward tied to a spoke reserve
  * Embedded campaign params provide the exact on-chain identifiers. Token addresses cannot safely
  * identify Aave V4 rewards because one spoke can expose the same underlying from multiple hubs.
@@ -39,9 +40,19 @@ export const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
         .filter((o) => o.status === OpportunityStatus.LIVE)
         .filter((o) => typeof o.type === 'string' && o.type.startsWith('AAVE_V4_'))
         .forEach((o) => {
-        var _a, _b;
+        var _a, _b, _c;
         const side = o.action === OpportunityAction.BORROW ? IncentiveSide.Borrow : IncentiveSide.Supply;
-        const incentive = buildIncentive(o);
+        const now = Date.now() / 1000;
+        const methods = (_a = o.campaigns) === null || _a === void 0 ? void 0 : _a.filter((c) => (c.startTimestamp === undefined || c.startTimestamp <= now)
+            && (c.endTimestamp === undefined || c.endTimestamp > now)).map((c) => { var _a, _b; return (_b = (_a = c.params) === null || _a === void 0 ? void 0 : _a.distributionMethodParameters) === null || _b === void 0 ? void 0 : _b.distributionMethod; });
+        // An opportunity-level APR cannot be split between simultaneous net and additive campaigns.
+        if (side === IncentiveSide.Supply && (methods === null || methods === void 0 ? void 0 : methods.includes('AAVE_V4_NET_APR'))
+            && methods.some((method) => !!method && method !== 'AAVE_V4_NET_APR'))
+            return;
+        const incentive = Object.assign(Object.assign({}, buildIncentive(o)), { 
+            // Missing methods keep the existing target-yield behavior.
+            isAdditiveReward: side === IncentiveSide.Supply && !!(methods === null || methods === void 0 ? void 0 : methods.length)
+                && methods.every((method) => !!method && method !== 'AAVE_V4_NET_APR') });
         // one opportunity can span several campaigns (e.g. renewed periods), so campaign identity is
         // collected per scope key before the reward entries are written
         const idsByKey = {};
@@ -54,11 +65,13 @@ export const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
                 idsByKey[key].parentCampaignIds.add(campaign.parentCampaignId);
         };
         if (o.type.includes('HUB')) {
-            (_a = o.campaigns) === null || _a === void 0 ? void 0 : _a.forEach((c) => {
-                var _a;
-                if (!((_a = c.params) === null || _a === void 0 ? void 0 : _a.hubAddress) || c.params.assetId === undefined || c.params.assetId === null)
+            (_b = o.campaigns) === null || _b === void 0 ? void 0 : _b.forEach((c) => {
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+                const hubAddress = (_b = (_a = c.params) === null || _a === void 0 ? void 0 : _a.hubAddress) !== null && _b !== void 0 ? _b : (_e = (_d = (_c = c.params) === null || _c === void 0 ? void 0 : _c.distributionMethodParameters) === null || _d === void 0 ? void 0 : _d.distributionSettings) === null || _e === void 0 ? void 0 : _e.hubAddress;
+                const assetId = (_g = (_f = c.params) === null || _f === void 0 ? void 0 : _f.assetId) !== null && _g !== void 0 ? _g : (_k = (_j = (_h = c.params) === null || _h === void 0 ? void 0 : _h.distributionMethodParameters) === null || _j === void 0 ? void 0 : _j.distributionSettings) === null || _k === void 0 ? void 0 : _k.assetId;
+                if (!hubAddress || assetId === undefined || assetId === null)
                     return;
-                collect(scopeKey(c.params.hubAddress, c.params.assetId), c);
+                collect(scopeKey(hubAddress, assetId), c);
             });
             Object.entries(idsByKey).forEach(([key, ids]) => {
                 if (!result.hub[key])
@@ -67,7 +80,7 @@ export const buildAaveV4MerklRewardMap = (opportunities, chainId) => {
             });
         }
         else if (o.type.includes('SPOKE')) {
-            (_b = o.campaigns) === null || _b === void 0 ? void 0 : _b.forEach((c) => {
+            (_c = o.campaigns) === null || _c === void 0 ? void 0 : _c.forEach((c) => {
                 var _a;
                 if (!((_a = c.params) === null || _a === void 0 ? void 0 : _a.spokeAddress) || c.params.reserveId === undefined || c.params.reserveId === null)
                     return;
@@ -86,7 +99,7 @@ export const getAaveV4MerkleCampaigns = (chainId) => __awaiter(void 0, void 0, v
     try {
         const opportunities = yield fetchAllMerklOpportunities({
             mainProtocolId: 'aave',
-            type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
+            type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_HUB_NET_LENDING,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
             status: OpportunityStatus.LIVE,
             campaigns: 'true',
         });
@@ -107,5 +120,7 @@ export const attachAaveV4MerklIncentives = (asset, spokeAddress, campaigns) => {
     const baseBorrow = asset.borrowIncentives || [];
     const spokeScoped = spokeAddress ? campaigns.spoke[scopeKey(spokeAddress, asset.reserveId)] : undefined;
     const hubScoped = asset.hub ? campaigns.hub[scopeKey(asset.hub, asset.assetId)] : undefined;
-    return Object.assign(Object.assign({}, asset), { spokeSupplyIncentives: ((_a = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.supply) === null || _a === void 0 ? void 0 : _a.length) ? [...baseSupply, ...spokeScoped.supply] : baseSupply, spokeBorrowIncentives: ((_b = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.borrow) === null || _b === void 0 ? void 0 : _b.length) ? [...baseBorrow, ...spokeScoped.borrow] : baseBorrow, hubSupplyIncentives: ((_c = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.supply) === null || _c === void 0 ? void 0 : _c.length) ? [...baseSupply, ...hubScoped.supply] : baseSupply, hubBorrowIncentives: ((_d = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.borrow) === null || _d === void 0 ? void 0 : _d.length) ? [...baseBorrow, ...hubScoped.borrow] : baseBorrow });
+    // Net-APR campaigns top up native yield; additive campaigns pay their APR on top.
+    const supplyRewards = (rewards = []) => rewards.map((reward) => (Object.assign(Object.assign({}, reward), { apy: reward.isAdditiveReward ? reward.apy : Dec.max(0, new Dec(reward.apy).minus(asset.supplyRate || 0)).toString() })));
+    return Object.assign(Object.assign({}, asset), { spokeSupplyIncentives: ((_a = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.supply) === null || _a === void 0 ? void 0 : _a.length) ? [...baseSupply, ...supplyRewards(spokeScoped.supply)] : baseSupply, spokeBorrowIncentives: ((_b = spokeScoped === null || spokeScoped === void 0 ? void 0 : spokeScoped.borrow) === null || _b === void 0 ? void 0 : _b.length) ? [...baseBorrow, ...spokeScoped.borrow] : baseBorrow, hubSupplyIncentives: ((_c = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.supply) === null || _c === void 0 ? void 0 : _c.length) ? [...baseSupply, ...supplyRewards(hubScoped.supply)] : baseSupply, hubBorrowIncentives: ((_d = hubScoped === null || hubScoped === void 0 ? void 0 : hubScoped.borrow) === null || _d === void 0 ? void 0 : _d.length) ? [...baseBorrow, ...hubScoped.borrow] : baseBorrow });
 };

package/esm/types/merkl.d.ts

@@ -11,6 +11,8 @@ export declare enum OpportunityStatus {
 export type MerklCampaign = {
     id: string;
     campaignId: string;
+    startTimestamp?: number;
+    endTimestamp?: number;
     /**
      * Merkl-internal `id` of the parent campaign — set on child campaigns, which re-publish a hub
      * (parent) campaign's reward scoped to a single spoke reserve. Absent on standalone campaigns,
@@ -24,6 +26,13 @@ export type MerklCampaign = {
         hubAddress?: EthAddress;
         hubAssetId?: string | number;
         assetId?: string | number;
+        distributionMethodParameters?: {
+            distributionMethod?: string;
+            distributionSettings?: {
+                hubAddress?: EthAddress;
+                assetId?: string | number;
+            };
+        };
     };
 };
 export type MerklOpportunity = {
@@ -102,6 +111,7 @@ export type MerkleRewardMap = Record<EthAddress, {
 export type AaveV4MerklIncentive = IncentiveData & {
     campaignIds?: string[];
     parentCampaignIds?: string[];
+    isAdditiveReward?: boolean;
 };
 export type AaveV4MerklScopedReward = {
     [side in IncentiveSide]?: AaveV4MerklIncentive[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defisaver/positions-sdk",
-  "version": "2.1.156",
+  "version": "2.1.157-pos-history-dev",
   "description": "",
   "main": "./cjs/index.js",
   "module": "./esm/index.js",

package/src/aaveV3/index.ts

@@ -6,6 +6,7 @@ import {
   AaveIncentivesControllerViem,
   AaveV3ViewContractViem,
   createViemContractFromConfigFunc,
+  getConfigContractAbi,
   StkAAVEViem,
 } from '../contracts';
 import { aaveAnyGetAggregatedPositionData, aaveV3IsInIsolationMode, aaveV3IsInSiloedMode } from '../helpers/aaveHelpers';
@@ -430,6 +431,195 @@ 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.
+ */
+
+// 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 });
+
+  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);
+
+/**
+ * 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.
+ */
+export const _getAaveV3HistoricalBalance = async (
+  provider: Client,
+  network: NetworkNumber,
+  market: AaveMarketInfo,
+  address: EthAddress,
+  block: number,
+  reserveTokens?: AaveV3ReserveTokenAddresses,
+): 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 erc20Abi = getConfigContractAbi('Erc20');
+  const blockNumber = BigInt(block);
+
+  // supply = aToken.balanceOf, debt = variableDebtToken.balanceOf + stableDebtToken.balanceOf, all at the block.
+  const balanceContracts = 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],
+    },
+  ]));
+
+  // @ts-ignore market.provider is a valid config key at runtime
+  const providerAbi = getConfigContractAbi(market.provider, network);
+
+  const [balanceResults, oracleAddress] = await Promise.all([
+    // @ts-ignore
+    provider.multicall({ contracts: balanceContracts, allowFailure: true, blockNumber }),
+    // resolve the oracle that was active at the block (Aave can rotate the oracle over time).
+    // No catch: if this read fails (bad archive node, rate limit, ...) we must surface the failure
+    // rather than silently returning $0 — the caller renders a gap instead of a misleading zero.
+    // @ts-ignore readContract exists on the public client returned by getViemProvider
+    provider.readContract({
+      address: market.providerAddress as EthAddress,
+      abi: providerAbi as any,
+      functionName: 'getPriceOracle',
+      blockNumber,
+    }),
+  ]);
+
+  // A totally failed balance read must not masquerade as a real $0 balance — throw so the caller
+  // can distinguish "fetch failed" (gap) from "position was empty" (genuine 0).
+  const anyBalanceRead = (balanceResults as any[]).some((r) => r?.status === 'success');
+  if (!anyBalanceRead) throw new Error(`AaveV3 historical balance: all balance reads failed at block ${block}`);
+  if (!oracleAddress) throw new Error(`AaveV3 historical balance: oracle unavailable at block ${block}`);
+
+  const activeAssets = 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');
+
+  if (!activeAssets.length) return empty;
+
+  const priceContracts = activeAssets.map((a) => ({
+    address: oracleAddress as EthAddress,
+    abi: AAVE_ORACLE_ABI,
+    functionName: 'getAssetPrice',
+    args: [a.underlyingAddress],
+  }));
+
+  // @ts-ignore
+  const priceResults = await provider.multicall({ contracts: priceContracts, allowFailure: true, blockNumber });
+
+  let suppliedUsd = new Dec(0);
+  let borrowedUsd = new Dec(0);
+  activeAssets.forEach((a, i) => {
+    const priceRes = priceResults[i];
+    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(),
+  };
+};
+
+export const getAaveV3HistoricalBalance = async (
+  provider: EthereumProvider,
+  network: NetworkNumber,
+  market: AaveMarketInfo,
+  address: EthAddress,
+  block: number,
+  reserveTokens?: AaveV3ReserveTokenAddresses,
+): Promise<AaveV3HistoricalBalance> => _getAaveV3HistoricalBalance(getViemProvider(provider, network, { batch: { multicall: true } }), network, market, address, block, reserveTokens);
+
 export const _getAaveV3AccountData = async (provider: Client, network: NetworkNumber, address: EthAddress, extractedState: any, blockNumber: 'latest' | number = 'latest'): Promise<AaveV3PositionData> => {
   const {
     selectedMarket: market, assetsData, eModeCategoriesData,

package/src/aaveV4/merkl.ts

@@ -1,7 +1,9 @@
+import Dec from 'decimal.js';
 import { aprToApy } from '../moneymarket';
 import { fetchAllMerklOpportunities } from '../services/merkl';
 import {
   AaveV4MerklRewardMap,
+  AaveV4MerklIncentive,
   AaveV4ReserveAssetData,
   IncentiveData,
   IncentiveKind,
@@ -15,7 +17,7 @@ import {
 
 /**
  * Merkl tags Aave V4 reward campaigns by scope via the `type` field:
- *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW   → reward tied to a hub asset
+ *   - AAVE_V4_HUB_SUPPLY / AAVE_V4_HUB_BORROW / AAVE_V4_HUB_NET_LENDING → hub asset
  *   - AAVE_V4_SPOKE_SUPPLY / AAVE_V4_SPOKE_BORROW → reward tied to a spoke reserve
  * Embedded campaign params provide the exact on-chain identifiers. Token addresses cannot safely
  * identify Aave V4 rewards because one spoke can expose the same underlying from multiple hubs.
@@ -46,7 +48,20 @@ export const buildAaveV4MerklRewardMap = (opportunities: MerklOpportunity[], cha
     .filter((o) => typeof o.type === 'string' && o.type.startsWith('AAVE_V4_'))
     .forEach((o) => {
       const side = o.action === OpportunityAction.BORROW ? IncentiveSide.Borrow : IncentiveSide.Supply;
-      const incentive = buildIncentive(o);
+      const now = Date.now() / 1000;
+      const methods = o.campaigns
+        ?.filter((c) => (c.startTimestamp === undefined || c.startTimestamp <= now)
+          && (c.endTimestamp === undefined || c.endTimestamp > now))
+        .map((c) => c.params?.distributionMethodParameters?.distributionMethod);
+      // An opportunity-level APR cannot be split between simultaneous net and additive campaigns.
+      if (side === IncentiveSide.Supply && methods?.includes('AAVE_V4_NET_APR')
+        && methods.some((method) => !!method && method !== 'AAVE_V4_NET_APR')) return;
+      const incentive = {
+        ...buildIncentive(o),
+        // Missing methods keep the existing target-yield behavior.
+        isAdditiveReward: side === IncentiveSide.Supply && !!methods?.length
+          && methods.every((method) => !!method && method !== 'AAVE_V4_NET_APR'),
+      };
       // one opportunity can span several campaigns (e.g. renewed periods), so campaign identity is
       // collected per scope key before the reward entries are written
       const idsByKey: Record<string, { campaignIds: Set<string>, parentCampaignIds: Set<string> }> = {};
@@ -58,8 +73,10 @@ export const buildAaveV4MerklRewardMap = (opportunities: MerklOpportunity[], cha
 
       if (o.type.includes('HUB')) {
         o.campaigns?.forEach((c) => {
-          if (!c.params?.hubAddress || c.params.assetId === undefined || c.params.assetId === null) return;
-          collect(scopeKey(c.params.hubAddress, c.params.assetId), c);
+          const hubAddress = c.params?.hubAddress ?? c.params?.distributionMethodParameters?.distributionSettings?.hubAddress;
+          const assetId = c.params?.assetId ?? c.params?.distributionMethodParameters?.distributionSettings?.assetId;
+          if (!hubAddress || assetId === undefined || assetId === null) return;
+          collect(scopeKey(hubAddress, assetId), c);
         });
         Object.entries(idsByKey).forEach(([key, ids]) => {
           if (!result.hub[key]) result.hub[key] = {};
@@ -84,7 +101,7 @@ export const getAaveV4MerkleCampaigns = async (chainId: NetworkNumber): Promise<
   try {
     const opportunities = await fetchAllMerklOpportunities({
       mainProtocolId: 'aave',
-      type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
+      type: 'AAVE_V4_HUB_SUPPLY,AAVE_V4_HUB_BORROW,AAVE_V4_HUB_NET_LENDING,AAVE_V4_SPOKE_SUPPLY,AAVE_V4_SPOKE_BORROW',
       status: OpportunityStatus.LIVE,
       campaigns: 'true',
     });
@@ -105,12 +122,17 @@ export const attachAaveV4MerklIncentives = (asset: AaveV4ReserveAssetData, spoke
 
   const spokeScoped = spokeAddress ? campaigns.spoke[scopeKey(spokeAddress, asset.reserveId)] : undefined;
   const hubScoped = asset.hub ? campaigns.hub[scopeKey(asset.hub, asset.assetId)] : undefined;
+  // Net-APR campaigns top up native yield; additive campaigns pay their APR on top.
+  const supplyRewards = (rewards: AaveV4MerklIncentive[] = []) => rewards.map((reward) => ({
+    ...reward,
+    apy: reward.isAdditiveReward ? reward.apy : Dec.max(0, new Dec(reward.apy).minus(asset.supplyRate || 0)).toString(),
+  }));
 
   return {
     ...asset,
-    spokeSupplyIncentives: spokeScoped?.supply?.length ? [...baseSupply, ...spokeScoped.supply] : baseSupply,
+    spokeSupplyIncentives: spokeScoped?.supply?.length ? [...baseSupply, ...supplyRewards(spokeScoped.supply)] : baseSupply,
     spokeBorrowIncentives: spokeScoped?.borrow?.length ? [...baseBorrow, ...spokeScoped.borrow] : baseBorrow,
-    hubSupplyIncentives: hubScoped?.supply?.length ? [...baseSupply, ...hubScoped.supply] : baseSupply,
+    hubSupplyIncentives: hubScoped?.supply?.length ? [...baseSupply, ...supplyRewards(hubScoped.supply)] : baseSupply,
     hubBorrowIncentives: hubScoped?.borrow?.length ? [...baseBorrow, ...hubScoped.borrow] : baseBorrow,
   };
 };

package/src/types/merkl.ts

@@ -14,6 +14,8 @@ export enum OpportunityStatus {
 export type MerklCampaign = {
   id: string;
   campaignId: string;
+  startTimestamp?: number;
+  endTimestamp?: number;
   /**
    * Merkl-internal `id` of the parent campaign — set on child campaigns, which re-publish a hub
    * (parent) campaign's reward scoped to a single spoke reserve. Absent on standalone campaigns,
@@ -27,6 +29,13 @@ export type MerklCampaign = {
     hubAddress?: EthAddress;
     hubAssetId?: string | number;
     assetId?: string | number;
+    distributionMethodParameters?: {
+      distributionMethod?: string;
+      distributionSettings?: {
+        hubAddress?: EthAddress;
+        assetId?: string | number;
+      };
+    };
   };
 };
 
@@ -100,6 +109,7 @@ export type MerkleRewardMap = Record<EthAddress, { supply?: MerkleRewardInfo; bo
 export type AaveV4MerklIncentive = IncentiveData & {
   campaignIds?: string[];
   parentCampaignIds?: string[];
+  isAdditiveReward?: boolean;
 };
 
 export type AaveV4MerklScopedReward = { [side in IncentiveSide]?: AaveV4MerklIncentive[] };