@xoxno/sdk-js 1.0.217 → 1.0.218

package/dist/cjs/sdk/stellar/__tests__/math/account.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Fixture-driven tests for `computeAccountRisk`, the limit helpers and the
+ * projections. Expected health factors are worked by hand from
+ * `rs-lending-xlm/docs/reference/formulas.md` §Valuation and health:
+ *   value_usd = round(round(round(shares·index/RAY)/1e9)·price/WAD)
+ *   ltv_collateral = Σ floor(floor-value · min(ltv, threshold) / BPS)
+ *   weighted_collateral = Σ floor(floor-value · threshold / BPS)
+ *   debt = Σ ceil-value; HF = floor(weighted_collateral · WAD / debt)
+ */
+export {};

package/dist/cjs/sdk/stellar/__tests__/math/parity.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parity between the SDK math and the xoxno-ui mirrors it replaces. The UI
+ * functions are re-implemented inline below as the oracle, ported verbatim
+ * (BigNumber integer ops → BigInt, floats kept as floats) from:
+ *   - xoxno-ui/src/modules/lending/stellar-scaled-math.ts
+ *       (`unscaleSupplyFloor`, `unscaleBorrowCeil`)
+ *   - xoxno-ui/src/modules/lending/utils.ts
+ *       (`getBorrowApy`, `getSupplyApy`, `getNewCollateral` + `getHealthPercentage`,
+ *        `calculateMaxBorrow` cap headroom)
+ *   - xoxno-ui/src/modules/lending/stellar-limits.ts
+ *       (`resolveMaxUtilization`, `utilCapBorrowUsd`, `utilCapWithdrawUsd`)
+ * Inputs are random but deterministic (mulberry32, fixed seed).
+ */
+export {};

package/dist/cjs/sdk/stellar/__tests__/math/scaled-rates.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hand-checked unit tests for the fixed-point primitives (`scaled.ts`) and the
+ * rate curve (`rates.ts`). Expected values are worked by hand from
+ * `rs-lending-xlm/common/src/math/fp_core.rs` and `common/src/rates/curve.rs`.
+ */
+export {};

package/dist/cjs/sdk/stellar/index.d.ts

@@ -18,5 +18,6 @@ export * from './prepare.js';
 export * from './position-mode.js';
 export * from './repay-swap.js';
 export * from './cctp.js';
+export * from './math/index.js';
 export type { StellarStrategySwapInput, StellarStrategySwapPathInput, StellarStrategySwapHopInput, } from './scval-encode.js';
 export { mapSorobanError } from '../../utils/soroban-errors.js';

package/dist/cjs/sdk/stellar/math/account.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Account valuation and risk — the client mirror of
+ * `rs-lending-xlm/contracts/controller/src/risk/totals.rs`
+ * (`calculate_account_risk_totals`) and the post-action gate in
+ * `contracts/controller/src/risk/validation.rs` (`require_post_pool_risk_gates`),
+ * as specified in `docs/reference/formulas.md` §Valuation and health.
+ *
+ * Inputs are the generated API DTOs; all integer math runs in `BigInt` on the
+ * raw string fields. Outputs carry both the raw WAD strings and display numbers.
+ */
+import type { AccountPositionDto, ReserveDto, StellarLendingLiveStateDto, StellarMarketIndexByHub } from '../lending-api-types.js';
+/**
+ * `common/src/constants/shared.rs::DEFAULT_MIN_BORROW_COLLATERAL_USD_WAD` —
+ * the floor `get_min_borrow_collateral_usd` returns until governance changes
+ * it. Used only when `liveState.minBorrowCollateralUsdWad` is absent or null.
+ */
+export declare const DEFAULT_MIN_BORROW_COLLATERAL_USD_WAD: bigint;
+export type PositionSide = 'supply' | 'borrow';
+/** One valued hub-asset leg of an account. */
+export type PositionValue = {
+    side: PositionSide;
+    hubId: number;
+    asset: string;
+    decimals: number;
+    /** Scaled shares (RAY) the valuation started from. */
+    scaledRay: string;
+    /** Index (RAY) applied to the shares. */
+    indexRay: string;
+    /** USD price per whole token (WAD) applied. */
+    usdPriceWad: string;
+    usdPrice: number;
+    /** Token base units: supply = `unscale_supply_floor`, borrow = `unscale_borrow_ceil`. */
+    amountBase: string;
+    amountShort: number;
+    /** USD (WAD): supply = half-up `position_value` (feeds `total_collateral`); borrow = `position_value_ceil` (risk debt). */
+    usdWad: string;
+    usd: number;
+    /** USD (WAD) the risk gates weight: supply = `position_value_floor`; borrow = same as `usdWad`. */
+    gateUsdWad: string;
+    entryLtvBps: number;
+    entryLiquidationThresholdBps: number;
+    entryLiquidationBonusBps: number;
+    entryLiquidationFeesBps: number;
+    /** Supplies: `floor(gateUsd * min(entryLtv, entryThreshold) / BPS)`; borrows: "0". */
+    ltvWeightedUsdWad: string;
+    /** Supplies: `floor(gateUsd * entryThreshold / BPS)`; borrows: "0". */
+    liquidationWeightedUsdWad: string;
+    /** Both the index and the price came from an accepted live-state row. */
+    liveDataUsed: boolean;
+};
+export type AccountRisk = {
+    accountId: string;
+    owner: string;
+    spokeId: number;
+    /** `AccountPositionDto.positionMode`: 0 normal, 1 multiply, 2 long, 3 short. */
+    mode: number;
+    supplies: PositionValue[];
+    borrows: PositionValue[];
+    /** Unweighted collateral, half-up (`AccountRiskTotals.total_collateral`). */
+    totalCollateralUsdWad: string;
+    totalCollateralUsd: number;
+    /** Floor-valued collateral weighted by stored `min(LTV, threshold)` (`ltv_collateral`). */
+    ltvWeightedCollateralUsdWad: string;
+    ltvWeightedCollateralUsd: number;
+    /** Floor-valued collateral weighted by stored liquidation threshold (`weighted_collateral`). */
+    liquidationWeightedCollateralUsdWad: string;
+    liquidationWeightedCollateralUsd: number;
+    /** Ceil-valued debt (`total_debt`). */
+    totalDebtUsdWad: string;
+    totalDebtUsd: number;
+    /** Contract convention `floor(weighted_collateral * WAD / debt)`; null when debt-free (the contract returns `i128::MAX`). */
+    healthFactorWad: string | null;
+    healthFactor: number | null;
+    /** UI convention: `debt / threshold-weighted collateral × 100`; higher is riskier, 0 without collateral. */
+    healthPercent: number;
+    /** Debt the LTV gate admits: `ltv_collateral` (`require_post_pool_risk_gates`). */
+    borrowLimitUsdWad: string;
+    borrowLimitUsd: number;
+    /** `max(0, borrowLimit - debt)`; 0 when `ltv_collateral` is below the min-collateral floor. */
+    availableBorrowUsdWad: string;
+    availableBorrowUsd: number;
+    /** Floor applied while debt remains (`get_min_borrow_collateral_usd`). */
+    minBorrowCollateralUsdWad: string;
+    minBorrowCollateralUsd: number;
+    /** Debt > 0 and health factor < 1 WAD. */
+    isLiquidatable: boolean;
+    /** `liveState` was supplied and every position was valued from an accepted live row. */
+    liveDataValid: boolean;
+};
+export type ReserveInput = Record<string, ReserveDto> | ReserveDto[];
+/** Key used by `StellarLendingContextDto.reserveDetailsByKey`. */
+export declare const reserveKey: (spokeId: number, hubId: number, asset: string) => string;
+/** Find the reserve backing a `(spokeId, hubId, asset)` coordinate; throws when missing. */
+export declare function resolveReserve(reserves: ReserveInput, spokeId: number, hubId: number, asset: string): ReserveDto;
+export type LiveSnapshot = {
+    /** Accepted index rows keyed `${hubId}:${asset}`. */
+    indexes: Map<string, StellarMarketIndexByHub>;
+    /** Accepted USD prices (WAD) keyed by asset. */
+    prices: Map<string, bigint>;
+    rejectedIndexKeys: Set<string>;
+    rejectedAssets: Set<string>;
+};
+export declare const liveIndexKey: (hubId: number, asset: string) => string;
+/** Build the divergence-guarded snapshot from `liveState.indexes`. */
+export declare function buildLiveSnapshot(liveState: StellarLendingLiveStateDto | undefined): LiveSnapshot;
+type PositionSeed = {
+    side: PositionSide;
+    hubId: number;
+    asset: string;
+    decimals: number;
+    scaledRay: bigint;
+    indexRay: bigint;
+    priceWad: bigint;
+    entryLtvBps: number;
+    entryLiquidationThresholdBps: number;
+    entryLiquidationBonusBps: number;
+    entryLiquidationFeesBps: number;
+    liveDataUsed: boolean;
+};
+/**
+ * Value scaled shares exactly as `calculate_account_risk_totals` does:
+ * supply → `position_value` (half-up display/total) and
+ * `position_value_floor` (gate); borrow → `position_value_ceil`.
+ */
+export declare function valueScaledPosition(seed: PositionSeed): PositionValue;
+/**
+ * Shares minted when `amountBase` enters a leg — `scaling.rs`
+ * `calculate_scaled_supply` (floor) / `calculate_scaled_borrow` (ceil), the
+ * only entry conversions the pool performs (`ops/supply.rs`, `ops/borrow.rs`).
+ */
+export declare function mintShares(side: PositionSide, amountBase: bigint, decimals: number, indexRay: bigint): bigint;
+/**
+ * Shares burned by a partial exit of `amountBase` — `formulas.md` rounding
+ * table: "Partial withdrawal burn: ceil", "Partial repayment burn: floor".
+ * Full closes (withdraw ≥ half-up balance, repay ≥ ceil debt) burn every
+ * share instead; callers handle that boundary.
+ */
+export declare function burnShares(side: PositionSide, amountBase: bigint, decimals: number, indexRay: bigint): bigint;
+/**
+ * Value a fresh leg entered with `amountBase`: shares come from
+ * {@link mintShares} and the valuation runs on those shares exactly as
+ * {@link valueScaledPosition} does (`position_value_*` never sees the base
+ * amount). `amountBase` on the result is therefore the share-derived balance,
+ * which can differ from the input by rounding when the index is not `RAY`.
+ */
+export declare function valueBasePosition(seed: Omit<PositionSeed, 'scaledRay'>, amountBase: bigint): PositionValue;
+export type AccountIdentity = Pick<AccountRisk, 'accountId' | 'owner' | 'spokeId' | 'mode'>;
+/**
+ * Fold valued positions into the contract's risk totals and the derived
+ * limits. `formulas.md`: `health_factor_wad = floor(weighted_collateral_wad *
+ * WAD / debt_wad)`; the post-action gate requires `debt <= ltv_collateral`,
+ * `HF >= 1 WAD` and `ltv_collateral >= floor` while debt remains.
+ */
+export declare function aggregateAccountRisk(identity: AccountIdentity, supplies: PositionValue[], borrows: PositionValue[], minBorrowCollateralUsdWad: bigint, liveDataValid: boolean): AccountRisk;
+export type ComputeAccountRiskInput = {
+    /** Every row of one account (same `accountId`), as `/accounts/{id}/positions` returns them. */
+    positions: AccountPositionDto[];
+    /** `context.reserveDetailsByKey` (keyed `${spokeId}:${hubId}:${asset}`) or a reserve array. */
+    reserves: ReserveInput;
+    /** `/live-state`: live indexes, prices and the min-collateral floor. Optional; positions then fall back to their own applied indexes and the reserve price. */
+    liveState?: StellarLendingLiveStateDto;
+};
+/**
+ * Value one account exactly as the controller's risk gates do.
+ *
+ * - Index: live-state row for `(hubId, asset)` when it passed the divergence
+ *   guard, else the position's `liveSupplyIndexRay` / `liveBorrowIndexRay`,
+ *   then the reserve's `live*IndexRay`, and last the position's stored
+ *   `supplyIndexRay` / `borrowIndexRay` (undocumented in the API schema; the
+ *   documented fields say "stored index on fallback", so it is treated as the
+ *   stalest snapshot). The contract accrues to the current index before every
+ *   gate, so fresher candidates win.
+ * - Price: live-state `usdPrice` (WAD) when accepted, else `reserve.usdPrice`
+ *   converted to WAD.
+ * - Weights: the position's own `entry*Bps`, as the contract stores them.
+ * - Min-collateral floor: `liveState.minBorrowCollateralUsdWad`, defaulting
+ *   to 5 USD (`DEFAULT_MIN_BORROW_COLLATERAL_USD_WAD`) when absent or null.
+ *
+ * Throws when `positions` is empty, mixes account ids, or names a reserve
+ * missing from `reserves`.
+ */
+export declare function computeAccountRisk(input: ComputeAccountRiskInput): AccountRisk;
+export {};

package/dist/cjs/sdk/stellar/math/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Stellar lending math: contract-exact share conversion, rate curve, account
+ * risk, per-action limits and projections in native `BigInt`. Ground truth is
+ * `rs-lending-xlm` (`common/src/rates/*.rs`, `contracts/controller/src/risk/*`,
+ * `docs/reference/formulas.md`); each function names the source it mirrors.
+ * @module Stellar lending math
+ */
+export * from './scaled.js';
+export * from './rates.js';
+export * from './account.js';
+export * from './limits.js';
+export * from './projection.js';

package/dist/cjs/sdk/stellar/math/limits.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 type { ReserveDto, StellarLendingLiveStateDto } from '../lending-api-types.js';
+import type { AccountRisk } from './account.js';
+export type LimitReason = 'healthFactor' | 'ltv' | 'cap' | 'liquidity' | 'utilizationCap' | 'minCollateral' | 'paused' | 'frozen' | null;
+export type Limit = {
+    /** Token base units. For a full-close withdraw this is the floor payout; sign `"0"` (the builder's withdraw-all sentinel) instead. */
+    amountBase: bigint;
+    amountShort: number;
+    /** The amount closes the whole position (withdraw: pays the floor balance; repay: burns every debt share and refunds excess). */
+    isFullClose: boolean;
+    /** Which gate produced `amountBase`; null when only the position size bounds it. */
+    reason: LimitReason;
+    /** Hub utilization (0..1) after the action at `amountBase`; null when not applicable. */
+    projectedUtilization: number | null;
+};
+/** `common/src/constants/pool.rs::LIQUIDATION_BUFFER_BPS`. */
+export declare const LIQUIDATION_BUFFER_BPS = 200n;
+/**
+ * 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 declare function maxBorrow(risk: AccountRisk, reserve: ReserveDto, liveState?: StellarLendingLiveStateDto): Limit;
+/**
+ * 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 declare function maxWithdraw(risk: AccountRisk, reserve: ReserveDto, _liveState?: StellarLendingLiveStateDto): Limit;
+/**
+ * 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 declare function maxSupply(reserve: ReserveDto): Limit;
+/**
+ * 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 declare function maxRepay(risk: AccountRisk, reserve: ReserveDto, walletBalance?: string | bigint): Limit;

package/dist/cjs/sdk/stellar/math/projection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 type { ReserveDto } from '../lending-api-types.js';
+import type { AccountRisk, PositionSide } from './account.js';
+export type PositionDelta = {
+    side: PositionSide;
+    hubId: number;
+    asset: string;
+    /** Signed token base units: positive supplies/borrows, negative withdraws/repays. */
+    amountBase: bigint | string;
+    /** Required when the account has no such position yet: decimals, `usdPrice` and the `collateralFactorBps` / `liquidationThresholdBps` a new position would snapshot. */
+    reserve?: ReserveDto;
+};
+/**
+ * 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 declare function projectAccountRisk(risk: AccountRisk, deltas: PositionDelta[]): AccountRisk;
+export type ReserveApyProjection = {
+    /** Hub utilization after the flows, 0..1. */
+    utilization: number;
+    utilizationRay: string;
+    /** Annual RAY rates from the curve. */
+    borrowAprRay: string;
+    supplyAprRay: string;
+    /** Simple annual rates as fractions (`0.05` = 5%). */
+    borrowApr: number;
+    supplyApr: number;
+    /** Continuously compounded `e^apr - 1`, fractions. */
+    borrowApy: number;
+    supplyApy: number;
+};
+/**
+ * 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 declare function projectReserveApy(reserve: ReserveDto, supplyDeltaBase?: bigint | string, borrowDeltaBase?: bigint | string): ReserveApyProjection;

package/dist/cjs/sdk/stellar/math/rates.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { ReserveIrmCurveDto } from '../lending-api-types.js';
+/**
+ * `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 declare function utilizationRay(borrowedRay: bigint, suppliedRay: bigint): bigint;
+/**
+ * `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 declare function annualBorrowRateRay(utilization: bigint, irm: ReserveIrmCurveDto): bigint;
+/**
+ * `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 declare function depositRateRay(utilization: bigint, borrowRateRay: bigint, reserveFactorBps: number): bigint;
+/** Annual RAY rate → simple APR as a fraction (`0.05` = 5%). */
+export declare const rayAprToNumber: (rateRay: bigint) => number;
+/**
+ * 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 declare const rayAprToApy: (rateRay: bigint) => number;

package/dist/cjs/sdk/stellar/math/scaled.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 declare const RAY: bigint;
+/** 10^18 — USD values, prices per whole token, health factor. */
+export declare const WAD: bigint;
+/** 10,000 — risk ratios and fees. */
+export declare const BPS = 10000n;
+export declare const RAY_DECIMALS = 27;
+export declare const WAD_DECIMALS = 18;
+/** Parse a raw integer string (or bigint/number) into a non-negative bigint. */
+export declare function toBigInt(value: string | number | bigint, label?: string): bigint;
+/** `fp_core::mul_div_floor` — floor(x * y / d) for non-negative operands. */
+export declare function mulDivFloor(x: bigint, y: bigint, d: bigint): bigint;
+/** `fp_core::mul_div_ceil` — ceil(x * y / d) for non-negative operands. */
+export declare function mulDivCeil(x: bigint, y: bigint, d: bigint): bigint;
+/** `fp_core::mul_div_half_up` — floor((x * y + d/2) / d) for non-negative operands. */
+export declare function mulDivHalfUp(x: bigint, y: bigint, d: bigint): bigint;
+/** `fp_core::div_by_int_half_up` — a / b rounded half up (non-negative a, b > 0). */
+export declare function divByIntHalfUp(a: bigint, b: bigint): bigint;
+/** `fp_core::rescale_floor` — move `a` between decimal scales, truncating when dropping digits. */
+export declare function rescaleFloor(a: bigint, fromDecimals: number, toDecimals: number): bigint;
+/** `fp_core::rescale_ceil` — like {@link rescaleFloor} but rounds a dropped remainder up. */
+export declare function rescaleCeil(a: bigint, fromDecimals: number, toDecimals: number): bigint;
+/** `fp_core::rescale_half_up` — like {@link rescaleFloor} but rounds a dropped remainder half up. */
+export declare function rescaleHalfUp(a: bigint, fromDecimals: number, toDecimals: number): bigint;
+export type Rounding = 'floor' | 'ceil' | 'halfUp';
+/**
+ * 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 declare function unscale(scaledRay: bigint, indexRay: bigint, decimals: number, rounding: Rounding): bigint;
+/**
+ * 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 declare function unscaleSupplyFloor(scaledRay: string | bigint, indexRay: string | bigint, decimals: number): bigint;
+/**
+ * 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 declare function unscaleBorrowCeil(scaledRay: string | bigint, indexRay: string | bigint, decimals: number): bigint;
+/**
+ * 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 declare function unscaleHalfUp(scaledRay: string | bigint, indexRay: string | bigint, decimals: number): bigint;
+/** `Ray::from_asset` — token base units → RAY (exact for decimals ≤ 27). */
+export declare function baseToRay(amountBase: bigint, decimals: number): bigint;
+/**
+ * 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 declare function positionValueWad(scaledRay: bigint, indexRay: bigint, priceWad: bigint, rounding: Rounding): bigint;
+/**
+ * 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 declare function baseValueWad(amountBase: bigint, decimals: number, priceWad: bigint, rounding: Rounding): bigint;
+/** WAD → JS number (display only; ~1e-16 relative precision). */
+export declare const wadToNumber: (wad: bigint) => number;
+/** RAY → JS number (display only). */
+export declare const rayToNumber: (ray: bigint) => number;
+/** Token base units → human-readable number (display only). */
+export declare const baseToShort: (amountBase: bigint, decimals: number) => number;
+/**
+ * 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 declare function numberToScaled(value: number, decimals: number): bigint;
+/** JS USD price → WAD, see {@link numberToScaled}. */
+export declare const numberToWad: (usd: number) => bigint;