@velocity-exchange/sdk 0.7.0 → 0.9.0

package/lib/node/user.js

@@ -724,12 +724,10 @@ 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, marginCategory, liquidationBuffer, includeOpenOrders, strict = false, now) {
-        now = now || new anchor_1.BN(new Date().getTime() / 1000);
+    getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict = false) {
         let netQuoteValue = numericConstants_1.ZERO;
         let totalAssetValue = numericConstants_1.ZERO;
         let totalLiabilityValue = numericConstants_1.ZERO;
@@ -744,11 +742,11 @@ class User {
             }
             const spotMarketAccount = this.velocityClient.getSpotMarketAccountOrThrow(spotPosition.marketIndex);
             const oraclePriceData = this.getOracleDataForSpotMarket(spotPosition.marketIndex);
-            let twap5min;
-            if (strict) {
-                twap5min = (0, oracles_1.calculateLiveOracleTwap)(spotMarketAccount.historicalOracleData, oraclePriceData, now, numericConstants_1.FIVE_MINUTE // 5MIN
-                );
-            }
+            // mirrors margin.rs: strict mode prices against the market's *stored*
+            // 5min TWAP, not a live-projected one
+            const twap5min = strict
+                ? spotMarketAccount.historicalOracleData.lastOraclePriceTwap5Min
+                : undefined;
             const strictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(oraclePriceData.price, twap5min);
             if (spotPosition.marketIndex === numericConstants_1.QUOTE_SPOT_MARKET_INDEX &&
                 countForQuote) {
@@ -813,8 +811,8 @@ class User {
         return { totalAssetValue, totalLiabilityValue };
     }
     /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalLiabilityValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6). */
-    getSpotMarketLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict = false, now) {
-        const { totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict, now);
+    getSpotMarketLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict = false) {
+        const { totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict);
         return totalLiabilityValue;
     }
     /** Thin wrapper around the `math/spotBalance` `getSpotLiabilityValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), negative. */
@@ -822,8 +820,8 @@ class User {
         return (0, spotBalance_2.getSpotLiabilityValue)(tokenAmount, strictOraclePrice, spotMarketAccount, this.getUserAccountOrThrow().maxMarginRatio, marginCategory, liquidationBuffer);
     }
     /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalAssetValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6), non-negative. */
-    getSpotMarketAssetValue(marketIndex, marginCategory, includeOpenOrders, strict = false, now) {
-        const { totalAssetValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict, now);
+    getSpotMarketAssetValue(marketIndex, marginCategory, includeOpenOrders, strict = false) {
+        const { totalAssetValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict);
         return totalAssetValue;
     }
     /** Thin wrapper around the `math/spotBalance` `getSpotAssetValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), non-negative. */
@@ -831,8 +829,8 @@ class User {
         return (0, spotBalance_2.getSpotAssetValue)(tokenAmount, strictOraclePrice, spotMarketAccount, this.getUserAccountOrThrow().maxMarginRatio, marginCategory);
     }
     /** Net spot value (`totalAssetValue - totalLiabilityValue`) for a single spot market. See `getSpotMarketAssetAndLiabilityValue` for parameter semantics. Returns QUOTE_PRECISION (1e6), can be negative. */
-    getSpotPositionValue(marketIndex, marginCategory, includeOpenOrders, strict = false, now) {
-        const { totalAssetValue, totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict, now);
+    getSpotPositionValue(marketIndex, marginCategory, includeOpenOrders, strict = false) {
+        const { totalAssetValue, totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict);
         return totalAssetValue.sub(totalLiabilityValue);
     }
     /**
@@ -900,9 +898,9 @@ class User {
     }
     /**
      * 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.
+     * 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.
      */
@@ -913,9 +911,37 @@ class User {
         }
         return this.getTotalCollateral('Initial', strict).lt(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() {
+        const userAccount = this.getUserAccountOrThrow();
+        return userAccount.equityFloor.add(userAccount.equityFloorBuffer);
+    }
+    /**
+     * 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,
+     * 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 = false) {
+        const equityFloor = this.getUserAccountOrThrow().equityFloor;
+        if (equityFloor.lte(numericConstants_1.ZERO)) {
+            return false;
+        }
+        return this.getTotalCollateral('Initial', strict).lt(this.getBufferedEquityFloor());
+    }
     /**
      * Cross-margin total collateral 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 = false) {
@@ -925,6 +951,20 @@ class User {
         }
         return anchor_1.BN.max(this.getTotalCollateral('Initial', strict).sub(equityFloor), numericConstants_1.ZERO);
     }
+    /**
+     * Cross-margin total collateral 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 = false) {
+        const equityFloor = this.getUserAccountOrThrow().equityFloor;
+        if (equityFloor.lte(numericConstants_1.ZERO)) {
+            return null;
+        }
+        return anchor_1.BN.max(this.getTotalCollateral('Initial', strict).sub(this.getBufferedEquityFloor()), numericConstants_1.ZERO);
+    }
     /**
      * Builds the liquidation-buffer map to pass into margin calculations while
      * a liquidation is in progress: `'cross'` is set to the state account's
@@ -1979,7 +2019,7 @@ 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 = 1000, }) {
         const inMarket = this.velocityClient.getSpotMarketAccountOrThrow(inMarketIndex);
@@ -1988,8 +2028,14 @@ class User {
         const inOraclePrice = inOraclePriceData.price;
         const outOraclePriceData = this.getOracleDataForSpotMarket(outMarketIndex);
         const outOraclePrice = outOraclePriceData.price;
-        const inStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(inOraclePrice);
-        const outStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(outOraclePrice);
+        // sizing mirrors handle_end_swap: both legs are priced strictly, against
+        // each market's stored 5min TWAP
+        const inStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(inOraclePrice, inMarket.historicalOracleData.lastOraclePriceTwap5Min);
+        const outStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(outOraclePrice, outMarket.historicalOracleData.lastOraclePriceTwap5Min);
+        // the returned leverage is a delta on top of getLeverageComponents' live-oracle
+        // baseline, so pricing its legs strictly would mix two bases in one figure
+        const inLeveragePrice = new strictOraclePrice_1.StrictOraclePrice(inOraclePrice);
+        const outLeveragePrice = new strictOraclePrice_1.StrictOraclePrice(outOraclePrice);
         const inPrecision = new anchor_1.BN(10 ** inMarket.decimals);
         const outPrecision = new anchor_1.BN(10 ** outMarket.decimals);
         const inSpotPosition = this.getSpotPosition(inMarketIndex) ||
@@ -1998,9 +2044,9 @@ class User {
             this.getEmptySpotPosition(outMarketIndex);
         const freeCollateral = this.getFreeCollateral();
         const inContributionInitial = this.calculateSpotPositionFreeCollateralContribution(inSpotPosition, inStrictOraclePrice);
-        const { totalAssetValue: inTotalAssetValueInitial, totalLiabilityValue: inTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(inSpotPosition, inStrictOraclePrice);
+        const { totalAssetValue: inTotalAssetValueInitial, totalLiabilityValue: inTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(inSpotPosition, inLeveragePrice);
         const outContributionInitial = this.calculateSpotPositionFreeCollateralContribution(outSpotPosition, outStrictOraclePrice);
-        const { totalAssetValue: outTotalAssetValueInitial, totalLiabilityValue: outTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(outSpotPosition, outStrictOraclePrice);
+        const { totalAssetValue: outTotalAssetValueInitial, totalLiabilityValue: outTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(outSpotPosition, outLeveragePrice);
         const initialContribution = inContributionInitial.add(outContributionInitial);
         const { perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue } = this.getLeverageComponents();
         if (!calculateSwap) {
@@ -2063,8 +2109,8 @@ class User {
         }
         const inPositionAfter = this.cloneAndUpdateSpotPosition(inSpotPosition, inSwap.neg(), inMarket);
         const outPositionAfter = this.cloneAndUpdateSpotPosition(outSpotPosition, outSwap, outMarket);
-        const { totalAssetValue: inTotalAssetValueAfter, totalLiabilityValue: inTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(inPositionAfter, inStrictOraclePrice);
-        const { totalAssetValue: outTotalAssetValueAfter, totalLiabilityValue: outTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(outPositionAfter, outStrictOraclePrice);
+        const { totalAssetValue: inTotalAssetValueAfter, totalLiabilityValue: inTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(inPositionAfter, inLeveragePrice);
+        const { totalAssetValue: outTotalAssetValueAfter, totalLiabilityValue: outTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(outPositionAfter, outLeveragePrice);
         const spotAssetValueDelta = inTotalAssetValueAfter
             .add(outTotalAssetValueAfter)
             .sub(inTotalAssetValueInitial)
@@ -2147,7 +2193,8 @@ class User {
         };
     }
     /**
-     * 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.
@@ -2161,19 +2208,21 @@ class User {
         const inOraclePrice = inOraclePriceData.price;
         const outOraclePriceData = this.getOracleDataForSpotMarket(outMarketIndex);
         const outOraclePrice = outOraclePriceData.price;
-        const inStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(inOraclePrice);
-        const outStrictOraclePrice = new strictOraclePrice_1.StrictOraclePrice(outOraclePrice);
+        // same live-oracle basis as getMaxSwapAmount's leverage legs and as the
+        // getLeverageComponents baseline these deltas are applied to
+        const inLeveragePrice = new strictOraclePrice_1.StrictOraclePrice(inOraclePrice);
+        const outLeveragePrice = new strictOraclePrice_1.StrictOraclePrice(outOraclePrice);
         const inSpotPosition = this.getSpotPosition(inMarketIndex) ||
             this.getEmptySpotPosition(inMarketIndex);
         const outSpotPosition = this.getSpotPosition(outMarketIndex) ||
             this.getEmptySpotPosition(outMarketIndex);
-        const { totalAssetValue: inTotalAssetValueInitial, totalLiabilityValue: inTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(inSpotPosition, inStrictOraclePrice);
-        const { totalAssetValue: outTotalAssetValueInitial, totalLiabilityValue: outTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(outSpotPosition, outStrictOraclePrice);
+        const { totalAssetValue: inTotalAssetValueInitial, totalLiabilityValue: inTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(inSpotPosition, inLeveragePrice);
+        const { totalAssetValue: outTotalAssetValueInitial, totalLiabilityValue: outTotalLiabilityValueInitial, } = this.calculateSpotPositionLeverageContribution(outSpotPosition, outLeveragePrice);
         const { perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue } = this.getLeverageComponents();
         const inPositionAfter = this.cloneAndUpdateSpotPosition(inSpotPosition, inAmount.abs().neg(), inMarket);
         const outPositionAfter = this.cloneAndUpdateSpotPosition(outSpotPosition, outAmount.abs(), outMarket);
-        const { totalAssetValue: inTotalAssetValueAfter, totalLiabilityValue: inTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(inPositionAfter, inStrictOraclePrice);
-        const { totalAssetValue: outTotalAssetValueAfter, totalLiabilityValue: outTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(outPositionAfter, outStrictOraclePrice);
+        const { totalAssetValue: inTotalAssetValueAfter, totalLiabilityValue: inTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(inPositionAfter, inLeveragePrice);
+        const { totalAssetValue: outTotalAssetValueAfter, totalLiabilityValue: outTotalLiabilityValueAfter, } = this.calculateSpotPositionLeverageContribution(outPositionAfter, outLeveragePrice);
         const spotAssetValueDelta = inTotalAssetValueAfter
             .add(outTotalAssetValueAfter)
             .sub(inTotalAssetValueInitial)
@@ -2921,8 +2970,10 @@ class User {
                 skipTokenValue = true;
             }
             const oraclePriceData = this.getOracleDataForSpotMarket(spotPosition.marketIndex);
+            // mirrors margin.rs: strict mode prices against the market's *stored*
+            // 5min TWAP, not a live-projected one
             const twap5 = strict
-                ? (0, oracles_1.calculateLiveOracleTwap)(spotMarket.historicalOracleData, oraclePriceData, new anchor_1.BN(Math.floor(Date.now() / 1000)), numericConstants_1.FIVE_MINUTE)
+                ? spotMarket.historicalOracleData.lastOraclePriceTwap5Min
                 : undefined;
             const strictOracle = new strictOraclePrice_1.StrictOraclePrice(oraclePriceData.price, twap5);
             if (isQuote) {

package/lib/node/velocityClient.d.ts

@@ -433,25 +433,24 @@ export declare class VelocityClient {
         externalWallet?: PublicKey;
     }): Promise<[PublicKey, TransactionInstruction]>;
     /**
-     * Grows an existing `SignedMsgUserOrders` account to hold more order-message slots. The program
-     * only allows growing, never shrinking.
+     * Resizes an existing `SignedMsgUserOrders` account. Growing (adding order-message slots) is
+     * permitted for any payer; shrinking is only permitted when the payer is the account's
+     * `authority`, because the account is authority-scoped and shared across all of the authority's
+     * subaccounts — a shrink evicts replay-protection UUIDs for every subaccount.
      * @param authority - Authority whose account is resized.
-     * @param numOrders - New (larger) number of order-message slots.
-     * @param userSubaccountId - Sub-account id used to derive the `user` account passed to the
-     * instruction; defaults to `0`.
+     * @param numOrders - New number of order-message slots.
      * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
      * @returns The transaction signature.
      */
-    resizeSignedMsgUserOrders(authority: PublicKey, numOrders: number, userSubaccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    resizeSignedMsgUserOrders(authority: PublicKey, numOrders: number, txParams?: TxParams): Promise<TransactionSignature>;
     /**
      * Builds the `resizeSignedMsgUserOrders` instruction. See `resizeSignedMsgUserOrders` for
      * semantics.
      * @param authority - Authority whose account is resized.
-     * @param numOrders - New (larger) number of order-message slots.
-     * @param userSubaccountId - Sub-account id used to derive the `user` account; defaults to `0`.
+     * @param numOrders - New number of order-message slots.
      * @returns The resize instruction.
      */
-    getResizeSignedMsgUserOrdersInstruction(authority: PublicKey, numOrders: number, userSubaccountId?: number): Promise<TransactionInstruction>;
+    getResizeSignedMsgUserOrdersInstruction(authority: PublicKey, numOrders: number): Promise<TransactionInstruction>;
     /**
      * Initializes `authority`'s `SignedMsgWsDelegates` account, which lists wallets authorized to
      * co-sign/relay that authority's signed-message ("swift") orders over a websocket connection
@@ -1574,14 +1573,17 @@ export declare class VelocityClient {
      * @param fromSubAccountId - Sub-account id to debit.
      * @param toSubAccountId - Sub-account id to credit.
      * @param equityFloorDelta - Equity floor (QUOTE_PRECISION) to move from the debited to the credited
-     * sub-account along with the funds, keeping the sum of floors constant. The debited side must stay
-     * at/above its reduced floor and the credited side's collateral (after the transfer lands) must back
-     * its increased floor, else the transfer reverts with `InvalidEquityFloorTransfer`. Pass `'auto'`
+     * sub-account along with the funds, keeping the sum of floors constant. The debited side must not
+     * already be below the floor being reduced (a below-floor sub-account cannot shed floor to defuse a
+     * pending equity-breaker trip), must stay at/above its reduced floor plus its `equityFloorBuffer`,
+     * and the credited side's collateral (after the transfer lands) must back its increased floor plus
+     * its own buffer, else the transfer reverts with `InvalidEquityFloorTransfer`. Pass `'auto'`
      * (quote market only) to move the minimal floor needed for the debited side to stay at/above its
-     * floor: `max(0, amount - (collateral - floor))`, capped at the debited side's floor. The auto delta
-     * never exceeds `amount`, so the credited side stays backed whenever it was before. Client-side
-     * pricing can differ slightly from the on-chain strict check at the exact boundary; retry with an
-     * explicit padded delta if an `'auto'` transfer reverts. Defaults to zero.
+     * buffered floor: `max(0, amount - max(0, collateral - (floor + buffer)))`, capped at the debited
+     * side's floor (see `calculateEquityFloorAutoDelta`). The auto delta never exceeds `amount`, so the
+     * credited side stays backed whenever it was before. Client-side pricing can differ slightly from
+     * the on-chain strict check at the exact boundary; retry with an explicit padded delta if an
+     * `'auto'` transfer reverts. Defaults to zero.
      * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
      * @returns The transaction signature.
      * @throws (on-chain) if `allowDelegateTransfer` is not enabled, if the signer is not the delegate on
@@ -3220,7 +3222,8 @@ export declare class VelocityClient {
      * position to the calling liquidator's sub-account at the oracle price (subject to `limitPrice`
      * and the on-chain liquidation fee). Reverts if `userAccountPublicKey` equals the liquidator's
      * own user account. Permissionless — any signer can act as liquidator, taking on the position
-     * and its PnL themselves.
+     * and its PnL themselves. Reverts with `EquityBelowFloor` if the liquidator's authority-wide
+     * equity breaker is tripped (a tripped authority is barred from position-acquiring liquidations).
      * @param userAccountPublicKey - Public key of the user account being liquidated.
      * @param userAccount - Decoded user account being liquidated.
      * @param marketIndex - Perp market index of the position to liquidate.
@@ -3272,7 +3275,9 @@ export declare class VelocityClient {
      * debt from the user to the liquidator's own sub-account in exchange for `assetMarketIndex`
      * collateral, when the user is below maintenance margin (or already flagged `beingLiquidated`).
      * Reverts if `userAccountPublicKey` equals the liquidator's own user account. Permissionless —
-     * any signer can act as liquidator.
+     * any signer can act as liquidator. Reverts with `EquityBelowFloor` if the liquidator's
+     * authority-wide equity breaker is tripped (a tripped authority is barred from position-acquiring
+     * liquidations).
      * @param userAccountPublicKey - Public key of the user account being liquidated.
      * @param userAccount - Decoded user account being liquidated.
      * @param assetMarketIndex - Spot market index of the collateral the liquidator receives.
@@ -3381,7 +3386,9 @@ export declare class VelocityClient {
      * PnL in `perpMarketIndex`. Only usable once the user's position size in `perpMarketIndex` is
      * zero (the PnL must already be fully unrealized/settled-out, not backed by an open position).
      * Reverts if `userAccountPublicKey` equals the liquidator's own user account. Permissionless —
-     * any signer can act as liquidator.
+     * any signer can act as liquidator. Reverts with `EquityBelowFloor` if the liquidator's
+     * authority-wide equity breaker is tripped (a tripped authority is barred from
+     * balance-acquiring liquidations).
      * @param userAccountPublicKey - Public key of the user account being liquidated.
      * @param userAccount - Decoded user account being liquidated.
      * @param perpMarketIndex - Perp market index whose unsettled PnL backs the transfer, QUOTE_PRECISION (1e6).
@@ -3412,7 +3419,9 @@ export declare class VelocityClient {
      * `perpMarketIndex` from the user to the liquidator in exchange for `assetMarketIndex` spot
      * collateral (the inverse of `liquidateBorrowForPerpPnl`). Only usable once the user's position
      * size in `perpMarketIndex` is zero. Reverts if `userAccountPublicKey` equals the liquidator's
-     * own user account. Permissionless — any signer can act as liquidator.
+     * own user account. Permissionless — any signer can act as liquidator. Reverts with
+     * `EquityBelowFloor` if the liquidator's authority-wide equity breaker is tripped (a tripped
+     * authority is barred from balance-acquiring liquidations).
      * @param userAccountPublicKey - Public key of the user account being liquidated.
      * @param userAccount - Decoded user account being liquidated.
      * @param perpMarketIndex - Perp market index of the negative unsettled PnL being absorbed.
@@ -3693,8 +3702,10 @@ export declare class VelocityClient {
     }): Promise<TransactionInstruction[]>;
     /**
      * Starts the unstaking cooldown for this wallet's insurance fund stake in `marketIndex`, locking
-     * in the number of IF shares corresponding to `amount` at the current share price. The actual
-     * withdrawal must be completed with `removeInsuranceFundStake` after
+     * in the number of IF shares corresponding to `amount` at the current share price. Any revenue
+     * already due to the insurance fund is settled first (mirroring `addInsuranceFundStake`), so the
+     * frozen exit value includes the staker's share of it rather than forfeiting it to the remaining
+     * stakers. The actual withdrawal must be completed with `removeInsuranceFundStake` after
      * `spotMarket.insuranceFund.unstakingPeriod` seconds have elapsed; only one request may be
      * in-flight per stake account (`cancelRequestRemoveInsuranceFundStake` to reset). A caller may
      * only act on their own stake account.
@@ -3770,8 +3781,10 @@ export declare class VelocityClient {
      * `pendingAmmProvision` into the AMM's fee pool (both leave `feePoolBufferTarget` behind). Every
      * drain reserves `max(netUserPnl, 0)` so user claims stay backed. This runs inline on every
      * `settlePNL` already — this instruction lets a keeper run it on demand without settling anyone's
-     * PnL. Gates the oracle price used to value `netUserPnl` the same way `settlePNL` does (price-band
-     * + validity/divergence checks when the market has curve updates enabled).
+     * PnL. Values `netUserPnl` at the market's fixed `expiryPrice` when the market is in `settlement`
+     * status (expired positions settle at that price, not the live oracle, so no live-oracle gate is
+     * applied); otherwise it uses the live oracle price and gates it the same way `settlePNL` does
+     * (price-band + validity/divergence checks when the market has curve updates enabled).
      * @param perpMarketIndex - Perp market index to sweep fees for.
      * @param txParams - Optional compute-unit/priority-fee overrides.
      * @returns The transaction signature.