@xoxno/sdk-js 1.0.218 → 1.0.220

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

@@ -0,0 +1 @@
+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,6 +14,8 @@ 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';

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;