@gearbox-protocol/sdk 18.3.0 → 18.4.0

package/dist/esm/permissionless/api/oracles/stress/classify.js

@@ -0,0 +1,256 @@
+//#region src/permissionless/api/oracles/stress/classify.ts
+/**
+* The feed types whose price is a protocol's exchange rate read off a
+* contract, mapped to the group that rate belongs to.
+*
+* These are not leaves: an LP feed also reads the price of whatever the rate
+* is denominated in, and that child is somebody else's source. What belongs to
+* the protocol is the rate alone, which is why these are perturbed at the
+* contract the feed reads it from rather than at the feed.
+*
+* `null` means the protocol is the vault's own and has to come from
+* {@link VAULT_GROUPS} or, failing that, from the feed's description.
+*/
+const RATE_TYPE_GROUPS = {
+	WSTETH: "Lido",
+	CURVE_STABLE: "Curve",
+	CURVE_CRYPTO: "Curve",
+	CURVE_TWAP: "Curve",
+	YEARN: "Yearn",
+	MELLOW_LRT: "Mellow",
+	BALANCER_STABLE: "Balancer",
+	BALANCER_WEIGHTED: "Balancer",
+	ERC4626: null
+};
+/**
+* Which protocol an ERC-4626 vault belongs to, by the symbol its feed is
+* described with.
+*
+* Curated, and deliberately short: a vault not named here becomes a group of
+* one under its own symbol, which is still a correct partition — one vault is
+* one source — and is flagged so a reader knows nothing claims it fails
+* alongside anything else.
+*/
+const VAULT_GROUPS = {
+	sUSDS: "Sky",
+	sDAI: "Sky",
+	sUSDe: "Ethena",
+	sUSDf: "Falcon",
+	wstUSR: "Resolv",
+	syrupUSDC: "Maple",
+	hgETH: "Kelp",
+	rstETH: "Mellow",
+	Re7LRT: "Mellow",
+	pzETH: "Mellow",
+	DVstETH: "Mellow",
+	tETH: "Treehouse"
+};
+/**
+* Rules over a Chainlink-shaped feed's own description, in order.
+*
+* Only reached for a leaf Gearbox did not deploy, which is where the provider
+* is not already stated. The first match wins, so the specific patterns come
+* before the general shape of a Chainlink pair.
+*/
+const DESCRIPTION_RULES = [
+	{
+		via: "description names Redstone",
+		match: /redstone/i,
+		group: "Redstone"
+	},
+	{
+		via: "description names Pyth",
+		match: /\bpyth\b/i,
+		group: "Pyth"
+	},
+	{
+		via: "description names Pendle",
+		match: /pendle/i,
+		group: "Pendle"
+	},
+	{
+		via: "description names Chronicle",
+		match: /chronicle/i,
+		group: "Chronicle"
+	},
+	{
+		via: "description names API3",
+		match: /\bapi3\b/i,
+		group: "API3"
+	},
+	{
+		via: "description names Chaos",
+		match: /chaos\s*labs/i,
+		group: "Chaos Labs"
+	},
+	{
+		via: "Midas naming convention",
+		match: /^m(TBILL|BASIS|EDGE|F-ONE|GLOBAL|Re7YIELD|[A-Z]{2,}[0-9]*)\s*\//,
+		group: "Midas"
+	},
+	{
+		via: "exchange-rate adapter, grouped by its token",
+		match: /^([A-Za-z0-9+]+)\s*[/-]\s*[A-Za-z0-9+]+\s+exchange\s+rate/i,
+		group: (m) => m[1]
+	}
+];
+/**
+* Whether a description is a Chainlink pair: `BASE / QUOTE`, spaced, in the
+* shape their aggregators have published for years.
+*
+* Paired with a version of 6, which is what `EACAggregatorProxy` answers and
+* what the imitators — version 0 or 1, mostly — do not. Either alone would be
+* wrong: plenty of adapters describe themselves as a spaced pair, and plenty
+* of Chainlink feeds are read through a wrapper that reports another version.
+*/
+const CHAINLINK_PAIR = /^[A-Za-z0-9+]+ \/ [A-Za-z0-9+]+$/;
+/** Feed types that are their own answer, with no source behind them at all. */
+const SELF_CONTAINED = {
+	CONSTANT: "Constant",
+	ZERO: "Zero"
+};
+/** The type without the `PRICE_FEED::` the bytecode repository prefixes it with. */
+function bareType(contractType) {
+	return contractType.replace(/^PRICE_FEED::/, "");
+}
+/**
+* Which group a leaf price feed belongs to, and how that was decided.
+*
+* The order is what makes it defensible: what Gearbox deployed says who it
+* reads, so those types are taken first; then the description rules, most
+* specific first; then the Chainlink shape; and anything left is its own group
+* under its own description, flagged.
+*/
+function classifyLeaf(node) {
+	const type = bareType(node.contractType);
+	const selfContained = SELF_CONTAINED[type];
+	if (selfContained) return {
+		group: selfContained,
+		identified: true,
+		via: "Gearbox feed type"
+	};
+	if (type === "REDSTONE" || type === "PYTH" || type === "CHAINLINK") return {
+		group: type === "PYTH" ? "Pyth" : type === "REDSTONE" ? "Redstone" : "Chainlink",
+		identified: true,
+		via: "Gearbox feed type"
+	};
+	for (const rule of DESCRIPTION_RULES) {
+		const m = node.description.match(rule.match);
+		if (m) return {
+			group: typeof rule.group === "function" ? rule.group(m) : rule.group,
+			identified: true,
+			via: rule.via
+		};
+	}
+	if (CHAINLINK_PAIR.test(node.description) && node.version === 6) return {
+		group: "Chainlink",
+		identified: true,
+		via: "Chainlink pair description at interface version 6"
+	};
+	return {
+		group: node.description || node.address,
+		identified: false,
+		via: "unrecognised: grouped alone under its own description"
+	};
+}
+/**
+* Which group a rate-bearing feed's rate belongs to.
+*
+* The type names the protocol for everything but an ERC-4626 vault, where the
+* protocol is the vault's own and is looked up by the symbol the feed is
+* described with — `"sUSDS / USD LP price feed"` is Sky's.
+*/
+function classifyRate(node) {
+	const type = bareType(node.contractType);
+	const named = RATE_TYPE_GROUPS[type];
+	if (named) return {
+		group: named,
+		identified: true,
+		via: "Gearbox feed type"
+	};
+	const symbol = node.description.match(/^([A-Za-z0-9+.-]+)\s*\//)?.[1];
+	const protocol = symbol ? VAULT_GROUPS[symbol] : void 0;
+	if (protocol) return {
+		group: protocol,
+		identified: true,
+		via: "curated vault table"
+	};
+	return {
+		group: symbol ?? node.address,
+		identified: false,
+		via: "vault not in the curated table: grouped alone under its symbol"
+	};
+}
+/**
+* Every source behind a chain's feed trees.
+*
+* A source per contract, not per feed: two of an oracle's trees carrying the
+* same aggregator is one source read twice, and the test varies it once.
+*
+* `rateTargets` says which contract each rate-bearing feed reads its rate
+* from — the feed's own `lpContract`, read separately because the compressor
+* does not report it. A feed missing from it is left out with a reason, since
+* perturbing the whole feed instead would charge its protocol with a failure
+* of whatever prices the thing the rate is denominated in.
+**/
+function classifySources(chainId, nodes, rateTargets, baselineOf) {
+	const sources = [];
+	const unresolved = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const isRate = bareType(node.contractType) in RATE_TYPE_GROUPS;
+		if (!isRate && node.underlyingFeeds.length > 0) continue;
+		const target = isRate ? rateTargets.get(node.address) : node.address;
+		if (!target) {
+			unresolved.push(node);
+			continue;
+		}
+		if (seen.has(target)) continue;
+		seen.add(target);
+		sources.push({
+			chainId,
+			kind: isRate ? "rate" : "feed",
+			target,
+			feed: node.address,
+			contractType: node.contractType,
+			description: node.description,
+			perturbable: !(bareType(node.contractType) in SELF_CONTAINED),
+			baseline: baselineOf(target),
+			...isRate ? classifyRate(node) : classifyLeaf(node)
+		});
+	}
+	return {
+		sources,
+		unresolved
+	};
+}
+/**
+* The sources each of the given feeds is priced through, following the trees
+* down from every one of them.
+*
+* A feed is reached by a source when the source sits anywhere beneath it, at
+* any depth: a market reading a composite of a composite of a Chainlink
+* aggregator is a market Chainlink can move. Memoised over the whole forest,
+* so a node shared by twenty trees is walked once.
+**/
+function sourcesByFeed(roots, nodes, sources) {
+	const sourceOfFeed = /* @__PURE__ */ new Map();
+	for (const source of sources) sourceOfFeed.set(source.feed, source.target);
+	const memo = /* @__PURE__ */ new Map();
+	const walk = (feed, path) => {
+		const done = memo.get(feed);
+		if (done) return done;
+		if (path.has(feed)) return /* @__PURE__ */ new Set();
+		const found = /* @__PURE__ */ new Set();
+		const own = sourceOfFeed.get(feed);
+		if (own) found.add(own);
+		path.add(feed);
+		for (const child of nodes.get(feed)?.underlyingFeeds ?? []) for (const source of walk(child, path)) found.add(source);
+		path.delete(feed);
+		memo.set(feed, found);
+		return found;
+	};
+	return new Map(roots.map((root) => [root, walk(root, /* @__PURE__ */ new Set())]));
+}
+//#endregion
+export { classifySources, sourcesByFeed };

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

@@ -0,0 +1,6 @@
+import { classifySources, sourcesByFeed } from "./classify.js";
+import { UNBOUNDED_DOWN, UNBOUNDED_UP, groupOverride, perturb, rateStub, roundDataStub } from "./override.js";
+import { scoreGroup, slotHarm, verdictOf } from "./score.js";
+import { DEFAULT_SCENARIOS, RATE_FEED_TYPE, readFeedTrees, readForest, readRateTargets, readUnder, runStressTest } from "./run.js";
+import "./types.js";
+export { DEFAULT_SCENARIOS, RATE_FEED_TYPE, UNBOUNDED_DOWN, UNBOUNDED_UP, classifySources, groupOverride, perturb, rateStub, readFeedTrees, readForest, readRateTargets, readUnder, roundDataStub, runStressTest, scoreGroup, slotHarm, sourcesByFeed, verdictOf };

package/dist/esm/permissionless/api/oracles/stress/override.js

@@ -0,0 +1,119 @@
+//#region src/permissionless/api/oracles/stress/override.ts
+/**
+* Making a contract lie for the length of one `eth_call`.
+*
+* No fork and no simulation harness: an `eth_call` carries a state override,
+* so the aggregator's code is replaced for that call alone and everything
+* above it — the composite feeds, their bounds, the oracle's own checks — runs
+* as deployed, on real state, at the current block. What comes back is what
+* the market would have read.
+**/
+/** A word, as the 32 bytes `PUSH32` wants, two's complement for negatives. */
+function word(value) {
+	return BigInt.asUintN(256, value).toString(16).padStart(64, "0");
+}
+/**
+* Runtime code answering every call with the same five words.
+*
+* Deliberately selector-blind. A price feed is read through more than
+* `latestRoundData` — `decimals`, `version`, sometimes `latestAnswer` — and
+* dispatching on each would mean knowing which of them every caller in a tree
+* reaches for. Five words decode as the round data; a caller expecting one
+* word reads the first, which is why `roundId` is set to the 8 decimals every
+* Gearbox feed reports rather than to a round number.
+*
+* `answeredInRound` is the same 8, so the `answeredInRound >= roundId` check
+* the older consumers make passes.
+**/
+function roundDataStub(answer, updatedAt) {
+	return `0x${[
+		`7f${word(8n)}600052`,
+		`7f${word(answer)}602052`,
+		`7f${word(updatedAt)}604052`,
+		`7f${word(updatedAt)}606052`,
+		`7f${word(8n)}608052`,
+		"60a06000f3"
+	].join("")}`;
+}
+/**
+* Runtime code answering every call with one word.
+*
+* What an exchange rate getter returns, whichever of them the feed calls:
+* `stEthPerToken`, `convertToAssets`, `get_virtual_price`, `pricePerShare`
+* and `getRate` all answer a single `uint256`, so the stub does not need to
+* know which.
+**/
+function rateStub(rate) {
+	return `0x7f${word(rate)}60005260206000f3`;
+}
+/**
+* The two unbounded ends, as far as the types involved can carry them.
+*
+* "Infinitely large" has to stop somewhere: a price is an `int256` and the
+* arithmetic above it multiplies, so a genuinely enormous answer overflows
+* inside the composite feed and reverts — which would be scored as the
+* oracle resisting, when all that happened is that the test asked something
+* the type cannot hold. `1e12` times the current answer is past any bound,
+* any sanity check and any collateral ratio, and still multiplies.
+*/
+const UNBOUNDED_UP = 0xe8d4a51000;
+/** The other end: a thousandth of a trillionth, which is as near zero. */
+const UNBOUNDED_DOWN = 1e-12;
+/**
+* A double as an exact integer ratio.
+*
+* Multipliers here span twenty-four orders of magnitude, so the obvious
+* `BigInt(Math.round(m * 1e9))` is not available: at the top of the range the
+* product is past what a double carries exactly and the multiplier quietly
+* stops being the one that was asked for. Going through the decimal expansion
+* keeps all fifteen digits a double has and puts the magnitude in the
+* exponent, where it costs nothing.
+*/
+function asRatio(multiplier) {
+	const [mantissa = "0", exponent = "0"] = multiplier.toExponential(14).split("e");
+	const digits = BigInt(mantissa.replace(".", ""));
+	const power = Number(exponent) - 14;
+	return power >= 0 ? {
+		num: digits * 10n ** BigInt(power),
+		den: 1n
+	} : {
+		num: digits,
+		den: 10n ** BigInt(-power)
+	};
+}
+/**
+* What a source should answer under a multiplier, given what it answers now.
+*
+* Floored at one rather than at zero: a multiplier small enough to round the
+* baseline away would be testing a feed reporting nothing, which is the revert
+* case and is a different scenario with a different meaning.
+*/
+function perturb(baseline, multiplier) {
+	const { num, den } = asRatio(Number.isFinite(multiplier) ? Math.min(Math.max(multiplier, UNBOUNDED_DOWN), UNBOUNDED_UP) : multiplier > 0 ? UNBOUNDED_UP : UNBOUNDED_DOWN);
+	const out = baseline * num / den;
+	return out === 0n ? 1n : out;
+}
+/**
+* The state override that makes every source of a group answer a multiple of
+* what it answers now.
+*
+* One override per contract, so a group whose sources share an aggregator
+* perturbs it once. Sources with nothing behind them and sources that are not
+* answering are both left out, for the reasons on
+* {@link StressSource.perturbable} and {@link StressSource.baseline} — an
+* empty result is a group there is nothing to simulate about.
+**/
+function groupOverride(sources, multiplier, updatedAt) {
+	const overrides = [];
+	for (const source of sources) {
+		if (!source.perturbable || source.baseline === null) continue;
+		const value = perturb(source.baseline, multiplier);
+		overrides.push({
+			address: source.target,
+			code: source.kind === "rate" ? rateStub(value) : roundDataStub(value, updatedAt)
+		});
+	}
+	return overrides;
+}
+//#endregion
+export { UNBOUNDED_DOWN, UNBOUNDED_UP, groupOverride, perturb, rateStub, roundDataStub };