@xoxno/sdk-js 1.0.217 → 1.0.219

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;

package/dist/cjs/sdk/stellar/route-verify.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Decoder and pre-signing verifier for the aggregator router's packed route
+ * (`routeXdr` / `swap_xdr`).
+ *
+ * The quote server is unauthenticated and returns the route as an opaque blob
+ * next to separate JSON display fields. The router enforces only the minimum
+ * that is ENCODED in the blob, so a caller must decode it and compare it with
+ * its own request before a wallet signs. The decoder mirrors
+ * `contracts/swap-aggregator/src/program.rs` (`Program::decode` + `validate`)
+ * and `execute::run` check for check; the encoder is `./scval-encode.ts`.
+ */
+import { type StellarNetwork } from './contracts.js';
+import { type StellarStrategySwapInput, type StellarSwapVenue } from './scval-encode.js';
+/**
+ * Cap on the serialized payload, checked before XDR parsing so a hostile
+ * response cannot force a proportional allocation. The largest legal payload
+ * (256 addresses, 126 amounts, 346 program bytes) is below 16 KiB.
+ */
+export declare const STELLAR_ROUTE_MAX_BYTES: number;
+export type StellarRouteErrorCode = 'MALFORMED' | 'OVERSIZED' | 'UNSUPPORTED_VERSION' | 'UNKNOWN_OPCODE' | 'INVALID_STRUCTURE' | 'TOKEN_IN_MISMATCH' | 'TOKEN_OUT_MISMATCH' | 'MIN_OUT_TOO_LOW' | 'AMOUNT_IN_EXCEEDED' | 'EXPECTATION_MISSING';
+/** Thrown when a route cannot be decoded or disagrees with the caller's request. */
+export declare class StellarRouteVerificationError extends Error {
+    readonly code: StellarRouteErrorCode;
+    constructor(code: StellarRouteErrorCode, message: string);
+}
+export type DecodedStellarRouteMode = {
+    kind: 'all';
+} | {
+    kind: 'prev';
+} | {
+    kind: 'fixed';
+    amount: bigint;
+} | {
+    kind: 'ppm';
+    ppm: number;
+};
+export type DecodedStellarRouteOp = {
+    kind: 'swap';
+    venue: StellarSwapVenue;
+    mode: DecodedStellarRouteMode;
+    pool: string;
+    tokenIn: string;
+    tokenOut: string;
+} | {
+    kind: 'burn' | 'mint';
+    pool: string;
+    shareToken: string;
+    /** Burn: first index of the per-constituent floor run. Mint: index of the minimum shares. */
+    amountIndex: number;
+};
+export interface DecodedStellarRoute {
+    version: number;
+    tokenIn: string;
+    tokenOut: string;
+    /** The minimum output the router enforces on chain (`amounts[min_out]`). */
+    totalMinOut: bigint;
+    referralId: number;
+    assets: string[];
+    amounts: bigint[];
+    ops: DecodedStellarRouteOp[];
+    /** Split weights in parts per million. */
+    weights: number[];
+}
+/**
+ * Any form the builders accept: base64 `routeXdr`, `0x` hex, raw bytes,
+ * `{ routeXdr }` / `{ swapXdr }` / `{ bytes }`, or a decoded payload object
+ * (encoded locally first, so the check covers exactly what would be signed).
+ */
+export type StellarRouteBytesInput = StellarStrategySwapInput;
+/**
+ * Decode and structurally validate route bytes. Applies every check of the
+ * on-chain decoder, so a route that `Program::decode` rejects does not decode
+ * here. Venue behaviour (pools, liquidity, budget) is not checked.
+ * @throws StellarRouteVerificationError
+ */
+export declare function decodeStellarRouteBytes(route: StellarRouteBytesInput): DecodedStellarRoute;
+/**
+ * Contract id of a quote-server token id: `C…` as is, `XLM` / `native` and
+ * `CODE:GISSUER` through the Stellar Asset Contract id of `network`.
+ * @throws StellarRouteVerificationError when the id needs a network and none is given.
+ */
+export declare function stellarTokenContractId(tokenId: string, network?: StellarNetwork): string;
+/** What the CALLER asked for. Take these from request state, not from the response. */
+export interface StellarRouteExpectation {
+    /** Input token contract id (`C…`). */
+    tokenIn: string;
+    /** Output token contract id (`C…`). */
+    tokenOut: string;
+    /** Lowest acceptable encoded `total_min_out`, base units. This is the value shown to the user. */
+    minOut: string | bigint;
+    /** Input amount, base units. When given, no fixed-size leg may spend more of `tokenIn`. */
+    amountIn?: string | bigint;
+}
+/**
+ * Decode `route` and require it to match `expected`. Call before signing any
+ * transaction that carries route bytes; never sign when this throws.
+ * @returns The decoded route, for display or further checks.
+ * @throws StellarRouteVerificationError
+ */
+export declare function verifyStellarRouteBytes(route: StellarRouteBytesInput, expected: StellarRouteExpectation): DecodedStellarRoute;

package/dist/cjs/sdk/stellar/scval-encode.d.ts

@@ -21,6 +21,16 @@ export declare const STELLAR_SWAP_VENUE_OPCODE: Record<StellarSwapVenue, number>
 export declare const STELLAR_PROGRAM_VERSION = 1;
 /** Split weights are parts per million. */
 export declare const PPM_DENOMINATOR = 1000000;
+export declare const OP_BURN = 5;
+export declare const OP_MINT = 6;
+export declare const MODE_ALL = 0;
+export declare const MODE_PREV = 1;
+export declare const MODE_FIXED_BASE = 2;
+export declare const MODE_PPM_BASE = 128;
+export declare const MAX_OPS = 48;
+export declare const MAX_WEIGHTS = 32;
+export declare const MAX_ASSETS = 256;
+export declare const MAX_AMOUNTS: number;
 export interface StellarStrategySwapHopInput {
     /** Quote-side estimate; not carried on the wire. */
     amountOut?: string;

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

@@ -11,8 +11,27 @@
  * opaque route bytes to the controller, which forwards them to the aggregator.
  */
 import type { StellarAggregatorQuoteResponseDto } from '@xoxno/types';
+import { type StellarNetwork } from './contracts.js';
 import type { BuiltStellarTx, StellarBuilderOptions } from './lending.js';
 import { type StellarStrategyPayloadInput, type StellarStrategySwapHopInput, type StellarStrategySwapInput, type StellarStrategySwapPathInput } from './scval-encode.js';
+/**
+ * The caller's own request, used to check a quote before it is signed. Every
+ * field that is absent falls back to the quote's JSON, which proves only that
+ * the response agrees with itself — pass request state whenever it is known.
+ */
+export interface StellarQuoteExpectation {
+    tokenIn?: string;
+    tokenOut?: string;
+    /** Lowest acceptable minimum output, base units. */
+    minOut?: string | bigint;
+    amountIn?: string | bigint;
+}
+export interface StellarQuoteMapOptions {
+    referralId?: number | string;
+    /** Needed only when a token id is `XLM` or `CODE:GISSUER` instead of `C…`. */
+    network?: StellarNetwork;
+    expected?: StellarQuoteExpectation;
+}
 export type StellarStrategyPayload = StellarStrategyPayloadInput;
 export type StellarStrategySwap = StellarStrategySwapInput;
 export type StellarStrategySwapHop = StellarStrategySwapHopInput;
@@ -55,15 +74,16 @@ export declare function buildStellarBatchSwapTx(opts: StellarBatchSwapBuilderOpt
  * Translate a quote-server response into the decoded `StrategyPayload` shape.
  * Prefer `mapQuoteResponseToStrategySwap` when the quote includes `routeXdr`.
  */
-export declare function mapQuoteResponseToStrategyPayload(quote: StellarAggregatorQuoteResponseDto, opts?: {
-    referralId?: number | string;
-}): StellarStrategyPayloadInput;
+export declare function mapQuoteResponseToStrategyPayload(quote: StellarAggregatorQuoteResponseDto, opts?: Pick<StellarQuoteMapOptions, 'referralId'>): StellarStrategyPayloadInput;
 /**
  * Return the executable quote route when the API provided it; otherwise build
  * the decoded fallback payload from hop/path fields.
+ *
+ * Either form is decoded and checked before it is returned: it must spend and
+ * deliver the expected pair and enforce a minimum that is not below the
+ * quote's `amountOutMin` (what a UI displays) nor below `expected.minOut`.
+ * @throws StellarRouteVerificationError — never sign a quote that throws here.
  */
-export declare function mapQuoteResponseToStrategySwap(quote: StellarAggregatorQuoteResponseDto, opts?: {
-    referralId?: number | string;
-}): StellarStrategySwapInput;
+export declare function mapQuoteResponseToStrategySwap(quote: StellarAggregatorQuoteResponseDto, opts?: StellarQuoteMapOptions): StellarStrategySwapInput;
 /** @deprecated Use `mapQuoteResponseToStrategyPayload`. */
 export declare const mapQuoteResponseToAggregatorSwap: typeof mapQuoteResponseToStrategyPayload;