@gearbox-protocol/sdk 14.12.0-next.81 → 14.12.0-next.83

package/dist/cjs/model/filters.js

@@ -1,10 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/model/filters.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.
-**/
-/**
 * Sentinel a filter condition can be set to instead of being omitted.
 **/
 const FILTER_ALL = "all";

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

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./filters.js");
+const require_model_filters = require("./filters.js");
 let zod_v4 = require("zod/v4");
 //#region src/model/filters.schema.ts
 /**
@@ -17,7 +17,16 @@ function filterable(schema) {
 	return zod_v4.z.union([schema, filterAllSchema]);
 }
 const booleanParamSchema = zod_v4.z.enum(["true", "false"]);
+/**
+* A boolean condition as a URL can carry it: a condition that does not narrow
+* is absent rather than spelled out, see {@link booleanParamSchema}.
+**/
+function encodeFlag(condition) {
+	if (!require_model_filters.isFilterSet(condition)) return;
+	return condition ? "true" : "false";
+}
 //#endregion
 exports.booleanParamSchema = booleanParamSchema;
+exports.encodeFlag = encodeFlag;
 exports.filterAllSchema = filterAllSchema;
 exports.filterable = filterable;

package/dist/cjs/model/index.js

@@ -33,6 +33,7 @@ exports.curatorNameSchema = require_model_curators_schema.curatorNameSchema;
 exports.curatorSchema = require_model_curators_schema.curatorSchema;
 exports.dataSourceSchema = require_model_response_schema.dataSourceSchema;
 exports.delayedReceivedAssetSchema = require_model_liquidations_schema.delayedReceivedAssetSchema;
+exports.encodeFlag = require_model_filters_schema.encodeFlag;
 exports.filterAllSchema = require_model_filters_schema.filterAllSchema;
 exports.filterable = require_model_filters_schema.filterable;
 exports.historyChartMetadataSchema = require_model_history_schema.historyChartMetadataSchema;
@@ -77,6 +78,8 @@ exports.poolPositionId = require_model_positions.poolPositionId;
 exports.poolPositionKeySchema = require_model_positions_schema.poolPositionKeySchema;
 exports.poolPositionSchema = require_model_positions_schema.poolPositionSchema;
 exports.positionCollateralSchema = require_model_positions_schema.positionCollateralSchema;
+exports.positionFilterQueryParamsSchema = require_model_positions_schema.positionFilterQueryParamsSchema;
+exports.positionFilterQuerySchema = require_model_positions_schema.positionFilterQuerySchema;
 exports.positionFilterSchema = require_model_positions_schema.positionFilterSchema;
 exports.positionHistoryMetricSchema = require_model_history_schema.positionHistoryMetricSchema;
 exports.positionHistoryQuerySchema = require_model_history_schema.positionHistoryQuerySchema;

package/dist/cjs/model/liquidations.js

@@ -14,7 +14,7 @@ const require_model_filters = require("./filters.js");
 **/
 function matchesLiquidatableAccountFilter(account, filter) {
 	if (!filter) return true;
-	if (require_model_filters.isFilterSet(filter.chainIds) && !filter.chainIds.includes(account.chainId)) return false;
+	if (filter.chainIds && !filter.chainIds.includes(account.chainId)) return false;
 	if (require_model_filters.isFilterSet(filter.underlyingType) && account.totalValue.token.assetType !== filter.underlyingType) return false;
 	if (require_model_filters.isFilterSet(filter.paused) && account.paused !== filter.paused) return false;
 	if (require_model_filters.isFilterSet(filter.rwa) && account.rwa !== filter.rwa) return false;

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

@@ -12,7 +12,7 @@ let zod_v4 = require("zod/v4");
 * {@link LiquidatableAccountFilter}
 **/
 const liquidatableAccountFilterSchema = zod_v4.z.object({
-	chainIds: require_model_filters_schema.filterable(zod_v4.z.array(require_model_primitives_schema.chainIdSchema)).optional(),
+	chainIds: zod_v4.z.array(require_model_primitives_schema.chainIdSchema).optional(),
 	underlyingType: require_model_filters_schema.filterable(require_model_primitives_schema.assetTypeSchema).optional(),
 	paused: require_model_filters_schema.filterable(zod_v4.z.boolean()).optional(),
 	rwa: require_model_filters_schema.filterable(zod_v4.z.boolean()).optional(),

package/dist/cjs/model/opportunities.js

@@ -43,7 +43,7 @@ function opportunityId(opportunity) {
 function matchesOpportunityFilter(opportunity, filter) {
 	if (!filter) return true;
 	if (require_model_filters.isFilterSet(filter.kind) && opportunity.kind !== filter.kind) return false;
-	if (require_model_filters.isFilterSet(filter.chainIds) && !filter.chainIds.includes(opportunity.chainId)) return false;
+	if (filter.chainIds && !filter.chainIds.includes(opportunity.chainId)) return false;
 	if (require_model_filters.isFilterSet(filter.underlyingType) && opportunity.underlyingToken.assetType !== filter.underlyingType) return false;
 	if (require_model_filters.isFilterSet(filter.paused) && opportunity.paused !== filter.paused) return false;
 	if (require_model_filters.isFilterSet(filter.sunset) && opportunity.sunset !== filter.sunset) return false;

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

@@ -106,7 +106,7 @@ const opportunitySchema = zod_v4.z.discriminatedUnion("kind", [poolOpportunitySc
 **/
 const opportunityFilterSchema = zod_v4.z.object({
 	kind: require_model_filters_schema.filterable(opportunityKindSchema).optional(),
-	chainIds: require_model_filters_schema.filterable(zod_v4.z.array(require_model_primitives_schema.chainIdSchema)).optional(),
+	chainIds: zod_v4.z.array(require_model_primitives_schema.chainIdSchema).optional(),
 	underlyingType: require_model_filters_schema.filterable(require_model_primitives_schema.assetTypeSchema).optional(),
 	paused: require_model_filters_schema.filterable(zod_v4.z.boolean()).optional(),
 	sunset: require_model_filters_schema.filterable(zod_v4.z.boolean()).optional(),
@@ -131,7 +131,7 @@ const opportunityFilterQuerySchema = zod_v4.z.codec(opportunityFilterQueryParams
 	decode: (params) => {
 		const filter = {};
 		if (params.kind !== void 0) filter.kind = params.kind;
-		if (params.chainIds !== void 0) filter.chainIds = decodeChainIds(params.chainIds);
+		if (params.chainIds !== void 0) filter.chainIds = params.chainIds === "" ? [] : params.chainIds.split(",").map(Number);
 		if (params.underlyingType !== void 0) filter.underlyingType = params.underlyingType;
 		if (params.paused !== void 0) filter.paused = params.paused === "true";
 		if (params.sunset !== void 0) filter.sunset = params.sunset === "true";
@@ -140,20 +140,13 @@ const opportunityFilterQuerySchema = zod_v4.z.codec(opportunityFilterQueryParams
 	},
 	encode: (filter) => ({
 		kind: require_model_filters.isFilterSet(filter.kind) ? filter.kind : void 0,
-		chainIds: require_model_filters.isFilterSet(filter.chainIds) ? filter.chainIds.join(",") : void 0,
+		chainIds: filter.chainIds?.join(","),
 		underlyingType: require_model_filters.isFilterSet(filter.underlyingType) ? filter.underlyingType : void 0,
-		paused: encodeFlag(filter.paused),
-		sunset: encodeFlag(filter.sunset),
-		rwa: encodeFlag(filter.rwa)
+		paused: require_model_filters_schema.encodeFlag(filter.paused),
+		sunset: require_model_filters_schema.encodeFlag(filter.sunset),
+		rwa: require_model_filters_schema.encodeFlag(filter.rwa)
 	})
 });
-function decodeChainIds(param) {
-	return param === "" ? [] : param.split(",").map(Number);
-}
-function encodeFlag(condition) {
-	if (!require_model_filters.isFilterSet(condition)) return;
-	return condition ? "true" : "false";
-}
 /**
 * {@link RateCurvePoint}
 **/

package/dist/cjs/model/positions.js

@@ -65,7 +65,7 @@ function positionId(position) {
 function matchesPositionFilter(position, filter) {
 	if (!filter) return true;
 	if (require_model_filters.isFilterSet(filter.kind) && position.kind !== filter.kind) return false;
-	if (require_model_filters.isFilterSet(filter.chainIds) && !filter.chainIds.includes(position.chainId)) return false;
+	if (filter.chainIds && !filter.chainIds.includes(position.chainId)) return false;
 	if (require_model_filters.isFilterSet(filter.isZeroDebt) && position.kind === "strategy" && position.totalDebt.value === 0n !== filter.isZeroDebt) return false;
 	if (require_model_filters.isFilterSet(filter.underlyingType)) {
 		const underlying = positionUnderlying(position);

package/dist/cjs/model/positions.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_filters = require("./filters.js");
 const require_model_filters_schema = require("./filters.schema.js");
 const require_model_primitives_schema = require("./primitives.schema.js");
 const require_model_opportunities_schema = require("./opportunities.schema.js");
@@ -104,10 +105,39 @@ const positionSchema = zod_v4.z.discriminatedUnion("kind", [
 const positionFilterSchema = zod_v4.z.object({
 	kind: require_model_filters_schema.filterable(positionKindSchema).optional(),
 	isZeroDebt: require_model_filters_schema.filterable(zod_v4.z.boolean()).optional(),
-	chainIds: require_model_filters_schema.filterable(zod_v4.z.array(require_model_primitives_schema.chainIdSchema)).optional(),
+	chainIds: zod_v4.z.array(require_model_primitives_schema.chainIdSchema).optional(),
 	underlyingType: require_model_filters_schema.filterable(require_model_primitives_schema.assetTypeSchema).optional()
 });
 /**
+* {@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.
+**/
+const positionFilterQueryParamsSchema = zod_v4.z.object({
+	kind: positionKindSchema.optional(),
+	isZeroDebt: require_model_filters_schema.booleanParamSchema.optional(),
+	chainIds: zod_v4.z.string().regex(/^$|^\d+(,\d+)*$/).optional(),
+	underlyingType: require_model_primitives_schema.assetTypeSchema.optional()
+});
+/**
+* Code for {@link PositionFilter} to encode/decode to/from url query parameters.
+**/
+const positionFilterQuerySchema = zod_v4.z.codec(positionFilterQueryParamsSchema, positionFilterSchema, {
+	decode: (params) => {
+		const filter = {};
+		if (params.kind !== void 0) filter.kind = params.kind;
+		if (params.isZeroDebt !== void 0) filter.isZeroDebt = params.isZeroDebt === "true";
+		if (params.chainIds !== void 0) filter.chainIds = params.chainIds === "" ? [] : params.chainIds.split(",").map(Number);
+		if (params.underlyingType !== void 0) filter.underlyingType = params.underlyingType;
+		return filter;
+	},
+	encode: (filter) => ({
+		kind: require_model_filters.isFilterSet(filter.kind) ? filter.kind : void 0,
+		isZeroDebt: require_model_filters_schema.encodeFlag(filter.isZeroDebt),
+		chainIds: filter.chainIds?.join(","),
+		underlyingType: require_model_filters.isFilterSet(filter.underlyingType) ? filter.underlyingType : void 0
+	})
+});
+/**
 * {@link PoolPositionKey}
 **/
 const poolPositionKeySchema = zod_v4.z.object({
@@ -139,6 +169,8 @@ exports.pointsRewardsPnLSchema = pointsRewardsPnLSchema;
 exports.poolPositionKeySchema = poolPositionKeySchema;
 exports.poolPositionSchema = poolPositionSchema;
 exports.positionCollateralSchema = positionCollateralSchema;
+exports.positionFilterQueryParamsSchema = positionFilterQueryParamsSchema;
+exports.positionFilterQuerySchema = positionFilterQuerySchema;
 exports.positionFilterSchema = positionFilterSchema;
 exports.positionKeySchema = positionKeySchema;
 exports.positionKindSchema = positionKindSchema;

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

@@ -12,22 +12,25 @@ let zod_v4 = require("zod/v4");
 /**
 * {@link DataSource}
 **/
-const dataSourceSchema = zod_v4.z.union([zod_v4.z.literal("onchain"), zod_v4.z.literal("offchain")]);
+const dataSourceSchema = zod_v4.z.enum(["onchain", "offchain"]);
 /**
 * {@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.
 **/
 const chainSucceededSchema = zod_v4.z.object({
 	chainId: require_model_primitives_schema.chainIdSchema,
 	status: zod_v4.z.literal("success"),
-	source: dataSourceSchema,
-	blockNumber: zod_v4.z.number().int().nonnegative().optional(),
-	timestamp: require_model_primitives_schema.timestampSchema.optional()
+	source: dataSourceSchema.default("offchain"),
+	blockNumber: zod_v4.z.number().int().nonnegative(),
+	timestamp: require_model_primitives_schema.timestampSchema
 });
 /**
 * {@link ChainFailed}
 *
-* `error` is a `string` on the wire. The schema accepts `unknown` so the same
-* codec also validates a locally produced envelope that carries an `Error`.
+* `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`.
 **/
 const chainFailedSchema = zod_v4.z.object({
 	chainId: require_model_primitives_schema.chainIdSchema,

package/dist/cjs/new-sdk/AbstractNamespace.js

@@ -1,158 +1,76 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sdk_chain_chains = require("../sdk/chain/chains.js");
-const require_new_sdk_types = require("./types.js");
+const require_new_sdk_errors_AllSourcesFailedError = require("./errors/AllSourcesFailedError.js");
+const require_new_sdk_errors_everyChainFailed = require("./errors/everyChainFailed.js");
+const require_new_sdk_errors_SourceUnavailableError = require("./errors/SourceUnavailableError.js");
+require("./errors/index.js");
 //#region src/new-sdk/AbstractNamespace.ts
 /**
-* Shared machinery of every {@link GearboxSDK} namespace.
+* Base class of every {@link GearboxSDK} namespace: holds the two source
+* namespaces, exposes each on its own, and runs merged reads over both.
 *
-* A namespace is a stateless router: it asks the sources its mode allows, in
-* parallel, merges what came back and reports what did not. This class owns
-* that routing — per-chain failure capture, backend degradation, the response
-* envelope and the all-sources-failed rule — so a namespace holds nothing but
-* its reads and its merge policy.
-*
-* The sources are whatever it was handed, and their readiness is their owner's
-* business: a source that is not ready to answer fails the read it was given,
-* and that failure is reported like any other.
-*
-* All protocol knowledge lives in the sources: `MultichainSDK` for the chain,
-* `GearboxAPI` for the backend. None of it is repeated here or in a subclass.
-*
-* @typeParam ListRow - Row type of the namespace's list read.
+* @typeParam Onchain - On-chain source namespace, e.g.
+*   `MultichainOpportunitiesService`.
+* @typeParam Offchain - Backend source namespace, e.g. `OffchainOpportunities`.
 **/
 var AbstractNamespace = class {
+	/**
+	* How far the backend may lag the chain and still serve a chain.
+	**/
+	maxOffchainLagSeconds;
 	logger;
+	#name;
 	#onchain;
 	#offchain;
-	constructor(name, onchain, offchain, logger) {
+	constructor(name, onchain, offchain, options) {
+		this.#name = name;
 		this.#onchain = onchain;
 		this.#offchain = offchain;
-		this.logger = logger?.child?.({ name }) ?? logger;
-	}
-	/**
-	* Asks both sources in parallel and combines whatever answered.
-	*
-	* The action name is only used in diagnostics and in the error raised when
-	* every source the read had failed.
-	**/
-	async read(action, fromChain, fromBackend, combine) {
-		const [onchain, offchain] = await Promise.all([this.fromChain(fromChain), this.fromBackend(fromBackend)]);
-		const meta = toMeta(onchain, offchain);
-		this.assertAnySourceSucceeded(action, meta);
-		return {
-			result: combine(onchain.value, offchain.value),
-			meta
-		};
-	}
-	/**
-	* Reads the namespace's list from both sources, unioned by
-	* {@link AbstractNamespace.mergeList}.
-	**/
-	async readList(action, fromChain, fromBackend) {
-		return this.read(action, fromChain, fromBackend, (onchain, offchain) => this.mergeList(onchain ?? [], offchain ?? []));
+		this.maxOffchainLagSeconds = options.maxOffchainLagSeconds;
+		this.logger = options.logger?.child?.({ name }) ?? options.logger;
 	}
 	/**
-	* Reads one row from both sources and merges them under
-	* {@link AbstractNamespace.mergeOne}. The key names the chain, so the
-	* on-chain leg queries exactly one.
+	* The on-chain source namespace on its own. Throws
+	* {@link SourceUnavailableError} in `offchain` mode.
 	**/
-	async readOne(action, chainId, fromChain, fromBackend) {
-		return this.read(action, async (sdk) => {
-			const network = this.networkOf(chainId);
-			if (!network) return { chains: [] };
-			return this.onOneChain(action, network, () => fromChain(sdk));
-		}, fromBackend, (onchain, offchain) => {
-			if (onchain && offchain) return this.mergeOne(onchain, offchain);
-			return onchain ?? offchain;
-		});
+	get onchain() {
+		if (!this.#onchain) throw new require_new_sdk_errors_SourceUnavailableError.SourceUnavailableError(this.#name, "onchain");
+		return this.#onchain;
 	}
 	/**
-	* Reads something only the backend can answer.
-	*
-	* The fallback stands in for a backend that answered with nothing, which is
-	* a different thing from a backend that failed and was dropped.
+	* The backend source namespace on its own. Throws
+	* {@link SourceUnavailableError} in `onchain` mode.
 	**/
-	async readOffchain(action, fromBackend, fallback) {
-		const offchain = await this.fromBackend(fromBackend);
-		const meta = toMeta({ chains: [] }, offchain);
-		this.assertAnySourceSucceeded(action, meta);
-		return {
-			result: offchain.value ?? fallback,
-			meta
-		};
+	get offchain() {
+		if (!this.#offchain) throw new require_new_sdk_errors_SourceUnavailableError.SourceUnavailableError(this.#name, "offchain");
+		return this.#offchain;
 	}
 	/**
-	* Runs a read against the chain, or reports the chain as absent when the
-	* namespace has no on-chain source at all.
+	* Asks both sources at once and merges what came back, failing only when no
+	* chain was served at all.
 	**/
-	async fromChain(run) {
-		return this.#onchain ? run(this.#onchain) : { chains: [] };
+	async merged(action, query) {
+		const onchain = this.#onchain;
+		const offchain = this.#offchain;
+		const [fromChain, fromBackend] = await Promise.all([this.#ask(action, "onchain", onchain, query.fromChain), this.#ask(action, "offchain", offchain, query.fromBackend)]);
+		const merged = query.merge(fromChain.response, fromBackend.response);
+		if (merged && !require_new_sdk_errors_everyChainFailed.everyChainFailed(merged.meta)) return merged;
+		const sole = onchain && offchain ? void 0 : fromChain.error ?? fromBackend.error;
+		if (sole !== void 0) throw sole;
+		throw new require_new_sdk_errors_AllSourcesFailedError.AllSourcesFailedError(action, [fromChain.error, fromBackend.error], merged?.meta);
 	}
 	/**
-	* Runs a read against the backend, turning any rejection into metadata so
-	* that a dead backend degrades a `both`-mode read instead of failing it.
+	* Runs one source's leg of a read, skipping a source this mode does not have
+	* and turning a rejection into an outcome.
 	**/
-	async fromBackend(run) {
-		if (!this.#offchain) return {};
+	async #ask(action, label, source, run) {
+		if (source === void 0) return {};
 		try {
-			const { result, meta } = await run(this.#offchain);
-			return {
-				value: meta.status === "success" ? result : void 0,
-				status: meta
-			};
+			return { response: await run(source) };
 		} catch (error) {
-			this.logger?.warn(error, "offchain read failed");
-			return { status: {
-				status: "error",
-				error
-			} };
-		}
-	}
-	/**
-	* Runs a read against one chain, turning a rejection into that chain's
-	* metadata entry.
-	**/
-	async onOneChain(action, network, run) {
-		try {
-			return {
-				value: await run(),
-				chains: [{
-					network,
-					status: "success"
-				}]
-			};
-		} catch (error) {
-			this.logger?.warn(error, `failed to ${action} on ${network}`);
-			return { chains: [{
-				network,
-				status: "error",
-				error
-			}] };
-		}
-	}
-	/**
-	* A read that reached at least one source returns what it has; a read where
-	* every source it had failed throws, because an empty result would otherwise
-	* be indistinguishable from "there is nothing here".
-	**/
-	assertAnySourceSucceeded(action, meta) {
-		const asked = meta.chains.length > 0 || meta.offchain !== void 0;
-		const answered = meta.chains.some((c) => c.status === "success") || meta.offchain?.status === "success";
-		if (asked && !answered) throw new require_new_sdk_types.AllSourcesFailedError(action, meta);
-	}
-	networkOf(chainId) {
-		try {
-			return require_sdk_chain_chains.getNetworkType(chainId);
-		} catch {
-			this.logger?.debug(`chain ${chainId} is not a Gearbox network, skipping the onchain source`);
-			return;
+			this.logger?.warn(error, `failed to ${action} from the ${label} source`);
+			return { error };
 		}
 	}
 };
-function toMeta(onchain, offchain) {
-	const meta = { chains: onchain.chains };
-	if (offchain.status) meta.offchain = offchain.status;
-	return meta;
-}
 //#endregion
 exports.AbstractNamespace = AbstractNamespace;

package/dist/cjs/new-sdk/GearboxSDK.js

@@ -1,20 +1,23 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_sdk_chain_chains = require("../sdk/chain/chains.js");
 const require_sdk_MultichainSDK = require("../sdk/MultichainSDK.js");
 require("../sdk/index.js");
+const require_new_sdk_errors_assertSameChains = require("./errors/assertSameChains.js");
+const require_new_sdk_errors_MissingSourceError = require("./errors/MissingSourceError.js");
+require("./errors/index.js");
 const require_offchain_GearboxAPI = require("../offchain/GearboxAPI.js");
 require("../offchain/index.js");
+require("./utils/mergeChains.js");
+require("./utils/index.js");
 const require_new_sdk_opportunities_OpportunitiesNamespace = require("./opportunities/OpportunitiesNamespace.js");
 require("./opportunities/index.js");
 const require_new_sdk_positions_PositionsNamespace = require("./positions/PositionsNamespace.js");
 require("./positions/index.js");
 //#region src/new-sdk/GearboxSDK.ts
 /**
-* Combined entry point over both sources of Gearbox data: the chain and the
-* Gearbox backend.
-*
-* The {@link Mode} is fixed at construction and decides which methods exist,
-* not what they return, so a screen written against `both` cannot silently
-* degrade to a subset when someone reconfigures the SDK:
+* Entry point over both sources of Gearbox data: the chain and the Gearbox
+* backend. The {@link Mode} is fixed at construction and decides which methods
+* exist.
 *
 * ```ts
 * const sdk = new GearboxSDK({
@@ -25,13 +28,9 @@ require("./positions/index.js");
 * });
 * await sdk.attach();
 *
-* const { result, meta } = await sdk.opportunities.list({ kind: "strategy" });
+* const { data, meta } = await sdk.opportunities.list({ kind: "strategy" });
 * ```
 *
-* Every read answers with `{ result, meta }`: `meta` says which chains and
-* which backend answered, because a partial answer is the normal case for a
-* multi-chain read.
-*
 * @typeParam M - Mode the instance was built in.
 **/
 var GearboxSDK = class {
@@ -40,8 +39,7 @@ var GearboxSDK = class {
 	**/
 	mode;
 	/**
-	* Chains this instance covers. Authoritative even when an injected on-chain
-	* SDK covers a different set.
+	* Chains this instance covers, which every read is scoped to.
 	**/
 	networks;
 	/**
@@ -55,46 +53,51 @@ var GearboxSDK = class {
 	#attachOptions;
 	#onchain;
 	#offchain;
-	/**
-	* Whether this instance built the on-chain SDK, and therefore attaches it.
-	**/
 	#ownsOnchain = false;
 	#attached;
 	constructor(options) {
-		const { mode, networks, onchain, offchain, attach, logger } = options;
+		const { mode, networks, onchain, offchain, attach, logger, maxOffchainLagSeconds = 120 } = options;
 		this.mode = mode;
 		this.networks = [...networks];
 		this.#attachOptions = attach;
 		const needsOnchain = mode === "onchain" || mode === "both";
 		const needsOffchain = mode === "offchain" || mode === "both";
-		if (needsOnchain && !onchain) throw new Error(`GearboxSDK in ${mode} mode needs an onchain source`);
-		if (needsOffchain && !offchain) throw new Error(`GearboxSDK in ${mode} mode needs an offchain source`);
+		if (needsOnchain && !onchain) throw new require_new_sdk_errors_MissingSourceError.MissingSourceError(mode, "onchain");
+		if (needsOffchain && !offchain) throw new require_new_sdk_errors_MissingSourceError.MissingSourceError(mode, "offchain");
 		if (!needsOnchain && onchain) logger?.warn(`GearboxSDK in ${mode} mode ignores the onchain source it was given`);
 		if (!needsOffchain && offchain) logger?.warn(`GearboxSDK in ${mode} mode ignores the offchain source it was given`);
-		if (needsOnchain && onchain) if (onchain instanceof require_sdk_MultichainSDK.MultichainSDK) this.#onchain = onchain;
-		else {
-			this.#onchain = new require_sdk_MultichainSDK.MultichainSDK({
-				logger,
-				...onchain
-			});
-			this.#ownsOnchain = true;
+		const chainIds = require_sdk_chain_chains.toChainIds(networks);
+		if (needsOnchain && onchain) {
+			if (onchain instanceof require_sdk_MultichainSDK.MultichainSDK) this.#onchain = onchain;
+			else {
+				this.#onchain = new require_sdk_MultichainSDK.MultichainSDK({
+					logger,
+					...onchain,
+					chains: chainsOf(onchain.chains, networks)
+				});
+				this.#ownsOnchain = true;
+			}
+			require_new_sdk_errors_assertSameChains.assertSameChains("onchain", networks, [...this.#onchain.chains.keys()]);
 		}
-		if (needsOffchain && offchain) this.#offchain = offchain instanceof require_offchain_GearboxAPI.GearboxAPI ? offchain : new require_offchain_GearboxAPI.GearboxAPI({
+		if (needsOffchain && offchain) if (offchain instanceof require_offchain_GearboxAPI.GearboxAPI) {
+			require_new_sdk_errors_assertSameChains.assertSameChains("offchain", chainIds, offchain.chainIds);
+			this.#offchain = offchain;
+		} else this.#offchain = new require_offchain_GearboxAPI.GearboxAPI({
 			logger,
-			...offchain
+			...offchain,
+			chainIds
 		});
 		this.#attached = !this.#ownsOnchain;
-		this.opportunities = new require_new_sdk_opportunities_OpportunitiesNamespace.OpportunitiesNamespace(this.#onchain, this.#offchain, logger);
-		this.positions = new require_new_sdk_positions_PositionsNamespace.PositionsNamespace(this.#onchain, this.#offchain, logger);
+		const namespaceOptions = {
+			maxOffchainLagSeconds,
+			logger
+		};
+		this.opportunities = new require_new_sdk_opportunities_OpportunitiesNamespace.OpportunitiesNamespace(this.#onchain, this.#offchain, namespaceOptions);
+		this.positions = new require_new_sdk_positions_PositionsNamespace.PositionsNamespace(this.#onchain, this.#offchain, namespaceOptions);
 	}
 	/**
-	* Attaches the on-chain SDK when this instance owns one.
-	*
-	* Reads issued before this resolves still reach the chain and fail there, so
-	* in `both` mode they are served from the backend alone and report the chain
-	* as failed in their meta, rather than blocking.
-	*
-	* A no-op in `offchain` mode and when an already-attached SDK was injected.
+	* Attaches the on-chain SDK when this instance owns one; a no-op in `offchain`
+	* mode and when an already-attached SDK was injected.
 	**/
 	async attach() {
 		if (this.#attached || !this.#ownsOnchain || !this.#onchain) return;
@@ -103,17 +106,15 @@ var GearboxSDK = class {
 	}
 	/**
 	* Whether the on-chain source is ready to be read from. Always `true` in
-	* `offchain` mode, where there is nothing to wait for.
+	* `offchain` mode.
 	**/
 	get attached() {
 		return this.mode === "offchain" ? true : this.#attached;
 	}
 	/**
 	* The underlying on-chain SDK, for everything this facade does not expose
-	* yet: markets, credit accounts, transaction building.
-	*
-	* `undefined` in `offchain` mode. Otherwise it exists from construction on,
-	* but only answers reads once {@link attach} has resolved.
+	* yet: markets, credit accounts, transaction building. `undefined` in
+	* `offchain` mode, and only answers reads once {@link attach} has resolved.
 	**/
 	get onchain() {
 		return this.#onchain;
@@ -125,5 +126,17 @@ var GearboxSDK = class {
 		return this.#offchain;
 	}
 };
+/**
+* Per-chain configuration of exactly the networks the SDK covers.
+**/
+function chainsOf(configured, networks) {
+	const chains = {};
+	for (const network of networks) {
+		const chain = configured[network];
+		if (!chain) throw new Error(`GearboxSDK covers ${network}, but its onchain source has no configuration for it`);
+		chains[network] = chain;
+	}
+	return chains;
+}
 //#endregion
 exports.GearboxSDK = GearboxSDK;

package/dist/cjs/new-sdk/errors/AllSourcesFailedError.js

@@ -0,0 +1,20 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/new-sdk/errors/AllSourcesFailedError.ts
+/**
+* Thrown when a read had sources to ask and none of them served a single chain.
+**/
+var AllSourcesFailedError = class extends AggregateError {
+	constructor(action, sourceErrors, meta) {
+		const causes = [...sourceErrors, ...chainErrors(meta)].filter((reason) => reason !== void 0);
+		super(causes, `cannot ${action}, every source failed (${causes.join("; ")})`);
+		this.name = "AllSourcesFailedError";
+	}
+};
+/**
+* Why each chain a merged envelope did report failed.
+**/
+function chainErrors(meta) {
+	return (meta?.chains ?? []).map((chain) => chain.status === "error" ? chain.error : void 0);
+}
+//#endregion
+exports.AllSourcesFailedError = AllSourcesFailedError;

package/dist/cjs/new-sdk/errors/MissingSourceError.js

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let viem = require("viem");
+//#region src/new-sdk/errors/MissingSourceError.ts
+/**
+* Thrown at construction when a {@link GearboxSDK} was not given a source its
+* {@link Mode} reads from.
+**/
+var MissingSourceError = class extends viem.BaseError {
+	name = "MissingSourceError";
+	/**
+	* Mode the SDK was built in.
+	**/
+	mode;
+	/**
+	* Source that mode needs and did not get.
+	**/
+	source;
+	constructor(mode, source) {
+		super(`A GearboxSDK in ${mode} mode needs an ${source} source.`);
+		this.mode = mode;
+		this.source = source;
+	}
+};
+//#endregion
+exports.MissingSourceError = MissingSourceError;