@gearbox-protocol/sdk 15.1.0-next.1 → 15.1.0-next.10

package/dist/esm/model/index.js

@@ -1,17 +1,19 @@
+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 { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema } from "./primitives.schema.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 { FILTER_ALL, isFilterSet } from "./filters.js";
 import { booleanParamSchema, encodeFlag, filterAllSchema, filterable } from "./filters.schema.js";
-import { POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS } from "./history.js";
-import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema } from "./primitives.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 { delayedReceivedAssetSchema, instantReceivedAssetSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, receivedAssetSchema } from "./liquidations.schema.js";
-import { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
-import { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, poolPositionHistoryMetricSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, strategyHistoryMetricSchema, strategyPositionHistoryMetricSchema } from "./history.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, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
 import { 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, tokenRewardsPnLSchema } from "./positions.schema.js";
 import "./primitives.js";
 import "./response.js";
 import { chainFailedSchema, chainMetadataSchema, chainSucceededSchema, dataSourceSchema, responseMetadataSchema, responseSchema } from "./response.schema.js";
-export { FILTER_ALL, POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS, 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 };
+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, amountSchema, apyBreakdownSchema, assetTypeSchema, booleanParamSchema, borrowRateBreakdownSchema, bpsSchema, chainFailedSchema, chainIdSchema, chainMetadataSchema, chainSucceededSchema, chartBundleSchemaFor, chartDenominationSchema, chartMetricSchema, chartQueryCodec, chartQueryParamsSchema, chartQuerySchema, chartRangeSchema, chartSeriesSchema, chartValueSchema, chartWindowSchema, curatorNameSchema, curatorSchema, dataSourceSchema, delayedReceivedAssetSchema, encodeFlag, filterAllSchema, filterable, instantReceivedAssetSchema, isFilterSet, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, noticeKindSchema, noticeSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolOpportunityChartMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionChartMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionId, positionKeySchema, positionKindSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionsTotalsSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, responseMetadataSchema, responseSchema, rewardsPnLSchema, rewardsSchema, strategyOpportunityChartMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionChartMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, txCallSchema };

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

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

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

@@ -0,0 +1,23 @@
+import { tokenSchema } from "./primitives.schema.js";
+import { z } from "zod/v4";
+//#region src/model/notices.schema.ts
+/**
+* {@link NoticeKind}
+**/
+const noticeKindSchema = z.union([
+	z.literal("expired"),
+	z.literal("externalRewards"),
+	z.literal("extraApy"),
+	z.literal("warning"),
+	z.literal("disclaimer")
+]);
+/**
+* {@link Notice}
+**/
+const noticeSchema = z.object({
+	kind: noticeKindSchema,
+	message: z.string(),
+	token: tokenSchema.optional()
+});
+//#endregion
+export { noticeKindSchema, noticeSchema };

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

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

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

@@ -1,9 +1,9 @@
-import { ZodAddress } from "../sdk/utils/zod.js";
+import { ZodAddress, ZodBigInt, ZodHex } from "../sdk/utils/zod.js";
+import { assetTypeSchema, bpsSchema, chainIdSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema } from "./primitives.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";
+import { apyBreakdownSchema, pointsProgramSchema } from "./opportunities.schema.js";
 import { z } from "zod/v4";
 //#region src/model/positions.schema.ts
 /**
@@ -72,6 +72,15 @@ const poolPositionSchema = z.object({
 	pnl: pnlBreakdownSchema.optional()
 });
 /**
+* {@link BorrowRateBreakdown}
+**/
+const borrowRateBreakdownSchema = z.object({
+	total: bpsSchema,
+	totalOnDebt: bpsSchema,
+	base: bpsSchema,
+	quotas: z.record(ZodAddress(), bpsSchema)
+});
+/**
 * {@link StrategyPosition}
 **/
 const strategyPositionSchema = z.object({
@@ -87,6 +96,9 @@ const strategyPositionSchema = z.object({
 	totalDebt: tokenAmountSchema,
 	totalValue: tokenAmountSchema,
 	healthFactor: bpsSchema,
+	borrowRate: borrowRateBreakdownSchema.optional(),
+	timeToLiquidation: ZodBigInt().nullable().optional(),
+	liquidationPrice: ZodBigInt().nullable().optional(),
 	pnl: pnlBreakdownSchema.optional(),
 	collaterals: z.array(positionCollateralSchema)
 });
@@ -161,5 +173,35 @@ const positionKeySchema = z.discriminatedUnion("kind", [z.object({
 	kind: z.literal("strategy"),
 	...strategyPositionKeySchema.shape
 })]);
+/**
+* {@link PositionsTotals}
+**/
+const positionsTotalsSchema = z.object({
+	currentYield: apyBreakdownSchema.nullable(),
+	pnl: pnlBreakdownSchema.nullable(),
+	netValueUsd: z.number().nullable(),
+	claimableUsd: z.number().nullable()
+});
+/**
+* {@link PositionTransactionKind}
+**/
+const positionTransactionKindSchema = z.union([
+	z.literal("open"),
+	z.literal("deposit"),
+	z.literal("withdraw"),
+	z.literal("adjustLeverage"),
+	z.literal("addCollateral"),
+	z.literal("withdrawCollateral"),
+	z.literal("liquidation")
+]);
+/**
+* {@link PositionTransaction}
+**/
+const positionTransactionSchema = z.object({
+	txHash: ZodHex(),
+	timestamp: timestampSchema,
+	kind: positionTransactionKindSchema,
+	assets: z.array(tokenAmountSchema)
+});
 //#endregion
-export { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema };
+export { borrowRateBreakdownSchema, pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterQueryParamsSchema, positionFilterQuerySchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, positionTransactionKindSchema, positionTransactionSchema, positionsTotalsSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema };

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

@@ -17,23 +17,34 @@ var AbstractNamespace = class {
 	**/
 	maxOffchainLagSeconds;
 	logger;
+	/**
+	* The SDK's loading policy, awaited before every on-chain leg: attached, and
+	* the touched chains no older than the SDK allows.
+	**/
+	ensureFresh;
 	#name;
 	#onchain;
 	#offchain;
+	/** {@link onchain}, built once: the source's methods behind the loading policy. */
+	#onchainView;
 	constructor(name, onchain, offchain, options) {
 		this.#name = name;
 		this.#onchain = onchain;
 		this.#offchain = offchain;
 		this.maxOffchainLagSeconds = options.maxOffchainLagSeconds;
+		this.ensureFresh = options.ensureFresh;
 		this.logger = options.logger?.child?.({ name }) ?? options.logger;
+		this.#onchainView = onchain && options.ensureFresh ? behindLoadingPolicy(onchain, options.ensureFresh) : onchain;
 	}
 	/**
-	* The on-chain source namespace on its own. Throws
+	* The on-chain source namespace on its own — every read of it attaches and
+	* revalidates like a merged read does, so a consumer showing the two sources
+	* separately still gets the SDK's loading policy. Throws
 	* {@link SourceUnavailableError} in `offchain` mode.
 	**/
 	get onchain() {
-		if (!this.#onchain) throw new SourceUnavailableError(this.#name, "onchain");
-		return this.#onchain;
+		if (!this.#onchainView) throw new SourceUnavailableError(this.#name, "onchain");
+		return this.#onchainView;
 	}
 	/**
 	* The backend source namespace on its own. Throws
@@ -50,7 +61,10 @@ var AbstractNamespace = class {
 	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 [fromChain, fromBackend] = await Promise.all([this.#ask(action, "onchain", onchain, async (source) => {
+			await this.ensureFresh?.(query.chainIds);
+			return query.fromChain(source);
+		}), 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;
@@ -71,5 +85,21 @@ var AbstractNamespace = class {
 		}
 	}
 };
+/**
+* The source's every method, awaiting the loading policy first. The policy is
+* asked for every chain — an escape hatch does not tell which chains a call
+* touches (the merged reads do, and scope it); the object identity differs
+* from the source's, its type does not.
+**/
+function behindLoadingPolicy(source, ensureFresh) {
+	return new Proxy(source, { get(target, property, receiver) {
+		const value = Reflect.get(target, property, receiver);
+		if (typeof value !== "function") return value;
+		return async (...args) => {
+			await ensureFresh();
+			return Reflect.apply(value, target, args);
+		};
+	} });
+}
 //#endregion
 export { AbstractNamespace };

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

@@ -14,6 +14,11 @@ import { PositionsNamespace } from "./positions/PositionsNamespace.js";
 import "./positions/index.js";
 //#region src/new-sdk/GearboxSDK.ts
 /**
+* Default {@link GearboxSDKOptions.maxStateAgeSeconds}: the fastest poll an
+* app runs, so a 30 s tick sees state no older than itself.
+**/
+const DEFAULT_MAX_STATE_AGE = 30;
+/**
 * 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.
@@ -53,12 +58,27 @@ var GearboxSDK = class {
 	#onchain;
 	#offchain;
 	#ownsOnchain = false;
+	#maxStateAgeSeconds;
+	#logger;
+	/**
+	* The banners the backend attaches to a pool opportunity or a strategy
+	* position, see {@link Notice}. Top-level because the subject is either
+	* kind of entity, so neither namespace owns it. Backend-only, hence gated
+	* by mode like every other backend read: absent in `onchain` mode.
+	**/
+	notices;
 	#attached;
+	/** The one attach in flight, shared by {@link attach} and every first read. */
+	#attaching;
+	/** One sync in flight per chain: concurrent stale reads join it. */
+	#syncing = /* @__PURE__ */ new Map();
 	constructor(options) {
-		const { mode, networks, onchain, offchain, attach, logger, maxOffchainLagSeconds = 120 } = options;
+		const { mode, networks, onchain, offchain, attach, logger, maxOffchainLagSeconds = 120, maxStateAgeSeconds = 30 } = options;
 		this.mode = mode;
 		this.networks = [...networks];
 		this.#attachOptions = attach;
+		this.#maxStateAgeSeconds = maxStateAgeSeconds;
+		this.#logger = logger;
 		const needsOnchain = mode === "onchain" || mode === "both";
 		const needsOffchain = mode === "offchain" || mode === "both";
 		if (needsOnchain && !onchain) throw new MissingSourceError(mode, "onchain");
@@ -91,19 +111,67 @@ var GearboxSDK = class {
 		this.#attached = !this.#ownsOnchain;
 		const namespaceOptions = {
 			maxOffchainLagSeconds,
+			ensureFresh: this.#onchain ? (chainIds) => this.#ensureFresh(chainIds) : void 0,
 			logger
 		};
 		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, namespaceOptions);
 		this.positions = new PositionsNamespace(this.#onchain, this.#offchain, namespaceOptions);
+		const backend = this.#offchain;
+		this.notices = backend ? (subject) => backend.notices.list(subject) : void 0;
 	}
 	/**
 	* 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() {
+		return this.#ensureAttached();
+	}
+	/**
+	* The attach every async read awaits: the first caller starts it, later
+	* ones join the same promise; a rejected attach is not cached, so the next
+	* read retries.
+	**/
+	async #ensureAttached() {
 		if (this.#attached || !this.#ownsOnchain || !this.#onchain) return;
-		await this.#onchain.attach(this.#attachOptions);
-		this.#attached = true;
+		if (!this.#attaching) {
+			const onchain = this.#onchain;
+			this.#attaching = onchain.attach(this.#attachOptions).then(() => {
+				this.#attached = true;
+			}).finally(() => {
+				this.#attaching = void 0;
+			});
+		}
+		return this.#attaching;
+	}
+	/**
+	* What every on-chain leg of an async read awaits: the source attached, and
+	* the chains the read touches (all of them when unnamed) synced when their
+	* loaded state is older than `maxStateAgeSeconds`. A sync that fails leaves
+	* the previous state to be served — its age tells the consumer it is stale.
+	**/
+	async #ensureFresh(chainIds) {
+		await this.#ensureAttached();
+		const onchain = this.#onchain;
+		if (!onchain) return;
+		const wanted = chainIds && new Set(chainIds);
+		const stale = [];
+		const now = Math.floor(Date.now() / 1e3);
+		for (const chain of onchain.chains.values()) {
+			if (wanted && !wanted.has(chain.chainId)) continue;
+			if (now - Number(chain.timestamp) > this.#maxStateAgeSeconds) stale.push(chain);
+		}
+		await Promise.all(stale.map((chain) => this.#sync(chain)));
+	}
+	#sync(chain) {
+		const inFlight = this.#syncing.get(chain.chainId);
+		if (inFlight) return inFlight;
+		const sync = chain.syncState().then(() => void 0).catch((error) => {
+			this.#logger?.warn(error, `failed to sync chain ${chain.chainId}; serving state of block ${chain.currentBlock}`);
+		}).finally(() => {
+			this.#syncing.delete(chain.chainId);
+		});
+		this.#syncing.set(chain.chainId, sync);
+		return sync;
 	}
 	/**
 	* Whether the on-chain source is ready to be read from. Always `true` in
@@ -140,4 +208,4 @@ function chainsOf(configured, networks) {
 	return chains;
 }
 //#endregion
-export { GearboxSDK };
+export { DEFAULT_MAX_STATE_AGE, GearboxSDK };

package/dist/esm/new-sdk/execute/ExecuteApi.js

@@ -0,0 +1,94 @@
+//#region src/new-sdk/execute/ExecuteApi.ts
+/**
+* {@inheritDoc OpportunitiesExecute}
+**/
+var ExecuteApi = class {
+	#chainOf;
+	constructor(chainOf) {
+		this.#chainOf = chainOf;
+	}
+	/**
+	* {@inheritDoc OpportunitiesExecute.buildTx}
+	**/
+	async buildTx(request) {
+		if (!request.sim.ok) throw new Error(`cannot build a transaction from a failed ${request.kind} simulation`);
+		const sdk = this.#chainOf(request.chainId);
+		switch (request.kind) {
+			case "pool": return poolTx(sdk, request);
+			case "open": return openTx(sdk, request);
+			case "account": return accountTx(sdk, request);
+		}
+	}
+};
+function poolTx(sdk, request) {
+	const { pool, wallet, sim } = request;
+	const { tokenIn, tokenOut } = sim.preview;
+	if (request.op === "deposit") {
+		const meta = sdk.pools.getDepositMetadata(pool, tokenIn.token, tokenOut.token);
+		const result = sdk.pools.addLiquidity({
+			pool,
+			wallet,
+			collateral: tokenIn,
+			meta
+		});
+		if (!result) throw new Error(`pool ${pool} takes no deposit transaction for ${tokenIn.token} (${meta.type})`);
+		return result.tx;
+	}
+	const meta = sdk.pools.getWithdrawalMetadata(pool, tokenIn.token, tokenOut.token);
+	return sdk.pools.removeLiquidity({
+		pool,
+		wallet,
+		amount: request.op === "withdraw" ? tokenOut.balance : tokenIn.balance,
+		permit: void 0,
+		meta,
+		mode: request.op === "withdraw" ? "withdraw" : "redeem"
+	}).tx;
+}
+async function openTx(sdk, request) {
+	const { creditManager, wallet, collateral, ethAmount, sim } = request;
+	const { preview } = sim;
+	return sdk.accounts.openCA({
+		creditManager,
+		to: wallet,
+		collateral,
+		ethAmount,
+		debt: preview.debt,
+		calls: preview.calls,
+		averageQuota: preview.averageQuota,
+		minQuota: preview.minQuota,
+		permits: {},
+		referralCode: 0n,
+		rwaOptions: await openRwaOptions(sdk, request)
+	});
+}
+/**
+* The documented `openCA` contract: ask the market for its open requirements
+* and hand them back as operation args, with the caller's cached signatures
+* attached. `undefined` on non-RWA markets and when no target token is named.
+**/
+async function openRwaOptions(sdk, request) {
+	if (!request.targetToken) return;
+	const requirements = await sdk.accounts.getOpenAccountRequirements(request.wallet, request.creditManager, { tokenOutAddress: request.targetToken });
+	if (!requirements) return;
+	return {
+		type: requirements.type,
+		tokensToRegister: requirements.tokensToRegister,
+		signaturesToCache: request.signaturesToCache ?? []
+	};
+}
+async function accountTx(sdk, request) {
+	const account = await sdk.accounts.getCreditAccountData(request.creditAccount);
+	if (!account) throw new Error(`credit account not found: ${request.creditAccount}`);
+	return sdk.accounts.executeCaUpdate(account, request.sim.calls, { ethAmount: nativeValue(request.sim.operations) });
+}
+/**
+* The coin the simulation asked the wallet for, which the facade wraps out of
+* `msg.value` before running the multicall. Taken off the collateral step that
+* recorded it rather than from the caller, so it cannot disagree with what was
+* simulated.
+**/
+function nativeValue(operations) {
+	return operations.reduce((total, op) => total + (op.type === "addCollateral" ? op.value ?? 0n : 0n), 0n);
+}
+//#endregion
+export { ExecuteApi };

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

@@ -0,0 +1,2 @@
+import { ExecuteApi } from "./ExecuteApi.js";
+export { ExecuteApi };

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

@@ -7,6 +7,10 @@ import { NoSourceServedError } from "./errors/NoSourceServedError.js";
 import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
 import "./errors/index.js";
 import { AbstractNamespace } from "./AbstractNamespace.js";
+import { ExecuteApi } from "./execute/ExecuteApi.js";
+import "./execute/index.js";
+import { SimulateApi } from "./simulate/SimulateApi.js";
+import "./simulate/index.js";
 import { filterResponse } from "./utils/filterResponse.js";
 import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./utils/mergeChains.js";
 import "./utils/index.js";
@@ -14,6 +18,6 @@ import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.j
 import "./opportunities/index.js";
 import { PositionsNamespace } from "./positions/PositionsNamespace.js";
 import "./positions/index.js";
-import { GearboxSDK } from "./GearboxSDK.js";
+import { DEFAULT_MAX_STATE_AGE, GearboxSDK } from "./GearboxSDK.js";
 import "./types.js";
-export { AbstractNamespace, AllSourcesFailedError, DEFAULT_MAX_OFFCHAIN_LAG, GearboxSDK, MissingSourceError, NoSourceServedError, OpportunitiesNamespace, PositionsNamespace, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };
+export { AbstractNamespace, AllSourcesFailedError, DEFAULT_MAX_OFFCHAIN_LAG, DEFAULT_MAX_STATE_AGE, ExecuteApi, GearboxSDK, MissingSourceError, NoSourceServedError, OpportunitiesNamespace, PositionsNamespace, SimulateApi, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };

package/dist/esm/new-sdk/opportunities/OpportunitiesNamespace.js

@@ -1,6 +1,12 @@
 import { matchesOpportunityFilter } from "../../model/opportunities.js";
 import "../../model/index.js";
+import { SourceUnavailableError } from "../errors/SourceUnavailableError.js";
+import "../errors/index.js";
 import { AbstractNamespace } from "../AbstractNamespace.js";
+import { ExecuteApi } from "../execute/ExecuteApi.js";
+import "../execute/index.js";
+import { SimulateApi } from "../simulate/SimulateApi.js";
+import "../simulate/index.js";
 import { filterResponse } from "../utils/filterResponse.js";
 import { mergeChainList, mergeChainOne } from "../utils/mergeChains.js";
 import "../utils/index.js";
@@ -18,14 +24,33 @@ var OpportunitiesNamespace = class extends AbstractNamespace {
 		pool: (onchain, offchain) => mergeChainOne(onchain, offchain, this.maxOffchainLagSeconds),
 		strategy: (onchain, offchain) => mergeChainOne(onchain, offchain, this.maxOffchainLagSeconds)
 	};
+	#simulate;
+	#execute;
 	constructor(onchain, offchain, options) {
 		super("Opportunities", onchain?.opportunities, offchain?.opportunities, options);
+		this.#simulate = onchain && new SimulateApi(onchain, options.ensureFresh);
+		this.#execute = onchain && new ExecuteApi((chainId) => onchain.chain(chainId));
+	}
+	/**
+	* {@inheritDoc OpportunitiesOnchainOnly.simulate}
+	**/
+	get simulate() {
+		if (!this.#simulate) throw new SourceUnavailableError("Opportunities", "onchain");
+		return this.#simulate;
+	}
+	/**
+	* {@inheritDoc OpportunitiesOnchainOnly.execute}
+	**/
+	get execute() {
+		if (!this.#execute) throw new SourceUnavailableError("Opportunities", "onchain");
+		return this.#execute;
 	}
 	/**
 	* {@inheritDoc OpportunitiesBase.list}
 	**/
 	async list(filter) {
 		return this.merged("list opportunities", {
+			chainIds: filter?.chainIds,
 			fromChain: (source) => source.list(filter),
 			fromBackend: (source) => source.list(filter),
 			merge: this.merge.list
@@ -36,6 +61,7 @@ var OpportunitiesNamespace = class extends AbstractNamespace {
 	**/
 	async getPool(key) {
 		return this.merged("get pool opportunity", {
+			chainIds: [key.chainId],
 			fromChain: (source) => source.getPool(key),
 			fromBackend: (source) => source.getPool(key),
 			merge: this.merge.pool
@@ -46,6 +72,7 @@ var OpportunitiesNamespace = class extends AbstractNamespace {
 	**/
 	async getStrategy(key) {
 		return this.merged("get strategy opportunity", {
+			chainIds: [key.chainId],
 			fromChain: (source) => source.getStrategy(key),
 			fromBackend: (source) => source.getStrategy(key),
 			merge: this.merge.strategy
@@ -57,12 +84,8 @@ var OpportunitiesNamespace = class extends AbstractNamespace {
 	filter(response, filter) {
 		return filterResponse(response, filter, matchesOpportunityFilter);
 	}
-	history(key) {
-		return { chart: (metric, range) => this.offchain.getHistory({
-			opportunity: key,
-			range,
-			metric
-		}) };
+	async charts(key, metrics, range) {
+		return this.offchain.getCharts(key, metrics, range);
 	}
 };
 //#endregion

package/dist/esm/new-sdk/positions/PositionsNamespace.js

@@ -22,6 +22,7 @@ var PositionsNamespace = class extends AbstractNamespace {
 	**/
 	async list(wallet, filter) {
 		return this.merged("list positions", {
+			chainIds: filter?.chainIds,
 			fromChain: (source) => source.list({
 				wallet,
 				filter
@@ -39,12 +40,8 @@ var PositionsNamespace = class extends AbstractNamespace {
 	filter(response, filter) {
 		return filterResponse(response, filter, matchesPositionFilter);
 	}
-	history(key) {
-		return { chart: (metric, range) => this.offchain.getHistory({
-			position: key,
-			range,
-			metric
-		}) };
+	async charts(key, metrics, range) {
+		return this.offchain.getCharts(key, metrics, range);
 	}
 };
 //#endregion