@gearbox-protocol/sdk 18.2.0-next.1 → 18.2.0-next.11

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

@@ -0,0 +1,94 @@
+import { formatUnits } from "viem";
+//#region src/permissionless/api/oracles/enrich.ts
+/**
+* What the oracles namespace works out for itself once the backend has
+* answered.
+*
+* All of it used to be the backend's, and all of it needs the chain: a quota
+* is denominated in its market's own underlying and a market cap is a supply
+* times a price, so none of these can be indexed — they can only be read at
+* the block the reader is on. Keeping them here means one description of each
+* rule rather than one per service that wants it, and a backend that holds no
+* viem client at all.
+**/
+/** Identifies a feed across chains, since an address alone does not. */
+function feedKey(chainId, address) {
+	return `${chainId}:${address.toLowerCase()}`;
+}
+/** Prices looked up the way {@link totalQuotas} and the caps need them. */
+function pricesByFeed(prices) {
+	return new Map(prices.map(({ chainId, address, price }) => [feedKey(chainId, address), price]));
+}
+/**
+* The asset's quota across its markets, totalled in USD.
+*
+* Each market's figures are converted at the price that market's own oracle
+* holds for its underlying, which is the same number that market's accounting
+* uses.
+*
+* Limits count only the markets still running, because a shut down market's
+* limit is not borrowable; what is already quoted counts everywhere, because
+* debt outstanding is exposure either way. A market whose underlying could not
+* be priced is skipped, which makes both figures floors, and `null` is nothing
+* to total rather than a zero.
+*
+* @param priceOf - The price each underlying feed reports, in the 8 decimals
+* every Gearbox feed uses.
+*/
+function totalQuotas(quotas, priceOf) {
+	let limit = 0;
+	let used = 0;
+	let anyLimit = false;
+	let anyUsed = false;
+	for (const quota of quotas) {
+		const raw = quota.underlyingPriceFeed === null ? null : priceOf(quota.underlyingPriceFeed);
+		if (raw === null || raw === void 0) continue;
+		const price = Number(formatUnits(raw, 8));
+		if (quota.quotaUsed !== null) {
+			used += quota.quotaUsed * price;
+			anyUsed = true;
+		}
+		if (quota.quotaLimit !== null && !quota.isShutdown) {
+			limit += quota.quotaLimit * price;
+			anyLimit = true;
+		}
+	}
+	return {
+		quotaLimitUsd: anyLimit ? limit : null,
+		quotaUsedUsd: anyUsed ? used : null
+	};
+}
+/**
+* What one feed values one asset's supply at: `price × totalSupply`.
+*
+* Multiplied as integers and formatted once, rather than through two floats:
+* an 8-decimal price times an 18-decimal supply loses its small end to a JS
+* number long before it loses the large one, and the figure is a total rather
+* than an estimate.
+*
+* `null` if either side could not be read — an asset nobody could price is
+* not an asset worth nothing.
+*/
+function toCap(price, totalSupply, decimals) {
+	if (price === null || price === void 0 || totalSupply === null || totalSupply === void 0) return null;
+	return formatUnits(price * totalSupply, 8 + decimals);
+}
+/** Larger first, with `null` after every figure including a real zero. */
+function descending(a, b) {
+	return (b ?? -1) - (a ?? -1);
+}
+/**
+* Assets ordered the way a reader scans them: what the protocol is built on
+* first, then what is actually borrowed against it, then what it is merely
+* allowed to be borrowed against.
+*
+* Applied here and not by the backend because the two middle terms are the
+* converted quotas, which only exist once the chain has been read. The
+* backend orders by the first term and the tie-breakers, so a caller reading
+* the route directly still gets a stable order; this refines it.
+*/
+function byCentrality(a, b) {
+	return b.underlyingMarketCount - a.underlyingMarketCount || descending(a.quotaUsedUsd, b.quotaUsedUsd) || descending(a.quotaLimitUsd, b.quotaLimitUsd) || a.symbol.localeCompare(b.symbol) || a.address.localeCompare(b.address) || a.chainId - b.chainId;
+}
+//#endregion
+export { byCentrality, feedKey, pricesByFeed, toCap, totalQuotas };

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

@@ -1,2 +1,11 @@
-export { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, PermissionlessOracles } from "./PermissionlessOracles.js";
+import { classifySources, sourcesByFeed } from "./stress/classify.js";
+import { UNBOUNDED_DOWN, UNBOUNDED_UP, groupOverride, perturb, rateStub, roundDataStub } from "./stress/override.js";
+import { scoreGroup, slotHarm, verdictOf } from "./stress/score.js";
+import { DEFAULT_SCENARIOS, RATE_FEED_TYPE, readForest, readRateTargets, runStressTest } from "./stress/run.js";
+import { BOUND_WEIGHT, INDEPENDENCE_WEIGHT, scoreMarket } from "./score/formula.js";
+import { runAssetScores } from "./score/run.js";
+import { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, PermissionlessOracles } from "./PermissionlessOracles.js";
+import "./score/index.js";
+import "./stress/index.js";
 import "./types.js";
+export { BOUND_WEIGHT, DEFAULT_SCENARIOS, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, INDEPENDENCE_WEIGHT, PermissionlessOracles, RATE_FEED_TYPE, UNBOUNDED_DOWN, UNBOUNDED_UP, classifySources, groupOverride, perturb, rateStub, readForest, readRateTargets, roundDataStub, runAssetScores, runStressTest, scoreGroup, scoreMarket, slotHarm, sourcesByFeed, verdictOf };

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

@@ -1,4 +1,5 @@
-import { addressRecord, addressSchema } from "../schemas.js";
+import { chainSchema } from "../chains/schemas.js";
+import { addressSchema } from "../schemas.js";
 import { z } from "zod/v4";
 //#region src/permissionless/api/oracles/schemas.ts
 /**
@@ -18,62 +19,121 @@ const priceFeedSchema = z.looseObject({
 	stalenessPeriod: z.number(),
 	name: z.string()
 });
-/** {@link PermissionlessAsset} */
-const assetSchema = z.looseObject({
+/**
+* {@link PermissionlessPriceFeedAsset}
+*
+* What identifies an asset, which is all a feed's own listing of one says.
+**/
+const priceFeedAssetSchema = z.looseObject({
 	address: addressSchema,
 	symbol: z.string(),
 	name: z.string(),
-	decimals: z.number(),
+	decimals: z.number()
+});
+/** {@link PermissionlessAsset} — identified as above, plus what prices it. */
+const assetSchema = priceFeedAssetSchema.extend({
 	owner: addressSchema,
 	priceFeeds: z.array(priceFeedSchema)
 });
-/** {@link PermissionlessPriceFeedStore} */
-const priceFeedStoreSchema = z.looseObject({
-	chainId: z.number(),
-	name: z.string(),
-	isPublic: z.boolean(),
-	isActivated: z.boolean(),
-	explorerUrl: z.string(),
+/**
+* {@link PermissionlessPriceFeedStore}
+*
+* A store is a chain's, and is described by the same five fields the chain
+* list answers with, so those are extended rather than restated.
+**/
+const priceFeedStoreSchema = chainSchema.extend({
 	assets: z.array(assetSchema),
 	priceFeeds: z.array(priceFeedSchema)
 });
-/** {@link PermissionlessPrices} */
-const pricesSchema = z.looseObject({
-	prices: addressRecord(z.string().nullable()),
-	marketCaps: addressRecord(addressRecord(z.string().nullable())),
-	time: z.number()
-});
-/** {@link PermissionlessPriceFeedAsset} */
-const priceFeedAssetSchema = z.looseObject({
-	address: addressSchema,
-	symbol: z.string(),
-	name: z.string(),
-	decimals: z.number()
-});
-/** {@link PermissionlessPriceFeedMarket} */
-const priceFeedMarketSchema = z.looseObject({
+/** Every chain's {@link PermissionlessPriceFeedStore}, one per chain. */
+const priceFeedStoresSchema = z.array(priceFeedStoreSchema);
+/**
+* What names a market, whichever side it is being listed from.
+*
+* A feed's markets and an asset's markets are different reads, but they
+* answer with the same market: who curates it, what it is denominated in and
+* how much of the quota is taken. Only what the read is about differs, which
+* is what each of the two below adds.
+**/
+const marketSchema = z.looseObject({
 	market: addressSchema,
 	marketConfigurator: addressSchema,
 	curatorName: z.string().nullable(),
 	marketName: z.string().nullable(),
+	underlyingSymbol: z.string().nullable(),
+	isUnderlying: z.boolean(),
+	quotaLimit: z.number().nullable(),
+	quotaUsed: z.number().nullable()
+});
+/**
+* {@link PermissionlessIndexedPriceFeedMarket} — the market as the feed's slot
+* in it, before the oracle is asked what period it holds for the slot.
+**/
+const priceFeedMarketSchema = marketSchema.extend({
 	token: addressSchema,
 	tokenSymbol: z.string().nullable(),
-	underlyingSymbol: z.string().nullable(),
 	reserve: z.boolean(),
-	isUnderlying: z.boolean(),
-	quotaLimit: z.number().nullable()
+	priceOracle: addressSchema
+});
+/**
+* {@link PermissionlessMarketSlot} — the same slot read from the chain's end,
+* so the feed is a column rather than what was asked for.
+**/
+const marketSlotSchema = priceFeedMarketSchema.extend({
+	chainId: z.number(),
+	underlyingToken: addressSchema,
+	isShutdown: z.boolean(),
+	priceFeed: addressSchema,
+	priceFeedName: z.string().nullable(),
+	priceFeedInStore: z.boolean(),
+	underlyingPriceFeed: addressSchema.nullable()
 });
-/** {@link PermissionlessPriceFeedDetails} */
+/** Every slot in scope, across whichever chains the read covered. */
+const marketSlotsSchema = z.array(marketSlotSchema);
+/** {@link PermissionlessIndexedPriceFeedDetails} */
 const priceFeedDetailsSchema = z.looseObject({
 	chainId: z.number(),
 	priceFeed: priceFeedSchema,
 	assets: z.array(priceFeedAssetSchema),
 	markets: z.array(priceFeedMarketSchema)
 });
-/** {@link PermissionlessPriceFeedMarketCaps} */
-const priceFeedMarketCapsSchema = z.looseObject({
-	marketCaps: addressRecord(z.string().nullable()),
-	time: z.number()
+/** {@link PermissionlessAssetMarketFeed} */
+const assetMarketFeedSchema = z.looseObject({
+	address: addressSchema,
+	name: z.string().nullable(),
+	inStore: z.boolean()
+});
+/** {@link PermissionlessAssetMarket} — the market as what prices the asset in it. */
+const assetMarketSchema = marketSchema.extend({
+	underlyingToken: addressSchema,
+	underlyingPriceFeed: addressSchema.nullable(),
+	isShutdown: z.boolean(),
+	mainFeed: assetMarketFeedSchema.nullable(),
+	reserveFeed: assetMarketFeedSchema.nullable()
+});
+/** {@link PermissionlessIndexedAssetDetails} */
+const assetDetailsSchema = z.looseObject({
+	chainId: z.number(),
+	asset: priceFeedAssetSchema,
+	priceFeeds: z.array(priceFeedSchema),
+	markets: z.array(assetMarketSchema)
+});
+/** {@link PermissionlessAssetQuota} */
+const assetQuotaSchema = z.looseObject({
+	quotaLimit: z.number().nullable(),
+	quotaUsed: z.number().nullable(),
+	isShutdown: z.boolean(),
+	underlyingPriceFeed: addressSchema.nullable()
+});
+/** {@link PermissionlessIndexedAssetSummary} */
+const assetSummarySchema = z.looseObject({
+	chainId: z.number(),
+	address: addressSchema,
+	symbol: z.string(),
+	underlyingMarketCount: z.number(),
+	marketQuotas: z.array(assetQuotaSchema)
 });
+/** The list of {@link PermissionlessAssetSummary}, already ordered. */
+const assetSummariesSchema = z.array(assetSummarySchema);
 //#endregion
-export { assetSchema, priceFeedAssetSchema, priceFeedDetailsSchema, priceFeedMarketCapsSchema, priceFeedMarketSchema, priceFeedSchema, priceFeedStoreSchema, pricesSchema };
+export { assetDetailsSchema, assetMarketFeedSchema, assetMarketSchema, assetQuotaSchema, assetSchema, assetSummariesSchema, assetSummarySchema, marketSlotSchema, marketSlotsSchema, priceFeedAssetSchema, priceFeedDetailsSchema, priceFeedMarketSchema, priceFeedSchema, priceFeedStoreSchema, priceFeedStoresSchema };

package/dist/esm/permissionless/api/oracles/score/formula.js

@@ -0,0 +1,96 @@
+//#region src/permissionless/api/oracles/score/formula.ts
+/**
+* How well a market guards an asset's price, from its two feeds alone.
+*
+* Two questions, and the points are lost for each separately:
+*
+* - Would the reserve disagree with a main feed that has gone wrong? Only if
+*   it is a second feed on other sources. A missing reserve, a
+*   `ZeroPriceFeed`, the main feed again, and a different feed on the same
+*   sources all answer no.
+* - Is either feed bounded? A `BoundedPriceFeed` caps the answer from above,
+*   and a Gearbox LP feed clamps its exchange rate to a window.
+*
+* Independence costs more than the bound, 6 points against 5, because it is
+* the broader protection: a bounded feed caps only from above, and an LP
+* feed's window holds only its rate, not the price of what the rate is in.
+* Either failure alone lands a market at 4 or 5; both together at 0.
+*/
+const INDEPENDENCE_WEIGHT = 6;
+const BOUND_WEIGHT = 5;
+/**
+* The feed types that bound what they answer: the `BoundedPriceFeed`, and
+* every Gearbox LP feed, all of which clamp the rate they read.
+*/
+const BOUNDED_TYPE = /::(BOUNDED|ERC4626|CURVE_\w+|WSTETH|YEARN|MELLOW\w*|BALANCER\w*)$/;
+const ZERO_TYPE = "PRICE_FEED::ZERO";
+/**
+* The share of the two sides' sources that are not shared, by key.
+*
+* Nothing on either side — two hardcoded prices — is 0, because a reserve is
+* there to be a second opinion and neither of them is one.
+*/
+function independenceOf(main, reserve) {
+	const a = new Set(main.map((source) => source.key));
+	const b = new Set(reserve.map((source) => source.key));
+	const union = /* @__PURE__ */ new Set([...a, ...b]);
+	if (union.size === 0) return 0;
+	return 1 - [...a].filter((key) => b.has(key)).length / union.size;
+}
+/** Down to the half point, so that a score is never rounded up into a band. */
+function toHalf(value) {
+	return Math.floor(value * 2 + 1e-9) / 2;
+}
+/**
+* One market's score for one asset.
+*
+* `reserve` is `null` where the market holds no reserve for the asset at all.
+* A source is passed per side and keyed by the caller, which is where it is
+* decided that an unnamed source is its own contract and a named one is its
+* group.
+*/
+function scoreMarket(market, main, reserve) {
+	const reasons = [];
+	let hasReserve = true;
+	if (reserve === null) {
+		hasReserve = false;
+		reasons.push("no reserve feed");
+	} else if (reserve.feed.contractType === ZERO_TYPE) {
+		hasReserve = false;
+		reasons.push("reserve is a ZeroPriceFeed");
+	} else if (reserve.feed.feed.toLowerCase() === main.feed.feed.toLowerCase()) {
+		hasReserve = false;
+		reasons.push("reserve is the main feed");
+	}
+	const reserveSources = hasReserve && reserve ? reserve.sources : [];
+	const independence = hasReserve ? independenceOf(main.sources, reserveSources) : 0;
+	const reserveKeys = new Set(reserveSources.map((source) => source.key));
+	const mainKeys = new Set(main.sources.map((source) => source.key));
+	const shared = main.sources.filter((source) => reserveKeys.has(source.key));
+	const names = (sources) => [...new Set(sources.map((source) => source.name))];
+	if (hasReserve && independence < 1) reasons.push(shared.length > 0 ? `main and reserve share ${names(shared).join(", ")}` : "neither feed reads a price source");
+	const unverified = hasReserve && [...main.sources.filter((source) => !reserveKeys.has(source.key)), ...reserveSources.filter((source) => !mainKeys.has(source.key))].some((source) => !source.identified);
+	const bounded = BOUNDED_TYPE.test(main.feed.contractType) || reserve !== null && BOUNDED_TYPE.test(reserve.feed.contractType);
+	if (!bounded) reasons.push("neither feed is bounded");
+	const score = toHalf(Math.max(0, 10 - 6 * (1 - independence) - 5 * (bounded ? 0 : 1)));
+	return {
+		...market,
+		main: {
+			...main.feed,
+			sources: names(main.sources)
+		},
+		reserve: reserve ? {
+			...reserve.feed,
+			sources: names(reserve.sources)
+		} : null,
+		hasReserve,
+		independence,
+		bounded,
+		sharedSources: names(shared),
+		unverified,
+		score,
+		reasons
+	};
+}
+//#endregion
+export { BOUND_WEIGHT, INDEPENDENCE_WEIGHT, scoreMarket };

package/dist/esm/permissionless/api/oracles/score/index.js

@@ -0,0 +1,4 @@
+import { BOUND_WEIGHT, INDEPENDENCE_WEIGHT, scoreMarket } from "./formula.js";
+import { runAssetScores } from "./run.js";
+import "./types.js";
+export { BOUND_WEIGHT, INDEPENDENCE_WEIGHT, runAssetScores, scoreMarket };

package/dist/esm/permissionless/api/oracles/score/run.js

@@ -0,0 +1,87 @@
+import { classifySources, sourcesByFeed } from "../stress/classify.js";
+import { RATE_FEED_TYPE, readForest, readRateTargets } from "../stress/run.js";
+import { scoreMarket } from "./formula.js";
+//#region src/permissionless/api/oracles/score/run.ts
+/**
+* How a source is told apart from another when two feeds are compared.
+*
+* A named source by its group, since two Chainlink aggregators are one
+* provider failing together. An unnamed one by its contract, since nothing
+* says what else it fails with — so the same contract on both sides is
+* shared, and two different ones are not.
+*/
+function toScoreSource(source) {
+	return {
+		key: source.identified ? `group:${source.group}` : `contract:${source.target}`,
+		name: source.group,
+		identified: source.identified
+	};
+}
+/**
+* Every asset of one chain, scored by how its running markets price it.
+*
+* One read of every oracle's feed tree and one of the LP feeds' rate
+* contracts, both multicalls: the score is a reading of the trees and needs
+* no simulation.
+**/
+async function runAssetScores({ client, chainId, slots, compressor, logger }) {
+	const running = slots.filter((slot) => !slot.isShutdown);
+	const oracles = [...new Set(running.map((slot) => slot.priceOracle.toLowerCase()))];
+	const { nodes, unreadableOracles } = await readForest(client, compressor, oracles);
+	for (const oracle of unreadableOracles) logger?.warn(`price oracle ${oracle} of chain ${chainId} would not report its feed tree; the markets on it are not scored`);
+	const { targets } = await readRateTargets(client, [...nodes.values()].filter((node) => RATE_FEED_TYPE.test(node.contractType)).map((node) => node.address));
+	const { sources } = classifySources(chainId, [...nodes.values()], targets, () => null);
+	const byTarget = new Map(sources.filter((source) => source.perturbable).map((source) => [source.target, toScoreSource(source)]));
+	const feedOf = (slot) => slot.priceFeed.toLowerCase();
+	const reach = sourcesByFeed([...new Set(running.map(feedOf))], nodes, sources);
+	const sourcesOf = (feed) => [...reach.get(feed) ?? []].map((target) => byTarget.get(target)).filter((source) => source !== void 0);
+	const positions = /* @__PURE__ */ new Map();
+	for (const slot of running) {
+		const key = `${slot.market.toLowerCase()}:${slot.token.toLowerCase()}`;
+		const position = positions.get(key) ?? {};
+		position[slot.reserve ? "reserve" : "main"] = slot;
+		positions.set(key, position);
+	}
+	const byAsset = /* @__PURE__ */ new Map();
+	for (const { main, reserve } of positions.values()) {
+		if (!main || main.isUnderlying) continue;
+		const asset = main.token.toLowerCase();
+		const entry = byAsset.get(asset) ?? {
+			symbol: main.tokenSymbol,
+			markets: []
+		};
+		byAsset.set(asset, entry);
+		const mainNode = nodes.get(feedOf(main));
+		if (!mainNode) continue;
+		if (mainNode.contractType === "PRICE_FEED::ZERO") continue;
+		const side = (slot) => ({
+			feed: {
+				feed: feedOf(slot),
+				name: slot.priceFeedName,
+				contractType: nodes.get(feedOf(slot))?.contractType ?? ""
+			},
+			sources: sourcesOf(feedOf(slot))
+		});
+		entry.markets.push(scoreMarket({
+			market: main.market,
+			marketName: main.marketName,
+			marketConfigurator: main.marketConfigurator,
+			curatorName: main.curatorName
+		}, side(main), reserve ? side(reserve) : null));
+	}
+	return [...byAsset].map(([asset, { symbol, markets }]) => {
+		const sorted = markets.sort((a, b) => a.score - b.score);
+		const worst = sorted[0] ?? null;
+		return {
+			chainId,
+			asset,
+			symbol,
+			score: worst?.score ?? null,
+			unverified: sorted.some((market) => market.unverified),
+			worst,
+			markets: sorted
+		};
+	});
+}
+//#endregion
+export { runAssetScores };

package/dist/esm/permissionless/api/oracles/score/types.js

@@ -0,0 +1 @@
+export {};