@gearbox-protocol/sdk 15.1.0-next.2 → 15.1.0-next.21

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

@@ -6,14 +6,23 @@ import { MissingSourceError } from "./errors/MissingSourceError.js";
 import "./errors/index.js";
 import { GearboxAPI } from "../offchain/GearboxAPI.js";
 import "../offchain/index.js";
+import { LiquidationsNamespace } from "./liquidations/LiquidationsNamespace.js";
+import "./liquidations/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";
+import { PreviewNamespace } from "./preview/PreviewNamespace.js";
+import "./preview/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.
@@ -49,16 +58,43 @@ var GearboxSDK = class {
 	* Namespace for the positions a wallet holds.
 	**/
 	positions;
+	/**
+	* Namespace for liquidatable credit accounts and delayed-withdrawal
+	* positions a liquidator holds. Onchain-only, hence gated by mode like
+	* every other chain read: absent in `offchain` mode.
+	**/
+	liquidations;
+	/**
+	* Namespace for on-chain previews of raw operation calldata. Onchain-only,
+	* hence gated by mode like every other chain read: absent in `offchain`
+	* mode.
+	**/
+	preview;
+	/**
+	* 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;
 	#attachOptions;
 	#onchain;
 	#offchain;
 	#ownsOnchain = false;
+	#maxStateAgeSeconds;
+	#logger;
 	#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 +127,69 @@ 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);
+		this.liquidations = this.#onchain ? new LiquidationsNamespace(this.#onchain, namespaceOptions) : void 0;
+		this.preview = this.#onchain ? new PreviewNamespace(this.#onchain, namespaceOptions) : void 0;
+		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 +226,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,12 @@ import { NoSourceServedError } from "./errors/NoSourceServedError.js";
 import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
 import "./errors/index.js";
 import { AbstractNamespace } from "./AbstractNamespace.js";
+import { LiquidationsNamespace } from "./liquidations/LiquidationsNamespace.js";
+import "./liquidations/index.js";
+import { ExecuteApi } from "./execute/ExecuteApi.js";
+import "./execute/index.js";
+import { PrepareApi } from "./prepare/PrepareApi.js";
+import "./prepare/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 +20,8 @@ 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 { PreviewNamespace } from "./preview/PreviewNamespace.js";
+import "./preview/index.js";
+import { DEFAULT_MAX_STATE_AGE, GearboxSDK } from "./GearboxSDK.js";
 import "./types.js";
-export { AbstractNamespace, AllSourcesFailedError, DEFAULT_MAX_OFFCHAIN_LAG, 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, LiquidationsNamespace, MissingSourceError, NoSourceServedError, OpportunitiesNamespace, PositionsNamespace, PrepareApi, PreviewNamespace, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };

package/dist/esm/new-sdk/liquidations/LiquidationsNamespace.js

@@ -0,0 +1,44 @@
+import { toChainIds } from "../../sdk/chain/chains.js";
+import "../../sdk/index.js";
+//#region src/new-sdk/liquidations/LiquidationsNamespace.ts
+/**
+* {@inheritDoc Liquidations}
+**/
+var LiquidationsNamespace = class {
+	#onchain;
+	#ensureFresh;
+	constructor(onchain, options) {
+		this.#onchain = onchain;
+		this.#ensureFresh = options.ensureFresh;
+	}
+	/**
+	* {@inheritDoc Liquidations.getLiquidatableAccounts}
+	**/
+	async getLiquidatableAccounts(props) {
+		await this.#ensureFresh?.(props?.chainIds);
+		return this.#onchain.liquidations.getLiquidatableAccounts(props);
+	}
+	/**
+	* {@inheritDoc Liquidations.getLiquidationDetails}
+	**/
+	async getLiquidationDetails(props) {
+		await this.#ensureFresh?.(toChainIds([props.network]));
+		return this.#onchain.liquidations.getLiquidationDetails(props);
+	}
+	/**
+	* {@inheritDoc Liquidations.buildLiquidationTx}
+	**/
+	async buildLiquidationTx(props) {
+		await this.#ensureFresh?.(toChainIds([props.network]));
+		return this.#onchain.liquidations.buildLiquidationTx(props);
+	}
+	/**
+	* {@inheritDoc Liquidations.getLiquidationPositions}
+	**/
+	async getLiquidationPositions(props) {
+		await this.#ensureFresh?.(props.chainIds);
+		return this.#onchain.liquidations.getLiquidationPositions(props);
+	}
+};
+//#endregion
+export { LiquidationsNamespace };

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

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

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 { PrepareApi } from "../prepare/PrepareApi.js";
+import "../prepare/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)
 	};
+	#prepare;
+	#execute;
 	constructor(onchain, offchain, options) {
 		super("Opportunities", onchain?.opportunities, offchain?.opportunities, options);
+		this.#prepare = onchain && new PrepareApi(onchain, options.ensureFresh);
+		this.#execute = onchain && new ExecuteApi((chainId) => onchain.chain(chainId));
+	}
+	/**
+	* {@inheritDoc OpportunitiesOnchainOnly.prepare}
+	**/
+	get prepare() {
+		if (!this.#prepare) throw new SourceUnavailableError("Opportunities", "onchain");
+		return this.#prepare;
+	}
+	/**
+	* {@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

@@ -2,8 +2,8 @@ import { matchesPositionFilter } from "../../model/positions.js";
 import "../../model/index.js";
 import { AbstractNamespace } from "../AbstractNamespace.js";
 import { filterResponse } from "../utils/filterResponse.js";
-import { mergeChainList } from "../utils/mergeChains.js";
 import "../utils/index.js";
+import { mergePositionList } from "./mergePositionList.js";
 //#region src/new-sdk/positions/PositionsNamespace.ts
 /**
 * The `positions` namespace of a {@link GearboxSDK}, see
@@ -13,7 +13,7 @@ var PositionsNamespace = class extends AbstractNamespace {
 	/**
 	* {@inheritDoc PositionsBase.merge}
 	**/
-	merge = { list: (onchain, offchain) => mergeChainList(onchain, offchain, this.maxOffchainLagSeconds) };
+	merge = { list: (onchain, offchain) => mergePositionList(onchain, offchain, this.maxOffchainLagSeconds) };
 	constructor(onchain, offchain, options) {
 		super("Positions", onchain?.positions, offchain?.positions, options);
 	}
@@ -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

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

@@ -0,0 +1,22 @@
+import { positionId } from "../../model/positions.js";
+import "../../model/index.js";
+import { mergeChainList } from "../utils/mergeChains.js";
+//#region src/new-sdk/positions/mergePositionList.ts
+function mergePositionList(onchain, offchain, maxLagSeconds) {
+	const merged = mergeChainList(onchain, offchain, maxLagSeconds);
+	if (!merged || !offchain) return merged;
+	const backendById = new Map(offchain.data.filter((row) => row.kind === "strategy").map((row) => [positionId(row), row]));
+	return {
+		...merged,
+		data: merged.data.map((row) => {
+			const backend = row.kind === "strategy" ? backendById.get(positionId(row)) : void 0;
+			return backend ? {
+				...row,
+				targetCollateral: backend.targetCollateral,
+				name: backend.name
+			} : row;
+		})
+	};
+}
+//#endregion
+export { mergePositionList };