@gearbox-protocol/sdk 16.0.0-next.9 → 16.1.0

package/dist/esm/onchain/accounts/intents/leverage-band.js

@@ -0,0 +1,69 @@
+import { BigIntMath } from "../../utils/bigint-math.js";
+import { LEVERAGE_DECIMALS } from "../../constants/math.js";
+//#region src/onchain/accounts/intents/leverage-band.ts
+/**
+* The leverages this market will actually fund for a position of this size.
+*
+* A credit manager's `maxLeverage` follows from the liquidation threshold
+* alone, so it is the same for a hundred dollars and for a million. What a
+* given deposit reaches is decided by the debt it implies —
+* `debt = netValue × (leverage − 1)` — and by the band the market puts that
+* debt in. This inverts that relation.
+*
+* Rounding is asymmetric because the forward direction truncates: the floor
+* rounds **up** so the leverage it names really does clear `minDebt`, and the
+* ceiling rounds **down** so it really does stay under the borrow limit.
+*
+* Nothing here is fetched or simulated — every input is loaded market state,
+* so a form can call this on each keystroke.
+*
+* @param props - {@link LeverageBandProps}
+* @returns The band, or `undefined` when there is nothing to offer: an
+* unknown manager, a market with no strategy, or a deposit too small to reach
+* `minDebt` at any leverage the threshold allows.
+*
+* @example
+* ```ts
+* // minDebt 1k, borrow limit 100k, threshold ceiling 9x, deposit worth 10k
+* calcLeverageBand({ sdk, creditManager, collateral }) // { min: 1.1, max: 9 }
+* ```
+**/
+function calcLeverageBand({ sdk, creditManager, collateral, targetHF }) {
+	const found = resolve(sdk, creditManager);
+	if (!found) return;
+	const { suite, market } = found;
+	const target = suite.strategyTargetCollateral;
+	if (!target) return;
+	const ceiling = suite.creditManager.maxLeverage(target, targetHF);
+	const underlying = market.pool.underlying;
+	const convert = (from, to, amount) => market.priceOracle.safeConvert(from, to, amount).value;
+	const netValue = collateral.reduce((acc, a) => acc + convert(a.token, underlying, a.balance), 0n);
+	if (netValue <= 0n) return {
+		min: 1,
+		max: ceiling
+	};
+	const { minDebt, maxDebt } = suite.creditFacade;
+	const available = market.pool.pool.creditManagerDebtParams.get(suite.creditManager.address)?.available;
+	const borrowLimit = available === void 0 ? maxDebt : BigIntMath.min(maxDebt, available);
+	const floor = BigIntMath.ceilDiv(LEVERAGE_DECIMALS * minDebt, netValue);
+	const roof = LEVERAGE_DECIMALS * borrowLimit / netValue;
+	const min = 1 + Number(floor) / Number(LEVERAGE_DECIMALS);
+	const max = Math.min(ceiling, 1 + Number(roof) / Number(LEVERAGE_DECIMALS));
+	return min > max ? void 0 : {
+		min,
+		max
+	};
+}
+/** The manager's suite and market, or nothing while they cannot be resolved. */
+function resolve(sdk, creditManager) {
+	try {
+		return {
+			suite: sdk.marketRegister.findCreditManager(creditManager),
+			market: sdk.marketRegister.findByCreditManager(creditManager)
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { calcLeverageBand };

package/dist/esm/onchain/accounts/intents/math.js

@@ -1,6 +1,8 @@
 import { BigIntMath } from "../../utils/bigint-math.js";
 import { LEVERAGE_DECIMALS } from "../../constants/math.js";
-import { IntentPreviewError } from "./refusal.js";
+import { checkDebtInBand, checkLeverageAtLeastOne } from "../../validation/checks.js";
+import { IntentPreviewError, raise } from "../../validation/refusal.js";
+import { toToken } from "../../validation/token.js";
 //#region src/onchain/accounts/intents/math.ts
 /** Debt that realises `leverage` on `collateral`: `D = C · (L − 1)`. */
 function debtForLeverage(collateral, leverage) {
@@ -37,32 +39,23 @@ function maxProportionalWithdrawal(position, band) {
 }
 /** Total leverage cannot drop below 1x — that would be negative debt. */
 function assertLeverageAtLeastOne(leverage) {
-	if (leverage < 100n) throw new IntentPreviewError("leverageOutOfRange", {
-		requested: leverage,
+	raise(checkLeverageAtLeastOne({
+		leverage,
 		min: LEVERAGE_DECIMALS
-	}, `target leverage ${leverage} is below 1x`);
+	}), `target leverage ${leverage} is below 1x`);
 }
 /**
 * Rejects a debt the facade would revert on: zero is always fine (no loan at
 * all), anything else has to sit inside `[minDebt, maxDebt]`.
 */
-function assertDebtInBand(debt, band, underlying) {
-	const detail = {
-		requested: {
-			token: underlying,
-			balance: debt
-		},
-		minDebt: {
-			token: underlying,
-			balance: band.minDebt
-		},
-		maxDebt: {
-			token: underlying,
-			balance: band.maxDebt
-		}
-	};
-	if (debt > band.maxDebt) throw new IntentPreviewError("debtOutOfRange", detail, `debt ${debt} exceeds maxDebt ${band.maxDebt}`);
-	if (debt > 0n && debt < band.minDebt) throw new IntentPreviewError("debtOutOfRange", detail, `debt ${debt} is below minDebt ${band.minDebt}`);
+function assertDebtInBand(sdk, debt, band, underlying) {
+	raise(checkDebtInBand({
+		debt,
+		minDebt: band.minDebt,
+		maxDebt: band.maxDebt,
+		underlying: toToken(sdk, underlying),
+		allowZero: true
+	}), debt > band.maxDebt ? `debt ${debt} exceeds maxDebt ${band.maxDebt}` : `debt ${debt} is below minDebt ${band.minDebt}`);
 }
 //#endregion
 export { assertDebtInBand, assertLeverageAtLeastOne, debtForLeverage, maxProportionalWithdrawal, proportionalDebt };

package/dist/esm/onchain/accounts/intents/maxWithdrawCollateral.js

@@ -11,9 +11,11 @@ import { eq } from "./utils/common.js";
 * check counts: a holding backed by a quota contributes the lesser of the
 * quota and its threshold-weighted value, an unquoted one — the underlying —
 * its weighted value alone, and dust or a disabled balance nothing at all.
-* Collateral is valued at the lower of its two feeds, the way the facade
-* values a call that hands funds over; the debt is valued at the main feed,
-* as the check does. Zero debt frees the whole balance.
+* Collateral is valued at the protocol safe price (`min` of the two feeds,
+* 0 when there is no reserve), the way the facade values a call that hands
+* funds over; the underlying is exempt and is valued at the main feed, as
+* `CreditManagerV3._safeConvertToUSD` does. The debt is valued at the main
+* feed, as the check does. Zero debt frees the whole balance.
 *
 * Rounding always favours the account, so the answer clears the check rather
 * than landing a wei short of it.
@@ -30,13 +32,13 @@ function maxWithdrawCollateral(props) {
 	const underlying = market.pool.underlying;
 	const target = creditAccount.tokens.find((t) => eq(t.token, token));
 	if (!target || target.balance <= 10n) return 0n;
-	if (creditAccount.accountDebt === 0n) return target.balance;
+	if (creditAccount.totalDebt === 0n) return target.balance;
 	const masked = creditAccount.enabledTokensMask !== 0n;
 	const counts = (t) => t.balance > 10n && (!masked || (t.mask & creditAccount.enabledTokensMask) !== 0n);
 	/** What a holding backs, in the check's units: USD × PERCENTAGE_FACTOR. */
 	const weigh = (t) => {
 		const lt = BigInt(creditManager.liquidationThresholds.get(t.token) ?? 0);
-		const weighted = (safeUsd(priceOracle, t.token, t.balance) ?? 0n) * lt;
+		const weighted = (eq(t.token, underlying) ? usd(priceOracle, t.token, t.balance) ?? 0n : priceOracle.safeConvertMinUSD(t.token, t.balance).value) * lt;
 		if (t.quota === 0n) return weighted;
 		return BigIntMath.min(quotaUsd(t) * PERCENTAGE_FACTOR, weighted);
 	};
@@ -47,15 +49,15 @@ function maxWithdrawCollateral(props) {
 		if (eq(t.token, token) || !counts(t)) continue;
 		otherMoney += weigh(t);
 	}
-	const borrowed = usd(priceOracle, underlying, creditAccount.accountDebt);
+	const borrowed = usd(priceOracle, underlying, creditAccount.totalDebt);
 	if (borrowed === void 0 || borrowed <= 0n) return 0n;
 	const required = borrowed * targetHF;
 	if (required <= otherMoney) return target.balance;
 	const shortfall = required - otherMoney;
 	if (target.quota > 0n && quotaUsd(target) * 10000n < shortfall) return 0n;
 	const targetLt = BigInt(creditManager.liquidationThresholds.get(target.token) ?? 0);
-	const targetUsd = safeUsd(priceOracle, target.token, target.balance);
-	if (targetLt === 0n || !targetUsd) return 0n;
+	const targetUsd = eq(target.token, underlying) ? usd(priceOracle, target.token, target.balance) ?? 0n : priceOracle.safeConvertMinUSD(target.token, target.balance).value;
+	if (targetLt === 0n || targetUsd === 0n) return 0n;
 	const keptUsd = BigIntMath.ceilDiv(shortfall, targetLt);
 	const kept = BigIntMath.ceilDiv(target.balance * keptUsd, targetUsd);
 	return kept >= target.balance ? 0n : target.balance - kept;
@@ -68,18 +70,5 @@ function usd(oracle, token, amount) {
 		return;
 	}
 }
-/**
-* USD value at the lower of the token's two feeds — what a call handing funds
-* over is judged at. Falls back to the main feed where there is no second one.
-**/
-function safeUsd(oracle, token, amount) {
-	const main = usd(oracle, token, amount);
-	if (main === void 0) return;
-	try {
-		return BigIntMath.min(main, oracle.convertToUSD(token, amount, true));
-	} catch {
-		return main;
-	}
-}
 //#endregion
 export { maxWithdrawCollateral };

package/dist/esm/onchain/accounts/intents/open-strategy.js

@@ -1,7 +1,7 @@
-import { IntentPreviewError } from "./refusal.js";
-import { convertAmount } from "./utils/convert-amount.js";
+import { IntentPreviewError } from "../../validation/refusal.js";
 import { assertCanBorrow, assertCollateralised, assertGrowthAllowed, assertMarketOperable, assertQuotaHeadroom } from "./guards.js";
 import { assertDebtInBand, assertLeverageAtLeastOne, debtForLeverage } from "./math.js";
+import { collectPriceImpact } from "./utils/price-impact.js";
 import { getQuotasForUpdate } from "./utils/quotas-for-update.js";
 import { createRouterPaths } from "./utils/router-path.js";
 import "./utils/index.js";
@@ -9,7 +9,8 @@ import "./utils/index.js";
 /** Stand-in account address: nothing exists on chain until the tx lands. */
 const NO_ACCOUNT = "0x0000000000000000000000000000000000000000";
 /**
-* Previews opening a leveraged position out of wallet collateral.
+* Builds the state opening a leveraged position out of wallet collateral would
+* reach.
 *
 * Debt follows from the target leverage against the supplied margin
 * (`debt = margin * (L - 1)`, `totalValue = margin * L`); the collateral and the
@@ -19,14 +20,14 @@ const NO_ACCOUNT = "0x0000000000000000000000000000000000000000";
 * no operation list — the caller passes the numbers and calls straight to
 * `sdk.accounts.openCA`.
 */
-async function previewOpenStrategy(props) {
+async function buildOpenStrategyState(props) {
 	const { sdk, creditManager, collateral, targetToken, leverage, slippage = 0, quotaReserve, leftoverBalances = [] } = props;
 	assertLeverageAtLeastOne(leverage);
 	const suite = sdk.marketRegister.findCreditManager(creditManager);
 	const market = sdk.marketRegister.findByCreditManager(creditManager);
 	assertMarketOperable(suite);
 	const underlying = market.pool.underlying.toLowerCase();
-	const convert = convertAmount(sdk, creditManager);
+	const convert = (from, to, amount) => market.priceOracle.safeConvert(from, to, amount).value;
 	const margin = collateral.reduce((acc, a) => acc + convert(a.token, underlying, a.balance), 0n);
 	if (margin <= 0n) throw new IntentPreviewError("insufficientSourceBalance", void 0, "openStrategy: collateral is worth nothing in underlying");
 	const debt = debtForLeverage(margin, leverage);
@@ -37,17 +38,19 @@ async function previewOpenStrategy(props) {
 		underlying,
 		enabledTokensMask: 0n,
 		totalDebtUSD: 0n,
-		accountDebt: 0n,
+		totalDebt: 0n,
 		tokens: []
 	};
-	assertDebtInBand(debt, suite.creditFacade, underlying);
-	assertCanBorrow(suite, debt);
-	const leg = await createRouterPaths({
+	assertDebtInBand(sdk, debt, suite.creditFacade, underlying);
+	assertCanBorrow(sdk, suite, debt);
+	const paths = createRouterPaths({
 		sdk,
 		creditAccount: account,
 		slippage
-	}).openStrategy({
-		expectedBalances: mergeExpectedBalances(collateral, underlying, debt),
+	});
+	const expectedBalances = mergeExpectedBalances(collateral, underlying, debt);
+	const leg = await paths.openStrategy({
+		expectedBalances,
 		leftoverBalances,
 		target: targetToken
 	});
@@ -74,7 +77,7 @@ async function previewOpenStrategy(props) {
 		before: [],
 		after: averageAssets
 	});
-	assertQuotaHeadroom(market, averageQuota);
+	assertQuotaHeadroom(sdk, market, averageQuota);
 	const snapshot = {
 		creditManager,
 		assets: averageAssets,
@@ -82,24 +85,22 @@ async function previewOpenStrategy(props) {
 		totalDebt: debt,
 		totalValue: margin + debt
 	};
-	const projectedPool = { availableLiquidityChange: -debt };
-	const metrics = {
-		healthFactor: sdk.positions.healthFactor(snapshot),
-		borrowRate: sdk.positions.borrowRate(snapshot, projectedPool),
-		timeToLiquidation: sdk.positions.timeToLiquidation(snapshot, projectedPool),
-		liquidationPrice: sdk.positions.liquidationPrice(snapshot)
-	};
-	assertCollateralised(metrics.healthFactor, false);
-	return {
-		debt,
-		collateral: margin,
+	const { assets: _assets, quotas: _quotas, ...projection } = sdk.positions.projection(snapshot, { availableLiquidityChange: -debt });
+	assertCollateralised(projection.healthFactor, false);
+	const priceImpact = await collectPriceImpact(leg.probe ? [leg.probe] : [], {
 		totalValue: margin + debt,
+		netValue: margin,
+		toUnderlying: (from, amount) => convert(from, underlying, amount)
+	});
+	return {
+		...projection,
+		currentPrice: sdk.positions.currentPrice(snapshot),
+		priceImpact,
 		averageAssets: averageAssets.map(priced),
 		minAssets: minAssets.map(priced),
 		averageQuota,
 		minQuota,
-		calls: [...leg.calls],
-		...metrics
+		calls: [...leg.calls]
 	};
 }
 /** Collateral plus the borrowed underlying, folded into one balance per token. */
@@ -129,4 +130,4 @@ function toAssets(balances) {
 	}));
 }
 //#endregion
-export { previewOpenStrategy };
+export { buildOpenStrategyState };

package/dist/esm/onchain/accounts/intents/plan.js

@@ -1,6 +1,7 @@
 import { MAX_UINT256, PERCENTAGE_FACTOR } from "../../constants/math.js";
 import "../../constants/index.js";
-import { IntentPreviewError } from "./refusal.js";
+import { IntentPreviewError } from "../../validation/refusal.js";
+import { toToken, toTokenAmount } from "../../validation/token.js";
 import { eq } from "./utils/common.js";
 import { assertDebtInBand, assertLeverageAtLeastOne, debtForLeverage, proportionalDebt } from "./math.js";
 //#region src/onchain/accounts/intents/plan.ts
@@ -24,14 +25,8 @@ function planAdjustLeverage(intent, view) {
 	if (delta > 0n) return [borrow(delta), convert(U, T, delta)];
 	const shortfall = -delta - view.balanceOf(U);
 	if (shortfall > 0n && eq(T, U)) throw new IntentPreviewError("insufficientSourceBalance", {
-		required: {
-			token: U,
-			balance: -delta
-		},
-		held: {
-			token: U,
-			balance: view.balanceOf(U)
-		}
+		required: toTokenAmount(view.sdk, U, -delta),
+		held: toTokenAmount(view.sdk, U, view.balanceOf(U))
 	}, `adjustLeverage: needs ${-delta} underlying, account holds ${view.balanceOf(U)}`);
 	return [...shortfall > 0n ? [convert(T, U, view.price(U, T, shortfall))] : [], repay(-delta)];
 }
@@ -39,11 +34,11 @@ function planAdjustLeverage(intent, view) {
 function planDeposit(intent, view) {
 	assertPositive(intent.amount, "deposit");
 	const U = view.underlying;
-	if (!eq(intent.token, U) && !(view.rwaAsset && eq(intent.token, view.rwaAsset))) throw new IntentPreviewError("unsupportedCollateralToken", { token: intent.token }, `deposit: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be deposited, got ${intent.token}`);
+	if (!eq(intent.token, U) && !(view.rwaAsset && eq(intent.token, view.rwaAsset))) throw new IntentPreviewError("unsupportedCollateralToken", { token: toToken(view.sdk, intent.token) }, `deposit: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be deposited, got ${intent.token}`);
 	const aU = view.price(intent.token, U, intent.amount);
 	const debtDelta = intent.targetLeverage === void 0 ? proportionalDebt(view, aU) : debtForLeverage(view.collateral + aU, intent.targetLeverage) - view.debt;
 	if (debtDelta < 0n) throw new IntentPreviewError("leverageOutOfRange", void 0, `deposit: target leverage ${intent.targetLeverage} would require repaying debt`);
-	assertDebtInBand(view.debt + debtDelta, view.band, U);
+	assertDebtInBand(view.sdk, view.debt + debtDelta, view.band, U);
 	const T = intent.positionToken ?? positionToken(view, "deposit");
 	const depositStays = eq(intent.token, T);
 	return [
@@ -70,24 +65,15 @@ function planRepay(intent, view) {
 	assertPositive(intent.amount, "repay");
 	const U = view.underlying;
 	const fundsInU = eq(intent.token, U);
-	if (!fundsInU && !(view.rwaAsset && eq(intent.token, view.rwaAsset))) throw new IntentPreviewError("unsupportedCollateralToken", { token: intent.token }, `repay: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be repaid with, got ${intent.token}`);
+	if (!fundsInU && !(view.rwaAsset && eq(intent.token, view.rwaAsset))) throw new IntentPreviewError("unsupportedCollateralToken", { token: toToken(view.sdk, intent.token) }, `repay: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be repaid with, got ${intent.token}`);
 	if (view.debt <= 0n) throw new IntentPreviewError("debtOutOfRange", {
-		requested: {
-			token: U,
-			balance: view.debt
-		},
-		minDebt: {
-			token: U,
-			balance: view.band.minDebt
-		},
-		maxDebt: {
-			token: U,
-			balance: view.band.maxDebt
-		}
+		requested: toTokenAmount(view.sdk, U, view.debt),
+		minDebt: toTokenAmount(view.sdk, U, view.band.minDebt),
+		maxDebt: toTokenAmount(view.sdk, U, view.band.maxDebt)
 	}, "repay: the account owes nothing");
 	const funding = everything(intent.amount) ? view.price(U, intent.token, withMargin(view.debt)) : intent.amount;
 	const repaid = min(view.price(intent.token, U, funding), view.debt);
-	assertDebtInBand(view.debt - repaid, view.band, U);
+	assertDebtInBand(view.sdk, view.debt - repaid, view.band, view.underlying);
 	return [
 		add(intent.token, funding, intent.value),
 		...fundsInU ? [] : [convert(intent.token, U, funding)],
@@ -155,7 +141,7 @@ function planWithdrawDelayed(intent, view) {
 			}
 		}];
 	}
-	if (!eq(T, U) && !(view.rwaAsset && eq(T, view.rwaAsset))) throw new IntentPreviewError("noDelayedRoute", { token: T }, `withdraw: a delayed route cannot pay out in ${T}`);
+	if (!eq(T, U) && !(view.rwaAsset && eq(T, view.rwaAsset))) throw new IntentPreviewError("noDelayedRoute", { token: toToken(view.sdk, T) }, `withdraw: a delayed route cannot pay out in ${T}`);
 	const payoutIsSource = eq(T, S);
 	return [{
 		kind: "request",
@@ -211,7 +197,7 @@ function planFinishWithdraw(intent, claimable, claimed, view) {
 	const U = view.underlying;
 	const T = intent.withdrawToken;
 	const W = intent.withdrawAmount;
-	if (!eq(T, U) && !(view.rwaAsset && eq(T, view.rwaAsset))) throw new IntentPreviewError("noDelayedRoute", { token: T }, `finishWithdraw: cannot pay out in ${T}`);
+	if (!eq(T, U) && !(view.rwaAsset && eq(T, view.rwaAsset))) throw new IntentPreviewError("noDelayedRoute", { token: toToken(view.sdk, T) }, `finishWithdraw: cannot pay out in ${T}`);
 	if (intent.debtRepaid === 0n) return [
 		claim(claimable),
 		convert(claimed.token, T, claimed.amount),
@@ -316,7 +302,7 @@ function withdrawShape(intent, view) {
 		};
 	}
 	const dD = proportionalDebt(view, WU);
-	assertDebtInBand(view.debt - dD, view.band, U);
+	assertDebtInBand(view.sdk, view.debt - dD, view.band, view.underlying);
 	return {
 		U,
 		T,
@@ -335,7 +321,7 @@ function leverageShape(intent, view) {
 	assertLeverageAtLeastOne(intent.targetLeverage);
 	if (view.collateral <= 0n) throw new IntentPreviewError("insufficientSourceBalance", void 0, "adjustLeverage: account has no collateral to lever");
 	const target = debtForLeverage(view.collateral, intent.targetLeverage);
-	assertDebtInBand(target, view.band, view.underlying);
+	assertDebtInBand(view.sdk, target, view.band, view.underlying);
 	return {
 		U: view.underlying,
 		delta: target - view.debt