@gearbox-protocol/sdk 18.3.1 → 18.4.0

package/dist/esm/permissionless/api/oracles/PermissionlessOracles.js

@@ -1,19 +1,55 @@
+import { getAssetType, getNetworkType, isRWAToken, isSupportedNetwork } from "../../../onchain/chain/chains.js";
+import { AP_PRICE_FEED_COMPRESSOR } from "../../../onchain/constants/address-provider.js";
 import { priceFeedDataSchema } from "../../../model/opportunities.schema.js";
+import { priceFeedCompressorAbi } from "../../../abi/compressors/priceFeedCompressor.js";
+import "../../../onchain/index.js";
+import { OffchainStatusError } from "../../../offchain/errors/OffchainStatusError.js";
 import { AbstractOffchainNamespace } from "../../../offchain/AbstractOffchainNamespace.js";
-import { getPrices } from "../../utils/price-update/get-prices.js";
-import { assetDetailsSchema, assetPricesSchema, priceFeedDetailsSchema, priceFeedMarketCapsSchema, priceFeedStoreSchema, pricesSchema } from "./schemas.js";
+import "../../deployment/addresses.js";
+import { AddressProviderContract } from "../../bindings/address-provider.js";
+import { getFeedDecimals, getLatestPrices, getPrices } from "../../utils/price-update/get-prices.js";
+import { byCentrality, feedKey, pricesByFeed, toCap, totalQuotas } from "./enrich.js";
+import { onchainPriceFeed } from "./onchain-feed.js";
+import { assetDetailsSchema, assetSummariesSchema, marketSlotsSchema, priceFeedDetailsSchema, priceFeedStoresSchema } from "./schemas.js";
+import { readFeedTrees, runStressTest } from "./stress/run.js";
+import { runAssetScores, runFeedPairScore } from "./score/run.js";
+import { erc20Abi, zeroAddress } from "viem";
 //#region src/permissionless/api/oracles/PermissionlessOracles.ts
 const GET_PRICES_GAS_LIMIT_BY_CHAIN_ID = { 143: 100000000n };
 const GET_PRICES_CHUNK_SIZE = 200;
 /**
+* What a market slot is: an oracle, a token, and whether it is the reserve
+* one. Not the market — a market that has switched oracles has rows under
+* each, and the slots are the old oracle's and the new one's separately.
+*/
+function slotKey(oracle, token, reserve) {
+	return `${oracle.toLowerCase()}:${token.toLowerCase()}:${reserve}`;
+}
+/** An unknown thrown value, as something a log line can carry. */
+function describe(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+/** The backend answered that it has no such feed. */
+function isNotFound(e) {
+	return e instanceof OffchainStatusError && e.status === 404;
+}
+/**
 * The price feeds of one chain: the PriceFeedStore as the backend has indexed
 * it, and the prices behind it.
 *
 * ```ts
 * const store = await permissionless.oracles.store({ chainId: 1 });
-* const { prices } = await permissionless.oracles.prices({ chainId: 1 });
+* const prices = await permissionless.oracles.getPrices(
+*   store.priceFeeds.map(({ address }) => ({ chainId: 1, address })),
+* );
 * ```
 *
+* The backend answers what it has indexed; anything that is only true at a
+* block — a price, a market cap, a quota in one currency, the period an
+* oracle holds for a slot — is read here, off the chain, and folded into what
+* it answered. That is why these reads mix a request with a multicall rather
+* than being either one.
+*
 * Read-only. What the store carries is decided on chain, so putting a feed
 * there is a batch the instance owner executes — see
 * {@link InstanceOwnerTransactions} — not a row a client writes here.
@@ -29,11 +65,64 @@ var PermissionlessOracles = class extends AbstractOffchainNamespace {
 	}
 	/**
 	* The store with the assets and feeds of one chain.
+	*
+	* {@link stores} narrowed to one and unwrapped, which is the whole of it:
+	* there is one route either way, and a chain the backend does not serve has
+	* no store to answer with rather than an empty one.
+	*
+	* @throws When the backend serves no store for the chain.
 	**/
 	async store({ chainId }) {
+		const [store] = await this.stores({ chainId });
+		if (!store) throw new Error(`no PriceFeedStore served for chain ${chainId}`);
+		return store;
+	}
+	/**
+	* The same stores for every chain the backend serves.
+	*
+	* One request rather than {@link store} per chain, which is what a page
+	* showing all of them would otherwise do: the backend assembles them in the
+	* same few queries it assembles one in, so the chains cost little more than
+	* the largest of them.
+	*
+	* Each entry names its own chain, so a store is never attributed by
+	* position. `chainId` narrows it to one, for a caller that wants the list
+	* shape either way.
+	*
+	* ```ts
+	* const stores = await permissionless.oracles.stores();
+	* ```
+	**/
+	async stores({ chainId } = {}) {
 		return this.getData({
-			path: `/pfs/${chainId}`,
-			schema: priceFeedStoreSchema
+			path: "/pfs/stores",
+			query: { chainId: chainId?.toString() },
+			schema: priceFeedStoresSchema
+		});
+	}
+	/**
+	* Every market slot in force, with the feed holding it and what the market
+	* has riding on it.
+	*
+	* The chain's whole slot table, which {@link feed} and {@link asset} answer
+	* one subject's slice of. What reads it this way is analysis over every
+	* market at once — which feed holds which slot, and what breaks if it
+	* lies — and asking a feed at a time would be a few hundred requests for
+	* the same rows.
+	*
+	* Served as indexed, with nothing folded in: the quotas are in each
+	* market's own underlying, as everywhere else, and pricing them is
+	* {@link getPrices} over the `underlyingPriceFeed` column.
+	*
+	* ```ts
+	* const slots = await permissionless.oracles.slots({ chainId: 1 });
+	* ```
+	**/
+	async slots({ chainId } = {}) {
+		return this.getData({
+			path: "/pfs/slots",
+			query: { chainId: chainId?.toString() },
+			schema: marketSlotsSchema
 		});
 	}
 	/**
@@ -51,14 +140,126 @@ var PermissionlessOracles = class extends AbstractOffchainNamespace {
 	* });
 	* ```
 	*
-	* @throws When the store does not carry the feed. A private draft is not
-	* here — it lives in whichever app wrote it.
+	* Each market row also carries the staleness period that market's own
+	* oracle holds for the slot, read off the chain here — see
+	* {@link PermissionlessPriceFeedMarket.marketStalenessPeriod}.
+	*
+	* A feed the store does not carry is read off the chain instead, through
+	* the PriceFeedCompressor, and answered with `inStore: false`: its type,
+	* version and description are the chain's, while what only the store knows
+	* — who deployed it, its staleness period, the assets it may price and the
+	* markets it fills — is answered as unknown or empty.
+	*
+	* @throws When neither the store nor the chain knows the feed. A private
+	* draft is not here — it lives in whichever app wrote it.
 	**/
 	async feed({ chainId, address }) {
-		return this.getData({
-			path: `/pfs/${chainId}/price-feed/${address}`,
-			schema: priceFeedDetailsSchema
+		const feed = address.toLowerCase();
+		let indexed;
+		try {
+			indexed = await this.getData({
+				path: `/pfs/${chainId}/price-feed/${address}`,
+				schema: priceFeedDetailsSchema
+			});
+		} catch (e) {
+			const node = isNotFound(e) ? await this.#onchainNode(chainId, feed) : void 0;
+			if (!node) throw e;
+			return {
+				chainId,
+				priceFeed: onchainPriceFeed(node),
+				assets: [],
+				markets: [],
+				inStore: false
+			};
+		}
+		const periods = await this.#stalenessPeriods(chainId, feed, indexed.markets);
+		return {
+			...indexed,
+			markets: indexed.markets.map((market) => ({
+				...market,
+				marketStalenessPeriod: periods.get(slotKey(market.priceOracle, market.token, market.reserve)) ?? null
+			})),
+			inStore: true
+		};
+	}
+	/**
+	* One feed as the PriceFeedCompressor reads it, or nothing when the chain
+	* cannot be read or the compressor does not know the feed.
+	*
+	* Failures are warnings and not errors: this only ever stands in for a
+	* store that did not have the feed, and the caller reports that miss
+	* rather than whatever kept the chain from answering in its place.
+	*/
+	async #onchainNode(chainId, feed) {
+		try {
+			const client = this.#chains.client(chainId);
+			const compressor = await new AddressProviderContract("0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38", client).getLatestVersionAddress(AP_PRICE_FEED_COMPRESSOR);
+			if (compressor === zeroAddress) return;
+			const { nodes } = await readFeedTrees(client, compressor, [feed]);
+			return nodes.get(feed);
+		} catch (e) {
+			this.logger?.warn(`could not read price feed ${feed} off chain ${chainId}: ${describe(e)}`);
+			return;
+		}
+	}
+	/**
+	* Staleness period each market's own oracle holds for the feed's slots,
+	* keyed by {@link slotKey}.
+	*
+	* One call per oracle rather than per slot: the compressor answers for a
+	* whole oracle at once, and a feed in a dozen markets of the same curator
+	* would otherwise pay a round trip per token. Scoped to the tokens actually
+	* asked about, since the unscoped overload returns the oracle's entire feed
+	* tree as well.
+	*
+	* Failures are warnings and not errors. A slot missing from the answer keeps
+	* its `null`, which the caller reports as "the oracle would not say" — the
+	* alternative is failing a read whose indexed half is perfectly good.
+	*/
+	async #stalenessPeriods(chainId, feed, rows) {
+		const periods = /* @__PURE__ */ new Map();
+		if (rows.length === 0) return periods;
+		const tokensByOracle = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			let tokens = tokensByOracle.get(row.priceOracle);
+			if (!tokens) {
+				tokens = /* @__PURE__ */ new Set();
+				tokensByOracle.set(row.priceOracle, tokens);
+			}
+			tokens.add(row.token);
+		}
+		let client;
+		let compressor;
+		try {
+			client = this.#chains.client(chainId);
+			compressor = await new AddressProviderContract("0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38", client).getLatestVersionAddress(AP_PRICE_FEED_COMPRESSOR);
+		} catch (e) {
+			this.logger?.warn(`no PriceFeedCompressor for chain ${chainId}, reporting no market staleness periods: ${describe(e)}`);
+			return periods;
+		}
+		const oracles = [...tokensByOracle.keys()];
+		const results = await client.multicall({
+			contracts: oracles.map((oracle) => ({
+				address: compressor,
+				abi: priceFeedCompressorAbi,
+				functionName: "getPriceOracleState",
+				args: [oracle, [...tokensByOracle.get(oracle) ?? []]]
+			})),
+			allowFailure: true
+		});
+		oracles.forEach((oracle, i) => {
+			const result = results[i];
+			if (result?.status !== "success") {
+				this.logger?.warn(`price oracle ${oracle} of chain ${chainId} would not report its feed map`);
+				return;
+			}
+			const { priceFeedMap } = result.result;
+			for (const entry of priceFeedMap) {
+				if (entry.priceFeed.toLowerCase() !== feed) continue;
+				periods.set(slotKey(oracle, entry.token, entry.reserve), Number(entry.stalenessPeriod));
+			}
 		});
+		return periods;
 	}
 	/**
 	* One asset of the store: the feeds allowed for it, and the markets that
@@ -74,37 +275,230 @@ var PermissionlessOracles = class extends AbstractOffchainNamespace {
 	*   await permissionless.oracles.asset({ chainId: 1, address: token });
 	* ```
 	*
+	* The quota totals are worked out here, over the very market rows this
+	* answers with — see {@link PermissionlessQuotaTotals}.
+	*
 	* @throws When the chain has no metadata for the address. An asset nothing
 	* was indexed for has no symbol or decimals, so there is no row to answer.
 	**/
 	async asset({ chainId, address }) {
-		return this.getData({
+		const indexed = await this.getData({
 			path: `/pfs/${chainId}/asset/${address}`,
 			schema: assetDetailsSchema
 		});
+		const priceOf = await this.#underlyingPrices(indexed.markets.map((market) => ({
+			chainId,
+			underlyingPriceFeed: market.underlyingPriceFeed
+		})));
+		return {
+			...indexed,
+			...totalQuotas(indexed.markets, (feed) => priceOf(chainId, feed))
+		};
+	}
+	/**
+	* The price of every underlying the given quota rows name, looked up by
+	* chain and feed.
+	*
+	* Distinct feeds only, because an asset in a dozen markets of the same
+	* underlying names the same feed a dozen times, and a list of every chain's
+	* assets names a handful of feeds per chain between them all.
+	*/
+	async #underlyingPrices(rows) {
+		const refs = /* @__PURE__ */ new Map();
+		for (const { chainId, underlyingPriceFeed } of rows) {
+			if (underlyingPriceFeed === null) continue;
+			const address = underlyingPriceFeed.toLowerCase();
+			refs.set(feedKey(chainId, address), {
+				chainId,
+				address
+			});
+		}
+		const prices = pricesByFeed(await this.getPrices([...refs.values()]));
+		return (chainId, feed) => prices.get(feedKey(chainId, feed));
 	}
 	/**
-	* What each of one asset's feeds prices it at, and the market cap each of
-	* them implies.
+	* Every asset the store carries, with what its markets make of it.
+	*
+	* Enough on its own to render a list of assets: the alternative is the
+	* store's whole read for the names plus a call per row for the quotas, and
+	* this is one request either way you scope it.
 	*
-	* The asset-side counterpart of {@link feedMarketCaps}, and priced the same
-	* way: one `totalSupply` read for the asset and one price per feed, rather
-	* than the chain-wide pass {@link prices} makes.
+	* Ordered by how central each asset is — the markets it underlies first,
+	* then what is quoted against it, then what it is allowed — so a consumer
+	* renders the rows as they arrive. Omit `chainId` for every chain the
+	* backend serves, ordered the same way across all of them.
 	*
-	* Several feeds for one asset do not have to agree — that is the point of
-	* having a reserve feed — so this answers per feed rather than picking one.
+	* Each row also carries its quota totals and what this SDK's tables say the
+	* asset is, neither of which is served — see
+	* {@link PermissionlessAssetSummary}. The totals are what the last two terms
+	* of the order are over, so this waits for them rather than handing back a
+	* list that would reshuffle a moment later.
 	*
 	* ```ts
-	* const { prices, marketCaps } = await permissionless.oracles.assetPrices({
+	* const assets = await permissionless.oracles.assets({ chainId: 1 });
+	* const everywhere = await permissionless.oracles.assets();
+	* ```
+	**/
+	async assets({ chainId } = {}) {
+		const indexed = await this.getData({
+			path: "/pfs/assets",
+			query: { chainId: chainId?.toString() },
+			schema: assetSummariesSchema
+		});
+		const networks = /* @__PURE__ */ new Map();
+		for (const { chainId: id } of indexed) if (!networks.has(id)) networks.set(id, isSupportedNetwork(id) ? getNetworkType(id) : void 0);
+		const priceOf = await this.#underlyingPrices(indexed.flatMap((asset) => asset.marketQuotas.map((quota) => ({
+			chainId: asset.chainId,
+			underlyingPriceFeed: quota.underlyingPriceFeed
+		}))));
+		return indexed.map((asset) => {
+			const network = networks.get(asset.chainId);
+			return {
+				...asset,
+				...totalQuotas(asset.marketQuotas, (feed) => priceOf(asset.chainId, feed)),
+				assetType: network === void 0 ? null : getAssetType(asset.address, network) ?? null,
+				isRwa: network === void 0 ? false : isRWAToken(asset.address, network)
+			};
+		}).sort(byCentrality);
+	}
+	/**
+	* What each source of price information can do to the chain's markets if it
+	* lies.
+	*
+	* The feeds under a chain's oracles are partitioned by where their numbers
+	* actually come from — Chainlink, Redstone, Pyth, Lido, Curve, each vault's
+	* own issuer — on the grounds that a source fails as a whole: whoever
+	* trusts one Chainlink aggregator trusts the operator behind all of them.
+	* Each group is then made to report a multiple of what it reports now, and
+	* every feed the markets read is read again inside that same call.
+	*
+	* No fork and no harness. The lie is a state override on an `eth_call`, so
+	* the composite feeds above it, their bounds and the oracle's own checks all
+	* run as deployed, against real state, at the current block — what comes
+	* back is what the market would have read.
+	*
+	* Each slot is scored by how its collateral moved *against its market's own
+	* underlying*, because that is what an account is valued by: a group that
+	* moves both legs has moved nothing. Beyond the two unbounded ends, each
+	* group is bisected for the multiple at which something first breaks, which
+	* is the figure that separates a source held in check by a bound from one
+	* nothing is checking.
+	*
+	* ```ts
+	* const report = await permissionless.oracles.stressTest({ chainId: 1 });
+	* for (const group of report.groups) {
+	*   console.log(group.verdict);
+	* }
+	* ```
+	*
+	* Report {@link StressReport.unidentifiedUsd} alongside anything taken from
+	* this: it is the quota priced through a source the partition could only
+	* name after its own description, and nothing says what that fails with.
+	*
+	* Reads the chain directly, so the client has to have attached — see
+	* {@link GearboxPermissionless.attach}. Costs one request for the slots and
+	* then, per group, one `eth_call` per scenario plus the bisection's; a whole
+	* chain comes to a minute or so, and `thresholds: false` cuts it to seconds.
+	*
+	* @throws When the client has not attached, when the chain has no client
+	* configured, or when no PriceFeedCompressor is deployed on it — none of the
+	* three leaves anything to simulate.
+	**/
+	/**
+	* Every asset's manipulation resistance: how far, from 1 to 10 times, a
+	* lying source can push the price its markets hold for it.
+	*
+	* Each source group behind an asset's feeds — Chainlink, Redstone, Lido and
+	* so on — is made in turn to answer ten times what it answers now, and a
+	* market scores by how far that moves its final price, `min(main,
+	* reserve)`, as a multiple either way: 1 for not at all, 1.04 for 4%, 10
+	* for the whole lie. A group under which the price stops answering moves
+	* nothing and is listed rather than scored. An asset scores its worst
+	* running market, underlying or collateral.
+	*
+	* Simulated on the chain as it stands, through state overrides in
+	* `eth_call`: one call per source group per chain, so the node behind the
+	* client has to accept overrides. A chain with no client configured, or
+	* whose node refuses, is left out with a warning rather than failing the
+	* rest.
+	*
+	* ```ts
+	* const scores = await permissionless.oracles.assetScores({ chainId: 1 });
+	* ```
+	*
+	* @throws {PermissionlessNotAttachedError} before
+	* {@link GearboxPermissionless.attach} has resolved.
+	**/
+	async assetScores({ chainId } = {}) {
+		const slots = await this.slots({ chainId });
+		const byChain = /* @__PURE__ */ new Map();
+		for (const slot of slots) byChain.set(slot.chainId, [...byChain.get(slot.chainId) ?? [], slot]);
+		return (await Promise.all([...byChain].map(async ([id, chainSlots]) => {
+			let client;
+			try {
+				client = this.#chains.client(id);
+			} catch (e) {
+				this.logger?.warn(`chain ${id} has no client, leaving its assets unscored: ${describe(e)}`);
+				return [];
+			}
+			try {
+				const compressor = await new AddressProviderContract("0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38", client).getLatestVersionAddress(AP_PRICE_FEED_COMPRESSOR);
+				return await runAssetScores({
+					client,
+					chainId: id,
+					slots: chainSlots,
+					compressor,
+					logger: this.logger ?? void 0
+				});
+			} catch (e) {
+				this.logger?.warn(`chain ${id} would not report its feed trees, leaving its assets unscored: ${describe(e)}`);
+				return [];
+			}
+		}))).flat();
+	}
+	/**
+	* The manipulation resistance of any main feed and reserve on a chain,
+	* scored the way {@link assetScores} scores a market holding them — for
+	* trying a pair before any market does.
+	*
+	* ```ts
+	* const pair = await permissionless.oracles.feedPairScore({
 	*   chainId: 1,
-	*   address: token,
+	*   main: "0x…",
+	*   reserve: "0x…",
 	* });
 	* ```
+	*
+	* Reads the chain directly, through state overrides in `eth_call`, so the
+	* client has to have attached and the node behind it has to accept them.
+	*
+	* @throws When the client has not attached, when the chain has no client or
+	* no PriceFeedCompressor, or when there is nothing to score: a feed the
+	* compressor cannot read, a `ZeroPriceFeed` main, or a final price that does
+	* not answer.
 	**/
-	async assetPrices({ chainId, address }) {
-		return this.getData({
-			path: `/pfs/${chainId}/asset/${address}/prices`,
-			schema: assetPricesSchema
+	async feedPairScore({ chainId, main, reserve }) {
+		const client = this.#chains.client(chainId);
+		const compressor = await new AddressProviderContract("0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38", client).getLatestVersionAddress(AP_PRICE_FEED_COMPRESSOR);
+		return runFeedPairScore({
+			client,
+			chainId,
+			compressor,
+			main,
+			reserve,
+			logger: this.logger ?? void 0
+		});
+	}
+	async stressTest({ chainId, ...options }) {
+		const client = this.#chains.client(chainId);
+		const compressor = await new AddressProviderContract("0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38", client).getLatestVersionAddress(AP_PRICE_FEED_COMPRESSOR);
+		return runStressTest({
+			client,
+			chainId,
+			compressor,
+			slots: await this.slots({ chainId }),
+			logger: this.logger ?? void 0,
+			...options
 		});
 	}
 	/**
@@ -128,69 +522,247 @@ var PermissionlessOracles = class extends AbstractOffchainNamespace {
 		});
 	}
 	/**
-	* What the market values each of one feed's assets at.
+	* What the named feeds price, read off the chain.
+	*
+	* Prices exactly what is asked for, at the current block, across as many
+	* chains as the list names — one read per chain, so a screen listing every
+	* chain's feeds pays per chain and not per row. A feed the store does not
+	* carry prices the same way, which is what makes this the call to reach for
+	* after a deploy, or while a form is still choosing between candidates.
 	*
-	* Prefer this over {@link prices} whenever the caller is looking at a single
-	* feed. That one prices the whole store, which costs the backend one
-	* `totalSupply` call per asset of every market on the chain; this costs it
-	* one price lookup and one multicall over the feed's own assets.
+	* Read in two passes. The first asks every feed what it reports as it
+	* stands, which is one multicall per chain; a feed that will not answer
+	* until it has been given a fresh one is then priced inside a simulation
+	* that updates it first, so a push-based feed prices as readily as a
+	* pull-based one. The second pass costs an `OnchainSDK` to attach, hence
+	* only the feeds that need it rather than all of them.
+	*
+	* `null` is a feed neither pass could read, and a chain with no client
+	* configured is every one of its feeds reading `null` rather than a failed
+	* call — the figures built on them are floors either way.
 	*
 	* ```ts
-	* const { marketCaps } = await permissionless.oracles.feedMarketCaps({
-	*   chainId: 1,
-	*   address: feed,
-	* });
+	* const [{ price }] = await permissionless.oracles.getPrices([
+	*   { chainId: 1, address: feed },
+	* ]);
 	* ```
+	*
+	* @returns One entry per feed asked for, in the order asked, each price in
+	* the 8 decimals every Gearbox feed reports.
 	**/
-	async feedMarketCaps({ chainId, address }) {
-		return this.getData({
-			path: `/pfs/${chainId}/price-feed/${address}/market-caps`,
-			schema: priceFeedMarketCapsSchema
-		});
+	async getPrices(feeds) {
+		const byChain = /* @__PURE__ */ new Map();
+		for (const { chainId, address } of feeds) {
+			const addresses = byChain.get(chainId) ?? /* @__PURE__ */ new Set();
+			addresses.add(address.toLowerCase());
+			byChain.set(chainId, addresses);
+		}
+		const chainIds = [...byChain.keys()];
+		const results = await Promise.all(chainIds.map((chainId) => this.#pricesOf(chainId, [...byChain.get(chainId) ?? []])));
+		const prices = new Map(chainIds.map((id, i) => [id, results[i] ?? {}]));
+		return feeds.map(({ chainId, address }) => ({
+			chainId,
+			address,
+			price: prices.get(chainId)?.[address.toLowerCase()] ?? null
+		}));
 	}
 	/**
-	* A price per feed, and a market cap per feed and asset. The feeds the
-	* indexer has not seen are read off the chain by the backend, so the store
-	* is priced whole.
+	* The scale each of the named feeds answers in.
+	*
+	* The companion to {@link getPrices} for the callers whose feeds are not
+	* all an oracle's: everything an oracle holds reports 8 decimals, but the
+	* feeds under a composite are whatever was deployed, and a rate leg at 18
+	* read as 8 is wrong by ten orders of magnitude rather than visibly wrong.
+	*
+	* Separate from the price because the two keep different company: this is
+	* fixed for the life of the contract and worth caching for the session,
+	* while a price is re-read whenever the reader asks. One multicall per
+	* chain either way.
 	*
-	* Chain-wide, and priced accordingly — see {@link feedMarketCaps} for one
-	* feed.
+	* `null` is a feed that would not answer, or one on a chain with no client
+	* configured.
+	*
+	* ```ts
+	* const [{ decimals }] = await permissionless.oracles.getDecimals([
+	*   { chainId: 1, address: feed },
+	* ]);
+	* ```
+	*
+	* @returns One entry per feed asked for, in the order asked.
 	**/
-	async prices({ chainId }) {
-		return this.getData({
-			path: `/pfs/${chainId}/prices`,
-			schema: pricesSchema
-		});
+	async getDecimals(feeds) {
+		const byChain = /* @__PURE__ */ new Map();
+		for (const { chainId, address } of feeds) {
+			const addresses = byChain.get(chainId) ?? /* @__PURE__ */ new Set();
+			addresses.add(address.toLowerCase());
+			byChain.set(chainId, addresses);
+		}
+		const chainIds = [...byChain.keys()];
+		const results = await Promise.all(chainIds.map((chainId) => this.#decimalsOf(chainId, [...byChain.get(chainId) ?? []])));
+		const decimals = new Map(chainIds.map((id, i) => [id, results[i] ?? {}]));
+		return feeds.map(({ chainId, address }) => ({
+			chainId,
+			address,
+			decimals: decimals.get(chainId)?.[address.toLowerCase()] ?? null
+		}));
+	}
+	/** One chain's half of {@link getDecimals}. */
+	async #decimalsOf(chainId, priceFeeds) {
+		let client;
+		try {
+			client = this.#chains.client(chainId);
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} has no client, reporting its ${priceFeeds.length} feed(s) without a scale: ${describe(e)}`);
+			return {};
+		}
+		try {
+			return await getFeedDecimals({
+				client,
+				priceFeeds
+			});
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} would not answer decimals for its ${priceFeeds.length} feed(s): ${describe(e)}`);
+			return {};
+		}
+	}
+	/** One chain's half of {@link getPrices}: the cheap pass, then the rest. */
+	async #pricesOf(chainId, priceFeeds) {
+		let client;
+		try {
+			client = this.#chains.client(chainId);
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} has no client, reporting its ${priceFeeds.length} feed(s) unpriced: ${describe(e)}`);
+			return {};
+		}
+		let prices;
+		try {
+			prices = await getLatestPrices({
+				client,
+				priceFeeds
+			});
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} would not answer for its ${priceFeeds.length} feed(s), trying each with an update: ${describe(e)}`);
+			prices = {};
+		}
+		const stale = priceFeeds.filter((feed) => (prices[feed] ?? null) === null);
+		if (stale.length === 0) return prices;
+		try {
+			return {
+				...prices,
+				...await getPrices({
+					client,
+					priceFeeds: stale,
+					chunkSize: 200,
+					gasLimit: GET_PRICES_GAS_LIMIT_BY_CHAIN_ID[chainId]
+				})
+			};
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} would not price ${stale.length} of its feed(s) even with an update, reporting them unpriced: ${describe(e)}`);
+			return prices;
+		}
 	}
 	/**
-	* The price each of the named feeds reports, read off the chain.
+	* What one chain's feeds value one chain's assets at: `price × totalSupply`
+	* per pair.
 	*
-	* Where {@link prices} answers for the store as a whole and at whatever
-	* moment the backend priced it, this prices exactly the feeds asked for, at
-	* the current block. A feed the store does not carry prices the same way,
-	* which is what makes this the call to reach for after a deploy, or while a
-	* form is still choosing between candidates.
+	* Asked from whichever side the caller is looking at — one asset through
+	* each of its feeds, or one feed over each of the assets it prices — because
+	* a screen shows one row per feed or one row per asset, never the full
+	* cross product. Both answer the same pairs in the same shape.
 	*
-	* Feeds needing a fresh answer before they can be read are updated inside
-	* the same simulation, so a push-based feed prices as readily as a
-	* pull-based one. `null` is a feed whose read reverted, not a zero.
+	* Two reads per chain: the prices, and one multicall for the assets'
+	* supplies and decimals. Several scopes can be asked at once, which is how a
+	* table of every asset's feeds pays per chain rather than per row; the pairs
+	* come back in the order the scopes named them. A pair neither read could
+	* resolve has a `null` cap, which is not a zero.
 	*
 	* ```ts
-	* const prices = await permissionless.oracles.getPrices({
+	* const caps = await permissionless.oracles.getMarketCap({
 	*   chainId: 1,
-	*   priceFeeds: [feed],
+	*   asset: token,
+	*   priceFeeds: [main, reserve],
 	* });
 	* ```
-	*
-	* @returns A price per feed, in the 8 decimals every Gearbox feed reports.
 	**/
-	async getPrices({ chainId, priceFeeds }) {
-		return getPrices({
-			client: this.#chains.client(chainId),
-			priceFeeds,
-			chunkSize: 200,
-			gasLimit: GET_PRICES_GAS_LIMIT_BY_CHAIN_ID[chainId]
+	async getMarketCap(scope) {
+		const pairs = (Array.isArray(scope) ? scope : [scope]).flatMap((one) => "asset" in one ? one.priceFeeds.map((priceFeed) => ({
+			chainId: one.chainId,
+			priceFeed: priceFeed.toLowerCase(),
+			asset: one.asset.toLowerCase()
+		})) : one.assets.map((asset) => ({
+			chainId: one.chainId,
+			priceFeed: one.priceFeed.toLowerCase(),
+			asset: asset.toLowerCase()
+		})));
+		if (pairs.length === 0) return [];
+		const feeds = /* @__PURE__ */ new Map();
+		const assetsByChain = /* @__PURE__ */ new Map();
+		for (const { chainId, priceFeed, asset } of pairs) {
+			feeds.set(feedKey(chainId, priceFeed), {
+				chainId,
+				address: priceFeed
+			});
+			const assets = assetsByChain.get(chainId) ?? /* @__PURE__ */ new Set();
+			assets.add(asset);
+			assetsByChain.set(chainId, assets);
+		}
+		const chainIds = [...assetsByChain.keys()];
+		const [prices, perChain] = await Promise.all([this.getPrices([...feeds.values()]), Promise.all(chainIds.map((chainId) => this.#supplies(chainId, [...assetsByChain.get(chainId) ?? []])))]);
+		const priced = pricesByFeed(prices);
+		const supplies = new Map(chainIds.map((id, i) => [id, perChain[i]]));
+		return pairs.map(({ chainId, priceFeed, asset }) => {
+			const supply = supplies.get(chainId)?.get(asset);
+			return {
+				chainId,
+				priceFeed,
+				asset,
+				cap: supply === void 0 ? null : toCap(priced.get(feedKey(chainId, priceFeed)), supply.totalSupply, supply.decimals)
+			};
+		});
+	}
+	/**
+	* Each asset's supply and the decimals it is counted in, which is what turns
+	* a supply into an amount.
+	*
+	* Both read rather than one of them taken from the index, so that a cap can
+	* be asked for an address nothing was indexed for at all — a token a form is
+	* still choosing, say. An asset missing from the answer is left out, and
+	* caps over it come back `null`.
+	*/
+	async #supplies(chainId, assets) {
+		const supplies = /* @__PURE__ */ new Map();
+		let client;
+		try {
+			client = this.#chains.client(chainId);
+		} catch (e) {
+			this.logger?.warn(`chain ${chainId} has no client, reporting no market caps: ${describe(e)}`);
+			return supplies;
+		}
+		const results = await client.multicall({
+			contracts: assets.flatMap((address) => [{
+				address,
+				abi: erc20Abi,
+				functionName: "totalSupply"
+			}, {
+				address,
+				abi: erc20Abi,
+				functionName: "decimals"
+			}]),
+			allowFailure: true
+		});
+		assets.forEach((address, i) => {
+			const supply = results[2 * i];
+			const decimals = results[2 * i + 1];
+			if (decimals?.status !== "success") {
+				this.logger?.warn(`asset ${address} of chain ${chainId} would not report its decimals, reporting no market cap for it`);
+				return;
+			}
+			supplies.set(address, {
+				totalSupply: supply?.status === "success" ? supply.result : null,
+				decimals: Number(decimals.result)
+			});
 		});
+		return supplies;
 	}
 };
 //#endregion