@xoxno/sdk-js 1.0.98 → 1.0.99

package/dist/sdk/index.d.ts

@@ -1,3 +1,4 @@
 import type { XOXNOClient } from '../utils/api';
 import type { SDK } from './types';
+export * from './stellar';
 export declare function buildSdk(client: XOXNOClient): SDK;

package/dist/sdk/stellar/__tests__/lending.test.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Snapshot + sanity tests for the Stellar Soroban lending transaction builders.
+ *
+ * These tests assert:
+ *   1. Every builder returns a non-empty base64 XDR.
+ *   2. XDR parses back into a valid Transaction with exactly one InvokeHostFunction
+ *      operation targeting the configured controller contract.
+ *   3. The function name encoded in the XDR matches the Stellar controller
+ *      entry point exactly (`supply`, `borrow`, `withdraw`, `repay`,
+ *      `liquidate`, `flash_loan`, `multiply`, `swap_debt`, `swap_collateral`,
+ *      `repay_debt_with_collateral`).
+ *   4. The XDR is deterministic — identical fixture inputs yield identical XDR.
+ *   5. Stable snapshots for the full XDR of every builder (regression guard
+ *      for any unintended encoding change).
+ *
+ * Builders are RPC-free — they accept a `sourceSequence` so output is
+ * fully deterministic and snapshot-testable. The UI layer is responsible
+ * for fetching the sequence and running `rpc.Server.prepareTransaction`
+ * before signing.
+ */
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * Stellar lending controller contract addresses + Soroban RPC config per network.
+ *
+ * Addresses are env-sourced so ops can rotate mainnet/testnet deployments without
+ * a code change. Defaults fall back to empty string so a missing env surfaces as a
+ * clear "controller address not configured" error at builder call time rather than
+ * silently pointing at the wrong contract.
+ */
+export type StellarNetwork = 'mainnet' | 'testnet';
+/**
+ * Stellar controller contract addresses per network.
+ * Env vars:
+ *   - STELLAR_LENDING_CONTROLLER_MAINNET
+ *   - STELLAR_LENDING_CONTROLLER_TESTNET
+ */
+export declare const STELLAR_LENDING_CONTROLLER: Record<StellarNetwork, string>;
+/**
+ * Default Soroban RPC URLs per network.
+ * Overridable at runtime via the `sorobanRpcUrl` option on each builder.
+ */
+export declare const STELLAR_SOROBAN_RPC_URL: Record<StellarNetwork, string>;
+/**
+ * Stellar network passphrases (Soroban tx signing domain separator).
+ * These are fixed by the Stellar network itself and must not be overridden.
+ */
+export declare const STELLAR_NETWORK_PASSPHRASE: Record<StellarNetwork, string>;
+/**
+ * Assert a controller address is configured for the target network.
+ * Throws early with a clear message rather than building an XDR that points at `""`.
+ */
+export declare function getStellarLendingController(network: StellarNetwork): string;

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

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './lending';

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

@@ -0,0 +1,143 @@
+/**
+ * Stellar Soroban lending transaction builders (Wave 1B).
+ *
+ * Each builder takes a Wave 0 `*Args` DTO from @xoxno/types plus a shared
+ * `StellarBuilderOptions` ({ network, caller, sourceSequence, ... }) and
+ * returns an unsigned transaction XDR string ready for wallet signing
+ * (Freighter / LOBSTR / xBull / WalletConnect via StellarWalletsKit).
+ *
+ * Mirrors the Stellar controller entry points in
+ * rs-lending/stellar/controller/src/lib.rs:
+ *
+ *   supply(caller, account_id: u64, e_mode_category: u32, assets: Vec<(Address, i128)>) -> u64
+ *   borrow(caller, account_id: u64, borrows: Vec<(Address, i128)>)
+ *   withdraw(caller, account_id: u64, withdrawals: Vec<(Address, i128)>)
+ *   repay(caller, account_id: u64, payments: Vec<(Address, i128)>)
+ *   liquidate(liquidator, account_id: u64, debt_payments: Vec<(Address, i128)>)
+ *   flash_loan(caller, asset, amount: i128, receiver, data: Bytes)
+ *   multiply(caller, account_id, e_mode_category, collateral_token,
+ *            debt_to_flash_loan: i128, debt_token, mode: u32, steps: SwapSteps) -> u64
+ *   swap_debt(caller, account_id, existing_debt_token, new_debt_amount: i128,
+ *             new_debt_token, steps: SwapSteps)
+ *   swap_collateral(caller, account_id, current_collateral, from_amount: i128,
+ *                   new_collateral, steps: SwapSteps)
+ *   repay_debt_with_collateral(caller, account_id, collateral_token,
+ *                              collateral_amount: i128, debt_token,
+ *                              steps: SwapSteps, close_position: bool)
+ *
+ * i128 values cross the boundary as decimal strings and are encoded via
+ * `new ScInt(str).toI128()`. addresses (Stellar `G...` accounts and Soroban
+ * `C...` contracts) are encoded via `new Address(str).toScVal()`.
+ *
+ * These builders are RPC-free on purpose: they accept a caller-supplied
+ * `sourceSequence` so the returned XDR is deterministic and snapshot-testable.
+ * The UI hook layer (Wave 1C) is responsible for fetching the current sequence
+ * via `rpc.Server.getAccount(caller)` and calling `rpc.Server.prepareTransaction`
+ * (which handles 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 { type StellarNetwork } from './contracts';
+/**
+ * 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;
+    /** 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 `SwapSteps` payload carried on
+ * `MultiplyArgs.steps`, `SwapDebtArgs.steps`, `SwapCollateralArgs.steps`,
+ * `RepayDebtWithCollateralArgs.steps`.
+ *
+ * @xoxno/types declares `steps: unknown` on the Wave 0 DTOs so every chain
+ * owns its own encoding. On Stellar, this is what callers MUST pass,
+ * which is serialised to a Soroban `Vec<SwapHop>` struct matching
+ * rs-lending/stellar/common/src/types.rs:
+ *
+ *   pub struct SwapHop {
+ *       pub pool_address: Address,
+ *       pub token_in: Address,
+ *       pub token_out: Address,
+ *       pub min_amount_out: i128,
+ *   }
+ */
+export interface StellarSwapStepsInput {
+    hops: StellarSwapHopInput[];
+}
+export interface StellarSwapHopInput {
+    poolAddress: string;
+    tokenIn: string;
+    tokenOut: string;
+    /** Decimal string i128. */
+    minAmountOut: string;
+}
+/**
+ * supply(caller, account_id: u64, e_mode_category: u32, assets: Vec<(Address, i128)>)
+ * @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;
+/**
+ * borrow(caller, account_id: u64, borrows: Vec<(Address, i128)>)
+ */
+export declare function buildStellarBorrowTx(opts: StellarBuilderOptions, args: BorrowArgs): BuiltStellarTx;
+/**
+ * withdraw(caller, account_id: u64, withdrawals: Vec<(Address, i128)>)
+ */
+export declare function buildStellarWithdrawTx(opts: StellarBuilderOptions, args: WithdrawArgs): 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: u32, steps: SwapSteps) -> u64
+ */
+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: SwapSteps)
+ */
+export declare function buildStellarSwapDebtTx(opts: StellarBuilderOptions, args: SwapDebtArgs): BuiltStellarTx;
+/**
+ * swap_collateral(caller, account_id, current_collateral, from_amount: i128,
+ *                 new_collateral, steps: SwapSteps)
+ */
+export declare function buildStellarSwapCollateralTx(opts: StellarBuilderOptions, args: SwapCollateralArgs): BuiltStellarTx;
+/**
+ * repay_debt_with_collateral(caller, account_id, collateral_token,
+ *                            collateral_amount: i128, debt_token,
+ *                            steps: SwapSteps, close_position: bool)
+ */
+export declare function buildStellarRepayDebtWithCollateralTx(opts: StellarBuilderOptions, args: RepayDebtWithCollateralArgs): BuiltStellarTx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xoxno/sdk-js",
-  "version": "1.0.98",
+  "version": "1.0.99",
   "description": "The SDK to interact with the XOXNO Protocol!",
   "type": "module",
   "exports": {
@@ -93,6 +93,7 @@
   "dependencies": {
     "@multiversx/sdk-core": "^15.3.2",
     "@multiversx/sdk-network-providers": "^2.9.3",
-    "@xoxno/types": "^1.0.379"
+    "@stellar/stellar-sdk": "^15.0.1",
+    "@xoxno/types": "^1.0.384"
   }
 }