@velocity-exchange/sdk 0.9.0 → 0.11.0

package/lib/browser/jupiter/jupiterClient.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.JupiterClient = exports.RECOMMENDED_JUPITER_API = exports.LEGACY_JUPITER_API = exports.RECOMMENDED_JUPITER_API_VERSION = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const node_fetch_1 = __importDefault(require("node-fetch"));
+const routeInstructions_1 = require("../swap/routeInstructions");
+const types_1 = require("../swap/types");
 exports.RECOMMENDED_JUPITER_API_VERSION = '/v1';
 /** @deprecated Use RECOMMENDED_JUPITER_API instead. lite-api.jup.ag requires migration to api.jup.ag with API key. */
 exports.LEGACY_JUPITER_API = 'https://lite-api.jup.ag/swap';
@@ -18,7 +20,8 @@ class JupiterClient {
      * @param apiKey - API key for Jupiter API. Required for api.jup.ag (free tier available at https://portal.jup.ag)
      */
     constructor({ connection, url, apiKey, }) {
-        this.lookupTableCahce = new Map();
+        this.providerName = 'jupiter';
+        this.lookupTableCache = new Map();
         this.connection = connection;
         this.url = url !== null && url !== void 0 ? url : exports.RECOMMENDED_JUPITER_API;
         this.apiKey = apiKey;
@@ -45,8 +48,7 @@ class JupiterClient {
      * @param swapMode the swap mode (ExactIn or ExactOut)
      * @param onlyDirectRoutes whether to only return direct routes
      */
-    async getQuote({ inputMint, outputMint, amount, maxAccounts = 50, // 50 is an estimated amount with buffer
-    slippageBps = 50, swapMode = 'ExactIn', onlyDirectRoutes = false, excludeDexes, autoSlippage = false, maxAutoSlippageBps, usdEstimate, }) {
+    async getQuote({ inputMint, outputMint, amount, maxAccounts = types_1.DEFAULT_SWAP_MAX_ACCOUNTS, slippageBps = 50, swapMode = 'ExactIn', onlyDirectRoutes = false, excludeDexes, autoSlippage = false, maxAutoSlippageBps, usdEstimate, }) {
         var _a;
         if (autoSlippage && maxAutoSlippageBps === undefined) {
             throw new Error('JupiterClient.getQuote: maxAutoSlippageBps is required when autoSlippage is enabled');
@@ -94,19 +96,25 @@ class JupiterClient {
         if (!quote.inputMint || !quote.outputMint || !quote.outAmount) {
             throw new Error('Jupiter quote failed: response is missing route fields');
         }
-        return quote;
+        // Jupiter's /swap endpoint takes the quote body back verbatim, so the
+        // quote is its own route payload.
+        return (0, types_1.buildSwapQuote)(quote, { provider: 'jupiter', quote });
     }
     /**
      * Get a swap transaction for quote
-     * @param quoteResponse quote to perform swap
+     * @param quote quote to perform swap, from {@link getQuote}
      * @param userPublicKey the signer's wallet public key
-     * @param slippageBps the slippage tolerance in basis points
+     *
+     * Always builds at the quote's own slippage — the price the caller was
+     * shown. Re-quote to change it rather than overriding it here.
      */
-    async getSwap({ quote, userPublicKey, slippageBps = 50, }) {
+    async getSwap({ quote, userPublicKey, }) {
         var _a;
         if (!quote) {
             throw new Error('Jupiter swap quote not provided. Please try again.');
         }
+        // `providerRoute` is our own wrapper, not part of Jupiter's quote body.
+        const { providerRoute: _providerRoute, ...quoteResponse } = quote;
         const apiVersionParam = this.url === exports.RECOMMENDED_JUPITER_API || this.url === exports.LEGACY_JUPITER_API
             ? exports.RECOMMENDED_JUPITER_API_VERSION
             : '';
@@ -114,9 +122,9 @@ class JupiterClient {
             method: 'POST',
             headers: this.getHeaders('application/json'),
             body: JSON.stringify({
-                quoteResponse: quote,
+                quoteResponse,
                 userPublicKey,
-                slippageBps,
+                slippageBps: quoteResponse.slippageBps,
             }),
         })).json();
         if (!('swapTransaction' in resp)) {
@@ -131,6 +139,41 @@ class JupiterClient {
             throw new Error('Something went wrong with creating the Jupiter swap transaction. Please try again.');
         }
     }
+    /**
+     * The standalone transaction Jupiter's `/swap` endpoint returns, setup and
+     * teardown included.
+     * @throws If the quote came from a different provider or a different wallet.
+     */
+    async getSwapTransaction({ quote, userPublicKey, }) {
+        const jupiterQuote = (0, types_1.expectProviderRoute)(quote, 'jupiter', userPublicKey)
+            .quote;
+        return this.getSwap({ quote: jupiterQuote, userPublicKey });
+    }
+    /**
+     * Builds the route instructions for a quote returned by {@link getQuote}.
+     *
+     * The quote carries its own route payload, so this reads no client state
+     * and two quotes in flight can never be confused for one another. The swap
+     * is built at the slippage the quote was priced at — re-quote to change it.
+     * @throws If the quote came from a different provider or a different wallet.
+     */
+    async getRouteInstructions({ quote, userPublicKey, }) {
+        const jupiterQuote = (0, types_1.expectProviderRoute)(quote, 'jupiter', userPublicKey)
+            .quote;
+        const transaction = await this.getSwap({
+            quote: jupiterQuote,
+            userPublicKey,
+        });
+        const { transactionMessage, lookupTables } = await this.getTransactionMessageAndLookupTables({ transaction });
+        return {
+            instructions: (0, routeInstructions_1.filterRouteInstructions)({
+                instructions: transactionMessage.instructions,
+                inputMint: new web3_js_1.PublicKey(quote.inputMint),
+                outputMint: new web3_js_1.PublicKey(quote.outputMint),
+            }),
+            lookupTables,
+        };
+    }
     /**
      * Get the transaction message and lookup tables for a transaction
      * @param transaction
@@ -149,7 +192,7 @@ class JupiterClient {
         };
     }
     async getLookupTable(accountKey) {
-        const cached = this.lookupTableCahce.get(accountKey.toString());
+        const cached = this.lookupTableCache.get(accountKey.toString());
         if (cached !== undefined) {
             return cached;
         }
@@ -159,36 +202,19 @@ class JupiterClient {
         }
         // Populate the cache — without this every route re-fetches the same tables,
         // which is a large share of the RPC calls a swap makes.
-        this.lookupTableCahce.set(accountKey.toString(), lookupTable);
+        this.lookupTableCache.set(accountKey.toString(), lookupTable);
         return lookupTable;
     }
     /**
-     * Get the jupiter instructions from transaction by filtering out instructions to compute budget and associated token programs
-     * @param transactionMessage the transaction message
-     * @param inputMint the input mint
-     * @param outputMint the output mint
+     * Strips the setup/teardown Jupiter wraps around its route.
+     * @deprecated Use {@link getRouteInstructions}, which quotes and filters in
+     * one step. Kept for callers holding a decompiled message of their own.
      */
     getJupiterInstructions({ transactionMessage, inputMint, outputMint, }) {
-        return transactionMessage.instructions.filter((instruction) => {
-            if (instruction.programId.toString() ===
-                'ComputeBudget111111111111111111111111111111') {
-                return false;
-            }
-            if (instruction.programId.toString() ===
-                'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA') {
-                return false;
-            }
-            if (instruction.programId.toString() === '11111111111111111111111111111111') {
-                return false;
-            }
-            if (instruction.programId.toString() ===
-                'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL') {
-                const mint = instruction.keys[3].pubkey;
-                if (mint.equals(inputMint) || mint.equals(outputMint)) {
-                    return false;
-                }
-            }
-            return true;
+        return (0, routeInstructions_1.filterRouteInstructions)({
+            instructions: transactionMessage.instructions,
+            inputMint,
+            outputMint,
         });
     }
 }

package/lib/browser/math/amm.d.ts

@@ -327,15 +327,16 @@ export declare function calculateSpreadBN(baseSpread: number, lastOracleReserveP
  * Convenience wrapper around `calculateSpreadBN` that derives its lower-level inputs
  * (reserve price, oracle-vs-reserve spread, live oracle std, and confidence interval) from
  * `amm`/`marketStats`/`oraclePriceData` directly, then applies the market's manual
- * `ammSpreadAdjustment` (%, shrink if negative/grow if positive, floored at 1) on top. Returns
- * `[baseSpread/2, baseSpread/2]` unchanged (no dynamic widening) if `baseSpread` or
- * `curveUpdateIntensity` is zero.
+ * `ammSpreadAdjustment` (%, shrink if negative/grow if positive, floored at 1) on top.
+ * Mirrors `update_spreads` in `vlp/amm/math/spread.rs`: the dynamic spread is computed
+ * whenever `curveUpdateIntensity` is nonzero, and only a zero `curveUpdateIntensity`
+ * falls back to `[baseSpread/2, baseSpread/2]` (truncated).
  * @param amm AMM state to price the spread for.
  * @param marketStats Market stats needed for volatility/funding-bias inputs.
- * @param oraclePriceData Current oracle price data; required unless `baseSpread`/`curveUpdateIntensity` are both zero.
+ * @param oraclePriceData Current oracle price data; required unless `curveUpdateIntensity` is zero.
  * @param now Current unix timestamp (seconds); defaults to wall-clock time if omitted.
  * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6); computed from `amm`'s reserves if omitted.
- * @throws if `oraclePriceData` is omitted while `baseSpread` and `curveUpdateIntensity` are both nonzero.
+ * @throws if `oraclePriceData` is omitted while `curveUpdateIntensity` is nonzero.
  * @returns `[longSpread, shortSpread]`, both BID_ASK_SPREAD_PRECISION (1e6) fraction-of-price units.
  */
 export declare function calculateSpread(amm: AMM, marketStats: MarketStats, oraclePriceData?: Pick<OraclePriceData, 'price' | 'confidence'>, now?: BN, reservePrice?: BN): [number, number];

package/lib/browser/math/amm.js

@@ -699,27 +699,57 @@ function calculateSpreadBN(baseSpread, lastOracleReservePriceSpreadPct, lastOrac
     return [longSpread, shortSpread];
 }
 exports.calculateSpreadBN = calculateSpreadBN;
+/**
+ * Applies the market's manual `ammSpreadAdjustment` (%, grow if positive / shrink if
+ * negative, floored at 1) to an already-computed spread pair. Mirrors the tail of
+ * `update_spreads` in `vlp/amm/math/spread.rs`, which applies it to the frozen-curve
+ * branch as well as the dynamic one, and rounds as integer math (ceil when growing,
+ * floor when shrinking).
+ * @param amm AMM state holding `ammSpreadAdjustment`.
+ * @param longSpread Long-side spread before adjustment.
+ * @param shortSpread Short-side spread before adjustment.
+ * @returns `[longSpread, shortSpread]` after adjustment.
+ */
+function applyAmmSpreadAdjustment(amm, longSpread, shortSpread) {
+    if (amm.ammSpreadAdjustment > 0) {
+        const grow = (spread) => Math.max(spread + Math.ceil((spread * amm.ammSpreadAdjustment) / 100), 1);
+        return [grow(longSpread), grow(shortSpread)];
+    }
+    if (amm.ammSpreadAdjustment < 0) {
+        const shrink = (spread) => Math.max(spread - Math.floor((spread * -amm.ammSpreadAdjustment) / 100), 1);
+        return [shrink(longSpread), shrink(shortSpread)];
+    }
+    return [longSpread, shortSpread];
+}
 /**
  * Convenience wrapper around `calculateSpreadBN` that derives its lower-level inputs
  * (reserve price, oracle-vs-reserve spread, live oracle std, and confidence interval) from
  * `amm`/`marketStats`/`oraclePriceData` directly, then applies the market's manual
- * `ammSpreadAdjustment` (%, shrink if negative/grow if positive, floored at 1) on top. Returns
- * `[baseSpread/2, baseSpread/2]` unchanged (no dynamic widening) if `baseSpread` or
- * `curveUpdateIntensity` is zero.
+ * `ammSpreadAdjustment` (%, shrink if negative/grow if positive, floored at 1) on top.
+ * Mirrors `update_spreads` in `vlp/amm/math/spread.rs`: the dynamic spread is computed
+ * whenever `curveUpdateIntensity` is nonzero, and only a zero `curveUpdateIntensity`
+ * falls back to `[baseSpread/2, baseSpread/2]` (truncated).
  * @param amm AMM state to price the spread for.
  * @param marketStats Market stats needed for volatility/funding-bias inputs.
- * @param oraclePriceData Current oracle price data; required unless `baseSpread`/`curveUpdateIntensity` are both zero.
+ * @param oraclePriceData Current oracle price data; required unless `curveUpdateIntensity` is zero.
  * @param now Current unix timestamp (seconds); defaults to wall-clock time if omitted.
  * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6); computed from `amm`'s reserves if omitted.
- * @throws if `oraclePriceData` is omitted while `baseSpread` and `curveUpdateIntensity` are both nonzero.
+ * @throws if `oraclePriceData` is omitted while `curveUpdateIntensity` is nonzero.
  * @returns `[longSpread, shortSpread]`, both BID_ASK_SPREAD_PRECISION (1e6) fraction-of-price units.
  */
 function calculateSpread(amm, marketStats, oraclePriceData, now, reservePrice) {
-    if (amm.baseSpread == 0 || amm.curveUpdateIntensity == 0) {
-        return [amm.baseSpread / 2, amm.baseSpread / 2];
+    // On chain the dynamic spread is computed whenever curveUpdateIntensity > 0; a
+    // baseSpread of 0 does NOT disable it, it only lowers the floor that the vol
+    // spread is maxed against. Short-circuiting on baseSpread == 0 made the SDK
+    // report a zero-width vAMM spread on markets configured with baseSpread 0,
+    // while the program was quoting an inventory-skewed spread of >10%.
+    if (amm.curveUpdateIntensity == 0) {
+        // integer division on chain: `base_spread.safe_div(2)`
+        const halfBaseSpread = Math.floor(amm.baseSpread / 2);
+        return applyAmmSpreadAdjustment(amm, halfBaseSpread, halfBaseSpread);
     }
     if (!oraclePriceData) {
-        throw new Error('calculateSpread: oraclePriceData is required when baseSpread and curveUpdateIntensity are nonzero');
+        throw new Error('calculateSpread: oraclePriceData is required when curveUpdateIntensity is nonzero');
     }
     if (!reservePrice) {
         reservePrice = calculatePrice(amm.baseAssetReserve, amm.quoteAssetReserve, amm.pegMultiplier);
@@ -733,17 +763,7 @@ function calculateSpread(amm, marketStats, oraclePriceData, now, reservePrice) {
     const liveOracleStd = (0, oracles_1.calculateLiveOracleStd)(marketStats, oraclePriceData, now);
     const confIntervalPct = (0, oracles_1.getNewOracleConfPct)(marketStats, oraclePriceData, reservePrice, now);
     const spreads = calculateSpreadBN(amm.baseSpread, targetMarkSpreadPct, confIntervalPct, amm.maxSpread, amm.quoteAssetReserve, amm.terminalQuoteAssetReserve, amm.pegMultiplier, amm.baseAssetAmountWithAmm, reservePrice, amm.totalFeeMinusDistributions, amm.netRevenueSinceLastFunding, amm.baseAssetReserve, amm.minBaseAssetReserve, amm.maxBaseAssetReserve, marketStats.markStd, liveOracleStd, marketStats.longIntensityVolume, marketStats.shortIntensityVolume, marketStats.volume24H, amm.ammInventorySpreadAdjustment, marketStats.last24HAvgFundingRate, marketStats.lastFundingOracleTwap, amm.fundingBiasSensitivity);
-    let longSpread = spreads[0];
-    let shortSpread = spreads[1];
-    if (amm.ammSpreadAdjustment > 0) {
-        longSpread = Math.max(longSpread + (longSpread * amm.ammSpreadAdjustment) / 100, 1);
-        shortSpread = Math.max(shortSpread + (shortSpread * amm.ammSpreadAdjustment) / 100, 1);
-    }
-    else if (amm.ammSpreadAdjustment < 0) {
-        longSpread = Math.max(longSpread - (longSpread * -amm.ammSpreadAdjustment) / 100, 1);
-        shortSpread = Math.max(shortSpread - (shortSpread * -amm.ammSpreadAdjustment) / 100, 1);
-    }
-    return [longSpread, shortSpread];
+    return applyAmmSpreadAdjustment(amm, spreads[0], spreads[1]);
 }
 exports.calculateSpread = calculateSpread;
 /**

package/lib/browser/math/margin.d.ts

@@ -104,13 +104,14 @@ export declare function calculateCollateralDepositRequiredForTrade(velocityClien
  * Minimal equity floor to carry along with a quote transfer of `amount` out
  * of a subaccount so the debited side ends at/above its buffered floor
  * (`equityFloor + equityFloorBuffer`): the first
- * `totalCollateral - (floor + buffer)` of the transfer carries no floor, the
+ * `netEquity - (floor + buffer)` of the transfer carries no floor, the
  * remainder carries floor one-for-one, capped at the floor the subaccount
- * actually holds. Returns zero when no floor is set. The result never exceeds
- * `amount`, so a credited side that met its own buffered floor before the
- * transfer still meets it after. All values QUOTE_PRECISION.
+ * actually holds. `netEquity` is `User.getNetUsdValue()`, the metric the
+ * onchain floor checks use. Returns zero when no floor is set. The result
+ * never exceeds `amount`, so a credited side that met its own buffered floor
+ * before the transfer still meets it after. All values QUOTE_PRECISION.
  */
-export declare function calculateEquityFloorAutoDelta(amount: BN, totalCollateral: BN, equityFloor: BN, equityFloorBuffer: BN): BN;
+export declare function calculateEquityFloorAutoDelta(amount: BN, netEquity: BN, equityFloor: BN, equityFloorBuffer: BN): BN;
 /**
  * Severity of a subaccount's equity relative to its floor, most to least
  * severe. `breached`: below the floor, the permissionless breaker can trip.
@@ -120,9 +121,10 @@ export declare function calculateEquityFloorAutoDelta(amount: BN, totalCollatera
  */
 export type EquityFloorLevel = 'breached' | 'critical' | 'warning' | 'healthy' | 'disabled';
 /**
- * Classifies `totalCollateral` against the floor thresholds. Used by the
- * `EquityFloorManager` and the equity-floor guard bot so both report the same
- * levels. `warningBufferMultiple` scales the warning threshold above the
- * floor (default 2: warn inside `floor + 2 * buffer`). All QUOTE_PRECISION.
+ * Classifies `netEquity` (`User.getNetUsdValue()`) against the floor
+ * thresholds. Used by the `EquityFloorManager` and the equity-floor guard bot
+ * so both report the same levels. `warningBufferMultiple` scales the warning
+ * threshold above the floor (default 2: warn inside `floor + 2 * buffer`).
+ * All QUOTE_PRECISION.
  */
-export declare function getEquityFloorLevel(totalCollateral: BN, equityFloor: BN, equityFloorBuffer: BN, warningBufferMultiple?: number): EquityFloorLevel;
+export declare function getEquityFloorLevel(netEquity: BN, equityFloor: BN, equityFloorBuffer: BN, warningBufferMultiple?: number): EquityFloorLevel;

package/lib/browser/math/margin.js

@@ -214,37 +214,39 @@ exports.calculateCollateralDepositRequiredForTrade = calculateCollateralDepositR
  * Minimal equity floor to carry along with a quote transfer of `amount` out
  * of a subaccount so the debited side ends at/above its buffered floor
  * (`equityFloor + equityFloorBuffer`): the first
- * `totalCollateral - (floor + buffer)` of the transfer carries no floor, the
+ * `netEquity - (floor + buffer)` of the transfer carries no floor, the
  * remainder carries floor one-for-one, capped at the floor the subaccount
- * actually holds. Returns zero when no floor is set. The result never exceeds
- * `amount`, so a credited side that met its own buffered floor before the
- * transfer still meets it after. All values QUOTE_PRECISION.
+ * actually holds. `netEquity` is `User.getNetUsdValue()`, the metric the
+ * onchain floor checks use. Returns zero when no floor is set. The result
+ * never exceeds `amount`, so a credited side that met its own buffered floor
+ * before the transfer still meets it after. All values QUOTE_PRECISION.
  */
-function calculateEquityFloorAutoDelta(amount, totalCollateral, equityFloor, equityFloorBuffer) {
+function calculateEquityFloorAutoDelta(amount, netEquity, equityFloor, equityFloorBuffer) {
     if (equityFloor.lte(numericConstants_1.ZERO)) {
         return numericConstants_1.ZERO;
     }
-    const excess = anchor_1.BN.max(totalCollateral.sub(equityFloor.add(equityFloorBuffer)), numericConstants_1.ZERO);
+    const excess = anchor_1.BN.max(netEquity.sub(equityFloor.add(equityFloorBuffer)), numericConstants_1.ZERO);
     return anchor_1.BN.min(anchor_1.BN.max(amount.sub(excess), numericConstants_1.ZERO), equityFloor);
 }
 exports.calculateEquityFloorAutoDelta = calculateEquityFloorAutoDelta;
 /**
- * Classifies `totalCollateral` against the floor thresholds. Used by the
- * `EquityFloorManager` and the equity-floor guard bot so both report the same
- * levels. `warningBufferMultiple` scales the warning threshold above the
- * floor (default 2: warn inside `floor + 2 * buffer`). All QUOTE_PRECISION.
+ * Classifies `netEquity` (`User.getNetUsdValue()`) against the floor
+ * thresholds. Used by the `EquityFloorManager` and the equity-floor guard bot
+ * so both report the same levels. `warningBufferMultiple` scales the warning
+ * threshold above the floor (default 2: warn inside `floor + 2 * buffer`).
+ * All QUOTE_PRECISION.
  */
-function getEquityFloorLevel(totalCollateral, equityFloor, equityFloorBuffer, warningBufferMultiple = 2) {
+function getEquityFloorLevel(netEquity, equityFloor, equityFloorBuffer, warningBufferMultiple = 2) {
     if (equityFloor.lte(numericConstants_1.ZERO)) {
         return 'disabled';
     }
-    if (totalCollateral.lt(equityFloor)) {
+    if (netEquity.lt(equityFloor)) {
         return 'breached';
     }
-    if (totalCollateral.lt(equityFloor.add(equityFloorBuffer))) {
+    if (netEquity.lt(equityFloor.add(equityFloorBuffer))) {
         return 'critical';
     }
-    if (totalCollateral.lt(equityFloor.add(equityFloorBuffer.muln(warningBufferMultiple)))) {
+    if (netEquity.lt(equityFloor.add(equityFloorBuffer.muln(warningBufferMultiple)))) {
         return 'warning';
     }
     return 'healthy';

package/lib/browser/math/superStake.d.ts

@@ -1,5 +1,5 @@
 import { AddressLookupTableAccount, PublicKey, TransactionInstruction } from '@solana/web3.js';
-import { JupiterClient, QuoteResponse } from '../jupiter/jupiterClient';
+import { JupiterClient, JupiterSwapQuote } from '../jupiter/jupiterClient';
 import { VelocityClient } from '../velocityClient';
 import { BN } from '../isomorphic/anchor';
 import { User } from '../user';
@@ -61,7 +61,7 @@ export declare function fetchBSolVelocityEmissions(): Promise<fetch.Response>;
  * @param {boolean} [params.forceMarinade] - Force the direct Marinade stake path over a Jupiter
  *   swap even if Jupiter would be cheaper (market index 2 only)
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse instead of
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse instead of
  *   fetching a fresh one
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price?: number }>} The instructions to submit, any address
@@ -78,7 +78,7 @@ export declare function findBestSuperStakeIxs({ marketIndex, amount, jupiterClie
     userAccountPublicKey?: PublicKey;
     forceMarinade?: boolean;
     onlyDirectRoutes?: boolean;
-    jupiterQuote?: QuoteResponse;
+    jupiterQuote?: JupiterSwapQuote;
 }): Promise<{
     ixs: TransactionInstruction[];
     lookupTables: AddressLookupTableAccount[];
@@ -100,7 +100,7 @@ export declare function findBestSuperStakeIxs({ marketIndex, amount, jupiterClie
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.forceMarinade] - Force the Marinade path regardless of Jupiter pricing
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price: number }>} The chosen route's instructions, required
  *   lookup tables, the method used, and the mSOL/SOL price used for the decision
@@ -113,7 +113,7 @@ export declare function findBestMSolSuperStakeIxs({ amount, jupiterClient, veloc
     userAccountPublicKey?: PublicKey;
     forceMarinade?: boolean;
     onlyDirectRoutes?: boolean;
-    jupiterQuote?: QuoteResponse;
+    jupiterQuote?: JupiterSwapQuote;
 }): Promise<{
     ixs: TransactionInstruction[];
     lookupTables: AddressLookupTableAccount[];
@@ -130,7 +130,7 @@ export declare function findBestMSolSuperStakeIxs({ amount, jupiterClient, veloc
  * @param {VelocityClient} params.velocityClient - Velocity client
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price?: number }>} Always resolves with `method: 'jupiter'`
  */
@@ -140,7 +140,7 @@ export declare function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, ve
     velocityClient: VelocityClient;
     userAccountPublicKey?: PublicKey;
     onlyDirectRoutes?: boolean;
-    jupiterQuote?: QuoteResponse;
+    jupiterQuote?: JupiterSwapQuote;
 }): Promise<{
     ixs: TransactionInstruction[];
     lookupTables: AddressLookupTableAccount[];
@@ -161,7 +161,7 @@ export declare function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, ve
  * @param {VelocityClient} params.velocityClient - Velocity client
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade' }>} Always resolves with `method: 'jupiter'`
  */
@@ -173,7 +173,7 @@ export declare function findBestLstSuperStakeIxs({ amount, jupiterClient, veloci
     velocityClient: VelocityClient;
     userAccountPublicKey?: PublicKey;
     onlyDirectRoutes?: boolean;
-    jupiterQuote?: QuoteResponse;
+    jupiterQuote?: JupiterSwapQuote;
 }): Promise<{
     ixs: TransactionInstruction[];
     lookupTables: AddressLookupTableAccount[];

package/lib/browser/math/superStake.js

@@ -49,7 +49,7 @@ exports.fetchBSolVelocityEmissions = fetchBSolVelocityEmissions;
  * @param {boolean} [params.forceMarinade] - Force the direct Marinade stake path over a Jupiter
  *   swap even if Jupiter would be cheaper (market index 2 only)
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse instead of
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse instead of
  *   fetching a fresh one
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price?: number }>} The instructions to submit, any address
@@ -112,7 +112,7 @@ exports.findBestSuperStakeIxs = findBestSuperStakeIxs;
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.forceMarinade] - Force the Marinade path regardless of Jupiter pricing
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price: number }>} The chosen route's instructions, required
  *   lookup tables, the method used, and the mSOL/SOL price used for the decision
@@ -155,10 +155,10 @@ async function findBestMSolSuperStakeIxs({ amount, jupiterClient, velocityClient
         };
     }
     else {
-        const { ixs, lookupTables } = await velocityClient.getJupiterSwapIxV6({
+        const { ixs, lookupTables } = await velocityClient.getProviderSwapIx({
             inMarketIndex: 1,
             outMarketIndex: 2,
-            jupiterClient,
+            swapProvider: jupiterClient,
             amount,
             userAccountPublicKey,
             onlyDirectRoutes,
@@ -183,7 +183,7 @@ exports.findBestMSolSuperStakeIxs = findBestMSolSuperStakeIxs;
  * @param {VelocityClient} params.velocityClient - Velocity client
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade'; price?: number }>} Always resolves with `method: 'jupiter'`
  */
@@ -214,15 +214,15 @@ exports.findBestJitoSolSuperStakeIxs = findBestJitoSolSuperStakeIxs;
  * @param {VelocityClient} params.velocityClient - Velocity client
  * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
  * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
- * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @param {JupiterSwapQuote} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
  * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
  *   method: 'jupiter' | 'marinade' }>} Always resolves with `method: 'jupiter'`
  */
 async function findBestLstSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, onlyDirectRoutes, lstMarketIndex, jupiterQuote, }) {
-    const { ixs, lookupTables } = await velocityClient.getJupiterSwapIxV6({
+    const { ixs, lookupTables } = await velocityClient.getProviderSwapIx({
         inMarketIndex: 1,
         outMarketIndex: lstMarketIndex,
-        jupiterClient,
+        swapProvider: jupiterClient,
         amount,
         userAccountPublicKey,
         onlyDirectRoutes,

package/lib/browser/swap/UnifiedSwapClient.d.ts

@@ -1,66 +1,23 @@
-import { Connection, PublicKey, TransactionMessage, AddressLookupTableAccount, VersionedTransaction, TransactionInstruction } from '@solana/web3.js';
-import { BN } from '../isomorphic/anchor';
+import { Connection, VersionedTransaction } from '@solana/web3.js';
 import { JupiterClient } from '../jupiter/jupiterClient';
 import { TitanClient } from '../titan/titanClient';
-export type SwapMode = 'ExactIn' | 'ExactOut';
-export type SwapClientType = 'jupiter' | 'titan';
+import { GetRouteInstructionsParams, SwapClientType, SwapProvider, SwapQuote, SwapQuoteParams, SwapRouteInstructions } from './types';
+export type { GetRouteInstructionsParams, SwapProviderRoute, SwapClientType, SwapMode, SwapProvider, SwapQuote, SwapQuoteParams, SwapRouteInstructions, UnifiedQuoteResponse, } from './types';
+/** Byte budget handed to a swap provider for the route portion of the tx. */
+export declare const DEFAULT_ROUTE_SIZE_CONSTRAINT: number;
 /**
- * Unified quote response interface that combines properties from both Jupiter and Titan
- * This provides a consistent interface while allowing for provider-specific fields
+ * Routes swap calls to the configured provider.
+ *
+ * Intentionally thin: it picks a provider and forwards. Anything that varies
+ * between Jupiter and Titan belongs in the provider, behind
+ * {@link SwapProvider} — branching on the provider here is how the two paths
+ * drifted apart previously, since nothing forced them to keep the same
+ * semantics.
  */
-export interface UnifiedQuoteResponse {
-    inputMint: string;
-    inAmount: string;
-    outputMint: string;
-    outAmount: string;
-    swapMode: SwapMode;
-    slippageBps: number;
-    routePlan: Array<{
-        swapInfo: any;
-        percent: number;
-    }>;
-    otherAmountThreshold?: string;
-    priceImpactPct?: string;
-    platformFee?: {
-        amount?: string;
-        feeBps?: number;
-    };
-    contextSlot?: number;
-    timeTaken?: number;
-    error?: string;
-    errorCode?: string;
-}
-export interface SwapQuoteParams {
-    inputMint: PublicKey;
-    outputMint: PublicKey;
-    amount: BN;
-    userPublicKey?: PublicKey;
-    maxAccounts?: number;
-    slippageBps?: number;
-    swapMode?: SwapMode;
-    onlyDirectRoutes?: boolean;
-    excludeDexes?: string[];
-    sizeConstraint?: number;
-    accountsLimitWritable?: number;
-    autoSlippage?: boolean;
-    maxAutoSlippageBps?: number;
-    usdEstimate?: number;
-}
-export interface SwapTransactionParams {
-    quote: UnifiedQuoteResponse;
-    userPublicKey: PublicKey;
-    slippageBps?: number;
-}
-export interface SwapTransactionResult {
-    transaction?: VersionedTransaction;
-    transactionMessage?: TransactionMessage;
-    lookupTables?: AddressLookupTableAccount[];
-}
-export declare class UnifiedSwapClient {
+export declare class UnifiedSwapClient implements SwapProvider {
     private client;
     private clientType;
     /**
-     * Create a unified swap client
      * @param clientType - 'jupiter' or 'titan'
      * @param connection - Solana connection
      * @param authToken - For Titan: auth token (required when not using proxy). For Jupiter: API key (required for api.jup.ag, get free key at https://portal.jup.ag)
@@ -74,32 +31,37 @@ export declare class UnifiedSwapClient {
         url?: string;
         proxyUrl?: string;
     });
+    get providerName(): SwapClientType;
+    /**
+     * The configured client, seen only as {@link SwapProvider}.
+     *
+     * Forwarding through the interface rather than the concrete union is what
+     * makes goal of this class enforceable: a provider added to the union that
+     * implements only part of the contract fails to compile here, instead of
+     * resolving against whichever call signatures the union happens to share.
+     */
+    private get provider();
     /**
-     * Get a swap quote from the underlying client
+     * Get a swap quote from the configured provider.
+     *
+     * Provider-specific fields on {@link SwapQuoteParams} are mapped by the
+     * provider, so the ones it doesn't recognise are simply ignored.
      */
-    getQuote(params: SwapQuoteParams): Promise<UnifiedQuoteResponse>;
+    getQuote(params: SwapQuoteParams): Promise<SwapQuote>;
     /**
-     * Get a swap transaction from the underlying client
+     * Builds the route instructions for a quote from {@link getQuote}, at the
+     * slippage that quote was priced at.
+     * @throws If the quote came from a different provider or a different wallet.
      */
-    getSwap(params: SwapTransactionParams): Promise<SwapTransactionResult>;
+    getRouteInstructions(params: GetRouteInstructionsParams): Promise<SwapRouteInstructions>;
     /**
-     * Get swap instructions from the underlying client (Jupiter or Titan)
-     * This is the core swap logic without any context preparation
+     * Builds a standalone swap transaction for a quote from {@link getQuote},
+     * keeping the provider's own compute budget, token account creation and SOL
+     * wrapping. Use {@link getRouteInstructions} for a swap that runs inside
+     * velocity's `beginSwap`/`endSwap` bracket.
+     * @throws If the quote came from a different provider or a different wallet.
      */
-    getSwapInstructions({ inputMint, outputMint, amount, userPublicKey, slippageBps, swapMode, onlyDirectRoutes, quote, sizeConstraint, }: {
-        inputMint: PublicKey;
-        outputMint: PublicKey;
-        amount: BN;
-        userPublicKey: PublicKey;
-        slippageBps?: number;
-        swapMode?: SwapMode;
-        onlyDirectRoutes?: boolean;
-        quote?: UnifiedQuoteResponse;
-        sizeConstraint?: number;
-    }): Promise<{
-        instructions: TransactionInstruction[];
-        lookupTables: AddressLookupTableAccount[];
-    }>;
+    getSwapTransaction(params: GetRouteInstructionsParams): Promise<VersionedTransaction>;
     /**
      * Get the underlying client instance
      */