@gearbox-protocol/sdk 18.3.1 → 18.4.0

package/dist/cjs/permissionless/api/oracles/stress/run.js

@@ -0,0 +1,485 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_abi_compressors_priceFeedCompressor = require("../../../../abi/compressors/priceFeedCompressor.js");
+const require_permissionless_api_oracles_stress_classify = require("./classify.js");
+const require_permissionless_api_oracles_stress_override = require("./override.js");
+const require_permissionless_api_oracles_stress_score = require("./score.js");
+let viem = require("viem");
+//#region src/permissionless/api/oracles/stress/run.ts
+/**
+* The two ends the question is asked at, which is what "infinitely large and
+* infinitely small" comes to once a type has to hold it.
+*/
+const DEFAULT_SCENARIOS = [{
+	label: "unbounded up",
+	multiplier: require_permissionless_api_oracles_stress_override.UNBOUNDED_UP
+}, {
+	label: "unbounded down",
+	multiplier: require_permissionless_api_oracles_stress_override.UNBOUNDED_DOWN
+}];
+const aggregatorAbi = (0, viem.parseAbi)(["function latestRoundData() view returns (uint80, int256, uint256, uint256, uint80)"]);
+/**
+* What a Gearbox LP feed exposes about the rate it reads.
+*
+* `lpContract` is the contract the rate comes off — the wstETH token, the
+* vault, the Curve pool — and is what a rate source is perturbed at.
+* The two bounds are the window the feed will accept a rate inside, which is
+* both this test's baseline and, as it turns out, most of its answer.
+*/
+const lpFeedAbi = (0, viem.parseAbi)([
+	"function lpContract() view returns (address)",
+	"function lowerBound() view returns (uint256)",
+	"function upperBound() view returns (uint256)"
+]);
+/**
+* The Gearbox LP feeds: a protocol's exchange rate, clamped to a window the
+* feed holds, times the price of what the rate is denominated in.
+*/
+const RATE_FEED_TYPE = /::(ERC4626|CURVE_\w+|WSTETH|YEARN|MELLOW\w*|BALANCER\w*)$/;
+/** The compressor's `bytes32` contract type, as the string it encodes. */
+function typeName(raw) {
+	return (0, viem.hexToString)(raw).replace(/\0+$/, "");
+}
+/** `price × amount` in USD, both of them as the chain reports them. */
+function usd(amount, price) {
+	if (amount === null || price === null || price <= 0n) return null;
+	return amount * Number((0, viem.formatUnits)(price, 8));
+}
+/**
+* The feed trees of every oracle the chain's markets use, flattened.
+*
+* One call per oracle and not per feed: the compressor answers an oracle's
+* entire tree at once, with every node's type, description, children and
+* current answer, which is the whole of what this test needs off the chain.
+* A node carried by several oracles is one node — the trees overlap heavily,
+* since the aggregators under them are the same handful.
+*/
+async function readForest(client, compressor, oracles) {
+	const states = await client.multicall({
+		contracts: oracles.map((oracle) => ({
+			address: compressor,
+			abi: require_abi_compressors_priceFeedCompressor.priceFeedCompressorAbi,
+			functionName: "getPriceOracleState",
+			args: [oracle]
+		})),
+		allowFailure: true
+	});
+	const nodes = /* @__PURE__ */ new Map();
+	const answers = /* @__PURE__ */ new Map();
+	const unreadableOracles = [];
+	states.forEach((state, i) => {
+		if (state.status !== "success") {
+			unreadableOracles.push(oracles[i]);
+			return;
+		}
+		const { priceFeedTree } = state.result;
+		addTree(priceFeedTree, nodes, answers);
+	});
+	return {
+		nodes,
+		answers,
+		unreadableOracles
+	};
+}
+/**
+* The trees under a handful of feeds, flattened, whether or not any oracle
+* holds them.
+*
+* One call for all of them: the compressor walks the feeds it is given the
+* way it walks an oracle's, and answers with the same nodes.
+*/
+async function readFeedTrees(client, compressor, feeds) {
+	const tree = await client.readContract({
+		address: compressor,
+		abi: require_abi_compressors_priceFeedCompressor.priceFeedCompressorAbi,
+		functionName: "loadPriceFeedTree",
+		args: [feeds]
+	});
+	const nodes = /* @__PURE__ */ new Map();
+	const answers = /* @__PURE__ */ new Map();
+	addTree(tree, nodes, answers);
+	return {
+		nodes,
+		answers
+	};
+}
+/** A tree's nodes into the flattened forest, the first copy of each kept. */
+function addTree(tree, nodes, answers) {
+	for (const node of tree) {
+		const address = node.baseParams.addr.toLowerCase();
+		if (nodes.has(address)) continue;
+		nodes.set(address, {
+			address,
+			contractType: typeName(node.baseParams.contractType),
+			version: Number(node.baseParams.version),
+			description: node.description,
+			underlyingFeeds: node.underlyingFeeds.map((feed) => feed.toLowerCase())
+		});
+		answers.set(address, node.answer.success ? node.answer.price : null);
+	}
+}
+/**
+* Where each rate-bearing feed reads its rate, and what it will accept.
+*
+* The baseline a rate source is perturbed from is the feed's own `lowerBound`
+* and not the rate itself. Reading the rate would mean knowing which getter
+* each protocol publishes it under — `stEthPerToken`, `convertToAssets`,
+* `get_virtual_price`, `pricePerShare` — and in exactly which units, which is
+* a table that goes stale. The bound is within the feed's own accepted window
+* of the live rate by construction, so it is the same figure to within that
+* window, which is two percent or so. That is immaterial against the
+* multipliers the ends of the sweep use, and at the fine end of the threshold
+* search the bound *is* the answer: an LP feed clamps the rate it accepts, so
+* where it breaks is where its bound is.
+*/
+async function readRateTargets(client, feeds) {
+	const targets = /* @__PURE__ */ new Map();
+	const baselines = /* @__PURE__ */ new Map();
+	const bounds = /* @__PURE__ */ new Map();
+	if (feeds.length === 0) return {
+		targets,
+		baselines,
+		bounds
+	};
+	const results = await client.multicall({
+		contracts: feeds.flatMap((address) => [
+			{
+				address,
+				abi: lpFeedAbi,
+				functionName: "lpContract"
+			},
+			{
+				address,
+				abi: lpFeedAbi,
+				functionName: "lowerBound"
+			},
+			{
+				address,
+				abi: lpFeedAbi,
+				functionName: "upperBound"
+			}
+		]),
+		allowFailure: true
+	});
+	feeds.forEach((feed, i) => {
+		const contract = results[3 * i];
+		const lower = results[3 * i + 1];
+		const upper = results[3 * i + 2];
+		if (contract?.status !== "success" || lower?.status !== "success") return;
+		const target = contract.result.toLowerCase();
+		targets.set(feed, target);
+		baselines.set(target, lower.result);
+		if (upper?.status === "success") bounds.set(feed, {
+			lower: lower.result,
+			upper: upper.result
+		});
+	});
+	return {
+		targets,
+		baselines,
+		bounds
+	};
+}
+/** Tries after the first before a refused read is given up on. */
+const READ_RETRIES = 3;
+/**
+* A multicall failure that is the node's and not the feed's.
+*
+* A call that reverted inside the multicall is decoded from its own return
+* data and carries no error of the `eth_call` around it; a chunk the node
+* refused carries exactly that, for every call in the chunk.
+*/
+function isRefusal(error) {
+	return error instanceof viem.BaseError && error.walk((cause) => cause instanceof viem.CallExecutionError) !== null;
+}
+/**
+* What every feed answers with one group's sources overridden.
+*
+* One `eth_call` for the whole chain: the overrides go in once and the feeds
+* are read through a multicall inside them, so a group costs a round trip per
+* scenario rather than a round trip per feed. A feed that reverts comes back
+* `null`, which is an outcome and not an error.
+*/
+async function readUnder(client, feeds, sources, multiplier, updatedAt, freshen = []) {
+	const driven = require_permissionless_api_oracles_stress_override.groupOverride(sources, multiplier, updatedAt);
+	const taken = new Set(driven.map((override) => override.address.toLowerCase()));
+	const overrides = [...require_permissionless_api_oracles_stress_override.groupOverride(freshen, 1, updatedAt).filter((override) => !taken.has(override.address.toLowerCase())), ...driven];
+	const readOnce = () => client.multicall({
+		contracts: feeds.map((address) => ({
+			address,
+			abi: aggregatorAbi,
+			functionName: "latestRoundData"
+		})),
+		allowFailure: true,
+		stateOverride: overrides.length > 0 ? overrides : void 0
+	});
+	let results = [];
+	for (let attempt = 0;; attempt++) {
+		results = await readOnce();
+		const refused = results.find((result) => result.status === "failure" && isRefusal(result.error));
+		if (!refused) break;
+		if (attempt >= READ_RETRIES) {
+			const reason = refused.error instanceof viem.BaseError ? refused.error.walk().shortMessage : String(refused.error);
+			throw new Error(`the node would not answer a read of ${feeds.length} feeds after 4 tries: ${reason}`, { cause: refused.error });
+		}
+		await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
+	}
+	return new Map(feeds.map((feed, i) => {
+		const result = results[i];
+		return [feed, result?.status === "success" ? result.result[1] ?? null : null];
+	}));
+}
+/**
+* A perturbation too small for any protection to be aimed at, which is what
+* makes it a control.
+*
+* A tenth of a percent is inside every bound these feeds carry and under every
+* deviation threshold, so a slot that does not budge under it is a slot the
+* override never reached — and every other figure about it is then unknown
+* rather than reassuring.
+*/
+const CALIBRATION_MULTIPLIER = 1.001;
+/**
+* How many of a group's reachable slots actually responded to being driven.
+*
+* Exact inequality on the answer and not a factor: at a tenth of a percent the
+* point is only whether the number moved at all.
+*/
+async function countResponsive(client, roots, slots, members, base, updatedAt) {
+	const nudged = await readUnder(client, roots, members, CALIBRATION_MULTIPLIER, updatedAt);
+	return slots.filter((slot) => {
+		return (base.get(slot.priceFeed) ?? null) !== (nudged.get(slot.priceFeed) ?? null);
+	}).length;
+}
+/** `stressed / base`, or `null` where either end is missing. */
+function factorOf(base, stressed) {
+	if (base === null || stressed === null || base === 0n) return null;
+	return Number(stressed) / Number(base);
+}
+/**
+* What a group did to one chain, market slot by market slot.
+*
+* The ratio and not the price: a slot is scored by how the collateral moved
+* against the market's own underlying, because that is what an account is
+* valued by. A group that moves both legs equally has moved nothing, and this
+* is where that shows up — the underlying's own feed is one of the feeds read
+* under the same override, so both legs come from the same call.
+*/
+function outcomeOf(scenario, slots, base, stressed, quotaUsd, chainTotalUsd) {
+	const movedPositions = /* @__PURE__ */ new Set();
+	const out = slots.map((slot) => {
+		const feed = {
+			feed: slot.priceFeed,
+			base: base.get(slot.priceFeed) ?? null,
+			stressed: stressed.get(slot.priceFeed) ?? null,
+			factor: factorOf(base.get(slot.priceFeed) ?? null, stressed.get(slot.priceFeed) ?? null)
+		};
+		const underlying = slot.underlyingPriceFeed;
+		const underlyingFactor = underlying === null ? 1 : factorOf(base.get(underlying) ?? null, stressed.get(underlying) ?? null) ?? null;
+		return {
+			market: slot.market,
+			marketName: slot.marketName,
+			curatorName: slot.curatorName,
+			token: slot.token,
+			tokenSymbol: slot.tokenSymbol,
+			reserve: slot.reserve,
+			isUnderlying: slot.isUnderlying,
+			feed,
+			ratioFactor: feed.factor === null || underlyingFactor === null || underlyingFactor === 0 ? null : feed.factor / underlyingFactor,
+			quotaUsedUsd: quotaUsd.get(slotKey(slot)) ?? null
+		};
+	});
+	const ratios = out.map((slot) => slot.ratioFactor).filter((r) => r !== null && Number.isFinite(r));
+	let movedUsd = 0;
+	slots.forEach((slot, i) => {
+		const outcome = out[i];
+		if (!(outcome !== void 0 && (outcome.ratioFactor !== null && outcome.ratioFactor !== 1 || outcome.feed.stressed === null && outcome.feed.base !== null)) || movedPositions.has(positionKey(slot))) return;
+		movedPositions.add(positionKey(slot));
+		movedUsd += outcome.quotaUsedUsd ?? 0;
+	});
+	return {
+		scenario,
+		slots: out,
+		worstInflation: ratios.length > 0 ? Math.max(...ratios) : null,
+		worstDeflation: ratios.length > 0 ? Math.min(...ratios) : null,
+		brokenSlots: out.filter((slot) => slot.feed.stressed === null && slot.feed.base !== null).length,
+		deadSlots: out.filter((slot) => slot.feed.base === null).length,
+		valueAtRisk: chainTotalUsd > 0 ? movedUsd / chainTotalUsd : 0
+	};
+}
+/** What identifies a slot across the reads that describe it. */
+function slotKey(slot) {
+	return `${slot.market}:${slot.token}:${slot.reserve}`;
+}
+/**
+* What identifies the *position* a slot prices, which is not the slot.
+*
+* A quota belongs to a `(market, token)` pair, and that pair has two slots:
+* the main feed and the reserve one. Summing money over slots would count
+* every such pair twice, so anything denominated in money is summed over this
+* instead, and the slot figures stay per slot.
+*/
+function positionKey(slot) {
+	return `${slot.market}:${slot.token}`;
+}
+/**
+* The quota riding on a set of slots, counted once per position.
+*
+* The sum a reader takes to be money at risk, so the double counting a
+* token's two slots would introduce is removed here rather than left for them
+* to notice.
+*/
+function quotaOver(slots, quotaUsd) {
+	const counted = /* @__PURE__ */ new Set();
+	let total = 0;
+	for (const slot of slots) {
+		const key = positionKey(slot);
+		if (counted.has(key)) continue;
+		counted.add(key);
+		total += quotaUsd.get(slotKey(slot)) ?? 0;
+	}
+	return total;
+}
+/**
+* The smallest multiple of a group's sources that moves some market past a
+* ratio of `target`, found by bisection.
+*
+* Eight steps over twelve orders of magnitude, which lands the answer inside a
+* factor of about ten percent — enough to say whether a source has to be
+* wrong by a percent or by a thousandfold before anything breaks, which is the
+* question. `null` is a group that does not get there at the far end either.
+*/
+async function bisect(read, from, to, target, steps = 8) {
+	if (!target(await read(to))) return null;
+	let lo = from;
+	let hi = to;
+	for (let i = 0; i < steps; i++) {
+		const mid = Math.sqrt(lo * hi);
+		if (target(await read(mid))) hi = mid;
+		else lo = mid;
+	}
+	return hi;
+}
+/**
+* Every source behind one chain's markets, put through the sweep a group at a
+* time.
+*
+* Takes the slots as read, so the caller decides whether that read came from
+* the backend or from somewhere else, and takes a client rather than making
+* one, so the whole thing is testable against a stub.
+**/
+async function runStressTest({ client, chainId, slots, compressor, scenarios = DEFAULT_SCENARIOS, thresholds = true, groups: only, logger }) {
+	const { nodes, answers, unreadableOracles } = await readForest(client, compressor, [...new Set(slots.map((slot) => slot.priceOracle.toLowerCase()))]);
+	for (const oracle of unreadableOracles) logger?.warn(`price oracle ${oracle} of chain ${chainId} would not report its feed tree; the markets on it are left out`);
+	const { targets, baselines: rateBaselines } = await readRateTargets(client, [...nodes.values()].filter((node) => RATE_FEED_TYPE.test(node.contractType)).map((node) => node.address));
+	const { sources, unresolved } = require_permissionless_api_oracles_stress_classify.classifySources(chainId, [...nodes.values()], targets, (target) => rateBaselines.get(target) ?? answers.get(target) ?? null);
+	for (const node of unresolved) logger?.warn(`feed ${node.address} of chain ${chainId} would not say what it reads its rate from; its protocol is left out of the partition`);
+	const roots = [.../* @__PURE__ */ new Set([...slots.map((slot) => slot.priceFeed), ...slots.map((slot) => slot.underlyingPriceFeed).filter((feed) => feed !== null)])];
+	const reach = require_permissionless_api_oracles_stress_classify.sourcesByFeed(roots, nodes, sources);
+	const quotaUsd = /* @__PURE__ */ new Map();
+	for (const slot of slots) {
+		const price = slot.underlyingPriceFeed === null ? null : answers.get(slot.underlyingPriceFeed) ?? null;
+		quotaUsd.set(slotKey(slot), usd(slot.quotaUsed, price));
+	}
+	const totalUsd = quotaOver(slots, quotaUsd);
+	const updatedAt = BigInt(Math.floor(Date.now() / 1e3));
+	const base = await readUnder(client, roots, [], 1, updatedAt);
+	const byGroup = /* @__PURE__ */ new Map();
+	for (const source of sources) byGroup.set(source.group, [...byGroup.get(source.group) ?? [], source]);
+	const unidentifiedUsd = quotaOver(slots.filter((slot) => {
+		const reached = reach.get(slot.priceFeed);
+		return sources.some((source) => !source.identified && reached?.has(source.target));
+	}), quotaUsd);
+	const reports = [];
+	for (const [group, members] of byGroup) {
+		if (only && !only.includes(group)) continue;
+		const targetSet = new Set(members.map((source) => source.target));
+		const reachable = slots.filter((slot) => [...reach.get(slot.priceFeed) ?? []].some((source) => targetSet.has(source)));
+		const reachableUsd = quotaOver(reachable, quotaUsd);
+		const roles = /* @__PURE__ */ new Map();
+		for (const slot of reachable) {
+			const key = positionKey(slot);
+			roles.set(key, (roles.get(key) ?? /* @__PURE__ */ new Set()).add(slot.reserve));
+		}
+		const undefendedPositions = [...roles.values()].filter((set) => set.has(true) && set.has(false)).length;
+		const silentSources = members.filter((source) => source.perturbable && source.baseline === null).length;
+		const drivable = members.filter((source) => source.perturbable && source.baseline !== null);
+		if (reachable.length === 0 || drivable.length === 0) {
+			reports.push({
+				chainId,
+				group,
+				sources: members,
+				identified: members.every((source) => source.identified),
+				reachableSlots: reachable.length,
+				reachableUsd,
+				undefendedPositions,
+				outcomes: [],
+				breakingPoints: [],
+				responsive: 0,
+				silentSources,
+				score: 10,
+				verdict: require_permissionless_api_oracles_stress_score.verdictOf(group, 10, [], reachable.length, reachableUsd, 0, silentSources, undefendedPositions, members.some((source) => !source.perturbable))
+			});
+			continue;
+		}
+		const outcomes = [];
+		for (const scenario of scenarios) {
+			const stressed = await readUnder(client, roots, members, scenario.multiplier, updatedAt);
+			outcomes.push(outcomeOf(scenario, reachable, base, stressed, quotaUsd, totalUsd));
+		}
+		const breakingPoints = [];
+		if (thresholds) {
+			const worstRatio = async (multiplier) => {
+				const stressed = await readUnder(client, roots, members, multiplier, updatedAt);
+				const outcome = outcomeOf({
+					label: "probe",
+					multiplier
+				}, reachable, base, stressed, quotaUsd, totalUsd);
+				return Math.max(outcome.worstInflation ?? 1, 1 / (outcome.worstDeflation ?? 1));
+			};
+			const up = await bisect(worstRatio, 1, require_permissionless_api_oracles_stress_override.UNBOUNDED_UP, (worst) => worst >= 2);
+			const down = await bisect(worstRatio, 1, require_permissionless_api_oracles_stress_override.UNBOUNDED_DOWN, (worst) => worst >= 2);
+			breakingPoints.push({
+				market: reachable[0]?.market ?? "0x",
+				token: reachable[0]?.token ?? "0x",
+				inflation: up,
+				deflation: down
+			});
+		}
+		const responsive = await countResponsive(client, roots, reachable, members, base, updatedAt);
+		const score = require_permissionless_api_oracles_stress_score.scoreGroup(outcomes);
+		reports.push({
+			chainId,
+			group,
+			sources: members,
+			identified: members.every((source) => source.identified),
+			reachableSlots: reachable.length,
+			reachableUsd,
+			undefendedPositions,
+			outcomes,
+			breakingPoints,
+			responsive,
+			silentSources,
+			score,
+			verdict: require_permissionless_api_oracles_stress_score.verdictOf(group, score, outcomes, reachable.length, reachableUsd, responsive, silentSources, undefendedPositions, false)
+		});
+	}
+	return {
+		chainId,
+		slots: slots.length,
+		roots: roots.length,
+		nodes: nodes.size,
+		deadSlots: slots.filter((slot) => (base.get(slot.priceFeed) ?? null) === null).length,
+		sources,
+		totalUsd,
+		unidentifiedUsd,
+		groups: reports.sort((a, b) => a.score - b.score || b.reachableUsd - a.reachableUsd)
+	};
+}
+//#endregion
+exports.DEFAULT_SCENARIOS = DEFAULT_SCENARIOS;
+exports.RATE_FEED_TYPE = RATE_FEED_TYPE;
+exports.readFeedTrees = readFeedTrees;
+exports.readForest = readForest;
+exports.readRateTargets = readRateTargets;
+exports.readUnder = readUnder;
+exports.runStressTest = runStressTest;

package/dist/cjs/permissionless/api/oracles/stress/score.js

@@ -0,0 +1,98 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/permissionless/api/oracles/stress/score.ts
+/**
+* Turning what a group did into a mark out of ten.
+*
+* Any single number over a thing this shaped is a judgement, so the one here
+* is spelled out rather than tuned: what it weighs, and why each term is
+* weighed that way, is in the comments below, and every figure it is computed
+* from stays in the report so a reader who disagrees can reweigh them.
+**/
+/**
+* How bad one slot's outcome is, on nought to one.
+*
+* Two kinds of harm, which are not the same kind of problem:
+*
+*  - a wrong price. The collateral is valued against the market's underlying,
+*    so what matters is the ratio and not either leg: a market whose
+*    collateral and underlying both doubled has not moved. Overvalued
+*    collateral is borrowed against and the loan is never repaid; undervalued
+*    collateral is liquidated out from under an account that was solvent.
+*    Both are counted, because a reader asking what a source can do to them
+*    is exposed to each.
+*
+*  - a price that stopped. The slot reverted where it used to answer, which
+*    freezes the market: nothing can be borrowed and, worse, nothing can be
+*    liquidated. Scored at half a full mispricing — it is a liveness failure
+*    rather than a licence to drain, and it is also loud, where a wrong number
+*    is silent.
+*
+* A hundredfold move in the ratio is full harm. Ten times is a half, and the
+* curve is logarithmic between them because the damage is: a position is
+* liquidatable somewhere around a tenth of a move, and everything past that is
+* degrees of already-gone.
+*/
+function slotHarm(slot) {
+	if (slot.feed.stressed === null && slot.feed.base !== null) return .5;
+	const factor = slot.ratioFactor;
+	if (factor === null || factor === 1 || !Number.isFinite(factor)) return factor !== null && !Number.isFinite(factor) ? 1 : 0;
+	return Math.min(1, Math.abs(Math.log10(factor)) / 2);
+}
+/**
+* The group's mark, over every scenario it was put through.
+*
+* Two views of the same slots, because either alone misleads. Weighing harm by
+* the quota riding on it is what a reader with money in the protocol wants —
+* a source that can only move a market with nothing in it has not done much.
+* But a market with nothing in it today is where tomorrow's deposit goes, so
+* the worst slot regardless of size is carried too, at a smaller weight.
+*
+* Ten is a group that moved nothing. Nought is one that revalued everything
+* the chain has out.
+*/
+function scoreGroup(outcomes) {
+	let weighted = 0;
+	let worst = 0;
+	for (const outcome of outcomes) {
+		const total = outcome.slots.reduce((sum, slot) => sum + (slot.quotaUsedUsd ?? 0), 0);
+		let scenarioWeighted = 0;
+		for (const slot of outcome.slots) {
+			const harm = slotHarm(slot);
+			worst = Math.max(worst, harm);
+			if (total > 0) scenarioWeighted += (slot.quotaUsedUsd ?? 0) / total * harm;
+		}
+		weighted = Math.max(weighted, scenarioWeighted);
+	}
+	const damage = .7 * weighted + .3 * worst;
+	return Math.round((1 - damage) * 100) / 10;
+}
+/**
+* The one line the score stands for.
+*
+* Says which of the two failures the group causes, because the remedies
+* differ: a wrong price is answered with bounds and a second feed, a dead one
+* with a reserve feed and a staleness period.
+*/
+function verdictOf(group, score, outcomes, reachableSlots, reachableUsd, responsive, silentSources, undefendedPositions, selfContained) {
+	const money = () => `$${Math.round(reachableUsd).toLocaleString("en-US")} of quota`;
+	if (reachableSlots === 0) return `${group} prices nothing any market reads.`;
+	if (selfContained) return `${group} carries its price in its own code and is not published to, so there is no source to lie: ${money()} behind ${reachableSlots} slot(s), at the mercy of whoever can replace the contract rather than of whoever reports to it.`;
+	if (outcomes.length === 0) return `${group} is not answering as it stands — ${silentSources} silent source(s) — so nothing could be perturbed: ${money()} behind ${reachableSlots} slot(s) is priced through something already not reporting.`;
+	if (responsive === 0) return `${group}: not one of its ${reachableSlots} slot(s) moved under a perturbation of a tenth of a percent, so this test never drove it. Treat every figure for it as unknown, not as safe.`;
+	const broken = Math.max(...outcomes.map((o) => o.brokenSlots), 0);
+	const inflation = Math.max(...outcomes.map((o) => o.worstInflation ?? 1), 1);
+	const deflation = Math.min(...outcomes.map((o) => o.worstDeflation ?? 1), 1);
+	const ends = [inflation > 1.01 ? `${inflation.toExponential(1)}× too high` : null, deflation < .99 ? `${deflation.toExponential(1)}× of what it should be` : null].filter((end) => end !== null);
+	const dead = Math.max(...outcomes.map((o) => o.deadSlots), 0);
+	const live = reachableSlots - dead;
+	const moves = ends.length > 0 ? `drives the collateral-to-underlying ratio of up to ${live} live slot(s) to ${ends.join(" and ")}` : `moves no ratio by more than a percent, with ${responsive} slot(s) proven to respond at all`;
+	const freeze = broken > 0 ? `, and stops ${broken} of them answering` : "";
+	const undefended = undefendedPositions > 0 ? ` Its reach includes ${undefendedPositions} position(s) whose main and reserve feed both read it, so the fallback fails with it.` : "";
+	const standing = dead > 0 ? ` ${dead} of its slot(s) are priced through a feed that is not answering right now, before any of this.` : "";
+	const silent = silentSources > 0 ? ` (${silentSources} of its sources are already silent and were not perturbed)` : "";
+	return `${group} (${score}/10): ${money()} behind it; ${moves}${freeze}.${undefended}${standing}${silent}`;
+}
+//#endregion
+exports.scoreGroup = scoreGroup;
+exports.slotHarm = slotHarm;
+exports.verdictOf = verdictOf;

package/dist/cjs/permissionless/api/oracles/stress/types.js

@@ -0,0 +1 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });

package/dist/cjs/permissionless/api/schemas.js

@@ -12,8 +12,6 @@ let zod_v4 = require("zod/v4");
 **/
 /** An address, in whatever case the backend serves it. */
 const addressSchema = zod_v4.z.custom((value) => typeof value === "string" && (0, viem.isAddress)(value, { strict: false }), { message: "invalid address" });
-/** A `0x`-prefixed hex string, as viem's `Hex`. */
-const hexSchema = zod_v4.z.custom((value) => typeof value === "string" && (0, viem.isHex)(value), { message: "invalid hex string" });
 /**
 * A record keyed by address. Spelled out here because zod types a record key
 * by the schema's output, which the branded `Address` is not inferred as.
@@ -25,4 +23,3 @@ function addressRecord(value) {
 //#endregion
 exports.addressRecord = addressRecord;
 exports.addressSchema = addressSchema;
-exports.hexSchema = hexSchema;

package/dist/cjs/permissionless/api/transactions/InstanceOwnerTransactions.js

@@ -137,10 +137,21 @@ var InstanceOwnerTransactions = class {
 		const batch = await this.#batchContext(chainId);
 		const pfCompressor = await this.#priceFeedCompressor(batch.client);
 		const known = await batch.store.getKnownPriceFeeds();
+		const isKnown = new Set(known.map(lower));
 		const feeds = await require_permissionless_api_transactions_lp_price_feeds.getFeedsToUpdate(batch.client, pfCompressor, known);
+		const addTxs = [];
+		const added = [];
 		const configureTxs = [];
-		for (const feed of feeds) configureTxs.push(...await require_permissionless_api_transactions_lp_price_feeds.updateBounds(batch.client, feed));
-		const txs = [batch.store.configurePriceFeeds(configureTxs.map((tx) => ({
+		for (const feed of feeds) {
+			const boundTxs = await require_permissionless_api_transactions_lp_price_feeds.updateBounds(batch.client, feed.address);
+			if (boundTxs.length === 0) continue;
+			if (!isKnown.has(feed.address)) {
+				addTxs.push(batch.store.addPriceFeedTx(feed.address, 0, feed.description));
+				added.push(feed.address);
+			}
+			configureTxs.push(...boundTxs);
+		}
+		const txs = [...addTxs, batch.store.configurePriceFeeds(configureTxs.map((tx) => ({
 			target: tx.to,
 			callData: tx.callData
 		})))];
@@ -149,7 +160,7 @@ var InstanceOwnerTransactions = class {
 			author: owner,
 			name: "update-bounds",
 			txs,
-			touchedFeeds: []
+			touchedFeeds: added
 		});
 	}
 	/**

package/dist/cjs/permissionless/api/transactions/lp-price-feeds.js

@@ -52,9 +52,12 @@ async function updateBounds(client, address) {
 /**
 * Of the whole feed tree behind `feeds`, the ones that are LP feeds: the
 * probe keeps whatever answers `getLPExchangeRate`.
+*
+* The trees reach past `feeds` themselves, so an LP feed read inside one of
+* them is among the results whether or not it is one of `feeds`.
 **/
 async function getFeedsToUpdate(client, pfCompressor, feeds) {
-	const updateableFeeds = /* @__PURE__ */ new Set();
+	const updateableFeeds = /* @__PURE__ */ new Map();
 	const { data } = await client.call({
 		to: pfCompressor,
 		data: (0, viem.encodeFunctionData)({
@@ -69,8 +72,8 @@ async function getFeedsToUpdate(client, pfCompressor, feeds) {
 		functionName: "loadPriceFeedTree",
 		data: data ?? "0x"
 	});
-	for (const tree of trees) updateableFeeds.add(tree.baseParams.addr.toLowerCase());
-	const candidates = Array.from(updateableFeeds);
+	for (const tree of trees) updateableFeeds.set(tree.baseParams.addr.toLowerCase(), tree.description);
+	const candidates = Array.from(updateableFeeds.keys());
 	const { results } = await require_onchain_utils_viem_simulateMulticall.simulateMulticall(client, {
 		contracts: candidates.map((feed) => ({
 			address: feed,
@@ -79,7 +82,10 @@ async function getFeedsToUpdate(client, pfCompressor, feeds) {
 		})),
 		allowFailure: true
 	});
-	return candidates.filter((_, index) => results[index]?.status === "success");
+	return candidates.filter((_, index) => results[index]?.status === "success").map((address) => ({
+		address,
+		description: updateableFeeds.get(address) ?? ""
+	}));
 }
 //#endregion
 exports.getFeedsToUpdate = getFeedsToUpdate;