@xoxno/sdk-js 1.0.223 → 1.0.225

package/dist/esm/sdk/stellar/lending.js

@@ -0,0 +1,358 @@
+/**
+ * Stellar lending user-operation transaction builders.
+ *
+ * Each builder takes a typed Stellar argument object plus shared
+ * `StellarLendingBuilderOptions` ({ network, caller, sourceSequence,
+ * controllerAddress, ... }) and returns
+ * unsigned transaction XDR that must be prepared before wallet signing.
+ *
+ * i128 values cross the boundary as decimal strings, encoded via
+ * `new ScInt(str).toI128()`. Addresses (Stellar `G...` accounts and Soroban
+ * `C...` contracts) are encoded via `new Address(str).toScVal()`.
+ *
+ * Builders are RPC-free: they accept a caller-supplied `sourceSequence` so the
+ * returned XDR is deterministic and snapshot-testable. The caller fetches the
+ * current sequence via `rpc.Server.getAccount(caller)` and runs
+ * `rpc.Server.prepareTransaction` (simulation + Soroban footprint/auth/resource
+ * fee) before handing the XDR to the wallet to sign.
+ */ import { Account, BASE_FEE, Contract, scValToNative, TransactionBuilder, xdr } from "@stellar/stellar-sdk";
+import { STELLAR_NETWORK_PASSPHRASE } from "./contracts.js";
+import { addr, asStellarBytes, asStellarStrategySwapBytes, bool, hubAsset, i128, option, seizeMode, tupleAddrAmountVec, tupleHubAssetAmount, tupleHubAssetAmountVec, u32, u64, vec } from "./scval-encode.js";
+// -----------------------------------------------------------------------------
+// Transaction assembly
+// -----------------------------------------------------------------------------
+/**
+ * Assemble an unsigned XDR that invokes a single Soroban contract method.
+ *
+ * Uses a synthetic `Account(caller, sourceSequence)` — no RPC call. The
+ * returned XDR still needs preparation (simulation to populate Soroban
+ * footprint + auth entries + resource fees) before signing. The UI layer
+ * does this via `rpc.Server.prepareTransaction`.
+ */ export function buildTx(opts, method, params) {
+    if (!opts.controllerAddress) {
+        throw new Error('Stellar lending controllerAddress is required');
+    }
+    const contract = new Contract(opts.controllerAddress);
+    const source = new Account(opts.caller, opts.sourceSequence);
+    const tx = new TransactionBuilder(source, {
+        fee: opts.fee ?? BASE_FEE,
+        networkPassphrase: STELLAR_NETWORK_PASSPHRASE[opts.network]
+    }).addOperation(contract.call(method, ...params)).setTimeout(opts.timeoutSeconds ?? 300).build();
+    return {
+        xdr: tx.toXDR()
+    };
+}
+// -----------------------------------------------------------------------------
+// Builders — 11 entry points, 1 : 1 with the multi-hub Stellar controller
+// -----------------------------------------------------------------------------
+function encodeSpokeId(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 0xffffffff) {
+        throw new Error('Stellar builder: spokeId must be an integer from 1 to 4294967295');
+    }
+    return u32(value);
+}
+/**
+ * supply(caller, account_id: u64, spoke_id: u32, assets: Vec<(HubAssetKey, i128)>)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarSupplyBatchTx(opts, args) {
+    const accountId = args.accountNonce ?? 0;
+    return buildTx(opts, 'supply', [
+        addr(opts.caller),
+        u64(accountId),
+        encodeSpokeId(args.spokeId),
+        tupleHubAssetAmountVec([
+            ...args.assets
+        ])
+    ]);
+}
+/** Single-asset `supply` — wraps the asset in a 1-element batch.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarSupplyTx(opts, args) {
+    return buildStellarSupplyBatchTx(opts, {
+        accountNonce: args.accountNonce,
+        spokeId: args.spokeId,
+        assets: [
+            {
+                hubId: args.hubId,
+                asset: args.asset,
+                amount: args.amount
+            }
+        ]
+    });
+}
+/**
+ * borrow(caller, account_id: u64, borrows: Vec<(HubAssetKey, i128)>,
+ * to: Option<Address>) — `to` is always sent; absent means the caller
+ * receives the funds.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarBorrowBatchTx(opts, args) {
+    return buildTx(opts, 'borrow', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        tupleHubAssetAmountVec([
+            ...args.borrows
+        ]),
+        option(args.to, addr)
+    ]);
+}
+/** Single-asset `borrow`.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarBorrowTx(opts, args) {
+    return buildStellarBorrowBatchTx(opts, {
+        accountNonce: args.accountNonce,
+        borrows: [
+            {
+                hubId: args.hubId,
+                asset: args.asset,
+                amount: args.amount
+            }
+        ],
+        to: args.to
+    });
+}
+/**
+ * withdraw(caller, account_id: u64, withdrawals: Vec<(HubAssetKey, i128)>,
+ * to: Option<Address>) — `to` is always sent; absent means the caller
+ * receives the funds.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarWithdrawBatchTx(opts, args) {
+    return buildTx(opts, 'withdraw', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        tupleHubAssetAmountVec([
+            ...args.withdrawals
+        ]),
+        option(args.to, addr)
+    ]);
+}
+/** Single-asset `withdraw`. Amount "0" withdraws the full supplied position.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarWithdrawTx(opts, args) {
+    return buildStellarWithdrawBatchTx(opts, {
+        accountNonce: args.accountNonce,
+        withdrawals: [
+            {
+                hubId: args.hubId,
+                asset: args.asset,
+                amount: args.amount
+            }
+        ],
+        to: args.to
+    });
+}
+/**
+ * repay(caller, account_id: u64, payments: Vec<(HubAssetKey, i128)>)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarRepayBatchTx(opts, args) {
+    return buildTx(opts, 'repay', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        tupleHubAssetAmountVec([
+            ...args.payments
+        ])
+    ]);
+}
+/** Single-asset `repay`.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarRepayTx(opts, args) {
+    return buildStellarRepayBatchTx(opts, {
+        accountNonce: args.accountNonce,
+        payments: [
+            {
+                hubId: args.hubId,
+                asset: args.asset,
+                amount: args.amount
+            }
+        ]
+    });
+}
+/**
+ * liquidate(liquidator, account_id: u64, debt_payments: Vec<(HubAssetKey, i128)>,
+ *           seize_mode: SeizeMode) -> u64
+ *
+ * The `u64` return is the account credited with the seized supply shares under
+ * `SeizeMode::Credit` (freshly opened when `Credit(0)` was passed), and `0`
+ * under `SeizeMode::Transfer`. Read it from the simulation / tx result with
+ * `decodeStellarLiquidateReturn`.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarLiquidateTx(opts, args) {
+    return buildTx(opts, 'liquidate', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        tupleHubAssetAmountVec([
+            ...args.debtPayments
+        ]),
+        seizeMode(args.seizeMode ?? 'Transfer')
+    ]);
+}
+/**
+ * Decode `liquidate`'s `u64` return value from its base64 XDR — the receiving
+ * account id, as a decimal string. `'0'` means `SeizeMode::Transfer` (the
+ * liquidator was paid in underlying tokens, no account was touched).
+ *
+ * Takes base64 XDR (as Soroban RPC delivers `returnValue` / `result.retval`)
+ * so no live `xdr.ScVal` crosses the consumer boundary — same contract as
+ * `decodeStellarLendingEvent`. Hold a parsed ScVal? Pass `toBase64Xdr(scv)`.
+ */ export function decodeStellarLiquidateReturn(returnValueB64) {
+    const native = scValToNative(xdr.ScVal.fromXDR(returnValueB64, 'base64'));
+    if (typeof native === 'bigint' || typeof native === 'number') {
+        return native.toString();
+    }
+    throw new Error(`Stellar builder: liquidate return value must be a u64, got ${typeof native}`);
+}
+/**
+ * flash_loan(caller, asset: HubAssetKey, amount: i128, receiver, data: Bytes)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarFlashLoanTx(opts, args) {
+    return buildTx(opts, 'flash_loan', [
+        addr(opts.caller),
+        hubAsset(args.hubId, args.asset),
+        i128(args.amount),
+        addr(args.receiver),
+        asStellarBytes(args.data)
+    ]);
+}
+/**
+ * Build a `migrate_from_blend` controller invocation: atomically moves a Blend
+ * V2 position (collateral + supply + debt) into XOXNO at zero flash-loan fee.
+ *
+ * ABI: `migrate_from_blend(caller, account_id, spoke_id, hub_id, blend_pool,
+ * collateral_assets, supply_assets, debt_caps: Vec<(Address, i128)>)`. Pass
+ * `accountId = "0"` to open a new account. Each debt cap should slightly exceed
+ * the live Blend debt — Blend refunds the excess, reconciled on-chain.
+ *
+ * Like every builder this emits an unsigned invoke; the nested `submit(from =
+ * user)` authorization is materialized by `prepareTransaction` (simulation) and
+ * signed by the wallet over the whole envelope. The Blend pool must be approved
+ * by the controller. Use an explicit destination hub and spoke; this operation
+ * does not consume aggregator route bytes.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarMigrateFromBlendTx(opts, args) {
+    return buildTx(opts, 'migrate_from_blend', [
+        addr(opts.caller),
+        u64(args.accountId),
+        encodeSpokeId(args.spokeId),
+        u32(args.hubId),
+        addr(args.blendPool),
+        vec(args.collateralTokens.map(addr)),
+        vec(args.supplyTokens.map(addr)),
+        tupleAddrAmountVec(args.debtCaps.map((d)=>({
+                token: d.token,
+                amount: d.cap
+            })))
+    ]);
+}
+/**
+ * multiply(caller, account_id, spoke_id, collateral: HubAssetKey,
+ *          debt_to_flash_loan: i128, debt: HubAssetKey, mode: PositionMode,
+ *          swap: Bytes, initial_payment: Option<(HubAssetKey, i128)>,
+ *          convert_swap: Option<Bytes>) -> u64
+ *
+ * `mode` is a repr(u32) `PositionMode` → encoded as `scvU32`. The two trailing
+ * `Option`s seed an optional initial collateral payment and a secondary swap
+ * converting it into the collateral token; both omit to Soroban `Void`.
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarMultiplyTx(opts, args) {
+    const accountId = args.accountNonce ?? 0;
+    return buildTx(opts, 'multiply', [
+        addr(opts.caller),
+        u64(accountId),
+        encodeSpokeId(args.spokeId),
+        hubAsset(args.collateral.hubId, args.collateral.asset),
+        i128(args.debtToFlashLoan),
+        hubAsset(args.debt.hubId, args.debt.asset),
+        u32(args.mode),
+        asStellarStrategySwapBytes(args.steps),
+        option(args.initialPayment, (p)=>tupleHubAssetAmount(p.hubId, p.asset, p.amount)),
+        option(args.convertSwap, asStellarStrategySwapBytes)
+    ]);
+}
+/**
+ * swap_debt(caller, account_id, existing_debt: HubAssetKey, amount: i128,
+ *           new_debt: HubAssetKey, swap: Bytes)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarSwapDebtTx(opts, args) {
+    return buildTx(opts, 'swap_debt', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        hubAsset(args.existingDebt.hubId, args.existingDebt.asset),
+        i128(args.newDebtAmount),
+        hubAsset(args.newDebt.hubId, args.newDebt.asset),
+        asStellarStrategySwapBytes(args.steps)
+    ]);
+}
+/**
+ * swap_collateral(caller, account_id, current: HubAssetKey, amount: i128,
+ *                 new: HubAssetKey, swap: Bytes)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarSwapCollateralTx(opts, args) {
+    return buildTx(opts, 'swap_collateral', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        hubAsset(args.current.hubId, args.current.asset),
+        i128(args.fromAmount),
+        hubAsset(args.newCollateral.hubId, args.newCollateral.asset),
+        asStellarStrategySwapBytes(args.steps)
+    ]);
+}
+/**
+ * repay_debt_with_collateral(caller, account_id, collateral: HubAssetKey,
+ *                            collateral_amount: i128, debt: HubAssetKey,
+ *                            swap: Bytes, close_position: bool)
+ * @param opts - Network, caller, current source sequence and deployment addresses.
+ * @param args - Operation arguments; token amounts are decimal base-unit strings.
+ * @returns Unsigned XDR; prepare with prepareStellarBuiltTx before wallet signing.
+ * @category Lending transactions
+ */ export function buildStellarRepayDebtWithCollateralTx(opts, args) {
+    return buildTx(opts, 'repay_debt_with_collateral', [
+        addr(opts.caller),
+        u64(args.accountNonce),
+        hubAsset(args.collateral.hubId, args.collateral.asset),
+        i128(args.collateralAmount),
+        hubAsset(args.debt.hubId, args.debt.asset),
+        asStellarStrategySwapBytes(args.steps),
+        bool(args.closePosition)
+    ]);
+}

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

@@ -0,0 +1,256 @@
+/**
+ * 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 { BPS, RAY, WAD, baseToRay, baseToShort, mulDivCeil, mulDivFloor, numberToWad, positionValueWad, toBigInt, unscale, wadToNumber } from "./scaled.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 const DEFAULT_MIN_BORROW_COLLATERAL_USD_WAD = 5n * WAD;
+/** Key used by `StellarLendingContextDto.reserveDetailsByKey`. */ export const reserveKey = (spokeId, hubId, asset)=>`${spokeId}:${hubId}:${asset}`;
+/** Find the reserve backing a `(spokeId, hubId, asset)` coordinate; throws when missing. */ export function resolveReserve(reserves, spokeId, hubId, asset) {
+    const list = Array.isArray(reserves) ? reserves : undefined;
+    const found = list ? list.find((r)=>r.spokeId === spokeId && r.hubId === hubId && r.asset === asset) : reserves[reserveKey(spokeId, hubId, asset)] ?? Object.values(reserves).find((r)=>r.spokeId === spokeId && r.hubId === hubId && r.asset === asset);
+    if (!found) {
+        throw new Error(`Stellar math: no reserve for ${reserveKey(spokeId, hubId, asset)}`);
+    }
+    return found;
+}
+// ---------------------------------------------------------------------------
+// Live-state divergence guard — mirror of xoxno-ui `use-scaled-amount.ts`
+// `buildStellarLiveSnapshot`: exact per-hub-asset indexes, asset-level price
+// consistency, and the controller oracle flags (a row the contract's
+// fail-closed solvency path would reject must not feed valuations either).
+// ---------------------------------------------------------------------------
+const POSITIVE_INTEGER = /^0*[1-9]\d*$/;
+const normalizedInteger = (value)=>typeof value === 'string' && POSITIVE_INTEGER.test(value) ? BigInt(value).toString() : null;
+export const liveIndexKey = (hubId, asset)=>`${hubId}:${asset}`;
+/** Build the divergence-guarded snapshot from `liveState.indexes`. */ export function buildLiveSnapshot(liveState) {
+    const indexes = new Map();
+    const prices = new Map();
+    const rejectedIndexKeys = new Set();
+    const rejectedAssets = new Set();
+    for (const row of liveState?.indexes ?? []){
+        const key = liveIndexKey(row.hubId, row.asset);
+        const supply = normalizedInteger(row.supplyIndex);
+        const borrow = normalizedInteger(row.borrowIndex);
+        const price = normalizedInteger(row.usdPrice);
+        const existing = indexes.get(key);
+        const sameAsExisting = existing && normalizedInteger(existing.supplyIndex) === supply && normalizedInteger(existing.borrowIndex) === borrow && normalizedInteger(existing.usdPrice) === price;
+        if (supply == null || borrow == null || price == null || existing && !sameAsExisting) {
+            rejectedIndexKeys.add(key);
+        } else if (!existing) {
+            indexes.set(key, row);
+        }
+        const oracleRejected = row.valid === false || row.stale === true || row.deviation === true;
+        const existingPrice = prices.get(row.asset);
+        if (price == null || oracleRejected || existingPrice !== undefined && existingPrice.toString() !== price) {
+            rejectedAssets.add(row.asset);
+        } else if (existingPrice === undefined) {
+            prices.set(row.asset, BigInt(price));
+        }
+    }
+    for (const key of rejectedIndexKeys)indexes.delete(key);
+    for (const asset of rejectedAssets)prices.delete(asset);
+    return {
+        indexes,
+        prices,
+        rejectedIndexKeys,
+        rejectedAssets
+    };
+}
+/** Weight a floor-valued gate USD by a BPS ratio, flooring (`Bps::apply_to_wad_floor`). */ const weightFloor = (gateUsdWad, bps)=>mulDivFloor(gateUsdWad, BigInt(bps), BPS);
+function finishPositionValue(seed, amountBase, usdWad, gateUsdWad) {
+    const isSupply = seed.side === 'supply';
+    const effectiveLtv = Math.min(seed.entryLtvBps, seed.entryLiquidationThresholdBps);
+    return {
+        side: seed.side,
+        hubId: seed.hubId,
+        asset: seed.asset,
+        decimals: seed.decimals,
+        scaledRay: seed.scaledRay.toString(),
+        indexRay: seed.indexRay.toString(),
+        usdPriceWad: seed.priceWad.toString(),
+        usdPrice: wadToNumber(seed.priceWad),
+        amountBase: amountBase.toString(),
+        amountShort: baseToShort(amountBase, seed.decimals),
+        usdWad: usdWad.toString(),
+        usd: wadToNumber(usdWad),
+        gateUsdWad: gateUsdWad.toString(),
+        entryLtvBps: seed.entryLtvBps,
+        entryLiquidationThresholdBps: seed.entryLiquidationThresholdBps,
+        entryLiquidationBonusBps: seed.entryLiquidationBonusBps,
+        entryLiquidationFeesBps: seed.entryLiquidationFeesBps,
+        ltvWeightedUsdWad: isSupply ? weightFloor(gateUsdWad, effectiveLtv).toString() : '0',
+        liquidationWeightedUsdWad: isSupply ? weightFloor(gateUsdWad, seed.entryLiquidationThresholdBps).toString() : '0',
+        liveDataUsed: seed.liveDataUsed
+    };
+}
+/**
+ * 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 function valueScaledPosition(seed) {
+    if (seed.side === 'supply') {
+        const amountBase = unscale(seed.scaledRay, seed.indexRay, seed.decimals, 'floor');
+        const usdWad = positionValueWad(seed.scaledRay, seed.indexRay, seed.priceWad, 'halfUp');
+        const gateUsdWad = positionValueWad(seed.scaledRay, seed.indexRay, seed.priceWad, 'floor');
+        return finishPositionValue(seed, amountBase, usdWad, gateUsdWad);
+    }
+    const amountBase = unscale(seed.scaledRay, seed.indexRay, seed.decimals, 'ceil');
+    const usdWad = positionValueWad(seed.scaledRay, seed.indexRay, seed.priceWad, 'ceil');
+    return finishPositionValue(seed, amountBase, usdWad, usdWad);
+}
+/**
+ * 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 function mintShares(side, amountBase, decimals, indexRay) {
+    const amountRay = baseToRay(amountBase, decimals);
+    return side === 'supply' ? mulDivFloor(amountRay, RAY, indexRay) : mulDivCeil(amountRay, RAY, indexRay);
+}
+/**
+ * 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 function burnShares(side, amountBase, decimals, indexRay) {
+    const amountRay = baseToRay(amountBase, decimals);
+    return side === 'supply' ? mulDivCeil(amountRay, RAY, indexRay) : mulDivFloor(amountRay, RAY, indexRay);
+}
+/**
+ * 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 function valueBasePosition(seed, amountBase) {
+    return valueScaledPosition({
+        ...seed,
+        scaledRay: mintShares(seed.side, amountBase, seed.decimals, seed.indexRay)
+    });
+}
+const firstIndex = (...candidates)=>{
+    for (const c of candidates){
+        const n = normalizedInteger(c);
+        if (n != null) return BigInt(n);
+    }
+    return RAY;
+};
+function valueDtoPosition(side, pos, reserve, snapshot) {
+    const scaledRay = toBigInt(side === 'supply' ? pos.supplyScaledRay : pos.borrowScaledRay, `${side}ScaledRay`);
+    if (scaledRay === 0n) return null;
+    const liveRow = snapshot.indexes.get(liveIndexKey(pos.hubId, pos.asset));
+    const livePrice = snapshot.prices.get(pos.asset);
+    const indexRay = side === 'supply' ? firstIndex(liveRow?.supplyIndex, pos.liveSupplyIndexRay, reserve.liveSupplyIndexRay, pos.supplyIndexRay) : firstIndex(liveRow?.borrowIndex, pos.liveBorrowIndexRay, reserve.liveBorrowIndexRay, pos.borrowIndexRay);
+    const priceWad = livePrice ?? numberToWad(reserve.usdPrice);
+    return valueScaledPosition({
+        side,
+        hubId: pos.hubId,
+        asset: pos.asset,
+        decimals: reserve.assetDecimals,
+        scaledRay,
+        indexRay,
+        priceWad,
+        entryLtvBps: pos.entryLtvBps,
+        entryLiquidationThresholdBps: pos.entryLiquidationThresholdBps,
+        entryLiquidationBonusBps: pos.entryLiquidationBonusBps,
+        entryLiquidationFeesBps: pos.entryLiquidationFeesBps,
+        liveDataUsed: liveRow !== undefined && livePrice !== undefined
+    });
+}
+const sumWad = (positions, pick)=>positions.reduce((acc, p)=>acc + BigInt(pick(p)), 0n);
+/**
+ * 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 function aggregateAccountRisk(identity, supplies, borrows, minBorrowCollateralUsdWad, liveDataValid) {
+    const totalCollateral = sumWad(supplies, (p)=>p.usdWad);
+    const ltvCollateral = sumWad(supplies, (p)=>p.ltvWeightedUsdWad);
+    const weightedCollateral = sumWad(supplies, (p)=>p.liquidationWeightedUsdWad);
+    const totalDebt = sumWad(borrows, (p)=>p.usdWad);
+    const healthFactorWad = totalDebt === 0n ? null : mulDivFloor(weightedCollateral, WAD, totalDebt);
+    const healthPercent = weightedCollateral === 0n ? 0 : Number(totalDebt) / Number(weightedCollateral) * 100;
+    const belowFloor = ltvCollateral < minBorrowCollateralUsdWad;
+    const availableBorrow = belowFloor || ltvCollateral <= totalDebt ? 0n : ltvCollateral - totalDebt;
+    return {
+        ...identity,
+        supplies,
+        borrows,
+        totalCollateralUsdWad: totalCollateral.toString(),
+        totalCollateralUsd: wadToNumber(totalCollateral),
+        ltvWeightedCollateralUsdWad: ltvCollateral.toString(),
+        ltvWeightedCollateralUsd: wadToNumber(ltvCollateral),
+        liquidationWeightedCollateralUsdWad: weightedCollateral.toString(),
+        liquidationWeightedCollateralUsd: wadToNumber(weightedCollateral),
+        totalDebtUsdWad: totalDebt.toString(),
+        totalDebtUsd: wadToNumber(totalDebt),
+        healthFactorWad: healthFactorWad === null ? null : healthFactorWad.toString(),
+        healthFactor: healthFactorWad === null ? null : wadToNumber(healthFactorWad),
+        healthPercent,
+        borrowLimitUsdWad: ltvCollateral.toString(),
+        borrowLimitUsd: wadToNumber(ltvCollateral),
+        availableBorrowUsdWad: availableBorrow.toString(),
+        availableBorrowUsd: wadToNumber(availableBorrow),
+        minBorrowCollateralUsdWad: minBorrowCollateralUsdWad.toString(),
+        minBorrowCollateralUsd: wadToNumber(minBorrowCollateralUsdWad),
+        isLiquidatable: healthFactorWad !== null && healthFactorWad < WAD,
+        liveDataValid
+    };
+}
+/**
+ * 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 function computeAccountRisk(input) {
+    const { positions, reserves, liveState } = input;
+    const first = positions[0];
+    if (!first) throw new Error('Stellar math: computeAccountRisk needs at least one position row');
+    for (const p of positions){
+        if (p.accountId !== first.accountId) {
+            throw new Error(`Stellar math: computeAccountRisk received mixed account ids (${first.accountId}, ${p.accountId})`);
+        }
+    }
+    const snapshot = buildLiveSnapshot(liveState);
+    const supplies = [];
+    const borrows = [];
+    for (const p of positions){
+        const reserve = resolveReserve(reserves, p.spokeId, p.hubId, p.asset);
+        const supply = valueDtoPosition('supply', p, reserve, snapshot);
+        if (supply) supplies.push(supply);
+        const borrow = valueDtoPosition('borrow', p, reserve, snapshot);
+        if (borrow) borrows.push(borrow);
+    }
+    const floorWad = liveState?.minBorrowCollateralUsdWad != null ? toBigInt(liveState.minBorrowCollateralUsdWad, 'minBorrowCollateralUsdWad') : DEFAULT_MIN_BORROW_COLLATERAL_USD_WAD;
+    const liveDataValid = liveState !== undefined && [
+        ...supplies,
+        ...borrows
+    ].every((p)=>p.liveDataUsed);
+    return aggregateAccountRisk({
+        accountId: first.accountId,
+        owner: first.owner,
+        spokeId: first.spokeId,
+        mode: first.positionMode
+    }, supplies, borrows, floorWad, liveDataValid);
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 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";