@xoxno/sdk-js 1.0.224 → 1.0.226

package/dist/esm/sdk/stellar/math/limits.js

@@ -0,0 +1,273 @@
+/**
+ * Largest valid amount per action, in token base units, with the reason that
+ * binds. Mirrors the gates the contract enforces rather than capping:
+ *
+ * - risk gate: `contracts/controller/src/risk/validation.rs`
+ *   `require_post_pool_risk_gates` (debt ≤ `min(LTV, threshold)`-weighted
+ *   collateral, HF ≥ 1, `ltv_collateral ≥ min_borrow_collateral_usd`);
+ * - listing flags: `positions/mod.rs::enforce_spoke_asset_flags`
+ *   (`paused` blocks every verb, `frozen` blocks entry only);
+ * - spoke caps: `formulas.md` §Caps (native units, no unlimited sentinel);
+ * - pool cash and the 200 BPS liquidation buffer:
+ *   `contracts/pool/src/guards.rs::require_liquidation_buffer`;
+ * - hub utilization ceiling: `guards.rs::require_utilization_below_max`
+ *   (skipped when `max_utilization >= RAY`; repay and liquidation are exempt).
+ *
+ * Hub totals and pool cash come from the `*Short` display numbers on
+ * `ReserveDto`, so cap / liquidity / utilization candidates are exact only to
+ * the double precision of those fields; the risk-gate candidate is exact.
+ * xoxno-ui parity: `stellar-limits.ts::computeStellarLimits`,
+ * `utils.ts::calculateMaxBorrow / calculateMaxSupply / calculateMaxRemove`.
+ */ import { buildLiveSnapshot, burnShares, liveIndexKey, mintShares } from "./account.js";
+import { utilizationRay } from "./rates.js";
+import { BPS, RAY, baseToRay, baseToShort, mulDivCeil, mulDivFloor, mulDivHalfUp, numberToScaled, numberToWad, positionValueWad, toBigInt, unscale } from "./scaled.js";
+/** `common/src/constants/pool.rs::LIQUIDATION_BUFFER_BPS`. */ export const LIQUIDATION_BUFFER_BPS = 200n;
+const pickMin = (candidates)=>candidates.reduce((best, c)=>c.amount < best.amount ? c : best);
+const nonNegative = (v)=>v < 0n ? 0n : v;
+const finish = (chosen, decimals, isFullClose, projectedUtilization)=>({
+        amountBase: chosen.amount,
+        amountShort: baseToShort(chosen.amount, decimals),
+        isFullClose,
+        reason: chosen.reason,
+        projectedUtilization
+    });
+const zero = (reason)=>({
+        amountBase: 0n,
+        amountShort: 0,
+        isFullClose: false,
+        reason,
+        projectedUtilization: null
+    });
+/**
+ * Reserve totals in base units from the API's display numbers.
+ *
+ * Assumption (Unverified against the API source): `availableLiquidityShort`
+ * is the hub pool's cash (`pool/cache/mod.rs::cash()`), the base both
+ * `require_reserves` and the liquidation buffer are checked against. The DTO
+ * describes it only as "Available liquidity / cash" without a scope marker
+ * while `suppliedShort` / `borrowedShort` are marked spoke-scoped and
+ * `HubPoolDto` carries no cash field; if the API serves it spoke-scoped the
+ * `liquidity` candidates are computed against the wrong base.
+ */ function hubTotals(reserve) {
+    const d = reserve.assetDecimals;
+    const maxUtil = toBigInt(reserve.irm.maxUtilizationRay, 'irm.maxUtilizationRay');
+    return {
+        suppliedBase: numberToScaled(reserve.hubPool.suppliedShort, d),
+        borrowedBase: numberToScaled(reserve.hubPool.borrowedShort, d),
+        cashBase: numberToScaled(reserve.availableLiquidityShort, d),
+        spokeSuppliedBase: numberToScaled(reserve.suppliedShort, d),
+        spokeBorrowedBase: numberToScaled(reserve.borrowedShort, d),
+        maxUtilizationRay: maxUtil >= RAY ? null : maxUtil
+    };
+}
+const projectedUtil = (suppliedBase, borrowedBase)=>suppliedBase <= 0n ? null : Number(borrowedBase) / Number(suppliedBase);
+/** Price the reserve the way `computeAccountRisk` would: accepted live row, else `reserve.usdPrice`. */ function reservePriceWad(reserve, liveState) {
+    return buildLiveSnapshot(liveState).prices.get(reserve.asset) ?? numberToWad(reserve.usdPrice);
+}
+/**
+ * Largest `x` in `[0, hi]` with `ok(x)` true, for a predicate that is true on
+ * a prefix (every gate here is monotone in the amount). Binary search, so the
+ * estimate feeding `hi` only needs to be an upper bound: rounding slack in the
+ * gates is not bounded in base units (an 18-decimal token at $0.01 needs
+ * hundreds of single-unit steps), so no fixed decrement count is safe.
+ */ function fitMax(hi, ok) {
+    if (hi <= 0n || !ok(0n)) return 0n;
+    let lo = 0n // ok
+    ;
+    let bad = hi + 1n;
+    while(bad - lo > 1n){
+        const mid = (lo + bad) / 2n;
+        if (ok(mid)) lo = mid;
+        else bad = mid;
+    }
+    return lo;
+}
+/** Slack added to a rounding-free estimate before searching, so the exact answer is never above `hi`. */ const ESTIMATE_SLACK = 16n;
+/** Largest borrow keeping `half_up(borrowed / supplied) <= maxUtilization`; null when the guard does not apply. */ function utilizationBorrowCap(totals, decimals) {
+    const max = totals.maxUtilizationRay;
+    if (max === null) return null;
+    const suppliedRay = baseToRay(totals.suppliedBase, decimals);
+    // `require_utilization_below_max` returns early with no supply; cash then binds.
+    if (suppliedRay === 0n) return null;
+    const estimate = nonNegative(mulDivFloor(totals.suppliedBase, max, RAY) - totals.borrowedBase);
+    return fitMax(estimate + ESTIMATE_SLACK, (x)=>utilizationRay(baseToRay(totals.borrowedBase + x, decimals), suppliedRay) <= max);
+}
+/** Largest withdraw keeping `half_up(borrowed / (supplied - x)) <= maxUtilization`; null when unbounded. */ function utilizationWithdrawCap(totals, decimals) {
+    const max = totals.maxUtilizationRay;
+    if (max === null || totals.borrowedBase === 0n) return null;
+    if (max === 0n) return 0n;
+    const minSupplied = mulDivCeil(totals.borrowedBase, RAY, max);
+    const hi = totals.suppliedBase < minSupplied ? 0n : totals.suppliedBase - minSupplied + ESTIMATE_SLACK;
+    const borrowedRay = baseToRay(totals.borrowedBase, decimals);
+    return fitMax(hi > totals.suppliedBase ? totals.suppliedBase : hi, (x)=>{
+        const remaining = baseToRay(totals.suppliedBase - x, decimals);
+        return remaining > 0n && utilizationRay(borrowedRay, remaining) <= max;
+    });
+}
+const findPosition = (list, reserve)=>list.find((p)=>p.hubId === reserve.hubId && p.asset === reserve.asset);
+/**
+ * Largest borrow of `reserve` the account can open now. Candidates, all in
+ * base units:
+ *
+ * - LTV gate: the contract mints `calculate_scaled_borrow` (ceil) shares,
+ *   merges them into the existing debt leg and requires
+ *   `ltv_collateral >= total_debt` with the merged leg valued by
+ *   `position_value_ceil` (`ops/borrow.rs::mint_debt`, `risk/totals.rs`,
+ *   `risk/validation.rs`). The search runs on exactly that predicate, with
+ *   the index and price `computeAccountRisk` used for the leg (else the
+ *   accepted live row, else `reserve.liveBorrowIndexRay` / `reserve.usdPrice`).
+ * - min-collateral floor, spoke borrow-cap headroom, pool cash minus the
+ *   liquidation buffer, and the hub utilization ceiling.
+ *
+ * A reserve that is not borrowable reports 0 with reason `cap` (same effect
+ * as a zero `borrowCap`).
+ */ export function maxBorrow(risk, reserve, liveState) {
+    if (reserve.paused) return zero('paused');
+    if (reserve.frozen) return zero('frozen');
+    if (!reserve.isBorrowable) return zero('cap');
+    const d = reserve.assetDecimals;
+    const totals = hubTotals(reserve);
+    const existing = findPosition(risk.borrows, reserve);
+    const liveRow = buildLiveSnapshot(liveState).indexes.get(liveIndexKey(reserve.hubId, reserve.asset));
+    const indexRay = existing ? BigInt(existing.indexRay) : toBigInt(liveRow?.borrowIndex ?? reserve.liveBorrowIndexRay, 'borrowIndex');
+    const priceWad = existing ? BigInt(existing.usdPriceWad) : reservePriceWad(reserve, liveState);
+    const existingScaled = existing ? BigInt(existing.scaledRay) : 0n;
+    const otherDebt = BigInt(risk.totalDebtUsdWad) - (existing ? BigInt(existing.usdWad) : 0n);
+    const ltvCollateral = BigInt(risk.ltvWeightedCollateralUsdWad);
+    const floorWad = BigInt(risk.minBorrowCollateralUsdWad);
+    const candidates = [];
+    if (ltvCollateral < floorWad) {
+        candidates.push({
+            amount: 0n,
+            reason: 'minCollateral'
+        });
+    } else {
+        const headroom = ltvCollateral - BigInt(risk.totalDebtUsdWad);
+        const estimate = headroom <= 0n || priceWad <= 0n ? 0n : mulDivFloor(headroom, 10n ** BigInt(d), priceWad);
+        const debtAfter = (x)=>otherDebt + positionValueWad(existingScaled + mintShares('borrow', x, d, indexRay), indexRay, priceWad, 'ceil');
+        candidates.push({
+            amount: estimate === 0n ? 0n : fitMax(estimate + ESTIMATE_SLACK, (x)=>debtAfter(x) <= ltvCollateral),
+            reason: 'ltv'
+        });
+    }
+    candidates.push({
+        amount: nonNegative(toBigInt(reserve.borrowCap, 'borrowCap') - totals.spokeBorrowedBase),
+        reason: 'cap'
+    });
+    const buffer = mulDivHalfUp(totals.suppliedBase, LIQUIDATION_BUFFER_BPS, BPS);
+    candidates.push({
+        amount: nonNegative(totals.cashBase - buffer),
+        reason: 'liquidity'
+    });
+    const utilCap = utilizationBorrowCap(totals, d);
+    if (utilCap !== null) candidates.push({
+        amount: utilCap,
+        reason: 'utilizationCap'
+    });
+    const chosen = pickMin(candidates);
+    return finish(chosen, d, false, projectedUtil(totals.suppliedBase, totals.borrowedBase + chosen.amount));
+}
+/**
+ * Largest withdraw of the account's `reserve` supply. Candidates: the risk
+ * gate (LTV-weighted collateral must stay ≥ `max(debt, floor)` — reported as
+ * `healthFactor`, or `minCollateral` when the floor is the stricter bound),
+ * pool cash, and the hub utilization ceiling. `paused` reports 0. When the
+ * whole position can go, `amountBase` is the floor payout and `isFullClose`
+ * is true — sign `"0"` so the contract takes the withdraw-all path
+ * (`resolve_withdrawal` treats any request ≥ the half-up balance as full).
+ * The position is priced as `risk` valued it, so `_liveState` is accepted for
+ * signature symmetry with {@link maxBorrow} but not consulted.
+ */ export function maxWithdraw(risk, reserve, _liveState) {
+    if (reserve.paused) return zero('paused');
+    const pos = findPosition(risk.supplies, reserve);
+    if (!pos) return zero(null);
+    const d = pos.decimals;
+    const totals = hubTotals(reserve);
+    const scaled = BigInt(pos.scaledRay);
+    const index = BigInt(pos.indexRay);
+    const price = BigInt(pos.usdPriceWad);
+    const payout = BigInt(pos.amountBase);
+    const halfUp = unscale(scaled, index, d, 'halfUp');
+    const debt = BigInt(risk.totalDebtUsdWad);
+    const floorWad = BigInt(risk.minBorrowCollateralUsdWad);
+    const bps = BigInt(Math.min(pos.entryLtvBps, pos.entryLiquidationThresholdBps));
+    const candidates = [];
+    let fullAllowed = true;
+    if (debt > 0n && bps > 0n) {
+        const required = debt > floorWad ? debt : floorWad;
+        const reason = floorWad > debt ? 'minCollateral' : 'healthFactor';
+        const others = BigInt(risk.ltvWeightedCollateralUsdWad) - BigInt(pos.ltvWeightedUsdWad);
+        if (others < required) {
+            fullAllowed = false;
+            const need = required - others;
+            const keepGateWad = mulDivCeil(need, BPS, bps);
+            const removableWad = BigInt(pos.gateUsdWad) - keepGateWad;
+            const estimate = removableWad <= 0n ? 0n : mulDivFloor(removableWad, 10n ** BigInt(d), price);
+            // A partial request at or above the half-up balance becomes a full close.
+            const partialMax = halfUp > 0n ? halfUp - 1n : 0n;
+            const hi = estimate + ESTIMATE_SLACK > partialMax ? partialMax : estimate + ESTIMATE_SLACK;
+            const ltvAfter = (amount)=>{
+                const burned = burnShares('supply', amount, d, index);
+                const remaining = burned >= scaled ? 0n : scaled - burned;
+                return mulDivFloor(positionValueWad(remaining, index, price, 'floor'), bps, BPS);
+            };
+            candidates.push({
+                amount: fitMax(hi, (x)=>ltvAfter(x) >= need),
+                reason
+            });
+        }
+    }
+    candidates.push({
+        amount: payout,
+        reason: null
+    });
+    candidates.push({
+        amount: totals.cashBase,
+        reason: 'liquidity'
+    });
+    const utilCap = utilizationWithdrawCap(totals, d);
+    if (utilCap !== null) candidates.push({
+        amount: utilCap,
+        reason: 'utilizationCap'
+    });
+    const chosen = pickMin(candidates);
+    const isFullClose = fullAllowed && chosen.amount >= payout;
+    return finish(chosen, d, isFullClose, projectedUtil(totals.suppliedBase - chosen.amount, totals.borrowedBase));
+}
+/**
+ * Largest supply into `reserve`: the spoke supply-cap headroom
+ * (`supplyCap - spoke supplied`, always enforced, `0` closes the side).
+ * `paused` and `frozen` both block entry.
+ */ export function maxSupply(reserve) {
+    if (reserve.paused) return zero('paused');
+    if (reserve.frozen) return zero('frozen');
+    const d = reserve.assetDecimals;
+    const totals = hubTotals(reserve);
+    const chosen = {
+        amount: nonNegative(toBigInt(reserve.supplyCap, 'supplyCap') - totals.spokeSuppliedBase),
+        reason: 'cap'
+    };
+    return finish(chosen, d, false, projectedUtil(totals.suppliedBase + chosen.amount, totals.borrowedBase));
+}
+/**
+ * Largest repay of the account's `reserve` debt: the ceil-rounded debt
+ * (`unscale_borrow_ceil`, which `resolve_repay` treats as a full close and
+ * refunds anything above), bounded by `walletBalance` (base units) when
+ * given — reported as `liquidity`. `paused` reports 0.
+ */ export function maxRepay(risk, reserve, walletBalance) {
+    if (reserve.paused) return zero('paused');
+    const pos = findPosition(risk.borrows, reserve);
+    if (!pos) return zero(null);
+    const d = pos.decimals;
+    const totals = hubTotals(reserve);
+    const debt = BigInt(pos.amountBase);
+    const wallet = walletBalance === undefined ? null : toBigInt(walletBalance, 'walletBalance');
+    const chosen = wallet !== null && wallet < debt ? {
+        amount: wallet,
+        reason: 'liquidity'
+    } : {
+        amount: debt,
+        reason: null
+    };
+    return finish(chosen, d, chosen.amount >= debt, projectedUtil(totals.suppliedBase, nonNegative(totals.borrowedBase - chosen.amount)));
+}

package/dist/esm/sdk/stellar/math/projection.js

@@ -0,0 +1,130 @@
+/**
+ * What-if projections: account risk after hypothetical position changes and
+ * reserve rates after hypothetical pool flows. Reuses the same aggregation
+ * (`aggregateAccountRisk`) and curve (`rates.ts`) as the live computations.
+ * xoxno-ui parity: `utils.ts::getProjectedHealthPercentage`,
+ * `getProjectedUtilization`, `getApyProjection`.
+ */ import { aggregateAccountRisk, burnShares, mintShares, valueBasePosition, valueScaledPosition } from "./account.js";
+import { annualBorrowRateRay, depositRateRay, rayAprToApy, rayAprToNumber, utilizationRay } from "./rates.js";
+import { baseToRay, numberToScaled, numberToWad, rayToNumber, toBigInt, unscale } from "./scaled.js";
+const sameLeg = (p, d)=>p.hubId === d.hubId && p.asset === d.asset;
+const signedBigInt = (value)=>{
+    if (typeof value === 'bigint') return value;
+    const trimmed = value.trim();
+    if (!/^-?\d+$/.test(trimmed)) throw new Error(`Stellar math: delta amountBase must be an integer string, got "${value}"`);
+    return BigInt(trimmed);
+};
+/**
+ * Re-value the account after applying `deltas`, moving shares the way the
+ * pool does. Existing legs change in shares (`mintShares` on entry,
+ * `burnShares` on a partial exit; a withdraw ≥ the half-up balance or a
+ * repay ≥ the ceil debt burns every share) and are revalued with
+ * `valueScaledPosition`; a new leg is minted from `amountBase`
+ * (`valueBasePosition`) and takes its index, price and entry weights from
+ * `delta.reserve` (no live price: pass the reserve you would supply into).
+ * A leg driven to zero is dropped. The min-collateral floor and
+ * `liveDataValid` carry over from `risk`.
+ */ export function projectAccountRisk(risk, deltas) {
+    const supplies = [
+        ...risk.supplies
+    ];
+    const borrows = [
+        ...risk.borrows
+    ];
+    for (const delta of deltas){
+        const list = delta.side === 'supply' ? supplies : borrows;
+        const idx = list.findIndex((p)=>sameLeg(p, delta));
+        const existing = idx === -1 ? undefined : list[idx];
+        const change = signedBigInt(delta.amountBase);
+        let projected;
+        if (!existing) {
+            projected = change <= 0n ? null : valueBasePosition(seedFromReserve(delta), change);
+        } else {
+            const seed = {
+                side: existing.side,
+                hubId: existing.hubId,
+                asset: existing.asset,
+                decimals: existing.decimals,
+                indexRay: BigInt(existing.indexRay),
+                priceWad: BigInt(existing.usdPriceWad),
+                entryLtvBps: existing.entryLtvBps,
+                entryLiquidationThresholdBps: existing.entryLiquidationThresholdBps,
+                entryLiquidationBonusBps: existing.entryLiquidationBonusBps,
+                entryLiquidationFeesBps: existing.entryLiquidationFeesBps,
+                liveDataUsed: existing.liveDataUsed
+            };
+            const scaled = BigInt(existing.scaledRay);
+            let next;
+            if (change >= 0n) {
+                next = scaled + mintShares(seed.side, change, seed.decimals, seed.indexRay);
+            } else {
+                const exit = -change;
+                const closeAt = seed.side === 'supply' ? unscale(scaled, seed.indexRay, seed.decimals, 'halfUp') : BigInt(existing.amountBase);
+                const burned = exit >= closeAt ? scaled : burnShares(seed.side, exit, seed.decimals, seed.indexRay);
+                next = burned >= scaled ? 0n : scaled - burned;
+            }
+            projected = next === 0n ? null : valueScaledPosition({
+                ...seed,
+                scaledRay: next
+            });
+        }
+        if (idx === -1) {
+            if (projected) list.push(projected);
+        } else if (projected) {
+            list[idx] = projected;
+        } else {
+            list.splice(idx, 1);
+        }
+    }
+    return aggregateAccountRisk({
+        accountId: risk.accountId,
+        owner: risk.owner,
+        spokeId: risk.spokeId,
+        mode: risk.mode
+    }, supplies, borrows, BigInt(risk.minBorrowCollateralUsdWad), risk.liveDataValid);
+}
+function seedFromReserve(delta) {
+    const reserve = delta.reserve;
+    if (!reserve) {
+        throw new Error(`Stellar math: projectAccountRisk needs \`reserve\` for a new ${delta.side} position on ${delta.hubId}:${delta.asset}`);
+    }
+    return {
+        side: delta.side,
+        hubId: delta.hubId,
+        asset: delta.asset,
+        decimals: reserve.assetDecimals,
+        indexRay: toBigInt(delta.side === 'supply' ? reserve.liveSupplyIndexRay : reserve.liveBorrowIndexRay, 'reserve live index'),
+        priceWad: numberToWad(reserve.usdPrice),
+        entryLtvBps: reserve.collateralFactorBps,
+        entryLiquidationThresholdBps: reserve.liquidationThresholdBps,
+        entryLiquidationBonusBps: reserve.liquidationPenaltyBps,
+        entryLiquidationFeesBps: reserve.liquidationFeesBps,
+        liveDataUsed: false
+    };
+}
+/**
+ * Hub rates after adding `supplyDeltaBase` / `borrowDeltaBase` (signed base
+ * units) to the reserve's hub-pool totals. Utilization is
+ * `curve.rs::utilization` over the projected totals; rates follow
+ * `annualBorrowRateRay` / `depositRateRay`. Whether `ReserveDto.supplyApy`
+ * / `borrowApy` are simple or compounded is not pinned by the API contract,
+ * so both `*Apr` and `*Apy` are returned.
+ */ export function projectReserveApy(reserve, supplyDeltaBase = 0n, borrowDeltaBase = 0n) {
+    const d = reserve.assetDecimals;
+    const clamp = (v)=>v < 0n ? 0n : v;
+    const supplied = clamp(numberToScaled(reserve.hubPool.suppliedShort, d) + signedBigInt(supplyDeltaBase));
+    const borrowed = clamp(numberToScaled(reserve.hubPool.borrowedShort, d) + signedBigInt(borrowDeltaBase));
+    const util = utilizationRay(baseToRay(borrowed, d), baseToRay(supplied, d));
+    const borrowRate = annualBorrowRateRay(util, reserve.irm);
+    const supplyRate = depositRateRay(util, borrowRate, reserve.irm.reserveFactorBps);
+    return {
+        utilization: rayToNumber(util),
+        utilizationRay: util.toString(),
+        borrowAprRay: borrowRate.toString(),
+        supplyAprRay: supplyRate.toString(),
+        borrowApr: rayAprToNumber(borrowRate),
+        supplyApr: rayAprToNumber(supplyRate),
+        borrowApy: rayAprToApy(borrowRate),
+        supplyApy: rayAprToApy(supplyRate)
+    };
+}

package/dist/esm/sdk/stellar/math/rates.js

@@ -0,0 +1,62 @@
+/**
+ * Interest-rate curve mirror of `rs-lending-xlm/common/src/rates/curve.rs`.
+ * Annual RAY in, annual RAY out; `Ray::mul` / `Ray::div` are half-up
+ * (`fp.rs`), matching the pool's view getters.
+ */ import { BPS, RAY, mulDivHalfUp, rayToNumber, toBigInt } from "./scaled.js";
+/** `Ray::mul` — half_up(a * b / RAY). */ const rayMul = (a, b)=>mulDivHalfUp(a, b, RAY);
+/** `Ray::div` — half_up(a * RAY / b). */ const rayDiv = (a, b)=>mulDivHalfUp(a, RAY, b);
+/**
+ * `curve.rs::utilization` — `borrowed / supplied` half-up in RAY; zero when
+ * nothing is supplied. The contract feeds it half-up-valued debt and supply
+ * (`formulas.md` §Utilization and annual rates).
+ */ export function utilizationRay(borrowedRay, suppliedRay) {
+    if (suppliedRay === 0n) return 0n;
+    return rayDiv(borrowedRay, suppliedRay);
+}
+/**
+ * `curve.rs::calculate_annual_borrow_rate` — three-segment piecewise-linear
+ * curve. Utilization is clamped to one RAY; below `mid` the rate ramps from
+ * `base` by `slope1`, between `mid` and `optimal` by `slope2`, above
+ * `optimal` by `slope3`; the result is capped at `maxBorrowRate`.
+ */ export function annualBorrowRateRay(utilization, irm) {
+    const u = utilization > RAY ? RAY : utilization;
+    const base = toBigInt(irm.baseRateRay, 'irm.baseRateRay');
+    const slope1 = toBigInt(irm.slope1Ray, 'irm.slope1Ray');
+    const slope2 = toBigInt(irm.slope2Ray, 'irm.slope2Ray');
+    const slope3 = toBigInt(irm.slope3Ray, 'irm.slope3Ray');
+    const mid = toBigInt(irm.midUtilizationRay, 'irm.midUtilizationRay');
+    const optimal = toBigInt(irm.optimalUtilizationRay, 'irm.optimalUtilizationRay');
+    const max = toBigInt(irm.maxBorrowRateRay, 'irm.maxBorrowRateRay');
+    let rate;
+    if (u < mid) {
+        rate = base + rayDiv(rayMul(u, slope1), mid);
+    } else if (u < optimal) {
+        const range = optimal - mid;
+        rate = base + slope1 + rayDiv(rayMul(u - mid, slope2), range);
+    } else {
+        const excess = u - optimal;
+        const range = RAY - optimal;
+        // `optimal == RAY` forces `u == RAY` (clamped) so `excess == 0`; the contract
+        // would trap on the zero divisor, the SDK reports the kink rate instead.
+        const contribution = range === 0n ? 0n : rayDiv(rayMul(excess, slope3), range);
+        rate = base + slope1 + slope2 + contribution;
+    }
+    return rate > max ? max : rate;
+}
+/**
+ * `curve.rs::calculate_deposit_rate` — supplier rate after the reserve factor:
+ * `half_up(half_up(u * borrowRate / RAY) * (BPS - rf) / BPS)`. Zero at zero
+ * utilization or a reserve factor outside `0..BPS`.
+ */ export function depositRateRay(utilization, borrowRateRay, reserveFactorBps) {
+    if (utilization === 0n) return 0n;
+    if (!Number.isInteger(reserveFactorBps) || reserveFactorBps < 0 || reserveFactorBps >= 10000) return 0n;
+    const rateXUtil = rayMul(utilization, borrowRateRay);
+    return mulDivHalfUp(rateXUtil, BPS - BigInt(reserveFactorBps), BPS);
+}
+/** Annual RAY rate → simple APR as a fraction (`0.05` = 5%). */ export const rayAprToNumber = (rateRay)=>rayToNumber(rateRay);
+/**
+ * Annual RAY rate → continuously compounded APY fraction, `e^apr − 1`. The
+ * pool compounds per millisecond with an eighth-order Taylor series
+ * (`compound.rs`), which the continuous exponential approximates to well
+ * within display precision.
+ */ export const rayAprToApy = (rateRay)=>Math.expm1(rayToNumber(rateRay));

package/dist/esm/sdk/stellar/math/scaled.js

@@ -0,0 +1,156 @@
+/**
+ * Contract-exact fixed-point primitives for the Stellar lending math module.
+ *
+ * Mirrors `rs-lending-xlm/common/src/math/fp_core.rs` (`mul_div_*`,
+ * `rescale_*`, `div_by_int_half_up`), `common/src/math/fp.rs` (`Ray`, `Wad`)
+ * and `common/src/rates/scaling.rs` (`unscale_supply_floor`,
+ * `unscale_borrow_ceil`). All arithmetic is native `BigInt` on the raw decimal
+ * strings the API serves; nothing here touches floating point except the
+ * `*Short` display converters at the bottom.
+ *
+ * Every helper assumes the contract's non-negative domain (`Ray`, `Wad` and
+ * position balances are never negative on-chain); {@link toBigInt} enforces
+ * that at the string boundary.
+ */ /** 10^27 — shares, indexes, rates and utilization. */ export const RAY = 10n ** 27n;
+/** 10^18 — USD values, prices per whole token, health factor. */ export const WAD = 10n ** 18n;
+/** 10,000 — risk ratios and fees. */ export const BPS = 10000n;
+export const RAY_DECIMALS = 27;
+export const WAD_DECIMALS = 18;
+/** Parse a raw integer string (or bigint/number) into a non-negative bigint. */ export function toBigInt(value, label = 'value') {
+    let out;
+    if (typeof value === 'bigint') out = value;
+    else if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value)) {
+            throw new Error(`Stellar math: ${label} must be a safe integer, got ${value}`);
+        }
+        out = BigInt(value);
+    } else {
+        const trimmed = value.trim();
+        if (!/^-?\d+$/.test(trimmed)) {
+            throw new Error(`Stellar math: ${label} must be a decimal integer string, got "${value}"`);
+        }
+        out = BigInt(trimmed);
+    }
+    if (out < 0n) throw new Error(`Stellar math: ${label} must be non-negative, got ${out}`);
+    return out;
+}
+/** `fp_core::mul_div_floor` — floor(x * y / d) for non-negative operands. */ export function mulDivFloor(x, y, d) {
+    if (d === 0n) throw new Error('Stellar math: division by zero');
+    return x * y / d;
+}
+/** `fp_core::mul_div_ceil` — ceil(x * y / d) for non-negative operands. */ export function mulDivCeil(x, y, d) {
+    if (d === 0n) throw new Error('Stellar math: division by zero');
+    const p = x * y;
+    const q = p / d;
+    return p % d === 0n ? q : q + 1n;
+}
+/** `fp_core::mul_div_half_up` — floor((x * y + d/2) / d) for non-negative operands. */ export function mulDivHalfUp(x, y, d) {
+    if (d === 0n) throw new Error('Stellar math: division by zero');
+    return (x * y + d / 2n) / d;
+}
+/** `fp_core::div_by_int_half_up` — a / b rounded half up (non-negative a, b > 0). */ export function divByIntHalfUp(a, b) {
+    if (b === 0n) throw new Error('Stellar math: division by zero');
+    const q = a / b;
+    const r = a % b;
+    const half = b / 2n + b % 2n;
+    return r >= half ? q + 1n : q;
+}
+const pow10 = (n)=>10n ** BigInt(n);
+/** `fp_core::rescale_floor` — move `a` between decimal scales, truncating when dropping digits. */ export function rescaleFloor(a, fromDecimals, toDecimals) {
+    if (fromDecimals === toDecimals) return a;
+    if (toDecimals > fromDecimals) return a * pow10(toDecimals - fromDecimals);
+    return a / pow10(fromDecimals - toDecimals);
+}
+/** `fp_core::rescale_ceil` — like {@link rescaleFloor} but rounds a dropped remainder up. */ export function rescaleCeil(a, fromDecimals, toDecimals) {
+    if (fromDecimals === toDecimals) return a;
+    if (toDecimals > fromDecimals) return a * pow10(toDecimals - fromDecimals);
+    const factor = pow10(fromDecimals - toDecimals);
+    const q = a / factor;
+    return a % factor === 0n ? q : q + 1n;
+}
+/** `fp_core::rescale_half_up` — like {@link rescaleFloor} but rounds a dropped remainder half up. */ export function rescaleHalfUp(a, fromDecimals, toDecimals) {
+    if (fromDecimals === toDecimals) return a;
+    if (toDecimals > fromDecimals) return a * pow10(toDecimals - fromDecimals);
+    return divByIntHalfUp(a, pow10(fromDecimals - toDecimals));
+}
+const MUL_DIV = {
+    floor: mulDivFloor,
+    ceil: mulDivCeil,
+    halfUp: mulDivHalfUp
+};
+const RESCALE = {
+    floor: rescaleFloor,
+    ceil: rescaleCeil,
+    halfUp: rescaleHalfUp
+};
+/**
+ * Scaled shares → token base units with one rounding direction at both steps.
+ * `scaling.rs`: `unscale_supply_floor` = `mul_floor` + `to_asset_floor`,
+ * `unscale_borrow_ceil` = `mul_ceil` + `to_asset_ceil`, `unscale_supply` /
+ * `unscale_borrow` (displayed balance) = `mul` (half-up) + `to_asset` (half-up).
+ */ export function unscale(scaledRay, indexRay, decimals, rounding) {
+    return RESCALE[rounding](MUL_DIV[rounding](scaledRay, indexRay, RAY), RAY_DECIMALS, decimals);
+}
+/**
+ * Current supplied amount in token base units — `scaling.rs::unscale_supply_floor`
+ * (`mul_floor` then `to_asset_floor`). This is what the pool pays on a full
+ * withdrawal, so the SDK never reports more collateral than the contract releases.
+ */ export function unscaleSupplyFloor(scaledRay, indexRay, decimals) {
+    return unscale(toBigInt(scaledRay, 'scaledRay'), toBigInt(indexRay, 'indexRay'), decimals, 'floor');
+}
+/**
+ * Current borrowed amount in token base units — `scaling.rs::unscale_borrow_ceil`
+ * (`mul_ceil` then `to_asset_ceil`). A repayment of at least this amount burns
+ * every debt share (`resolve_repay`), so a max repay always covers the debt.
+ *
+ * Note: the xoxno-ui mirror (`stellar-scaled-math.ts`) rounds the share product
+ * half-up before the ceil rescale; the contract ceils both steps. This module
+ * follows the contract.
+ */ export function unscaleBorrowCeil(scaledRay, indexRay, decimals) {
+    return unscale(toBigInt(scaledRay, 'scaledRay'), toBigInt(indexRay, 'indexRay'), decimals, 'ceil');
+}
+/**
+ * Displayed balance in token base units — `scaling.rs::unscale_supply` /
+ * `unscale_borrow` (half-up at both steps). `resolve_withdrawal` treats a
+ * request at or above this value as a full withdrawal.
+ */ export function unscaleHalfUp(scaledRay, indexRay, decimals) {
+    return unscale(toBigInt(scaledRay, 'scaledRay'), toBigInt(indexRay, 'indexRay'), decimals, 'halfUp');
+}
+/** `Ray::from_asset` — token base units → RAY (exact for decimals ≤ 27). */ export function baseToRay(amountBase, decimals) {
+    if (decimals > RAY_DECIMALS) throw new Error(`Stellar math: decimals ${decimals} exceed RAY scale`);
+    return rescaleFloor(amountBase, decimals, RAY_DECIMALS);
+}
+/**
+ * USD value (WAD) of a scaled position — `common/src/rates/value.rs`
+ * `position_value` (halfUp) / `position_value_floor` / `position_value_ceil`:
+ * `asset_ray = round(scaled * index / RAY)`, `asset_wad = round(asset_ray / 1e9)`,
+ * `usd_wad = round(asset_wad * price / WAD)` with one direction at all three steps.
+ */ export function positionValueWad(scaledRay, indexRay, priceWad, rounding) {
+    const assetRay = MUL_DIV[rounding](scaledRay, indexRay, RAY);
+    const assetWad = RESCALE[rounding](assetRay, RAY_DECIMALS, WAD_DECIMALS);
+    return MUL_DIV[rounding](assetWad, priceWad, WAD);
+}
+/**
+ * USD value (WAD) of a token amount in base units, using the same last two
+ * steps as {@link positionValueWad}. Used by projections, where the hypothetical
+ * amount is a token quantity rather than shares.
+ */ export function baseValueWad(amountBase, decimals, priceWad, rounding) {
+    const assetWad = RESCALE[rounding](baseToRay(amountBase, decimals), RAY_DECIMALS, WAD_DECIMALS);
+    return MUL_DIV[rounding](assetWad, priceWad, WAD);
+}
+/** WAD → JS number (display only; ~1e-16 relative precision). */ export const wadToNumber = (wad)=>Number(wad) / 1e18;
+/** RAY → JS number (display only). */ export const rayToNumber = (ray)=>Number(ray) / 1e27;
+/** Token base units → human-readable number (display only). */ export const baseToShort = (amountBase, decimals)=>Number(amountBase) / 10 ** decimals;
+/**
+ * Decimal JS number (a `usdPrice` / `*Short` API field) → integer at `decimals`.
+ * Uses `toFixed` so no float arithmetic runs after the parse; precision is that
+ * of the input double (~15–16 significant digits). Domain: `0 < value < 1e21`
+ * (`toFixed` switches to exponential notation at 1e21); anything outside,
+ * non-finite included, maps to 0 rather than throwing.
+ */ export function numberToScaled(value, decimals) {
+    if (!Number.isFinite(value) || value <= 0 || value >= 1e21) return 0n;
+    const fixed = value.toFixed(decimals);
+    const [whole = '0', frac = ''] = fixed.split('.');
+    return BigInt(whole + frac.padEnd(decimals, '0'));
+}
+/** JS USD price → WAD, see {@link numberToScaled}. */ export const numberToWad = (usd)=>numberToScaled(usd, WAD_DECIMALS);

package/dist/esm/sdk/stellar/position-mode.js

@@ -0,0 +1,11 @@
+/**
+ * Map MVX `PositionMode` numbering to the Stellar lending controller enum.
+ *
+ * MVX: None=0, Normal=1, Multiply=2, Long=3, Short=4
+ * Stellar: Normal=0, Multiply=1, Long=2, Short=3
+ */ export function toStellarPositionMode(mvxMode) {
+    if (mvxMode <= 0 || mvxMode > 4) {
+        throw new Error(`Invalid PositionMode ${mvxMode} for Stellar — ` + `expected 1 (Normal) through 4 (Short). ` + `"None" (0) has no Stellar equivalent.`);
+    }
+    return mvxMode - 1;
+}