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

package/dist/cjs/onchain/positions/PositionsService.js

@@ -0,0 +1,308 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_AddressMap = require("../utils/AddressMap.js");
+const require_onchain_chain_chains = require("../chain/chains.js");
+require("../constants/math.js");
+require("../constants/index.js");
+require("../utils/index.js");
+const require_onchain_base_SDKConstruct = require("../base/SDKConstruct.js");
+require("../base/index.js");
+const require_onchain_market_math = require("../market/math.js");
+const require_onchain_market_strategyName = require("../market/strategyName.js");
+const require_model_filters = require("../../model/filters.js");
+const require_model_positions = require("../../model/positions.js");
+require("../../model/index.js");
+const require_onchain_market_pool_math = require("../market/pool/math.js");
+const require_onchain_positions_calcBorrowRate = require("./calcBorrowRate.js");
+const require_onchain_positions_calcHealthFactor = require("./calcHealthFactor.js");
+const require_onchain_positions_calcLiquidationPrice = require("./calcLiquidationPrice.js");
+const require_onchain_positions_calcTimeToLiquidationMs = require("./calcTimeToLiquidationMs.js");
+const require_onchain_positions_types = require("./types.js");
+//#region src/onchain/positions/PositionsService.ts
+/**
+* The `positions` read model of one chain: everything a wallet holds in the
+* protocol — pool shares, open credit accounts, and delayed withdrawals it
+* took over by liquidating.
+**/
+var PositionsService = class extends require_onchain_base_SDKConstruct.SDKConstruct {
+	/**
+	* Every position of a wallet on this chain, optionally narrowed by
+	* {@link PositionFilter} (see {@link matchesPositionFilter} for what each
+	* condition selects). Reads live chain state, so rows reflect the moment of
+	* the call rather than the SDK's loaded snapshot.
+	**/
+	async list(props) {
+		const { wallet, filter, blockNumber } = props;
+		if (filter?.chainIds && !filter.chainIds.includes(this.chainId)) return [];
+		const wantedKind = filter?.kind;
+		const wanted = (kind) => !require_model_filters.isFilterSet(wantedKind) || wantedKind === kind;
+		const isZeroDebt = filter?.isZeroDebt;
+		const [pool, strategy, liquidation] = await Promise.all([
+			wanted("pool") ? this.sdk.pools.listPositions({
+				wallet,
+				blockNumber
+			}) : Promise.resolve([]),
+			wanted("strategy") ? this.listStrategyPositions({
+				owner: wallet,
+				includeZeroDebt: !require_model_filters.isFilterSet(isZeroDebt) || isZeroDebt,
+				blockNumber
+			}) : Promise.resolve([]),
+			wanted("liquidation") ? this.sdk.liquidations.getLiquidationPositions({
+				liquidator: wallet,
+				blockNumber
+			}) : Promise.resolve([])
+		]);
+		return [
+			...pool,
+			...strategy,
+			...liquidation
+		].filter((row) => require_model_positions.matchesPositionFilter(row, filter));
+	}
+	/**
+	* Describes all credit accounts of a wallet as strategy positions.
+	*
+	* @param props - {@link ListStrategyPositionsProps}
+	**/
+	async listStrategyPositions(props) {
+		const { owner, includeZeroDebt, blockNumber } = props;
+		const accounts = await this.sdk.accounts.getBorrowerCreditAccounts(owner, { includeZeroDebt }, blockNumber);
+		const withdrawals = await Promise.all(accounts.map((ca) => this.#accountWithdrawals(ca, blockNumber)));
+		return accounts.map((ca, i) => this.#toStrategyPosition(ca, withdrawals[i] ?? new require_onchain_utils_AddressMap.AddressMap()));
+	}
+	/**
+	* Health factor of an account state, in basis points (`10000` = 1.0).
+	**/
+	healthFactor(snapshot, options) {
+		const data = this.#marketData(snapshot);
+		return require_onchain_positions_calcHealthFactor.calcHealthFactor({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			prices: data.prices,
+			reservePrices: data.reservePrices,
+			safePrices: options?.safePrices,
+			liquidationThresholds: data.liquidationThresholds,
+			activeQuotas: data.activeQuotas
+		});
+	}
+	/**
+	* Cost of an account state's debt, broken down into the pool's base rate
+	* and per-token quota rates. A projection passes the operation's liquidity
+	* delta via {@link ProjectedPoolOptions} to have the base rate re-quoted at
+	* the post-operation pool utilization.
+	**/
+	borrowRate(snapshot, options) {
+		const data = this.#marketData(snapshot);
+		return require_onchain_positions_calcBorrowRate.calcBorrowRate({
+			snapshot,
+			baseInterestRate: this.#baseInterestRate(snapshot, data, options),
+			feeInterest: data.feeInterest,
+			quotaRates: data.quotaRates,
+			resolveToken: (address) => this.sdk.tokensMeta.mustGetToken(address)
+		});
+	}
+	/**
+	* Estimated milliseconds until the account's health factor decays to
+	* `10000` under its current borrow rate, or `null` when the debt carries
+	* no rate (or the account is already liquidatable). Takes the same
+	* projection options as {@link PositionsService.borrowRate}, so a projected
+	* state decays at the projected rate.
+	**/
+	timeToLiquidation(snapshot, options) {
+		const data = this.#marketData(snapshot);
+		return require_onchain_positions_calcTimeToLiquidationMs.calcTimeToLiquidationMs(require_onchain_positions_calcHealthFactor.calcHealthFactor({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			prices: data.prices,
+			liquidationThresholds: data.liquidationThresholds,
+			activeQuotas: data.activeQuotas
+		}), BigInt(require_onchain_positions_calcBorrowRate.calcBorrowRate({
+			snapshot,
+			baseInterestRate: this.#baseInterestRate(snapshot, data, options),
+			feeInterest: data.feeInterest,
+			quotaRates: data.quotaRates,
+			resolveToken: (address) => this.sdk.tokensMeta.mustGetToken(address)
+		}).totalOnDebt));
+	}
+	/**
+	* The base rate a metric is computed at, in ray: the pool's own, or — for a
+	* projection carrying a liquidity delta — the rate the interest model quotes
+	* at the utilization that delta leaves behind. A market whose rate model is
+	* not the linear one has nothing to re-quote from, and keeps the current
+	* rate.
+	*
+	* Callers pass the operation's total-debt change. On a borrow that is the
+	* principal leaving the pool; on a repayment it is the whole transfer back,
+	* interest and fees included. Either way it is the pool's own liquidity
+	* move, to within the share of a repayment the fees take.
+	**/
+	#baseInterestRate(snapshot, data, options) {
+		const delta = options?.availableLiquidityChange;
+		if (!delta) return data.baseInterestRate;
+		const suite = this.sdk.marketRegister.findByCreditManager(snapshot.creditManager).pool;
+		let params;
+		try {
+			params = suite.linearModel.params;
+		} catch {
+			return data.baseInterestRate;
+		}
+		const { pool } = suite;
+		return require_onchain_market_math.bpsToRay(require_onchain_market_pool_math.borrowRateAtUtilization(require_onchain_market_pool_math.utilizationAfterLiquidityChange(pool.expectedLiquidity, pool.availableLiquidity, delta), params));
+	}
+	/**
+	* Price of the single non-underlying collateral at which the account
+	* becomes liquidatable, or `null` when the account holds zero or several
+	* non-underlying assets.
+	**/
+	liquidationPrice(snapshot) {
+		const data = this.#marketData(snapshot);
+		return require_onchain_positions_calcLiquidationPrice.calcLiquidationPrice({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			liquidationThresholds: data.liquidationThresholds
+		});
+	}
+	/**
+	* Builds one strategy position from an account snapshot.
+	*
+	* @param withdrawals - Delayed withdrawals of the account, keyed by the
+	* phantom token that represents them on it.
+	**/
+	#toStrategyPosition(ca, withdrawals) {
+		const suite = this.sdk.marketRegister.findCreditManager(ca.creditManager);
+		const { market } = suite;
+		const { priceOracle } = market;
+		const { pool } = market.pool;
+		const token = market.underlyingToken;
+		const totalDebtValue = ca.debt + ca.accruedInterest + ca.accruedFees;
+		const target = require_onchain_chain_chains.getAccountTargetCollateral(ca.creditAccount, this.sdk.chainId) ?? suite.strategyTargetCollateral;
+		const priceFailed = !ca.success;
+		const recomputeTotals = ca.debt === 0n || priceFailed;
+		const collaterals = [];
+		let totalValue = recomputeTotals ? 0n : ca.totalValue;
+		let totalValueUSD = recomputeTotals ? 0n : ca.totalValueUSD;
+		for (const t of ca.tokens) {
+			if (t.balance <= 10n) continue;
+			collaterals.push({
+				collateral: priceOracle.toTokenAmount(t.token, t.balance),
+				quota: priceOracle.toTokenAmount(market.underlying, t.quota),
+				withdrawals: withdrawals.get(t.token) ?? []
+			});
+			if (recomputeTotals) {
+				const value = priceOracle.safeConvert(t.token, market.underlying, t.balance) || 0n;
+				totalValue += value;
+				const usd = priceOracle.safeConvertToUSD(t.token, t.balance) || 0n;
+				totalValueUSD += usd;
+			}
+		}
+		const snapshot = {
+			...require_onchain_positions_types.accountSnapshotFromCreditAccountData(ca),
+			totalValue
+		};
+		const borrowRate = this.borrowRate(snapshot);
+		const timeToLiquidation = this.timeToLiquidation(snapshot);
+		const liquidationPrice = this.liquidationPrice(snapshot);
+		const totalDebtUSD = priceFailed ? priceOracle.safeConvertToUSD(market.underlying, totalDebtValue) ?? 0n : ca.totalDebtUSD;
+		return {
+			kind: "strategy",
+			chainId: this.sdk.chainId,
+			creditManager: ca.creditManager,
+			creditAccount: ca.creditAccount,
+			underlyingToken: token,
+			name: target ? require_onchain_market_strategyName.strategyName(this.sdk.tokensMeta.mustGetToken(target), token) : token.symbol,
+			targetCollateral: target ? this.sdk.tokensMeta.mustGetToken(target) : null,
+			leverage: require_onchain_market_math.calcPositionLeverage(totalValue, totalDebtValue),
+			borrowApy: require_onchain_market_math.calcBorrowApy(pool.baseInterestRate, suite.creditManager.feeInterest),
+			totalDebt: {
+				token,
+				value: totalDebtValue,
+				valueUsd: require_onchain_market_math.usdToNumber(totalDebtUSD)
+			},
+			totalValue: {
+				token,
+				value: totalValue,
+				valueUsd: require_onchain_market_math.usdToNumber(totalValueUSD)
+			},
+			healthFactor: priceFailed ? this.healthFactor(snapshot) : require_onchain_market_math.healthFactorBps(ca.healthFactor),
+			borrowRate,
+			timeToLiquidation,
+			liquidationPrice,
+			collaterals,
+			...priceFailed ? { error: require_model_positions.STRATEGY_POSITION_COLLATERAL_ERROR } : {}
+		};
+	}
+	/**
+	* Delayed withdrawals of one account, keyed by the phantom token that
+	* represents them on it, so that each collateral row can pick up its own.
+	**/
+	async #accountWithdrawals(ca, blockNumber) {
+		const compressor = this.sdk.withdrawalCompressor;
+		const byPhantomToken = new require_onchain_utils_AddressMap.AddressMap(void 0, "accountWithdrawals");
+		const holdsPhantomToken = ca.tokens.some((t) => t.balance > 10n && compressor?.getWithdrawalSourceToken(t.token) !== void 0);
+		if (!compressor || !holdsPhantomToken) return byPhantomToken;
+		const { priceOracle } = this.sdk.marketRegister.findByCreditManager(ca.creditManager);
+		const { claimable, pending } = await compressor.getCurrentWithdrawals(ca.creditAccount, blockNumber);
+		const add = (w, outputs, claimableAt) => {
+			const assets = outputs.map((o) => ({
+				isDelayed: true,
+				...priceOracle.toTokenAmount(o.token, o.amount),
+				redeemer: w.redeemer,
+				claimableAt: claimableAt === void 0 ? void 0 : Number(claimableAt)
+			}));
+			byPhantomToken.upsert(w.withdrawalPhantomToken, [...byPhantomToken.get(w.withdrawalPhantomToken) ?? [], ...assets]);
+		};
+		for (const w of claimable) add(w, w.outputs);
+		for (const w of pending) add(w, w.expectedOutputs, w.claimableAt);
+		return byPhantomToken;
+	}
+	/**
+	* Collects decimals, prices and thresholds for the snapshot's tokens plus
+	* the market underlying, even when the account holds no underlying balance.
+	**/
+	#marketData(snapshot) {
+		const market = this.sdk.marketRegister.findByCreditManager(snapshot.creditManager);
+		const cm = this.sdk.marketRegister.findCreditManager(snapshot.creditManager).creditManager;
+		const { priceOracle } = market;
+		const underlying = market.pool.underlying;
+		const { pqk, pool } = market.pool;
+		const tokens = [underlying];
+		for (const a of snapshot.assets) tokens.push(a.token);
+		for (const q of snapshot.quotas) tokens.push(q.token);
+		const decimals = {};
+		const prices = {};
+		const reservePrices = {};
+		const liquidationThresholds = {};
+		const activeQuotas = {};
+		const quotaRates = {};
+		for (const token of tokens) {
+			const meta = this.sdk.tokensMeta.get(token);
+			if (meta) decimals[token] = meta.decimals;
+			try {
+				prices[token] = priceOracle.mainPrice(token);
+			} catch {}
+			try {
+				reservePrices[token] = priceOracle.reservePrice(token);
+			} catch {}
+			const lt = cm.liquidationThresholds.get(token);
+			if (lt !== void 0) liquidationThresholds[token] = lt;
+			if (pqk.hasActiveQuota(token)) {
+				activeQuotas[token] = true;
+				quotaRates[token] = pqk.quotaRate(token);
+			}
+		}
+		return {
+			underlying,
+			decimals,
+			prices,
+			reservePrices,
+			liquidationThresholds,
+			activeQuotas,
+			quotaRates,
+			baseInterestRate: pool.baseInterestRate,
+			feeInterest: cm.feeInterest
+		};
+	}
+};
+//#endregion
+exports.PositionsService = PositionsService;

package/dist/cjs/onchain/positions/calcBorrowRate.js

@@ -0,0 +1,47 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_AddressMap = require("../utils/AddressMap.js");
+const require_onchain_constants_math = require("../constants/math.js");
+const require_onchain_market_math = require("../market/math.js");
+//#region src/onchain/positions/calcBorrowRate.ts
+/**
+* Cost of an account state's debt, broken down into the pool's base rate and
+* per-token quota rates.
+*
+* The base rate is the market's borrow APY: whatever `baseInterestRate` the
+* caller hands over, plus the credit manager's interest fee — the same value
+* `borrowApy` reports on a position, and the same arithmetic when a projection
+* hands over the rate its post-operation utilization implies. Quota
+* contributions are `quotaBalance * quotaRate` with the interest fee on top,
+* normalized against the total value (`total`, `quotas`) and against the
+* debt (`totalOnDebt`, the rate the debt itself grows at). Formulas are in
+* parity with the frontend's `BorrowRateUtils`.
+**/
+function calcBorrowRate(props) {
+	const { snapshot, baseInterestRate, feeInterest, quotaRates, resolveToken } = props;
+	const { quotas, totalDebt, totalValue } = snapshot;
+	const rates = new require_onchain_utils_AddressMap.AddressMap(Object.entries(quotaRates));
+	const base = require_onchain_market_math.calcBorrowApy(baseInterestRate, feeInterest);
+	const fee = require_onchain_constants_math.PERCENTAGE_FACTOR + BigInt(feeInterest);
+	let quotaRateSum = 0n;
+	const perQuota = [];
+	for (const q of quotas) {
+		if (q.balance <= 10n) continue;
+		const rate = rates.get(q.token);
+		const rateBalance = rate === void 0 ? 0n : q.balance * BigInt(rate);
+		quotaRateSum += rateBalance;
+		const withFee = rateBalance * fee / require_onchain_constants_math.PERCENTAGE_FACTOR;
+		perQuota.push({
+			token: resolveToken(q.token),
+			rate: totalValue > 0n ? Number(withFee / totalValue) : 0
+		});
+	}
+	const quotaRateSumWithFee = quotaRateSum * fee / require_onchain_constants_math.PERCENTAGE_FACTOR;
+	return {
+		total: totalValue > 0n ? Number(totalDebt * BigInt(base) / totalValue) + Number(quotaRateSumWithFee / totalValue) : 0,
+		totalOnDebt: totalDebt > 0n ? base + Number(quotaRateSumWithFee / totalDebt) : 0,
+		base,
+		quotas: perQuota
+	};
+}
+//#endregion
+exports.calcBorrowRate = calcBorrowRate;

package/dist/cjs/onchain/positions/calcHealthFactor.js

@@ -0,0 +1,52 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_AddressMap = require("../utils/AddressMap.js");
+const require_onchain_utils_bigint_math = require("../utils/bigint-math.js");
+const require_onchain_constants_math = require("../constants/math.js");
+let viem = require("viem");
+//#region src/onchain/positions/calcHealthFactor.ts
+/**
+* Health factor of an account state, in basis points (`10000` = 1.0).
+*
+* Collateral is valued under liquidation thresholds, with quoted tokens
+* capped by their quota, and compared against the debt's value. An account
+* with no debt reports `65535` (`MAX_UINT16`), the contract's own sentinel
+* scaled down. Formulas are in parity with the legacy `calcHealthFactor`.
+* Tokens with no price in {@link CalcHealthFactorProps.prices} contribute
+* nothing.
+**/
+function calcHealthFactor(props) {
+	const { snapshot, underlying, decimals, prices, reservePrices = {}, safePrices = false, liquidationThresholds, activeQuotas } = props;
+	if (snapshot.totalDebt === 0n) return Number(require_onchain_constants_math.MAX_UINT16);
+	const decimalsByToken = new require_onchain_utils_AddressMap.AddressMap(Object.entries(decimals));
+	const pricesByToken = new require_onchain_utils_AddressMap.AddressMap(Object.entries(prices));
+	const reservePricesByToken = new require_onchain_utils_AddressMap.AddressMap(Object.entries(reservePrices));
+	const lts = new require_onchain_utils_AddressMap.AddressMap(Object.entries(liquidationThresholds));
+	const active = new require_onchain_utils_AddressMap.AddressMap(Object.entries(activeQuotas));
+	const priceOf = (token, forCollateral) => {
+		const main = pricesByToken.get(token);
+		if (!safePrices || !forCollateral) return main;
+		const reserve = reservePricesByToken.get(token);
+		if (main !== void 0 && reserve !== void 0) return require_onchain_utils_bigint_math.BigIntMath.min(main, reserve);
+		return main ?? reserve;
+	};
+	const convertToUSD = (token, amount, forCollateral = false) => {
+		const price = priceOf(token, forCollateral);
+		if (price === void 0) return null;
+		const scale = 10n ** BigInt(decimalsByToken.get(token) ?? 18);
+		return amount * price / scale;
+	};
+	const assetMoney = snapshot.assets.reduce((acc, { token, balance }) => {
+		if (balance <= 10n) return acc;
+		const lt = BigInt(lts.get(token) ?? 0);
+		const tokenLtWeighted = (convertToUSD(token, balance, true) ?? 0n) * lt;
+		const quota = snapshot.quotas.find((q) => (0, viem.isAddressEqual)(q.token, token));
+		const quotaBalance = quota && (active.get(token) ?? false) ? quota.balance : 0n;
+		const quotaWeighted = (convertToUSD(underlying, quotaBalance) ?? 0n) * require_onchain_constants_math.PERCENTAGE_FACTOR;
+		return acc + (quota ? require_onchain_utils_bigint_math.BigIntMath.min(quotaWeighted, tokenLtWeighted) : tokenLtWeighted);
+	}, 0n);
+	const borrowedMoney = convertToUSD(underlying, snapshot.totalDebt) ?? 0n;
+	const hf = borrowedMoney > 0n ? assetMoney / borrowedMoney : 0n;
+	return Number(hf);
+}
+//#endregion
+exports.calcHealthFactor = calcHealthFactor;

package/dist/cjs/onchain/positions/calcLiquidationPrice.js

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../constants/math.js");
+const require_onchain_positions_calcLiquidationPriceForTarget = require("./calcLiquidationPriceForTarget.js");
+let viem = require("viem");
+//#region src/onchain/positions/calcLiquidationPrice.ts
+/**
+* Liquidation price of an account state's target collateral, in the oracle's
+* 8-decimal (`PRICE_DECIMALS`) fixed point.
+*
+* As the frontend does, a liquidation price only exists when the account
+* holds exactly one non-dust non-underlying asset; otherwise `null`.
+**/
+function calcLiquidationPrice(props) {
+	const { snapshot, underlying } = props;
+	const targets = snapshot.assets.filter((a) => a.balance > 10n && !(0, viem.isAddressEqual)(a.token, underlying));
+	if (targets.length !== 1) return null;
+	return require_onchain_positions_calcLiquidationPriceForTarget.calcLiquidationPriceForTarget({
+		...props,
+		targetToken: targets[0].token
+	});
+}
+//#endregion
+exports.calcLiquidationPrice = calcLiquidationPrice;

package/dist/cjs/onchain/positions/calcLiquidationPriceForTarget.js

@@ -0,0 +1,30 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_AddressMap = require("../utils/AddressMap.js");
+const require_onchain_constants_math = require("../constants/math.js");
+let viem = require("viem");
+//#region src/onchain/positions/calcLiquidationPriceForTarget.ts
+/**
+* Liquidation price of an explicitly named collateral token, in
+* `PRICE_DECIMALS` fixed point; `0n` when the account holds none of it or the
+* token has no liquidation threshold. Formula is in parity with the legacy
+* `liquidationPrice`: the effective debt (debt less the underlying balance's
+* contribution under its threshold) over the threshold-weighted target
+* balance.
+**/
+function calcLiquidationPriceForTarget(props) {
+	const { snapshot, targetToken, underlying, decimals, liquidationThresholds } = props;
+	const decimalsByToken = new require_onchain_utils_AddressMap.AddressMap(Object.entries(decimals));
+	const lts = new require_onchain_utils_AddressMap.AddressMap(Object.entries(liquidationThresholds));
+	const underlyingDecimals = decimalsByToken.get(underlying) ?? 18;
+	const underlyingBalance = snapshot.assets.find((a) => (0, viem.isAddressEqual)(a.token, underlying))?.balance ?? 0n;
+	const ltUnderlying = BigInt(lts.get(underlying) ?? 0);
+	const effectiveDebt = (snapshot.totalDebt - underlyingBalance * ltUnderlying / require_onchain_constants_math.PERCENTAGE_FACTOR) * require_onchain_constants_math.WAD / 10n ** BigInt(underlyingDecimals);
+	const targetDecimals = decimalsByToken.get(targetToken) ?? 18;
+	const targetBalance = snapshot.assets.find((a) => (0, viem.isAddressEqual)(a.token, targetToken))?.balance ?? 0n;
+	const effectiveTargetBalance = targetBalance * require_onchain_constants_math.WAD / 10n ** BigInt(targetDecimals);
+	const lpLT = BigInt(lts.get(targetToken) ?? 0);
+	if (targetBalance <= 10n || lpLT <= 0n) return 0n;
+	return effectiveDebt * require_onchain_constants_math.PRICE_DECIMALS * require_onchain_constants_math.PERCENTAGE_FACTOR / (effectiveTargetBalance * lpLT);
+}
+//#endregion
+exports.calcLiquidationPriceForTarget = calcLiquidationPriceForTarget;

package/dist/cjs/onchain/positions/calcTimeToLiquidationMs.js

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_constants_math = require("../constants/math.js");
+//#region src/onchain/positions/calcTimeToLiquidationMs.ts
+/**
+* Estimated milliseconds until `healthFactorBps` decays to `10000` (1.0)
+* while the debt grows at `totalBorrowRateOnDebt`, in the same `Bps` scale
+* (`10000` = 100%) as {@link BorrowRateBreakdown.totalOnDebt} reports it —
+* not the legacy `PERCENTAGE_FACTOR_1KK` (`1_000_000` = 100%) scale the
+* pre-rewrite frontend fed into its own `getTimeToLiquidation`.
+*
+* `null` when the account is already at or under the liquidation threshold,
+* or when the debt carries no borrow rate at all.
+**/
+function calcTimeToLiquidationMs(healthFactorBps, totalBorrowRateOnDebt) {
+	if (BigInt(healthFactorBps) <= 10000n || totalBorrowRateOnDebt === 0n) return null;
+	return (BigInt(healthFactorBps) - require_onchain_constants_math.PERCENTAGE_FACTOR) * (BigInt(require_onchain_constants_math.SECONDS_PER_YEAR) * require_onchain_constants_math.PERCENTAGE_FACTOR / totalBorrowRateOnDebt) * 1000n / require_onchain_constants_math.PERCENTAGE_FACTOR;
+}
+//#endregion
+exports.calcTimeToLiquidationMs = calcTimeToLiquidationMs;

package/dist/cjs/onchain/positions/index.js

@@ -0,0 +1,17 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_positions_calcBorrowRate = require("./calcBorrowRate.js");
+const require_onchain_positions_calcHealthFactor = require("./calcHealthFactor.js");
+const require_onchain_positions_calcLiquidationPriceForTarget = require("./calcLiquidationPriceForTarget.js");
+const require_onchain_positions_calcLiquidationPrice = require("./calcLiquidationPrice.js");
+const require_onchain_positions_calcTimeToLiquidationMs = require("./calcTimeToLiquidationMs.js");
+const require_onchain_positions_MultichainPositionsService = require("./MultichainPositionsService.js");
+const require_onchain_positions_types = require("./types.js");
+const require_onchain_positions_PositionsService = require("./PositionsService.js");
+exports.MultichainPositionsService = require_onchain_positions_MultichainPositionsService.MultichainPositionsService;
+exports.PositionsService = require_onchain_positions_PositionsService.PositionsService;
+exports.accountSnapshotFromCreditAccountData = require_onchain_positions_types.accountSnapshotFromCreditAccountData;
+exports.calcBorrowRate = require_onchain_positions_calcBorrowRate.calcBorrowRate;
+exports.calcHealthFactor = require_onchain_positions_calcHealthFactor.calcHealthFactor;
+exports.calcLiquidationPrice = require_onchain_positions_calcLiquidationPrice.calcLiquidationPrice;
+exports.calcLiquidationPriceForTarget = require_onchain_positions_calcLiquidationPriceForTarget.calcLiquidationPriceForTarget;
+exports.calcTimeToLiquidationMs = require_onchain_positions_calcTimeToLiquidationMs.calcTimeToLiquidationMs;

package/dist/cjs/onchain/positions/types.js

@@ -0,0 +1,30 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../constants/math.js");
+//#region src/onchain/positions/types.ts
+/**
+* Builds an {@link AccountSnapshot} from on-chain credit account data
+**/
+function accountSnapshotFromCreditAccountData(ca) {
+	const assets = [];
+	const quotas = [];
+	for (const t of ca.tokens) {
+		if (t.balance <= 10n) continue;
+		assets.push({
+			token: t.token,
+			balance: t.balance
+		});
+		quotas.push({
+			token: t.token,
+			balance: t.quota
+		});
+	}
+	return {
+		creditManager: ca.creditManager,
+		assets,
+		quotas,
+		totalDebt: ca.debt + ca.accruedInterest + ca.accruedFees,
+		totalValue: ca.totalValue
+	};
+}
+//#endregion
+exports.accountSnapshotFromCreditAccountData = accountSnapshotFromCreditAccountData;

package/dist/cjs/onchain/router/AbstractRouterContract.js

@@ -0,0 +1,141 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_AddressSet = require("../utils/AddressSet.js");
+const require_onchain_utils_AssetsMap = require("../utils/AssetsMap.js");
+const require_onchain_constants_math = require("../constants/math.js");
+const require_onchain_utils_isDust = require("../utils/isDust.js");
+const require_onchain_utils_formatter = require("../utils/formatter.js");
+require("../utils/index.js");
+const require_onchain_base_BaseContract = require("../base/BaseContract.js");
+require("../base/index.js");
+const require_onchain_router_helpers = require("./helpers.js");
+//#region src/onchain/router/AbstractRouterContract.ts
+/**
+* @internal
+* Base class for router contract wrappers.
+*
+* Provides helpers that classify credit-account token balances into
+* "expected" (to be swapped) and "leftover" (to be kept) categories,
+* which concrete router implementations use when building optimised
+* multi-call swap paths.
+*
+* @typeParam abi - ABI type of the underlying router contract.
+**/
+var AbstractRouterContract = class extends require_onchain_base_BaseContract.BaseContract {
+	/**
+	* Reference to the parent SDK instance.
+	**/
+	sdk;
+	constructor(sdk, args) {
+		super(sdk, args);
+		this.sdk = sdk;
+	}
+	getExpectedAndLeftover(ca, cm, options = {}) {
+		const { leftoverBalances, expectedBalances, tokensToClaim } = options.balances ? options.balances : this.getDefaultExpectedAndLeftover(ca, options.keepAssets, options.debtOnly);
+		const expected = new require_onchain_utils_AssetsMap.AssetsMap();
+		const leftover = new require_onchain_utils_AssetsMap.AssetsMap();
+		for (const token of cm.collateralTokens) {
+			const actual = expectedBalances.get(token) || 0n;
+			expected.upsert(token, actual > 10n ? actual : 0n);
+			leftover.upsert(token, require_onchain_router_helpers.limitLeftover(leftoverBalances.get(token) || 1n, token) ?? 1n);
+		}
+		return {
+			expectedBalances: expected,
+			leftoverBalances: leftover,
+			tokensToClaim
+		};
+	}
+	getDefaultExpectedAndLeftover(ca, keepAssets, debtOnly) {
+		const expectedBalances = new require_onchain_utils_AssetsMap.AssetsMap();
+		const leftoverBalances = new require_onchain_utils_AssetsMap.AssetsMap();
+		const keepAssetsSet = new require_onchain_utils_AddressSet.AddressSet(keepAssets);
+		if (debtOnly) {
+			const result = this.getLeftoversAfterBuyingDebt(ca, keepAssetsSet);
+			if (result) return result;
+			else this.logger?.warn("no token found to cover debt");
+		}
+		for (const { token, balance, mask } of ca.tokens) {
+			const isEnabled = (mask & ca.enabledTokensMask) !== 0n;
+			expectedBalances.upsert(token, balance);
+			if (keepAssetsSet.has(token) || !isEnabled || require_onchain_utils_isDust.isDust({
+				sdk: this.sdk,
+				token,
+				balance,
+				creditManager: ca.creditManager
+			})) leftoverBalances.upsert(token, require_onchain_router_helpers.limitLeftover(balance, token) ?? balance);
+		}
+		return {
+			expectedBalances,
+			leftoverBalances,
+			tokensToClaim: new require_onchain_utils_AssetsMap.AssetsMap()
+		};
+	}
+	/**
+	* Tries to sell just enough of the most valuable token to cover debt.
+	* @param ca
+	* @param keepAssets
+	* @returns
+	*/
+	getLeftoversAfterBuyingDebt(ca, keepAssets) {
+		const { priceOracle } = this.sdk.marketRegister.findByCreditManager(ca.creditManager);
+		const expectedBalances = new require_onchain_utils_AssetsMap.AssetsMap();
+		const leftoverBalances = new require_onchain_utils_AssetsMap.AssetsMap();
+		const usdBalances = [];
+		for (const { token, balance, mask } of ca.tokens) {
+			const isEnabled = (mask & ca.enabledTokensMask) !== 0n;
+			expectedBalances.upsert(token, balance);
+			leftoverBalances.upsert(token, require_onchain_router_helpers.limitLeftover(balance, token) ?? balance);
+			if (isEnabled && !keepAssets.has(token)) usdBalances.push({
+				token,
+				balance: this.safeConvertToUSD(priceOracle, token, balance)
+			});
+		}
+		usdBalances.sort((a, b) => {
+			if (a.balance > b.balance) return -1;
+			if (a.balance < b.balance) return 1;
+			return 0;
+		});
+		if (usdBalances.length === 0) return;
+		const highestToken = usdBalances[0];
+		const lt = this.sdk.marketRegister.findCreditManager(ca.creditManager).creditManager.liquidationThresholds.mustGet(highestToken.token);
+		const requiredDebtUSD = ca.totalDebtUSD * require_onchain_constants_math.PERCENTAGE_FACTOR / BigInt(lt);
+		if (highestToken.balance < requiredDebtUSD) return;
+		const tokenAmount = this.safeConvertFromUSD(priceOracle, highestToken.token, requiredDebtUSD);
+		if (tokenAmount === 0n) return;
+		let leftoverBalance = leftoverBalances.get(highestToken.token) ?? 0n;
+		leftoverBalance -= tokenAmount;
+		if (leftoverBalance < 0n) return;
+		leftoverBalances.upsert(highestToken.token, leftoverBalance);
+		const tokenAmountStr = this.sdk.tokensMeta.formatBN(highestToken.token, tokenAmount, { symbol: true });
+		const totalDebtUSDStr = require_onchain_utils_formatter.formatBN(ca.totalDebtUSD, 8);
+		this.logger?.debug(`will sell ${tokenAmountStr} (LT=${lt}) to cover debt of ${totalDebtUSDStr} USD`);
+		return {
+			expectedBalances,
+			leftoverBalances,
+			tokensToClaim: new require_onchain_utils_AssetsMap.AssetsMap()
+		};
+	}
+	safeConvertToUSD(priceOracle, token, balance) {
+		try {
+			return priceOracle.convertToUSD(token, balance);
+		} catch {
+			try {
+				return priceOracle.convertToUSD(token, balance, true);
+			} catch {
+				return 0n;
+			}
+		}
+	}
+	safeConvertFromUSD(priceOracle, token, balance) {
+		try {
+			return priceOracle.convertFromUSD(token, balance);
+		} catch {
+			try {
+				return priceOracle.convertFromUSD(token, balance, true);
+			} catch {
+				return 0n;
+			}
+		}
+	}
+};
+//#endregion
+exports.AbstractRouterContract = AbstractRouterContract;