@velocity-exchange/sdk 0.8.0 → 0.10.0

package/lib/browser/titan/titanClient.js

@@ -3,14 +3,30 @@ 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";
     SwapMode["ExactOut"] = "ExactOut";
 })(SwapMode || (exports.SwapMode = SwapMode = {}));
 const TITAN_API_URL = 'https://api.titan.exchange';
+/** Retries for a route's lookup tables, which must all resolve for the tx to fit. */
+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;
@@ -26,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,
@@ -83,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: {
@@ -116,81 +162,108 @@ 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');
+    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');
         }
-        if (route.instructions && route.instructions.length > 0) {
-            try {
-                const { transactionMessage, lookupTables } = await this.getTransactionMessageAndLookupTables(route, userPublicKey);
-                return { transactionMessage, lookupTables };
-            }
-            catch (err) {
-                throw new Error('Something went wrong with creating the Titan swap transaction. Please try again.');
-            }
-            finally {
-                // Clear cached quote data after use
-                this.lastQuoteData = undefined;
-                this.lastQuoteParams = undefined;
-            }
+        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));
+    }
+    /**
+     * 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.
+     */
+    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');
         }
-        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,
+        };
     }
     /**
-     * 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
+     * Fetches a lookup table required by a route, retrying transient RPC
+     * 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.
      */
-    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;
+    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) {
+                await sleep(LOOKUP_TABLE_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
             }
-            if (programId === 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA') {
-                return false;
+            let altAccount;
+            try {
+                altAccount = await this.connection.getAddressLookupTable(altPubkey);
             }
-            if (programId === '11111111111111111111111111111111') {
-                return false;
+            catch (err) {
+                // Transient — rate limiting, connection reset. Worth another go.
+                lastError = err;
+                continue;
             }
-            // 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;
-                    }
-                }
+            if (altAccount.value) {
+                this.lookupTableCache.set(altPubkey.toString(), altAccount.value);
+                return altAccount.value;
             }
-            return true;
-        });
-        return filteredInstructions;
+            // A successful response with no value means the route references a
+            // table that isn't on-chain. Retrying won't conjure it up.
+            throw new Error(`Address lookup table ${altPubkey.toString()} does not exist`);
+        }
+        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),
@@ -199,29 +272,13 @@ class TitanClient {
             })),
             data: Buffer.from(instruction.d),
         }));
-        // Get recent blockhash
-        const { blockhash } = await this.connection.getLatestBlockhash();
-        // Build address lookup tables if provided
-        const addressLookupTables = [];
-        if (route.addressLookupTables && route.addressLookupTables.length > 0) {
-            for (const altPubkey of route.addressLookupTables) {
-                try {
-                    const altAccount = await this.connection.getAddressLookupTable(new web3_js_1.PublicKey(altPubkey));
-                    if (altAccount.value) {
-                        addressLookupTables.push(altAccount.value);
-                    }
-                }
-                catch (err) {
-                    console.warn(`Failed to fetch address lookup table:`, err);
-                }
-            }
-        }
-        const transactionMessage = new web3_js_1.TransactionMessage({
-            payerKey: userPublicKey,
-            recentBlockhash: blockhash,
-            instructions: solanaInstructions,
-        });
-        return { transactionMessage, lookupTables: addressLookupTables };
+        // 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 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/browser/types.d.ts

@@ -116,7 +116,9 @@ export declare enum UserStatus {
     BEING_LIQUIDATED = 1,
     BANKRUPT = 2,
     REDUCE_ONLY = 4,
-    ADVANCED_LP = 8
+    ADVANCED_LP = 8,
+    /** Owned by a Strategy Vault (authority is a vault PDA; equity prices vault shares). Revenue-share sweeps skip such Users so a builder/referral reward can't enter vault NAV. */
+    VAULT_OWNED = 32
 }
 /** Bitmask mirror of `UserAccount.specialUserStatus`. `VAMM_HEDGER` marks the account used by the protocol's own vAMM-hedging bot. */
 export declare enum SpecialUserStatus {
@@ -1697,8 +1699,10 @@ export type UserAccount = {
     poolId: number;
     /** bitmask, see `SpecialUserStatus` */
     specialUserStatus: number;
-    /** QUOTE_PRECISION (1e6); admin-set minimum cross-margin total collateral for risk-increasing orders, fills, withdrawals and transfers; 0 = disabled */
+    /** QUOTE_PRECISION (1e6); admin-set minimum cross-margin total collateral; below it the permissionless breaker can trip; 0 = disabled */
     equityFloor: BN;
+    /** QUOTE_PRECISION (1e6); extra headroom above `equityFloor` required by risk-increasing orders, fills, withdrawals and transfers; no effect while `equityFloor` is 0 */
+    equityFloorBuffer: BN;
 };
 /** A user's balance in one spot market. Decoded mirror of the on-chain `SpotPosition`. */
 export type SpotPosition = {

package/lib/browser/types.js

@@ -103,6 +103,8 @@ var UserStatus;
     UserStatus[UserStatus["REDUCE_ONLY"] = 4] = "REDUCE_ONLY";
     UserStatus[UserStatus["ADVANCED_LP"] = 8] = "ADVANCED_LP";
     // 16 reserved (was PROTECTED_MAKER)
+    /** Owned by a Strategy Vault (authority is a vault PDA; equity prices vault shares). Revenue-share sweeps skip such Users so a builder/referral reward can't enter vault NAV. */
+    UserStatus[UserStatus["VAULT_OWNED"] = 32] = "VAULT_OWNED";
 })(UserStatus || (exports.UserStatus = UserStatus = {}));
 /** Bitmask mirror of `UserAccount.specialUserStatus`. `VAMM_HEDGER` marks the account used by the protocol's own vAMM-hedging bot. */
 var SpecialUserStatus;

package/lib/browser/user.d.ts

@@ -362,24 +362,23 @@ export declare class User {
      * @param marginCategory `'Initial'` or `'Maintenance'` asset/liability weights; omit for unweighted (100%) values.
      * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) added to the liability weight side.
      * @param includeOpenOrders If false, ignores open bids/asks and only counts the current balance (faster, less conservative).
-     * @param strict Use the worse of live oracle price vs 5-minute TWAP. Defaults to false.
-     * @param now Unix timestamp (seconds) used for TWAP staleness when `strict` is set; defaults to current time.
+     * @param strict Use the worse of live oracle price vs the market's stored 5-minute TWAP. Defaults to false.
      * @returns `{ totalAssetValue, totalLiabilityValue }`, both QUOTE_PRECISION (1e6) and non-negative.
      */
-    getSpotMarketAssetAndLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean, now?: BN): {
+    getSpotMarketAssetAndLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean): {
         totalAssetValue: BN;
         totalLiabilityValue: BN;
     };
     /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalLiabilityValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6). */
-    getSpotMarketLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    getSpotMarketLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean): BN;
     /** Thin wrapper around the `math/spotBalance` `getSpotLiabilityValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), negative. */
     getSpotLiabilityValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, marginCategory?: MarginCategory, liquidationBuffer?: BN): BN;
     /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalAssetValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6), non-negative. */
-    getSpotMarketAssetValue(marketIndex?: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    getSpotMarketAssetValue(marketIndex?: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean): BN;
     /** Thin wrapper around the `math/spotBalance` `getSpotAssetValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), non-negative. */
     getSpotAssetValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, marginCategory?: MarginCategory): BN;
     /** Net spot value (`totalAssetValue - totalLiabilityValue`) for a single spot market. See `getSpotMarketAssetAndLiabilityValue` for parameter semantics. Returns QUOTE_PRECISION (1e6), can be negative. */
-    getSpotPositionValue(marketIndex: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    getSpotPositionValue(marketIndex: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean): BN;
     /**
      * Net spot value (`totalAssetValue - totalLiabilityValue`) across all spot
      * markets combined.
@@ -411,20 +410,45 @@ 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. While below the floor, 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_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;
     /**
-     * Cross-margin total collateral in excess of the admin-set `equityFloor`,
+     * The equity required by risk-increasing actions:
+     * `equityFloor + equityFloorBuffer` (QUOTE_PRECISION). Mirrors
+     * `User::buffered_equity_floor` on-chain. Meaningless while
+     * `equityFloor` is 0 (the checks are disabled).
+     */
+    getBufferedEquityFloor(): BN;
+    /**
+     * 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.
+     */
+    isBelowBufferedEquityFloor(): boolean;
+    /**
+     * Net equity (`getNetUsdValue`) in excess of the admin-set `equityFloor`,
      * floored at zero (QUOTE_PRECISION). Unbounded (`null`) when no floor is set.
-     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
+     * This is headroom above the trip threshold; headroom above the level
+     * risk-increasing actions must clear is `getEquityAboveBufferedFloor`.
+     */
+    getEquityAboveFloor(): BN | null;
+    /**
+     * 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.
      */
-    getEquityAboveFloor(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
@@ -768,7 +792,7 @@ export declare class User {
      * @param outMarketIndex
      * @param calculateSwap Optional function to simulate the in-to-out conversion (e.g. to model swap fees/slippage); defaults to a 1:1 oracle-price conversion.
      * @param iterationLimit How many binary-search iterations to run before erroring out. Defaults to 1000.
-     * @returns `inAmount`/`outAmount` in each market's own token decimals, and the resulting `leverage` (TEN_THOUSAND, 1e4 precision) after the swap.
+     * @returns `inAmount`/`outAmount` in each market's own token decimals, and the resulting `leverage` (TEN_THOUSAND, 1e4 precision) after the swap. Sizing is TWAP-bounded to match the program's margin check; `leverage` is marked at the live oracle price so it stays comparable to `getLeverage()`.
      */
     getMaxSwapAmount({ inMarketIndex, outMarketIndex, calculateSwap, iterationLimit, }: {
         inMarketIndex: number;
@@ -796,7 +820,8 @@ export declare class User {
         totalLiabilityValue: BN;
     };
     /**
-     * Estimates what the user leverage will be after swap
+     * Estimates what the user leverage will be after swap, marked at the live
+     * oracle price so it stays comparable to `getLeverage()`.
      * @param inMarketIndex Market being sold/paid from.
      * @param outMarketIndex Market being bought/received.
      * @param inAmount Amount removed from `inMarketIndex`, that market's own token decimals.