@xoxno/sdk-js 1.0.223 → 1.0.225

package/dist/esm/sdk/stellar/scval-encode.js

@@ -0,0 +1,464 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * 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 { Address, ScInt, xdr } from "@stellar/stellar-sdk";
+import { Buffer } from "buffer";
+/**
+ * On-chain swap venues, validated at runtime for a caller-supplied venue.
+ * Mirrors the Soroban-only aggregator router's opcode table.
+ */ export const STELLAR_SWAP_VENUES = [
+    'Soroswap',
+    'Aquarius',
+    'Phoenix',
+    'Sushi',
+    'CometDex'
+];
+/**
+ * Instruction opcode per venue. Part of the on-chain ABI — see
+ * `contracts/swap-aggregator/src/program.rs`.
+ */ export const STELLAR_SWAP_VENUE_OPCODE = {
+    Soroswap: 0,
+    Aquarius: 1,
+    Phoenix: 2,
+    Sushi: 3,
+    CometDex: 4
+};
+/** Wire version of the packed program. Must match the contract's `VERSION`. */ export const STELLAR_PROGRAM_VERSION = 1;
+/** Split weights are parts per million. */ export const PPM_DENOMINATOR = 1000000;
+export const OP_BURN = 5;
+export const OP_MINT = 6;
+export const MODE_ALL = 0;
+export const MODE_PREV = 1;
+export const MODE_FIXED_BASE = 2;
+export const MODE_PPM_BASE = 128;
+export const MAX_OPS = 48;
+export const MAX_WEIGHTS = 32;
+export const MAX_ASSETS = 256;
+export const MAX_AMOUNTS = MODE_PPM_BASE - MODE_FIXED_BASE;
+export const addr = (a)=>new Address(a).toScVal();
+export const i128 = (s)=>new ScInt(s).toI128();
+export const u32 = (n)=>xdr.ScVal.scvU32(n);
+export const u64 = (n)=>{
+    if (typeof n === 'number' && !Number.isSafeInteger(n)) {
+        throw new Error('Stellar builder: u64 numbers must be safe integers; pass a decimal string for larger values');
+    }
+    return new ScInt(typeof n === 'string' ? n : n.toString()).toU64();
+};
+export const bool = (b)=>xdr.ScVal.scvBool(b);
+export const str = (s)=>xdr.ScVal.scvString(s);
+export const sym = (s)=>xdr.ScVal.scvSymbol(s);
+export const voidVal = ()=>xdr.ScVal.scvVoid();
+export const vec = (items)=>xdr.ScVal.scvVec(items);
+export const bytes = (hex)=>{
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const buf = Buffer.from(cleanHex, 'hex');
+    return xdr.ScVal.scvBytes(buf);
+};
+/**
+ * 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 const bytesN = (hex, length = 32)=>{
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const buf = Buffer.from(cleanHex, 'hex');
+    if (buf.length !== length) {
+        throw new Error(`Stellar builder: expected a ${length}-byte BytesN (got ${buf.length} bytes from "${hex}")`);
+    }
+    return xdr.ScVal.scvBytes(buf);
+};
+/**
+ * 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 const option = (value, encode)=>value === undefined || value === null ? voidVal() : encode(value);
+/**
+ * Encode a single Soroban tuple `(Address, i128)` as a 2-element `scvVec`.
+ */ export const tupleAddrAmount = (token, amount)=>xdr.ScVal.scvVec([
+        addr(token),
+        i128(amount)
+    ]);
+/**
+ * Encode `Vec<(Address, i128)>` — a Soroban tuple-vec of (asset, amount).
+ * Each tuple is a 2-element `scvVec`.
+ */ export const tupleAddrAmountVec = (entries)=>xdr.ScVal.scvVec(entries.map((e)=>tupleAddrAmount(e.token, e.amount)));
+/**
+ * Encode a `HubAssetKey` `#[contracttype]` struct — the `(hub_id, asset)`
+ * coordinate that keys liquidity and positions on the multi-hub controller.
+ * Emitted as an ScVal map with symbol keys in lexicographic order
+ * (`asset`, then `hub_id`).
+ */ export const hubAsset = (hubId, asset)=>scStruct({
+        asset: addr(asset),
+        hub_id: u32(hubId)
+    });
+/**
+ * Encode a single Soroban tuple `(HubAssetKey, i128)` as a 2-element `scvVec`.
+ */ export const tupleHubAssetAmount = (hubId, asset, amount)=>xdr.ScVal.scvVec([
+        hubAsset(hubId, asset),
+        i128(amount)
+    ]);
+/**
+ * Encode `Vec<(HubAssetKey, i128)>` — the multi-hub batch payload carried by
+ * `supply` / `borrow` / `withdraw` / `repay` / `liquidate`.
+ */ export const tupleHubAssetAmountVec = (entries)=>xdr.ScVal.scvVec(entries.map((e)=>tupleHubAssetAmount(e.hubId, e.asset, e.amount)));
+/**
+ * Encode `SeizeMode`. Soroban serializes a `#[contracttype]` enum as
+ * `scvVec([scvSymbol(Variant), ...payload])` — the void variant carries only
+ * the symbol, `Credit` appends its `u64`. Same shape as `OracleReadMode`
+ * (`Spot` / `Twap(u32)`) in `admin.ts`.
+ */ export const seizeMode = (mode)=>{
+    if (mode === 'Transfer') return vec([
+        sym('Transfer')
+    ]);
+    if (mode && typeof mode === 'object' && 'Credit' in mode) {
+        const id = mode.Credit;
+        // `0` is the "open a fresh account" sentinel, so only reject genuinely
+        // unrepresentable ids here; `u64()` rejects negatives and overflow.
+        if (typeof id === 'number' && !Number.isInteger(id)) {
+            throw new Error(`Stellar builder: SeizeMode Credit account id must be an integer u64, got ${id}`);
+        }
+        return vec([
+            sym('Credit'),
+            u64(id)
+        ]);
+    }
+    throw new Error(`Stellar builder: SeizeMode must be 'Transfer' or { Credit: accountId }, got ${JSON.stringify(mode)}`);
+};
+/**
+ * Encode a Soroban `struct` — at the XDR level, structs are maps with
+ * `Symbol` keys in **lexicographic order** of field names.
+ */ export const scStruct = (fields)=>{
+    const entries = Object.keys(fields).sort().map((k)=>new xdr.ScMapEntry({
+            key: sym(k),
+            val: fields[k]
+        }));
+    return xdr.ScVal.scvMap(entries);
+};
+/**
+ * Lowers a strategy plan into the router's two registries plus the packed
+ * instruction stream.
+ *
+ * Mirrors `contracts/swap-aggregator/src/program.rs` and the Rust builder in
+ * `arb-algo`. Instructions reference addresses and amounts by `u8` index, so an
+ * address several hops share costs 40 bytes once rather than once per hop.
+ */ class ProgramLowering {
+    /** Index of `address` in the registry, appending it if new. */ asset(address) {
+        const found = this.assets.indexOf(address);
+        if (found !== -1) return found;
+        if (this.assets.length >= MAX_ASSETS) {
+            throw new Error('Stellar builder: strategy references more than 256 distinct addresses');
+        }
+        this.assets.push(address);
+        return this.assets.length - 1;
+    }
+    /** Index of a newly appended amount. */ amount(value) {
+        if (this.amounts.length >= MAX_AMOUNTS) {
+            throw new Error('Stellar builder: strategy references too many distinct amounts');
+        }
+        this.amounts.push(value);
+        return this.amounts.length - 1;
+    }
+    /** Index of a newly appended split weight. */ weight(ppm) {
+        if (this.weights.length >= MAX_WEIGHTS) {
+            throw new Error('Stellar builder: strategy uses more than 32 split weights');
+        }
+        if (!Number.isInteger(ppm) || ppm <= 0 || ppm > PPM_DENOMINATOR) {
+            throw new Error(`Stellar builder: split weight ${ppm} outside 1..=${PPM_DENOMINATOR}`);
+        }
+        this.weights.push(ppm);
+        return this.weights.length - 1;
+    }
+    emit(opcode, mode, a, b, c) {
+        this.ops.push([
+            opcode,
+            mode,
+            a,
+            b,
+            c
+        ]);
+    }
+    /** Emit one path: the head instruction sizes the input, the rest chain. */ emitPath(path, headMode) {
+        path.hops.forEach((hop, n)=>{
+            if (hop.tokenIn === hop.tokenOut) {
+                throw new Error('Stellar builder: hop swaps a token for itself');
+            }
+            const previous = path.hops[n - 1];
+            if (previous && hop.tokenIn !== previous.tokenOut) {
+                throw new Error("Stellar builder: hop does not chain onto its predecessor's output");
+            }
+            this.emit(STELLAR_SWAP_VENUE_OPCODE[hop.venue], n === 0 ? headMode : MODE_PREV, this.asset(hop.pool), this.asset(hop.tokenIn), this.asset(hop.tokenOut));
+        });
+    }
+    /**
+   * Lower paths one starting-token group at a time.
+   *
+   * The contract measures a ppm instruction against the vault balance *at that
+   * moment*, so absolute weights are rewritten as successive shares of the
+   * shrinking remainder. A group that routes its whole balance ends on `All`,
+   * which absorbs ppm rounding exactly.
+   */ lowerPaths(paths) {
+        const live = paths.filter((p)=>p.hops.length > 0);
+        const done = Array.from({
+            length: live.length
+        }, ()=>false);
+        for(let i = 0; i < live.length; i += 1){
+            if (done[i]) continue;
+            const groupToken = live[i].hops[0]?.tokenIn;
+            const members = [];
+            for(let j = i; j < live.length; j += 1){
+                if (live[j].hops[0]?.tokenIn === groupToken) {
+                    members.push(j);
+                }
+            }
+            const total = members.reduce((sum, j)=>sum + live[j].splitPpm, 0);
+            if (total > PPM_DENOMINATOR) {
+                throw new Error(`Stellar builder: split weights for one token sum to ${total}, above ${PPM_DENOMINATOR}`);
+            }
+            const sweeps = total === PPM_DENOMINATOR;
+            let remaining = PPM_DENOMINATOR;
+            members.forEach((j, n)=>{
+                done[j] = true;
+                const path = live[j];
+                let mode;
+                if (n + 1 === members.length && sweeps) {
+                    mode = MODE_ALL;
+                } else {
+                    if (remaining === 0) {
+                        throw new Error('Stellar builder: split weights exhaust the group before its last path');
+                    }
+                    const relative = Math.floor(path.splitPpm * PPM_DENOMINATOR / remaining);
+                    remaining -= Math.min(path.splitPpm, remaining);
+                    mode = MODE_PPM_BASE + this.weight(relative);
+                }
+                this.emitPath(path, mode);
+            });
+        }
+    }
+    /** Serialize header, instructions, and weights. */ toBytes(tokenIn, tokenOut, referralId) {
+        if (this.ops.length === 0) {
+            throw new Error('Stellar builder: strategy lowered to zero instructions');
+        }
+        if (this.ops.length > MAX_OPS) {
+            throw new Error(`Stellar builder: strategy has ${this.ops.length} instructions, the router accepts ${MAX_OPS}`);
+        }
+        const out = [
+            STELLAR_PROGRAM_VERSION,
+            tokenIn,
+            tokenOut,
+            0,
+            referralId >>> 24 & 0xff,
+            referralId >>> 16 & 0xff,
+            referralId >>> 8 & 0xff,
+            referralId & 0xff,
+            this.ops.length,
+            this.weights.length
+        ];
+        for (const op of this.ops)out.push(...op);
+        for (const ppm of this.weights){
+            out.push(ppm >>> 16 & 0xff, ppm >>> 8 & 0xff, ppm & 0xff);
+        }
+        return Buffer.from(out);
+    }
+    get assetList() {
+        return this.assets;
+    }
+    get amountList() {
+        return this.amounts;
+    }
+    constructor(totalMinOut){
+        _define_property(this, "assets", []);
+        _define_property(this, "amounts", []);
+        _define_property(this, "ops", []);
+        _define_property(this, "weights", []);
+        // Slot 0 is the strategy-wide minimum output.
+        this.amounts.push(totalMinOut);
+    }
+}
+/**
+ * Encode the aggregator router's `StrategyPayload`. The caller usually receives
+ * this already encoded as quote `routeXdr`; this helper is for tests and for
+ * callers that construct routes locally.
+ */ export const encodeStrategyPayload = (payload)=>{
+    const low = new ProgramLowering(payload.totalMinOut);
+    const tokenIn = low.asset(payload.tokenIn);
+    const tokenOut = low.asset(payload.tokenOut);
+    if (tokenIn === tokenOut) {
+        throw new Error('Stellar builder: `tokenIn` and `tokenOut` are the same asset');
+    }
+    if (payload.burnPool) {
+        const pool = low.asset(payload.burnPool);
+        const start = low.amountList.length;
+        for (const min of payload.burnMinAmounts ?? [])low.amount(min);
+        // A burn consumes the whole LP balance, which is `tokenIn`.
+        low.emit(OP_BURN, MODE_ALL, pool, tokenIn, start);
+    }
+    low.lowerPaths(payload.paths);
+    if (payload.mintPool) {
+        const preSwap = payload.preSwapAmount;
+        if (preSwap && BigInt(preSwap) > 0n) {
+            const tokens = payload.mintPoolTokens;
+            if (!tokens || tokens.length !== 2) {
+                throw new Error('Stellar builder: `preSwapAmount` needs `mintPoolTokens` to name the pool’s two constituents');
+            }
+            const [tokenA, tokenB] = tokens;
+            const [from, to] = payload.preSwapFromA ? [
+                tokenA,
+                tokenB
+            ] : [
+                tokenB,
+                tokenA
+            ];
+            low.emit(STELLAR_SWAP_VENUE_OPCODE.Aquarius, MODE_FIXED_BASE + low.amount(preSwap), low.asset(payload.mintPool), low.asset(from), low.asset(to));
+        }
+        // The mint credits `tokenOut`, the pool's share token.
+        low.emit(OP_MINT, MODE_ALL, low.asset(payload.mintPool), tokenOut, low.amount(payload.mintMinShares ?? '1'));
+    }
+    const referralId = Number(payload.referralId ?? 0);
+    if (!Number.isInteger(referralId) || referralId < 0 || referralId > 0xffffffff) {
+        throw new Error(`Stellar builder: referral id ${payload.referralId} does not fit the wire’s u32`);
+    }
+    return scStruct({
+        amounts: xdr.ScVal.scvVec(low.amountList.map((a)=>i128(a))),
+        assets: xdr.ScVal.scvVec(low.assetList.map((a)=>addr(a))),
+        ops: xdr.ScVal.scvBytes(low.toBytes(tokenIn, tokenOut, referralId))
+    });
+};
+export const encodeStrategyPayloadToBytes = (payload)=>xdr.ScVal.scvBytes(Buffer.from(encodeStrategyPayload(payload).toXDR('base64'), 'base64'));
+/**
+ * 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 const asStellarStrategyPayload = (steps)=>{
+    if (!steps || typeof steps !== 'object') {
+        throw new Error('Stellar builder: decoded strategy `steps` must be a StrategyPayload ({ paths, tokenIn, tokenOut, totalMinOut })');
+    }
+    const candidate = steps;
+    if (!Array.isArray(candidate.paths) || candidate.paths.length === 0 && !candidate.burnPool && !candidate.mintPool) {
+        throw new Error('Stellar builder: `steps.paths` needs a strategy path or a liquidity burn/mint operation');
+    }
+    if (typeof candidate.tokenIn !== 'string') {
+        throw new Error('Stellar builder: `steps.tokenIn` must be a contract address');
+    }
+    if (typeof candidate.tokenOut !== 'string') {
+        throw new Error('Stellar builder: `steps.tokenOut` must be a contract address');
+    }
+    if (typeof candidate.totalMinOut !== 'string') {
+        throw new Error('Stellar builder: `steps.totalMinOut` must be an i128 decimal string');
+    }
+    // Weights are grouped by the token a path starts from: parallel legs out of
+    // the same token share one budget, and a burn releases several tokens that
+    // each get their own.
+    const groupPpm = new Map();
+    for (const [idx, path] of candidate.paths.entries()){
+        if (!path || typeof path.splitPpm !== 'number' || path.splitPpm <= 0 || !Array.isArray(path.hops) || path.hops.length === 0) {
+            throw new Error(`Stellar builder: \`steps.paths[${idx}]\` must have splitPpm > 0 and a non-empty hops array`);
+        }
+        for (const [hopIdx, hop] of path.hops.entries()){
+            if (!hop || typeof hop.pool !== 'string' || typeof hop.tokenIn !== 'string' || typeof hop.tokenOut !== 'string' || !STELLAR_SWAP_VENUES.includes(hop.venue)) {
+                throw new Error(`Stellar builder: \`steps.paths[${idx}].hops[${hopIdx}]\` must have pool, tokenIn, tokenOut, and a valid Soroban venue`);
+            }
+        }
+        const head = path.hops[0];
+        groupPpm.set(head.tokenIn, (groupPpm.get(head.tokenIn) ?? 0) + path.splitPpm);
+    }
+    for (const [token, sum] of groupPpm){
+        if (sum > PPM_DENOMINATOR) {
+            throw new Error(`Stellar builder: \`steps.paths[].splitPpm\` for ${token} sums to ${sum}, above ${PPM_DENOMINATOR}`);
+        }
+        // Without a mint leg every routed token must be fully consumed, or the
+        // router's residual guard rejects the strategy on-chain.
+        if (!candidate.mintPool && sum !== PPM_DENOMINATOR) {
+            throw new Error(`Stellar builder: \`steps.paths[].splitPpm\` for ${token} must sum to ${PPM_DENOMINATOR}, got ${sum}`);
+        }
+    }
+    return candidate;
+};
+const isHexString = (s)=>s.length > 0 && s.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(s);
+const strategyBytes = (data)=>{
+    const buf = Buffer.from(data);
+    if (buf.length === 0) {
+        throw new Error('Stellar builder: strategy swap bytes must be non-empty base64 routeXdr, 0x hex string, or Uint8Array');
+    }
+    return xdr.ScVal.scvBytes(buf);
+};
+/**
+ * Genuinely empty strategy swap bytes. Required by `repay_debt_with_collateral`
+ * and `swap_debt` when the collateral/borrowed asset is identical to the debt
+ * asset — the controller asserts `swap.is_empty()` in that case and reverts
+ * `InvalidPayments` if any route is supplied, even an unused placeholder.
+ */ export const emptyStrategySwapBytes = ()=>xdr.ScVal.scvBytes(Buffer.alloc(0));
+const decodeStrategyBytesString = (encoded)=>{
+    const trimmed = encoded.trim();
+    if (trimmed.startsWith('0x')) {
+        const hex = trimmed.slice(2);
+        if (!isHexString(hex)) {
+            throw new Error('Stellar builder: strategy swap bytes hex string must be 0x-prefixed and even-length');
+        }
+        return Buffer.from(hex, 'hex');
+    }
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(trimmed)) {
+        throw new Error('Stellar builder: strategy swap bytes must be base64 routeXdr or 0x-prefixed hex');
+    }
+    const decoded = Buffer.from(trimmed, 'base64');
+    if (decoded.length === 0) {
+        throw new Error('Stellar builder: strategy swap bytes must be non-empty base64 routeXdr, 0x hex string, or Uint8Array');
+    }
+    return decoded;
+};
+const hasRouteXdr = (input)=>'routeXdr' in input && typeof input.routeXdr === 'string';
+const hasSwapXdr = (input)=>'swapXdr' in input && typeof input.swapXdr === 'string';
+const hasBytes = (input)=>'bytes' in input && (typeof input.bytes === 'string' || input.bytes instanceof Uint8Array);
+/**
+ * Encode opaque strategy bytes for the lending controller. Accepted inputs:
+ *   - quote `routeXdr` base64 string
+ *   - `{ routeXdr }` / `{ swapXdr }`
+ *   - raw `Uint8Array` / `{ bytes }`
+ *   - decoded `StrategyPayload` object
+ */ export const asStellarStrategySwapBytes = (steps)=>{
+    if (typeof steps === 'string') {
+        return strategyBytes(decodeStrategyBytesString(steps));
+    }
+    if (steps instanceof Uint8Array) {
+        return steps.length === 0 ? emptyStrategySwapBytes() : strategyBytes(steps);
+    }
+    if (steps && typeof steps === 'object') {
+        if (hasRouteXdr(steps)) {
+            return strategyBytes(decodeStrategyBytesString(steps.routeXdr));
+        }
+        if (hasSwapXdr(steps)) {
+            return strategyBytes(decodeStrategyBytesString(steps.swapXdr));
+        }
+        if (hasBytes(steps)) {
+            if (typeof steps.bytes === 'string') {
+                return strategyBytes(decodeStrategyBytesString(steps.bytes));
+            }
+            return steps.bytes.length === 0 ? emptyStrategySwapBytes() : strategyBytes(steps.bytes);
+        }
+        return encodeStrategyPayloadToBytes(asStellarStrategyPayload(steps));
+    }
+    throw new Error('Stellar builder: `steps` must be opaque strategy bytes (`routeXdr`, base64/hex string, or Uint8Array)');
+};
+/**
+ * Validate the untyped `data` field on FlashLoanArgs and narrow it to
+ * Buffer / hex string for Soroban `Bytes` encoding.
+ */ export const asStellarBytes = (data)=>{
+    if (typeof data === 'string') return bytes(data);
+    if (data instanceof Uint8Array) return xdr.ScVal.scvBytes(Buffer.from(data));
+    throw new Error('Stellar builder: `data` must be a hex string or Uint8Array (Soroban Bytes payload)');
+};

package/dist/esm/sdk/stellar/swap-history.js

@@ -0,0 +1,46 @@
+import { Address, scValToBigInt, StrKey, TransactionBuilder } from "@stellar/stellar-sdk";
+import { decodeStellarRouteBytes } from "./route-verify.js";
+import { xdrBytes, xdrField, xdrType } from "./xdr-compat.js";
+/**
+ * Synchronously decode direct XOXNO router swaps, including fee-bump envelopes.
+ * Returns null for malformed, unrelated or ambiguous envelopes. Without an
+ * operation index exactly one matching swap is required. No RPC or output
+ * amount inference: the route minimum is not the amount actually received.
+ * The network passphrase parses the envelope; it cannot prove its network.
+ */ export function decodeStellarSwapEnvelope(options) {
+    try {
+        const { envelopeXdr, networkPassphrase, routerAddress, viewer, operationIndex } = options;
+        if (!networkPassphrase || !StrKey.isValidContract(routerAddress) || new Address(viewer).toString() !== viewer || typeof envelopeXdr !== 'string' || envelopeXdr.length > 1024 * 1024 || envelopeXdr.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(envelopeXdr) || operationIndex !== undefined && (!Number.isSafeInteger(operationIndex) || operationIndex < 0)) return null;
+        const parsed = TransactionBuilder.fromXDR(envelopeXdr, networkPassphrase);
+        const tx = 'innerTransaction' in parsed ? parsed.innerTransaction : parsed;
+        if (operationIndex !== undefined && operationIndex >= tx.operations.length) return null;
+        let found = null;
+        for (const [index, operation] of tx.operations.entries()){
+            if (operationIndex !== undefined && index !== operationIndex) continue;
+            if (operation.type !== 'invokeHostFunction') continue;
+            const host = operation.func;
+            if (xdrType(host) !== 'hostFunctionTypeInvokeContract') continue;
+            const call = xdrField(host, 'invokeContract');
+            if (Address.fromScAddress(xdrField(call, 'contractAddress')).toString() !== routerAddress || xdrField(call, 'functionName').toString() !== 'execute_strategy') continue;
+            const args = xdrField(call, 'args');
+            const [sender, amount, routeBytes] = args;
+            if (args.length !== 3 || !sender || !amount || !routeBytes || xdrType(sender) !== 'scvAddress' || xdrType(amount) !== 'scvI128' || xdrType(routeBytes) !== 'scvBytes') return null;
+            if (Address.fromScAddress(xdrField(sender, 'address')).toString() !== viewer) continue;
+            // Read i128 with the SDK's own conversion, preserving values above 2^53.
+            const amountIn = scValToBigInt(amount);
+            if (amountIn <= 0n) return null;
+            const route = decodeStellarRouteBytes(xdrBytes(routeBytes));
+            if (route.tokenIn === route.tokenOut || !StrKey.isValidContract(route.tokenIn) || !StrKey.isValidContract(route.tokenOut)) return null;
+            if (found) return null;
+            found = {
+                tokenIn: route.tokenIn,
+                tokenOut: route.tokenOut,
+                amountInAtoms: amountIn.toString(),
+                operationIndex: index
+            };
+        }
+        return found;
+    } catch  {
+        return null;
+    }
+}

package/dist/esm/sdk/stellar/swap-index.js

@@ -0,0 +1 @@
+export { decodeStellarSwapEnvelope } from "./swap-history.js";

package/dist/esm/sdk/stellar/swap.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { Account, BASE_FEE, Contract, TransactionBuilder } from "@stellar/stellar-sdk";
+import { STELLAR_NETWORK_PASSPHRASE } from "./contracts.js";
+import { StellarRouteVerificationError, stellarTokenContractId, verifyStellarRouteBytes } from "./route-verify.js";
+import { addr, asStellarStrategySwapBytes, encodeStrategyPayload, i128 } from "./scval-encode.js";
+const hasPayloadPaths = (swap)=>Boolean(swap && typeof swap === 'object' && !(swap instanceof Uint8Array) && 'paths' in swap);
+const withDefaultReferral = (swap, referralId)=>{
+    if (!hasPayloadPaths(swap) || swap.referralId !== undefined) return swap;
+    return {
+        ...swap,
+        referralId: referralId ?? 0
+    };
+};
+export const encodeStrategyPayloadToRouteXdr = (payload)=>encodeStrategyPayload(payload).toXDR('base64');
+/**
+ * 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 function buildStellarExecuteStrategyTx(opts, swap) {
+    if (!opts.routerAddress) {
+        throw new Error('Stellar aggregator routerAddress is required');
+    }
+    const contract = new Contract(opts.routerAddress);
+    const source = new Account(opts.caller, opts.sourceSequence);
+    const swapBytes = asStellarStrategySwapBytes(withDefaultReferral(swap, opts.referralId));
+    const tx = new TransactionBuilder(source, {
+        fee: opts.fee ?? BASE_FEE,
+        networkPassphrase: STELLAR_NETWORK_PASSPHRASE[opts.network]
+    }).addOperation(contract.call('execute_strategy', addr(opts.caller), i128(opts.totalIn), swapBytes)).setTimeout(opts.timeoutSeconds ?? 300).build();
+    return {
+        xdr: tx.toXDR()
+    };
+}
+/**
+ * Translate a quote-server response into the decoded `StrategyPayload` shape.
+ * Prefer `mapQuoteResponseToStrategySwap` when the quote includes `routeXdr`.
+ */ export function mapQuoteResponseToStrategyPayload(quote, opts = {}) {
+    if (typeof quote.amountOutMin !== 'string') {
+        throw new Error('mapQuoteResponseToStrategyPayload: quote response is missing `amountOutMin`. Pass `slippage` when fetching the quote.');
+    }
+    const paths = quote.paths ? quote.paths.map((path)=>({
+            hops: path.swaps.map(mapHop),
+            splitPpm: path.splitPpm
+        })) : [
+        {
+            hops: quote.hops.map(mapHop),
+            splitPpm: 1000000
+        }
+    ];
+    return {
+        paths,
+        referralId: opts.referralId ?? 0,
+        tokenIn: quote.from,
+        tokenOut: quote.to,
+        totalMinOut: quote.amountOutMin
+    };
+}
+/**
+ * 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 function mapQuoteResponseToStrategySwap(quote, opts = {}) {
+    const expected = opts.expected ?? {};
+    // Built locally from the JSON when the server sent no route, so the encoded
+    // minimum IS `amountOutMin`; the same check then covers both forms.
+    const swap = typeof quote.routeXdr === 'string' && quote.routeXdr.length > 0 ? {
+        routeXdr: quote.routeXdr
+    } : mapQuoteResponseToStrategyPayload(quote, opts);
+    // The route is an opaque blob beside the JSON display fields. The router
+    // enforces only the minimum inside the blob, so it must not be below what
+    // the JSON (and therefore the UI) shows, nor below the caller's own floor.
+    const floors = [
+        quote.amountOutMin,
+        expected.minOut
+    ].filter((v)=>v !== undefined).map((v)=>{
+        if (typeof v === 'bigint') return v;
+        if (typeof v !== 'string' || !/^\d+$/.test(v)) {
+            throw new StellarRouteVerificationError('MALFORMED', 'minimum output must be a base-unit integer string');
+        }
+        return BigInt(v);
+    });
+    const minOut = floors.reduce((max, v)=>max === undefined || v > max ? v : max, undefined);
+    if (minOut === undefined) {
+        throw new StellarRouteVerificationError('EXPECTATION_MISSING', 'quote has no `amountOutMin`; pass `slippage` when fetching it or `expected.minOut`');
+    }
+    // The caller's pair is authoritative; the JSON pair only labels the response.
+    verifyStellarRouteBytes(swap, {
+        tokenIn: stellarTokenContractId(expected.tokenIn ?? quote.from, opts.network),
+        tokenOut: stellarTokenContractId(expected.tokenOut ?? quote.to, opts.network),
+        minOut,
+        amountIn: expected.amountIn ?? quote.amountIn
+    });
+    return swap;
+}
+const mapHop = (hop)=>({
+        amountOut: hop.amountOut,
+        pool: hop.address,
+        tokenIn: hop.from,
+        tokenOut: hop.to,
+        venue: hop.dex
+    });

package/dist/esm/sdk/stellar/xdr-compat.js

@@ -0,0 +1,17 @@
+import { Buffer } from "buffer";
+/** SDK 16 exposes XDR getters; SDK 17 exposes the same fields as properties. */ export function xdrField(value, key) {
+    const field = value[key];
+    return typeof field === 'function' ? field.call(value) : field;
+}
+export function xdrType(value) {
+    if (!value || typeof value !== 'object') return undefined;
+    const union = value;
+    return typeof union.switch === 'function' ? union.switch().name : union.type;
+}
+/** SDK 17 opaque byte fields wrap their Uint8Array in `value`. */ export function xdrBytes(value) {
+    return xdrOpaque(xdrField(value, 'bytes'));
+}
+export function xdrOpaque(value) {
+    const bytes = value;
+    return Buffer.from('value' in bytes ? bytes.value : bytes);
+}