@gearbox-protocol/sdk 16.0.0-next.4 → 16.0.0-next.40

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

@@ -0,0 +1,462 @@
+import { AddressMap } from "../utils/AddressMap.js";
+import "../constants/math.js";
+import "../constants/index.js";
+import "../utils/index.js";
+import { SDKConstruct } from "../base/SDKConstruct.js";
+import "../base/index.js";
+import { bpsToRay, calcBorrowApy, calcPositionLeverage, healthFactorBps, usdToNumber } from "../market/math.js";
+import { isFilterSet } from "../../model/filters.js";
+import { STRATEGY_POSITION_COLLATERAL_ERROR, matchesPositionFilter } from "../../model/positions.js";
+import "../../model/index.js";
+import { collateralPriceInUnderlying } from "../market/oracle/collateralPriceInUnderlying.js";
+import { borrowRateAtUtilization, utilizationAfterLiquidityChange } from "../market/pool/math.js";
+import { calcBorrowRate } from "./calcBorrowRate.js";
+import { calcHealthFactor } from "./calcHealthFactor.js";
+import { calcLiquidationPrice, soleNonUnderlyingCollateral } from "./calcLiquidationPrice.js";
+import { calcTimeToLiquidationMs } from "./calcTimeToLiquidationMs.js";
+import { accountSnapshotFromCreditAccountData } from "./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 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) => !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: !isFilterSet(isZeroDebt) || isZeroDebt,
+				blockNumber
+			}) : Promise.resolve([]),
+			wanted("liquidation") ? this.sdk.liquidations.getLiquidationPositions({
+				liquidator: wallet,
+				blockNumber
+			}) : Promise.resolve([])
+		]);
+		return [
+			...pool,
+			...strategy,
+			...liquidation
+		].filter((row) => 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 AddressMap()));
+	}
+	/**
+	* Returns delayed withdrawals of a strategy position
+	*
+	* Empty when this chain has no withdrawal compressor, or when the account's
+	* credit manager has no withdrawal config — no config, no withdrawal, and
+	* nothing to ask the chain about.
+	*
+	* The manager comes from the caller. It used to be read off the account
+	* here, which cost an uncached read of the whole account to learn one field
+	* every caller already knows.
+	**/
+	async getCurrentWithdrawals(props) {
+		const { creditAccount, creditManager, blockNumber } = props;
+		const empty = {
+			claimable: [],
+			pending: []
+		};
+		const compressor = this.sdk.withdrawalCompressor;
+		if (!compressor) return empty;
+		await compressor.loadWithdrawableAssets();
+		if (compressor.getWithdrawableAssets(creditManager).length === 0) return empty;
+		const { priceOracle } = this.sdk.marketRegister.findByCreditManager(creditManager);
+		return this.#toPositionWithdrawals(await compressor.getCurrentWithdrawals(creditAccount, blockNumber), priceOracle);
+	}
+	/**
+	* Health factor of an account state, in basis points (`10000` = 1.0).
+	**/
+	healthFactor(snapshot, options) {
+		const data = this.#marketData(snapshot);
+		return 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 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 calcTimeToLiquidationMs(calcHealthFactor({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			prices: data.prices,
+			liquidationThresholds: data.liquidationThresholds,
+			activeQuotas: data.activeQuotas
+		}), BigInt(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 bpsToRay(borrowRateAtUtilization(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 calcLiquidationPrice({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			liquidationThresholds: data.liquidationThresholds
+		});
+	}
+	/**
+	* What the collateral {@link liquidationPrice} is quoted for costs in the
+	* market underlying right now, in the same `PRICE_DECIMALS` fixed point —
+	* the pair a form shows beside the liquidation price. `null` under exactly
+	* the conditions that leave the liquidation price `null`, plus an oracle
+	* that cannot answer for either side.
+	**/
+	currentPrice(snapshot) {
+		const market = this.sdk.marketRegister.findByCreditManager(snapshot.creditManager);
+		const underlying = market.pool.underlying;
+		const collateral = soleNonUnderlyingCollateral(snapshot, underlying);
+		if (!collateral) return null;
+		return collateralPriceInUnderlying(market.priceOracle, collateral, underlying);
+	}
+	/**
+	* Every derived number of an account state at once — the whole
+	* {@link AccountMetrics} half of a projection.
+	*
+	* This is what both halves of the SDK fill their answers from: `prepare`, for
+	* a state it walked an intent into, and `preview`, for one it replayed out of
+	* calldata. One snapshot in, one set of metrics out, so the two descriptions
+	* of the same operation cannot disagree because one of them grew its own
+	* formula.
+	*
+	* Identical to the four methods above field for field, and cheaper than
+	* calling them one by one: the market data is collected once, and the health
+	* factor and borrow rate the time to liquidation decays at are the very ones
+	* reported beside it.
+	**/
+	metrics(snapshot, options) {
+		const data = this.#marketData(snapshot);
+		const factor = (safePrices) => calcHealthFactor({
+			snapshot,
+			underlying: data.underlying,
+			decimals: data.decimals,
+			prices: data.prices,
+			reservePrices: data.reservePrices,
+			safePrices,
+			liquidationThresholds: data.liquidationThresholds,
+			activeQuotas: data.activeQuotas
+		});
+		const healthFactor = factor(false);
+		const borrowRate = calcBorrowRate({
+			snapshot,
+			baseInterestRate: this.#baseInterestRate(snapshot, data, options),
+			feeInterest: data.feeInterest,
+			quotaRates: data.quotaRates,
+			resolveToken: (address) => this.sdk.tokensMeta.mustGetToken(address)
+		});
+		return {
+			healthFactor,
+			safeHealthFactor: factor(true),
+			borrowRate,
+			timeToLiquidation: calcTimeToLiquidationMs(healthFactor, BigInt(borrowRate.totalOnDebt)),
+			liquidationPrice: calcLiquidationPrice({
+				snapshot,
+				underlying: data.underlying,
+				decimals: data.decimals,
+				liquidationThresholds: data.liquidationThresholds
+			}),
+			leverage: calcPositionLeverage(snapshot.totalValue, snapshot.totalDebt)
+		};
+	}
+	/**
+	* A projected account state as both halves of the SDK report it: the holdings
+	* priced and named, and the metrics of {@link PositionsService.metrics}.
+	*
+	* The snapshot is taken at its word — what it lists is what comes back, so a
+	* caller that drops dust before the walk reports an account without it, and
+	* one that keeps wei reports them. That is the whole of the policy left to
+	* the caller; everything downstream of the balances is decided here.
+	*
+	* @param options - The operation's effect on the pool, for the rate the
+	* metrics are quoted at, see {@link ProjectedPoolOptions}.
+	**/
+	projection(snapshot, options) {
+		const { creditManager, totalValue, totalDebt } = snapshot;
+		const market = this.sdk.marketRegister.findByCreditManager(creditManager);
+		const { priceOracle } = market;
+		return {
+			...this.sdk.marketRegister.findCreditManager(creditManager).creditOperationMarket(),
+			totalValue: market.toUnderlyingAmount(totalValue),
+			totalDebt: market.toUnderlyingAmount(totalDebt),
+			netValue: market.toUnderlyingAmount(totalValue - totalDebt),
+			assets: snapshot.assets.map((a) => priceOracle.toTokenAmount(a.token, a.balance)),
+			quotas: snapshot.quotas.map((q) => ({
+				token: this.sdk.tokensMeta.mustGetToken(q.token),
+				...priceOracle.toAmount(market.underlying, q.balance)
+			})),
+			...this.metrics(snapshot, options)
+		};
+	}
+	/**
+	* 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 = suite.underlyingToken;
+		const totalDebtValue = ca.debt + ca.accruedInterest + ca.accruedFees;
+		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 = {
+			...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: suite.accountStrategyName(ca.creditAccount),
+			targetCollateral: suite.accountTargetCollateral(ca.creditAccount),
+			leverage: calcPositionLeverage(totalValue, totalDebtValue),
+			borrowApy: calcBorrowApy(pool.baseInterestRate, suite.creditManager.feeInterest),
+			totalDebt: {
+				token,
+				value: totalDebtValue,
+				valueUsd: usdToNumber(totalDebtUSD)
+			},
+			totalValue: {
+				token,
+				value: totalValue,
+				valueUsd: usdToNumber(totalValueUSD)
+			},
+			healthFactor: priceFailed ? this.healthFactor(snapshot) : healthFactorBps(ca.healthFactor),
+			borrowRate,
+			timeToLiquidation,
+			liquidationPrice,
+			collaterals,
+			...priceFailed ? { error: 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 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;
+	}
+	/**
+	* Maps compressor withdrawals into the read model's vocabulary.
+	**/
+	#toPositionWithdrawals(raw, priceOracle) {
+		return {
+			claimable: raw.claimable.map((w) => this.#toPositionClaimableWithdrawal(w, priceOracle)),
+			pending: raw.pending.map((w) => this.#toPositionPendingWithdrawal(w, priceOracle))
+		};
+	}
+	#toPositionClaimableWithdrawal(w, priceOracle) {
+		return {
+			sourceToken: this.sdk.tokensMeta.mustGetToken(w.token),
+			withdrawalPhantomToken: priceOracle.toTokenAmount(w.withdrawalPhantomToken, w.withdrawalTokenSpent),
+			outputs: w.outputs.map((o) => priceOracle.toTokenAmount(o.token, o.amount)),
+			claimCall: this.#claimTx(w.claimCalls, w.token),
+			redeemer: w.redeemer,
+			intent: w.intent
+		};
+	}
+	#toPositionPendingWithdrawal(w, priceOracle) {
+		return {
+			sourceToken: this.sdk.tokensMeta.mustGetToken(w.token),
+			withdrawalPhantomToken: this.sdk.tokensMeta.mustGetToken(w.withdrawalPhantomToken),
+			expectedOutputs: w.expectedOutputs.map((o) => priceOracle.toTokenAmount(o.token, o.amount)),
+			claimableAt: Number(w.claimableAt),
+			redeemer: w.redeemer,
+			intent: w.intent
+		};
+	}
+	/**
+	* Subcompressors always report exactly one adapter call per claimable
+	* withdrawal.
+	**/
+	#claimTx(claimCalls, sourceToken) {
+		const call = claimCalls[0];
+		if (claimCalls.length !== 1 || !call) throw new Error(`expected exactly one claim call for withdrawal of ${sourceToken}, got ${claimCalls.length}`);
+		return {
+			to: call.target,
+			callData: call.callData
+		};
+	}
+	/**
+	* 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
+export { PositionsService };

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

@@ -0,0 +1,46 @@
+import { AddressMap } from "../utils/AddressMap.js";
+import { PERCENTAGE_FACTOR } from "../constants/math.js";
+import { calcBorrowApy } from "../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 AddressMap(Object.entries(quotaRates));
+	const base = calcBorrowApy(baseInterestRate, feeInterest);
+	const fee = 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 / PERCENTAGE_FACTOR;
+		perQuota.push({
+			token: resolveToken(q.token),
+			rate: totalValue > 0n ? Number(withFee / totalValue) : 0
+		});
+	}
+	const quotaRateSumWithFee = quotaRateSum * fee / 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
+export { calcBorrowRate };

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

@@ -0,0 +1,51 @@
+import { AddressMap } from "../utils/AddressMap.js";
+import { BigIntMath } from "../utils/bigint-math.js";
+import { MAX_UINT16, PERCENTAGE_FACTOR } from "../constants/math.js";
+import { isAddressEqual } from "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(MAX_UINT16);
+	const decimalsByToken = new AddressMap(Object.entries(decimals));
+	const pricesByToken = new AddressMap(Object.entries(prices));
+	const reservePricesByToken = new AddressMap(Object.entries(reservePrices));
+	const lts = new AddressMap(Object.entries(liquidationThresholds));
+	const active = new 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 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) => isAddressEqual(q.token, token));
+		const quotaBalance = quota && (active.get(token) ?? false) ? quota.balance : 0n;
+		const quotaWeighted = (convertToUSD(underlying, quotaBalance) ?? 0n) * PERCENTAGE_FACTOR;
+		return acc + (quota ? BigIntMath.min(quotaWeighted, tokenLtWeighted) : tokenLtWeighted);
+	}, 0n);
+	const borrowedMoney = convertToUSD(underlying, snapshot.totalDebt) ?? 0n;
+	const hf = borrowedMoney > 0n ? assetMoney / borrowedMoney : 0n;
+	return Number(hf);
+}
+//#endregion
+export { calcHealthFactor };

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

@@ -0,0 +1,31 @@
+import "../constants/math.js";
+import { calcLiquidationPriceForTarget } from "./calcLiquidationPriceForTarget.js";
+import { isAddressEqual } from "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 targetToken = soleNonUnderlyingCollateral(props.snapshot, props.underlying);
+	if (!targetToken) return null;
+	return calcLiquidationPriceForTarget({
+		...props,
+		targetToken
+	});
+}
+/**
+* The one collateral a liquidation price — and the current price beside it —
+* can be quoted for: the account's single non-dust, non-underlying asset.
+* `null` when it holds none or several, which is the case neither figure
+* exists for.
+**/
+function soleNonUnderlyingCollateral(snapshot, underlying) {
+	const targets = snapshot.assets.filter((a) => a.balance > 10n && !isAddressEqual(a.token, underlying));
+	return targets.length === 1 ? targets[0].token : null;
+}
+//#endregion
+export { calcLiquidationPrice, soleNonUnderlyingCollateral };

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

@@ -0,0 +1,29 @@
+import { AddressMap } from "../utils/AddressMap.js";
+import { PERCENTAGE_FACTOR, PRICE_DECIMALS, WAD } from "../constants/math.js";
+import { isAddressEqual } from "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 AddressMap(Object.entries(decimals));
+	const lts = new AddressMap(Object.entries(liquidationThresholds));
+	const underlyingDecimals = decimalsByToken.get(underlying) ?? 18;
+	const underlyingBalance = snapshot.assets.find((a) => isAddressEqual(a.token, underlying))?.balance ?? 0n;
+	const ltUnderlying = BigInt(lts.get(underlying) ?? 0);
+	const effectiveDebt = (snapshot.totalDebt - underlyingBalance * ltUnderlying / PERCENTAGE_FACTOR) * WAD / 10n ** BigInt(underlyingDecimals);
+	const targetDecimals = decimalsByToken.get(targetToken) ?? 18;
+	const targetBalance = snapshot.assets.find((a) => isAddressEqual(a.token, targetToken))?.balance ?? 0n;
+	const effectiveTargetBalance = targetBalance * WAD / 10n ** BigInt(targetDecimals);
+	const lpLT = BigInt(lts.get(targetToken) ?? 0);
+	if (targetBalance <= 10n || lpLT <= 0n) return 0n;
+	return effectiveDebt * PRICE_DECIMALS * PERCENTAGE_FACTOR / (effectiveTargetBalance * lpLT);
+}
+//#endregion
+export { calcLiquidationPriceForTarget };

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

@@ -0,0 +1,18 @@
+import { PERCENTAGE_FACTOR, SECONDS_PER_YEAR } from "../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) - PERCENTAGE_FACTOR) * (BigInt(SECONDS_PER_YEAR) * PERCENTAGE_FACTOR / totalBorrowRateOnDebt) * 1000n / PERCENTAGE_FACTOR;
+}
+//#endregion
+export { calcTimeToLiquidationMs };

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

@@ -0,0 +1,9 @@
+import { calcBorrowRate } from "./calcBorrowRate.js";
+import { calcHealthFactor } from "./calcHealthFactor.js";
+import { calcLiquidationPriceForTarget } from "./calcLiquidationPriceForTarget.js";
+import { calcLiquidationPrice, soleNonUnderlyingCollateral } from "./calcLiquidationPrice.js";
+import { calcTimeToLiquidationMs } from "./calcTimeToLiquidationMs.js";
+import { MultichainPositionsService } from "./MultichainPositionsService.js";
+import { accountSnapshotFromCreditAccountData } from "./types.js";
+import { PositionsService } from "./PositionsService.js";
+export { MultichainPositionsService, PositionsService, accountSnapshotFromCreditAccountData, calcBorrowRate, calcHealthFactor, calcLiquidationPrice, calcLiquidationPriceForTarget, calcTimeToLiquidationMs, soleNonUnderlyingCollateral };

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

@@ -0,0 +1,29 @@
+import "../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
+export { accountSnapshotFromCreditAccountData };