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

package/dist/esm/sdk/accounts/intents/tests/withdraw.fixtures.js

@@ -0,0 +1,402 @@
+import { POS, POS2, RWA_ASSET, UND, WALLET, buildFixtureCreditAccount, buildMarketSdk, caToken } from "../testing/market.js";
+//#region src/sdk/accounts/intents/tests/withdraw.fixtures.ts
+/**
+* Start withdraw fixtures (intent 2.1) — one per row of the S/T matrix.
+*
+* Every case starts from 2000 UND of TVL against 1000 UND of debt: 1000 UND of
+* collateral at 2x. Withdrawing 100 UND of value therefore repays 100 of debt
+* (`dD = D0 * W / C0`), so 200 UND of value must be liquidated in total and the
+* account settles at 1800 TVL / 900 debt — still 2x.
+*
+* `POS` and `POS2` both convert 1:1 with `UND`, keeping swap amounts honest
+* against the mock router, which echoes its input amount.
+*/
+const LT = 9200n;
+const quotaOf = (balance) => balance * LT / 10000n;
+/** 100 UND of value leaving the account. */
+const W = 10000000000n;
+/** Payout plus proportional repayment. */
+const SPEND = 2n * W;
+const TVL_BEFORE = 200000000000n;
+const DEBT_BEFORE = 100000000000n;
+const TVL_AFTER = TVL_BEFORE - SPEND;
+const DEBT_AFTER = DEBT_BEFORE - W;
+const QUOTA_BEFORE = quotaOf(TVL_BEFORE);
+const QUOTA_AFTER = quotaOf(TVL_AFTER);
+/** Quota ops carry signed deltas. */
+const QUOTA_DELTA = QUOTA_AFTER - QUOTA_BEFORE;
+const base = {
+	accountDebt: DEBT_BEFORE,
+	totalValue: TVL_AFTER,
+	accountDebtAfter: DEBT_AFTER
+};
+/** Row 1 — S = U, T = U: repay, then hand over the underlying. */
+const case_und_und = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET
+	},
+	tokens: [caToken(UND, TVL_BEFORE)],
+	ops: [{
+		type: "decreaseDebt",
+		amount: W
+	}, {
+		type: "withdrawCollateral",
+		token: UND,
+		amount: W,
+		to: WALLET
+	}]
+};
+/** Row 2 — S = U, T = POS: repay, then route the payout out of the underlying. */
+const case_und_pos = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET,
+		tokenOut: POS
+	},
+	tokens: [caToken(UND, TVL_BEFORE)],
+	ops: [
+		{
+			type: "decreaseDebt",
+			amount: W
+		},
+		{
+			type: "swap",
+			from: [{
+				token: UND,
+				balance: W
+			}],
+			tokenOut: POS,
+			amountOut: W
+		},
+		{
+			type: "withdrawCollateral",
+			token: POS,
+			amount: W,
+			to: WALLET
+		}
+	]
+};
+/** Row 3 — S = POS, T = U: both legs land in the underlying, so one swap covers them. */
+const case_pos_und = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET,
+		sourceToken: POS
+	},
+	tokens: [caToken(POS, TVL_BEFORE, QUOTA_BEFORE)],
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: SPEND
+			}],
+			tokenOut: UND,
+			amountOut: SPEND
+		},
+		{
+			type: "decreaseDebt",
+			amount: W
+		},
+		{
+			type: "withdrawCollateral",
+			token: UND,
+			amount: W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: QUOTA_DELTA
+			}],
+			desiredQuota: {}
+		}
+	]
+};
+/** Row 4 — S = T = POS: only the repayment needs routing. */
+const case_pos_pos = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET,
+		sourceToken: POS,
+		tokenOut: POS
+	},
+	tokens: [caToken(POS, TVL_BEFORE, QUOTA_BEFORE)],
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: W
+			}],
+			tokenOut: UND,
+			amountOut: W
+		},
+		{
+			type: "decreaseDebt",
+			amount: W
+		},
+		{
+			type: "withdrawCollateral",
+			token: POS,
+			amount: W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: QUOTA_DELTA
+			}],
+			desiredQuota: {}
+		}
+	]
+};
+/** Row 5 — S = POS, T = POS2: two independent legs out of the same source. */
+const case_pos_pos2 = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET,
+		sourceToken: POS,
+		tokenOut: POS2
+	},
+	tokens: [caToken(POS, TVL_BEFORE, QUOTA_BEFORE)],
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: W
+			}],
+			tokenOut: UND,
+			amountOut: W
+		},
+		{
+			type: "decreaseDebt",
+			amount: W
+		},
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: W
+			}],
+			tokenOut: POS2,
+			amountOut: W
+		},
+		{
+			type: "withdrawCollateral",
+			token: POS2,
+			amount: W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: QUOTA_DELTA
+			}],
+			desiredQuota: {}
+		}
+	]
+};
+/** RWA market: the underlying payout is force-unwrapped to the asset. */
+const case_rwa_payout = {
+	...base,
+	intent: {
+		type: "WITHDRAW",
+		amount: W,
+		to: WALLET,
+		sourceToken: POS
+	},
+	tokens: [caToken(POS, TVL_BEFORE, QUOTA_BEFORE)],
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: SPEND
+			}],
+			tokenOut: UND,
+			amountOut: SPEND
+		},
+		{
+			type: "decreaseDebt",
+			amount: W
+		},
+		{
+			type: "unwrapRwaCollateral",
+			tokenIn: UND,
+			amount: W,
+			tokenOut: RWA_ASSET,
+			amountOut: W
+		},
+		{
+			type: "withdrawCollateral",
+			token: RWA_ASSET,
+			amount: W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: QUOTA_DELTA
+			}],
+			desiredQuota: {}
+		}
+	],
+	rwaAssets: { [UND]: RWA_ASSET }
+};
+/** Matrix baseline: 10A of position against 8U of debt (2U collateral at 5x). */
+const M4_BALANCE = 1000000000n;
+const M4_DEBT = 800000000n;
+/** Matrix payout W: 1U. */
+const M4_W = 100000000n;
+/** Proportional repayment `dD = D0 * W / C0` = 4U. */
+const M4_DD = 400000000n;
+/** Payout plus repayment: 5U liquidated in total. */
+const M4_SPEND = 500000000n;
+/**
+* Matrix 4.1 — withdraw 1U, source `POS`, payout `UND`.
+*
+* MATRIX MISMATCH: the matrix pays out first — `swap → withdrawCollateral →
+* decreaseDebt → changeQuota`. The engine repays before paying out
+* (`repay(dD, keep: W)` precedes the payout leg in `planWithdraw`):
+* `swap → decreaseDebt → withdrawCollateral → changeQuota`. Amounts are
+* identical; only the order differs.
+*/
+const case_matrix_4_1 = {
+	intent: {
+		type: "WITHDRAW",
+		amount: M4_W,
+		to: WALLET,
+		sourceToken: POS
+	},
+	tokens: [caToken(POS, M4_BALANCE, quotaOf(M4_BALANCE))],
+	accountDebt: M4_DEBT,
+	totalValue: M4_SPEND,
+	accountDebtAfter: M4_DD,
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: M4_SPEND
+			}],
+			tokenOut: UND,
+			amountOut: M4_SPEND
+		},
+		{
+			type: "decreaseDebt",
+			amount: M4_DD
+		},
+		{
+			type: "withdrawCollateral",
+			token: UND,
+			amount: M4_W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: quotaOf(M4_SPEND) - quotaOf(M4_BALANCE)
+			}],
+			desiredQuota: {}
+		}
+	]
+};
+/**
+* Matrix 4.2 — 4.1 on the RWA market: the payout is unwrapped on the way out.
+*
+* MATRIX MISMATCH: same ordering divergence as 4.1 — the matrix expects
+* `swap → unwrapRwaCollateral → withdrawCollateral(RWA) → decreaseDebt →
+* changeQuota`, the engine repays first:
+* `swap → decreaseDebt → unwrapRwaCollateral → withdrawCollateral(RWA) →
+* changeQuota`.
+*/
+const case_matrix_4_2 = {
+	intent: {
+		type: "WITHDRAW",
+		amount: M4_W,
+		to: WALLET,
+		sourceToken: POS
+	},
+	tokens: [caToken(POS, M4_BALANCE, quotaOf(M4_BALANCE))],
+	accountDebt: M4_DEBT,
+	totalValue: M4_SPEND,
+	accountDebtAfter: M4_DD,
+	ops: [
+		{
+			type: "swap",
+			from: [{
+				token: POS,
+				balance: M4_SPEND
+			}],
+			tokenOut: UND,
+			amountOut: M4_SPEND
+		},
+		{
+			type: "decreaseDebt",
+			amount: M4_DD
+		},
+		{
+			type: "unwrapRwaCollateral",
+			tokenIn: UND,
+			amount: M4_W,
+			tokenOut: RWA_ASSET,
+			amountOut: M4_W
+		},
+		{
+			type: "withdrawCollateral",
+			token: RWA_ASSET,
+			amount: M4_W,
+			to: WALLET
+		},
+		{
+			type: "changeQuota",
+			quotaIncrease: [],
+			quotaDecrease: [{
+				token: POS,
+				balance: quotaOf(M4_SPEND) - quotaOf(M4_BALANCE)
+			}],
+			desiredQuota: {}
+		}
+	],
+	rwaAssets: { [UND]: RWA_ASSET }
+};
+function buildWithdrawSdk(c) {
+	return buildMarketSdk({ rwaAssets: c.rwaAssets });
+}
+function buildWithdrawProps(c, sdk) {
+	return {
+		intent: c.intent,
+		creditAccount: buildFixtureCreditAccount({
+			accountDebt: c.accountDebt,
+			tokens: c.tokens
+		}),
+		sdk,
+		quotaReserve: void 0,
+		slippage: void 0
+	};
+}
+//#endregion
+export { DEBT_AFTER, DEBT_BEFORE, M4_BALANCE, M4_DD, M4_DEBT, M4_SPEND, M4_W, QUOTA_AFTER, QUOTA_BEFORE, QUOTA_DELTA, SPEND, TVL_AFTER, TVL_BEFORE, W, buildWithdrawProps, buildWithdrawSdk, case_matrix_4_1, case_matrix_4_2, case_pos_pos, case_pos_pos2, case_pos_und, case_rwa_payout, case_und_pos, case_und_und };

package/dist/esm/sdk/accounts/intents/types.js

@@ -1 +1,16 @@
-export {};
+//#region src/sdk/accounts/intents/types.ts
+/**
+* Validation failure that maps onto {@link PreviewErrorReason} rather than
+* crashing the caller: thrown by builders, converted to `{ ok: false }` by
+* `CreditAccountOperationsService.startIntent`.
+*/
+var IntentPreviewError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message ?? reason);
+		this.name = "IntentPreviewError";
+		this.reason = reason;
+	}
+};
+//#endregion
+export { IntentPreviewError };

package/dist/esm/sdk/accounts/intents/utils/adjust-state-to-snapshot.js

@@ -0,0 +1,17 @@
+//#region src/sdk/accounts/intents/utils/adjust-state-to-snapshot.ts
+/**
+* Maps an intents {@link OperationState} onto the {@link AccountSnapshot} that
+* position-metric functions take. `accountDebt` is treated as total debt
+* (principal plus accrued interest and fees).
+**/
+function adjustStateToSnapshot(creditManager, state) {
+	return {
+		creditManager,
+		assets: state.assets,
+		quotas: Object.values(state.quotas),
+		totalDebt: state.accountDebt,
+		totalValue: state.totalValue
+	};
+}
+//#endregion
+export { adjustStateToSnapshot };

package/dist/esm/sdk/accounts/intents/utils/credit-account-slice.js

@@ -0,0 +1,43 @@
+import { calcBorrowedAmountPlusInterestAndFees } from "./borrowed-amount-plus-interest-and-fees.js";
+//#region src/sdk/accounts/intents/utils/credit-account-slice.ts
+/**
+* Narrows full account data down to the slice the intent engine operates on.
+*
+* `accountDebt` is the total repayable debt (principal + accrued interest +
+* accrued fees) rather than the principal, because every debt-touching intent
+* settles the full outstanding amount.
+*
+* Addresses are lowercased so that `eq` comparisons and `AddressMap` lookups
+* behave consistently everywhere downstream.
+*/
+function toCreditAccountSlice(ca) {
+	return {
+		creditAccount: ca.creditAccount.toLowerCase(),
+		creditManager: ca.creditManager.toLowerCase(),
+		creditFacade: ca.creditFacade.toLowerCase(),
+		underlying: ca.underlying.toLowerCase(),
+		enabledTokensMask: ca.enabledTokensMask,
+		totalDebtUSD: ca.totalDebtUSD,
+		accountDebt: calcBorrowedAmountPlusInterestAndFees(ca),
+		tokens: ca.tokens.map((t) => ({
+			...t,
+			token: t.token.toLowerCase()
+		}))
+	};
+}
+/**
+* Reads an account by address and narrows it to {@link CreditAccountSlice}.
+*
+* The shared read model's `StrategyPosition` carries neither `tokens` nor
+* `enabledTokensMask` / `creditFacade` / `totalDebtUSD`, so simulating against
+* an existing position costs one account read.
+*
+* @throws When the account is not found in the connected markets.
+*/
+async function fetchCreditAccountSlice(sdk, creditAccount) {
+	const data = await sdk.accounts.getCreditAccountData(creditAccount);
+	if (!data) throw new Error(`credit account not found: ${creditAccount}`);
+	return toCreditAccountSlice(data);
+}
+//#endregion
+export { fetchCreditAccountSlice, toCreditAccountSlice };

package/dist/esm/sdk/accounts/intents/utils/index.js

@@ -1,9 +1,11 @@
-import { assembleOperationCalls } from "./assemble-operation-calls.js";
-import { calcBorrowedAmountPlusInterestAndFees } from "./borrowed-amount-plus-interest-and-fees.js";
 import { eq, toRouterCaSlice, toTargetDecimals } from "./common.js";
 import { convertAmount } from "./convert-amount.js";
-import { getQuotasForUpdate } from "./quotas-for-update.js";
-import { simulateOperationAssets } from "./simulate-assets.js";
-import { simulateState } from "./simulate-adjust-state.js";
-import { getOperationsWithQuotaUpdate } from "./with-quota-update.js";
-export { assembleOperationCalls, calcBorrowedAmountPlusInterestAndFees, convertAmount, eq, getOperationsWithQuotaUpdate, getQuotasForUpdate, simulateOperationAssets, simulateState, toRouterCaSlice, toTargetDecimals };
+import { isPhantomToken, isRedemptionPhantomToken, pickFattestNonPhantomToken, rankAccountTokens } from "./pick-token.js";
+import { adjustStateToSnapshot } from "./adjust-state-to-snapshot.js";
+import { assembleOperationCalls } from "./assemble-operation-calls.js";
+import { calcBorrowedAmountPlusInterestAndFees } from "./borrowed-amount-plus-interest-and-fees.js";
+import { fetchCreditAccountSlice, toCreditAccountSlice } from "./credit-account-slice.js";
+import { OperationLedger } from "./ledger.js";
+import { clearedQuotas, getQuotasForUpdate, quotasAfterUpdate } from "./quotas-for-update.js";
+import { createRouterPaths } from "./router-path.js";
+export { OperationLedger, adjustStateToSnapshot, assembleOperationCalls, calcBorrowedAmountPlusInterestAndFees, clearedQuotas, convertAmount, createRouterPaths, eq, fetchCreditAccountSlice, getQuotasForUpdate, isPhantomToken, isRedemptionPhantomToken, pickFattestNonPhantomToken, quotasAfterUpdate, rankAccountTokens, toCreditAccountSlice, toRouterCaSlice, toTargetDecimals };

package/dist/esm/sdk/accounts/intents/utils/ledger.js

@@ -0,0 +1,93 @@
+import { BigIntMath } from "../../../utils/bigint-math.js";
+//#region src/sdk/accounts/intents/utils/ledger.ts
+/**
+* Running account state, advanced one operation at a time.
+*
+* Exists because the amounts an operation is built from depend on the balances
+* the previous ones left behind: a swap has to know how much of its input token
+* is genuinely swap input, so the router does not sweep collateral that must
+* stay put. Applying each op as it is built keeps that a single forward pass —
+* a builder that re-simulated the chain from the start for every leg would be
+* quadratic in the number of legs and easy to desynchronise.
+*/
+var OperationLedger = class {
+	#balances = /* @__PURE__ */ new Map();
+	#underlying;
+	#convert;
+	#debt;
+	constructor(args) {
+		this.#underlying = args.underlying;
+		this.#convert = args.convert;
+		this.#debt = args.debt;
+		for (const asset of args.initialAssets) {
+			const token = asset.token.toLowerCase();
+			this.#balances.set(token, (this.#balances.get(token) ?? 0n) + asset.balance);
+		}
+	}
+	get debt() {
+		return this.#debt;
+	}
+	balanceOf(token) {
+		return this.#balances.get(token.toLowerCase()) ?? 0n;
+	}
+	applyAll(operations) {
+		for (const op of operations) this.apply(op);
+		return this;
+	}
+	snapshot() {
+		const assets = [...this.#balances.entries()].map(([token, balance]) => ({
+			token,
+			balance
+		}));
+		return {
+			assets,
+			totalValue: assets.reduce((acc, a) => acc + this.#convert(a.token, this.#underlying, a.balance), 0n),
+			debt: this.#debt
+		};
+	}
+	/** Advances the state by one operation; quota changes move no balance. */
+	apply(op) {
+		switch (op.type) {
+			case "changeQuota": break;
+			case "increaseDebt":
+				this.#debt += op.amount;
+				this.#add(this.#underlying, op.amount);
+				break;
+			case "decreaseDebt":
+				this.#debt = BigIntMath.max(0n, this.#debt - op.amount);
+				this.#add(this.#underlying, -op.amount);
+				break;
+			case "addCollateral":
+				this.#add(op.token, op.amount);
+				break;
+			case "withdrawCollateral":
+				this.#add(op.token, -op.amount);
+				break;
+			case "swap":
+				for (const input of op.from) this.#add(input.token, -input.balance);
+				this.#add(op.tokenOut, op.amountOut);
+				break;
+			case "wrapRwaCollateral":
+			case "unwrapRwaCollateral":
+				this.#add(op.tokenIn, -op.amount);
+				this.#add(op.tokenOut, op.amountOut);
+				break;
+			case "startDelayedWithdrawal":
+				this.#add(op.token, -op.amountIn);
+				for (const out of op.outputs) this.#add(out.token, out.amount);
+				break;
+			case "claimDelayedWithdrawal":
+				this.#add(op.withdrawalPhantomToken, -op.withdrawalTokenSpent);
+				for (const out of op.outputs) this.#add(out.token, out.amount);
+		}
+		return this;
+	}
+	#add(token, delta) {
+		const key = token.toLowerCase();
+		const balance = (this.#balances.get(key) ?? 0n) + delta;
+		if (balance <= 0n) this.#balances.delete(key);
+		else this.#balances.set(key, balance);
+	}
+};
+//#endregion
+export { OperationLedger };

package/dist/esm/sdk/accounts/intents/utils/pick-token.js

@@ -0,0 +1,68 @@
+import { NON_STRATEGY_PHANTOM_TOKEN_TYPES } from "../../../market/credit/collateralUtils.js";
+import { eq } from "./common.js";
+import { convertAmount } from "./convert-amount.js";
+//#region src/sdk/accounts/intents/utils/pick-token.ts
+/** Prefix marking every phantom-token contract type in the registry. */
+const PHANTOM_TOKEN_PREFIX = "PHANTOM_TOKEN::";
+/**
+* Whether `token` is a phantom (a non-transferable position marker such as a
+* pending delayed withdrawal).
+*
+* Reads `contractType` directly instead of going through
+* `TokensMeta.isPhantomToken`, which throws when extended token data has not
+* been loaded. Here an unknown token is simply treated as non-phantom.
+*/
+function isPhantomToken(sdk, token) {
+	return !!sdk.tokensMeta.get(token)?.contractType?.startsWith(PHANTOM_TOKEN_PREFIX);
+}
+const REDEMPTION_PHANTOM_TOKEN_TYPES = new Set(NON_STRATEGY_PHANTOM_TOKEN_TYPES);
+/**
+* Whether `token` is the phantom of a redemption in flight, rather than one of
+* the phantoms a position is simply held in (Convex, Infrared, staking
+* rewards), which the router sells like any other balance.
+*
+* Only the former stands between an account and being emptied: it cannot be
+* sold and it cannot leave until its claim has landed.
+*/
+function isRedemptionPhantomToken(sdk, token) {
+	const contractType = sdk.tokensMeta.get(token)?.contractType;
+	return !!contractType && REDEMPTION_PHANTOM_TOKEN_TYPES.has(contractType);
+}
+/**
+* Account balances that can actually back an operation, richest first.
+*
+* Phantoms are dropped because a pending delayed withdrawal cannot be spent:
+* it has to be claimed first, in a transaction of its own.
+*/
+function rankAccountTokens(args) {
+	const { creditAccount, sdk, exclude = [] } = args;
+	const convert = convertAmount(sdk, creditAccount.creditManager);
+	const candidates = [];
+	for (const t of creditAccount.tokens) {
+		if (t.balance <= 0n) continue;
+		if (exclude.some((e) => eq(e, t.token))) continue;
+		if (isPhantomToken(sdk, t.token)) continue;
+		candidates.push({
+			token: t.token,
+			balance: t.balance,
+			valueInUnderlying: convert(t.token, creditAccount.underlying, t.balance)
+		});
+	}
+	candidates.sort((a, b) => {
+		if (a.valueInUnderlying !== b.valueInUnderlying) return a.valueInUnderlying > b.valueInUnderlying ? -1 : 1;
+		return a.token < b.token ? -1 : a.token > b.token ? 1 : 0;
+	});
+	return candidates;
+}
+/**
+* Default working token for flows that do not get one from the caller: the
+* most valuable non-phantom balance on the account.
+*
+* Used for the source of a partial withdraw and the position leg of a leverage
+* adjustment, both of which the caller may override explicitly.
+*/
+function pickFattestNonPhantomToken(args) {
+	return rankAccountTokens(args)[0];
+}
+//#endregion
+export { isPhantomToken, isRedemptionPhantomToken, pickFattestNonPhantomToken, rankAccountTokens };