@defisaver/positions-sdk 2.1.169-custom-fetching-dev → 2.1.169-custom-fetching-3-dev

package/src/services/merkl.ts

@@ -1,31 +1,164 @@
-import { MerklOpportunity } from '../types';
+import {
+  MerklAprRecord, MerklCampaignListItem, MerklOpportunity, OpportunityStatus,
+} from '../types';
 import { LONGER_TIMEOUT } from './utils';
 
-const MERKL_OPPORTUNITIES_URL = 'https://fe.defisaver.com/api/merkl/opportunities';
+const MERKL_API_URL = 'https://fe.defisaver.com/api/merkl';
+const MERKL_OPPORTUNITIES_URL = `${MERKL_API_URL}/opportunities`;
+const MERKL_CAMPAIGNS_URL = `${MERKL_API_URL}/campaigns`;
+
+// Merkl caps list pages at 100 items; opportunity ids are batched below that so a single page
+// covers every id in the batch.
+const MERKL_MAX_PAGE_ITEMS = 100;
+const OPPORTUNITY_ID_BATCH_SIZE = 50;
+// APR history is fetched per opportunity, so historical lookups are throttled to keep a block with
+// many live campaigns from firing every request at once.
+const APR_RECORDS_CONCURRENCY = 10;
+const SECONDS_PER_DAY = 24 * 60 * 60;
+
+const merklGet = async <T>(url: string, query: Record<string, string>, label: string): Promise<T> => {
+  const res = await fetch(`${url}?${new URLSearchParams(query)}`, { signal: AbortSignal.timeout(LONGER_TIMEOUT) });
+  if (!res.ok) throw new Error(`Failed to fetch Merkl ${label}`);
+  return res.json();
+};
 
 /**
- * Fetches every page matching the query. Merkl returns 20 opportunities by default, so omitting
- * `items` and advancing `page` avoids imposing a client-side maximum on the result set.
+ * Fetches every page matching the query, advancing `page` until an empty page comes back. When
+ * `items` is omitted, Merkl's default page size applies and no client-side maximum is imposed.
  */
-export const fetchAllMerklOpportunities = async (query: Record<string, string>): Promise<MerklOpportunity[]> => {
-  const opportunities: MerklOpportunity[] = [];
+const fetchAllMerklPages = async <T>(url: string, query: Record<string, string>, label: string, items?: number): Promise<T[]> => {
+  const results: T[] = [];
   let page = 0;
-  let pageOpportunities: MerklOpportunity[];
+  let pageResults: T[];
 
   do {
-    const searchParams = new URLSearchParams({ ...query, page: page.toString() });
-    const res = await fetch(`${MERKL_OPPORTUNITIES_URL}?${searchParams}`, { // eslint-disable-line no-await-in-loop
-      signal: AbortSignal.timeout(LONGER_TIMEOUT),
-    });
-    if (!res.ok) throw new Error(`Failed to fetch Merkl opportunities page ${page}`);
+    const pageQuery = { ...query, page: page.toString(), ...(items ? { items: items.toString() } : {}) };
+    const data = await merklGet<unknown>(url, pageQuery, `${label} page ${page}`); // eslint-disable-line no-await-in-loop
+    if (!Array.isArray(data)) throw new Error(`Invalid Merkl ${label} response on page ${page}`);
 
-    const data = await res.json(); // eslint-disable-line no-await-in-loop
-    if (!Array.isArray(data)) throw new Error(`Invalid Merkl opportunities response on page ${page}`);
-
-    pageOpportunities = data as MerklOpportunity[];
-    opportunities.push(...pageOpportunities);
+    pageResults = data as T[];
+    results.push(...pageResults);
     page += 1;
-  } while (pageOpportunities.length > 0);
+  } while (pageResults.length > 0);
+
+  return results;
+};
+
+/**
+ * Fetches every opportunity matching the query. Merkl returns 20 opportunities by default, so omitting
+ * `items` and advancing `page` avoids imposing a client-side maximum on the result set.
+ */
+export const fetchAllMerklOpportunities = async (query: Record<string, string>): Promise<MerklOpportunity[]> => (
+  fetchAllMerklPages<MerklOpportunity>(MERKL_OPPORTUNITIES_URL, query, 'opportunities')
+);
+
+/** Fetches every campaign matching the query, e.g. `{ mainProtocolId: 'aave', status: 'LIVE,PAST' }`. */
+export const fetchAllMerklCampaigns = async (query: Record<string, string>): Promise<MerklCampaignListItem[]> => (
+  fetchAllMerklPages<MerklCampaignListItem>(MERKL_CAMPAIGNS_URL, query, 'campaigns', MERKL_MAX_PAGE_ITEMS)
+);
 
-  return opportunities;
+/**
+ * Fetches the opportunities with the given Merkl-internal ids, regardless of their current status.
+ * Ids Merkl no longer serves (hidden or test campaigns) are simply absent from the result.
+ */
+export const fetchMerklOpportunitiesByIds = async (ids: string[]): Promise<MerklOpportunity[]> => {
+  const batches: string[][] = [];
+  for (let i = 0; i < ids.length; i += OPPORTUNITY_ID_BATCH_SIZE) batches.push(ids.slice(i, i + OPPORTUNITY_ID_BATCH_SIZE));
+  const results = await Promise.all(batches.map((batch) => merklGet<unknown>(
+    MERKL_OPPORTUNITIES_URL,
+    { id: batch.join(','), items: MERKL_MAX_PAGE_ITEMS.toString() },
+    'opportunities by id',
+  )));
+  return results.flatMap((data) => {
+    if (!Array.isArray(data)) throw new Error('Invalid Merkl opportunities by id response');
+    return data as MerklOpportunity[];
+  });
 };
+
+/**
+ * Returns the reward APR Merkl recorded for the opportunity at the given unix timestamp (seconds),
+ * or `undefined` when no campaign was computing for it then. Records are hourly buckets keyed by
+ * their start, newest first, so the first bucket at or before the timestamp carries the value in
+ * force at that moment; the window is a day wide to tolerate computation gaps.
+ */
+export const fetchMerklOpportunityAprAt = async (opportunityId: string, timestamp: number): Promise<number | undefined> => {
+  const records = await merklGet<unknown>(`${MERKL_OPPORTUNITIES_URL}/${opportunityId}/apr-records`, {
+    grain: 'HOUR',
+    from: (timestamp - SECONDS_PER_DAY).toString(),
+    to: timestamp.toString(),
+    items: '1',
+  }, `APR records for opportunity ${opportunityId}`);
+  if (!Array.isArray(records)) throw new Error(`Invalid Merkl APR records response for opportunity ${opportunityId}`);
+  return (records as MerklAprRecord[])[0]?.apr;
+};
+
+const mapWithConcurrency = async <T, R>(items: T[], concurrency: number, fn: (item: T) => Promise<R>): Promise<R[]> => {
+  const results: R[] = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    results.push(...await Promise.all(items.slice(i, i + concurrency).map(fn))); // eslint-disable-line no-await-in-loop
+  }
+  return results;
+};
+
+/**
+ * Reconstructs the opportunities that were live at `timestamp` (unix seconds), shaped like the
+ * live listing so the per-protocol reward mappers can consume either without knowing which they got:
+ *   1. campaigns for the protocol (and chain, when the query names one) whose [start, end] covers
+ *      the timestamp identify the opportunities that were rewarded then — the live listing can't,
+ *      since campaigns live then are mostly PAST now and ones live now didn't exist then;
+ *   2. those opportunities are loaded by id (works for PAST ones too) and narrowed to `query.type`;
+ *   3. each one's `apr` is replaced with the value Merkl recorded at the timestamp, and ones with no
+ *      record then are dropped, since nothing was being computed for them.
+ * `status` is forced to LIVE so status filters downstream keep working, `campaigns` carries the
+ * covering campaigns, and a reward token breakdown is synthesized from the campaign's reward token
+ * when Merkl no longer serves one for the opportunity (it drops them once an opportunity is PAST).
+ * `query.status` is ignored: it describes the present, not the requested moment.
+ */
+export const fetchMerklOpportunitiesAt = async (query: Record<string, string>, timestamp: number): Promise<MerklOpportunity[]> => {
+  const campaignQuery: Record<string, string> = { status: 'LIVE,PAST', endTimestamp: timestamp.toString() };
+  if (query.mainProtocolId) campaignQuery.mainProtocolId = query.mainProtocolId;
+  if (query.chainId) campaignQuery.chainId = query.chainId;
+
+  // `endTimestamp` only narrows the listing upstream — the exact window check happens here
+  const campaigns = (await fetchAllMerklCampaigns(campaignQuery))
+    .filter((c) => c.opportunityId && +(c.startTimestamp ?? 0) <= timestamp && timestamp <= +(c.endTimestamp ?? 0));
+  const campaignsByOpportunity: Record<string, MerklCampaignListItem[]> = {};
+  campaigns.forEach((c) => {
+    if (!campaignsByOpportunity[c.opportunityId]) campaignsByOpportunity[c.opportunityId] = [];
+    campaignsByOpportunity[c.opportunityId].push(c);
+  });
+  const opportunityIds = Object.keys(campaignsByOpportunity);
+  if (!opportunityIds.length) return [];
+
+  const types = query.type?.split(',').filter(Boolean);
+  const opportunities = (await fetchMerklOpportunitiesByIds(opportunityIds))
+    .filter((o) => !types?.length || types.includes(o.type));
+
+  const aprs = await mapWithConcurrency(opportunities, APR_RECORDS_CONCURRENCY, (o) => fetchMerklOpportunityAprAt(o.id, timestamp));
+
+  return opportunities.flatMap((o, i) => {
+    const apr = aprs[i];
+    if (apr === undefined) return [];
+    const coveringCampaigns = campaignsByOpportunity[o.id];
+    const rewardToken = coveringCampaigns.find((c) => c.rewardToken)?.rewardToken;
+    const hasBreakdown = !!o.rewardsRecord?.breakdowns?.length;
+    return [{
+      ...o,
+      status: OpportunityStatus.LIVE,
+      apr,
+      campaigns: coveringCampaigns,
+      rewardsRecord: hasBreakdown || !rewardToken ? o.rewardsRecord : {
+        ...o.rewardsRecord,
+        breakdowns: [{ token: rewardToken, campaignId: coveringCampaigns[0].campaignId } as MerklOpportunity['rewardsRecord']['breakdowns'][number]],
+      },
+    }];
+  });
+};
+
+/**
+ * Live opportunities when no timestamp is given, otherwise the opportunities as they were at that
+ * unix timestamp (seconds) — see `fetchMerklOpportunitiesAt`.
+ */
+export const fetchMerklOpportunities = async (query: Record<string, string>, asOfTimestamp?: number): Promise<MerklOpportunity[]> => (
+  asOfTimestamp === undefined ? fetchAllMerklOpportunities(query) : fetchMerklOpportunitiesAt(query, asOfTimestamp)
+);

package/src/services/priceService.ts

@@ -10,36 +10,39 @@ import {
   WeETHPriceFeedContractViem,
   WstETHPriceFeedContractViem,
 } from '../contracts';
-import { EthAddress, NetworkNumber, HexString } from '../types/common';
+import {
+  Blockish, EthAddress, NetworkNumber, HexString,
+} from '../types/common';
 import { getEthAmountForDecimals } from './utils';
+import { setViemBlockNumber } from './viem';
 import { USD_QUOTE } from '../constants';
 
-export const getEthPrice = async (client: Client) => {
+export const getEthPrice = async (client: Client, block: Blockish = 'latest') => {
   const contract = ETHPriceFeedContractViem(client, NetworkNumber.Eth);
-  const price = await contract.read.latestAnswer();
+  const price = await contract.read.latestAnswer(setViemBlockNumber(block));
   return new Dec(price.toString()).div(1e8).toString();
 };
 
-export const getUSDCPrice = async (client: Client) => {
+export const getUSDCPrice = async (client: Client, block: Blockish = 'latest') => {
   const contract = USDCPriceFeedContractViem(client, NetworkNumber.Eth);
-  const price = await contract.read.latestAnswer();
+  const price = await contract.read.latestAnswer(setViemBlockNumber(block));
   return new Dec(price.toString()).div(1e8).toString();
 };
 
-export const getCompPrice = async (client: Client) => {
+export const getCompPrice = async (client: Client, block: Blockish = 'latest') => {
   const contract = COMPPriceFeedContractViem(client, NetworkNumber.Eth);
-  const price = await contract.read.latestAnswer();
+  const price = await contract.read.latestAnswer(setViemBlockNumber(block));
   return new Dec(price.toString()).div(1e8).toString();
 };
 
-export const getWstETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth) => {
+export const getWstETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth, block: Blockish = 'latest') => {
   const wstETHFeedContract = WstETHPriceFeedContractViem(client, network);
   const ethFeedContract = ETHPriceFeedContractViem(client, network);
 
   const [ethPriceWei, wstETHRateWei, decimals] = await Promise.all([
-    ethFeedContract.read.latestAnswer(),
-    wstETHFeedContract.read.latestRoundData(),
-    wstETHFeedContract.read.decimals(),
+    ethFeedContract.read.latestAnswer(setViemBlockNumber(block)),
+    wstETHFeedContract.read.latestRoundData(setViemBlockNumber(block)),
+    wstETHFeedContract.read.decimals(setViemBlockNumber(block)),
   ]);
 
   const ethPrice = new Dec(ethPriceWei.toString()).div(1e8);
@@ -49,14 +52,14 @@ export const getWstETHPrice = async (client: Client, network: NetworkNumber = Ne
   return new Dec(ethPrice).mul(wstETHRate).toString();
 };
 
-export const getWeETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth) => {
+export const getWeETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth, block: Blockish = 'latest') => {
   const weETHFeedContract = WeETHPriceFeedContractViem(client, network);
   const ethFeedContract = ETHPriceFeedContractViem(client, network);
 
   const [ethPriceWei, weETHRateWei, decimals] = await Promise.all([
-    ethFeedContract.read.latestAnswer(),
-    weETHFeedContract.read.latestRoundData(),
-    weETHFeedContract.read.decimals(),
+    ethFeedContract.read.latestAnswer(setViemBlockNumber(block)),
+    weETHFeedContract.read.latestRoundData(setViemBlockNumber(block)),
+    weETHFeedContract.read.decimals(setViemBlockNumber(block)),
   ]);
 
   const ethPrice = new Dec(ethPriceWei.toString()).div(1e8);
@@ -66,11 +69,11 @@ export const getWeETHPrice = async (client: Client, network: NetworkNumber = Net
   return new Dec(ethPrice).mul(weETHRate).toString();
 };
 
-export const getWsrETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth) => {
+export const getWsrETHPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth, block: Blockish = 'latest') => {
   const feedRegistryContract = DFSFeedRegistryContractViem(client, network);
   const [ethPriceWei, wrsETHRateWei] = await Promise.all([
-    feedRegistryContract.read.latestRoundData([getAssetInfo('WETH', network).address as HexString, USD_QUOTE]),
-    feedRegistryContract.read.latestRoundData([getAssetInfo('wrsETH', network).address as HexString, getAssetInfo('WETH', network).address as HexString]),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('WETH', network).address as HexString, USD_QUOTE], setViemBlockNumber(block)),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('wrsETH', network).address as HexString, getAssetInfo('WETH', network).address as HexString], setViemBlockNumber(block)),
   ]);
 
   const ethPrice = new Dec(ethPriceWei[1].toString()).div(1e8);
@@ -80,11 +83,11 @@ export const getWsrETHPrice = async (client: Client, network: NetworkNumber = Ne
   return new Dec(ethPrice).mul(wrsETHRate).toString();
 };
 
-export const getSyrupUSDTPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth) => {
+export const getSyrupUSDTPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth, block: Blockish = 'latest') => {
   const feedRegistryContract = DFSFeedRegistryContractViem(client, network);
   const [usdtPriceWei, syrupUSDTRateWei] = await Promise.all([
-    feedRegistryContract.read.latestRoundData([getAssetInfo('USDT', network).address as HexString, USD_QUOTE]),
-    feedRegistryContract.read.latestRoundData([getAssetInfo('syrupUSDT', network).address as HexString, getAssetInfo('USDT', network).address as HexString]),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('USDT', network).address as HexString, USD_QUOTE], setViemBlockNumber(block)),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('syrupUSDT', network).address as HexString, getAssetInfo('USDT', network).address as HexString], setViemBlockNumber(block)),
   ]);
 
   const usdtPrice = new Dec(usdtPriceWei[1].toString()).div(1e8);
@@ -94,11 +97,11 @@ export const getSyrupUSDTPrice = async (client: Client, network: NetworkNumber =
   return new Dec(usdtPrice).mul(syrupUSDTPrice).toString();
 };
 
-export const getWstUSRPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth) => {
+export const getWstUSRPrice = async (client: Client, network: NetworkNumber = NetworkNumber.Eth, block: Blockish = 'latest') => {
   const feedRegistryContract = DFSFeedRegistryContractViem(client, network);
   const [usrPriceWei, wstUSRRateWei] = await Promise.all([
-    feedRegistryContract.read.latestRoundData([getAssetInfo('USR', network).address as HexString, USD_QUOTE]),
-    feedRegistryContract.read.latestRoundData([getAssetInfo('wstUSR', network).address as HexString, getAssetInfo('USR', network).address as HexString]),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('USR', network).address as HexString, USD_QUOTE], setViemBlockNumber(block)),
+    feedRegistryContract.read.latestRoundData([getAssetInfo('wstUSR', network).address as HexString, getAssetInfo('USR', network).address as HexString], setViemBlockNumber(block)),
   ]);
 
   const usrPrice = new Dec(usrPriceWei[1].toString()).div(1e8);
@@ -248,24 +251,24 @@ export const parseWeETHPriceCalls = (_ethPrice: string, weETHrateAnswer: string,
 };
 
 // this is a fixed version, the original version is above but requires to refactor comp v3 function, so it's easier to just copy the function for now
-export const getWstETHPriceFluid = async (client: PublicClient, network: NetworkNumber) => {
+export const getWstETHPriceFluid = async (client: PublicClient, network: NetworkNumber, block: Blockish = 'latest') => {
   const calls = getWstETHChainLinkPriceCalls(client, network);
-  const results = await client.multicall({ contracts: calls });
+  const results = await client.multicall({ contracts: calls, ...setViemBlockNumber(block) });
   // @ts-ignore
   const { ethPrice, wstETHRate } = parseWstETHPriceCalls(results[0].result!.toString(), results[1].result[1]!.toString(), results[2].result!.toString());
 
   return new Dec(ethPrice).mul(wstETHRate).toString();
 };
 
-export const getBTCPriceForFluid = async (client: PublicClient, network: NetworkNumber) => {
+export const getBTCPriceForFluid = async (client: PublicClient, network: NetworkNumber, block: Blockish = 'latest') => {
   const contract = BTCPriceFeedContractViem(client, network);
-  const price = await contract.read.latestAnswer();
+  const price = await contract.read.latestAnswer(setViemBlockNumber(block));
   return new Dec(price).div(1e8).toString();
 };
 
-export const getEthPriceForFluid = async (client: PublicClient, network: NetworkNumber) => {
+export const getEthPriceForFluid = async (client: PublicClient, network: NetworkNumber, block: Blockish = 'latest') => {
   const contract = ETHPriceFeedContractViem(client, network);
-  const price = await contract.read.latestAnswer();
+  const price = await contract.read.latestAnswer(setViemBlockNumber(block));
   return new Dec(price).div(1e8).toString();
 };
 

package/src/services/viem.ts

@@ -3,7 +3,9 @@ import {
   custom,
   encodeFunctionData,
   type Abi,
+  type Client,
 } from 'viem';
+import { getBlock } from 'viem/actions';
 import {
   arbitrum, base, mainnet, optimism, linea, plasma,
 } from 'viem/chains';
@@ -34,6 +36,20 @@ export const getViemProvider = (provider: EthereumProvider, network: NetworkNumb
   ...options,
 });
 
+/**
+ * Unix timestamp (seconds) of the block, for data sources keyed by time rather than block (Merkl
+ * reward history). `'latest'` resolves to `undefined` without an RPC call, since live sources need
+ * no timestamp. A numeric block costs one `eth_getBlockByNumber` unless the caller already knows
+ * its timestamp and passes it — flows that fetch many markets at one block resolve it once and
+ * hand it down.
+ */
+export const getBlockTimestamp = async (client: Client, block: Blockish, blockTimestamp?: number): Promise<number | undefined> => {
+  if (block === 'latest') return undefined;
+  if (blockTimestamp !== undefined) return blockTimestamp;
+  const { timestamp } = await getBlock(client, { blockNumber: BigInt(block) });
+  return Number(timestamp);
+};
+
 export const setViemBlockNumber = (block: Blockish) => {
   if (block === 'latest') return {};
   return { blockNumber: BigInt(block) };

package/src/spark/index.ts

@@ -62,7 +62,7 @@ export const sparkEmodeCategoriesMapping = (extractedState: { assetsData: SparkA
   return categoriesMapping;
 };
 
-export const _getSparkMarketsData = async (provider: Client, network: NetworkNumber, selectedMarket: SparkMarketData): Promise<SparkMarketsData> => {
+export const _getSparkMarketsData = async (provider: Client, network: NetworkNumber, selectedMarket: SparkMarketData, blockNumber: Blockish = 'latest'): Promise<SparkMarketsData> => {
   const marketAddress = selectedMarket.providerAddress;
 
   const loanInfoContract = SparkViewContractViem(provider, network);
@@ -70,8 +70,8 @@ export const _getSparkMarketsData = async (provider: Client, network: NetworkNum
 
   // eslint-disable-next-line prefer-const
   let [loanInfo, rewardInfo] = await Promise.all([
-    loanInfoContract.read.getFullTokensInfo([marketAddress, selectedMarket.assets.map(a => getAssetInfo(ethToWeth(a)).address) as EthAddress[]]),
-    sparkIncentivesContract.read.getReservesIncentivesData([marketAddress]),
+    loanInfoContract.read.getFullTokensInfo([marketAddress, selectedMarket.assets.map(a => getAssetInfo(ethToWeth(a)).address) as EthAddress[]], setViemBlockNumber(blockNumber)),
+    sparkIncentivesContract.read.getReservesIncentivesData([marketAddress], setViemBlockNumber(blockNumber)),
   ]);
 
   rewardInfo = rewardInfo.reduce((all: any, market: any) => {
@@ -246,7 +246,8 @@ export const getSparkMarketsData = async (
   provider: EthereumProvider,
   network: NetworkNumber,
   selectedMarket: SparkMarketData,
-): Promise<SparkMarketsData> => _getSparkMarketsData(getViemProvider(provider, network), network, selectedMarket);
+  blockNumber: Blockish = 'latest',
+): Promise<SparkMarketsData> => _getSparkMarketsData(getViemProvider(provider, network), network, selectedMarket, blockNumber);
 
 export const EMPTY_SPARK_DATA = {
   usedAssets: {},
@@ -287,6 +288,7 @@ export const _getSparkAccountData = async (
   network: NetworkNumber,
   address: EthAddress,
   extractedState: { selectedMarket: SparkMarketData, assetsData: SparkAssetsData, eModeCategoriesData: EModeCategoriesData },
+  blockNumber: Blockish = 'latest',
 ) => {
   const {
     selectedMarket: market, assetsData,
@@ -313,9 +315,9 @@ export const _getSparkAccountData = async (
   const middleAddressIndex = Math.floor(_addresses.length / 2); // split addresses in half to avoid gas limit by multicall
 
   const [userEMode, tokenBalances1, tokenBalances2] = await Promise.all([
-    lendingPoolContract.read.getUserEMode([address]),
-    loanInfoContract.read.getTokenBalances([marketAddress, address, _addresses.slice(0, middleAddressIndex) as EthAddress[]]),
-    loanInfoContract.read.getTokenBalances([marketAddress, address, _addresses.slice(middleAddressIndex, _addresses.length) as EthAddress[]]),
+    lendingPoolContract.read.getUserEMode([address], setViemBlockNumber(blockNumber)),
+    loanInfoContract.read.getTokenBalances([marketAddress, address, _addresses.slice(0, middleAddressIndex) as EthAddress[]], setViemBlockNumber(blockNumber)),
+    loanInfoContract.read.getTokenBalances([marketAddress, address, _addresses.slice(middleAddressIndex, _addresses.length) as EthAddress[]], setViemBlockNumber(blockNumber)),
   ]);
 
 
@@ -406,7 +408,8 @@ export const getSparkAccountData = async (
   network: NetworkNumber,
   address: EthAddress,
   extractedState: { selectedMarket: SparkMarketData, assetsData: SparkAssetsData, eModeCategoriesData: EModeCategoriesData },
-) => _getSparkAccountData(getViemProvider(provider, network), network, address, extractedState);
+  blockNumber: Blockish = 'latest',
+) => _getSparkAccountData(getViemProvider(provider, network), network, address, extractedState, blockNumber);
 
 export const getSparkFullPositionData = async (provider: EthereumProvider, network: NetworkNumber, address: EthAddress, market: SparkMarketData): Promise<SparkPositionData> => {
   const marketData = await getSparkMarketsData(provider, network, market);

package/src/types/merkl.ts

@@ -114,6 +114,26 @@ export type MerklOpportunity = {
   };
 };
 
+/** One entry of Merkl's campaign listing: a campaign plus the opportunity it rewards. */
+export type MerklCampaignListItem = MerklCampaign & {
+  opportunityId: string;
+  type: string;
+  rewardToken?: MerklOpportunity['rewardsRecord']['breakdowns'][number]['token'];
+};
+
+/** One bucket of an opportunity's APR history (`apr` is the last value recorded in the bucket). */
+export type MerklAprRecord = {
+  timestamp: string;
+  date: string;
+  apr: number;
+  open: number;
+  min: number;
+  max: number;
+  avg: number;
+  samples: number;
+  hasUntrustedContribution: boolean;
+};
+
 export type MerkleRewardInfo = { apy: string; rewardTokenSymbol: string, description: string, identifier: string };
 export type MerkleRewardMap = Record<EthAddress, { supply?: MerkleRewardInfo; borrow?: MerkleRewardInfo }>;
 

package/src/types/portfolio.ts

@@ -95,6 +95,8 @@ export interface CustomDeFiDataOptions {
   isSim?: boolean;
   /** viem multicall calldata cap in bytes; defaults to 250k (2k when isSim). */
   batchSize?: number;
+  /** Every read is made at this block; defaults to latest. */
+  blockNumber?: number;
 }
 
 export interface CustomDeFiData {

package/src/umbrella/index.ts

@@ -1,19 +1,20 @@
 import { Client } from 'viem';
 import { AaveUmbrellaViewViem, AaveV3ViewContractViem } from '../contracts';
-import { EthAddress, NetworkNumber } from '../types/common';
+import { Blockish, EthAddress, NetworkNumber } from '../types/common';
 import { compareAddresses, convertHybridArraysToObjects, getEthAmountForDecimals } from '../services/utils';
+import { setViemBlockNumber } from '../services/viem';
 import { findMatching, tokenEntries } from './umbrellaUtils';
 
 const umbrella = '0xD400fc38ED4732893174325693a63C30ee3881a8';
 const aaveOracle = '0x54586bE62E3c3580375aE3723C145253060Ca0C2';
 
-export const getUmbrellaData = async (provider: Client, network: NetworkNumber, address: EthAddress) => {
+export const getUmbrellaData = async (provider: Client, network: NetworkNumber, address: EthAddress, blockNumber: Blockish = 'latest') => {
   const umbrellaView = AaveUmbrellaViewViem(provider, network);
   const aaveV3View = AaveV3ViewContractViem(provider, network);
   const [tokensAggregatedData, additionalUmbrellaStakingData, userAggregatedData] = await Promise.all([
-    umbrellaView.read.getTokensAggregatedData([umbrella, aaveOracle]),
-    aaveV3View.read.getAdditionalUmbrellaStakingData([umbrella, address]),
-    umbrellaView.read.getUserAggregatedData([umbrella, address]),
+    umbrellaView.read.getTokensAggregatedData([umbrella, aaveOracle], setViemBlockNumber(blockNumber)),
+    aaveV3View.read.getAdditionalUmbrellaStakingData([umbrella, address], setViemBlockNumber(blockNumber)),
+    umbrellaView.read.getUserAggregatedData([umbrella, address], setViemBlockNumber(blockNumber)),
   ]);
 
   return Object.fromEntries(