@xoxno/sdk-js 1.0.217 → 1.0.219

package/dist/cjs/sdk/stellar/__tests__/auth-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

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/__tests__/route-verify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/sdk/stellar/auth-policy.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Pre-signing allowlist for the Soroban authorization tree of a PREPARED
+ * transaction.
+ *
+ * Simulation records every `require_auth` that code on the call stack makes
+ * for the caller — including one made by a rogue pool or token inside a swap
+ * hop, e.g. `any_token.transfer(caller, attacker, x)`. The wallet signature
+ * covers the whole tree, so whatever `prepareTransaction` returns is what the
+ * user authorizes. Each policy below is the set of sub-invocations the
+ * contracts legitimately request from the caller, with the source that proves
+ * it (paths are in the `rs-lending-xlm` repository):
+ *
+ * | Entrypoint | Caller sub-invocations | Source |
+ * |---|---|---|
+ * | controller `supply` | `asset.transfer(caller, pool, <= amount)` per asset | `contracts/controller/src/positions/supply.rs:118` |
+ * | controller `repay` | `asset.transfer(caller, pool, <= amount)` per asset | `contracts/controller/src/positions/debt.rs:144` |
+ * | controller `liquidate` | `asset.transfer(liquidator, pool, <= payment)` per asset | `contracts/controller/src/positions/liquidation/apply.rs:50` |
+ * | controller `multiply` | `asset.transfer(caller, controller, <= initial_payment)` when present | `contracts/controller/src/strategies/multiply.rs:169` |
+ * | controller `migrate_from_blend` | `blend_pool.submit(caller, controller, controller, [withdraw / withdraw_collateral / repay])`, at most twice | `contracts/controller/src/external/blend.rs:46-97` |
+ * | controller `borrow`, `withdraw`, `swap_debt`, `swap_collateral`, `repay_debt_with_collateral`, `flash_loan`, `flash_position`, any other | none | the controller funds these from its own custody (`strategies/legs.rs:50`, `strategies/flash_position.rs:285`) |
+ * | governance, any | none | proposer auth only |
+ * | router `execute_strategy` | `token_in.transfer(sender, router, <= total_in)` | `contracts/swap-aggregator/src/execute/mod.rs:81` |
+ */
+import { xdr } from '@stellar/stellar-sdk';
+import { type StellarNetwork } from './contracts.js';
+export type StellarAuthPolicyErrorCode = 'MALFORMED_TRANSACTION' | 'INVOCATION_CHANGED' | 'UNSUPPORTED_CONTRACT' | 'CALLER_MISMATCH' | 'DUPLICATE_ENTRY' | 'UNEXPECTED_ROOT' | 'UNEXPECTED_CALL' | 'NESTED_INVOCATION' | 'UNEXPECTED_TOKEN' | 'UNEXPECTED_SENDER' | 'UNEXPECTED_RECIPIENT' | 'AMOUNT_EXCEEDED';
+/** The invocation that broke the policy, in readable form. */
+export interface StellarAuthOffender {
+    contract: string;
+    fn: string;
+    args: string[];
+}
+/** Thrown when the authorization tree holds anything the policy does not allow. */
+export declare class StellarAuthPolicyError extends Error {
+    readonly code: StellarAuthPolicyErrorCode;
+    readonly offender?: StellarAuthOffender;
+    constructor(code: StellarAuthPolicyErrorCode, message: string, offender?: StellarAuthOffender);
+}
+/** Total the caller may send to `to` in `token` across all sub-invocations. */
+export interface StellarAuthTransferAllowance {
+    token: string;
+    to: string;
+    maxAmount: bigint;
+}
+/** A non-transfer sub-invocation the caller legitimately authorizes. */
+export interface StellarAuthCallAllowance {
+    contract: string;
+    fn: string;
+    maxCount: number;
+    /** Returns why `args` are not acceptable, or `undefined` when they are. */
+    reject: (args: xdr.ScVal[]) => string | undefined;
+}
+export interface StellarAuthPolicy {
+    caller: string;
+    root: {
+        contract: string;
+        fn: string;
+    };
+    transfers: StellarAuthTransferAllowance[];
+    calls?: StellarAuthCallAllowance[];
+}
+/**
+ * Enforce `policy` on the authorization entries of a prepared transaction.
+ * Entries that belong to other addresses are ignored. For the caller: at most
+ * one entry, the expected root, and only allowlisted leaf sub-invocations.
+ * @param sourceAccount - Account that source-account credentials stand for
+ * (the operation source, else the transaction source). When omitted, such
+ * entries are treated as the caller's.
+ * @throws StellarAuthPolicyError
+ */
+export declare function assertStellarAuthEntries(entries: readonly xdr.SorobanAuthorizationEntry[], policy: StellarAuthPolicy, sourceAccount?: string): void;
+/** Contract addresses a policy is derived against. */
+export interface StellarAuthDeployment {
+    lendingController: string;
+    lendingPool: string;
+    aggregatorRouter: string;
+    governance: string;
+}
+/**
+ * Derive the policy for one contract invocation from its own arguments. The
+ * arguments are what the application built from the user's intent, so the
+ * allowed transfers are bounded by exactly what the user asked to pay.
+ * @throws StellarAuthPolicyError for a contract outside `deployment`.
+ */
+export declare function stellarAuthPolicyForInvocation(caller: string, invocation: xdr.InvokeContractArgs, deployment: StellarAuthDeployment): StellarAuthPolicy;
+export interface StellarPreparedTxAuthOptions {
+    network: StellarNetwork;
+    /** The wallet address that will sign. */
+    caller: string;
+    /**
+     * The unsigned builder output that was sent to `prepareTransaction`. When
+     * given, the prepared invocation must be byte-identical to it.
+     */
+    builtXdr?: string;
+    /** Replaces the derived policy (other contracts, custom flash receivers). */
+    policy?: StellarAuthPolicy;
+    /** Overrides manifest addresses for a non-standard deployment. */
+    deployment?: Partial<StellarAuthDeployment>;
+}
+/**
+ * Check a prepared transaction (base64 XDR, as `prepareTransaction` returns
+ * it) before it is passed to a wallet. Takes XDR strings so no live SDK object
+ * crosses the consumer's bundle boundary. Never sign when this throws.
+ * @throws StellarAuthPolicyError | StellarRouteVerificationError
+ */
+export declare function assertStellarPreparedTxAuth(preparedXdr: string, opts: StellarPreparedTxAuthOptions): void;

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

@@ -20,6 +20,8 @@ export interface StellarDeployment {
     readonly aquariusApiUrl: string;
     readonly aquariusRouter: string;
     readonly lendingController: string;
+    /** The controller's single liquidity pool: the recipient of supply, repay and liquidation transfers. */
+    readonly lendingPool: string;
     readonly aggregatorRouter: string;
     readonly governance: string;
     readonly priceAggregator: string;
@@ -41,6 +43,7 @@ export declare const STELLAR_NETWORKS: {
         readonly aquariusApiUrl: "https://amm-api.aqua.network";
         readonly aquariusRouter: "CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK";
         readonly lendingController: "CAUCMIN5KSXEVZ7NMXR3LZATGD5EFIEUI5XWTFLYRO2R5OTXI22WE5JX";
+        readonly lendingPool: "CBXRNDQMAJFG4VUKMKFEMFS75UUXE2SPSNV4LEEFCSNBCN66PYRWBKXO";
         readonly aggregatorRouter: "CCVENFSVCBYDHVOACFZXMNNYVOZ3LKXPZYU5LUI4N7KTXOKRVYD7F3TR";
         readonly governance: "CC44PEQW7HSEPKAZ5ZRPH2JS5M5KVJXCUBLJ2ZX4E3WCDKMNFILHC2AD";
         readonly priceAggregator: "CBGUF2G2Q7HCVCWYISDXBHPVBGMYNXA7PG2VET66YBZX6IKOOV27NSMV";
@@ -56,6 +59,7 @@ export declare const STELLAR_NETWORKS: {
         readonly aquariusApiUrl: "https://amm-api-testnet.aqua.network";
         readonly aquariusRouter: "CBCFTQSPDBAIZ6R6PJQKSQWKNKWH2QIV3I4J72SHWBIK3ADRRAM5A6GD";
         readonly lendingController: "CCXRWJ6SIU2WPFEGLFGJVITPL57QAYIMIO6OAM2NBGNDQSSCK2FFV3F3";
+        readonly lendingPool: "CBSGF6QOQAMPFBEVSYPEQHSZRIHJ6RCGUPCRDMUX36DEKRWFAO2PZB5A";
         readonly aggregatorRouter: "CDNTWMWW2WGYTKIZTJYNGNVQQZI4KTC5BQRZ3275KESRX5T4O3AYECL5";
         readonly governance: "CDS33JDOYH3F3FL4QUQ6DV4WKHML2AKHF4LADTZ57FRUAEBTE7NMY5FQ";
         readonly priceAggregator: "CAALOOTIDXCX7D7FMQIBSSAJLPKOM3GMXS4UUSTDIG42JCRRJHOPUHOP";
@@ -74,6 +78,7 @@ export declare const stellarNetworks: {
         readonly aquariusApiUrl: "https://amm-api.aqua.network";
         readonly aquariusRouter: "CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK";
         readonly lendingController: "CAUCMIN5KSXEVZ7NMXR3LZATGD5EFIEUI5XWTFLYRO2R5OTXI22WE5JX";
+        readonly lendingPool: "CBXRNDQMAJFG4VUKMKFEMFS75UUXE2SPSNV4LEEFCSNBCN66PYRWBKXO";
         readonly aggregatorRouter: "CCVENFSVCBYDHVOACFZXMNNYVOZ3LKXPZYU5LUI4N7KTXOKRVYD7F3TR";
         readonly governance: "CC44PEQW7HSEPKAZ5ZRPH2JS5M5KVJXCUBLJ2ZX4E3WCDKMNFILHC2AD";
         readonly priceAggregator: "CBGUF2G2Q7HCVCWYISDXBHPVBGMYNXA7PG2VET66YBZX6IKOOV27NSMV";
@@ -89,6 +94,7 @@ export declare const stellarNetworks: {
         readonly aquariusApiUrl: "https://amm-api-testnet.aqua.network";
         readonly aquariusRouter: "CBCFTQSPDBAIZ6R6PJQKSQWKNKWH2QIV3I4J72SHWBIK3ADRRAM5A6GD";
         readonly lendingController: "CCXRWJ6SIU2WPFEGLFGJVITPL57QAYIMIO6OAM2NBGNDQSSCK2FFV3F3";
+        readonly lendingPool: "CBSGF6QOQAMPFBEVSYPEQHSZRIHJ6RCGUPCRDMUX36DEKRWFAO2PZB5A";
         readonly aggregatorRouter: "CDNTWMWW2WGYTKIZTJYNGNVQQZI4KTC5BQRZ3275KESRX5T4O3AYECL5";
         readonly governance: "CDS33JDOYH3F3FL4QUQ6DV4WKHML2AKHF4LADTZ57FRUAEBTE7NMY5FQ";
         readonly priceAggregator: "CAALOOTIDXCX7D7FMQIBSSAJLPKOM3GMXS4UUSTDIG42JCRRJHOPUHOP";

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

@@ -14,9 +14,12 @@ export * from './governance.js';
 export * from './events/index.js';
 export * from './quote.js';
 export * from './swap.js';
+export * from './route-verify.js';
+export * from './auth-policy.js';
 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;