@velocity-exchange/sdk 0.9.0 → 0.10.0

package/lib/node/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/node/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,58 +19,42 @@ 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;
 }
 //# sourceMappingURL=titanClient.d.ts.map

package/lib/node/titan/titanClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"titanClient.d.ts","sourceRoot":"","sources":["../../../src/titan/titanClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"titanClient.d.ts","sourceRoot":"","sources":["../../../src/titan/titanClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,UAAU,EAEV,yBAAyB,EAGzB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAEN,0BAA0B,EAC1B,YAAY,EACZ,SAAS,EACT,eAAe,EACf,qBAAqB,EAGrB,MAAM,eAAe,CAAC;AAEvB,oBAAY,QAAQ;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;CACrB;AA4FD,qBAAa,WAAY,YAAW,YAAY;IAC/C,SAAgB,YAAY,WAAW;IAEvC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,yCAAgD;gBAEpD,EACX,UAAU,EACV,SAAS,EACT,GAAG,EACH,QAAQ,GACR,EAAE;QACF,UAAU,EAAE,UAAU,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB;IAOD,OAAO,CAAC,WAAW;IAwDnB;;;;;;;;;;OAUG;IACU,QAAQ,CAAC,EACrB,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACb,WAAuC,EACvC,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,qBAAqB,GACrB,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IA2HvC;;;;;;OAMG;IACU,kBAAkB,CAAC,EAC/B,KAAK,EACL,aAAa,GACb,EAAE,0BAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsB7D;;;;;;;;OAQG;IACU,oBAAoB,CAAC,EACjC,KAAK,EACL,aAAa,GACb,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAwB9D;;;;;OAKG;YACW,gBAAgB;YA4ChB,8BAA8B;CA6B5C"}

package/lib/node/titan/titanClient.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TitanClient = exports.SwapMode = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const msgpack_1 = require("@msgpack/msgpack");
+const routeInstructions_1 = require("../swap/routeInstructions");
+const types_1 = require("../swap/types");
 var SwapMode;
 (function (SwapMode) {
     SwapMode["ExactIn"] = "ExactIn";
@@ -13,8 +15,18 @@ const TITAN_API_URL = 'https://api.titan.exchange';
 const LOOKUP_TABLE_FETCH_RETRIES = 2;
 const LOOKUP_TABLE_RETRY_BASE_DELAY_MS = 150;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Titan sends pubkeys as raw bytes. Absent fields decode to `undefined`. */
+const decodePubkey = (bytes) => bytes ? new web3_js_1.PublicKey(bytes).toString() : undefined;
+/**
+ * For the normalized quote's small metadata fields, which are typed `number`.
+ * Only safe because slots, durations and bps are far below 2^53 — never use it
+ * on a token amount.
+ */
+const toNumber = (value) => value === undefined ? undefined : Number(value);
 class TitanClient {
     constructor({ connection, authToken, url, proxyUrl, }) {
+        this.providerName = 'titan';
+        this.lookupTableCache = new Map();
         this.connection = connection;
         this.authToken = authToken;
         this.url = url !== null && url !== void 0 ? url : TITAN_API_URL;
@@ -30,25 +42,41 @@ class TitanClient {
             outputMint: outputMint.toString(),
             amount: amount.toString(),
             userPublicKey: userPublicKey.toString(),
-            ...(slippageBps && { slippageBps: slippageBps.toString() }),
-            ...(swapMode && { swapMode: normalizedSwapMode.toString() }),
-            ...(maxAccounts && { accountsLimitTotal: maxAccounts.toString() }),
-            ...(excludeDexes && { excludeDexes: excludeDexes.join(',') }),
-            ...(onlyDirectRoutes && {
+            ...(slippageBps != null && { slippageBps: slippageBps.toString() }),
+            ...(swapMode != null && { swapMode: normalizedSwapMode.toString() }),
+            ...(maxAccounts != null && {
+                accountsLimitTotal: maxAccounts.toString(),
+            }),
+            ...(excludeDexes != null && { excludeDexes: excludeDexes.join(',') }),
+            // Only sent when explicitly true — Titan treats the field's presence,
+            // not its value, as the toggle.
+            ...(onlyDirectRoutes === true && {
                 onlyDirectRoutes: onlyDirectRoutes.toString(),
             }),
-            ...(sizeConstraint && { sizeConstraint: sizeConstraint.toString() }),
-            ...(accountsLimitWritable && {
+            ...(sizeConstraint != null && {
+                sizeConstraint: sizeConstraint.toString(),
+            }),
+            ...(accountsLimitWritable != null && {
                 accountsLimitWritable: accountsLimitWritable.toString(),
             }),
         });
     }
     /**
-     * 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.
      */
-    async getQuote({ inputMint, outputMint, amount, userPublicKey, maxAccounts = 50, // 50 is an estimated amount with buffer
-    slippageBps, swapMode, onlyDirectRoutes, excludeDexes, sizeConstraint, accountsLimitWritable, }) {
-        var _a;
+    async getQuote({ inputMint, outputMint, amount, userPublicKey, maxAccounts = types_1.DEFAULT_SWAP_MAX_ACCOUNTS, slippageBps, swapMode, onlyDirectRoutes, excludeDexes, sizeConstraint, accountsLimitWritable, }) {
+        var _a, _b, _c, _d, _e;
+        if (!userPublicKey) {
+            throw new Error('Titan quotes require a userPublicKey.');
+        }
         const params = this.buildParams({
             inputMint,
             outputMint,
@@ -87,29 +115,43 @@ class TitanClient {
             throw new Error(`Titan API error: ${response.status} ${response.statusText}`);
         }
         const buffer = await response.arrayBuffer();
-        const data = (0, msgpack_1.decode)(buffer);
-        // Cache the quote data and parameters for later use in getSwap
-        this.lastQuoteData = data;
-        this.lastQuoteParams = params.toString();
+        // `useBigInt64` or every u64 above 2^53 is silently rounded on the way in,
+        // including the `inAmount` callers size `beginSwap` off.
+        const data = (0, msgpack_1.decode)(buffer, { useBigInt64: true });
         // We are only querying for the best avaiable route so use that
         const route = data.quotes[Object.keys(data.quotes)[0]];
         if (!route) {
             throw new Error('No routes available');
         }
-        return {
-            inputMint: inputMint.toString(),
-            inAmount: amount.toString(),
-            outputMint: outputMint.toString(),
+        if (!((_a = route.instructions) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw new Error('Titan route has no instructions');
+        }
+        // Titan echoes the pair it routed. Take the pair from the response rather
+        // than assuming the request was honoured — a route for another pair pays
+        // out into a token account `endSwap` isn't watching, and only fails
+        // on-chain once the funds have already moved.
+        const routedInputMint = (_b = decodePubkey(data.inputMint)) !== null && _b !== void 0 ? _b : inputMint.toString();
+        const routedOutputMint = (_c = decodePubkey(data.outputMint)) !== null && _c !== void 0 ? _c : outputMint.toString();
+        if (routedInputMint !== inputMint.toString() ||
+            routedOutputMint !== outputMint.toString()) {
+            throw new Error(`Titan quoted ${routedInputMint} -> ${routedOutputMint} but the swap asked for ${inputMint.toString()} -> ${outputMint.toString()}.`);
+        }
+        return (0, types_1.buildSwapQuote)({
+            inputMint: routedInputMint,
+            outputMint: routedOutputMint,
+            // The route's own input, not the requested amount — under ExactOut the
+            // request is the output, and callers size `beginSwap` off `inAmount`.
+            inAmount: ((_d = route.inAmount) !== null && _d !== void 0 ? _d : amount).toString(),
             outAmount: route.outAmount.toString(),
             swapMode: data.swapMode,
-            slippageBps: route.slippageBps,
+            slippageBps: Number(route.slippageBps),
             platformFee: route.platformFee
                 ? {
                     amount: route.platformFee.amount.toString(),
-                    feeBps: route.platformFee.fee_bps,
+                    feeBps: Number(route.platformFee.fee_bps),
                 }
                 : undefined,
-            routePlan: ((_a = route.steps) === null || _a === void 0 ? void 0 : _a.map((step) => {
+            routePlan: ((_e = route.steps) === null || _e === void 0 ? void 0 : _e.map((step) => {
                 var _a;
                 return ({
                     swapInfo: {
@@ -120,85 +162,81 @@ class TitanClient {
                         inAmount: step.inAmount.toString(),
                         outAmount: step.outAmount.toString(),
                         feeAmount: ((_a = step.feeAmount) === null || _a === void 0 ? void 0 : _a.toString()) || '0',
-                        feeMint: step.feeMint ? new web3_js_1.PublicKey(step.feeMint).toString() : '',
+                        feeMint: step.feeMint
+                            ? new web3_js_1.PublicKey(step.feeMint).toString()
+                            : '',
                     },
                     percent: 100,
                 });
             })) || [],
-            contextSlot: route.contextSlot,
-            timeTaken: route.timeTaken,
-        };
+            contextSlot: toNumber(route.contextSlot),
+            timeTaken: toNumber(route.timeTaken),
+        }, { provider: 'titan', route, quotedFor: userPublicKey.toString() });
     }
     /**
-     * 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.
      */
-    async getSwap({ userPublicKey, }) {
-        // Check if we have cached quote data that matches the current parameters
-        if (!this.lastQuoteData) {
-            throw new Error('No matching quote data found. Please get a fresh quote before attempting to swap.');
-        }
-        // Reuse the cached quote data
-        const data = this.lastQuoteData;
-        // We are only querying for the best avaiable route so use that
-        const route = data.quotes[Object.keys(data.quotes)[0]];
-        if (!route) {
-            throw new Error('No routes available');
-        }
-        if (route.instructions && route.instructions.length > 0) {
-            // Errors propagate as-is. Replacing them with generic copy here loses
-            // the reason the swap can't be built — an unresolvable lookup table,
-            // say — which the caller needs to decide whether re-quoting will help.
-            try {
-                const { transactionMessage, lookupTables } = await this.getTransactionMessageAndLookupTables(route, userPublicKey);
-                return { transactionMessage, lookupTables };
-            }
-            finally {
-                // Clear cached quote data after use
-                this.lastQuoteData = undefined;
-                this.lastQuoteParams = undefined;
-            }
+    async getSwapTransaction({ quote, userPublicKey, }) {
+        var _a;
+        const route = (0, types_1.expectProviderRoute)(quote, 'titan', userPublicKey)
+            .route;
+        if (!((_a = route.instructions) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw new Error('No instructions provided in the route');
         }
-        throw new Error('No instructions provided in the route');
+        const [{ instructions, lookupTables }, { blockhash }] = await Promise.all([
+            this.getInstructionsAndLookupTables(route),
+            this.connection.getLatestBlockhash(),
+        ]);
+        return new web3_js_1.VersionedTransaction(new web3_js_1.TransactionMessage({
+            payerKey: userPublicKey,
+            recentBlockhash: blockhash,
+            instructions,
+        }).compileToV0Message(lookupTables));
     }
     /**
-     * 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, }) {
-        // Filter out common system instructions that can be handled by VelocityClient
-        const filteredInstructions = transactionMessage.instructions.filter((instruction) => {
-            const programId = instruction.programId.toString();
-            // Filter out system programs
-            if (programId === 'ComputeBudget111111111111111111111111111111') {
-                return false;
-            }
-            if (programId === 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA') {
-                return false;
-            }
-            if (programId === '11111111111111111111111111111111') {
-                return false;
-            }
-            // Filter out Associated Token Account creation for input/output mints
-            if (programId === 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL') {
-                if (instruction.keys.length > 3) {
-                    const mint = instruction.keys[3].pubkey;
-                    if (mint.equals(inputMint) || mint.equals(outputMint)) {
-                        return false;
-                    }
-                }
-            }
-            return true;
-        });
-        return filteredInstructions;
+    async getRouteInstructions({ quote, userPublicKey, }) {
+        var _a;
+        const route = (0, types_1.expectProviderRoute)(quote, 'titan', userPublicKey)
+            .route;
+        if (!((_a = route.instructions) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw new Error('No instructions provided in the route');
+        }
+        // Errors propagate as-is. Replacing them with generic copy here loses
+        // the reason the swap can't be built — an unresolvable lookup table,
+        // say — which the caller needs to decide whether re-quoting will help.
+        const { instructions, lookupTables } = await this.getInstructionsAndLookupTables(route);
+        return {
+            instructions: (0, routeInstructions_1.filterRouteInstructions)({
+                instructions,
+                inputMint: new web3_js_1.PublicKey(quote.inputMint),
+                outputMint: new web3_js_1.PublicKey(quote.outputMint),
+            }),
+            lookupTables,
+        };
     }
     /**
      * 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.
      */
     async fetchLookupTable(altPubkey) {
+        const cached = this.lookupTableCache.get(altPubkey.toString());
+        if (cached !== undefined) {
+            return cached;
+        }
         let lastError;
         for (let attempt = 0; attempt <= LOOKUP_TABLE_FETCH_RETRIES; attempt++) {
             if (attempt > 0) {
@@ -214,6 +252,7 @@ class TitanClient {
                 continue;
             }
             if (altAccount.value) {
+                this.lookupTableCache.set(altPubkey.toString(), altAccount.value);
                 return altAccount.value;
             }
             // A successful response with no value means the route references a
@@ -222,8 +261,9 @@ class TitanClient {
         }
         throw new Error(`Failed to fetch address lookup table ${altPubkey.toString()}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
     }
-    async getTransactionMessageAndLookupTables(route, userPublicKey) {
-        const solanaInstructions = route.instructions.map((instruction) => ({
+    async getInstructionsAndLookupTables(route) {
+        var _a;
+        const instructions = route.instructions.map((instruction) => ({
             programId: new web3_js_1.PublicKey(instruction.p),
             keys: instruction.a.map((meta) => ({
                 pubkey: new web3_js_1.PublicKey(meta.p),
@@ -232,27 +272,13 @@ class TitanClient {
             })),
             data: Buffer.from(instruction.d),
         }));
-        // Get recent blockhash
-        const { blockhash } = await this.connection.getLatestBlockhash();
-        // Build address lookup tables if provided.
-        //
         // These all have to resolve. A table that fails to load isn't a slightly
         // worse route — every account it would have compressed to a 1-byte index
         // gets inlined as a 32-byte pubkey instead, which pushes the transaction
         // past the size limit and only surfaces later as an opaque
         // "encoding overruns Uint8Array". Failing here lets the caller re-quote.
-        const addressLookupTables = [];
-        if (route.addressLookupTables && route.addressLookupTables.length > 0) {
-            for (const altPubkey of route.addressLookupTables) {
-                addressLookupTables.push(await this.fetchLookupTable(new web3_js_1.PublicKey(altPubkey)));
-            }
-        }
-        const transactionMessage = new web3_js_1.TransactionMessage({
-            payerKey: userPublicKey,
-            recentBlockhash: blockhash,
-            instructions: solanaInstructions,
-        });
-        return { transactionMessage, lookupTables: addressLookupTables };
+        const lookupTables = await Promise.all(((_a = route.addressLookupTables) !== null && _a !== void 0 ? _a : []).map((altPubkey) => this.fetchLookupTable(new web3_js_1.PublicKey(altPubkey))));
+        return { instructions, lookupTables };
     }
 }
 exports.TitanClient = TitanClient;

package/lib/node/user.d.ts

@@ -410,14 +410,15 @@ export declare class User {
      */
     getTotalCollateral(marginCategory?: MarginCategory, strict?: boolean, includeOpenOrders?: boolean, liquidationBuffer?: BN, perpMarketIndex?: number): BN;
     /**
-     * True when the account has an admin-set `equityFloor` and its cross-margin
-     * total collateral is below it. This is the trip threshold of the
-     * permissionless `tripEquityFloorBreaker`; action gating happens at
-     * `equityFloor + equityFloorBuffer` (see `isBelowBufferedEquityFloor`).
-     * Mirrors `User::is_below_equity_floor` on-chain.
-     * @param strict Use TWAP-bounded oracle pricing, matching the withdraw path. Defaults to false.
+     * True when the account has an admin-set `equityFloor` and its net equity
+     * (`getNetUsdValue`: unweighted assets and perp PnL minus unweighted spot
+     * liabilities, at live oracle prices) is below it. This is the trip
+     * threshold of the permissionless `tripEquityFloorBreaker`; action gating
+     * happens at `equityFloor + equityFloorBuffer` (see
+     * `isBelowBufferedEquityFloor`). Mirrors `User::is_below_equity_floor`
+     * onchain.
      */
-    isBelowEquityFloor(strict?: boolean): boolean;
+    isBelowEquityFloor(): boolean;
     /**
      * The equity required by risk-increasing actions:
      * `equityFloor + equityFloorBuffer` (QUOTE_PRECISION). Mirrors
@@ -426,31 +427,28 @@ export declare class User {
      */
     getBufferedEquityFloor(): BN;
     /**
-     * True when the account has an admin-set `equityFloor` and its cross-margin
-     * total collateral is below `equityFloor + equityFloorBuffer`. While below,
-     * the program rejects risk-increasing order placement and fills,
+     * True when the account has an admin-set `equityFloor` and its net equity
+     * (`getNetUsdValue`) is below `equityFloor + equityFloorBuffer`. While
+     * below, the program rejects risk-increasing order placement and fills,
      * withdrawals, and transfers out of the account (`EquityBelowFloor`);
      * reduce-only activity stays allowed. Mirrors
      * `User::is_below_buffered_equity_floor` on-chain.
-     * @param strict Use TWAP-bounded oracle pricing, matching the withdraw path. Defaults to false.
      */
-    isBelowBufferedEquityFloor(strict?: boolean): boolean;
+    isBelowBufferedEquityFloor(): boolean;
     /**
-     * Cross-margin total collateral in excess of the admin-set `equityFloor`,
+     * Net equity (`getNetUsdValue`) in excess of the admin-set `equityFloor`,
      * floored at zero (QUOTE_PRECISION). Unbounded (`null`) when no floor is set.
      * This is headroom above the trip threshold; headroom above the level
      * risk-increasing actions must clear is `getEquityAboveBufferedFloor`.
-     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
      */
-    getEquityAboveFloor(strict?: boolean): BN | null;
+    getEquityAboveFloor(): BN | null;
     /**
-     * Cross-margin total collateral in excess of `equityFloor +
+     * Net equity (`getNetUsdValue`) in excess of `equityFloor +
      * equityFloorBuffer`, floored at zero (QUOTE_PRECISION). Unbounded
      * (`null`) when no floor is set. When this reaches zero, risk-increasing
      * actions start rejecting.
-     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
      */
-    getEquityAboveBufferedFloor(strict?: boolean): BN | null;
+    getEquityAboveBufferedFloor(): BN | null;
     /**
      * Builds the liquidation-buffer map to pass into margin calculations while
      * a liquidation is in progress: `'cross'` is set to the state account's