@gearbox-protocol/sdk 15.1.0-next.11 → 15.1.0-next.12

package/dist/cjs/dev/mode-parity/compareOpportunities.js

@@ -0,0 +1,105 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model_opportunities = require("../../model/opportunities.js");
+const require_model_opportunities_schema = require("../../model/opportunities.schema.js");
+require("../../model/index.js");
+const require_dev_mode_parity_fieldDiff = require("./fieldDiff.js");
+const require_dev_mode_parity_compareRules = require("./compareRules.js");
+//#region src/dev/mode-parity/compareOpportunities.ts
+const tagDiff = require_dev_mode_parity_compareRules.makeTagDiff({
+	pool: require_dev_mode_parity_compareRules.compileCompareRules(require_model_opportunities_schema.poolOpportunitySchema),
+	strategy: require_dev_mode_parity_compareRules.compileCompareRules(require_model_opportunities_schema.strategyOpportunitySchema)
+});
+/**
+* Matches two opportunity listings by {@link opportunityId} and reports every
+* field the two sources disagree on.
+*
+* Nothing is filtered out. A field only the backend can fill, or a USD value
+* that drifted within snapshot-lag noise, is still reported — tagged
+* {@link FieldDiff.expected} so that {@link CompareCounts.clean} can ignore it
+* while {@link CompareCounts.identical} stays strict.
+**/
+function compareOpportunities(input) {
+	const onchainRows = indexById(input.onchain.data);
+	const offchainRows = indexById(input.offchain.data);
+	const onlyOnchain = [];
+	const onlyOffchain = [];
+	const matched = [];
+	for (const [id, row] of onchainRows) {
+		const counterpart = offchainRows.get(id);
+		if (!counterpart) {
+			onlyOnchain.push(toRef(row));
+			continue;
+		}
+		const diffs = diffOpportunity(row, counterpart);
+		matched.push({
+			id,
+			kind: row.kind,
+			chainId: row.chainId,
+			onchainName: row.name,
+			offchainName: counterpart.name,
+			identical: diffs.length === 0,
+			clean: diffs.every((diff) => diff.expected),
+			diffs
+		});
+	}
+	for (const [id, row] of offchainRows) if (!onchainRows.has(id)) onlyOffchain.push(toRef(row));
+	byId(onlyOnchain);
+	byId(onlyOffchain);
+	matched.sort((a, b) => a.id.localeCompare(b.id));
+	return {
+		generatedAt: input.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		backendUrl: input.backendUrl,
+		networks: [...input.networks],
+		onchainChains: input.onchain.meta.chains,
+		offchainChains: input.offchain.meta.chains,
+		summary: summarize(input.onchain.data, input.offchain.data, onlyOnchain, onlyOffchain, matched),
+		onlyOnchain,
+		onlyOffchain,
+		matched
+	};
+}
+function indexById(rows) {
+	return new Map(rows.map((row) => [require_model_opportunities.opportunityId(row), row]));
+}
+function byId(refs) {
+	refs.sort((a, b) => a.id.localeCompare(b.id));
+}
+function toRef(row) {
+	const base = {
+		id: require_model_opportunities.opportunityId(row),
+		kind: row.kind,
+		chainId: row.chainId,
+		name: row.name
+	};
+	return row.kind === "pool" ? {
+		...base,
+		pool: row.pool
+	} : {
+		...base,
+		creditManager: row.creditManager,
+		targetCollateral: row.targetCollateral.address
+	};
+}
+/**
+* Every field two versions of one opportunity disagree on.
+**/
+function diffOpportunity(onchain, offchain) {
+	return require_dev_mode_parity_fieldDiff.diffObjects(onchain, offchain).map((diff) => tagDiff(diff, onchain.kind));
+}
+function summarize(onchain, offchain, onlyOnchain, onlyOffchain, matched) {
+	const byChain = require_dev_mode_parity_fieldDiff.union(onchain.map((row) => String(row.chainId)), offchain.map((row) => String(row.chainId))).map((chainId) => ({
+		chainId: Number(chainId),
+		...require_dev_mode_parity_fieldDiff.toCompareCounts(onchain.filter((row) => String(row.chainId) === chainId).length, offchain.filter((row) => String(row.chainId) === chainId).length, onlyOnchain.filter((ref) => String(ref.chainId) === chainId).length, onlyOffchain.filter((ref) => String(ref.chainId) === chainId).length, matched.filter((match) => String(match.chainId) === chainId))
+	})).sort((a, b) => a.chainId - b.chainId);
+	return {
+		...require_dev_mode_parity_fieldDiff.toCompareCounts(onchain.length, offchain.length, onlyOnchain.length, onlyOffchain.length, matched),
+		byChain,
+		diffsByPath: require_dev_mode_parity_fieldDiff.countPaths(matched.flatMap((match) => match.diffs.map((diff) => ({
+			id: match.id,
+			diff
+		}))))
+	};
+}
+//#endregion
+exports.compareOpportunities = compareOpportunities;
+exports.diffOpportunity = diffOpportunity;

package/dist/cjs/dev/{comparePositions.js → mode-parity/comparePositions.js}

@@ -1,8 +1,16 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_model_positions = require("../model/positions.js");
-require("../model/index.js");
-const require_dev_fieldDiff = require("./fieldDiff.js");
-//#region src/dev/comparePositions.ts
+const require_model_liquidations_schema = require("../../model/liquidations.schema.js");
+const require_model_positions = require("../../model/positions.js");
+const require_model_positions_schema = require("../../model/positions.schema.js");
+require("../../model/index.js");
+const require_dev_mode_parity_fieldDiff = require("./fieldDiff.js");
+const require_dev_mode_parity_compareRules = require("./compareRules.js");
+//#region src/dev/mode-parity/comparePositions.ts
+const tagDiff = require_dev_mode_parity_compareRules.makeTagDiff({
+	pool: require_dev_mode_parity_compareRules.compileCompareRules(require_model_positions_schema.poolPositionSchema),
+	strategy: require_dev_mode_parity_compareRules.compileCompareRules(require_model_positions_schema.strategyPositionSchema),
+	liquidation: require_dev_mode_parity_compareRules.compileCompareRules(require_model_liquidations_schema.liquidationPositionSchema)
+});
 /**
 * Matches two position listings per wallet by {@link positionId} and reports
 * every field the two sources disagree on.
@@ -36,7 +44,7 @@ function comparePositions(input) {
 * Every field two versions of one position disagree on.
 **/
 function diffPosition(onchain, offchain) {
-	return require_dev_fieldDiff.diffObjects(onchain, offchain, { keyOf: keyOfPositionArray }).map((diff) => tagDiff(diff, onchain.kind));
+	return require_dev_mode_parity_fieldDiff.diffObjects(onchain, offchain, { keyOf: keyOfPositionArray }).map((diff) => tagDiff(diff, onchain.kind));
 }
 function compareWallet(input) {
 	const onchainRows = indexById(input.onchain.data);
@@ -101,43 +109,9 @@ function toRef(row) {
 * address. Rewards-points programs already identify themselves by `id`.
 **/
 function keyOfPositionArray(path, value) {
-	if (path !== "collaterals" || !require_dev_fieldDiff.isRecord(value) || !require_dev_fieldDiff.isRecord(value.collateral)) return;
+	if (path !== "collaterals" || !require_dev_mode_parity_fieldDiff.isRecord(value) || !require_dev_mode_parity_fieldDiff.isRecord(value.collateral)) return;
 	const token = value.collateral.token;
-	return require_dev_fieldDiff.isRecord(token) && typeof token.address === "string" ? token.address : void 0;
-}
-const BPS_RATE_PATHS = /* @__PURE__ */ new Set([
-	"borrowApy",
-	"apy.organicApy",
-	"healthFactor"
-]);
-/**
-* Amount fields whose bigint `value` moves with interest accrual between the
-* backend's last sync and the current block.
-**/
-function isLagAmountPath(path) {
-	return path === "totalDebt.value" || path === "totalValue.value" || path === "netValue.value" || path.endsWith(".collateral.value") || path.endsWith(".quota.value");
-}
-/**
-* Fields documented `@mode offchain` or `@mode onchain` in the model.
-**/
-function isModeScoped(path, kind) {
-	if (path === "pnl" || path.startsWith("pnl.")) return true;
-	if (kind === "pool") return path === "apy.totalApy" || path.startsWith("apy.rewards");
-	if (kind === "strategy") return path === "netApy" || path.startsWith("netApy.") || path === "borrowRate" || path.startsWith("borrowRate.") || path === "timeToLiquidation" || path === "liquidationPrice";
-	return false;
-}
-function tagDiff(diff, kind) {
-	if (isModeScoped(diff.path, kind)) return require_dev_fieldDiff.withExpected(diff, "mode-scoped");
-	if (withinTolerance(diff)) return require_dev_fieldDiff.withExpected(diff, "tolerance");
-	return diff;
-}
-function withinTolerance(diff) {
-	if (diff.kind === "usd") return require_dev_fieldDiff.isUsdWithinTolerance(diff.onchain, diff.offchain);
-	if (diff.kind !== "numeric") return false;
-	if (diff.path === "leverage") return require_dev_fieldDiff.withinRelative(require_dev_fieldDiff.asFiniteNumber(diff.onchain), require_dev_fieldDiff.asFiniteNumber(diff.offchain), require_dev_fieldDiff.USD_RELATIVE_EPSILON);
-	if (BPS_RATE_PATHS.has(diff.path)) return require_dev_fieldDiff.isBpsWithinTolerance(diff.onchain, diff.offchain);
-	if (isLagAmountPath(diff.path)) return require_dev_fieldDiff.isAmountWithinTolerance(diff.onchain, diff.offchain);
-	return false;
+	return require_dev_mode_parity_fieldDiff.isRecord(token) && typeof token.address === "string" ? token.address : void 0;
 }
 function summarize(inputs, wallets, failed) {
 	const compared = wallets.filter((wallet) => !wallet.error);
@@ -146,24 +120,27 @@ function summarize(inputs, wallets, failed) {
 	const onlyOnchain = compared.flatMap((wallet) => wallet.onlyOnchain);
 	const onlyOffchain = compared.flatMap((wallet) => wallet.onlyOffchain);
 	const matched = compared.flatMap((wallet) => wallet.matched);
-	const byChain = require_dev_fieldDiff.union(allOnchain.map((row) => String(row.chainId)), allOffchain.map((row) => String(row.chainId))).map((chainId) => ({
+	const byChain = require_dev_mode_parity_fieldDiff.union(allOnchain.map((row) => String(row.chainId)), allOffchain.map((row) => String(row.chainId))).map((chainId) => ({
 		chainId: Number(chainId),
-		...require_dev_fieldDiff.toCompareCounts(allOnchain.filter((row) => String(row.chainId) === chainId).length, allOffchain.filter((row) => String(row.chainId) === chainId).length, onlyOnchain.filter((ref) => String(ref.chainId) === chainId).length, onlyOffchain.filter((ref) => String(ref.chainId) === chainId).length, matched.filter((match) => String(match.chainId) === chainId))
+		...require_dev_mode_parity_fieldDiff.toCompareCounts(allOnchain.filter((row) => String(row.chainId) === chainId).length, allOffchain.filter((row) => String(row.chainId) === chainId).length, onlyOnchain.filter((ref) => String(ref.chainId) === chainId).length, onlyOffchain.filter((ref) => String(ref.chainId) === chainId).length, matched.filter((match) => String(match.chainId) === chainId))
 	})).sort((a, b) => a.chainId - b.chainId);
 	const byWallet = wallets.map((wallet) => ({
 		wallet: wallet.wallet,
 		...wallet.error ? { error: wallet.error } : {},
-		...require_dev_fieldDiff.toCompareCounts(wallet.matched.length + wallet.onlyOnchain.length, wallet.matched.length + wallet.onlyOffchain.length, wallet.onlyOnchain.length, wallet.onlyOffchain.length, wallet.matched)
+		...require_dev_mode_parity_fieldDiff.toCompareCounts(wallet.matched.length + wallet.onlyOnchain.length, wallet.matched.length + wallet.onlyOffchain.length, wallet.onlyOnchain.length, wallet.onlyOffchain.length, wallet.matched)
 	}));
 	const walletsClean = compared.filter((wallet) => wallet.onlyOnchain.length === 0 && wallet.onlyOffchain.length === 0 && wallet.matched.every((match) => match.clean)).length;
 	return {
-		...require_dev_fieldDiff.toCompareCounts(allOnchain.length, allOffchain.length, onlyOnchain.length, onlyOffchain.length, matched),
+		...require_dev_mode_parity_fieldDiff.toCompareCounts(allOnchain.length, allOffchain.length, onlyOnchain.length, onlyOffchain.length, matched),
 		wallets: wallets.length,
 		walletsClean,
 		walletsFailed: failed,
 		byChain,
 		byWallet,
-		diffsByPath: require_dev_fieldDiff.countPaths(matched.flatMap((match) => match.diffs))
+		diffsByPath: require_dev_mode_parity_fieldDiff.countPaths(matched.flatMap((match) => match.diffs.map((diff) => ({
+			id: match.id,
+			diff
+		}))))
 	};
 }
 /**

package/dist/cjs/dev/mode-parity/compareRules.js

@@ -0,0 +1,93 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model_compare_schema = require("../../model/compare.schema.js");
+const require_dev_mode_parity_fieldDiff = require("./fieldDiff.js");
+//#region src/dev/mode-parity/compareRules.ts
+/**
+* Walks a schema and records every field that carries compare metadata.
+*
+* `"amount"` on an object (an Amount / TokenAmount) is stored
+* at `<path>.value`; every other tag is stored at the field's own path.
+**/
+function compileCompareRules(schema) {
+	const rules = /* @__PURE__ */ new Map();
+	walk(schema, "", /* @__PURE__ */ new Set(), rules);
+	return rules;
+}
+/**
+* Tags diffs using the rules compiled for each row kind.
+*
+* Mode tags match the path or anything nested under it. Tolerance tags match
+* the path exactly and dispatch on {@link CompareTolerance}.
+**/
+function makeTagDiff(rulesByKind) {
+	return (diff, kind) => {
+		const rules = rulesByKind[kind];
+		if (!rules) return diff;
+		const path = require_dev_mode_parity_fieldDiff.collapseArrayKeys(diff.path);
+		if (isModeScoped(path, rules)) return require_dev_mode_parity_fieldDiff.withExpected(diff, "mode-scoped");
+		const tag = rules.get(path);
+		if (tag && typeof tag === "object" && withinTolerance(tag.tolerance, diff)) return require_dev_mode_parity_fieldDiff.withExpected(diff, "tolerance");
+		return diff;
+	};
+}
+function isModeScoped(path, rules) {
+	for (const [rulePath, tag] of rules) {
+		if (tag !== "offchainOnly" && tag !== "onchainOnly") continue;
+		if (path === rulePath || path.startsWith(`${rulePath}.`) || path.startsWith(`${rulePath}[`)) return true;
+	}
+	return false;
+}
+function withinTolerance(kind, diff) {
+	switch (kind) {
+		case "usd": return require_dev_mode_parity_fieldDiff.isUsdWithinTolerance(diff.onchain, diff.offchain);
+		case "bps": return require_dev_mode_parity_fieldDiff.isBpsWithinTolerance(diff.onchain, diff.offchain);
+		case "amount": return require_dev_mode_parity_fieldDiff.isAmountWithinTolerance(diff.onchain, diff.offchain);
+		case "float": return require_dev_mode_parity_fieldDiff.withinRelative(require_dev_mode_parity_fieldDiff.asFiniteNumber(diff.onchain), require_dev_mode_parity_fieldDiff.asFiniteNumber(diff.offchain), require_dev_mode_parity_fieldDiff.USD_RELATIVE_EPSILON);
+	}
+}
+function walk(schema, path, seen, rules) {
+	if (seen.has(schema)) return;
+	const nextSeen = new Set(seen);
+	nextSeen.add(schema);
+	const tag = require_model_compare_schema.compareTagOf(schema);
+	if (tag) record(path, tag, schema, rules);
+	const def = schema.def;
+	switch (def.type) {
+		case "optional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "readonly":
+			if (def.innerType) walk(def.innerType, path, nextSeen, rules);
+			return;
+		case "array":
+			if (def.element) walk(def.element, `${path}[]`, nextSeen, rules);
+			return;
+		case "object":
+			if (def.shape) for (const [key, field] of Object.entries(def.shape)) walk(field, join(path, key), nextSeen, rules);
+			return;
+		case "union":
+			for (const option of def.options ?? []) walk(option, path, nextSeen, rules);
+			return;
+		case "pipe":
+			if (def.out) walk(def.out, path, nextSeen, rules);
+			return;
+		case "lazy":
+			if (def.getter) walk(def.getter(), path, nextSeen, rules);
+			return;
+		default: return;
+	}
+}
+function record(path, tag, schema, rules) {
+	if (typeof tag === "object" && tag.tolerance === "amount" && schema.def.type === "object") {
+		rules.set(join(path, "value"), tag);
+		return;
+	}
+	rules.set(path, tag);
+}
+function join(path, key) {
+	return path ? `${path}.${key}` : key;
+}
+//#endregion
+exports.compileCompareRules = compileCompareRules;
+exports.makeTagDiff = makeTagDiff;

package/dist/cjs/dev/{fieldDiff.js → mode-parity/fieldDiff.js}

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/dev/fieldDiff.ts
+//#region src/dev/mode-parity/fieldDiff.ts
 /**
 * Relative drift allowed on {@link Amount.valueUsd} before a USD float is a
 * real disagreement: 0.1%.
@@ -70,7 +70,7 @@ function withExpected(diff, reason) {
 **/
 function countPaths(diffs) {
 	const counts = /* @__PURE__ */ new Map();
-	for (const diff of diffs) {
+	for (const { id, diff } of diffs) {
 		const path = collapseArrayKeys(diff.path);
 		const entry = counts.get(path) ?? {
 			path,
@@ -83,10 +83,31 @@ function countPaths(diffs) {
 		if (diff.expected) entry.expected += 1;
 		else entry.unexpected += 1;
 		if (!entry.kinds.includes(diff.kind)) entry.kinds.push(diff.kind);
+		recordWorst(entry, id, diff);
 		counts.set(path, entry);
 	}
 	return [...counts.values()].sort((a, b) => b.unexpected - a.unexpected || b.count - a.count || a.path.localeCompare(b.path));
 }
+function recordWorst(entry, id, diff) {
+	const bps = relativeDiffBps(diff.onchain, diff.offchain);
+	if (bps === void 0) return;
+	const worst = {
+		id,
+		path: diff.path,
+		bps,
+		onchain: diff.onchain,
+		offchain: diff.offchain
+	};
+	if (diff.expected) {
+		if (isWorse(worst, entry.worstExpected)) entry.worstExpected = worst;
+		return;
+	}
+	if (isWorse(worst, entry.worstUnexpected)) entry.worstUnexpected = worst;
+}
+function isWorse(candidate, current) {
+	if (!current) return true;
+	return candidate.bps > current.bps || candidate.bps === current.bps && candidate.id.localeCompare(current.id) < 0;
+}
 /**
 * Collapse `collateralTokens[0xa0b8...].symbol` to `collateralTokens[].symbol`.
 **/
@@ -152,6 +173,31 @@ function withinRelativeBigint(onchain, offchain, epsilon) {
 function asFiniteNumber(value) {
 	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+/**
+* Relative difference of two numbers or bigints, in bps:
+* `|a − b| / max(|a|, |b|) * 10_000`. `undefined` when the values are not
+* a comparable pair of finite numbers or of bigints.
+**/
+function relativeDiffBps(onchain, offchain) {
+	if (typeof onchain === "bigint" && typeof offchain === "bigint") return relativeDiffBpsBigint(onchain, offchain);
+	const left = asFiniteNumber(onchain);
+	const right = asFiniteNumber(offchain);
+	if (left === void 0 || right === void 0) return;
+	const scale = Math.max(Math.abs(left), Math.abs(right));
+	return scale === 0 ? 0 : Math.abs(left - right) / scale * 1e4;
+}
+/**
+* Same formula as {@link relativeDiffBps} for bigints, computed in integer
+* arithmetic to milli-bps so a 1e18-scale amount does not round through
+* `Number`.
+**/
+function relativeDiffBpsBigint(onchain, offchain) {
+	if (onchain === offchain) return 0;
+	const diff = onchain > offchain ? onchain - offchain : offchain - onchain;
+	const scale = abs(onchain) > abs(offchain) ? abs(onchain) : abs(offchain);
+	if (scale === 0n) return 0;
+	return Number(diff * 10000n * 1000n / scale) / 1e3;
+}
 function union(left, right) {
 	return [.../* @__PURE__ */ new Set([...left, ...right])];
 }
@@ -234,6 +280,7 @@ exports.isAmountWithinTolerance = isAmountWithinTolerance;
 exports.isBpsWithinTolerance = isBpsWithinTolerance;
 exports.isRecord = isRecord;
 exports.isUsdWithinTolerance = isUsdWithinTolerance;
+exports.relativeDiffBps = relativeDiffBps;
 exports.toCompareCounts = toCompareCounts;
 exports.union = union;
 exports.withExpected = withExpected;

package/dist/cjs/dev/mode-parity/scriptUtils.js

@@ -0,0 +1,131 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_dev_providers = require("../providers.js");
+let pino = require("pino");
+//#region src/dev/mode-parity/scriptUtils.ts
+const NETWORKS = [
+	"Mainnet",
+	"Monad",
+	"Plasma",
+	"Somnia",
+	"Etherlink"
+];
+const BACKEND_URL = process.env.BACKEND_URL ?? "https://api.gear-dev.dev";
+const TIMEOUT = 48e4;
+function requireEnv(name) {
+	const value = process.env[name];
+	if (!value) throw new Error(`${name} is required to reach the chains this script reads`);
+	return value;
+}
+function rpcUrls() {
+	const alchemyKey = requireEnv("ALCHEMY_KEY");
+	const alchemy = (network) => {
+		const url = require_dev_providers.getAlchemyUrl(network, alchemyKey);
+		if (!url) throw new Error(`Alchemy serves no URL for ${network}`);
+		return url;
+	};
+	return {
+		Mainnet: alchemy("Mainnet"),
+		Monad: alchemy("Monad"),
+		Plasma: alchemy("Plasma"),
+		Somnia: requireEnv("SOMNIA_PROVIDER"),
+		Etherlink: requireEnv("ETHERLINK_PROVIDER")
+	};
+}
+function createLogger() {
+	return (0, pino.pino)({
+		level: process.env.LOG_LEVEL ?? "info",
+		formatters: {
+			bindings: () => ({}),
+			level: (label) => ({ level: label })
+		}
+	});
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Runs `fn` over `items` with at most `concurrency` in flight.
+**/
+async function mapPool(items, concurrency, fn) {
+	let next = 0;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (true) {
+			const index = next;
+			next += 1;
+			if (index >= items.length) return;
+			await fn(items[index]);
+		}
+	});
+	await Promise.all(workers);
+}
+/**
+* Formats a relative difference in bps as a percent, e.g. 12.5 → `"0.125%"`.
+**/
+function formatBpsAsPercent(bps) {
+	if (!Number.isFinite(bps)) return "";
+	const percent = bps / 100;
+	if (percent === 0) return "0%";
+	return `${Math.abs(percent) >= 1 ? trimTrailingZeros(percent.toFixed(3)) : trimTrailingZeros(percent.toPrecision(4))}%`;
+}
+function trimTrailingZeros(value) {
+	return value.includes(".") ? value.replace(/\.?0+$/, "") : value;
+}
+function worstColumns(worst) {
+	return {
+		"max diff": worst ? formatBpsAsPercent(worst.bps) : "",
+		"worst entity": worst?.id ?? ""
+	};
+}
+/**
+* Prints the shared membership table, the fields that differed most often,
+* and any chain that failed to answer.
+**/
+function printCompareSummary(noun, report, extraLines = []) {
+	const { summary } = report;
+	console.log(`\n${noun} from ${report.backendUrl} vs the chain`);
+	console.table(summary.byChain.map((chain) => ({
+		chain: chain.chainId,
+		onchain: chain.onchainRows,
+		offchain: chain.offchainRows,
+		matched: chain.matched,
+		identical: chain.identical,
+		clean: chain.clean,
+		differing: chain.differing,
+		"only onchain": chain.onlyOnchain,
+		"only offchain": chain.onlyOffchain
+	})));
+	for (const line of extraLines) console.log(line);
+	const unexpected = summary.diffsByPath.filter((entry) => entry.unexpected > 0);
+	const expected = summary.diffsByPath.filter((entry) => entry.unexpected === 0 && entry.expected > 0);
+	if (unexpected.length) {
+		console.log("\nunexpected fields that differed most often:");
+		console.table(unexpected.slice(0, 25).map((entry) => ({
+			field: entry.path,
+			unexpected: entry.unexpected,
+			expected: entry.expected,
+			kinds: entry.kinds.join(", "),
+			...worstColumns(entry.worstUnexpected)
+		})));
+	}
+	if (expected.length) {
+		console.log("\nexpected fields (mode-scoped or within tolerance):");
+		console.table(expected.slice(0, 25).map((entry) => ({
+			field: entry.path,
+			rows: entry.expected,
+			kinds: entry.kinds.join(", "),
+			...worstColumns(entry.worstExpected)
+		})));
+	}
+	for (const chain of [...report.onchainChains, ...report.offchainChains]) if (chain.status === "error") console.log(`chain ${chain.chainId} failed on ${chain.source}:`, chain.error);
+}
+//#endregion
+exports.BACKEND_URL = BACKEND_URL;
+exports.NETWORKS = NETWORKS;
+exports.TIMEOUT = TIMEOUT;
+exports.createLogger = createLogger;
+exports.errorMessage = errorMessage;
+exports.formatBpsAsPercent = formatBpsAsPercent;
+exports.mapPool = mapPool;
+exports.printCompareSummary = printCompareSummary;
+exports.requireEnv = requireEnv;
+exports.rpcUrls = rpcUrls;

package/dist/cjs/model/compare.schema.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/model/compare.schema.ts
+/**
+* Marks a field that only the backend fills.
+**/
+function offchainOnly(schema) {
+	return schema.meta({ compare: "offchainOnly" });
+}
+/**
+* Marks a field that only the chain fills.
+**/
+function onchainOnly(schema) {
+	return schema.meta({ compare: "onchainOnly" });
+}
+/**
+* Marks a numeric field whose two sources may drift within {@link kind}.
+**/
+function tolerance(schema, kind) {
+	return schema.meta({ compare: { tolerance: kind } });
+}
+/**
+* The compare tag registered on a schema, if any.
+**/
+function compareTagOf(schema) {
+	const meta = schema.meta();
+	if (!meta || !("compare" in meta)) return;
+	return meta.compare;
+}
+//#endregion
+exports.compareTagOf = compareTagOf;
+exports.offchainOnly = offchainOnly;
+exports.onchainOnly = onchainOnly;
+exports.tolerance = tolerance;

package/dist/cjs/model/curators.schema.js

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_sdk_utils_zod = require("../sdk/utils/zod.js");
+const require_model_compare_schema = require("./compare.schema.js");
 let zod_v4 = require("zod/v4");
 //#region src/model/curators.schema.ts
 /**
@@ -31,7 +32,7 @@ const curatorNameSchema = zod_v4.z.enum([
 const curatorSchema = zod_v4.z.object({
 	address: require_sdk_utils_zod.ZodAddress(),
 	name: curatorNameSchema.optional(),
-	url: zod_v4.z.string().nullable()
+	url: require_model_compare_schema.offchainOnly(zod_v4.z.string().nullable())
 });
 //#endregion
 exports.curatorNameSchema = curatorNameSchema;

package/dist/cjs/model/index.js

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_model_charts = require("./charts.js");
+const require_model_compare_schema = require("./compare.schema.js");
 const require_model_primitives_schema = require("./primitives.schema.js");
 const require_model_charts_schema = require("./charts.schema.js");
 require("./curators.js");
@@ -45,6 +46,7 @@ exports.chartRangeSchema = require_model_charts_schema.chartRangeSchema;
 exports.chartSeriesSchema = require_model_charts_schema.chartSeriesSchema;
 exports.chartValueSchema = require_model_charts_schema.chartValueSchema;
 exports.chartWindowSchema = require_model_charts_schema.chartWindowSchema;
+exports.compareTagOf = require_model_compare_schema.compareTagOf;
 exports.curatorNameSchema = require_model_curators_schema.curatorNameSchema;
 exports.curatorSchema = require_model_curators_schema.curatorSchema;
 exports.dataSourceSchema = require_model_response_schema.dataSourceSchema;
@@ -66,6 +68,8 @@ exports.matchesOpportunityFilter = require_model_opportunities.matchesOpportunit
 exports.matchesPositionFilter = require_model_positions.matchesPositionFilter;
 exports.noticeKindSchema = require_model_notices_schema.noticeKindSchema;
 exports.noticeSchema = require_model_notices_schema.noticeSchema;
+exports.offchainOnly = require_model_compare_schema.offchainOnly;
+exports.onchainOnly = require_model_compare_schema.onchainOnly;
 exports.opportunityBaseSchema = require_model_opportunities_schema.opportunityBaseSchema;
 exports.opportunityDetailSchema = require_model_opportunities_schema.opportunityDetailSchema;
 exports.opportunityFilterQueryParamsSchema = require_model_opportunities_schema.opportunityFilterQueryParamsSchema;
@@ -124,4 +128,5 @@ exports.tokenAmountSchema = require_model_primitives_schema.tokenAmountSchema;
 exports.tokenRewardsPnLSchema = require_model_positions_schema.tokenRewardsPnLSchema;
 exports.tokenRewardsSchema = require_model_opportunities_schema.tokenRewardsSchema;
 exports.tokenSchema = require_model_primitives_schema.tokenSchema;
+exports.tolerance = require_model_compare_schema.tolerance;
 exports.txCallSchema = require_model_primitives_schema.txCallSchema;

package/dist/cjs/model/opportunities.schema.js

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_sdk_utils_zod = require("../sdk/utils/zod.js");
+const require_model_compare_schema = require("./compare.schema.js");
 const require_model_primitives_schema = require("./primitives.schema.js");
 const require_model_curators_schema = require("./curators.schema.js");
 const require_model_filters = require("./filters.js");
@@ -46,9 +47,9 @@ const rewardsSchema = zod_v4.z.discriminatedUnion("kind", [tokenRewardsSchema, p
 * {@link ApyBreakdown}
 **/
 const apyBreakdownSchema = zod_v4.z.object({
-	totalApy: require_model_primitives_schema.bpsSchema.optional(),
-	organicApy: require_model_primitives_schema.bpsSchema,
-	rewards: zod_v4.z.array(rewardsSchema).optional()
+	totalApy: require_model_compare_schema.offchainOnly(require_model_primitives_schema.bpsSchema).optional(),
+	organicApy: require_model_compare_schema.tolerance(require_model_primitives_schema.bpsSchema, "bps"),
+	rewards: require_model_compare_schema.offchainOnly(zod_v4.z.array(rewardsSchema)).optional()
 });
 /**
 * {@link OpportunityBase}
@@ -71,9 +72,9 @@ const poolOpportunitySchema = zod_v4.z.object({
 	...opportunityBaseSchema.shape,
 	kind: zod_v4.z.literal("pool"),
 	pool: require_sdk_utils_zod.ZodAddress(),
-	totalSupply: require_model_primitives_schema.amountSchema,
-	availableLiquidity: require_model_primitives_schema.amountSchema,
-	utilization: require_model_primitives_schema.bpsSchema,
+	totalSupply: require_model_compare_schema.tolerance(require_model_primitives_schema.amountSchema, "amount"),
+	availableLiquidity: require_model_compare_schema.tolerance(require_model_primitives_schema.amountSchema, "amount"),
+	utilization: require_model_compare_schema.tolerance(require_model_primitives_schema.bpsSchema, "bps"),
 	supplyApy: apyBreakdownSchema
 });
 /**
@@ -88,12 +89,12 @@ const strategyOpportunitySchema = zod_v4.z.object({
 	liquidationPremium: require_model_primitives_schema.bpsSchema,
 	liquidationFee: require_model_primitives_schema.bpsSchema,
 	expirationDate: require_model_primitives_schema.timestampSchema.nullable(),
-	collateralApy: apyBreakdownSchema.optional(),
-	maxLeverageApy: apyBreakdownSchema.optional(),
-	borrowApy: require_model_primitives_schema.bpsSchema.optional(),
-	additionalBorrowApy: require_model_primitives_schema.bpsSchema.optional(),
-	totalValue: require_model_primitives_schema.amountSchema.optional(),
-	utilization: require_model_primitives_schema.bpsSchema.optional(),
+	collateralApy: require_model_compare_schema.offchainOnly(apyBreakdownSchema).optional(),
+	maxLeverageApy: require_model_compare_schema.offchainOnly(apyBreakdownSchema).optional(),
+	borrowApy: require_model_compare_schema.tolerance(require_model_primitives_schema.bpsSchema, "bps").optional(),
+	additionalBorrowApy: require_model_compare_schema.tolerance(require_model_primitives_schema.bpsSchema, "bps").optional(),
+	totalValue: require_model_compare_schema.offchainOnly(require_model_primitives_schema.amountSchema).optional(),
+	utilization: require_model_compare_schema.offchainOnly(require_model_primitives_schema.bpsSchema).optional(),
 	maxBorrowAmount: require_model_primitives_schema.amountSchema,
 	maxLeverage: require_model_primitives_schema.leverageSchema
 });