@velocity-exchange/sdk 0.9.0 → 0.10.0

package/lib/node/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
      */

package/lib/node/swap/UnifiedSwapClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnifiedSwapClient.d.ts","sourceRoot":"","sources":["../../../src/swap/UnifiedSwapClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"UnifiedSwapClient.d.ts","sourceRoot":"","sources":["../../../src/swap/UnifiedSwapClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EACN,0BAA0B,EAC1B,cAAc,EACd,YAAY,EACZ,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAIjB,YAAY,EACX,0BAA0B,EAC1B,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,oBAAoB,GACpB,MAAM,SAAS,CAAC;AAQjB,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,QACM,CAAC;AAEjD;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACrD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,UAAU,CAAiB;IAEnC;;;;;;OAMG;gBACS,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,GAAG,EACH,QAAQ,GACR,EAAE;QACF,UAAU,EAAE,cAAc,CAAC;QAC3B,UAAU,EAAE,UAAU,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB;IAqBD,IAAW,YAAY,IAAI,cAAc,CAExC;IAED;;;;;;;OAOG;IACH,OAAO,KAAK,QAAQ,GAEnB;IAED;;;;;OAKG;IACU,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAOlE;;;;OAIG;IACU,oBAAoB,CAChC,MAAM,EAAE,0BAA0B,GAChC,OAAO,CAAC,qBAAqB,CAAC;IAIjC;;;;;;OAMG;IACU,kBAAkB,CAC9B,MAAM,EAAE,0BAA0B,GAChC,OAAO,CAAC,oBAAoB,CAAC;IAIhC;;OAEG;IACI,SAAS,IAAI,aAAa,GAAG,WAAW;IAI/C;;OAEG;IACI,aAAa,IAAI,cAAc;IAItC;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,OAAO,IAAI,OAAO;CAGzB"}

package/lib/node/swap/UnifiedSwapClient.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnifiedSwapClient = void 0;
+exports.UnifiedSwapClient = exports.DEFAULT_ROUTE_SIZE_CONSTRAINT = void 0;
 const jupiterClient_1 = require("../jupiter/jupiterClient");
 const titanClient_1 = require("../titan/titanClient");
 const utils_1 = require("../tx/utils");
@@ -10,10 +10,18 @@ const utils_1 = require("../tx/utils");
  */
 const VELOCITY_SWAP_IX_SIZE_BUFFER = 375;
 /** Byte budget handed to a swap provider for the route portion of the tx. */
-const DEFAULT_ROUTE_SIZE_CONSTRAINT = utils_1.MAX_TX_BYTE_SIZE - VELOCITY_SWAP_IX_SIZE_BUFFER;
+exports.DEFAULT_ROUTE_SIZE_CONSTRAINT = utils_1.MAX_TX_BYTE_SIZE - VELOCITY_SWAP_IX_SIZE_BUFFER;
+/**
+ * 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.
+ */
 class UnifiedSwapClient {
     /**
-     * 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)
@@ -41,129 +49,50 @@ class UnifiedSwapClient {
             throw new Error(`Unsupported client type: ${clientType}`);
         }
     }
+    get providerName() {
+        return this.clientType;
+    }
+    /**
+     * 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.
+     */
+    get provider() {
+        return this.client;
+    }
     /**
-     * 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.
      */
     async getQuote(params) {
-        if (this.clientType === 'jupiter') {
-            const jupiterClient = this.client;
-            const { userPublicKey: _userPublicKey, // Not needed for Jupiter
-            sizeConstraint: _sizeConstraint, // Jupiter-specific params to exclude
-            accountsLimitWritable: _accountsLimitWritable, ...jupiterParams } = params;
-            return await jupiterClient.getQuote(jupiterParams);
-        }
-        else {
-            const titanClient = this.client;
-            const { autoSlippage: _autoSlippage, // Titan-specific params to exclude
-            maxAutoSlippageBps: _maxAutoSlippageBps, usdEstimate: _usdEstimate, ...titanParams } = params;
-            if (!titanParams.userPublicKey) {
-                throw new Error('userPublicKey is required for Titan quotes');
-            }
-            // Cast to ensure TypeScript knows userPublicKey is defined
-            const titanParamsWithUser = {
-                ...titanParams,
-                userPublicKey: titanParams.userPublicKey,
-                swapMode: titanParams.swapMode, // Titan expects string
-                sizeConstraint: titanParams.sizeConstraint || DEFAULT_ROUTE_SIZE_CONSTRAINT,
-            };
-            return await titanClient.getQuote(titanParamsWithUser);
-        }
+        var _a;
+        return this.provider.getQuote({
+            ...params,
+            sizeConstraint: (_a = params.sizeConstraint) !== null && _a !== void 0 ? _a : exports.DEFAULT_ROUTE_SIZE_CONSTRAINT,
+        });
     }
     /**
-     * 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.
      */
-    async getSwap(params) {
-        if (this.clientType === 'jupiter') {
-            const jupiterClient = this.client;
-            // Cast the quote to Jupiter's specific QuoteResponse type
-            const jupiterParams = {
-                ...params,
-                quote: params.quote,
-            };
-            const transaction = await jupiterClient.getSwap(jupiterParams);
-            return { transaction };
-        }
-        else {
-            const titanClient = this.client;
-            const { userPublicKey } = params;
-            // For Titan, we need to reconstruct the parameters from the quote
-            const result = await titanClient.getSwap({
-                userPublicKey,
-            });
-            return {
-                transactionMessage: result.transactionMessage,
-                lookupTables: result.lookupTables,
-            };
-        }
+    async getRouteInstructions(params) {
+        return this.provider.getRouteInstructions(params);
     }
     /**
-     * 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.
      */
-    async getSwapInstructions({ inputMint, outputMint, amount, userPublicKey, slippageBps, swapMode = 'ExactIn', onlyDirectRoutes = false, quote, sizeConstraint, }) {
-        const isExactOut = swapMode === 'ExactOut';
-        let swapInstructions;
-        let lookupTables;
-        if (this.clientType === 'jupiter') {
-            const jupiterClient = this.client;
-            // Get quote if not provided
-            let finalQuote = quote;
-            if (!finalQuote) {
-                finalQuote = await jupiterClient.getQuote({
-                    inputMint,
-                    outputMint,
-                    amount,
-                    slippageBps,
-                    swapMode,
-                    onlyDirectRoutes,
-                });
-            }
-            if (!finalQuote) {
-                throw new Error('Could not fetch swap quote. Please try again.');
-            }
-            // Get swap transaction and extract instructions
-            const transaction = await jupiterClient.getSwap({
-                quote: finalQuote,
-                userPublicKey,
-                slippageBps,
-            });
-            const { transactionMessage, lookupTables: jupiterLookupTables } = await jupiterClient.getTransactionMessageAndLookupTables({
-                transaction,
-            });
-            swapInstructions = jupiterClient.getJupiterInstructions({
-                transactionMessage,
-                inputMint,
-                outputMint,
-            });
-            lookupTables = jupiterLookupTables;
-        }
-        else {
-            const titanClient = this.client;
-            // For Titan, get swap directly (it handles quote internally).
-            //
-            // NOTE: `getSwap` reads only `userPublicKey` — it replays the route
-            // cached by the preceding `getQuote`, so every other argument here is
-            // inert. The size constraint is therefore enforced at quote time (see
-            // `getQuote` above), which means an explicit `sizeConstraint` passed
-            // only to this method does not affect route selection.
-            const { transactionMessage, lookupTables: titanLookupTables } = await titanClient.getSwap({
-                inputMint,
-                outputMint,
-                amount,
-                userPublicKey,
-                slippageBps,
-                swapMode: isExactOut ? titanClient_1.SwapMode.ExactOut : titanClient_1.SwapMode.ExactIn,
-                onlyDirectRoutes,
-                sizeConstraint: sizeConstraint || DEFAULT_ROUTE_SIZE_CONSTRAINT,
-            });
-            swapInstructions = titanClient.getTitanInstructions({
-                transactionMessage,
-                inputMint,
-                outputMint,
-            });
-            lookupTables = titanLookupTables;
-        }
-        return { instructions: swapInstructions, lookupTables };
+    async getSwapTransaction(params) {
+        return this.provider.getSwapTransaction(params);
     }
     /**
      * Get the underlying client instance

package/lib/node/swap/routeInstructions.d.ts

@@ -0,0 +1,20 @@
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * Strips the setup and teardown a provider wraps around its route, leaving the
+ * instructions that go between `beginSwap` and `endSwap`.
+ *
+ * Velocity supplies its own compute budget, funds the input token account from
+ * the spot market vault, and sweeps the output back, so the provider's versions
+ * of all three are redundant. Its ATA creation for the input or output mint is
+ * dropped too, since velocity creates those itself; ATAs for any other mint
+ * (intermediate hops, fee accounts) are kept because nothing else creates them.
+ *
+ * Shared by both providers on purpose — when this lived in each client the two
+ * copies drifted, and the difference only showed up as a malformed transaction.
+ */
+export declare function filterRouteInstructions({ instructions, inputMint, outputMint, }: {
+    instructions: TransactionInstruction[];
+    inputMint: PublicKey;
+    outputMint: PublicKey;
+}): TransactionInstruction[];
+//# sourceMappingURL=routeInstructions.d.ts.map

package/lib/node/swap/routeInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeInstructions.d.ts","sourceRoot":"","sources":["../../../src/swap/routeInstructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAWpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,EACvC,YAAY,EACZ,SAAS,EACT,UAAU,GACV,EAAE;IACF,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,SAAS,CAAC;CACtB,GAAG,sBAAsB,EAAE,CAwB3B"}

package/lib/node/swap/routeInstructions.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterRouteInstructions = void 0;
+const COMPUTE_BUDGET_PROGRAM_ID = 'ComputeBudget111111111111111111111111111111';
+const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111';
+const ASSOCIATED_TOKEN_PROGRAM_ID = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+/** Index of the mint in an associated-token-account instruction's key list. */
+const ATA_IX_MINT_KEY_INDEX = 3;
+/**
+ * Strips the setup and teardown a provider wraps around its route, leaving the
+ * instructions that go between `beginSwap` and `endSwap`.
+ *
+ * Velocity supplies its own compute budget, funds the input token account from
+ * the spot market vault, and sweeps the output back, so the provider's versions
+ * of all three are redundant. Its ATA creation for the input or output mint is
+ * dropped too, since velocity creates those itself; ATAs for any other mint
+ * (intermediate hops, fee accounts) are kept because nothing else creates them.
+ *
+ * Shared by both providers on purpose — when this lived in each client the two
+ * copies drifted, and the difference only showed up as a malformed transaction.
+ */
+function filterRouteInstructions({ instructions, inputMint, outputMint, }) {
+    return instructions.filter((instruction) => {
+        var _a;
+        const programId = instruction.programId.toString();
+        if (programId === COMPUTE_BUDGET_PROGRAM_ID ||
+            programId === TOKEN_PROGRAM_ID ||
+            programId === SYSTEM_PROGRAM_ID) {
+            return false;
+        }
+        if (programId === ASSOCIATED_TOKEN_PROGRAM_ID) {
+            // Guarded: a malformed ATA instruction with a short key list would
+            // otherwise throw here rather than simply being kept.
+            const mint = (_a = instruction.keys[ATA_IX_MINT_KEY_INDEX]) === null || _a === void 0 ? void 0 : _a.pubkey;
+            if (mint && (mint.equals(inputMint) || mint.equals(outputMint))) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+exports.filterRouteInstructions = filterRouteInstructions;

package/lib/node/swap/types.d.ts

@@ -0,0 +1,197 @@
+import { AddressLookupTableAccount, PublicKey, TransactionInstruction, VersionedTransaction } from '@solana/web3.js';
+import { BN } from '../isomorphic/anchor';
+export type SwapMode = 'ExactIn' | 'ExactOut';
+export type SwapClientType = 'jupiter' | 'titan';
+/** Account budget assumed when a caller doesn't specify one. */
+export declare const DEFAULT_SWAP_MAX_ACCOUNTS = 50;
+/**
+ * Quote fields shared by every provider. Provider-specific extras are optional
+ * and must never be required to build a swap — see {@link SwapQuote}.
+ */
+export interface UnifiedQuoteResponse {
+    inputMint: string;
+    inAmount: string;
+    outputMint: string;
+    outAmount: string;
+    swapMode: SwapMode;
+    /**
+     * The slippage the route was quoted at. Authoritative — this is what the
+     * swap executes with, since {@link SwapProvider.getRouteInstructions} takes
+     * no slippage override. To swap at different slippage, quote again.
+     */
+    slippageBps: number;
+    routePlan: Array<{
+        swapInfo: any;
+        percent: number;
+    }>;
+    /** Jupiter only. */
+    otherAmountThreshold?: string;
+    /** Jupiter provides this; Titan doesn't, so callers derive it. */
+    priceImpactPct?: string;
+    platformFee?: {
+        amount?: string;
+        feeBps?: number;
+    };
+    contextSlot?: number;
+    timeTaken?: number;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * What the provider says its route does, recorded when the quote was produced.
+ *
+ * An implementation detail of the tamper check described on
+ * {@link expectProviderRoute} — you never write one of these. {@link
+ * buildSwapQuote} records it from the quote a provider is already returning.
+ */
+export interface SwapRouteFields {
+    readonly inputMint: string;
+    readonly outputMint: string;
+    readonly inAmount: string;
+    readonly outAmount: string;
+    readonly swapMode: SwapMode;
+    readonly slippageBps: number;
+}
+/**
+ * Everything a provider needs to turn its own quote back into instructions.
+ *
+ * Attached to the quote rather than held on the client so that building a swap
+ * is a pure function of the quote you were given. A provider that kept this
+ * internally would silently build against whatever route it happened to have
+ * cached, which is invisible at the call site and wrong whenever more than one
+ * quote is in flight.
+ *
+ * Opaque — read the normalized fields on {@link SwapQuote} instead.
+ */
+export type SwapProviderRoute = {
+    readonly provider: 'jupiter';
+    readonly quote: unknown;
+    readonly routed: SwapRouteFields;
+    readonly quotedFor?: string;
+} | {
+    readonly provider: 'titan';
+    readonly route: unknown;
+    readonly routed: SwapRouteFields;
+    readonly quotedFor?: string;
+};
+/**
+ * A {@link SwapProviderRoute} as a provider hands it to {@link buildSwapQuote} —
+ * the payload without the `routed` fields, which `buildSwapQuote` records itself.
+ */
+export type SwapProviderRoutePayload = OmitRouted<SwapProviderRoute>;
+/** Distributes over the union, so each member keeps its own payload field. */
+type OmitRouted<R> = R extends unknown ? Omit<R, 'routed'> : never;
+/**
+ * A quote plus the provider payload needed to execute it. Always pass the quote
+ * you intend to swap on; providers will not fall back to a previous one.
+ *
+ * Treat it as immutable. The normalized fields are checked against the payload
+ * before a swap is built, so an edited copy is rejected rather than silently
+ * executed as the swap it was originally quoted for — re-quote instead.
+ */
+export type SwapQuote = UnifiedQuoteResponse & {
+    readonly providerRoute: SwapProviderRoute;
+};
+export interface SwapQuoteParams {
+    inputMint: PublicKey;
+    outputMint: PublicKey;
+    amount: BN;
+    /** Required by Titan, which bakes the user's token accounts into the route. */
+    userPublicKey?: PublicKey;
+    maxAccounts?: number;
+    slippageBps?: number;
+    swapMode?: SwapMode;
+    onlyDirectRoutes?: boolean;
+    excludeDexes?: string[];
+    /** Titan only. */
+    sizeConstraint?: number;
+    /** Titan only. */
+    accountsLimitWritable?: number;
+    /** Jupiter only. */
+    autoSlippage?: boolean;
+    /** Jupiter only. */
+    maxAutoSlippageBps?: number;
+    /** Jupiter only. */
+    usdEstimate?: number;
+}
+export interface SwapRouteInstructions {
+    instructions: TransactionInstruction[];
+    lookupTables: AddressLookupTableAccount[];
+}
+export interface GetRouteInstructionsParams {
+    quote: SwapQuote;
+    /**
+     * Wallet the swap executes as. Must be the wallet the quote was requested
+     * for when the provider binds routes to a wallet — see
+     * {@link expectProviderRoute}.
+     *
+     * Don't be confused by the Velocity user account public key, which is different.
+     * This is usually the Velocity authority.
+     */
+    userPublicKey: PublicKey;
+}
+/**
+ * The contract every swap provider implements.
+ *
+ * Quote, then build — either into velocity's swap bracket, or into a standalone
+ * transaction. Both clients satisfying the same interface is what stops one
+ * provider growing behaviour the other doesn't have; callers get identical
+ * semantics regardless of which is configured.
+ *
+ * Provider-specific request fields live on {@link SwapQuoteParams} and are
+ * mapped by the provider itself, so adding one never means editing the unified
+ * client. Nothing that only one provider can honour belongs on
+ * {@link GetRouteInstructionsParams} — a build-time parameter the other silently
+ * ignores is indistinguishable from it being applied.
+ */
+export interface SwapProvider {
+    readonly providerName: SwapClientType;
+    getQuote(params: SwapQuoteParams): Promise<SwapQuote>;
+    /**
+     * Builds the route instructions for a quote returned by this provider's
+     * `getQuote`, at the slippage that quote was priced at.
+     * @throws If the quote came from a different provider or a different wallet.
+     */
+    getRouteInstructions(params: GetRouteInstructionsParams): Promise<SwapRouteInstructions>;
+    /**
+     * Builds a complete, self-contained swap transaction — the setup and
+     * teardown `getRouteInstructions` strips are still attached: compute budget,
+     * token account creation, and SOL wrapping.
+     *
+     * For swaps the caller signs and sends on its own. A swap running inside
+     * velocity's `beginSwap`/`endSwap` bracket wants `getRouteInstructions`
+     * instead — velocity supplies all three itself, and a second copy wraps SOL
+     * that nothing then unwraps.
+     *
+     * @throws If the quote came from a different provider or a different wallet.
+     */
+    getSwapTransaction(params: GetRouteInstructionsParams): Promise<VersionedTransaction>;
+}
+/**
+ * Assembles the {@link SwapQuote} a provider's `getQuote` returns, from the
+ * normalized quote and the route payload that will execute it.
+ *
+ * Providers call this rather than building the object themselves. It records
+ * what the route was quoted with next to the payload, which is what lets
+ * {@link expectProviderRoute} reject a quote edited after it was returned — so
+ * that check needs no cooperation from the provider beyond calling this.
+ */
+export declare function buildSwapQuote<Q extends UnifiedQuoteResponse>(quote: Q, providerRoute: SwapProviderRoutePayload): Q & SwapQuote;
+/**
+ * Narrows a quote's payload to `provider`, checks it can be executed by
+ * `userPublicKey`, and checks it still matches the quote it travels on.
+ *
+ * A route is wallet-bound when the provider resolves the user's token accounts
+ * at quote time (Titan does; Jupiter builds per-wallet at swap time). Those
+ * providers record the wallet on `quotedFor`, and executing such a route as
+ * anyone else moves funds through accounts the signer doesn't own.
+ *
+ * @throws If the quote was produced by a different provider, for a wallet other
+ * than `userPublicKey`, or for a different pair, size, mode or slippage than the
+ * quote now claims.
+ */
+export declare function expectProviderRoute<T extends SwapClientType>(quote: SwapQuote, provider: T, userPublicKey: PublicKey): Extract<SwapProviderRoute, {
+    provider: T;
+}>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/lib/node/swap/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/swap/types.ts"],"names":[],"mappings":"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"}