@xoxno/sdk-js 1.0.224 → 1.0.226

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

@@ -0,0 +1,47 @@
+import { TransactionBuilder, rpc } from "@stellar/stellar-sdk";
+import { STELLAR_NETWORK_PASSPHRASE } from "./contracts.js";
+export function tagStellarInvokedContractError(contractId, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`[xoxno-invoked:${contractId}] ${message}`);
+}
+/**
+ * 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.
+ * @param server - Host application's RPC server on the selected network.
+ * @param xdr - Unsigned builder output, not a signed transaction.
+ * @param opts - Pass `network` explicitly; it must match the RPC and wallet.
+ * @returns Prepared, unsigned base64 XDR for wallet signing.
+ * @remarks This helper does not sign, submit, or wait for confirmation. Existing
+ * calls without `network` retain a neutral hash domain because XDR contains no
+ * passphrase; always select the actual network when the wallet signs.
+ * @category Transaction preparation
+ */ export async function prepareStellarTxXdr(server, xdr, opts) {
+    const instructionLeeway = opts?.instructionLeeway ?? 20000000;
+    if (!Number.isInteger(instructionLeeway) || instructionLeeway < 0 || instructionLeeway > 0xffffffff) {
+        throw new Error('instructionLeeway must be an integer from 0 to 4294967295');
+    }
+    const tx = TransactionBuilder.fromXDR(xdr, opts?.network ? STELLAR_NETWORK_PASSPHRASE[opts.network] : '');
+    try {
+        const simulation = await server.simulateTransaction(tx, {
+            cpuInstructions: instructionLeeway
+        });
+        if (rpc.Api.isSimulationError(simulation)) throw new Error(simulation.error);
+        return rpc.assembleTransaction(tx, simulation).build().toXDR();
+    } catch (error) {
+        if (opts?.invokedContractId) {
+            throw tagStellarInvokedContractError(opts.invokedContractId, error);
+        }
+        throw error;
+    }
+}
+/**
+ * Prepare {@link BuiltStellarTx} before wallet signing.
+ * @param server - Host RPC server for the selected deployment.
+ * @param built - Unsigned output of any Stellar transaction builder.
+ * @param opts - Network and optional contract context for error mapping.
+ * @returns Prepared unsigned base64 XDR; sign this result, then submit it.
+ * @category Transaction preparation
+ */ export async function prepareStellarBuiltTx(server, built, opts) {
+    return prepareStellarTxXdr(server, built.xdr, opts);
+}

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

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */ const buildUrl = (base, path, query)=>{
+    const url = new URL(path, base.endsWith('/') ? base : `${base}/`);
+    if (query) {
+        for (const [key, value] of Object.entries(query)){
+            if (value === undefined) continue;
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+};
+/**
+ * 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.
+ *
+ * For lending strategies, pass the quote's `routeXdr` to the builder's
+ * `steps`. Amounts are token base-unit decimal strings. Requote after changes
+ * to amount, direction or slippage; preparation is the execution check.
+ *
+ * Passing `sender` (G...) together with `slippage` returns a direct-swap
+ * envelope under `transaction.envelopeXdr`. The router comes from the service's
+ * `/api/v1/config`; the `router` request field is ignored by the service and is
+ * no longer sent. Prepare the envelope before wallet signing unless
+ * `transaction.simulated` is true.
+ * @param request - Exactly one of amountIn or amountOut; optional referralId is forwarded unchanged.
+ * @param opts - Quote-server URL and optional fetch options supplied by the host.
+ * @returns Quote estimates and opaque route bytes; does not execute a swap.
+ * @category Strategy quotes
+ */ export async function getStellarAggregatorQuote(request, opts) {
+    if (!opts.baseUrl) {
+        throw new Error('Stellar quote baseUrl is required');
+    }
+    if (request.amountIn == null === (request.amountOut == null)) {
+        throw new Error('getStellarAggregatorQuote: exactly one of `amountIn` or `amountOut` must be provided');
+    }
+    const url = buildUrl(opts.baseUrl, 'api/v1/quote', {
+        from: request.from,
+        to: request.to,
+        amountIn: request.amountIn,
+        amountOut: request.amountOut,
+        maxHops: request.maxHops,
+        maxSplits: request.maxSplits,
+        slippage: request.slippage,
+        includePaths: request.includePaths,
+        sender: request.sender,
+        simulate: request.simulate,
+        referralId: request.referralId,
+        platform: request.platform,
+        fresh: request.fresh
+    });
+    const res = await fetch(url, opts.fetchOptions);
+    if (!res.ok) {
+        const body = await res.text().catch(()=>'');
+        throw new Error(`Stellar quote server responded ${res.status} ${res.statusText} for ${url} — ${body}`);
+    }
+    return await res.json();
+}
+/**
+ * List tokens currently indexed by the quote server. Useful to populate
+ * pickers or validate that a user-supplied token has on-chain liquidity.
+ * @category Strategy quotes
+ */ export async function getStellarQuoteTokens(opts) {
+    if (!opts.baseUrl) {
+        throw new Error('Stellar quote baseUrl is required');
+    }
+    const url = buildUrl(opts.baseUrl, 'api/v1/tokens');
+    const res = await fetch(url, opts.fetchOptions);
+    if (!res.ok) {
+        const body = await res.text().catch(()=>'');
+        throw new Error(`Stellar quote server responded ${res.status} ${res.statusText} for ${url} — ${body}`);
+    }
+    return await res.json();
+}

package/dist/esm/sdk/stellar/read/client.js

@@ -0,0 +1,82 @@
+function nextLink(header) {
+    if (!header) return undefined;
+    // Match complete link-values, including commas inside URIs and quoted parameters.
+    const link = /\s*<([^<>\s]+)>\s*((?:;\s*[\w!#$%&'*+.^`|~-]+\s*=\s*(?:"(?:[^"\\\r\n]|\\.)*"|[\w!#$%&'*+.^`|~:/-]+)\s*)*)(,|$)/gy;
+    let next;
+    let offset = 0;
+    while(offset < header.length){
+        const match = link.exec(header);
+        if (!match || match[3] && link.lastIndex === header.length) {
+            throw new Error('Invalid pagination Link header');
+        }
+        let isNext = false;
+        let hasRelation = false;
+        for (const parameter of match[2].matchAll(/;\s*([\w!#$%&'*+.^`|~-]+)\s*=\s*(?:"((?:[^"\\\r\n]|\\.)*)"|([\w!#$%&'*+.^`|~:/-]+))\s*/g)){
+            if (parameter[1].toLowerCase() !== 'rel') continue;
+            if (hasRelation) throw new Error('Duplicate pagination link relation');
+            hasRelation = true;
+            const relation = (parameter[2] ?? parameter[3]).replace(/\\(.)/g, '$1');
+            isNext = relation.toLowerCase().split(/\s+/).includes('next');
+        }
+        if (isNext) {
+            if (next !== undefined) throw new Error('Multiple next pagination links');
+            next = match[1];
+        }
+        offset = link.lastIndex;
+    }
+    return next;
+}
+export function createStellarLendingReadClient(options) {
+    const base = new URL(options.baseUrl.trim());
+    if (![
+        'https:',
+        'http:'
+    ].includes(base.protocol) || base.username || base.password || base.search || base.hash) {
+        throw new Error('baseUrl must be an HTTP API root without credentials, query or fragment');
+    }
+    base.pathname = `${base.pathname.replace(/\/+$/, '')}/`;
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!fetcher) throw new Error('A fetch implementation is required');
+    async function pages(path, signal) {
+        const endpoint = new URL(`stellar-lending/v1/${path}`, base);
+        let url = endpoint;
+        const visited = new Set();
+        const result = [];
+        while(true){
+            if (visited.has(url.href)) throw new Error('Pagination Link cycle');
+            visited.add(url.href);
+            // Reject redirects before a custom fetch could forward credentials to another host.
+            const response = await fetcher(url.href, {
+                signal,
+                redirect: 'error'
+            });
+            if (response.redirected || response.url && new URL(response.url).href !== url.href) {
+                throw new Error('Stellar lending redirects are not allowed');
+            }
+            if (!response.ok) throw new Error(`Stellar lending request failed: HTTP ${response.status}`);
+            const rows = await response.json();
+            if (!Array.isArray(rows)) throw new Error('Stellar lending response must be an array');
+            result.push(...rows);
+            const next = nextLink(response.headers.get('Link'));
+            if (!next) break;
+            const target = new URL(next, url);
+            if (target.origin !== endpoint.origin || target.pathname !== endpoint.pathname || target.username || target.password || target.hash) {
+                throw new Error('Pagination Link must stay on the same API endpoint');
+            }
+            url = target;
+        }
+        return result;
+    }
+    return {
+        assets: ({ usage, signal } = {})=>{
+            if (usage !== undefined && usage !== 'collateral' && usage !== 'borrow') {
+                throw new Error('usage must be collateral or borrow');
+            }
+            return pages(`assets${usage ? `?usage=${usage}` : ''}`, signal);
+        },
+        positions: (owner, { signal } = {})=>{
+            if (!owner.trim() || owner === '.' || owner === '..') throw new Error('owner is required');
+            return pages(`users/${encodeURIComponent(owner)}/positions`, signal);
+        }
+    };
+}

package/dist/esm/sdk/stellar/read/index.js

@@ -0,0 +1,3 @@
+/** Dependency-free Stellar lending REST reads and public response contracts. */ export * from "./types.js";
+export * from "./schemas.js";
+export * from "./client.js";

package/dist/esm/sdk/stellar/read/schemas.js

@@ -0,0 +1,158 @@
+// Inline OpenAPI 3 schemas shared with servers; no decorators or runtime dependencies.
+const string = {
+    type: 'string'
+};
+const number = {
+    type: 'number'
+};
+const boolean = {
+    type: 'boolean'
+};
+const nullableString = {
+    ...string,
+    nullable: true
+};
+const nullableNumber = {
+    ...number,
+    nullable: true
+};
+const network = {
+    ...string,
+    enum: [
+        'mainnet',
+        'testnet'
+    ]
+};
+const dataStatus = {
+    ...string,
+    enum: [
+        'ready',
+        'stale',
+        'incomplete'
+    ]
+};
+function object(properties) {
+    return {
+        type: 'object',
+        required: Object.keys(properties),
+        properties
+    };
+}
+const token = {
+    sac: string,
+    symbol: string,
+    name: string,
+    decimals: nullableNumber,
+    logoUrl: nullableString
+};
+const priceStatus = object({
+    valid: boolean,
+    stale: boolean,
+    deviation: boolean,
+    timestamp: nullableNumber
+});
+const positionAsset = object({
+    ...token,
+    hubId: number,
+    hubName: string,
+    amountRaw: {
+        ...nullableString,
+        description: 'Integer token base units, never scaled shares.'
+    },
+    amount: nullableString,
+    apy: {
+        ...nullableNumber,
+        description: 'Fraction: 0.05 means 5%.'
+    },
+    priceUsd: nullableNumber,
+    valueUsd: nullableNumber,
+    priceStatus,
+    indexRay: nullableString,
+    indexedAt: number,
+    indexedLedger: number
+});
+const capacity = object({
+    amountRaw: nullableString,
+    amount: nullableString,
+    usd: nullableNumber
+});
+const spoke = object({
+    spokeId: number,
+    spokeName: string,
+    ltvBps: number,
+    supplyCapacity: capacity,
+    borrowCapacity: capacity,
+    canSupply: boolean,
+    canBeCollateral: boolean,
+    canBorrow: boolean,
+    canOpenAccount: {
+        ...boolean,
+        description: 'Spoke admits new accounts; other entry gates still apply.'
+    }
+});
+/** OpenAPI response schema for LendingPosition[]. Every property is required; nullable data remains explicit. */ export const lendingPositionsSchema = {
+    type: 'array',
+    items: object({
+        accountId: string,
+        nftContract: string,
+        network,
+        spokeId: nullableNumber,
+        spokeName: nullableString,
+        supplied: {
+            type: 'array',
+            items: positionAsset
+        },
+        borrow: {
+            type: 'array',
+            items: positionAsset
+        },
+        hasDebt: {
+            ...boolean,
+            nullable: true,
+            description: 'Null when account rows are unavailable.'
+        },
+        healthFactor: {
+            ...nullableNumber,
+            description: 'Null without debt or when risk inputs are unavailable.'
+        },
+        borrowLimitUsd: nullableNumber,
+        availableBorrowUsd: {
+            ...nullableNumber,
+            description: 'Account headroom, before per-market constraints.'
+        },
+        netApy: {
+            ...nullableNumber,
+            description: 'Net annual yield divided by positive net equity; fraction.'
+        },
+        dataStatus
+    })
+};
+/** OpenAPI response schema for LendingAsset[]. Capacities are indexed estimates. */ export const lendingAssetsSchema = {
+    type: 'array',
+    items: object({
+        ...token,
+        hubId: number,
+        hubName: string,
+        network,
+        supplyApy: {
+            ...nullableNumber,
+            description: 'Fraction: 0.05 means 5%.'
+        },
+        borrowApy: {
+            ...nullableNumber,
+            description: 'Fraction: 0.05 means 5%.'
+        },
+        priceUsd: nullableNumber,
+        priceStatus,
+        spokes: {
+            type: 'array',
+            items: spoke
+        },
+        dataStatus,
+        indexedAt: {
+            ...number,
+            description: 'Pool state timestamp. Capacities are indexed snapshot estimates; prepare/simulate before signing.'
+        },
+        indexedLedger: number
+    })
+};

package/dist/esm/sdk/stellar/read/types.js

@@ -0,0 +1 @@
+/** Render-ready REST data. Null means unavailable, never an inferred zero. */ export { };

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

@@ -0,0 +1,12 @@
+/**
+ * Empty strategy swap bytes for `repay_debt_with_collateral` when
+ * `collateral_token === debt_token`. The controller requires the swap payload
+ * to be genuinely empty in this case (`swap.is_empty()`) and reverts
+ * `InvalidPayments` if any route is supplied, even an unused placeholder.
+ *
+ * `token`/`collateralAmount` are accepted-but-ignored so existing callers of
+ * the old `(token, collateralAmount)` signature keep compiling; the swap
+ * payload is always empty regardless of their values.
+ */ export function buildSameTokenRepaySwapSteps(_token, _collateralAmount) {
+    return new Uint8Array(0);
+}

package/dist/esm/sdk/stellar/route-verify.js

@@ -0,0 +1,285 @@
+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;
+}
+/**
+ * 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 { Address, Asset, scValToBigInt, StrKey, xdr } from "@stellar/stellar-sdk";
+import { STELLAR_NETWORK_PASSPHRASE } from "./contracts.js";
+import { xdrBytes, xdrField, xdrType } from "./xdr-compat.js";
+import { asStellarStrategySwapBytes, MAX_AMOUNTS, MAX_ASSETS, MAX_OPS, MAX_WEIGHTS, MODE_ALL, MODE_FIXED_BASE, MODE_PPM_BASE, MODE_PREV, OP_BURN, OP_MINT, PPM_DENOMINATOR, STELLAR_PROGRAM_VERSION, STELLAR_SWAP_VENUES } from "./scval-encode.js";
+const HEADER_LEN = 10;
+const OP_LEN = 5;
+const WEIGHT_LEN = 3;
+const MAX_PROGRAM_BYTES = HEADER_LEN + OP_LEN * MAX_OPS + WEIGHT_LEN * MAX_WEIGHTS;
+/**
+ * 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 const STELLAR_ROUTE_MAX_BYTES = 16 * 1024;
+/** Thrown when a route cannot be decoded or disagrees with the caller's request. */ export class StellarRouteVerificationError extends Error {
+    constructor(code, message){
+        super(`Stellar route verification failed [${code}]: ${message}`), _define_property(this, "code", void 0);
+        this.name = 'StellarRouteVerificationError';
+        this.code = code;
+    }
+}
+const fail = (code, message)=>{
+    throw new StellarRouteVerificationError(code, message);
+};
+const toBuffer = (route)=>{
+    const encoded = typeof route === 'string' ? route : route && typeof route === 'object' && 'routeXdr' in route ? route.routeXdr : undefined;
+    // Base64 expands 3 bytes to 4 characters; reject before decoding.
+    if (typeof encoded === 'string' && encoded.length > STELLAR_ROUTE_MAX_BYTES * 2) {
+        return fail('OVERSIZED', `encoded route has ${encoded.length} characters`);
+    }
+    try {
+        return xdrBytes(asStellarStrategySwapBytes(route));
+    } catch (error) {
+        return fail('MALFORMED', error instanceof Error ? error.message : String(error));
+    }
+};
+const readPayloadFields = (buf)=>{
+    let value;
+    try {
+        // `fromXDR` rejects truncated input and trailing bytes.
+        value = xdr.ScVal.fromXDR(buf);
+    } catch (error) {
+        return fail('MALFORMED', `payload is not one XDR ScVal: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (xdrType(value) !== 'scvMap') {
+        return fail('MALFORMED', 'payload must be a StrategyPayload map');
+    }
+    const entries = xdrField(value, 'map') ?? [];
+    // A `#[contracttype]` struct is a map with exactly its fields, keys sorted.
+    const keys = entries.map((entry)=>xdrType(xdrField(entry, 'key')) === 'scvSymbol' ? xdrField(xdrField(entry, 'key'), 'sym').toString() : '');
+    if (keys.join(',') !== 'amounts,assets,ops') {
+        return fail('MALFORMED', 'payload fields must be exactly amounts, assets, ops');
+    }
+    const [amountsVal, assetsVal, opsVal] = entries.map((entry)=>xdrField(entry, 'val'));
+    if (xdrType(amountsVal) !== 'scvVec' || xdrType(assetsVal) !== 'scvVec' || xdrType(opsVal) !== 'scvBytes') {
+        return fail('MALFORMED', 'payload field has the wrong type');
+    }
+    return {
+        amounts: xdrField(amountsVal, 'vec') ?? [],
+        assets: xdrField(assetsVal, 'vec') ?? [],
+        ops: xdrBytes(opsVal)
+    };
+};
+/**
+ * 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 function decodeStellarRouteBytes(route) {
+    const buf = toBuffer(route);
+    if (buf.length === 0) fail('MALFORMED', 'route is empty');
+    if (buf.length > STELLAR_ROUTE_MAX_BYTES) {
+        fail('OVERSIZED', `route has ${buf.length} bytes, above ${STELLAR_ROUTE_MAX_BYTES}`);
+    }
+    const fields = readPayloadFields(buf);
+    const assetsLen = fields.assets.length;
+    const amountsLen = fields.amounts.length;
+    if (assetsLen === 0) fail('MALFORMED', 'asset registry is empty');
+    if (assetsLen > MAX_ASSETS || amountsLen > MAX_AMOUNTS) {
+        fail('OVERSIZED', `registries hold ${assetsLen} assets and ${amountsLen} amounts`);
+    }
+    const assets = fields.assets.map((value, i)=>{
+        if (xdrType(value) !== 'scvAddress') {
+            return fail('MALFORMED', `assets[${i}] is not an address`);
+        }
+        return Address.fromScAddress(xdrField(value, 'address')).toString();
+    });
+    const amounts = fields.amounts.map((value, i)=>{
+        if (xdrType(value) !== 'scvI128') {
+            return fail('MALFORMED', `amounts[${i}] is not an i128`);
+        }
+        return scValToBigInt(value);
+    });
+    const ops = fields.ops;
+    if (ops.length < HEADER_LEN) fail('MALFORMED', 'program header is truncated');
+    if (ops.length > MAX_PROGRAM_BYTES) {
+        fail('OVERSIZED', `program has ${ops.length} bytes, above ${MAX_PROGRAM_BYTES}`);
+    }
+    const byte = (at)=>{
+        const value = ops[at];
+        return value === undefined ? fail('MALFORMED', `program byte ${at} is missing`) : value;
+    };
+    const version = byte(0);
+    if (version !== STELLAR_PROGRAM_VERSION) {
+        fail('UNSUPPORTED_VERSION', `program version ${version}, expected ${STELLAR_PROGRAM_VERSION}`);
+    }
+    const opCount = byte(8);
+    const weightCount = byte(9);
+    if (opCount === 0) fail('INVALID_STRUCTURE', 'program has no instructions');
+    if (opCount > MAX_OPS || weightCount > MAX_WEIGHTS) {
+        fail('OVERSIZED', `program declares ${opCount} instructions and ${weightCount} weights`);
+    }
+    const weightsAt = HEADER_LEN + OP_LEN * opCount;
+    if (ops.length !== weightsAt + WEIGHT_LEN * weightCount) {
+        fail('MALFORMED', 'program length does not match its instruction and weight counts');
+    }
+    const tokenInIdx = byte(1);
+    const tokenOutIdx = byte(2);
+    const minOutIdx = byte(3);
+    if (tokenInIdx >= assetsLen || tokenOutIdx >= assetsLen || minOutIdx >= amountsLen) {
+        fail('MALFORMED', 'header index is outside its registry');
+    }
+    if (tokenInIdx === tokenOutIdx) fail('INVALID_STRUCTURE', 'token_in equals token_out');
+    const referralId = ops.readUInt32BE(4);
+    const weights = [];
+    for(let i = 0; i < weightCount; i += 1){
+        const ppm = ops.readUIntBE(weightsAt + WEIGHT_LEN * i, WEIGHT_LEN);
+        if (ppm === 0 || ppm > PPM_DENOMINATOR) {
+            fail('INVALID_STRUCTURE', `split weight ${ppm} outside 1..=${PPM_DENOMINATOR}`);
+        }
+        weights.push(ppm);
+    }
+    const asset = (idx)=>assets[idx] ?? fail('MALFORMED', `asset index ${idx} is outside the registry`);
+    const amount = (idx)=>amounts[idx] ?? fail('MALFORMED', `amount index ${idx} is outside the registry`);
+    const decoded = [];
+    // Registry index of the previous instruction's single output; a burn has none.
+    let producedIdx;
+    for(let i = 0; i < opCount; i += 1){
+        const at = HEADER_LEN + OP_LEN * i;
+        const opcode = byte(at);
+        const modeByte = byte(at + 1);
+        const idxA = byte(at + 2);
+        const idxB = byte(at + 3);
+        const idxC = byte(at + 4);
+        if (opcode > OP_MINT) fail('UNKNOWN_OPCODE', `instruction ${i} has opcode ${opcode}`);
+        let mode;
+        if (modeByte === MODE_ALL) {
+            mode = {
+                kind: 'all'
+            };
+        } else if (modeByte === MODE_PREV) {
+            // `Prev` needs a predecessor with one output, and that output must be
+            // this input. The contract compares registry INDICES, so do the same.
+            if (producedIdx === undefined || producedIdx !== idxB) {
+                fail('INVALID_STRUCTURE', `instruction ${i} does not chain onto its predecessor`);
+            }
+            mode = {
+                kind: 'prev'
+            };
+        } else if (modeByte >= MODE_PPM_BASE) {
+            const ppm = weights[modeByte - MODE_PPM_BASE];
+            if (ppm === undefined) fail('MALFORMED', `instruction ${i} weight index is out of range`);
+            mode = {
+                kind: 'ppm',
+                ppm: ppm
+            };
+        } else {
+            mode = {
+                kind: 'fixed',
+                amount: amount(modeByte - MODE_FIXED_BASE)
+            };
+        }
+        const pool = asset(idxA);
+        if (opcode === OP_BURN || opcode === OP_MINT) {
+            if (mode.kind !== 'all') fail('MALFORMED', `liquidity instruction ${i} must use mode All`);
+            if (idxC >= amountsLen) fail('MALFORMED', `instruction ${i} amount index is out of range`);
+            decoded.push({
+                kind: opcode === OP_BURN ? 'burn' : 'mint',
+                pool,
+                shareToken: asset(idxB),
+                amountIndex: idxC
+            });
+            producedIdx = opcode === OP_MINT ? idxB : undefined;
+            continue;
+        }
+        if (idxB === idxC) fail('INVALID_STRUCTURE', `instruction ${i} swaps a token for itself`);
+        decoded.push({
+            kind: 'swap',
+            venue: STELLAR_SWAP_VENUES[opcode],
+            mode,
+            pool,
+            tokenIn: asset(idxB),
+            tokenOut: asset(idxC)
+        });
+        producedIdx = idxC;
+    }
+    const totalMinOut = amount(minOutIdx);
+    // `execute::run` rejects a non-positive minimum.
+    if (totalMinOut <= 0n) fail('MIN_OUT_TOO_LOW', `encoded total_min_out is ${totalMinOut}`);
+    return {
+        version,
+        tokenIn: asset(tokenInIdx),
+        tokenOut: asset(tokenOutIdx),
+        totalMinOut,
+        referralId,
+        assets,
+        amounts,
+        ops: decoded,
+        weights
+    };
+}
+/**
+ * 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 function stellarTokenContractId(tokenId, network) {
+    if (StrKey.isValidContract(tokenId)) return tokenId;
+    if (!network) {
+        return fail('EXPECTATION_MISSING', `token ${tokenId} is not a contract id; pass \`network\` to derive its asset contract`);
+    }
+    try {
+        const sep = tokenId.indexOf(':');
+        const classic = tokenId === 'XLM' || tokenId === 'native' ? Asset.native() : new Asset(tokenId.slice(0, sep), tokenId.slice(sep + 1));
+        return classic.contractId(STELLAR_NETWORK_PASSPHRASE[network]);
+    } catch  {
+        return fail('MALFORMED', `token id ${tokenId} is not a contract id or a classic asset`);
+    }
+}
+const toAmount = (value, label)=>{
+    if (typeof value === 'bigint') return value;
+    if (!/^\d+$/.test(value)) {
+        return fail('EXPECTATION_MISSING', `${label} must be a base-unit integer string`);
+    }
+    return BigInt(value);
+};
+/**
+ * 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 function verifyStellarRouteBytes(route, expected) {
+    const minOut = toAmount(expected.minOut, 'expected.minOut');
+    if (minOut <= 0n) fail('EXPECTATION_MISSING', 'expected.minOut must be positive');
+    const decoded = decodeStellarRouteBytes(route);
+    if (decoded.tokenIn !== expected.tokenIn) {
+        fail('TOKEN_IN_MISMATCH', `route spends ${decoded.tokenIn}, expected ${expected.tokenIn}`);
+    }
+    if (decoded.tokenOut !== expected.tokenOut) {
+        fail('TOKEN_OUT_MISMATCH', `route delivers ${decoded.tokenOut}, expected ${expected.tokenOut}`);
+    }
+    if (decoded.totalMinOut < minOut) {
+        fail('MIN_OUT_TOO_LOW', `route enforces a minimum of ${decoded.totalMinOut}, below the expected ${minOut}`);
+    }
+    if (expected.amountIn !== undefined) {
+        const amountIn = toAmount(expected.amountIn, 'expected.amountIn');
+        for (const op of decoded.ops){
+            if (op.kind === 'swap' && op.mode.kind === 'fixed' && op.tokenIn === decoded.tokenIn && op.mode.amount > amountIn) {
+                fail('AMOUNT_IN_EXCEEDED', `a leg spends ${op.mode.amount}, above the input ${amountIn}`);
+            }
+        }
+    }
+    return decoded;
+}