@velocity-exchange/sdk 0.9.0 → 0.11.0

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
@@ -451,6 +450,45 @@ export declare class VelocityClient {
      * @returns The resize instruction.
      */
     getResizeSignedMsgUserOrdersInstruction(authority: PublicKey, numOrders: number): Promise<TransactionInstruction>;
+    /**
+     * Grows a zero-copy account (User, PerpMarket, SpotMarket, State, ...) to the size the
+     * deployed program compiles in for its type, as part of an account-size migration after a
+     * program upgrade that appended fields. Requires `HotRole.AccountExtension` (cold, warm, or
+     * the configured account-extension hot key) — the wallet must hold that role. The payer
+     * covers the rent-exempt shortfall and the program zero-fills the new tail. No-op when the
+     * account is already at size, so cranking is idempotent. See `docs/ACCOUNT-EXTENSION.md`.
+     * @param account - The account to extend.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
+    extendAccount(account: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `extendAccount` instruction. See `extendAccount` for semantics.
+     * @param account - The account to extend.
+     * @param payer - Rent payer; defaults to the wallet.
+     * @param authority - `HotRole.AccountExtension` holder; defaults to the wallet.
+     * @returns The extend instruction.
+     */
+    getExtendAccountIx(account: PublicKey, payer?: PublicKey, authority?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Devnet/test only: grows a zero-copy account to an arbitrary larger size, simulating the
+     * state right after a struct-growing program upgrade. Requires `HotRole.AccountExtension`
+     * like `extendAccount`. The instruction is compiled out of mainnet program builds.
+     * @param account - The account to extend.
+     * @param newLen - Target account data length in bytes (must be >= the current length).
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
+    extendAccountDevnet(account: PublicKey, newLen: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `extendAccountDevnet` instruction. See `extendAccountDevnet` for semantics.
+     * @param account - The account to extend.
+     * @param newLen - Target account data length in bytes.
+     * @param payer - Rent payer; defaults to the wallet.
+     * @param authority - `HotRole.AccountExtension` holder; defaults to the wallet.
+     * @returns The extend instruction.
+     */
+    getExtendAccountDevnetIx(account: PublicKey, newLen: number, payer?: PublicKey, authority?: PublicKey): 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
@@ -1573,16 +1611,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 +2346,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 +2382,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;
+    /**
+     * 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;
     /**
-     * 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.
+     * 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 +2443,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 +2485,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 +2553,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 +3346,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 +3361,7 @@ export declare class VelocityClient {
         slippageBps?: number;
         swapMode?: SwapMode;
         onlyDirectRoutes?: boolean;
-        quote?: QuoteResponse;
+        quote?: JupiterSwapQuote;
         userAccount: UserAccount;
         userAccountPublicKey: PublicKey;
         liquidatorSubAccountId?: number;