@gearbox-protocol/sdk 16.0.0-next.53 → 16.0.0-next.55

package/dist/esm/model/index.js

@@ -1,21 +1,23 @@
-import { CHART_METRIC_UNITS, CHART_RANGES, CHART_UNAVAILABLE_CODES, POOL_OPPORTUNITY_CHART_METRICS, POOL_POSITION_CHART_METRICS, STRATEGY_OPPORTUNITY_CHART_METRICS, STRATEGY_POSITION_CHART_METRICS } from "./charts.js";
+import "./analytics.js";
+import { FILTER_ALL, isFilterSet } from "./filters.js";
+import { booleanParamSchema, encodeFlag, filterAllSchema, filterable } from "./filters.schema.js";
 import { backendPreferred, compareTagOf, offchainOnly, onchainOnly, tolerance } from "./compare.schema.js";
+import { curatorNameSchema, curatorSchema } from "./curators.schema.js";
 import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema, underlyingTokenSchema } from "./primitives.schema.js";
+import { delayedReceivedAssetSchema, instantReceivedAssetSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, receivedAssetSchema } from "./liquidations.schema.js";
+import { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, opportunityTotalsSchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
+import { borrowRateBreakdownSchema, pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionsTotalsSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenQuotaRateSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
+import { ANALYTICS_POSITIONS_DEFAULT_LIMIT, ANALYTICS_POSITIONS_MAX_LIMIT, analyticsPositionListOptionsSchema, analyticsPositionListQueryParamsSchema, analyticsPositionListQuerySchema, analyticsPositionPageSchema, analyticsPositionSchema, analyticsPositionSortFieldSchema, analyticsSortDirectionSchema } from "./analytics.schema.js";
+import { CHART_METRIC_UNITS, CHART_RANGES, CHART_UNAVAILABLE_CODES, POOL_OPPORTUNITY_CHART_METRICS, POOL_POSITION_CHART_METRICS, STRATEGY_OPPORTUNITY_CHART_METRICS, STRATEGY_POSITION_CHART_METRICS } from "./charts.js";
 import { chartBundleSchemaFor, chartDenominationSchema, chartMetricSchema, chartQueryCodec, chartQueryParamsSchema, chartQuerySchema, chartRangeSchema, chartSeriesSchema, chartValueSchema, chartWindowSchema, poolOpportunityChartMetricSchema, poolPositionChartMetricSchema, strategyOpportunityChartMetricSchema, strategyPositionChartMetricSchema } from "./charts.schema.js";
 import "./curators.js";
-import { curatorNameSchema, curatorSchema } from "./curators.schema.js";
 import "./delayed-intents.js";
 import "./errors.js";
-import { FILTER_ALL, isFilterSet } from "./filters.js";
-import { booleanParamSchema, encodeFlag, filterAllSchema, filterable } from "./filters.schema.js";
 import { matchesLiquidatableAccountFilter } from "./liquidations.js";
-import { delayedReceivedAssetSchema, instantReceivedAssetSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, receivedAssetSchema } from "./liquidations.schema.js";
 import "./notices.js";
 import { noticeKindSchema, noticeSchema } from "./notices.schema.js";
 import { matchesOpportunityFilter, opportunityId, poolOpportunityId, strategyOpportunityId } from "./opportunities.js";
-import { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, opportunityTotalsSchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
 import { STRATEGY_POSITION_COLLATERAL_ERROR, liquidationPositionId, matchesPositionFilter, poolPositionId, positionId, strategyPositionId } from "./positions.js";
-import { borrowRateBreakdownSchema, pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionsTotalsSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenQuotaRateSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
 import { asEstimated } from "./previews.js";
 import "./primitives.js";
 import "./response.js";
@@ -23,4 +25,4 @@ import { chainFailedSchema, chainMetadataSchema, chainSucceededSchema, dataSourc
 import { isSDKError, safeValue, sdkErr, sdkOk } from "./result.js";
 import "./withdrawals.js";
 import { positionClaimableWithdrawalSchema, positionPendingWithdrawalSchema, positionWithdrawalsSchema, withdrawalOutputAmountSchema } from "./withdrawals.schema.js";
-export { CHART_METRIC_UNITS, CHART_RANGES, CHART_UNAVAILABLE_CODES, FILTER_ALL, POOL_OPPORTUNITY_CHART_METRICS, POOL_POSITION_CHART_METRICS, STRATEGY_OPPORTUNITY_CHART_METRICS, STRATEGY_POSITION_CHART_METRICS, STRATEGY_POSITION_COLLATERAL_ERROR, amountSchema, apyBreakdownSchema, asEstimated, assetTypeSchema, backendPreferred, booleanParamSchema, borrowRateBreakdownSchema, bpsSchema, chainFailedSchema, chainIdSchema, chainMetadataSchema, chainSucceededSchema, chartBundleSchemaFor, chartDenominationSchema, chartMetricSchema, chartQueryCodec, chartQueryParamsSchema, chartQuerySchema, chartRangeSchema, chartSeriesSchema, chartValueSchema, chartWindowSchema, compareTagOf, curatorNameSchema, curatorSchema, dataSourceSchema, delayedReceivedAssetSchema, encodeFlag, filterAllSchema, filterable, instantReceivedAssetSchema, isFilterSet, isSDKError, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, noticeKindSchema, noticeSchema, offchainOnly, onchainOnly, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, opportunityTotalsSchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolOpportunityChartMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionChartMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionClaimableWithdrawalSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionId, positionKeySchema, positionKindSchema, positionPendingWithdrawalSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionWithdrawalsSchema, positionsTotalsSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, responseMetadataSchema, responseSchema, rewardsPnLSchema, rewardsSchema, safeValue, sdkErr, sdkOk, strategyOpportunityChartMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionChartMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenQuotaRateSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, tolerance, txCallSchema, underlyingTokenSchema, withdrawalOutputAmountSchema };
+export { ANALYTICS_POSITIONS_DEFAULT_LIMIT, ANALYTICS_POSITIONS_MAX_LIMIT, CHART_METRIC_UNITS, CHART_RANGES, CHART_UNAVAILABLE_CODES, FILTER_ALL, POOL_OPPORTUNITY_CHART_METRICS, POOL_POSITION_CHART_METRICS, STRATEGY_OPPORTUNITY_CHART_METRICS, STRATEGY_POSITION_CHART_METRICS, STRATEGY_POSITION_COLLATERAL_ERROR, amountSchema, analyticsPositionListOptionsSchema, analyticsPositionListQueryParamsSchema, analyticsPositionListQuerySchema, analyticsPositionPageSchema, analyticsPositionSchema, analyticsPositionSortFieldSchema, analyticsSortDirectionSchema, apyBreakdownSchema, asEstimated, assetTypeSchema, backendPreferred, booleanParamSchema, borrowRateBreakdownSchema, bpsSchema, chainFailedSchema, chainIdSchema, chainMetadataSchema, chainSucceededSchema, chartBundleSchemaFor, chartDenominationSchema, chartMetricSchema, chartQueryCodec, chartQueryParamsSchema, chartQuerySchema, chartRangeSchema, chartSeriesSchema, chartValueSchema, chartWindowSchema, compareTagOf, curatorNameSchema, curatorSchema, dataSourceSchema, delayedReceivedAssetSchema, encodeFlag, filterAllSchema, filterable, instantReceivedAssetSchema, isFilterSet, isSDKError, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, noticeKindSchema, noticeSchema, offchainOnly, onchainOnly, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, opportunityTotalsSchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolOpportunityChartMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionChartMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionClaimableWithdrawalSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionId, positionKeySchema, positionKindSchema, positionPendingWithdrawalSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionWithdrawalsSchema, positionsTotalsSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, responseMetadataSchema, responseSchema, rewardsPnLSchema, rewardsSchema, safeValue, sdkErr, sdkOk, strategyOpportunityChartMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionChartMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenQuotaRateSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, tolerance, txCallSchema, underlyingTokenSchema, withdrawalOutputAmountSchema };

package/dist/esm/model/liquidations.schema.js

@@ -1,7 +1,7 @@
 import { ZodAddress } from "../onchain/utils/zod.js";
-import { assetTypeSchema, bpsSchema, chainIdSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema, underlyingTokenSchema } from "./primitives.schema.js";
-import { curatorSchema } from "./curators.schema.js";
 import { filterable } from "./filters.schema.js";
+import { curatorSchema } from "./curators.schema.js";
+import { assetTypeSchema, bpsSchema, chainIdSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema, underlyingTokenSchema } from "./primitives.schema.js";
 import { z } from "zod/v4";
 //#region src/model/liquidations.schema.ts
 /**

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

@@ -1,9 +1,9 @@
 import { ZodAddress } from "../onchain/utils/zod.js";
-import { offchainOnly, tolerance } from "./compare.schema.js";
-import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenSchema, underlyingTokenSchema } from "./primitives.schema.js";
-import { curatorSchema } from "./curators.schema.js";
 import { isFilterSet } from "./filters.js";
 import { booleanParamSchema, encodeFlag, filterable } from "./filters.schema.js";
+import { offchainOnly, tolerance } from "./compare.schema.js";
+import { curatorSchema } from "./curators.schema.js";
+import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenSchema, underlyingTokenSchema } from "./primitives.schema.js";
 import { z } from "zod/v4";
 //#region src/model/opportunities.schema.ts
 /**

package/dist/esm/model/positions.schema.js

@@ -1,8 +1,8 @@
 import { ZodAddress, ZodBigInt, ZodHex } from "../onchain/utils/zod.js";
-import { backendPreferred, offchainOnly, onchainOnly, tolerance } from "./compare.schema.js";
-import { assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, underlyingTokenSchema } from "./primitives.schema.js";
 import { isFilterSet } from "./filters.js";
 import { booleanParamSchema, encodeFlag, filterable } from "./filters.schema.js";
+import { backendPreferred, offchainOnly, onchainOnly, tolerance } from "./compare.schema.js";
+import { assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, underlyingTokenSchema } from "./primitives.schema.js";
 import { delayedReceivedAssetSchema, liquidationPositionSchema } from "./liquidations.schema.js";
 import { apyBreakdownSchema, pointsProgramSchema } from "./opportunities.schema.js";
 import { z } from "zod/v4";

package/dist/esm/offchain/GearboxAPI.js

@@ -1,3 +1,5 @@
+import { OffchainAnalytics } from "./analytics/OffchainAnalytics.js";
+import "./analytics/index.js";
 import { OffchainNotices } from "./notices/OffchainNotices.js";
 import "./notices/index.js";
 import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
@@ -27,6 +29,8 @@ var GearboxAPI = class {
 	* Chains every read of this client is scoped to.
 	**/
 	chainIds;
+	/** Protocol-wide, backend-only analytics. */
+	analytics;
 	/**
 	* Namespace for pool and strategy opportunities.
 	**/
@@ -41,6 +45,7 @@ var GearboxAPI = class {
 	notices;
 	constructor(options) {
 		this.chainIds = [...options.chainIds];
+		this.analytics = new OffchainAnalytics(options);
 		this.opportunities = new OffchainOpportunities(options);
 		this.positions = new OffchainPositions(options);
 		this.notices = new OffchainNotices(options);

package/dist/esm/offchain/analytics/OffchainAnalytics.js

@@ -0,0 +1,11 @@
+import { OffchainAnalyticsPositions } from "./OffchainAnalyticsPositions.js";
+//#region src/offchain/analytics/OffchainAnalytics.ts
+/** Backend-only protocol analytics, grouped by subject. */
+var OffchainAnalytics = class {
+	positions;
+	constructor(options) {
+		this.positions = new OffchainAnalyticsPositions(options);
+	}
+};
+//#endregion
+export { OffchainAnalytics };

package/dist/esm/offchain/analytics/OffchainAnalyticsPositions.js

@@ -0,0 +1,23 @@
+import { analyticsPositionListQuerySchema, analyticsPositionPageSchema } from "../../model/analytics.schema.js";
+import { AbstractOffchainNamespace } from "../AbstractOffchainNamespace.js";
+import { z } from "zod/v4";
+//#region src/offchain/analytics/OffchainAnalyticsPositions.ts
+/** Backend client for protocol-wide position analytics. */
+var OffchainAnalyticsPositions = class extends AbstractOffchainNamespace {
+	constructor(options) {
+		super("OffchainAnalyticsPositions", options);
+	}
+	/** {@inheritDoc IOffchainAnalyticsPositions.list} */
+	async list(options) {
+		return this.get({
+			path: "/v2/analytics/positions",
+			query: z.encode(analyticsPositionListQuerySchema, {
+				...options,
+				chainIds: this.scopedChainIds(options)
+			}),
+			schema: analyticsPositionPageSchema
+		});
+	}
+};
+//#endregion
+export { OffchainAnalyticsPositions };

package/dist/esm/offchain/analytics/index.js

@@ -0,0 +1,4 @@
+import { OffchainAnalyticsPositions } from "./OffchainAnalyticsPositions.js";
+import { OffchainAnalytics } from "./OffchainAnalytics.js";
+import "./types.js";
+export { OffchainAnalytics, OffchainAnalyticsPositions };

package/dist/esm/offchain/index.js

@@ -10,6 +10,9 @@ import { OffchainValidationError } from "./errors/OffchainValidationError.js";
 import { readResponseBody } from "./errors/readResponseBody.js";
 import "./errors/index.js";
 import { AbstractOffchainNamespace } from "./AbstractOffchainNamespace.js";
+import { OffchainAnalyticsPositions } from "./analytics/OffchainAnalyticsPositions.js";
+import { OffchainAnalytics } from "./analytics/OffchainAnalytics.js";
+import "./analytics/index.js";
 import { OffchainNotices } from "./notices/OffchainNotices.js";
 import "./notices/index.js";
 import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
@@ -18,4 +21,4 @@ import { OffchainPositions } from "./positions/OffchainPositions.js";
 import "./positions/index.js";
 import { GearboxAPI } from "./GearboxAPI.js";
 import "./types.js";
-export { AbstractOffchainNamespace, GearboxAPI, OffchainInvalidJsonError, OffchainNotConfiguredError, OffchainNotImplementedError, OffchainNotices, OffchainOpportunities, OffchainPositions, OffchainRequestFailedError, OffchainStatusError, OffchainTransportError, OffchainValidationError, backendMessage, errorCause, readResponseBody };
+export { AbstractOffchainNamespace, GearboxAPI, OffchainAnalytics, OffchainAnalyticsPositions, OffchainInvalidJsonError, OffchainNotConfiguredError, OffchainNotImplementedError, OffchainNotices, OffchainOpportunities, OffchainPositions, OffchainRequestFailedError, OffchainStatusError, OffchainTransportError, OffchainValidationError, backendMessage, errorCause, readResponseBody };

package/dist/esm/rewards/errors.js

@@ -0,0 +1,26 @@
+import { BaseError } from "viem";
+//#region src/rewards/errors.ts
+/**
+* Thrown when none of Merkl's domains answered for a chain.
+*
+* Everything a reader needs is in the message: this error travels to consumers
+* inside a chain's {@link ChainFailed} metadata, where it is typed `unknown`
+* and may be serialised by something that turns an arbitrary object into `{}`.
+*/
+var MerklRequestFailedError = class extends BaseError {
+	name = "MerklRequestFailedError";
+	chainId;
+	constructor(chainId, path, attempts) {
+		super(`Merkl could not be reached for chain ${chainId}.`, {
+			cause: attempts.find(([, c]) => c instanceof Error)?.[1],
+			metaMessages: attempts.map(([domain, cause]) => `${domain}${path} — ${describe(cause)}`)
+		});
+		this.chainId = chainId;
+	}
+};
+function describe(cause) {
+	if (cause instanceof Error) return cause.name === "TimeoutError" ? "timed out" : cause.message;
+	return String(cause);
+}
+//#endregion
+export { MerklRequestFailedError };

package/dist/esm/rewards/index.js

@@ -1,5 +1,4 @@
-import "./apy/index.js";
-import { getMerklRewards } from "./rewards/api.js";
-import { PoolPointsAPI, getKeyForPoolPointsInfo } from "./rewards/extra-apy.js";
-import "./rewards/index.js";
-export { PoolPointsAPI, getKeyForPoolPointsInfo, getMerklRewards };
+import { MerklRequestFailedError } from "./errors.js";
+import { toMerklRewards } from "./toMerklRewards.js";
+import { getMerklRewardsMultichain } from "./multichain.js";
+export { MerklRequestFailedError, getMerklRewardsMultichain, toMerklRewards };

package/dist/esm/rewards/merkl-api.js

@@ -0,0 +1,42 @@
+import { MerklRequestFailedError } from "./errors.js";
+//#region src/rewards/merkl-api.ts
+/**
+* Merkl's own host and the Angle mirror, tried in this order.
+*/
+const MERKL_DOMAINS = ["https://api.merkl.xyz", "https://api-merkl.angle.money"];
+const MERKL_API_KEY_HEADER = "X-API-Key";
+/**
+* Per-attempt budget. Merkl has no timeout of its own, and a hung connection
+* would otherwise stall its leg of a fan-out for as long as the socket lives.
+*/
+const ATTEMPT_TIMEOUT = 1e4;
+/**
+* The wallet's raw Merkl rewards on one chain.
+*
+* Rejects with {@link MerklRequestFailedError} when neither domain answers, so
+* a caller can tell an unreachable Merkl from a wallet with nothing to claim.
+* A non-2xx counts as no answer and moves to the next domain: it carries no
+* rewards either way, and treating it as success would report emptiness that
+* was never established.
+*/
+async function fetchMerklUserRewards({ chainId, user, apiKey }) {
+	const path = `/v4/users/${user}/rewards?chainId=${chainId}`;
+	const headers = apiKey ? { [MERKL_API_KEY_HEADER]: apiKey } : void 0;
+	const attempts = [];
+	for (const domain of MERKL_DOMAINS) try {
+		const response = await fetch(`${domain}${path}`, {
+			headers,
+			signal: AbortSignal.timeout(ATTEMPT_TIMEOUT)
+		});
+		if (!response.ok) {
+			attempts.push([domain, /* @__PURE__ */ new Error(`answered ${response.status}`)]);
+			continue;
+		}
+		return await response.json();
+	} catch (error) {
+		attempts.push([domain, error]);
+	}
+	throw new MerklRequestFailedError(chainId, path, attempts);
+}
+//#endregion
+export { MERKL_API_KEY_HEADER, MERKL_DOMAINS, fetchMerklUserRewards };

package/dist/esm/rewards/multichain.js

@@ -0,0 +1,39 @@
+import { MultichainConstruct } from "../onchain/base/MultichainConstruct.js";
+import "../onchain/index.js";
+import { fetchMerklUserRewards } from "./merkl-api.js";
+import { toMerklRewards } from "./toMerklRewards.js";
+import { getAddress } from "viem";
+//#region src/rewards/multichain.ts
+/**
+* The fan-out itself. Private because rewards are not an SDK namespace yet:
+* the read is a free function, and this is only how it reaches `queryChains`.
+**/
+var MerklRewardsFanOut = class extends MultichainConstruct {
+	async list(wallet, chainIds, apiKey) {
+		const user = getAddress(wallet);
+		return this.queryChains({
+			chainIds,
+			label: "list rewards",
+			block: "state",
+			run: async (sdk) => toMerklRewards(sdk, await fetchMerklUserRewards({
+				chainId: sdk.chainId,
+				user,
+				apiKey
+			}))
+		});
+	}
+};
+/**
+* Every claimable Merkl reward a wallet holds, across the chains the handle
+* carries.
+*
+* Answers the read model's own envelope, so a chain that could not be reached
+* is `status: "error"` in `meta.chains` while a chain with nothing to claim is
+* a `"success"` that contributed no rows. That distinction is the point: the
+* single-chain read this replaces resolved empty either way.
+**/
+async function getMerklRewardsMultichain({ sdk, wallet, chainIds, apiKey }) {
+	return new MerklRewardsFanOut(sdk).list(wallet, chainIds, apiKey);
+}
+//#endregion
+export { getMerklRewardsMultichain };

package/dist/esm/rewards/{rewards/api.js → toMerklRewards.js}

@@ -1,27 +1,16 @@
-import { AddressMap } from "../../onchain/utils/AddressMap.js";
-import { BigIntMath } from "../../onchain/utils/bigint-math.js";
-import { toBigInt } from "../../onchain/utils/formatter.js";
-import "../../onchain/index.js";
-import { MerkleXYZApi } from "./merkl-api.js";
+import { AddressMap } from "../onchain/utils/AddressMap.js";
+import { BigIntMath } from "../onchain/utils/bigint-math.js";
+import { toBigInt } from "../onchain/utils/formatter.js";
+import "../onchain/index.js";
 import { formatUnits, getAddress, isAddress } from "viem";
-//#region src/rewards/rewards/api.ts
+//#region src/rewards/toMerklRewards.ts
 /**
-* The wallet's claimable Merkl rewards on one chain.
-*
-* Never rejects on a transport failure: the fetch is settled rather than
-* awaited, and a failure goes to `reportError` and yields an empty list. A
-* caller that must tell "this chain is down" from "this chain has no rewards"
-* has to watch that callback.
+* Merkl's answer for one chain, turned into rows of the read model.
 */
-async function getMerklRewards({ sdk, account, reportError, apiKey }) {
-	const [merkleXYZLMResponse] = await Promise.allSettled([MerkleXYZApi.fetchWithFallback(MerkleXYZApi.getUserRewardsUrl({ params: {
-		chainId: sdk.chainId,
-		user: getAddress(account)
-	} }), apiKey)]);
-	const merkleXYZLm = extractFulfilled(merkleXYZLMResponse, reportError, "merkleXYZLm")?.data;
+function toMerklRewards(sdk, response) {
 	const poolByItsToken = AddressMap.fromMappedArray(sdk.marketRegister.pools.map(({ pool }) => pool.address), (address) => address);
 	const claimable = /* @__PURE__ */ new Map();
-	for (const chainRewards of merkleXYZLm || []) for (const reward of chainRewards.rewards) {
+	for (const chainRewards of response) for (const reward of chainRewards.rewards) {
 		if (!isAddress(reward.token.address, { strict: false })) continue;
 		const rewardTokenAddress = getAddress(reward.token.address);
 		for (const reason of reward.breakdowns) {
@@ -29,9 +18,9 @@ async function getMerklRewards({ sdk, account, reportError, apiKey }) {
 			if (!isAddress(poolTokenAddress, { strict: false })) continue;
 			const pool = poolByItsToken.get(poolTokenAddress);
 			if (!pool) continue;
-			const total = toBigInt(reason.amount || 0);
-			const claimed = toBigInt(reason.claimed || 0);
-			const amount = BigIntMath.max(total - claimed, 0n);
+			const amounts = toAmounts(reason);
+			if (!amounts) continue;
+			const amount = BigIntMath.max(amounts.total - amounts.claimed, 0n);
 			if (amount === 0n) continue;
 			const key = `${pool}_${rewardTokenAddress}`;
 			const seen = claimable.get(key);
@@ -53,6 +42,20 @@ async function getMerklRewards({ sdk, account, reportError, apiKey }) {
 	}
 	return [...claimable.values()].map(toReward);
 }
+/**
+* `toBigInt` throws on anything `BigInt()` cannot parse, and Merkl's amounts
+* are free-form strings.
+*/
+function toAmounts(reason) {
+	try {
+		return {
+			total: toBigInt(reason.amount || 0),
+			claimed: toBigInt(reason.claimed || 0)
+		};
+	} catch {
+		return;
+	}
+}
 function toReward({ price, token, value, ...rest }) {
 	return {
 		...rest,
@@ -77,10 +80,5 @@ function toRewardToken(sdk, address, merkl) {
 		decimals: merkl.decimals || 18
 	};
 }
-function extractFulfilled(r, reportError, description) {
-	if (r.status === "fulfilled") return r.value;
-	if (reportError) reportError(r.reason, description);
-	else console.error(r.reason);
-}
 //#endregion
-export { getMerklRewards };
+export { toMerklRewards };

package/dist/esm/sdk/GearboxSDK.js

@@ -6,6 +6,8 @@ import "../offchain/index.js";
 import { assertSameChains } from "./errors/assertSameChains.js";
 import { MissingSourceError } from "./errors/MissingSourceError.js";
 import "./errors/index.js";
+import { AnalyticsNamespace } from "./analytics/AnalyticsNamespace.js";
+import "./analytics/index.js";
 import { LiquidationsNamespace } from "./liquidations/LiquidationsNamespace.js";
 import "./liquidations/index.js";
 import "./utils/mergeChains.js";
@@ -50,6 +52,8 @@ var GearboxSDK = class {
 	* Chains this instance covers, which every read is scoped to.
 	**/
 	networks;
+	/** Protocol-wide analytics. Undefined in `onchain` mode. */
+	analytics;
 	/**
 	* Namespace for pool and strategy opportunities.
 	**/
@@ -130,6 +134,7 @@ var GearboxSDK = class {
 			ensureFresh: this.#onchain ? (chainIds) => this.#ensureFresh(chainIds) : void 0,
 			logger
 		};
+		this.analytics = this.#offchain ? new AnalyticsNamespace(this.#offchain) : void 0;
 		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, namespaceOptions);
 		this.positions = new PositionsNamespace(this.#onchain, this.#offchain, namespaceOptions);
 		this.liquidations = this.#onchain ? new LiquidationsNamespace(this.#onchain, namespaceOptions) : void 0;

package/dist/esm/sdk/analytics/AnalyticsNamespace.js

@@ -0,0 +1,10 @@
+//#region src/sdk/analytics/AnalyticsNamespace.ts
+/** Backend-only protocol analytics exposed by {@link GearboxSDK}. */
+var AnalyticsNamespace = class {
+	positions;
+	constructor(backend) {
+		this.positions = backend.analytics.positions;
+	}
+};
+//#endregion
+export { AnalyticsNamespace };

package/dist/esm/sdk/analytics/index.js

@@ -0,0 +1,3 @@
+import { AnalyticsNamespace } from "./AnalyticsNamespace.js";
+import "./types.js";
+export { AnalyticsNamespace };

package/dist/esm/sdk/index.js

@@ -8,6 +8,8 @@ import { NoSourceServedError } from "./errors/NoSourceServedError.js";
 import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
 import "./errors/index.js";
 import { AbstractNamespace } from "./AbstractNamespace.js";
+import { AnalyticsNamespace } from "./analytics/AnalyticsNamespace.js";
+import "./analytics/index.js";
 import { LiquidationsNamespace } from "./liquidations/LiquidationsNamespace.js";
 import "./liquidations/index.js";
 import { ExecuteApi } from "./execute/ExecuteApi.js";
@@ -26,4 +28,4 @@ import { PreviewNamespace } from "./preview/PreviewNamespace.js";
 import "./preview/index.js";
 import { DEFAULT_MAX_STATE_AGE, GearboxSDK } from "./GearboxSDK.js";
 import "./types.js";
-export { AbstractNamespace, AllSourcesFailedError, DEFAULT_MAX_OFFCHAIN_LAG, DEFAULT_MAX_STATE_AGE, ExecuteApi, GearboxSDK, IntentPreviewError, LiquidationsNamespace, MissingSourceError, NoSourceServedError, OpportunitiesNamespace, PositionsNamespace, PrepareApi, PreviewNamespace, SourceChainMismatchError, SourceUnavailableError, assertSameChains, creditAccountNotFound, everyChainFailed, filterResponse, mergeChainList, mergeChainOne, noStrategyTargetCollateral, raise, refuse, toRefusalError, unexpectedFailure };
+export { AbstractNamespace, AllSourcesFailedError, AnalyticsNamespace, DEFAULT_MAX_OFFCHAIN_LAG, DEFAULT_MAX_STATE_AGE, ExecuteApi, GearboxSDK, IntentPreviewError, LiquidationsNamespace, MissingSourceError, NoSourceServedError, OpportunitiesNamespace, PositionsNamespace, PrepareApi, PreviewNamespace, SourceChainMismatchError, SourceUnavailableError, assertSameChains, creditAccountNotFound, everyChainFailed, filterResponse, mergeChainList, mergeChainOne, noStrategyTargetCollateral, raise, refuse, toRefusalError, unexpectedFailure };

package/dist/types/dev/mode-parity/compareOpportunities.d.ts

@@ -36,14 +36,10 @@ interface OpportunityMatch {
    **/
   onchainName: string;
   offchainName: string;
-  /**
-   * No diffs at all, including the documented offchain-only ones.
-   **/
-  identical: boolean;
   /**
    * No unexpected diffs: every disagreement is mode-scoped or within tolerance.
    **/
-  clean: boolean;
+  similar: boolean;
   diffs: FieldDiff[];
 }
 /**
@@ -93,8 +89,8 @@ interface CompareOpportunitiesInput {
  *
  * 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.
+ * {@link FieldDiff.expected} so that {@link CompareCounts.similar} can ignore
+ * it.
  **/
 declare function compareOpportunities(input: CompareOpportunitiesInput): OpportunityCompareReport;
 /**

package/dist/types/dev/mode-parity/comparePositions.d.ts

@@ -34,15 +34,11 @@ interface PositionMatch {
   chainId: ChainId;
   onchainName: string;
   offchainName: string;
-  /**
-   * No diffs at all, including the documented mode-scoped ones.
-   **/
-  identical: boolean;
   /**
    * No unexpected diffs: every disagreement is mode-scoped, backend-preferred,
    * or within tolerance.
    **/
-  clean: boolean;
+  similar: boolean;
   diffs: FieldDiff[];
 }
 /**
@@ -78,7 +74,7 @@ interface PositionsCompareSummary extends CompareCounts {
    * Wallets whose listings were read and that have no membership gaps and no
    * unexpected field diffs.
    **/
-  walletsClean: number;
+  walletsSimilar: number;
   walletsFailed: number;
   byChain: ChainCompareCounts[];
   byWallet: WalletCompareCounts[];
@@ -139,8 +135,8 @@ interface ComparePositionsInput {
  * Nothing is filtered out. A field only one mode can fill, a strategy field
  * both-mode merge overlays from the backend, 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.
+ * {@link FieldDiff.expected} so that {@link CompareCounts.similar} can ignore
+ * it.
  **/
 declare function comparePositions(input: ComparePositionsInput): PositionsCompareReport;
 /**

package/dist/types/dev/mode-parity/fieldDiff.d.ts

@@ -42,7 +42,7 @@ interface FieldDiff {
   kind: DiffKind;
   /**
    * Present when this disagreement is documented or within snapshot-lag noise,
-   * so it does not keep the row from being counted as clean.
+   * so it does not keep the row from being counted as similar.
    **/
   expected?: true;
   reason?: ExpectedDiffReason;
@@ -102,12 +102,14 @@ interface CompareCounts {
   onchainRows: number;
   offchainRows: number;
   matched: number;
-  identical: number;
   /**
-   * Matched rows with no unexpected diffs, including the identical ones.
+   * Matched rows with no unexpected diffs.
    **/
-  clean: number;
-  differing: number;
+  similar: number;
+  /**
+   * Matched rows with at least one unexpected diff.
+   **/
+  different: number;
   onlyOnchain: number;
   onlyOffchain: number;
 }
@@ -157,7 +159,7 @@ declare function diffValue(path: string, onchain: unknown, offchain: unknown, ou
  **/
 declare function diffObjects(onchain: unknown, offchain: unknown, options?: DiffOptions): FieldDiff[];
 /**
- * Mark a diff expected, so a later `clean` count can ignore it.
+ * Mark a diff expected, so a later `similar` count can ignore it.
  **/
 declare function withExpected(diff: FieldDiff, reason: ExpectedDiffReason): FieldDiff;
 /**
@@ -174,8 +176,7 @@ declare function collapseArrayKeys(path: string): string;
  * Membership and match totals of one comparison, from already-built lists.
  **/
 declare function toCompareCounts(onchainRows: number, offchainRows: number, onlyOnchain: number, onlyOffchain: number, matched: ReadonlyArray<{
-  identical: boolean;
-  clean: boolean;
+  similar: boolean;
 }>): CompareCounts;
 /**
  * USD floats within {@link USD_RELATIVE_EPSILON}.

package/dist/types/dev/mode-parity/scriptUtils.d.ts

@@ -16,6 +16,10 @@ declare const TIMEOUT = 480000;
 interface PrintableCompareSummary extends CompareCounts {
   byChain: ChainCompareCounts[];
   diffsByPath: DiffPathCount[];
+  /**
+   * Present on position reports: wallets whose listings could not be read.
+   **/
+  walletsFailed?: number;
 }
 /**
  * Per-source chain metadata both compare reports carry.
@@ -38,10 +42,31 @@ declare function mapPool<T>(items: readonly T[], concurrency: number, fn: (item:
  * Formats a relative difference in bps as a percent, e.g. 12.5 → `"0.125%"`.
  **/
 declare function formatBpsAsPercent(bps: number): string;
+/**
+ * Reasons a compare run should fail CI: unexpected membership or field diffs,
+ * both sources empty, a chain that could not be read, or wallets that failed
+ * to list. Expected diffs (mode-scoped, backend-preferred, tolerance) do not
+ * fail the run.
+ **/
+declare function evaluateCompareFailure(report: PrintableCompareReport): string[];
 /**
  * Prints the shared membership table, the fields that differed most often,
  * and any chain that failed to answer.
  **/
 declare function printCompareSummary(noun: string, report: PrintableCompareReport, extraLines?: string[]): void;
+/**
+ * Markdown of the same summary printed to the console, for GitHub job summaries.
+ **/
+declare function formatCompareMarkdown(noun: string, report: PrintableCompareReport, extraLines?: string[], reasons?: string[]): string;
+/**
+ * Appends {@link formatCompareMarkdown} to `GITHUB_STEP_SUMMARY` when running
+ * in GitHub Actions. No-op locally.
+ **/
+declare function writeGithubJobSummary(noun: string, report: PrintableCompareReport, extraLines?: string[], reasons?: string[]): void;
+/**
+ * Console + job-summary output for a compare run. Returns the failure reasons
+ * so the caller can exit 1 when the report is not similar.
+ **/
+declare function reportCompare(noun: string, report: PrintableCompareReport, extraLines?: string[]): string[];
 //#endregion
-export { BACKEND_URL, ComparedNetwork, NETWORKS, PrintableCompareReport, PrintableCompareSummary, TIMEOUT, createLogger, errorMessage, formatBpsAsPercent, mapPool, printCompareSummary, requireEnv, rpcUrls };
+export { BACKEND_URL, ComparedNetwork, NETWORKS, PrintableCompareReport, PrintableCompareSummary, TIMEOUT, createLogger, errorMessage, evaluateCompareFailure, formatBpsAsPercent, formatCompareMarkdown, mapPool, printCompareSummary, reportCompare, requireEnv, rpcUrls, writeGithubJobSummary };