@xoxno/sdk-js 1.0.218 → 1.0.220

package/dist/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/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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xoxno/sdk-js",
-  "version": "1.0.218",
+  "version": "1.0.220",
   "description": "The SDK to interact with the XOXNO Protocol!",
   "type": "module",
   "exports": {