@gearbox-protocol/sdk 14.12.0-next.80 → 14.12.0-next.82

package/dist/esm/sdk/pools/PoolService.js

@@ -1,5 +1,5 @@
-import { ierc20Abi } from "../../abi/iERC20.js";
 import { AddressSet } from "../utils/AddressSet.js";
+import { ierc20Abi } from "../../abi/iERC20.js";
 import "../constants/addresses.js";
 import { RAY } from "../constants/math.js";
 import "../constants/index.js";
@@ -188,7 +188,8 @@ var PoolService = class extends SDKConstruct {
 				args: [props.wallet]
 			})),
 			allowFailure: false,
-			batchSize: 0
+			batchSize: 0,
+			blockNumber: props.blockNumber
 		});
 		return markets.flatMap((market, i) => {
 			const shares = balances[i] ?? 0n;

package/dist/esm/sdk/positions/MultichainPositionsService.js

@@ -1,50 +1,27 @@
-import { getNetworkType } from "../chain/chains.js";
 import { MultichainConstruct } from "../base/MultichainConstruct.js";
 import "../base/index.js";
-import { isFilterSet } from "../../model/filters.js";
-import "../../model/index.js";
 //#region src/sdk/positions/MultichainPositionsService.ts
 /**
 * Cross-chain counterpart of {@link PositionsService}.
 *
-* Fans out over every chain configured in {@link MultichainSDK}. A chain that
-* fails is logged and skipped so one dead RPC does not hide the positions a
-* wallet holds elsewhere; its failure is reported in
-* {@link MultichainResult.meta}.
-*
 * @typeParam Plugins - Map of attached plugin types.
 **/
 var MultichainPositionsService = class extends MultichainConstruct {
 	/**
 	* Positions of a wallet on all queried chains, see
 	* {@link PositionsService.list}.
-	*
-	* A filter that names chains narrows the fan-out itself, so chains whose rows
-	* would be discarded are never queried and never appear in the meta.
 	**/
 	async list(props) {
 		return this.queryChains({
-			networks: this.#networksOf(props.filter),
+			chainIds: props.filter?.chainIds,
 			label: "list positions",
-			run: (sdk) => sdk.positions.list(props)
+			block: "latest",
+			run: (sdk, block) => sdk.positions.list({
+				...props,
+				blockNumber: block.blockNumber
+			})
 		});
 	}
-	/**
-	* Chains named by the filter, or `undefined` to query all of them. Chain ids
-	* the SDK does not support are dropped here rather than reported as failures:
-	* a filter naming them is a narrowing, not a request.
-	**/
-	#networksOf(filter) {
-		const chainIds = filter?.chainIds;
-		if (!isFilterSet(chainIds)) return;
-		const networks = [];
-		for (const chainId of chainIds) try {
-			networks.push(getNetworkType(chainId));
-		} catch {
-			this.sdk.logger?.debug(`ignoring unsupported chain ${chainId} in positions filter`);
-		}
-		return networks;
-	}
 };
 //#endregion
 export { MultichainPositionsService };

package/dist/esm/sdk/positions/PositionsService.js

@@ -17,19 +17,25 @@ var PositionsService = class extends SDKConstruct {
 	* the call rather than the SDK's loaded snapshot.
 	**/
 	async list(props) {
-		const { wallet, filter } = props;
-		const chainIds = filter?.chainIds;
-		if (isFilterSet(chainIds) && !chainIds.includes(this.chainId)) return [];
+		const { wallet, filter, blockNumber } = props;
+		if (filter?.chainIds && !filter.chainIds.includes(this.chainId)) return [];
 		const wantedKind = filter?.kind;
 		const wanted = (kind) => !isFilterSet(wantedKind) || wantedKind === kind;
 		const isZeroDebt = filter?.isZeroDebt;
 		const [pool, strategy, liquidation] = await Promise.all([
-			wanted("pool") ? this.sdk.pools.listPositions({ wallet }) : Promise.resolve([]),
+			wanted("pool") ? this.sdk.pools.listPositions({
+				wallet,
+				blockNumber
+			}) : Promise.resolve([]),
 			wanted("strategy") ? this.sdk.accounts.listPositions({
 				owner: wallet,
-				includeZeroDebt: !isFilterSet(isZeroDebt) || isZeroDebt
+				includeZeroDebt: !isFilterSet(isZeroDebt) || isZeroDebt,
+				blockNumber
 			}) : Promise.resolve([]),
-			wanted("liquidation") ? this.sdk.liquidations.getLiquidationPositions({ liquidator: wallet }) : Promise.resolve([])
+			wanted("liquidation") ? this.sdk.liquidations.getLiquidationPositions({
+				liquidator: wallet,
+				blockNumber
+			}) : Promise.resolve([])
 		]);
 		return [
 			...pool,

package/dist/esm/sdk/utils/viem/simulateWithPriceUpdates.js

@@ -1,6 +1,6 @@
 import { errorAbis } from "../../../abi/errors.js";
-import { iUpdatablePriceFeedAbi } from "../../../abi/iUpdatablePriceFeed.js";
 import { generateCastTraceCall } from "./cast.js";
+import { iUpdatablePriceFeedAbi } from "../../../abi/iUpdatablePriceFeed.js";
 import { simulateMulticall } from "./simulateMulticall.js";
 import { BaseError, CallExecutionError, ContractFunctionRevertedError, decodeFunctionData, decodeFunctionResult, encodeFunctionData, parseAbi } from "viem";
 import { getAction, parseAccount } from "viem/utils";

package/dist/types/model/filters.d.ts

@@ -1,8 +1,14 @@
+import { ChainId } from "./primitives.js";
 //#region src/model/filters.d.ts
 /**
- * The vocabulary every read-model filter is written in: how a single condition
- * says "do not narrow", and how a predicate asks whether it narrows at all.
+ * The part of a filter that scopes it to chains, which every list filter has.
  **/
+interface ChainScopedFilter {
+  /**
+   * Keep only entities from these chains.
+   **/
+  chainIds?: ChainId[];
+}
 /**
  * Sentinel a filter condition can be set to instead of being omitted.
  **/
@@ -27,4 +33,4 @@ type Filterable<T> = T | FilterAll;
  **/
 declare function isFilterSet<T>(condition: Filterable<T> | undefined): condition is T;
 //#endregion
-export { FILTER_ALL, FilterAll, Filterable, isFilterSet };
+export { ChainScopedFilter, FILTER_ALL, FilterAll, Filterable, isFilterSet };

package/dist/types/model/filters.schema.d.ts

@@ -1,3 +1,4 @@
+import { Filterable } from "./filters.js";
 import { z } from "zod/v4";
 //#region src/model/filters.schema.d.ts
 /**
@@ -16,5 +17,10 @@ declare const booleanParamSchema: z.ZodEnum<{
   false: "false";
   true: "true";
 }>;
+/**
+ * A boolean condition as a URL can carry it: a condition that does not narrow
+ * is absent rather than spelled out, see {@link booleanParamSchema}.
+ **/
+declare function encodeFlag(condition: Filterable<boolean> | undefined): "true" | "false" | undefined;
 //#endregion
-export { booleanParamSchema, filterAllSchema, filterable };
+export { booleanParamSchema, encodeFlag, filterAllSchema, filterable };

package/dist/types/model/index.d.ts

@@ -1,8 +1,8 @@
-import { Curator, CuratorName } from "./curators.js";
 import { Amount, AssetType, Bps, ChainId, Leverage, Timestamp, Token, TokenAmount, TxCall } from "./primitives.js";
+import { Curator, CuratorName } from "./curators.js";
 import { curatorNameSchema, curatorSchema } from "./curators.schema.js";
-import { FILTER_ALL, FilterAll, Filterable, isFilterSet } from "./filters.js";
-import { booleanParamSchema, filterAllSchema, filterable } from "./filters.schema.js";
+import { ChainScopedFilter, FILTER_ALL, FilterAll, Filterable, isFilterSet } from "./filters.js";
+import { booleanParamSchema, encodeFlag, filterAllSchema, filterable } from "./filters.schema.js";
 import { ApyBreakdown, Opportunity, OpportunityBase, OpportunityDetail, OpportunityFilter, OpportunityId, OpportunityKey, OpportunityKind, PointRewards, PointsProgram, PoolOpportunity, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, PriceFeedData, PriceFeedSummary, QuotaAsset, RateCurve, RateCurvePoint, Rewards, StrategyOpportunity, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef, TokenRewards, matchesOpportunityFilter, opportunityId, poolOpportunityId, strategyOpportunityId } from "./opportunities.js";
 import { DelayedReceivedAsset, InstantReceivedAsset, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, ReceivedAsset, matchesLiquidatableAccountFilter } from "./liquidations.js";
 import { PnlBreakdown, PointsProgramPnL, PointsRewardsPnL, PoolPosition, PoolPositionKey, PoolPositionRef, Position, PositionCollateral, PositionFilter, PositionId, PositionKey, PositionKind, RewardsPnL, StrategyPosition, StrategyPositionKey, StrategyPositionRef, TokenRewardsPnL, liquidationPositionId, matchesPositionFilter, poolPositionId, positionId, strategyPositionId } from "./positions.js";
@@ -10,6 +10,8 @@ import { HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, Histor
 import { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, poolPositionHistoryMetricSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, strategyHistoryMetricSchema, strategyPositionHistoryMetricSchema } from "./history.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, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
-import { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
+import { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
 import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema } from "./primitives.schema.js";
-export { Amount, ApyBreakdown, AssetType, Bps, ChainId, Curator, CuratorName, DelayedReceivedAsset, FILTER_ALL, FilterAll, Filterable, HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, HistorySeries, InstantReceivedAsset, Leverage, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, Opportunity, OpportunityBase, OpportunityDetail, OpportunityFilter, OpportunityHistoryQuery, OpportunityId, OpportunityKey, OpportunityKind, POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, PnlBreakdown, PointRewards, PointsProgram, PointsProgramPnL, PointsRewardsPnL, PoolHistoryMetric, PoolOpportunity, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, PoolPosition, PoolPositionHistoryMetric, PoolPositionKey, PoolPositionRef, Position, PositionCollateral, PositionFilter, PositionHistoryMetric, PositionHistoryQuery, PositionId, PositionKey, PositionKind, PriceFeedData, PriceFeedSummary, QuotaAsset, RateCurve, RateCurvePoint, ReceivedAsset, Rewards, RewardsPnL, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS, StrategyHistoryMetric, StrategyOpportunity, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef, StrategyPosition, StrategyPositionHistoryMetric, StrategyPositionKey, StrategyPositionRef, Timestamp, Token, TokenAmount, TokenRewards, TokenRewardsPnL, TxCall, amountSchema, apyBreakdownSchema, assetTypeSchema, booleanParamSchema, bpsSchema, chainIdSchema, curatorNameSchema, curatorSchema, delayedReceivedAssetSchema, filterAllSchema, filterable, historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, instantReceivedAssetSchema, isFilterSet, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityHistoryQuerySchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolHistoryMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionHistoryMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, positionId, positionKeySchema, positionKindSchema, positionSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, rewardsPnLSchema, rewardsSchema, strategyHistoryMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionHistoryMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, txCallSchema };
+import { ChainFailed, ChainMetadata, ChainScoped, ChainSucceeded, DataResponse, DataSource, ResponseMetadata } from "./response.js";
+import { chainFailedSchema, chainMetadataSchema, chainSucceededSchema, dataSourceSchema, responseMetadataSchema, responseSchema } from "./response.schema.js";
+export { Amount, ApyBreakdown, AssetType, Bps, ChainFailed, ChainId, ChainMetadata, ChainScoped, ChainScopedFilter, ChainSucceeded, Curator, CuratorName, DataResponse, DataSource, DelayedReceivedAsset, FILTER_ALL, FilterAll, Filterable, HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, HistorySeries, InstantReceivedAsset, Leverage, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, Opportunity, OpportunityBase, OpportunityDetail, OpportunityFilter, OpportunityHistoryQuery, OpportunityId, OpportunityKey, OpportunityKind, POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, PnlBreakdown, PointRewards, PointsProgram, PointsProgramPnL, PointsRewardsPnL, PoolHistoryMetric, PoolOpportunity, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, PoolPosition, PoolPositionHistoryMetric, PoolPositionKey, PoolPositionRef, Position, PositionCollateral, PositionFilter, PositionHistoryMetric, PositionHistoryQuery, PositionId, PositionKey, PositionKind, PriceFeedData, PriceFeedSummary, QuotaAsset, RateCurve, RateCurvePoint, ReceivedAsset, ResponseMetadata, Rewards, RewardsPnL, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS, StrategyHistoryMetric, StrategyOpportunity, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef, StrategyPosition, StrategyPositionHistoryMetric, StrategyPositionKey, StrategyPositionRef, Timestamp, Token, TokenAmount, TokenRewards, TokenRewardsPnL, TxCall, amountSchema, apyBreakdownSchema, assetTypeSchema, booleanParamSchema, bpsSchema, chainFailedSchema, chainIdSchema, chainMetadataSchema, chainSucceededSchema, curatorNameSchema, curatorSchema, dataSourceSchema, delayedReceivedAssetSchema, encodeFlag, filterAllSchema, filterable, historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, instantReceivedAssetSchema, isFilterSet, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityHistoryQuerySchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolHistoryMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionHistoryMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, positionId, positionKeySchema, positionKindSchema, positionSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, responseMetadataSchema, responseSchema, rewardsPnLSchema, rewardsSchema, strategyHistoryMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionHistoryMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, txCallSchema };

package/dist/types/model/liquidations.d.ts

@@ -1,5 +1,5 @@
 import { AssetType, ChainId, Timestamp, Token, TokenAmount, TxCall } from "./primitives.js";
-import { Filterable } from "./filters.js";
+import { ChainScopedFilter, Filterable } from "./filters.js";
 import { Address } from "viem";
 //#region src/model/liquidations.d.ts
 /**
@@ -10,11 +10,7 @@ import { Address } from "viem";
  * `"all"` to say the same thing explicitly, which is what a UI whose state has
  * an "any" option holds, see {@link Filterable}. Conditions combine with AND.
  **/
-interface LiquidatableAccountFilter {
-  /**
-   * Keep only accounts on these chains.
-   **/
-  chainIds?: Filterable<ChainId[]>;
+interface LiquidatableAccountFilter extends ChainScopedFilter {
   /**
    * Keep only accounts whose underlying — the token of
    * {@link LiquidatableAccount.totalValue} — is of this class.

package/dist/types/model/liquidations.schema.d.ts

@@ -8,7 +8,7 @@ import { z } from "zod/v4";
  * {@link LiquidatableAccountFilter}
  **/
 declare const liquidatableAccountFilterSchema: z.ZodObject<{
-  chainIds: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
   underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
   paused: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
   rwa: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;

package/dist/types/model/opportunities.d.ts

@@ -1,6 +1,6 @@
-import { Curator } from "./curators.js";
 import { Amount, AssetType, Bps, ChainId, Leverage, Timestamp, Token } from "./primitives.js";
-import { Filterable } from "./filters.js";
+import { Curator } from "./curators.js";
+import { ChainScopedFilter, Filterable } from "./filters.js";
 import { Address } from "viem";
 //#region src/model/opportunities.d.ts
 /**
@@ -356,15 +356,11 @@ declare function opportunityId(opportunity: Opportunity): OpportunityId;
  * `"all"` to say the same thing explicitly, which is what a UI whose state has
  * an "any" option holds, see {@link Filterable}. Conditions combine with AND.
  **/
-interface OpportunityFilter {
+interface OpportunityFilter extends ChainScopedFilter {
   /**
    * Keep only pools or only strategies.
    **/
   kind?: Filterable<OpportunityKind>;
-  /**
-   * Keep only opportunities on these chains.
-   **/
-  chainIds?: Filterable<ChainId[]>;
   /**
    * Keep only opportunities whose {@link OpportunityBase.underlyingToken} is of
    * this class, which for an RWA market means the class of the token its

package/dist/types/model/opportunities.schema.d.ts

@@ -562,7 +562,7 @@ declare const opportunitySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
  **/
 declare const opportunityFilterSchema: z.ZodObject<{
   kind: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">]>, z.ZodLiteral<"all">]>>;
-  chainIds: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
   underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
   paused: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
   sunset: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
@@ -610,7 +610,7 @@ declare const opportunityFilterQuerySchema: z.ZodCodec<z.ZodObject<{
   }>>;
 }, z.core.$strip>, z.ZodObject<{
   kind: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">]>, z.ZodLiteral<"all">]>>;
-  chainIds: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
   underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
   paused: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
   sunset: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;

package/dist/types/model/positions.d.ts

@@ -1,5 +1,5 @@
 import { AssetType, Bps, ChainId, Leverage, Token, TokenAmount } from "./primitives.js";
-import { Filterable } from "./filters.js";
+import { ChainScopedFilter, Filterable } from "./filters.js";
 import { ApyBreakdown, PointsProgram } from "./opportunities.js";
 import { DelayedReceivedAsset, LiquidationPosition } from "./liquidations.js";
 import { Address } from "viem";
@@ -264,7 +264,7 @@ declare function positionId(position: Position): PositionId;
  * `"all"` to say the same thing explicitly, which is what a UI whose state has
  * an "any" option holds, see {@link Filterable}. Conditions combine with AND.
  **/
-interface PositionFilter {
+interface PositionFilter extends ChainScopedFilter {
   /**
    * Keep only positions of this kind.
    **/
@@ -274,10 +274,6 @@ interface PositionFilter {
    * Applicable only to {@link StrategyPosition}
    **/
   isZeroDebt?: Filterable<boolean>;
-  /**
-   * Keep only positions on these chains.
-   **/
-  chainIds?: Filterable<ChainId[]>;
   /**
    * Keep only positions whose underlying is of this class, which for an RWA
    * market means the class of the token its wrapper holds.

package/dist/types/model/positions.schema.d.ts

@@ -694,9 +694,39 @@ declare const positionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 declare const positionFilterSchema: z.ZodObject<{
   kind: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">, z.ZodLiteral<"liquidation">]>, z.ZodLiteral<"all">]>>;
   isZeroDebt: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
-  chainIds: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
   underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
 }, z.core.$strip>;
+/**
+ * {@link PositionFilter} as a URL can carry it: every condition is a string,
+ * and a condition that does not narrow is absent rather than empty.
+ **/
+declare const positionFilterQueryParamsSchema: z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">, z.ZodLiteral<"liquidation">]>>;
+  isZeroDebt: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  chainIds: z.ZodOptional<z.ZodString>;
+  underlyingType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+}, z.core.$strip>;
+/**
+ * Code for {@link PositionFilter} to encode/decode to/from url query parameters.
+ **/
+declare const positionFilterQuerySchema: z.ZodCodec<z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">, z.ZodLiteral<"liquidation">]>>;
+  isZeroDebt: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  chainIds: z.ZodOptional<z.ZodString>;
+  underlyingType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">, z.ZodLiteral<"liquidation">]>, z.ZodLiteral<"all">]>>;
+  isZeroDebt: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+  underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
+}, z.core.$strip>>;
 /**
  * {@link PoolPositionKey}
  **/
@@ -726,4 +756,4 @@ declare const positionKeySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   kind: z.ZodLiteral<"strategy">;
 }, z.core.$strip>], "kind">;
 //#endregion
-export { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema };
+export { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema };

package/dist/types/model/response.d.ts

@@ -0,0 +1,105 @@
+import { ChainId, Timestamp } from "./primitives.js";
+//#region src/model/response.d.ts
+/**
+ * Shared response envelope: the payload plus per-chain metadata naming which
+ * source served each chain.
+ *
+ * The backend sends this on HTTP success only. Transport failures, timeouts,
+ * and backend error bodies are not an envelope — the offchain client wraps
+ * those, because the request may never have reached the backend.
+ *
+ * @typeParam T - Payload type
+ **/
+interface DataResponse<T> {
+  /**
+   * Response payload.
+   **/
+  data: T;
+  /**
+   * Per-chain outcome of the read, see {@link ResponseMetadata}.
+   **/
+  meta: ResponseMetadata;
+}
+/**
+ * Per-chain outcomes attached to every {@link DataResponse}.
+ **/
+interface ResponseMetadata {
+  /**
+   * One entry per chain the read asked. After a merge, each success names the
+   * side that won it in {@link ChainSucceeded.source}, so a consumer can tell
+   * a chain served live from a chain served by the backend without per-row
+   * provenance.
+   **/
+  chains: ChainMetadata[];
+}
+/**
+ * Which side produced a chain's data.
+ **/
+type DataSource = "onchain" | "offchain";
+/**
+ * Chain that answered, which source served it, and the block it answered from.
+ *
+ * Discriminated from {@link ChainFailed} on {@link status}, so a success
+ * without a source, or without the block it reflects, is unrepresentable.
+ **/
+interface ChainSucceeded {
+  /**
+   * Chain the entry describes.
+   **/
+  chainId: ChainId;
+  status: "success";
+  /**
+   * Source that produced this chain's data. Never absent on success: some
+   * source produced it.
+   **/
+  source: DataSource;
+  /**
+   * Block the data reflects. A `number` here (model convention), converted
+   * from `bigint` at the onchain boundary. A chain that cannot say which block
+   * it answered from is a {@link ChainFailed}.
+   **/
+  blockNumber: number;
+  /**
+   * Unix seconds of {@link blockNumber}.
+   **/
+  timestamp: Timestamp;
+}
+/**
+ * Chain that did not answer.
+ **/
+interface ChainFailed {
+  /**
+   * Chain the entry describes.
+   **/
+  chainId: ChainId;
+  status: "error";
+  /**
+   * Source that failed this chain. Absent when every source failed for it, so
+   * no side won it.
+   **/
+  source?: DataSource;
+  /**
+   * Rejection reason. A `string` in a JSON response, an `Error` (or an
+   * `AggregateError` when both sources failed) when produced locally.
+   *
+   * Serialises to `{}` if an envelope carrying a real `Error` is put into
+   * Redux or a log as-is.
+   **/
+  error?: unknown;
+}
+/**
+ * Per-chain outcome, discriminated on {@link ChainSucceeded.status} /
+ * {@link ChainFailed.status}.
+ **/
+type ChainMetadata = ChainSucceeded | ChainFailed;
+/**
+ * Anything the read model scopes to one chain, i.e. every list row.
+ **/
+interface ChainScoped {
+  /**
+   * Chain the row lives on.
+   **/
+  chainId: ChainId;
+}
+//#endregion
+export { ChainFailed, ChainMetadata, ChainScoped, ChainSucceeded, DataResponse, DataSource, ResponseMetadata };

package/dist/types/model/response.schema.d.ts

@@ -0,0 +1,98 @@
+import { DataResponse } from "./response.js";
+import { z } from "zod/v4";
+//#region src/model/response.schema.d.ts
+/**
+ * Runtime schemas for {@link ./response.js}, see the note in
+ * `primitives.schema.ts` on why they are written by hand.
+ *
+ * `responseSchema(payloadSchema)` validates a successful backend 2xx body.
+ * HTTP and transport errors never pass through it.
+ **/
+/**
+ * {@link DataSource}
+ **/
+declare const dataSourceSchema: z.ZodEnum<{
+  offchain: "offchain";
+  onchain: "onchain";
+}>;
+/**
+ * {@link ChainSucceeded}
+ *
+ * `source` may be omitted by the backend and decodes to `"offchain"`. The block
+ * has no such default: a success that omits it fails validation.
+ **/
+declare const chainSucceededSchema: z.ZodObject<{
+  chainId: z.ZodNumber;
+  status: z.ZodLiteral<"success">;
+  source: z.ZodDefault<z.ZodEnum<{
+    offchain: "offchain";
+    onchain: "onchain";
+  }>>;
+  blockNumber: z.ZodNumber;
+  timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * {@link ChainFailed}
+ *
+ * `error` is a `string` in a JSON body. The schema accepts `unknown` so the
+ * same codec also validates a locally produced envelope carrying an `Error`.
+ **/
+declare const chainFailedSchema: z.ZodObject<{
+  chainId: z.ZodNumber;
+  status: z.ZodLiteral<"error">;
+  source: z.ZodOptional<z.ZodEnum<{
+    offchain: "offchain";
+    onchain: "onchain";
+  }>>;
+  error: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * {@link ChainMetadata}
+ **/
+declare const chainMetadataSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  chainId: z.ZodNumber;
+  status: z.ZodLiteral<"success">;
+  source: z.ZodDefault<z.ZodEnum<{
+    offchain: "offchain";
+    onchain: "onchain";
+  }>>;
+  blockNumber: z.ZodNumber;
+  timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+  chainId: z.ZodNumber;
+  status: z.ZodLiteral<"error">;
+  source: z.ZodOptional<z.ZodEnum<{
+    offchain: "offchain";
+    onchain: "onchain";
+  }>>;
+  error: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>], "status">;
+/**
+ * {@link ResponseMetadata}
+ **/
+declare const responseMetadataSchema: z.ZodObject<{
+  chains: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    chainId: z.ZodNumber;
+    status: z.ZodLiteral<"success">;
+    source: z.ZodDefault<z.ZodEnum<{
+      offchain: "offchain";
+      onchain: "onchain";
+    }>>;
+    blockNumber: z.ZodNumber;
+    timestamp: z.ZodNumber;
+  }, z.core.$strip>, z.ZodObject<{
+    chainId: z.ZodNumber;
+    status: z.ZodLiteral<"error">;
+    source: z.ZodOptional<z.ZodEnum<{
+      offchain: "offchain";
+      onchain: "onchain";
+    }>>;
+    error: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strip>], "status">>;
+}, z.core.$strip>;
+/**
+ * {@link DataResponse} parameterized by the payload schema.
+ **/
+declare function responseSchema<S extends z.ZodType>(payloadSchema: S): z.ZodType<DataResponse<z.output<S>>>;
+//#endregion
+export { chainFailedSchema, chainMetadataSchema, chainSucceededSchema, dataSourceSchema, responseMetadataSchema, responseSchema };