@xoxno/sdk-js 1.0.137 → 1.0.142

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

@@ -0,0 +1,171 @@
+/**
+ * Stellar lending user-operation transaction builders.
+ *
+ * Each builder takes an `*Args` DTO from `@xoxno/types` plus a shared
+ * `StellarBuilderOptions` ({ network, caller, sourceSequence, ... }) and returns
+ * an unsigned transaction XDR string ready for 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 type { BorrowArgs, FlashLoanArgs, LiquidateArgs, MultiplyArgs, RepayArgs, RepayDebtWithCollateralArgs, SupplyArgs, SwapCollateralArgs, SwapDebtArgs, WithdrawArgs } from '@xoxno/types';
+import { xdr } from '@stellar/stellar-sdk';
+import { type StellarNetwork } from './contracts';
+import { type StellarStrategySwapHopInput, type StellarStrategySwapInput, type StellarStrategySwapPathInput } from './scval-encode';
+/**
+ * Stellar `G...` public key of the caller (tx source account).
+ */
+export type StellarAccountAddress = string;
+export interface StellarBuilderOptions {
+    network: StellarNetwork;
+    caller: StellarAccountAddress;
+    /**
+     * Current sequence number of the caller account, as a decimal string.
+     * Callers fetch this from Soroban RPC (`server.getAccount(caller)`) before
+     * building. Keeping it as an input (rather than fetching inside the builder)
+     * makes builders sync-friendly, RPC-free, and deterministic for snapshot tests.
+     */
+    sourceSequence: string;
+    /**
+     * Override the controller contract address. Normally resolved from env via
+     * `getStellarLendingController(network)` — override is for tests and
+     * preview/staging deployments.
+     */
+    controllerAddress?: string;
+    /**
+     * Override the governance (timelock) contract address. Normally resolved from
+     * env via `getStellarGovernance(network)` — override is for tests and
+     * preview/staging deployments. Required (env or override) for the governance
+     * `propose_*` / `execute` / `execute_*` builders.
+     */
+    governanceAddress?: string;
+    /** Base fee in stroops (default BASE_FEE = "100"). */
+    fee?: string;
+    /** Tx timeout in seconds (default 300). */
+    timeoutSeconds?: number;
+}
+export interface BuiltStellarTx {
+    /** Unsigned transaction XDR (base64) ready for wallet signing. */
+    xdr: string;
+}
+/**
+ * Input shape for the Stellar-specific `swap` payload carried on
+ * `MultiplyArgs.steps`, `SwapDebtArgs.steps`, `SwapCollateralArgs.steps`, and
+ * `RepayDebtWithCollateralArgs.steps`.
+ *
+ * `@xoxno/types` declares `steps: unknown` on these DTOs so every chain owns
+ * its own encoding. On Stellar, callers pass opaque aggregator strategy bytes,
+ * normally the quote response `routeXdr` (base64 ScVal XDR) or `{ routeXdr }`.
+ * The lending controller forwards those bytes to the aggregator and does not
+ * decode the aggregator route.
+ */
+export type StellarSwapStepsInput = StellarStrategySwapInput;
+export type StellarSwapHopInput = StellarStrategySwapHopInput;
+export type StellarSwapPathInput = StellarStrategySwapPathInput;
+export type { StellarSwapVenue } from './scval-encode';
+/**
+ * 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 declare function buildTx(opts: StellarBuilderOptions, method: string, params: xdr.ScVal[]): BuiltStellarTx;
+export interface StellarTokenAmount {
+    token: string;
+    amount: string;
+}
+export interface StellarSupplyBatchArgs {
+    accountNonce?: number;
+    eModeCategory?: number;
+    assets: ReadonlyArray<StellarTokenAmount>;
+}
+export interface StellarBorrowBatchArgs {
+    accountNonce: number;
+    borrows: ReadonlyArray<StellarTokenAmount>;
+}
+export interface StellarWithdrawBatchArgs {
+    accountNonce: number;
+    withdrawals: ReadonlyArray<StellarTokenAmount>;
+    /**
+     * Optional recipient override (`C...` or `G...`). The pool pays the
+     * withdrawn tokens to this address instead of the caller. Omit for the
+     * standard flow — the contract arg is still sent, encoded as
+     * `Option::None` (ScVal void), which the controller resolves to the
+     * caller.
+     */
+    to?: string;
+}
+export interface StellarRepayBatchArgs {
+    accountNonce: number;
+    payments: ReadonlyArray<StellarTokenAmount>;
+}
+/**
+ * supply(caller, account_id: u64, e_mode_category: u32, assets: Vec<(Address, i128)>)
+ */
+export declare function buildStellarSupplyBatchTx(opts: StellarBuilderOptions, args: StellarSupplyBatchArgs): BuiltStellarTx;
+/**
+ * @xoxno/types `SupplyArgs` is a single-asset shape; the Stellar contract
+ * expects a batch — we wrap the single asset in a 1-element Vec.
+ */
+export declare function buildStellarSupplyTx(opts: StellarBuilderOptions, args: SupplyArgs): BuiltStellarTx;
+export declare function buildStellarBorrowBatchTx(opts: StellarBuilderOptions, args: StellarBorrowBatchArgs): BuiltStellarTx;
+/**
+ * borrow(caller, account_id: u64, borrows: Vec<(Address, i128)>)
+ */
+export declare function buildStellarBorrowTx(opts: StellarBuilderOptions, args: BorrowArgs): BuiltStellarTx;
+export declare function buildStellarWithdrawBatchTx(opts: StellarBuilderOptions, args: StellarWithdrawBatchArgs): BuiltStellarTx;
+/**
+ * withdraw(caller, account_id: u64, withdrawals: Vec<(Address, i128)>,
+ * to: Option<Address>) — `to` is always sent; absent means the caller
+ * receives the funds.
+ */
+export declare function buildStellarWithdrawTx(opts: StellarBuilderOptions, args: WithdrawArgs): BuiltStellarTx;
+export declare function buildStellarRepayBatchTx(opts: StellarBuilderOptions, args: StellarRepayBatchArgs): BuiltStellarTx;
+/**
+ * repay(caller, account_id: u64, payments: Vec<(Address, i128)>)
+ */
+export declare function buildStellarRepayTx(opts: StellarBuilderOptions, args: RepayArgs): BuiltStellarTx;
+/**
+ * liquidate(liquidator, account_id: u64, debt_payments: Vec<(Address, i128)>)
+ */
+export declare function buildStellarLiquidateTx(opts: StellarBuilderOptions, args: LiquidateArgs): BuiltStellarTx;
+/**
+ * flash_loan(caller, asset, amount: i128, receiver, data: Bytes)
+ */
+export declare function buildStellarFlashLoanTx(opts: StellarBuilderOptions, args: FlashLoanArgs): BuiltStellarTx;
+/**
+ * multiply(caller, account_id, e_mode_category, collateral_token,
+ *          debt_to_flash_loan: i128, debt_token, mode: PositionMode,
+ *          swap: Bytes, initial_payment: Option<(Address, 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`.
+ */
+export declare function buildStellarMultiplyTx(opts: StellarBuilderOptions, args: MultiplyArgs): BuiltStellarTx;
+/**
+ * swap_debt(caller, account_id, existing_debt_token, new_debt_amount: i128,
+ *           new_debt_token, steps: Bytes)
+ */
+export declare function buildStellarSwapDebtTx(opts: StellarBuilderOptions, args: SwapDebtArgs): BuiltStellarTx;
+/**
+ * swap_collateral(caller, account_id, current_collateral, from_amount: i128,
+ *                 new_collateral, steps: Bytes)
+ */
+export declare function buildStellarSwapCollateralTx(opts: StellarBuilderOptions, args: SwapCollateralArgs): BuiltStellarTx;
+/**
+ * repay_debt_with_collateral(caller, account_id, collateral_token,
+ *                            collateral_amount: i128, debt_token,
+ *                            steps: Bytes, close_position: bool)
+ */
+export declare function buildStellarRepayDebtWithCollateralTx(opts: StellarBuilderOptions, args: RepayDebtWithCollateralArgs): BuiltStellarTx;

package/dist/cjs/sdk/stellar/position-mode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Map MVX `PositionMode` numbering to the Stellar lending controller enum.
+ *
+ * MVX: None=0, Normal=1, Multiply=2, Long=3, Short=4
+ * Stellar: Normal=0, Multiply=1, Long=2, Short=3
+ */
+export declare function toStellarPositionMode(mvxMode: number): number;

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

@@ -0,0 +1,25 @@
+import type { FeeBumpTransaction, Transaction } from '@stellar/stellar-sdk';
+import type { BuiltStellarTx } from './lending';
+/**
+ * The single `rpc.Server` capability the prepare helpers need. Declared
+ * structurally instead of `Pick<rpc.Server, 'prepareTransaction'>` so the
+ * published `.d.ts` references stellar-sdk's concrete `Transaction` exports
+ * rather than its `rpc` namespace — the namespaced form trips
+ * `dts-bundle-generator`'s external-type resolution under stellar-sdk v16. A
+ * real `rpc.Server` satisfies this structurally, so call sites are unchanged.
+ */
+export interface StellarTxPreparer {
+    prepareTransaction(tx: Transaction | FeeBumpTransaction): Promise<Transaction>;
+}
+export declare function tagStellarInvokedContractError(contractId: string, error: unknown): Error;
+/**
+ * Simulate a built Soroban envelope (footprint, auth, resource fee) and return
+ * prepared base64 XDR. Optionally tag failures with the invoked contract id so
+ * UIs can map `Error(Contract, #N)` codes to the right ABI.
+ */
+export declare function prepareStellarTxXdr(server: StellarTxPreparer, xdr: string, opts?: {
+    invokedContractId?: string;
+}): Promise<string>;
+export declare function prepareStellarBuiltTx(server: StellarTxPreparer, built: BuiltStellarTx, opts?: {
+    invokedContractId?: string;
+}): Promise<string>;

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

@@ -0,0 +1,58 @@
+/**
+ * Typed client for the Stellar aggregator quote server
+ * (`GET /api/v1/quote`, `GET /api/v1/tokens`).
+ *
+ * The quote server is a standalone Rust service (deployed independently
+ * of the main XOXNO API), so this module hits its base URL directly
+ * rather than routing through the swagger-driven endpoints map.
+ *
+ * All response shapes are mirrored 1:1 by `@xoxno/types` DTOs
+ * (`StellarAggregatorQuoteResponseDto`, `StellarQuotePathDto`, etc.) —
+ * the wire shape is camelCase, the Soroban contract receives snake_case
+ * after the SDK encoder rewrites field names.
+ */
+import type { StellarAggregatorQuoteRequestDto, StellarAggregatorQuoteResponseDto, StellarTokenKind } from '@xoxno/types';
+import { type StellarNetwork } from './contracts';
+/**
+ * Resolved token entry returned by the quote server's tokens endpoint.
+ * Mirrors the indexer's `TokenEntry` JSON exactly.
+ */
+export interface StellarQuoteToken {
+    /** Canonical token id. `C…` for Soroban contracts; `CODE:GISSUER…`
+     *  for Classic; `XLM` for native. */
+    id: string;
+    kind: StellarTokenKind;
+    decimals: number;
+    /** Soroban Asset Contract peer for Classic assets (null otherwise). */
+    sacPeer: string | null;
+    /** Classic asset code (for Classic / SAC entries; null for Soroban). */
+    code: string | null;
+    /** Number of pools touching this token in the current snapshot. */
+    degree: number;
+}
+export interface StellarQuoteFetchOptions {
+    /** Network selects which base URL to hit. */
+    network: StellarNetwork;
+    /** Override the resolved base URL (useful for tests / preview). */
+    baseUrl?: string;
+    /** Per-call fetch options (signal, headers, etc.). */
+    fetchOptions?: RequestInit;
+}
+/**
+ * Fetch a route quote from the Stellar aggregator quote server.
+ *
+ * Forward mode: pass `amountIn` to compute the maximum reachable
+ * `amountOut`. Reverse mode: pass `amountOut` to compute the minimum
+ * `amountIn` that delivers at least that output.
+ *
+ * Pass both `sender` (G-strkey) and `router` (C-strkey) to receive a
+ * ready-to-sign envelope under `transaction.envelopeXdr`. The caller
+ * must still run `simulateTransaction` to attach Soroban resource fees
+ * before signing.
+ */
+export declare function getStellarAggregatorQuote(request: StellarAggregatorQuoteRequestDto, opts: StellarQuoteFetchOptions): Promise<StellarAggregatorQuoteResponseDto>;
+/**
+ * List tokens currently indexed by the quote server. Useful to populate
+ * pickers or validate that a user-supplied token has on-chain liquidity.
+ */
+export declare function getStellarQuoteTokens(opts: StellarQuoteFetchOptions): Promise<StellarQuoteToken[]>;

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

@@ -0,0 +1,7 @@
+import type { StellarStrategyPayloadInput } from './scval-encode';
+/**
+ * Placeholder aggregator route when `repay_debt_with_collateral` has
+ * `collateral_token === debt_token`. The controller short-circuits and never
+ * decodes the route, but the Soroban arg must still be valid `Bytes`.
+ */
+export declare function buildSameTokenRepaySwapSteps(token: string, collateralAmount: string): StellarStrategyPayloadInput;

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

@@ -0,0 +1,115 @@
+/**
+ * Soroban `ScVal` encoding primitives for the Stellar lending builders.
+ *
+ * i128/u128 values cross the boundary as decimal strings (`new ScInt(str)`).
+ * Addresses (Stellar `G...` accounts and Soroban `C...` contracts) encode via
+ * `new Address(str).toScVal()`.
+ */
+import { xdr } from '@stellar/stellar-sdk';
+/**
+ * On-chain swap venues, validated at runtime for a caller-supplied venue.
+ * Mirrors the Soroban-only aggregator router's `SwapVenue` enum.
+ */
+export declare const STELLAR_SWAP_VENUES: readonly ["Soroswap", "Aquarius", "Phoenix", "Sushi", "CometDex"];
+export type StellarSwapVenue = (typeof STELLAR_SWAP_VENUES)[number];
+export interface StellarStrategySwapHopInput {
+    amountOut: string;
+    pool: string;
+    tokenIn: string;
+    tokenOut: string;
+    venue: StellarSwapVenue;
+}
+export interface StellarStrategySwapPathInput {
+    hops: StellarStrategySwapHopInput[];
+    splitPpm: number;
+}
+export interface StellarStrategyPayloadInput {
+    paths: StellarStrategySwapPathInput[];
+    referralId?: number | string;
+    tokenIn: string;
+    tokenOut: string;
+    totalMinOut: string;
+}
+export type StellarStrategySwapInput = string | Uint8Array | {
+    routeXdr: string;
+} | {
+    swapXdr: string;
+} | {
+    bytes: string | Uint8Array;
+} | StellarStrategyPayloadInput;
+export type StellarSwapStepsInput = StellarStrategySwapInput;
+export declare const addr: (a: string) => xdr.ScVal;
+export declare const i128: (s: string) => xdr.ScVal;
+export declare const u32: (n: number) => xdr.ScVal;
+export declare const u64: (n: number | string) => xdr.ScVal;
+export declare const bool: (b: boolean) => xdr.ScVal;
+export declare const str: (s: string) => xdr.ScVal;
+export declare const sym: (s: string) => xdr.ScVal;
+export declare const voidVal: () => xdr.ScVal;
+export declare const vec: (items: xdr.ScVal[]) => xdr.ScVal;
+export declare const bytes: (hex: string) => xdr.ScVal;
+/**
+ * Encode a Soroban `BytesN<N>` (default 32) — a fixed-length byte array such as
+ * a WASM hash. Validates the decoded length so a malformed hash fails at the
+ * SDK boundary, not deep inside the host.
+ */
+export declare const bytesN: (hex: string, length?: number) => xdr.ScVal;
+/**
+ * Encode a Soroban `Option<T>`: `None` is `scvVoid`, `Some(x)` is the bare
+ * encoded `x` (Soroban does not wrap `Some`). NOT for the contract's custom
+ * `OracleSourceConfigInputOption` enum, which is a tagged union — see
+ * `encodeOracleSourceConfigInputOption` in `admin.ts`.
+ */
+export declare const option: <T>(value: T | undefined | null, encode: (v: T) => xdr.ScVal) => xdr.ScVal;
+/**
+ * Encode a single Soroban tuple `(Address, i128)` as a 2-element `scvVec`.
+ */
+export declare const tupleAddrAmount: (token: string, amount: string) => xdr.ScVal;
+/**
+ * Encode `Vec<(Address, i128)>` — a Soroban tuple-vec of (asset, amount).
+ * Each tuple is a 2-element `scvVec`.
+ */
+export declare const tupleAddrAmountVec: (entries: Array<{
+    token: string;
+    amount: string;
+}>) => xdr.ScVal;
+/**
+ * Encode a Soroban `struct` — at the XDR level, structs are maps with
+ * `Symbol` keys in **lexicographic order** of field names.
+ */
+export declare const scStruct: (fields: Record<string, xdr.ScVal>) => xdr.ScVal;
+/**
+ * Encode a Soroban `enum SwapVenue` (tag-only / unit variant). At the XDR level
+ * a unit variant is `scvVec([symbol_name])`.
+ */
+export declare const encodeSwapVenue: (venue: StellarSwapVenue) => xdr.ScVal;
+/**
+ * Encode the aggregator router's decoded `StrategyPayload` struct. The caller
+ * usually receives this as quote `routeXdr`; this helper is for tests and for
+ * callers that construct routes locally.
+ */
+export declare const encodeStrategyPayload: (payload: StellarStrategyPayloadInput) => xdr.ScVal;
+/** @deprecated Use `encodeStrategyPayload`. */
+export declare const encodeAggregatorSwap: (payload: StellarStrategyPayloadInput) => xdr.ScVal;
+export declare const encodeStrategyPayloadToBytes: (payload: StellarStrategyPayloadInput) => xdr.ScVal;
+/**
+ * Validate the untyped `steps` field and narrow it to `StrategyPayload`.
+ * Throws if the caller passed the wrong shape so the failure surfaces at the
+ * SDK boundary, not inside the Soroban host on-chain.
+ */
+export declare const asStellarStrategyPayload: (steps: unknown) => StellarStrategyPayloadInput;
+/**
+ * Encode opaque strategy bytes for the lending controller. Accepted inputs:
+ *   - quote `routeXdr` base64 string
+ *   - `{ routeXdr }` / `{ swapXdr }`
+ *   - raw `Uint8Array` / `{ bytes }`
+ *   - decoded `StrategyPayload` object
+ */
+export declare const asStellarStrategySwapBytes: (steps: unknown) => xdr.ScVal;
+/** @deprecated Use `asStellarStrategyPayload` or `asStellarStrategySwapBytes`. */
+export declare const asStellarSwapSteps: (steps: unknown) => StellarStrategyPayloadInput;
+/**
+ * Validate the untyped `data` field on FlashLoanArgs and narrow it to
+ * Buffer / hex string for Soroban `Bytes` encoding.
+ */
+export declare const asStellarBytes: (data: unknown) => xdr.ScVal;

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

@@ -0,0 +1,70 @@
+/**
+ * Stellar aggregator router direct-call transaction builder.
+ *
+ * Builds an unsigned XDR for
+ * `router.execute_strategy(sender, total_in, swap_xdr)` so a user can swap
+ * A -> B without involving the lending controller. The strategy route is
+ * opaque bytes: normally the quote response `routeXdr`, decoded into Soroban
+ * `Bytes` for the contract call.
+ *
+ * Lending strategies use the builders in `./lending.ts`; they pass the same
+ * opaque route bytes to the controller, which forwards them to the aggregator.
+ */
+import type { StellarAggregatorQuoteResponseDto } from '@xoxno/types';
+import type { BuiltStellarTx, StellarBuilderOptions } from './lending';
+import { type StellarStrategyPayloadInput, type StellarStrategySwapHopInput, type StellarStrategySwapInput, type StellarStrategySwapPathInput } from './scval-encode';
+export type StellarStrategyPayload = StellarStrategyPayloadInput;
+export type StellarStrategySwap = StellarStrategySwapInput;
+export type StellarStrategySwapHop = StellarStrategySwapHopInput;
+export type StellarStrategySwapPath = StellarStrategySwapPathInput;
+export interface StellarExecuteStrategyBuilderOptions extends StellarBuilderOptions {
+    /**
+     * Override the resolved aggregator router contract address. Normally
+     * resolved from `STELLAR_AGGREGATOR_ROUTER[network]`.
+     */
+    routerAddress?: string;
+    /**
+     * Total input amount passed to `execute_strategy` (i128 decimal string).
+     * For a quote-derived swap, pass `quote.amountIn`.
+     */
+    totalIn: string;
+    /**
+     * Referral identifier used only when the `swap` input is a decoded
+     * `StrategyPayload` object and does not already include `referralId`.
+     * Quote `routeXdr` already contains the referral chosen by the quote server.
+     */
+    referralId?: number | string;
+}
+/** @deprecated Use `StellarExecuteStrategyBuilderOptions`. */
+export interface StellarBatchSwapBuilderOptions extends StellarExecuteStrategyBuilderOptions {
+}
+export declare const encodeStrategyPayloadToRouteXdr: (payload: StellarStrategyPayloadInput) => string;
+/**
+ * Build an unsigned XDR for a direct user -> aggregator router swap.
+ *
+ * Pass the quote response `routeXdr` string or `{ routeXdr }` directly when
+ * available. Decoded `StrategyPayload` objects are accepted for local tests and
+ * custom route builders.
+ */
+export declare function buildStellarExecuteStrategyTx(opts: StellarExecuteStrategyBuilderOptions, swap: StellarStrategySwapInput): BuiltStellarTx;
+/**
+ * @deprecated The router no longer exposes `batch_execute`; this wrapper now
+ * builds `execute_strategy(sender, total_in, swap_xdr)`.
+ */
+export declare function buildStellarBatchSwapTx(opts: StellarBatchSwapBuilderOptions, swap: StellarStrategySwapInput): BuiltStellarTx;
+/**
+ * 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;
+/**
+ * Return the executable quote route when the API provided it; otherwise build
+ * the decoded fallback payload from hop/path fields.
+ */
+export declare function mapQuoteResponseToStrategySwap(quote: StellarAggregatorQuoteResponseDto, opts?: {
+    referralId?: number | string;
+}): StellarStrategySwapInput;
+/** @deprecated Use `mapQuoteResponseToStrategyPayload`. */
+export declare const mapQuoteResponseToAggregatorSwap: typeof mapQuoteResponseToStrategyPayload;