@velocity-exchange/sdk 0.9.0 → 0.10.0

package/lib/browser/user.js

@@ -897,19 +897,20 @@ class User {
         return marginCalc.totalCollateral;
     }
     /**
-     * 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.
-     */
-    isBelowEquityFloor(strict = 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() {
         const equityFloor = this.getUserAccountOrThrow().equityFloor;
         if (equityFloor.lte(numericConstants_1.ZERO)) {
             return false;
         }
-        return this.getTotalCollateral('Initial', strict).lt(equityFloor);
+        return this.getNetUsdValue().lt(equityFloor);
     }
     /**
      * The equity required by risk-increasing actions:
@@ -922,48 +923,45 @@ class User {
         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,
+     * 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 = false) {
+    isBelowBufferedEquityFloor() {
         const equityFloor = this.getUserAccountOrThrow().equityFloor;
         if (equityFloor.lte(numericConstants_1.ZERO)) {
             return false;
         }
-        return this.getTotalCollateral('Initial', strict).lt(this.getBufferedEquityFloor());
+        return this.getNetUsdValue().lt(this.getBufferedEquityFloor());
     }
     /**
-     * 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 = false) {
+    getEquityAboveFloor() {
         const equityFloor = this.getUserAccountOrThrow().equityFloor;
         if (equityFloor.lte(numericConstants_1.ZERO)) {
             return null;
         }
-        return anchor_1.BN.max(this.getTotalCollateral('Initial', strict).sub(equityFloor), numericConstants_1.ZERO);
+        return anchor_1.BN.max(this.getNetUsdValue().sub(equityFloor), numericConstants_1.ZERO);
     }
     /**
-     * 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 = false) {
+    getEquityAboveBufferedFloor() {
         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);
+        return anchor_1.BN.max(this.getNetUsdValue().sub(this.getBufferedEquityFloor()), numericConstants_1.ZERO);
     }
     /**
      * Builds the liquidation-buffer map to pass into margin calculations while
@@ -2429,9 +2427,9 @@ class User {
         const spotMarket = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         // eslint-disable-next-line prefer-const
         let { borrowLimit, withdrawLimit } = (0, spotBalance_2.calculateWithdrawLimit)(spotMarket, nowTs);
-        // the withdraw path enforces the equity floor on post-withdraw total
-        // collateral, so equity above the floor caps free collateral here
-        const equityAboveFloor = this.getEquityAboveFloor(true);
+        // the withdraw path enforces the equity floor on post-withdraw net
+        // equity, so equity above the floor caps free collateral here
+        const equityAboveFloor = this.getEquityAboveFloor();
         if (equityAboveFloor !== null && equityAboveFloor.eq(numericConstants_1.ZERO)) {
             return numericConstants_1.ZERO;
         }

package/lib/browser/velocityClient.d.ts

@@ -30,8 +30,8 @@ import { User } from './user';
 import { UserSubscriptionConfig } from './userConfig';
 import { VelocityEnv, VelocityProgram } from './config';
 import { UserStats } from './userStats';
-import { JupiterClient, QuoteResponse } from './jupiter/jupiterClient';
-import { SwapMode, UnifiedQuoteResponse } from './swap/UnifiedSwapClient';
+import { JupiterClient, JupiterSwapQuote } from './jupiter/jupiterClient';
+import { SwapMode, SwapProvider, SwapQuote } from './swap/types';
 import { UserStatsSubscriptionConfig } from './userStatsConfig';
 import { TxHandler } from './tx/txHandler';
 import { SignedMsgOrderParams } from './types';
@@ -39,7 +39,6 @@ import { TakerInfo } from './types';
 import { ConstituentMap } from './constituentMap/constituentMap';
 import { RevenueShareEscrowMap } from './userMap/revenueShareEscrowMap';
 import { TitanClient } from './titan/titanClient';
-import { UnifiedSwapClient } from './swap/UnifiedSwapClient';
 /**
  * Union type for swap clients (Titan and Jupiter) - Legacy type
  * @deprecated Use UnifiedSwapClient class instead
@@ -1573,16 +1572,19 @@ 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 not
+     * sub-account along with the funds, keeping the sum of floors constant. A proportional share of
+     * the debited side's `equityFloorBuffer` travels with the floor (rounded up on the debited side,
+     * so shedding the whole floor also sheds the whole buffer; no orphan buffer is left on a
+     * check-disabled sub-account), keeping the sum of buffers constant too. 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'`
+     * pending equity-breaker trip), must stay at/above its reduced floor plus its reduced buffer,
+     * and the credited side's net equity (after the transfer lands) must back its increased floor plus
+     * its increased 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
-     * buffered floor: `max(0, amount - max(0, collateral - (floor + buffer)))`, capped at the debited
+     * buffered floor: `max(0, amount - max(0, netEquity - (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
+     * the onchain 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.
@@ -2305,34 +2307,32 @@ export declare class VelocityClient {
      * instructions in a single transaction, so the swap is settled directly against the user's
      * deposits/vault balances rather than the wallet's own token accounts. Sends and confirms the
      * transaction.
-     * @param swapClient - Swap client used to fetch routes/instructions (`UnifiedSwapClient` or a
-     * `TitanClient`); dispatches to `getSwapIxV2` or `getTitanSwapIx` respectively.
-     * @param jupiterClient - @deprecated Use `swapClient` instead. When passed (and `swapClient` is
-     * not), dispatches to `getJupiterSwapIxV6`.
+     * @param swapClient - Provider used to quote the swap and build its route: a
+     * `UnifiedSwapClient`, or a `TitanClient`/`JupiterClient` directly. See `getProviderSwapIx`.
+     * @param jupiterClient - @deprecated Use `swapClient` instead. Used only when `swapClient` is
+     * not passed.
      * @param outMarketIndex - Spot market index of the token being bought.
      * @param inMarketIndex - Spot market index of the token being sold.
      * @param outAssociatedTokenAccount - Token account to receive the bought token; created
      * idempotently if omitted.
      * @param inAssociatedTokenAccount - Token account to source the sold token from; created
      * idempotently if omitted.
-     * @param amount - Amount of the "in" token (or "out" token when `swapMode` is `ExactOut`, in
-     * which case this is the desired output amount), in the token's own mint decimals — not a
-     * fixed protocol precision.
+     * @param amount - Amount of the "in" token (or "out" token when the effective mode is
+     * `ExactOut`, in which case this is the desired output amount), in the token's own mint
+     * decimals — not a fixed protocol precision.
      * @param slippageBps - Max slippage in basis points passed to the swap provider's routing API.
-     * @param swapMode - `ExactIn` (default) or `ExactOut`.
+     * @param swapMode - `ExactIn` (default) or `ExactOut`. Ignored when `quote` is passed — the
+     * quote's own mode wins.
      * @param reduceOnly - Whether the in/out token's position on the velocity account must reduce
      * (not flip sign); enforced by `endSwap` after the swap completes.
-     * @param v6 - @deprecated Use `quote` instead. Pre-fetched Jupiter v6 quote response.
-     * @param quote - Pre-fetched quote response (skips an extra round-trip to the swap provider).
+     * @param quote - Pre-fetched quote (skips an extra round-trip to the swap provider). Must be
+     * for this pair and this `amount`.
      * @param txParams - Optional compute-unit/priority-fee overrides.
-     * @throws If neither `swapClient` nor `jupiterClient` is provided, or if `swapClient` is not a
-     * recognized client type.
+     * @throws If neither `swapClient` nor `jupiterClient` is provided.
      * @returns The transaction signature.
      */
-    swap({ swapClient, jupiterClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, reduceOnly, txParams, v6, quote, onlyDirectRoutes, }: {
-        swapClient?: UnifiedSwapClient | SwapClient;
-        /** @deprecated Use swapClient instead. Legacy parameter for backward compatibility */
-        jupiterClient?: JupiterClient;
+    swap({ swapClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, reduceOnly, txParams, quote, onlyDirectRoutes, }: {
+        swapClient?: SwapProvider;
         outMarketIndex: number;
         inMarketIndex: number;
         outAssociatedTokenAccount?: PublicKey;
@@ -2343,49 +2343,59 @@ export declare class VelocityClient {
         reduceOnly?: SwapReduceOnly;
         txParams?: TxParams;
         onlyDirectRoutes?: boolean;
-        v6?: {
-            quote?: QuoteResponse;
-        };
-        quote?: UnifiedQuoteResponse;
+        quote?: SwapQuote;
     }): Promise<TransactionSignature>;
     /**
-     * Builds the instruction list for a Titan-routed swap: creates any missing associated token
-     * accounts, wraps Titan's routing instructions between `beginSwap`/`endSwap`. See `swap` for
-     * parameter semantics; `amount` is in the "in" token's mint decimals.
-     * @param userAccountPublicKey - Optional user account override (e.g. when the account is being
-     * created in the same transaction and not yet resolvable via `getUserAccountPublicKey`).
-     * @returns `ixs` — instruction list (ATA creation, `beginSwap`, Titan swap instructions,
-     * `endSwap`, in order) and `lookupTables` needed to fit it in a versioned transaction.
+     * Throws unless a quote swaps exactly the pair the `beginSwap`/`endSwap` pair is being built
+     * for. A mismatched quote routes and executes normally, but deposits its output into a token
+     * account `endSwap` isn't watching, so it reverts with `InvalidSwap: amount_out must be
+     * greater than 0` only after the funds have already moved.
      */
-    getTitanSwapIx({ titanClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, reduceOnly, userAccountPublicKey, }: {
-        titanClient: TitanClient;
-        outMarketIndex: number;
-        inMarketIndex: number;
-        outAssociatedTokenAccount?: PublicKey;
-        inAssociatedTokenAccount?: PublicKey;
-        amount: BN;
-        slippageBps?: number;
-        swapMode?: string;
-        onlyDirectRoutes?: boolean;
-        reduceOnly?: SwapReduceOnly;
-        userAccountPublicKey?: PublicKey;
-    }): Promise<{
-        ixs: TransactionInstruction[];
-        lookupTables: AddressLookupTableAccount[];
-    }>;
+    protected assertQuoteMatchesMarkets(quote: {
+        inputMint: string;
+        outputMint: string;
+    }, inMarket: SpotMarketAccount, outMarket: SpotMarketAccount): void;
     /**
-     * Builds the instruction list for a Jupiter v6-routed swap: fetches a quote if none is passed,
-     * creates any missing associated token accounts, and wraps Jupiter's routing instructions
-     * between `beginSwap`/`endSwap`. See `swap` for parameter semantics; `amount` is in the "in"
-     * token's mint decimals.
+     * Throws unless a quote is for the size the caller asked to swap. `beginSwap` releases funds
+     * sized off the quote, so a quote for a different size moves the wrong amount out of the user's
+     * deposits.
+     */
+    private assertQuoteMatchesAmount;
+    /**
+     * Resolves the wallet's associated token account for a spot market, plus the instruction that
+     * creates it when it doesn't exist yet.
+     */
+    private getOrCreateSwapTokenAccount;
+    /**
+     * Builds the instruction list for a swap routed through any `SwapProvider` (Jupiter, Titan, or
+     * a `UnifiedSwapClient` wrapping either): creates any missing associated token accounts and
+     * wraps the provider's routing instructions between `beginSwap`/`endSwap`.
+     * @param swapProvider - Provider that quotes the swap and builds its route instructions.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outAssociatedTokenAccount - Token account to receive the bought token; created
+     * idempotently if omitted.
+     * @param inAssociatedTokenAccount - Token account to source the sold token from; created
+     * idempotently if omitted.
+     * @param amount - Amount in the "in" token's mint decimals, or the "out" token's when the
+     * effective mode is `ExactOut`.
+     * @param slippageBps - Max slippage in basis points; only used when a quote has to be fetched.
+     * @param swapMode - `ExactIn` (default) or `ExactOut`. The mode a quote is fetched at; the
+     * resulting quote's own mode is what sizes the swap, so it is ignored when `quote` is passed.
+     * @param onlyDirectRoutes - Restricts a fetched quote to single-hop routes.
+     * @param maxAccounts - Account budget for a fetched route.
+     * @param reduceOnly - Which side must not increase in magnitude; enforced by `endSwap`.
+     * @param quote - Pre-fetched quote. Authoritative when passed: its `swapMode` is the effective
+     * mode, and it must be for this pair and this `amount`.
      * @param userAccountPublicKey - Optional user account override (e.g. when the account is being
-     * created in the same transaction).
-     * @throws If no quote is passed and Jupiter's quote API returns none.
-     * @returns `ixs` — instruction list (ATA creation, `beginSwap`, Jupiter swap instructions,
-     * `endSwap`, in order) and `lookupTables` needed to fit it in a versioned transaction.
+     * created in the same transaction and not yet resolvable via `getUserAccountPublicKey`).
+     * @throws If the quote — passed in or freshly fetched — is for a different pair or a different
+     * size than the swap being built.
+     * @returns `ixs` — ATA creation, `beginSwap`, the route's instructions, `endSwap`, in order —
+     * and the `lookupTables` needed to fit them in a versioned transaction.
      */
-    getJupiterSwapIxV6({ jupiterClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, quote, reduceOnly, userAccountPublicKey, }: {
-        jupiterClient: JupiterClient;
+    getProviderSwapIx({ swapProvider, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, maxAccounts, reduceOnly, quote, userAccountPublicKey, }: {
+        swapProvider: SwapProvider;
         outMarketIndex: number;
         inMarketIndex: number;
         outAssociatedTokenAccount?: PublicKey;
@@ -2394,8 +2404,9 @@ export declare class VelocityClient {
         slippageBps?: number;
         swapMode?: SwapMode;
         onlyDirectRoutes?: boolean;
-        quote?: QuoteResponse;
+        maxAccounts?: number;
         reduceOnly?: SwapReduceOnly;
+        quote?: SwapQuote;
         userAccountPublicKey?: PublicKey;
     }): Promise<{
         ixs: TransactionInstruction[];
@@ -2435,37 +2446,6 @@ export declare class VelocityClient {
         beginSwapIx: TransactionInstruction;
         endSwapIx: TransactionInstruction;
     }>;
-    /**
-     * Builds the instruction list for a swap routed through a `UnifiedSwapClient` (the current
-     * preferred swap path). Creates any missing associated token accounts and wraps the client's
-     * routing instructions between `beginSwap`/`endSwap`. See `swap` for parameter semantics;
-     * `amount` is in the "in" token's mint decimals (or "out" token's decimals when `swapMode` is
-     * `ExactOut`).
-     * @param userAccountPublicKey - Optional user account override (e.g. when the account is being
-     * created in the same transaction).
-     * @returns `ixs` — instruction list (ATA creation, `beginSwap`, routed swap instructions,
-     * `endSwap`, in order) and `lookupTables` needed to fit it in a versioned transaction.
-     */
-    getSwapIxV2({ swapClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, reduceOnly, quote, v6, userAccountPublicKey, }: {
-        swapClient: UnifiedSwapClient;
-        outMarketIndex: number;
-        inMarketIndex: number;
-        outAssociatedTokenAccount?: PublicKey;
-        inAssociatedTokenAccount?: PublicKey;
-        amount: BN;
-        slippageBps?: number;
-        swapMode?: SwapMode;
-        onlyDirectRoutes?: boolean;
-        reduceOnly?: SwapReduceOnly;
-        quote?: UnifiedQuoteResponse;
-        v6?: {
-            quote?: QuoteResponse;
-        };
-        userAccountPublicKey?: PublicKey;
-    }): Promise<{
-        ixs: TransactionInstruction[];
-        lookupTables: AddressLookupTableAccount[];
-    }>;
     /**
      * Converts a portion of the user's deposited wSOL (spot market index 1) into mSOL (spot market
      * index 2) by staking it with Marinade Finance, then swapping the resulting mSOL back into the
@@ -2534,11 +2514,12 @@ export declare class VelocityClient {
     getForceCancelOrdersIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
     /**
      * Keeper instruction: trips the authority-wide equity floor breaker. Proves on-chain that the
-     * given subaccount's cross-margin total collateral is below its `equityFloor` (reverts with
-     * `SufficientCollateral` otherwise, or if no floor is set) and sets `equityBreakerTripped` on the
-     * authority's `UserStats` — every subaccount of the authority then rejects risk-increasing fills,
-     * withdrawals and transfers out until the warm admin calls `resetEquityFloorBreaker`.
-     * Permissionless — any signer may trip it; the margin calculation is the proof.
+     * given subaccount's net equity (unweighted assets and perp PnL minus spot liabilities) is below
+     * its `equityFloor` (reverts with `SufficientCollateral` otherwise, if no floor is set, or with
+     * `InvalidOracle` if any of the subaccount's oracles is invalid) and sets `equityBreakerTripped`
+     * on the authority's `UserStats` — every subaccount of the authority then rejects risk-increasing
+     * fills, withdrawals and transfers out until the warm admin calls `resetEquityFloorBreaker`.
+     * Permissionless — any signer may trip it; the equity calculation is the proof.
      * @param userAccountPublicKey - Public key of the breached subaccount's user account.
      * @param user - Decoded user account of the breached subaccount.
      * @param txParams - Optional compute-unit/priority-fee overrides.
@@ -3326,7 +3307,8 @@ export declare class VelocityClient {
      * @param userAccountPublicKey - Public key of the user account being liquidated.
      * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
      * @param maxAccounts - Caps the number of accounts Jupiter's route may use.
-     * @throws If no quote can be fetched and `quote` was not supplied.
+     * @throws If no quote can be fetched and `quote` was not supplied, or if the quote — passed in or
+     * freshly fetched — is for a different pair or a different size than the swap being built.
      * @returns The ordered instructions (pre-instructions, `beginSwap`, Jupiter swap, `endSwap`) and
      * any address lookup tables the Jupiter route requires.
      */
@@ -3340,7 +3322,7 @@ export declare class VelocityClient {
         slippageBps?: number;
         swapMode?: SwapMode;
         onlyDirectRoutes?: boolean;
-        quote?: QuoteResponse;
+        quote?: JupiterSwapQuote;
         userAccount: UserAccount;
         userAccountPublicKey: PublicKey;
         liquidatorSubAccountId?: number;