@velocity-exchange/sdk 0.9.0 → 0.11.0

package/lib/browser/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/browser/swap/routeInstructions.d.ts

@@ -0,0 +1,19 @@
+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[];

package/lib/browser/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/browser/swap/types.d.ts

@@ -0,0 +1,196 @@
+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 {};

package/lib/browser/swap/types.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectProviderRoute = exports.buildSwapQuote = exports.DEFAULT_SWAP_MAX_ACCOUNTS = void 0;
+/** Account budget assumed when a caller doesn't specify one. */
+exports.DEFAULT_SWAP_MAX_ACCOUNTS = 50;
+/**
+ * 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.
+ */
+function buildSwapQuote(quote, providerRoute) {
+    const { inputMint, outputMint, inAmount, outAmount, swapMode, slippageBps } = quote;
+    const routed = {
+        inputMint,
+        outputMint,
+        inAmount,
+        outAmount,
+        swapMode,
+        slippageBps,
+    };
+    return {
+        ...quote,
+        providerRoute: { ...providerRoute, routed },
+    };
+}
+exports.buildSwapQuote = buildSwapQuote;
+/** Fields that must describe the same swap on the quote and on its route. */
+const ROUTED_FIELDS = [
+    'inputMint',
+    'outputMint',
+    'inAmount',
+    'outAmount',
+    'swapMode',
+    'slippageBps',
+];
+/**
+ * Throws unless the quote's normalized fields still describe the route it
+ * carries.
+ *
+ * Callers and velocity's swap guards read the normalized fields; the provider
+ * executes the opaque payload. Nothing but this ties the two together, so a
+ * quote that was copied and edited — `{ ...quote, inAmount }`, a mint rewritten
+ * in place — would pass every pair, size and slippage check and then execute the
+ * route it was originally quoted for.
+ */
+function assertQuoteMatchesRoute(quote, provider, routed) {
+    if (!routed) {
+        throw new Error(`Quote is missing the route fields recorded at quote time. It must come from ${provider}'s getQuote, which builds it with buildSwapQuote.`);
+    }
+    for (const field of ROUTED_FIELDS) {
+        // Stringified: a provider may normalize a numeric field it decoded.
+        if (String(quote[field]) !== String(routed[field])) {
+            throw new Error(`Quote reports ${field} ${String(quote[field])} but the route it carries was quoted with ${String(routed[field])}. The quote was modified after it was returned; re-quote instead.`);
+        }
+    }
+}
+/**
+ * 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.
+ */
+function expectProviderRoute(quote, provider, userPublicKey) {
+    const route = quote === null || quote === void 0 ? void 0 : quote.providerRoute;
+    if (!route) {
+        throw new Error(`Quote is missing its provider route. It must come from ${provider}'s getQuote.`);
+    }
+    if (route.provider !== provider) {
+        throw new Error(`Quote came from ${route.provider} but is being swapped on ${provider}.`);
+    }
+    if (route.quotedFor && route.quotedFor !== userPublicKey.toString()) {
+        throw new Error(`Quote was requested for ${route.quotedFor} but is being swapped by ${userPublicKey.toString()}.`);
+    }
+    assertQuoteMatchesRoute(quote, provider, route.routed);
+    return route;
+}
+exports.expectProviderRoute = expectProviderRoute;

package/lib/browser/titan/titanClient.d.ts

@@ -1,36 +1,16 @@
-import { Connection, PublicKey, TransactionMessage, AddressLookupTableAccount, TransactionInstruction } from '@solana/web3.js';
-import { BN } from '../isomorphic/anchor';
+import { Connection, AddressLookupTableAccount, VersionedTransaction } from '@solana/web3.js';
+import { GetRouteInstructionsParams, SwapProvider, SwapQuote, SwapQuoteParams, SwapRouteInstructions } from '../swap/types';
 export declare enum SwapMode {
     ExactIn = "ExactIn",
     ExactOut = "ExactOut"
 }
-export interface QuoteResponse {
-    inputMint: string;
-    inAmount: string;
-    outputMint: string;
-    outAmount: string;
-    swapMode: SwapMode;
-    slippageBps: number;
-    platformFee?: {
-        amount?: string;
-        feeBps?: number;
-    };
-    routePlan: Array<{
-        swapInfo: any;
-        percent: number;
-    }>;
-    contextSlot?: number;
-    timeTaken?: number;
-    error?: string;
-    errorCode?: string;
-}
-export declare class TitanClient {
+export declare class TitanClient implements SwapProvider {
+    readonly providerName = "titan";
     authToken: string;
     url: string;
     connection: Connection;
     proxyUrl?: string;
-    private lastQuoteData?;
-    private lastQuoteParams?;
+    lookupTableCache: Map<string, AddressLookupTableAccount>;
     constructor({ connection, authToken, url, proxyUrl, }: {
         connection: Connection;
         authToken: string;
@@ -39,57 +19,41 @@ export declare class TitanClient {
     });
     private buildParams;
     /**
-     * Get routes for a swap
+     * Get the best available route for a swap.
+     *
+     * The route is returned on the quote's `providerRoute`, so
+     * {@link getRouteInstructions} builds exactly what was quoted here, at the
+     * slippage quoted here.
+     * @throws If `userPublicKey` is missing — Titan bakes the user's token
+     * accounts into the route, so a route quoted for one wallet cannot be
+     * executed by another. The wallet is recorded on the route and enforced
+     * when the route is built.
      */
-    getQuote({ inputMint, outputMint, amount, userPublicKey, maxAccounts, // 50 is an estimated amount with buffer
-    slippageBps, swapMode, onlyDirectRoutes, excludeDexes, sizeConstraint, accountsLimitWritable, }: {
-        inputMint: PublicKey;
-        outputMint: PublicKey;
-        amount: BN;
-        userPublicKey: PublicKey;
-        maxAccounts?: number;
-        slippageBps?: number;
-        swapMode?: string;
-        onlyDirectRoutes?: boolean;
-        excludeDexes?: string[];
-        sizeConstraint?: number;
-        accountsLimitWritable?: number;
-    }): Promise<QuoteResponse>;
+    getQuote({ inputMint, outputMint, amount, userPublicKey, maxAccounts, slippageBps, swapMode, onlyDirectRoutes, excludeDexes, sizeConstraint, accountsLimitWritable, }: SwapQuoteParams): Promise<SwapQuote>;
     /**
-     * Get a swap transaction for quote
+     * The route as Titan built it, compiled into a signable transaction. Titan
+     * returns instructions rather than a transaction, so unlike Jupiter there is
+     * nothing to strip — the route already includes its own setup and teardown.
+     * @throws If the quote came from a different provider or a different wallet,
+     * or if a lookup table the route depends on can't be loaded.
      */
-    getSwap({ userPublicKey, }: {
-        inputMint?: PublicKey;
-        outputMint?: PublicKey;
-        amount?: BN;
-        userPublicKey: PublicKey;
-        maxAccounts?: number;
-        slippageBps?: number;
-        swapMode?: SwapMode;
-        onlyDirectRoutes?: boolean;
-        excludeDexes?: string[];
-        sizeConstraint?: number;
-        accountsLimitWritable?: number;
-    }): Promise<{
-        transactionMessage: TransactionMessage;
-        lookupTables: AddressLookupTableAccount[];
-    }>;
+    getSwapTransaction({ quote, userPublicKey, }: GetRouteInstructionsParams): Promise<VersionedTransaction>;
     /**
-     * Get the titan 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
+     * Builds the route instructions for a quote returned by {@link getQuote}.
+     *
+     * The route travels on the quote, so this reads no client state and two
+     * quotes in flight can never be confused for one another. Slippage was
+     * fixed when Titan built the route, so there is nothing to apply here.
+     * @throws If the quote came from a different provider or a different wallet,
+     * or if a lookup table the route depends on can't be loaded.
      */
-    getTitanInstructions({ transactionMessage, inputMint, outputMint, }: {
-        transactionMessage: TransactionMessage;
-        inputMint: PublicKey;
-        outputMint: PublicKey;
-    }): TransactionInstruction[];
+    getRouteInstructions({ quote, userPublicKey, }: GetRouteInstructionsParams): Promise<SwapRouteInstructions>;
     /**
      * Fetches a lookup table required by a route, retrying transient RPC
-     * failures (rate limiting in particular) before giving up.
+     * failures (rate limiting in particular) before giving up. Checks the
+     * instance cache first and populates it on a fresh fetch.
      * @throws If the table still can't be loaded, or doesn't exist on-chain.
      */
     private fetchLookupTable;
-    private getTransactionMessageAndLookupTables;
+    private getInstructionsAndLookupTables;
 }