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

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

@@ -1,5 +1,6 @@
 import { ZodAddress } from "../sdk/utils/zod.js";
-import { filterable } from "./filters.schema.js";
+import { isFilterSet } from "./filters.js";
+import { booleanParamSchema, encodeFlag, filterable } from "./filters.schema.js";
 import { assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, tokenAmountSchema, tokenSchema } from "./primitives.schema.js";
 import { apyBreakdownSchema, pointsProgramSchema } from "./opportunities.schema.js";
 import { delayedReceivedAssetSchema, liquidationPositionSchema } from "./liquidations.schema.js";
@@ -103,10 +104,39 @@ const positionSchema = z.discriminatedUnion("kind", [
 const positionFilterSchema = z.object({
 	kind: filterable(positionKindSchema).optional(),
 	isZeroDebt: filterable(z.boolean()).optional(),
-	chainIds: filterable(z.array(chainIdSchema)).optional(),
+	chainIds: z.array(chainIdSchema).optional(),
 	underlyingType: filterable(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 = z.object({
+	kind: positionKindSchema.optional(),
+	isZeroDebt: booleanParamSchema.optional(),
+	chainIds: z.string().regex(/^$|^\d+(,\d+)*$/).optional(),
+	underlyingType: assetTypeSchema.optional()
+});
+/**
+* Code for {@link PositionFilter} to encode/decode to/from url query parameters.
+**/
+const positionFilterQuerySchema = 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: isFilterSet(filter.kind) ? filter.kind : void 0,
+		isZeroDebt: encodeFlag(filter.isZeroDebt),
+		chainIds: filter.chainIds?.join(","),
+		underlyingType: isFilterSet(filter.underlyingType) ? filter.underlyingType : void 0
+	})
+});
+/**
 * {@link PoolPositionKey}
 **/
 const poolPositionKeySchema = z.object({
@@ -132,4 +162,4 @@ const positionKeySchema = z.discriminatedUnion("kind", [z.object({
 	...strategyPositionKeySchema.shape
 })]);
 //#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/esm/model/response.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,58 @@
+import { chainIdSchema, timestampSchema } from "./primitives.schema.js";
+import { z } from "zod/v4";
+//#region src/model/response.schema.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}
+**/
+const dataSourceSchema = 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 = z.object({
+	chainId: chainIdSchema,
+	status: z.literal("success"),
+	source: dataSourceSchema.default("offchain"),
+	blockNumber: z.number().int().nonnegative(),
+	timestamp: timestampSchema
+});
+/**
+* {@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`.
+**/
+const chainFailedSchema = z.object({
+	chainId: chainIdSchema,
+	status: z.literal("error"),
+	source: dataSourceSchema.optional(),
+	error: z.unknown().optional()
+});
+/**
+* {@link ChainMetadata}
+**/
+const chainMetadataSchema = z.discriminatedUnion("status", [chainSucceededSchema, chainFailedSchema]);
+/**
+* {@link ResponseMetadata}
+**/
+const responseMetadataSchema = z.object({ chains: z.array(chainMetadataSchema) });
+/**
+* {@link DataResponse} parameterized by the payload schema.
+**/
+function responseSchema(payloadSchema) {
+	return z.object({
+		data: payloadSchema,
+		meta: responseMetadataSchema
+	});
+}
+//#endregion
+export { chainFailedSchema, chainMetadataSchema, chainSucceededSchema, dataSourceSchema, responseMetadataSchema, responseSchema };

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

@@ -1,157 +1,75 @@
-import { getNetworkType } from "../sdk/chain/chains.js";
-import { AllSourcesFailedError } from "./types.js";
+import { AllSourcesFailedError } from "./errors/AllSourcesFailedError.js";
+import { everyChainFailed } from "./errors/everyChainFailed.js";
+import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
+import "./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 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 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 && !everyChainFailed(merged.meta)) return merged;
+		const sole = onchain && offchain ? void 0 : fromChain.error ?? fromBackend.error;
+		if (sole !== void 0) throw sole;
+		throw new 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 AllSourcesFailedError(action, meta);
-	}
-	networkOf(chainId) {
-		try {
-			return 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
 export { AbstractNamespace };

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

@@ -1,19 +1,22 @@
+import { toChainIds } from "../sdk/chain/chains.js";
 import { MultichainSDK } from "../sdk/MultichainSDK.js";
 import "../sdk/index.js";
+import { assertSameChains } from "./errors/assertSameChains.js";
+import { MissingSourceError } from "./errors/MissingSourceError.js";
+import "./errors/index.js";
 import { GearboxAPI } from "../offchain/GearboxAPI.js";
 import "../offchain/index.js";
+import "./utils/mergeChains.js";
+import "./utils/index.js";
 import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
 import "./opportunities/index.js";
 import { PositionsNamespace } from "./positions/PositionsNamespace.js";
 import "./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({
@@ -24,13 +27,9 @@ import "./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 {
@@ -39,8 +38,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;
 	/**
@@ -54,46 +52,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 MissingSourceError(mode, "onchain");
+		if (needsOffchain && !offchain) throw new 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 MultichainSDK) this.#onchain = onchain;
-		else {
-			this.#onchain = new MultichainSDK({
-				logger,
-				...onchain
-			});
-			this.#ownsOnchain = true;
+		const chainIds = toChainIds(networks);
+		if (needsOnchain && onchain) {
+			if (onchain instanceof MultichainSDK) this.#onchain = onchain;
+			else {
+				this.#onchain = new MultichainSDK({
+					logger,
+					...onchain,
+					chains: chainsOf(onchain.chains, networks)
+				});
+				this.#ownsOnchain = true;
+			}
+			assertSameChains("onchain", networks, [...this.#onchain.chains.keys()]);
 		}
-		if (needsOffchain && offchain) this.#offchain = offchain instanceof GearboxAPI ? offchain : new GearboxAPI({
+		if (needsOffchain && offchain) if (offchain instanceof GearboxAPI) {
+			assertSameChains("offchain", chainIds, offchain.chainIds);
+			this.#offchain = offchain;
+		} else this.#offchain = new GearboxAPI({
 			logger,
-			...offchain
+			...offchain,
+			chainIds
 		});
 		this.#attached = !this.#ownsOnchain;
-		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, logger);
-		this.positions = new PositionsNamespace(this.#onchain, this.#offchain, logger);
+		const namespaceOptions = {
+			maxOffchainLagSeconds,
+			logger
+		};
+		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, namespaceOptions);
+		this.positions = new 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;
@@ -102,17 +105,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;
@@ -124,5 +125,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
 export { GearboxSDK };

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

@@ -0,0 +1,19 @@
+//#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
+export { AllSourcesFailedError };

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

@@ -0,0 +1,24 @@
+import { BaseError } from "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 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
+export { MissingSourceError };

package/dist/esm/new-sdk/errors/NoSourceServedError.js

@@ -0,0 +1,19 @@
+//#region src/new-sdk/errors/NoSourceServedError.ts
+/**
+* The failure of a chain no source served. It is reported in that chain's
+* metadata entry rather than thrown: the other chains of the same read may
+* still have been served.
+**/
+var NoSourceServedError = class extends AggregateError {
+	/**
+	* Chain no source served.
+	**/
+	chainId;
+	constructor(chainId, reasons) {
+		super(reasons, `no source could serve chain ${chainId}`);
+		this.name = "NoSourceServedError";
+		this.chainId = chainId;
+	}
+};
+//#endregion
+export { NoSourceServedError };

package/dist/esm/new-sdk/errors/SourceChainMismatchError.js

@@ -0,0 +1,33 @@
+import { BaseError } from "viem";
+//#region src/new-sdk/errors/SourceChainMismatchError.ts
+/**
+* Thrown at construction when a source covers anything other than exactly the
+* chains a {@link GearboxSDK} was built for, see
+* {@link GearboxSDKOptions.networks}.
+**/
+var SourceChainMismatchError = class extends BaseError {
+	name = "SourceChainMismatchError";
+	/**
+	* Source whose coverage does not match.
+	**/
+	source;
+	/**
+	* Chains the SDK covers.
+	**/
+	expected;
+	/**
+	* Chains the source covers.
+	**/
+	covered;
+	constructor(source, expected, covered) {
+		super(`The ${source} source does not cover the chains this GearboxSDK was built for.`, { metaMessages: [`Expected: ${named(expected)}`, `Covered: ${named(covered)}`] });
+		this.source = source;
+		this.expected = [...expected];
+		this.covered = [...covered];
+	}
+};
+function named(chains) {
+	return chains.join(", ") || "no chain";
+}
+//#endregion
+export { SourceChainMismatchError };

package/dist/esm/new-sdk/errors/SourceUnavailableError.js

@@ -0,0 +1,24 @@
+import { BaseError } from "viem";
+//#region src/new-sdk/errors/SourceUnavailableError.ts
+/**
+* Thrown when a source branch of a namespace is read in a mode that has no such
+* source, e.g. `sdk.opportunities.onchain` in `offchain` mode.
+**/
+var SourceUnavailableError = class extends BaseError {
+	name = "SourceUnavailableError";
+	/**
+	* Namespace whose branch was read.
+	**/
+	namespace;
+	/**
+	* Source this mode does not read.
+	**/
+	source;
+	constructor(namespace, source) {
+		super(`The ${namespace} namespace has no ${source} source in this mode.`);
+		this.namespace = namespace;
+		this.source = source;
+	}
+};
+//#endregion
+export { SourceUnavailableError };

package/dist/esm/new-sdk/errors/assertSameChains.js

@@ -0,0 +1,11 @@
+import { SourceChainMismatchError } from "./SourceChainMismatchError.js";
+//#region src/new-sdk/errors/assertSameChains.ts
+/**
+* Rejects a source covering anything other than exactly the chains the SDK was
+* built for. A source is not narrowed to them: it has to name them.
+**/
+function assertSameChains(source, expected, covered) {
+	if (covered.length !== expected.length || covered.some((chain) => !expected.includes(chain))) throw new SourceChainMismatchError(source, expected, covered);
+}
+//#endregion
+export { assertSameChains };

package/dist/esm/new-sdk/errors/everyChainFailed.js

@@ -0,0 +1,10 @@
+//#region src/new-sdk/errors/everyChainFailed.ts
+/**
+* Whether a merged envelope covered chains and lost every one of them, which is
+* what makes a read a failure rather than a partial result.
+**/
+function everyChainFailed(meta) {
+	return meta.chains.length > 0 && meta.chains.every((chain) => chain.status === "error");
+}
+//#endregion
+export { everyChainFailed };

package/dist/esm/new-sdk/errors/index.js

@@ -0,0 +1,8 @@
+import { AllSourcesFailedError } from "./AllSourcesFailedError.js";
+import { SourceChainMismatchError } from "./SourceChainMismatchError.js";
+import { assertSameChains } from "./assertSameChains.js";
+import { everyChainFailed } from "./everyChainFailed.js";
+import { MissingSourceError } from "./MissingSourceError.js";
+import { NoSourceServedError } from "./NoSourceServedError.js";
+import { SourceUnavailableError } from "./SourceUnavailableError.js";
+export { AllSourcesFailedError, MissingSourceError, NoSourceServedError, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed };