@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/velocityClient.d.ts

@@ -10,8 +10,8 @@
  *   - Manages the program account subscription lifecycle (markets, oracles, user accounts).
  *   - Provides oracle price reads, market config lookups, and PDA derivation helpers.
  *
- * Admin operations (market init, fee updates, oracle config) live in {@link AdminClient} (adminClient.ts).
- * Read-only user account queries (margin, positions, PnL) live in {@link User} (user.ts).
+ * Admin operations (market init, fee updates, oracle config) live in `AdminClient` (adminClient.ts).
+ * Read-only user account queries (margin, positions, PnL) live in `User` (user.ts).
  *
  * Instruction → on-chain handler mapping: see ARCHITECTURE.md § SDK↔Instruction Mapping.
  */
@@ -48,7 +48,22 @@ export type SwapClient = TitanClient | JupiterClient;
 type RemainingAccountParams = import('./core/remainingAccounts').RemainingAccountParams;
 /**
  * # VelocityClient
- * This class is the main way to interact with Velocity Exchange. It allows you to subscribe to the various accounts where the Market's state is stored, as well as: opening positions, liquidating, settling funding, depositing & withdrawing, and more.
+ * Main entry point for interacting with Velocity Exchange from TypeScript. A single instance wraps
+ * one `authority` wallet (optionally trading on behalf of multiple sub-accounts via
+ * `authoritySubAccountMap`, or as a delegate via `includeDelegates`) and owns:
+ *   - the Anchor `program` handle and RPC `connection`/`provider`,
+ *   - the account subscription (`accountSubscriber`) that streams State, PerpMarket, SpotMarket,
+ *     and oracle accounts (websocket, polling, or grpc — selected via `VelocityClientConfig.accountSubscription`),
+ *   - the set of loaded `User` / `UserStats` objects for this authority's sub-accounts,
+ *   - the `txSender` / `txHandler` used to build, sign, and send every instruction the class exposes.
+ *
+ * Most instruction-building methods come in pairs: `doThing(...)` builds the instruction(s), wraps
+ * them in a transaction, signs, sends, and confirms; `getDoThingIx(...)` (or `getDoThingIxs(...)`)
+ * only builds and returns the raw `TransactionInstruction`(s) for callers composing their own
+ * transaction (e.g. bundling several instructions, or using a custom `txParams`/lookup-table setup).
+ *
+ * Almost every account-touching method requires `subscribe()` to have resolved and the target
+ * sub-account's `User` to be loaded first — see `subscribe`, `addUser`, `switchActiveUser`.
  */
 export declare class VelocityClient {
     connection: Connection;
@@ -83,95 +98,307 @@ export declare class VelocityClient {
     txParams: TxParams;
     enableMetricsEvents?: boolean;
     txHandler: TxHandler;
+    /**
+     * Whether this client has completed `subscribe()` and its underlying `accountSubscriber` is
+     * still actively streaming account updates. Most account-reading and instruction-building
+     * methods assume this is `true`; call `subscribe()` first if it is `false`.
+     */
     get isSubscribed(): boolean;
     private getPrePlaceOrderIxs;
+    /**
+     * Overrides the internal subscribed flag directly, without touching `accountSubscriber`. Intended
+     * for advanced/test callers managing subscription state manually; regular callers should use
+     * `subscribe()` / `unsubscribe()` instead.
+     * @param val - New value for the internal subscribed flag.
+     */
     set isSubscribed(val: boolean);
+    /**
+     * Constructs a `VelocityClient` from a `VelocityClientConfig`. Does not perform any network I/O —
+     * it wires up the Anchor `program`/`provider`, resolves the account-subscription strategy
+     * (websocket/polling/grpc), and constructs the `txSender`/`txHandler` used by every instruction
+     * method, but does not fetch or subscribe to any accounts. Call `subscribe()` afterwards before
+     * using the client.
+     *
+     * Config interplay of note:
+     *   - `authority` defaults to `config.wallet.publicKey`; `activeSubAccountId` defaults to `0`.
+     *   - Exactly one of `includeDelegates`, `subAccountIds`, or `authoritySubAccountMap` may be set —
+     *     passing more than one throws. `subAccountIds` is shorthand for
+     *     `authoritySubAccountMap = { [authority]: subAccountIds }`.
+     *   - `txVersion` defaults based on whether `config.wallet` supports versioned transactions.
+     *   - `txParams.computeUnits` defaults to `600_000` and `computeUnitsPrice` to `0` (no priority fee)
+     *     when not provided.
+     *   - `config.accountSubscription.type` selects `PollingVelocityClientAccountSubscriber`,
+     *     a grpc subscriber, or (default) `WebSocketVelocityClientAccountSubscriber`.
+     *   - `config.userStats` (default falsy) additionally constructs a `UserStats` instance for the
+     *     authority.
+     *   - `config.marketLookupTables` defaults to the lookup tables from `configs[env]` for the
+     *     resolved `env` (default `'mainnet-beta'`).
+     * @param config - Client configuration; see `VelocityClientConfig` (velocityClientConfig.ts).
+     * @throws if more than one of `includeDelegates`/`subAccountIds`/`authoritySubAccountMap` is set.
+     */
     constructor(config: VelocityClientConfig);
+    /**
+     * Builds the internal `Map` key used to index `this.users` for a given sub-account/authority pair.
+     * @param subAccountId - Sub-account id.
+     * @param authority - Owning (or delegated) authority public key for the sub-account.
+     * @returns A string key of the form `"<subAccountId>_<authority>"`.
+     */
     getUserMapKey(subAccountId: number, authority: PublicKey): string;
+    /**
+     * Constructs (but does not subscribe) a `User` for the given sub-account/authority.
+     * @param subAccountId - Sub-account id to derive the user account PDA for.
+     * @param accountSubscriptionConfig - Subscription strategy to use for the new `User`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns An unsubscribed `User` instance.
+     */
     createUser(subAccountId: number, accountSubscriptionConfig: UserSubscriptionConfig, authority?: PublicKey): User;
+    /**
+     * Subscribes the client to on-chain state: loads and subscribes to the sub-account(s) implied by
+     * the constructor/`updateWallet` config (`addAndSubscribeToUsers`), subscribes the `accountSubscriber`
+     * (State, PerpMarket, SpotMarket, oracle accounts), and, if `userStats` was configured, subscribes
+     * it too. Must be called (and resolve `true`) before using most other methods on this class.
+     * @returns `true` if every subscription succeeded; `false` if any failed. Also updates `isSubscribed`.
+     */
     subscribe(): Promise<boolean>;
+    /**
+     * Subscribes every currently-loaded `User` in `this.users`. Does not add new users or subscribe
+     * `accountSubscriber`/`userStats` — see `subscribe()` for full client subscription.
+     * @returns One subscribe promise per loaded user, resolving to that user's subscribe success.
+     */
     subscribeUsers(): Promise<boolean>[];
     /**
-     *	Forces the accountSubscriber to fetch account updates from rpc
+     * Forces every loaded `User`, the `accountSubscriber`, and (if present) `userStats` to fetch fresh
+     * account data from RPC immediately, bypassing the normal websocket/polling cadence. Useful in
+     * tests (e.g. local validator) where a just-landed transaction's effects need to be visible
+     * without waiting for the next update.
      */
     fetchAccounts(): Promise<void>;
+    /**
+     * Unsubscribes all loaded users, the `accountSubscriber`, and (if present) `userStats`, and sets
+     * `isSubscribed` to `false`. Does not clear `this.users` — the `User` objects remain but stop
+     * receiving updates until re-subscribed.
+     */
     unsubscribe(): Promise<void>;
+    /**
+     * Unsubscribes every currently-loaded `User` in `this.users` without clearing the map or touching
+     * `accountSubscriber`/`userStats`.
+     * @returns One unsubscribe promise per loaded user.
+     */
     unsubscribeUsers(): Promise<void>[];
     statePublicKey?: PublicKey;
+    /**
+     * Returns the `State` account PDA for this program, computing and caching it on first call.
+     * @returns The `State` account public key.
+     */
     getStatePublicKey(): Promise<PublicKey>;
     signerPublicKey?: PublicKey;
+    /**
+     * Returns the program's PDA signer (used as the authority for vault CPIs), computing and caching
+     * it on first call. Synchronous — the signer PDA has no seeds that require an on-chain lookup.
+     * @returns The velocity signer public key.
+     */
     getSignerPublicKey(): PublicKey;
+    /**
+     * Returns the last account-subscriber-cached `State` account. Does not hit RPC.
+     * @returns The current `StateAccount` snapshot.
+     * @throws if `subscribe()` has not been called (or the state account has never loaded).
+     */
     getStateAccount(): StateAccount;
     /**
-     * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
+     * Like `getStateAccount` but forces a fresh RPC fetch first. Useful for anchor tests where an
+     * update needs to be observed immediately rather than waiting for the next subscription push.
+     * @returns The freshly-fetched `StateAccount`.
      */
     forceGetStateAccount(): Promise<StateAccount>;
+    /**
+     * Returns the last account-subscriber-cached `PerpMarketAccount` for a market index. Does not hit
+     * RPC. The market must be one of the indexes/lookup-tables this client subscribed to.
+     * @param marketIndex - Perp market index.
+     * @returns The cached `PerpMarketAccount`, or `undefined` if not loaded/subscribed.
+     */
     getPerpMarketAccount(marketIndex: number): PerpMarketAccount | undefined;
     /**
-     * Like {@link getPerpMarketAccount} but throws if the market is not loaded,
+     * Like `getPerpMarketAccount` but throws if the market is not loaded,
      * for call sites that require a guaranteed account.
+     * @param marketIndex - Perp market index.
+     * @returns The cached `PerpMarketAccount`.
+     * @throws if the market is not loaded.
      */
     getPerpMarketAccountOrThrow(marketIndex: number): PerpMarketAccount;
     /**
-     * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
-     * @param marketIndex
+     * Like `getPerpMarketAccount` but forces a fresh RPC fetch, retrying up to 10 times (one fetch per
+     * attempt) until the market account appears. Useful in anchor tests right after
+     * `initializePerpMarket` where the market may not yet be visible to the subscriber.
+     * @param marketIndex - Perp market index.
+     * @returns The `PerpMarketAccount`, or `undefined` if still not found after 10 attempts.
      */
     forceGetPerpMarketAccount(marketIndex: number): Promise<PerpMarketAccount | undefined>;
+    /**
+     * Returns all currently-loaded `PerpMarketAccount`s (does not hit RPC).
+     * @returns Array of loaded perp market accounts, in subscriber order.
+     */
     getPerpMarketAccounts(): PerpMarketAccount[];
+    /**
+     * Returns the last account-subscriber-cached `SpotMarketAccount` for a market index. Does not hit
+     * RPC.
+     * @param marketIndex - Spot market index.
+     * @returns The cached `SpotMarketAccount`, or `undefined` if not loaded/subscribed.
+     */
     getSpotMarketAccount(marketIndex: number): SpotMarketAccount | undefined;
     /**
-     * Like {@link getSpotMarketAccount} but throws if the market is not loaded,
+     * Like `getSpotMarketAccount` but throws if the market is not loaded,
      * for call sites that require a guaranteed account.
+     * @param marketIndex - Spot market index.
+     * @returns The cached `SpotMarketAccount`.
+     * @throws if the market is not loaded.
      */
     getSpotMarketAccountOrThrow(marketIndex: number): SpotMarketAccount;
     /**
-     * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
-     * @param marketIndex
+     * Like `getSpotMarketAccount` but forces a fresh RPC fetch first. Useful for anchor tests where an
+     * update needs to be observed immediately.
+     * @param marketIndex - Spot market index.
+     * @returns The freshly-fetched `SpotMarketAccount`, or `undefined` if not found.
      */
     forceGetSpotMarketAccount(marketIndex: number): Promise<SpotMarketAccount | undefined>;
+    /**
+     * Returns all currently-loaded `SpotMarketAccount`s (does not hit RPC).
+     * @returns Array of loaded spot market accounts, in subscriber order.
+     */
     getSpotMarketAccounts(): SpotMarketAccount[];
+    /**
+     * Convenience accessor for the quote spot market (`QUOTE_SPOT_MARKET_INDEX`, always index 0), i.e.
+     * the USDC market used to denominate collateral/PnL across the protocol.
+     * @returns The quote `SpotMarketAccount`.
+     * @throws if the quote spot market is not loaded.
+     */
     getQuoteSpotMarketAccount(): SpotMarketAccount;
+    /**
+     * Returns the last subscriber-cached oracle price data for a given oracle account/source. Does not
+     * hit RPC.
+     * @param oraclePublicKey - Oracle account public key.
+     * @param oracleSource - Oracle protocol/feed variant (Pyth, Pyth Lazer, Switchboard, etc.) that
+     * determines how the account is decoded.
+     * @returns The cached oracle price data and the slot it was observed at, or `undefined` if this
+     * oracle isn't subscribed.
+     */
     getOraclePriceDataAndSlot(oraclePublicKey: PublicKey, oracleSource: OracleSource): DataAndSlot<OraclePriceData> | undefined;
+    /**
+     * Fetches and caches the `AddressLookupTableAccount`s for `this.marketLookupTables`, so
+     * transaction builders can include them to shrink versioned-transaction size. Subsequent calls
+     * return the cached result.
+     * @returns The resolved lookup table accounts (entries that don't exist on-chain are filtered out).
+     */
     fetchAllLookupTableAccounts(): Promise<AddressLookupTableAccount[]>;
     private getTxVersionForNewWallet;
     /**
-     * Update the wallet to use for velocity transactions and linked user account
-     * @param newWallet
-     * @param subAccountIds
-     * @param activeSubAccountId
-     * @param includeDelegates
+     * Swaps the wallet/authority this client transacts and subscribes as, rebuilding the Anchor
+     * `provider`/`program`, `txSender`, `txHandler`, `userStats`, and (if already subscribed) every
+     * loaded `User` for the new authority. Use this instead of constructing a new `VelocityClient` when
+     * a UI wallet-adapter connection changes.
+     *
+     * At most one of `includeDelegates`, `subAccountIds`, or `authoritySubaccountMap` may be passed
+     * (mirrors the constructor's mutual-exclusion rule); `subAccountIds` is shorthand for
+     * `authoritySubaccountMap = { [newWallet.publicKey]: subAccountIds }`.
+     * @param newWallet - Wallet to switch to; becomes the new `authority`.
+     * @param subAccountIds - Sub-account ids to load for `newWallet`'s authority. Mutually exclusive
+     * with `includeDelegates` and `authoritySubaccountMap`.
+     * @param activeSubAccountId - Sub-account id to make active after the switch.
+     * @param includeDelegates - If `true`, load every sub-account this wallet is a delegate for, in
+     * addition to sub-accounts it owns directly. Mutually exclusive with `subAccountIds` and
+     * `authoritySubaccountMap`.
+     * @param authoritySubaccountMap - Explicit map of authority (as string) to sub-account ids to load,
+     * for managing multiple authorities from one wallet. Mutually exclusive with `subAccountIds` and
+     * `includeDelegates`.
+     * @returns `true` if re-subscribing users (when previously subscribed) succeeded; otherwise `false`.
+     * @throws if more than one of `includeDelegates`/`subAccountIds`/`authoritySubaccountMap` is set.
      */
     updateWallet(newWallet: IWallet, subAccountIds?: number[], activeSubAccountId?: number, includeDelegates?: boolean, authoritySubaccountMap?: Map<string, number[]>): Promise<boolean>;
     /**
      * Update the subscribed accounts to a given authority, while leaving the
      * connected wallet intact. This allows a user to emulate another user's
      * account on the UI and sign permissionless transactions with their own wallet.
-     * @param emulateAuthority
+     *
+     * `authority` is repointed to `emulateAuthority` and `includeDelegates` is forced to `true`, but the
+     * connected `wallet` (and thus its signing key) is unchanged — instructions that require the
+     * emulated authority's own signature (e.g. deposits from its wallet) will still fail; only actions
+     * the connected wallet is independently authorized for (e.g. as a delegate, or read-only views)
+     * will succeed.
+     * @param emulateAuthority - Authority public key to view/act as.
+     * @returns `true` if re-subscribing users (when previously subscribed) succeeded; otherwise `false`.
      */
     emulateAccount(emulateAuthority: PublicKey): Promise<boolean>;
+    /**
+     * Sets the client's `activeSubAccountId`/`authority` (the sub-account used by default when a
+     * method's `subAccountId` param is omitted). If `authority` changes, re-derives and re-subscribes
+     * `userStats` for the new authority (assumed unnecessary when only the sub-account id changes for
+     * the same authority). Does not load or subscribe the target `User` itself — call `addUser` first
+     * if it isn't already loaded.
+     * @param subAccountId - Sub-account id to make active.
+     * @param authority - Authority to switch to; defaults to the current `this.authority` (no change).
+     */
     switchActiveUser(subAccountId: number, authority?: PublicKey): Promise<void>;
+    /**
+     * Loads and subscribes a `User` for a sub-account, adding it to `this.users`. If a subscribed
+     * `User` for this sub-account/authority is already loaded, returns `true` immediately without
+     * re-subscribing.
+     * @param subAccountId - Sub-account id to load.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @param userAccount - Optional pre-fetched `UserAccount` data to seed the subscription with,
+     * avoiding an extra RPC round-trip (e.g. when the caller already has it from a prior fetch).
+     * @returns `true` if the user was already loaded or subscribed successfully; `false` if
+     * subscription failed (e.g. the on-chain user account doesn't exist).
+     */
     addUser(subAccountId: number, authority?: PublicKey, userAccount?: UserAccount): Promise<boolean>;
     /**
      * Adds and subscribes to users based on params set by the constructor or by updateWallet.
+     *
+     * If `authoritySubAccountMap` is non-empty, loads exactly the (authority, subAccountId) pairs it
+     * lists. Otherwise fetches every on-chain `UserAccount` owned by `authority` (defaulting to
+     * `this.wallet.publicKey`), plus (when `includeDelegates` is `true`) every account this authority
+     * is a delegate for, and loads all of them. If `activeSubAccountId` is not already set, the first
+     * loaded account becomes active. A no-op returning `true` if `skipLoadUsers` is set (e.g. no real
+     * wallet configured).
+     * @param authority - Authority to load accounts for; defaults to `this.wallet.publicKey`. Ignored
+     * when `authoritySubAccountMap` is set (its keys are used instead).
+     * @returns `true` if every implied user loaded/subscribed successfully.
      */
     addAndSubscribeToUsers(authority?: PublicKey): Promise<boolean>;
     /**
-     * Returns the instructions to initialize a user account and the public key of the user account.
-     * @param subAccountId
-     * @param name
-     * @param referrerInfo
-     * @returns [instructions, userAccountPublicKey]
+     * Builds the instructions to initialize a user (sub-account) for `this.authority`, without sending
+     * a transaction. For `subAccountId === 0`, also prepends `initializeUserStats` if the authority's
+     * `UserStats` account doesn't already exist on-chain (every authority needs exactly one, created
+     * alongside its first sub-account).
+     * @param subAccountId - Sub-account id to create; defaults to `0`. Must not already exist.
+     * @param name - Display name (max 32 bytes, UTF-8), stored on-chain. Defaults to `DEFAULT_USER_NAME`
+     * for sub-account 0, or `"Subaccount {subAccountId + 1}"` otherwise.
+     * @param referrerInfo - Referrer's `referrer`/`referrerStats` public keys to attribute this account
+     * to a referrer at creation time (fee-share eligibility); omit if there is no referrer.
+     * @param poolId - If provided, appends an instruction to set the sub-account's isolated pool id
+     * after creation.
+     * @returns A tuple of `[instructions, userAccountPublicKey]` — the caller is responsible for
+     * building/sending the transaction.
      */
     getInitializeUserAccountIxs(subAccountId?: number, name?: string, referrerInfo?: ReferrerInfo, poolId?: number): Promise<[TransactionInstruction[], PublicKey]>;
     /**
-     * Initializes a user account and returns the transaction signature and the public key of the user account.
-     * @param subAccountId
-     * @param name
-     * @param referrerInfo
-     * @param txParams
-     * @returns [transactionSignature, userAccountPublicKey]
+     * Initializes a new user (sub-account) for `this.authority` on-chain, then loads and subscribes it
+     * into `this.users` via `addUser`. See `getInitializeUserAccountIxs` for parameter semantics and
+     * the implicit `UserStats` creation for `subAccountId === 0`.
+     * @param subAccountId - Sub-account id to create; defaults to `0`.
+     * @param name - Display name (max 32 bytes); see `getInitializeUserAccountIxs` for the default.
+     * @param referrerInfo - Referrer's `referrer`/`referrerStats` public keys, if attributing this
+     * account to a referrer.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns A tuple of `[transactionSignature, userAccountPublicKey]`.
      */
     initializeUserAccount(subAccountId?: number, name?: string, referrerInfo?: ReferrerInfo, txParams?: TxParams): Promise<[TransactionSignature, PublicKey]>;
+    /**
+     * Builds the `initializeUserStats` instruction for `this.authority`. Every authority needs exactly
+     * one `UserStats` account (created automatically by `getInitializeUserAccountIxs`/
+     * `initializeUserAccount` alongside sub-account 0 if missing); call this directly only when
+     * building a custom initialization flow.
+     * @param overrides.externalWallet - Pays for account creation instead of `this.wallet`, if set.
+     * @returns The `initializeUserStats` instruction.
+     */
     getInitializeUserStatsIx(overrides?: {
         /**
          * Optional external wallet to use as payer. If provided, this wallet will pay
@@ -179,7 +406,25 @@ export declare class VelocityClient {
          */
         externalWallet?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Initializes the `SignedMsgUserOrders` account for `authority`, which caches recently-submitted
+     * off-chain signed (SignedMsg / "swift") order messages so keepers can look them up and verify
+     * duplicates on-chain. Required once per authority before that authority's signed-message orders
+     * can be placed.
+     * @param authority - Authority the account is created for.
+     * @param numOrders - Number of order-message slots to allocate; determines account rent/size.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns A tuple of `[transactionSignature, signedMsgUserAccountPublicKey]`.
+     */
     initializeSignedMsgUserOrders(authority: PublicKey, numOrders: number, txParams?: TxParams): Promise<[TransactionSignature, PublicKey]>;
+    /**
+     * Builds the `initializeSignedMsgUserOrders` instruction. See `initializeSignedMsgUserOrders` for
+     * semantics.
+     * @param authority - Authority the account is created for.
+     * @param numOrders - Number of order-message slots to allocate.
+     * @param overrides.externalWallet - Pays for account creation instead of `this.wallet`, if set.
+     * @returns A tuple of `[signedMsgUserAccountPublicKey, instruction]`.
+     */
     getInitializeSignedMsgUserOrdersAccountIx(authority: PublicKey, numOrders: number, overrides?: {
         /**
          * Optional external wallet to use as payer. If provided, this wallet will pay
@@ -187,102 +432,483 @@ 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.
+     * @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 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>;
+    /**
+     * 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`.
+     * @returns The resize instruction.
+     */
     getResizeSignedMsgUserOrdersInstruction(authority: PublicKey, numOrders: number, userSubaccountId?: 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
+     * without holding general trading authority.
+     * @param authority - Authority the delegates account is created for.
+     * @param delegates - Initial set of delegate public keys; defaults to an empty list.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     initializeSignedMsgWsDelegatesAccount(authority: PublicKey, delegates?: PublicKey[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeSignedMsgWsDelegates` instruction. See
+     * `initializeSignedMsgWsDelegatesAccount` for semantics.
+     * @param authority - Authority the delegates account is created for.
+     * @param delegates - Initial set of delegate public keys; defaults to an empty list.
+     * @returns The initialize instruction.
+     */
     getInitializeSignedMsgWsDelegatesAccountIx(authority: PublicKey, delegates?: PublicKey[]): Promise<TransactionInstruction>;
+    /**
+     * Initializes the per-authority `RevenueShare` account, which accumulates that authority's
+     * lifetime referrer and builder fee-share rewards. One per authority (not per sub-account); an
+     * authority must have this before it can earn referrer or builder revenue share.
+     * @param authority - Authority the account is created for.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     initializeRevenueShare(authority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeRevenueShare` instruction. See `initializeRevenueShare` for semantics.
+     * @param authority - Authority the account is created for.
+     * @param overrides.payer - Pays for account creation instead of `this.wallet`, if set.
+     * @returns The initialize instruction.
+     */
     getInitializeRevenueShareIx(authority: PublicKey, overrides?: {
         payer?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Initializes `authority`'s `RevenueShareEscrow` account — the per-user account that tracks
+     * pending builder-fee orders and the list of builders this user has approved (`approvedBuilders`),
+     * required to place orders carrying a builder fee. On creation, `escrow.referrer` is copied from
+     * the authority's existing `UserStats.referrer`, if any.
+     * @param authority - Authority the escrow is created for.
+     * @param numOrders - Number of pending-order slots to allocate; determines account rent/size. Can
+     * be grown later with `resizeRevenueShareEscrowOrders` (never shrunk).
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     initializeRevenueShareEscrow(authority: PublicKey, numOrders: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeRevenueShareEscrow` instruction. See `initializeRevenueShareEscrow` for
+     * semantics.
+     * @param authority - Authority the escrow is created for.
+     * @param numOrders - Number of pending-order slots to allocate.
+     * @param overrides.payer - Pays for account creation instead of `this.wallet`, if set.
+     * @returns The initialize instruction.
+     */
     getInitializeRevenueShareEscrowIx(authority: PublicKey, numOrders: number, overrides?: {
         payer?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Grows `authority`'s `RevenueShareEscrow` order slots. On-chain rejects `numOrders` smaller than
+     * the current slot count (shrinking is not supported).
+     * @param authority - Authority whose escrow is resized.
+     * @param numOrders - New (larger or equal) number of pending-order slots.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `InvalidRevenueShareResize`) if `numOrders` is less than the current slot count.
+     */
     resizeRevenueShareEscrowOrders(authority: PublicKey, numOrders: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `resizeRevenueShareEscrowOrders` instruction. See `resizeRevenueShareEscrowOrders` for
+     * semantics.
+     * @param authority - Authority whose escrow is resized.
+     * @param numOrders - New (larger or equal) number of pending-order slots.
+     * @returns The resize instruction.
+     */
     getResizeRevenueShareEscrowOrdersIx(authority: PublicKey, numOrders: number): Promise<TransactionInstruction>;
     /**
-     * Creates the transaction to add or update an approved builder.
-     * This allows the builder to receive revenue share from referrals.
-     *
-     * @param builder - The public key of the builder to add or update.
-     * @param maxFeeTenthBps - The maximum fee tenth bps to set for the builder.
+     * Adds, updates, or revokes an approved builder in the caller's own `RevenueShareEscrow`
+     * (`this.wallet.publicKey` unless `overrides.authority` is set on the underlying ix). This is the
+     * *user's* opt-in that lets `builder` attach a builder fee (capped at `maxFeeTenthBps`) to orders
+     * this user places — it does not itself submit any order. `maxFeeTenthBps` is in tenths of a basis
+     * point (1 unit = 0.001%, i.e. `10_000` tenth-bps = 1%).
+     * @param builder - The public key of the builder to add or update. Must differ from the escrow's
+     * own authority.
+     * @param maxFeeTenthBps - The maximum fee, in tenths of a basis point, the builder may charge.
      * @param add - Whether to add or update the builder. If the builder already exists, `add = true` will update the `maxFeeTenthBps`, otherwise it will add the builder. If `add = false`, the builder's `maxFeeTenthBps` will be set to 0.
      * @param txParams - The transaction parameters to use for the transaction.
      * @returns The transaction to add or update an approved builder.
+     * @throws (on-chain `CannotRevokeBuilderWithOpenOrders`) if `add` is `false` and the builder has
+     * open (unsettled) orders outstanding — those must be cancelled/settled first.
      */
     changeApprovedBuilder(builder: PublicKey, maxFeeTenthBps: number, add: boolean, txParams?: TxParams): Promise<TransactionSignature>;
     /**
-     * Creates the transaction instruction to add or update an approved builder.
-     * This allows the builder to receive revenue share from referrals.
-     *
+     * Builds the `changeApprovedBuilder` instruction. See `changeApprovedBuilder` for semantics; unlike
+     * the wrapper, `overrides.authority` lets you target an escrow other than the connected wallet's.
      * @param builder - The public key of the builder to add or update.
-     * @param maxFeeTenthBps - The maximum fee tenth bps to set for the builder.
+     * @param maxFeeTenthBps - The maximum fee, in tenths of a basis point (1 unit = 0.001%).
      * @param add - Whether to add or update the builder. If the builder already exists, `add = true` will update the `maxFeeTenthBps`, otherwise it will add the builder. If `add = false`, the builder's `maxFeeTenthBps` will be set to 0.
+     * @param overrides.authority - Escrow authority to target; defaults to `this.wallet.publicKey`.
+     * @param overrides.payer - Pays for any account resize instead of `this.wallet`, if set.
      * @returns The transaction instruction to add or update an approved builder.
      */
     getChangeApprovedBuilderIx(builder: PublicKey, maxFeeTenthBps: number, add: boolean, overrides?: {
         authority?: PublicKey;
         payer?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Authorizes `delegate` on `authority`'s existing `SignedMsgWsDelegates` account (must already be
+     * initialized via `initializeSignedMsgWsDelegatesAccount`). Signed by `this.wallet.publicKey`,
+     * which must be `authority`.
+     * @param authority - Authority whose delegates list is updated.
+     * @param delegate - Delegate public key to authorize.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     addSignedMsgWsDelegate(authority: PublicKey, delegate: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `changeSignedMsgWsDelegateStatus` instruction with `add = true`. See
+     * `addSignedMsgWsDelegate` for semantics.
+     * @param authority - Authority whose delegates list is updated.
+     * @param delegate - Delegate public key to authorize.
+     * @returns The instruction.
+     */
     getAddSignedMsgWsDelegateIx(authority: PublicKey, delegate: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Revokes `delegate`'s authorization on `authority`'s `SignedMsgWsDelegates` account. Signed by
+     * `this.wallet.publicKey`, which must be `authority`.
+     * @param authority - Authority whose delegates list is updated.
+     * @param delegate - Delegate public key to revoke.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     removeSignedMsgWsDelegate(authority: PublicKey, delegate: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `changeSignedMsgWsDelegateStatus` instruction with `add = false`. See
+     * `removeSignedMsgWsDelegate` for semantics.
+     * @param authority - Authority whose delegates list is updated.
+     * @param delegate - Delegate public key to revoke.
+     * @returns The instruction.
+     */
     getRemoveSignedMsgWsDelegateIx(authority: PublicKey, delegate: PublicKey): Promise<TransactionInstruction>;
     private getInitializeUserInstructions;
+    /**
+     * Returns the sub-account id that would be assigned to the next sub-account created for
+     * `this.wallet.publicKey` (i.e. `UserStats.numberOfSubAccountsCreated`, which increments on every
+     * `initializeUser` and never reuses ids after `deleteUser`). Prefers the already-loaded `userStats`
+     * subscription; falls back to an RPC fetch if it isn't loaded or has no cached account yet.
+     * @returns The next sub-account id to be created.
+     * @throws if no `UserStats` account exists on-chain for `this.wallet.publicKey` (i.e. sub-account 0
+     * has never been initialized).
+     */
     getNextSubAccountId(): Promise<number>;
+    /**
+     * Registers `this.wallet`'s sub-account 0 as a referrer under a human-readable `name`, creating a
+     * `ReferrerNameAccount` PDA keyed by that name. Other users can then look up this authority's
+     * `referrer`/`referrerStats` public keys by name (see `getReferrerNameAccountsForAuthority`) when
+     * passing `referrerInfo` to `initializeUserAccount`. Fails if the name is already taken (PDA
+     * already initialized).
+     * @param name - Referrer name to register (encoded/truncated the same way as user names).
+     * @returns The transaction signature.
+     */
     initializeReferrerName(name: string): Promise<TransactionSignature>;
+    /**
+     * Updates the display name stored on a sub-account. Signed by `this.wallet.publicKey`, which must
+     * be the sub-account's authority.
+     * @param name - New display name (max 32 bytes, UTF-8).
+     * @param subAccountId - Sub-account id to rename; defaults to `0`.
+     * @returns The transaction signature.
+     */
     updateUserName(name: string, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Sets a per-sub-account custom (higher) minimum margin ratio for one or more sub-accounts in a
+     * single transaction, self-imposing a lower max leverage than the market default. Signed by
+     * `this.wallet.publicKey` for each sub-account's authority.
+     * @param updates - List of `{ marginRatio, subAccountId }` updates to apply.
+     * `marginRatio` is in `MARGIN_PRECISION` (1e4 = 100%), e.g. `2000` = 20% margin ratio = 5x max
+     * leverage.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     updateUserCustomMarginRatio(updates: {
         marginRatio: number;
         subAccountId: number;
     }[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserCustomMarginRatio` instruction for a single sub-account. As a side effect,
+     * ensures the target sub-account is loaded via `addUser` before building the instruction. See
+     * `updateUserCustomMarginRatio` for unit/semantics.
+     * @param marginRatio - Minimum margin ratio, in `MARGIN_PRECISION` (1e4 = 100%).
+     * @param subAccountId - Sub-account id to update; defaults to `0`.
+     * @returns The instruction.
+     */
     getUpdateUserCustomMarginRatioIx(marginRatio: number, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Builds the instruction to set a custom minimum margin ratio for a single open perp position
+     * (rather than the whole sub-account), letting a position use different effective max leverage than
+     * the sub-account default. Used internally by `getPrePlaceOrderIxs` to implement per-order
+     * `positionMaxLev`.
+     * @param perpMarketIndex - Perp market index of the position to constrain.
+     * @param marginRatio - Minimum margin ratio for this position, in `MARGIN_PRECISION` (1e4 = 100%).
+     * @param subAccountId - Sub-account id owning the position; defaults to `0`.
+     * @param overrides.userAccountPublicKey - Explicit user account PDA, skipping derivation.
+     * @param overrides.authority - Authority to derive the user account PDA for if
+     * `userAccountPublicKey` isn't given; defaults to `this.authority`.
+     * @param overrides.signingAuthority - Signer passed to the instruction; defaults to
+     * `this.wallet.publicKey`.
+     * @returns The instruction.
+     */
     getUpdateUserPerpPositionCustomMarginRatioIx(perpMarketIndex: number, marginRatio: number, subAccountId?: number, overrides?: {
         userAccountPublicKey?: PublicKey;
         authority?: PublicKey;
         signingAuthority?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Sends the instruction built by `getUpdateUserPerpPositionCustomMarginRatioIx`. See that method
+     * for semantics/units.
+     * @param perpMarketIndex - Perp market index of the position to constrain.
+     * @param marginRatio - Minimum margin ratio for this position, in `MARGIN_PRECISION` (1e4 = 100%).
+     * @param subAccountId - Sub-account id owning the position; defaults to `0`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     updateUserPerpPositionCustomMarginRatio(perpMarketIndex: number, marginRatio: number, subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the instruction to toggle a sub-account's "margin trading enabled" flag, which permits
+     * borrowing against spot collateral (multiple simultaneous spot borrows / cross-margined spot). It
+     * is incompatible with holding a position in an `Isolated`-tier perp market — enabling it while
+     * such a position is open, or opening one while it's enabled, is rejected on-chain. As a side
+     * effect, ensures the target sub-account is loaded via `addUser`.
+     * @param marginTradingEnabled - New value for the flag.
+     * @param subAccountId - Sub-account id to update; defaults to `0`.
+     * @param userAccountPublicKey - Explicit user account PDA, skipping derivation from
+     * `this.wallet.publicKey`/`subAccountId`.
+     * @returns The instruction.
+     */
     getUpdateUserMarginTradingEnabledIx(marginTradingEnabled: boolean, subAccountId?: number, userAccountPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Sends instructions built by `getUpdateUserMarginTradingEnabledIx` for one or more sub-accounts in
+     * a single transaction. See that method for semantics.
+     * @param updates - List of `{ marginTradingEnabled, subAccountId }` updates to apply.
+     * @returns The transaction signature.
+     */
     updateUserMarginTradingEnabled(updates: {
         marginTradingEnabled: boolean;
         subAccountId: number;
     }[]): Promise<TransactionSignature>;
+    /**
+     * Builds the instruction to set (or clear, with `PublicKey.default`) the delegate authority on a
+     * sub-account. The delegate can sign most trading instructions (place/cancel orders, etc.) on the
+     * sub-account's behalf, but `withdraw` always requires the true owning `authority`'s own signature
+     * (delegates can never withdraw). A delegate-initiated internal transfer of the sub-account's
+     * collateral to another of the owner's sub-accounts is possible only via `transferDepositByDelegate`,
+     * and only once the owner has separately opted in via `updateUserAllowDelegateTransfer`.
+     * @param delegate - New delegate public key; pass `PublicKey.default` to remove the delegate.
+     * @param overrides.subAccountId - Sub-account id to update; defaults to `this.activeSubAccountId`.
+     * @param overrides.userAccountPublicKey - Explicit user account PDA, skipping derivation.
+     * @param overrides.authority - Signer for the instruction; defaults to `this.wallet.publicKey`.
+     * @returns The instruction.
+     */
     getUpdateUserDelegateIx(delegate: PublicKey, overrides: {
         subAccountId?: number;
         userAccountPublicKey?: PublicKey;
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Sends the `updateUserDelegate` instruction for `this.wallet.publicKey`'s sub-account. See
+     * `getUpdateUserDelegateIx` for full semantics.
+     * @param delegate - New delegate public key; pass `PublicKey.default` to remove the delegate.
+     * @param subAccountId - Sub-account id to update; defaults to `0`.
+     * @returns The transaction signature.
+     */
     updateUserDelegate(delegate: PublicKey, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the instruction to set the `allowDelegateTransfer` opt-in flag on `this.wallet.publicKey`'s
+     * `UserStats` account. This flag gates `transferDepositByDelegate` across *all* of this authority's
+     * sub-accounts — if it is `false` (the default), any delegate-initiated internal transfer attempt
+     * is rejected on-chain regardless of that sub-account's delegate. It does not affect direct
+     * deposits/withdrawals, which are unaffected by delegate status.
+     * @param allowDelegateTransfer - New value for the flag.
+     * @returns The instruction.
+     */
     getUpdateUserAllowDelegateTransferIx(allowDelegateTransfer: boolean): Promise<TransactionInstruction>;
+    /**
+     * Sends the instruction built by `getUpdateUserAllowDelegateTransferIx`. See that method for
+     * semantics.
+     * @param allowDelegateTransfer - New value for the flag.
+     * @returns The transaction signature.
+     */
     updateUserAllowDelegateTransfer(allowDelegateTransfer: boolean): Promise<TransactionSignature>;
+    /**
+     * Sends instructions built by `getUpdateAdvancedDlpIx` for one or more sub-accounts.
+     *
+     * **Currently non-functional**: the on-chain `update_user_advanced_lp` instruction handler is
+     * commented out of the program's Anchor `#[program]` module (see `programs/velocity/src/lib.rs`)
+     * and is absent from the generated IDL, so `program.instruction.updateUserAdvancedLp` does not
+     * exist and this call will throw at runtime until the instruction is re-enabled on-chain.
+     * @param updates - List of `{ advancedLp, subAccountId }` updates to apply.
+     * @returns The transaction signature.
+     * @throws always, until `update_user_advanced_lp` is re-enabled on-chain and regenerated into the IDL.
+     */
     updateUserAdvancedLp(updates: {
         advancedLp: boolean;
         subAccountId: number;
     }[]): Promise<TransactionSignature>;
+    /**
+     * Builds the (currently unavailable — see `updateUserAdvancedLp`) `updateUserAdvancedLp`
+     * instruction, which would flag a sub-account as an "advanced LP" participant.
+     * @param advancedLp - New value for the flag.
+     * @param subAccountId - Sub-account id to update.
+     * @returns The instruction, if the on-chain ix existed.
+     * @throws always, since `program.instruction.updateUserAdvancedLp` is not defined in the current IDL.
+     */
     getUpdateAdvancedDlpIx(advancedLp: boolean, subAccountId: number): Promise<any>;
+    /**
+     * Sends instructions built by `getUpdateUserReduceOnlyIx` for one or more sub-accounts in a single
+     * transaction. See that method for semantics.
+     * @param updates - List of `{ reduceOnly, subAccountId }` updates to apply.
+     * @returns The transaction signature.
+     */
     updateUserReduceOnly(updates: {
         reduceOnly: boolean;
         subAccountId: number;
     }[]): Promise<TransactionSignature>;
+    /**
+     * Builds the instruction to toggle a sub-account's reduce-only status. When reduce-only, orders on
+     * the sub-account may only decrease existing positions, never open or increase one.
+     * @param reduceOnly - New value for the flag.
+     * @param subAccountId - Sub-account id to update.
+     * @returns The instruction.
+     * @throws (on-chain `LiquidationsOngoing`) if the sub-account is currently being liquidated.
+     */
     getUpdateUserReduceOnlyIx(reduceOnly: boolean, subAccountId: number): Promise<TransactionInstruction>;
+    /**
+     * Sends instructions built by `getUpdateUserPoolIdIx` for one or more sub-accounts in a single
+     * transaction. See that method for semantics.
+     * @param updates - List of `{ poolId, subAccountId }` updates to apply.
+     * @returns The transaction signature.
+     */
     updateUserPoolId(updates: {
         poolId: number;
         subAccountId: number;
     }[]): Promise<TransactionSignature>;
+    /**
+     * Builds the instruction to move a sub-account into a different isolated pool. On-chain,
+     * re-validates the sub-account still meets its initial margin requirement after the switch using
+     * only markets/oracles passed via `remaining_accounts` — the caller (this method doesn't add any)
+     * must supply those if the sub-account has open deposits/positions, or the ix will fail.
+     * @param poolId - New pool id for the sub-account.
+     * @param subAccountId - Sub-account id to update.
+     * @returns The instruction.
+     * @throws (on-chain) if the sub-account has deposits/positions in markets outside the new pool, or
+     * otherwise fails the initial margin check after the switch.
+     */
     getUpdateUserPoolIdIx(poolId: number, subAccountId: number): Promise<TransactionInstruction>;
+    /**
+     * Fetches every `User` account that exists on-chain for this program via `getProgramAccounts` (with
+     * a `memcmp` filter, not restricted to this client's authority). Expensive — intended for indexers/
+     * admin tooling, not per-trade calls.
+     * @param includeIdle - If `false`, filters out idle (inactive) user accounts server-side; defaults
+     * to `true` (return all).
+     * @returns All matching `User` program accounts with their addresses.
+     */
     fetchAllUserAccounts(includeIdle?: boolean): Promise<ProgramAccount<UserAccount>[]>;
+    /**
+     * Fetches (via RPC `memcmp` filter, not the account subscriber) every on-chain `User` account whose
+     * `delegate` field equals `delegate`, i.e. every sub-account this wallet can trade on behalf of as a
+     * delegate.
+     * @param delegate - Delegate public key to search for.
+     * @returns Matching `UserAccount`s, sorted by `subAccountId` ascending.
+     */
     getUserAccountsForDelegate(delegate: PublicKey): Promise<UserAccount[]>;
+    /**
+     * Fetches (via RPC, not the account subscriber) every on-chain `User` account owned by `authority`,
+     * with each account's PDA address included.
+     * @param authority - Authority to search for.
+     * @returns Matching `UserAccount`s and their addresses, in RPC-returned order (not sorted).
+     */
     getUserAccountsAndAddressesForAuthority(authority: PublicKey): Promise<ProgramAccount<UserAccount>[]>;
+    /**
+     * Fetches (via RPC, not the account subscriber) every on-chain `User` account owned by `authority`.
+     * Used internally by `addAndSubscribeToUsers` to discover an authority's sub-accounts.
+     * @param authority - Authority to search for.
+     * @returns Matching `UserAccount`s, sorted by `subAccountId` ascending.
+     */
     getUserAccountsForAuthority(authority: PublicKey): Promise<UserAccount[]>;
+    /**
+     * Fetches (via RPC `memcmp` filter) every `UserStats` account whose `referrer` field equals
+     * `referrer`, i.e. every authority that was referred by this referrer.
+     * @param referrer - Referrer authority public key to search for.
+     * @returns Matching `UserStatsAccount`s, in RPC-returned order.
+     */
     getReferredUserStatsAccountsByReferrer(referrer: PublicKey): Promise<UserStatsAccount[]>;
+    /**
+     * Fetches (via RPC `memcmp` filter) every `ReferrerNameAccount` registered by `authority` via
+     * `initializeReferrerName`.
+     * @param authority - Authority to search for.
+     * @returns Matching `ReferrerNameAccount`s, in RPC-returned order.
+     */
     getReferrerNameAccountsForAuthority(authority: PublicKey): Promise<ReferrerNameAccount[]>;
+    /**
+     * Deletes a sub-account owned by `this.wallet.publicKey` and unsubscribes/removes it from
+     * `this.users`. On-chain requires the sub-account to be fully closed out: no open perp/spot
+     * positions, no open orders, not bankrupt, not being liquidated, and (unless idle) sub-account 0 of
+     * a referrer cannot be deleted at all. If the protocol charges a `maxInitializeUserFee` and the
+     * account's `UserStats` is younger than ~13 days, the sub-account must also be marked `idle`.
+     * @param subAccountId - Sub-account id to delete; defaults to `0`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `UserCantBeDeleted`) if any of the above preconditions aren't met.
+     */
     deleteUser(subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `deleteUser` instruction. See `deleteUser` for on-chain preconditions.
+     * @param userAccountPublicKey - User account PDA to delete.
+     * @returns The instruction.
+     */
     getUserDeletionIx(userAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper-only instruction: force-cancels all open orders and deletes/closes an inactive, near-zero
+     * equity user account, refunding remaining rent to `userAccount.authority`. Requires the signer
+     * (`this.wallet.publicKey`) to hold the `UserFlag` hot-role. On-chain, requires the account's
+     * total equity to be under `QUOTE_PRECISION / 20` (0.05 USDC, QUOTE_PRECISION = 1e6) and (outside
+     * `anchor-test` builds) at least ~3 months of inactivity since `lastActiveSlot`. Not for
+     * self-service account deletion — see `deleteUser` for that.
+     * @param userAccountPublicKey - PDA of the user account to force-delete.
+     * @param userAccount - The account's current on-chain data, used to build `remaining_accounts` for
+     * the markets it holds positions in.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain) if the signer lacks the `UserFlag` hot-role, if equity exceeds the dust
+     * threshold, or if the account has been active too recently.
+     */
     forceDeleteUser(userAccountPublicKey: PublicKey, userAccount: UserAccount, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the keeper-only `forceDeleteUser` instruction, assembling `remaining_accounts` for the
+     * account's non-empty spot positions, its revenue-share escrow (if any order carries a builder
+     * fee), and every mint/token-program needed for its open spot balances. See `forceDeleteUser` for
+     * on-chain preconditions.
+     * @param userAccountPublicKey - PDA of the user account to force-delete.
+     * @param userAccount - The account's current on-chain data.
+     * @returns The instruction.
+     */
     getForceDeleteUserIx(userAccountPublicKey: PublicKey, userAccount: UserAccount): Promise<TransactionInstruction>;
+    /**
+     * Closes `this.wallet.publicKey`'s `SignedMsgUserOrders` account, refunding its rent to the
+     * authority. Requires the account to exist (see `isSignedMsgUserOrdersAccountInitialized`).
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     deleteSignedMsgUserOrders(txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `deleteSignedMsgUserOrders` instruction, signed by `this.wallet.publicKey`. See
+     * `deleteSignedMsgUserOrders` for semantics.
+     * @param authority - Authority whose `SignedMsgUserOrders` PDA is derived and closed.
+     * @returns The instruction.
+     */
     getSignedMsgUserOrdersDeletionIx(authority: PublicKey): Promise<any>;
     /**
      * Checks if a SignedMsg User Orders account exists for the given authority.
@@ -293,64 +919,180 @@ export declare class VelocityClient {
      * @returns Promise that resolves to true if the account exists, false otherwise
      */
     isSignedMsgUserOrdersAccountInitialized(authority: PublicKey): Promise<boolean>;
+    /**
+     * Reclaims any lamports on a sub-account's `User` PDA in excess of the rent-exempt minimum for its
+     * current size (e.g. left over after the account was resized smaller), transferring them to
+     * `this.wallet.publicKey`.
+     * @param subAccountId - Sub-account id to reclaim rent from; defaults to `0`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `CantReclaimRent`) if there are no excess lamports, or if the account's
+     * `UserStats` is younger than ~13 days while the protocol enforces a max sub-account count.
+     */
     reclaimRent(subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `reclaimRent` instruction. See `reclaimRent` for semantics/preconditions.
+     * @param userAccountPublicKey - User account PDA to reclaim excess rent from.
+     * @returns The instruction.
+     */
     getReclaimRentIx(userAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Looks up an already-loaded `User` from `this.users` (does not fetch or subscribe).
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns The loaded `User`.
+     * @throws if `subAccountId`/`authority` can't be resolved, or no matching user is loaded (call
+     * `addUser` first).
+     */
     getUser(subAccountId?: number, authority?: PublicKey): User;
+    /**
+     * Checks whether a `User` for the given sub-account/authority is currently loaded in `this.users`,
+     * without throwing. Safe to call with unresolvable `subAccountId`/`authority` (returns `false`).
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns `true` if a matching `User` is loaded.
+     */
     hasUser(subAccountId?: number, authority?: PublicKey): boolean;
+    /**
+     * Returns every currently-loaded `User`, with sub-accounts owned directly by `this.wallet.publicKey`
+     * first, followed by delegated sub-accounts (owned by other authorities this wallet delegates for).
+     * @returns All loaded `User`s in that order.
+     */
     getUsers(): User[];
+    /**
+     * Returns the `UserStats` instance for `this.authority`, if one was constructed (via
+     * `config.userStats`, `updateWallet`, `emulateAccount`, or `switchActiveUser`).
+     * @returns The `UserStats` instance, or `undefined` if none exists.
+     */
     getUserStats(): UserStats | undefined;
     /**
-     * Like {@link getUserStats} but throws if there is no UserStats
+     * Like `getUserStats` but throws if there is no UserStats
      * subscription, for call sites that require a guaranteed account.
      */
     getUserStatsOrThrow(): UserStats;
+    /**
+     * Fetches (via RPC, not the account subscriber) the `ReferrerNameAccount` registered for a given
+     * name via `initializeReferrerName`.
+     * @param name - Referrer name to look up.
+     * @returns The `ReferrerNameAccount`.
+     * @throws if no `ReferrerNameAccount` is registered under `name`.
+     */
     fetchReferrerNameAccount(name: string): Promise<ReferrerNameAccount | undefined>;
+    /**
+     * Returns the `UserStats` account PDA for `this.authority`, computing and caching it on first call
+     * (or after `this.authority` changes, since callers like `updateWallet`/`switchActiveUser` reset the
+     * cache).
+     * @returns The `UserStats` account public key.
+     */
     getUserStatsAccountPublicKey(): PublicKey;
+    /**
+     * Returns the user account PDA for an already-loaded sub-account (does not derive/compute a PDA
+     * for a sub-account that hasn't been loaded).
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns The user account public key.
+     * @throws if no matching user is loaded — see `getUser`.
+     */
     getUserAccountPublicKey(subAccountId?: number, authority?: PublicKey): Promise<PublicKey>;
+    /**
+     * Returns the last subscriber-cached `UserAccount` data for a loaded sub-account. Does not hit RPC.
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns The cached `UserAccount`, or `undefined` if not yet loaded.
+     * @throws if no matching `User` is loaded — see `getUser`.
+     */
     getUserAccount(subAccountId?: number, authority?: PublicKey): UserAccount | undefined;
     /**
-     * Like {@link getUserAccount} but throws a named error instead of returning
+     * Like `getUserAccount` but throws a named error instead of returning
      * `undefined` when the account has not been loaded yet. Use at call sites
      * that structurally require a loaded account.
      */
     getUserAccountOrThrow(subAccountId?: number, authority?: PublicKey): UserAccount;
     /**
-     * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
-     * @param subAccountId
+     * Like `getUserAccount` but forces a fresh RPC fetch first. Useful for anchor tests where an
+     * update needs to be observed immediately.
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns The freshly-fetched `UserAccount`, or `undefined` if not found.
+     * @throws if no matching `User` is loaded — see `getUser`.
      */
     forceGetUserAccount(subAccountId?: number, authority?: PublicKey): Promise<UserAccount | undefined>;
+    /**
+     * Like `getUserAccount` but also returns the slot the data was last observed at.
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @param authority - Authority owning the sub-account; defaults to `this.authority`.
+     * @returns The cached `UserAccount` and its slot, or `undefined` if not yet loaded.
+     * @throws if no matching `User` is loaded — see `getUser`.
+     */
     getUserAccountAndSlot(subAccountId?: number, authority?: PublicKey): DataAndSlot<UserAccount> | undefined;
+    /**
+     * Returns a sub-account's spot balance entry for a market, if it holds one.
+     * @param marketIndex - Spot market index.
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @returns The `SpotPosition`, or `undefined` if the sub-account has no balance in this market.
+     * @throws if the sub-account is not loaded — see `getUserAccountOrThrow`.
+     */
     getSpotPosition(marketIndex: number, subAccountId?: number): SpotPosition | undefined;
+    /**
+     * Convenience accessor for the active sub-account's quote (USDC) token amount.
+     * @returns Signed token amount, in the quote spot market's token precision (positive if a deposit,
+     * negative if a borrow). See `getTokenAmount`.
+     */
     getQuoteAssetTokenAmount(): BN;
+    /**
+     * Returns the isolated deposit token amount backing a sub-account's isolated perp position in a
+     * given market (the collateral segregated into that position via
+     * `transferIsolatedPerpPositionDeposit`, distinct from the sub-account's general/cross balances).
+     * @param perpMarketIndex - Perp market index of the isolated position.
+     * @param subAccountId - Sub-account id; defaults to `this.activeSubAccountId`.
+     * @returns Token amount in the quote spot market's token precision.
+     */
     getIsolatedPerpPositionTokenAmount(perpMarketIndex: number, subAccountId?: number): BN;
     /**
-     * Returns the token amount for a given market. The spot market precision is based on the token mint decimals.
-     * Positive if it is a deposit, negative if it is a borrow.
-     * @param marketIndex
+     * Returns the active sub-account's balance in a spot market, converted from the internal scaled
+     * balance representation to actual token units.
+     * @param marketIndex - Spot market index.
+     * @returns Token amount in the spot market's own token precision (`10^mint.decimals`, e.g.
+     * QUOTE_PRECISION (1e6) for USDC). Positive if a deposit, negative if a borrow. `ZERO` if the
+     * sub-account has no balance in this market.
      */
     getTokenAmount(marketIndex: number): BN;
     /**
-     * Converts an amount to the spot precision for a given market. The spot market precision is based on the token mint decimals.
-     * @param marketIndex
-     * @param amount
+     * Converts a human-readable (UI) amount to a market's on-chain spot precision (`10^mint.decimals`).
+     * A plain `number` is scaled up via `castNumberToSpotPrecision`; a `BN` is assumed to already be a
+     * whole-token count and is scaled by the same factor.
+     * @param marketIndex - Spot market index whose token decimals determine the scale factor.
+     * @param amount - UI amount to convert.
+     * @returns The amount in the spot market's token precision.
      */
     convertToSpotPrecision(marketIndex: number, amount: BN | number): BN;
     /**
-     * Converts an amount to the perp precision. The perp market precision is {@link BASE_PRECISION} (1e9).
-     * @param amount
+     * Converts a human-readable (UI) base-asset amount to `BASE_PRECISION` (1e9), the precision used for
+     * perp/spot order base amounts.
+     * @param amount - UI base amount to convert. A `number` is scaled via a precision-safe helper; a
+     * `BN` is assumed to already be a whole-unit count and is multiplied directly by `BASE_PRECISION`.
+     * @returns The amount in `BASE_PRECISION` (1e9).
      */
     convertToPerpPrecision(amount: BN | number): BN;
     /**
-     * Converts an amount to the price precision. The perp market precision is {@link PRICE_PRECISION} (1e6).
-     * @param amount
+     * Converts a human-readable (UI) price to `PRICE_PRECISION` (1e6).
+     * @param amount - UI price to convert.
+     * @returns The amount in `PRICE_PRECISION` (1e6) when `amount` is a `number` (uses
+     * `numberToSafeBN(amount, PRICE_PRECISION)`).
+     * **Note:** when `amount` is a `BN`, this multiplies by `BASE_PRECISION` (1e9), not
+     * `PRICE_PRECISION` (1e6) — that is very likely a bug (1000x too large) rather than intended
+     * behavior; pass a `number` for correct scaling until this is fixed.
      */
     convertToPricePrecision(amount: BN | number): BN;
     /**
-     * Each velocity instruction must include perp and sport market accounts in the ix remaining accounts.
+     * Each velocity instruction must include perp and spot market accounts in the ix remaining accounts.
      * Use this function to force a subset of markets to be included in the remaining accounts for every ix
-     *
-     * @param perpMarketIndexes
-     * @param spotMarketIndexes
+     * built by this client going forward (accumulates into `mustIncludePerpMarketIndexes` /
+     * `mustIncludeSpotMarketIndexes`; there is no corresponding "unset" — construct a new client to
+     * reset). Useful when an instruction's own logic can't infer every market/oracle it needs (e.g. a
+     * cross-margin health check spanning markets the user has no position in yet).
+     * @param perpMarketIndexes - Perp market indexes to always include.
+     * @param spotMarketIndexes - Spot market indexes to always include.
      */
     mustIncludeMarketsInIx({ perpMarketIndexes, spotMarketIndexes, }: {
         perpMarketIndexes: number[];
@@ -358,10 +1100,55 @@ export declare class VelocityClient {
     }): void;
     private cachePerpMarketSlot;
     private cacheSpotMarketSlot;
+    /**
+     * Builds the `remaining_accounts` list (perp/spot market + oracle accounts, plus any accounts
+     * derived from the given `userAccounts`) that most instructions need appended so the on-chain
+     * handler can load the markets/oracles it touches. Always includes markets registered via
+     * `mustIncludeMarketsInIx`, in addition to whatever `params` (e.g. `userAccounts`,
+     * `writableSpotMarketIndexes`) implies. Used internally by nearly every instruction-building method
+     * on this class; exposed publicly for callers assembling custom instructions.
+     * @param params - Describes which markets/users to derive remaining accounts for; see
+     * `RemainingAccountParams` (core/remainingAccounts.ts).
+     * @returns The `AccountMeta[]` to append to an instruction's accounts.
+     */
     getRemainingAccounts(params: RemainingAccountParams): AccountMeta[];
+    /**
+     * Adds a perp market's account meta (and its oracle and quote spot market) into the shared maps used
+     * to de-duplicate remaining accounts across multiple markets in one instruction. The oracle is
+     * marked writable only for `prelaunch`-sourced oracles being written to.
+     * @param marketIndex - Perp market index to include.
+     * @param writable - Whether the perp market account meta should be writable.
+     * @param oracleAccountMap - Shared map (keyed by oracle pubkey string) mutated in place.
+     * @param spotMarketAccountMap - Shared map (keyed by spot market index) mutated in place.
+     * @param perpMarketAccountMap - Shared map (keyed by perp market index) mutated in place.
+     */
     addPerpMarketToRemainingAccountMaps(marketIndex: number, writable: boolean, oracleAccountMap: Map<string, AccountMeta>, spotMarketAccountMap: Map<number, AccountMeta>, perpMarketAccountMap: Map<number, AccountMeta>): void;
+    /**
+     * Adds a spot market's account meta (and its oracle, if any) into the shared maps used to
+     * de-duplicate remaining accounts across multiple markets in one instruction.
+     * @param marketIndex - Spot market index to include.
+     * @param writable - Whether the spot market account meta should be writable.
+     * @param oracleAccountMap - Shared map (keyed by oracle pubkey string) mutated in place.
+     * @param spotMarketAccountMap - Shared map (keyed by spot market index) mutated in place.
+     */
     addSpotMarketToRemainingAccountMaps(marketIndex: number, writable: boolean, oracleAccountMap: Map<string, AccountMeta>, spotMarketAccountMap: Map<number, AccountMeta>): void;
+    /**
+     * Appends each builder's `User` (sub-account 0) and `RevenueShare` account metas to
+     * `remainingAccounts` (writable), deduping by pubkey so an authority that is both a builder and a
+     * referrer isn't pushed twice — the on-chain revenue-share account loader rejects duplicates and
+     * would abort the whole instruction.
+     * @param builders - Builder authority public keys to include.
+     * @param remainingAccounts - Array mutated in place by appending the builder account metas.
+     */
     addBuilderToRemainingAccounts(builders: PublicKey[], remainingAccounts: AccountMeta[]): void;
+    /**
+     * Builds the deduplicated oracle/spot-market/perp-market account-meta maps needed to cover every
+     * non-empty position across a set of user accounts (e.g. taker + makers in a fill), including the
+     * quote spot market whenever a spot position has open orders. All accounts are added read-only.
+     * @param userAccounts - User accounts whose open positions determine which markets to include.
+     * @returns The three account-meta maps, keyed by oracle pubkey string / spot market index / perp
+     * market index respectively.
+     */
     getRemainingAccountMapsForUsers(userAccounts: UserAccount[]): {
         oracleAccountMap: Map<string, AccountMeta>;
         spotMarketAccountMap: Map<number, AccountMeta>;
@@ -372,7 +1159,7 @@ export declare class VelocityClient {
      *
      * `orderId` is the monotonically incrementing u32 counter that the program assigns at
      * placement time — it is not known until the place instruction executes on-chain. Use
-     * {@link getOrderByUserId} when you need to look up an order by the caller-supplied
+     * `getOrderByUserId` when you need to look up an order by the caller-supplied
      * `userOrderId` instead.
      *
      * Returns `undefined` when the order is not found (already filled, cancelled, or the
@@ -382,54 +1169,164 @@ export declare class VelocityClient {
     /**
      * Look up an open order by the caller-supplied `userOrderId` from the cached user account.
      *
-     * `userOrderId` is a 1-255 slot chosen by the caller in {@link OrderParams} and is stable
+     * `userOrderId` is a 1-255 slot chosen by the caller in `OrderParams` and is stable
      * across the life of the order — useful when you need to reference an order before the
-     * program-assigned {@link Order.orderId} is known (e.g. immediately after placing without
-     * waiting for confirmation). Use {@link getOrder} when you have the program-assigned ID.
+     * program-assigned `Order.orderId` is known (e.g. immediately after placing without
+     * waiting for confirmation). Use `getOrder` when you have the program-assigned ID.
      *
      * Returns `undefined` when the order is not found (already filled, cancelled, or the
      * account cache is stale).
      */
     getOrderByUserId(userOrderId: number, subAccountId?: number): Order | undefined;
     /**
-     * Get the associated token address for the given spot market
-     * @param marketIndex
-     * @param useNative
-     * @param tokenProgram
+     * Resolves the token account to use for a spot market's mint. For the wrapped-SOL market with
+     * `useNative = true` (the default), returns `authority` itself (native SOL, no wrapping) rather
+     * than an SPL associated token account; for every other market (or `useNative = false`), returns
+     * the derived associated token account address (not guaranteed to exist on-chain — see
+     * `getAssociatedTokenAccountCreationIx`).
+     * @param marketIndex - Spot market index whose mint the token account is for.
+     * @param useNative - If `true` (default) and the market is wrapped SOL, return `authority` directly
+     * instead of an ATA.
+     * @param tokenProgram - Token program the mint belongs to; defaults to the classic SPL Token program.
+     * @param authority - Wallet the token account belongs to; defaults to `this.wallet.publicKey`.
+     * @param allowOwnerOffCurve - Passed through to `getAssociatedTokenAddress`; set `true` for PDA owners.
+     * @returns The resolved token account address (or `authority`, for native SOL).
      */
     getAssociatedTokenAccount(marketIndex: number, useNative?: boolean, tokenProgram?: PublicKey, authority?: PublicKey, allowOwnerOffCurve?: boolean): Promise<PublicKey>;
+    /**
+     * Builds an `CreateIdempotent` associated-token-account instruction (creates `account` if it
+     * doesn't already exist; no-ops without failing if it does), constructed manually rather than via
+     * `@solana/spl-token`'s helper.
+     * @param account - Associated token account address to create.
+     * @param payer - Pays for the account creation; must sign the transaction.
+     * @param owner - Token account owner.
+     * @param mint - Mint the token account is for.
+     * @param tokenProgram - Token program the mint belongs to; defaults to the classic SPL Token program.
+     * @returns The `CreateIdempotent` instruction.
+     */
     createAssociatedTokenAccountIdempotentInstruction(account: PublicKey, payer: PublicKey, owner: PublicKey, mint: PublicKey, tokenProgram?: PublicKey): TransactionInstruction;
+    /**
+     * Builds the full instruction sequence for a deposit, without sending a transaction. If
+     * `associatedTokenAccount` equals the signer and the market is wrapped SOL, transparently wraps
+     * native SOL first (creates a temporary wrapped-SOL account funded with `amount`, deposits from it,
+     * then closes it at the end of the same transaction, refunding rent to the signer) — otherwise
+     * deposits directly from `associatedTokenAccount`.
+     * @param amount - Amount to deposit, in the spot market's own token precision (`10^mint.decimals`).
+     * @param marketIndex - Spot market index to deposit into.
+     * @param associatedTokenAccount - Source token account (or the signer's own pubkey, for native SOL).
+     * @param subAccountId - Sub-account id to credit; defaults to `this.activeSubAccountId`.
+     * @param reduceOnly - If `true`, the deposit is capped so it cannot flip/increase a net borrow
+     * position beyond what's needed to reach zero (used to repay a borrow without over-depositing).
+     * @param overrides.authority - Signer/depositor authority; defaults to `this.wallet.publicKey`.
+     * @returns The ordered list of instructions (wrap SOL, deposit, unwrap SOL as applicable).
+     */
     getDepositTxnIx(amount: BN, marketIndex: number, associatedTokenAccount: PublicKey, subAccountId?: number, reduceOnly?: boolean, overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Builds (but does not send) a single transaction that deposits collateral and then places a
+     * pre-signed SignedMsg ("swift") taker perp order in one atomic bundle — useful for funding a new
+     * or under-collateralized account immediately before submitting an off-chain-signed order.
+     * Optionally also initializes the taker's `SignedMsgUserOrders` account (with 8 order slots) first,
+     * if it doesn't already exist.
+     * @param signedOrderParams - The pre-signed SignedMsg order message/params to place.
+     * @param takerInfo - Taker's user/user-stats accounts, loaded `UserAccount` data, and the signing
+     * authority for the order message.
+     * @param depositAmount - Amount to deposit, in `depositSpotMarketIndex`'s token precision.
+     * @param depositSpotMarketIndex - Spot market index to deposit into.
+     * @param tradePerpMarketIndex - Perp market index the signed order trades.
+     * @param subAccountId - Sub-account id to deposit into and place the order for.
+     * @param takerAssociatedTokenAccount - Source token account for the deposit.
+     * @param initSwiftAccount - If `true`, initializes the taker's `SignedMsgUserOrders` account first
+     * when it doesn't already exist; defaults to `false`.
+     * @returns Nothing — currently discards the built transaction rather than returning or sending it
+     * (likely a bug: the built `VersionedTransaction`/`Transaction` from `buildTransaction` is neither
+     * returned nor passed to `sendTransaction`).
+     */
     buildSwiftDepositTx(signedOrderParams: SignedMsgOrderParams, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
         takerUserAccount: UserAccount;
         signingAuthority: PublicKey;
     }, depositAmount: BN, depositSpotMarketIndex: number, tradePerpMarketIndex: number, subAccountId: number, takerAssociatedTokenAccount: PublicKey, initSwiftAccount?: boolean): Promise<void>;
+    /**
+     * Builds (via `getDepositTxnIx`) and wraps a full deposit transaction, without sending it.
+     * Optionally also initializes the depositor's `SignedMsgUserOrders` account first, if it doesn't
+     * already exist. Forces `computeUnits` to `800_000` regardless of `txParams`/`this.txParams`.
+     * @param amount - Amount to deposit, in the spot market's own token precision.
+     * @param marketIndex - Spot market index to deposit into.
+     * @param associatedTokenAccount - Source token account (or the signer's own pubkey, for native SOL).
+     * @param subAccountId - Sub-account id to credit; defaults to `this.activeSubAccountId`.
+     * @param reduceOnly - If `true`, caps the deposit so it cannot exceed what's needed to zero out an
+     * existing borrow.
+     * @param txParams - Optional compute-unit-price/other overrides; `computeUnits` is always
+     * overridden to `800_000`.
+     * @param initSwiftAccount - If `true`, initializes the signer's `SignedMsgUserOrders` account first
+     * when it doesn't already exist; defaults to `false`.
+     * @param overrides.authority - Signer/depositor authority; defaults to `this.wallet.publicKey`.
+     * @returns The built (unsigned/unsent) transaction.
+     */
     createDepositTxn(amount: BN, marketIndex: number, associatedTokenAccount: PublicKey, subAccountId?: number, reduceOnly?: boolean, txParams?: TxParams, initSwiftAccount?: boolean, overrides?: {
         authority?: PublicKey;
     }): Promise<VersionedTransaction | Transaction>;
     /**
-     * Deposit funds into the given spot market
-     *
-     * @param amount to deposit
-     * @param marketIndex spot market index to deposit into
-     * @param associatedTokenAccount can be the wallet public key if using native sol
-     * @param subAccountId subaccountId to deposit
-     * @param reduceOnly if true, deposit must not increase account risk
-     * @param txParams transaction parameters
-     * @param initSwiftAccount if true, initialize a swift account for the user
-     * @param overrides allows overriding authority for the deposit transaction
+     * Deposits collateral into a spot market for a sub-account: builds (`createDepositTxn`), signs, and
+     * sends the transaction, then caches the confirming slot for this market so subsequent instructions
+     * built by this client can use the freshest oracle/market data.
+     * @param amount - Amount to deposit, in the spot market's own token precision (`10^mint.decimals`,
+     * e.g. QUOTE_PRECISION (1e6) for USDC).
+     * @param marketIndex - Spot market index to deposit into.
+     * @param associatedTokenAccount - Source token account; can be the wallet's own public key when
+     * depositing native SOL into the wrapped-SOL market (see `getAssociatedTokenAccount`).
+     * @param subAccountId - Sub-account id to credit; defaults to `this.activeSubAccountId`.
+     * @param reduceOnly - If `true`, caps the deposit so it cannot exceed what's needed to fully repay
+     * an existing borrow (never opens/increases a deposit position); defaults to `false`.
+     * @param txParams - Optional transaction parameters; `computeUnits` is always forced to `800_000`.
+     * @param initSwiftAccount - If `true`, also initializes the signer's `SignedMsgUserOrders` account
+     * first if it doesn't exist; defaults to `false`.
+     * @param overrides.authority - Signer/depositor authority; defaults to `this.wallet.publicKey`.
+     * @returns The transaction signature.
+     * @throws (on-chain) if the sub-account's `poolId` doesn't match the spot market's pool, the market
+     * is uninitialized/paused for deposits, or `amount` is `0`.
      */
     deposit(amount: BN, marketIndex: number, associatedTokenAccount: PublicKey, subAccountId?: number, reduceOnly?: boolean, txParams?: TxParams, initSwiftAccount?: boolean, overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the raw `deposit` instruction (no SOL-wrapping helpers — see `getDepositTxnIx` for the
+     * full sequence). Assembles `remaining_accounts` from the target sub-account's current positions
+     * (forcing a fresh fetch when `userInitialized` is `true`) plus the market's mint and, if the mint
+     * uses a transfer hook, its extra account metas.
+     * @param amount - Amount to deposit, in the spot market's own token precision.
+     * @param marketIndex - Spot market index to deposit into.
+     * @param userTokenAccount - Source token account for the deposit.
+     * @param subAccountId - Sub-account id to credit; defaults to `this.activeSubAccountId`.
+     * @param reduceOnly - If `true`, caps the deposit at what's needed to repay an existing borrow.
+     * @param userInitialized - Set `false` only when depositing as part of creating a brand-new user
+     * account in the same transaction (skips fetching/using existing position data).
+     * @param overrides.authority - Signer/depositor authority; defaults to `this.wallet.publicKey`.
+     * @returns The `deposit` instruction.
+     * @throws if `userInitialized` is `true` but the user account fails to load after a forced fetch.
+     */
     getDepositInstruction(amount: BN, marketIndex: number, userTokenAccount: PublicKey, subAccountId?: number, reduceOnly?: boolean, userInitialized?: boolean, overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
     private checkIfAccountExists;
+    /**
+     * Builds the instructions to create and fund a temporary wrapped-SOL token account (via
+     * `createAccountWithSeed` + `initializeAccount`, no keypair required — derived deterministically
+     * from `authority` and a random seed). The caller is responsible for closing it after use (see the
+     * `createCloseAccountInstruction` pattern in `getDepositTxnIx`).
+     * @param amount - Lamport amount to wrap (native SOL to make available as wrapped SOL).
+     * @param includeRent - If `true`, funds the account with `amount` plus an extra
+     * `LAMPORTS_PER_SOL / 100` (0.01 SOL) rent buffer; if falsy, funds with only the rent buffer (no
+     * `amount`).
+     * @param overrides.authority - Owner/payer of the wrapped-SOL account; defaults to
+     * `this.wallet.publicKey`.
+     * @returns `ixs` (create + initialize instructions), `pubkey` (the new wrapped-SOL account
+     * address), and `signers` (always empty — no keypair signature is needed for a seed-derived
+     * account).
+     */
     getWrappedSolAccountCreationIxs(amount: BN, includeRent?: boolean, overrides?: {
         authority?: PublicKey;
     }): Promise<{
@@ -438,12 +1335,84 @@ export declare class VelocityClient {
         signers: Signer[];
         pubkey: PublicKey;
     }>;
+    /**
+     * Returns the correct SPL token program (classic or Token-2022) for a spot market's mint, based on
+     * its `tokenProgramFlag`.
+     * @param spotMarketAccount - Spot market whose mint's token program is needed.
+     * @returns `TOKEN_2022_PROGRAM_ID` or `TOKEN_PROGRAM_ID`.
+     */
     getTokenProgramForSpotMarket(spotMarketAccount: SpotMarketAccount): PublicKey;
+    /**
+     * Checks whether a spot market's mint belongs to the Token-2022 program.
+     * @param spotMarketAccount - Spot market to check.
+     * @returns `true` if the market's `tokenProgramFlag` has the `Token2022` bit set.
+     */
     isToken2022(spotMarketAccount: SpotMarketAccount): boolean;
+    /**
+     * Checks whether a spot market's mint has a Token-2022 transfer hook, requiring extra account
+     * metas to be appended on any instruction that moves its tokens.
+     * @param spotMarketAccount - Spot market to check.
+     * @returns `true` if the market's `tokenProgramFlag` has the `TransferHook` bit set.
+     */
     isTransferHook(spotMarketAccount: SpotMarketAccount): boolean;
+    /**
+     * Appends a spot market's mint as a read-only remaining account, but only when the mint is
+     * Token-2022 (the classic SPL Token program doesn't need the mint passed for transfers). No-op for
+     * classic SPL Token mints.
+     * @param spotMarketAccount - Spot market whose mint may need to be included.
+     * @param remainingAccounts - Array mutated in place by appending the mint account meta, if needed.
+     */
     addTokenMintToRemainingAccounts(spotMarketAccount: SpotMarketAccount, remainingAccounts: AccountMeta[]): void;
+    /**
+     * Resolves and appends the Token-2022 transfer-hook program's extra required account metas for a
+     * mint. Required on any instruction transferring tokens for a mint where `isTransferHook` is `true`
+     * (e.g. deposits/withdrawals/transfers involving that market).
+     * @param mint - Transfer-hook mint to resolve extra accounts for.
+     * @param remainingAccounts - Array mutated in place by appending the resolved extra account metas.
+     */
     addExtraAccountMetasToRemainingAccounts(mint: PublicKey, remainingAccounts: AccountMeta[]): Promise<void>;
+    /**
+     * Builds a (non-idempotent) instruction to create an associated token account owned by
+     * `this.wallet.publicKey`, paid for by `this.wallet.publicKey`.
+     * @param tokenMintAddress - Mint the associated token account is for.
+     * @param associatedTokenAddress - Associated token account address to create.
+     * @param tokenProgram - Token program the mint belongs to.
+     * @returns The create-associated-token-account instruction.
+     */
     getAssociatedTokenAccountCreationIx(tokenMintAddress: PublicKey, associatedTokenAddress: PublicKey, tokenProgram: PublicKey): TransactionInstruction;
+    /**
+     * Builds the full instruction sequence to create a new sub-account and fund it with an initial
+     * deposit in one transaction, without sending it. Handles: initializing `UserStats` (for
+     * `subAccountId === 0`) and the `SignedMsgUserOrders` account if missing, wrapping native SOL when
+     * depositing/donating SOL, creating the depositor's associated token account for Token-2022 mints
+     * if it doesn't exist, sourcing the deposit either from a token account or (if `fromSubAccountId` is
+     * given) via an internal transfer from another of the authority's sub-accounts, an optional donation
+     * to the market's revenue pool, an optional custom margin ratio, and unwrapping any temporary SOL
+     * account at the end.
+     * @param amount - Amount to deposit, in `marketIndex`'s token precision.
+     * @param userTokenAccount - Source token account for the deposit (ignored if `fromSubAccountId` is
+     * set, or replaced with a temporary wrapped-SOL account for a SOL deposit from the depositor).
+     * @param marketIndex - Spot market index to deposit into; defaults to `0` (quote/USDC).
+     * @param subAccountId - New sub-account id to create; defaults to `0`.
+     * @param name - Display name for the new sub-account; see `getInitializeUserAccountIxs` for the
+     * default.
+     * @param fromSubAccountId - If set, sources the deposit via an internal transfer from this other
+     * sub-account of the same authority instead of from `userTokenAccount`.
+     * @param referrerInfo - Referrer's `referrer`/`referrerStats` public keys, if attributing this
+     * account to a referrer.
+     * @param donateAmount - Additional lamport amount to donate to spot market index `1`'s (SOL's, in
+     * the default market configs) revenue pool in the same transaction, funded via a temporary
+     * wrapped-SOL account regardless of `marketIndex`; defaults to none. Note the destination market for
+     * the donation is hardcoded to index `1`, not derived from `marketIndex`.
+     * @param customMaxMarginRatio - If set, also sets this sub-account's custom margin ratio (in
+     * `MARGIN_PRECISION`, 1e4 = 100%) at creation time.
+     * @param poolId - If set, also assigns the sub-account to this isolated pool at creation time.
+     * @param overrides.externalWallet - Optional external wallet to deposit/pay from instead of
+     * `this.wallet.publicKey` (the sub-account's owning `authority` is unaffected).
+     * @returns The ordered instructions and the new user account's public key.
+     * @throws if a SOL/donation amount requires a temporary wrapped-SOL account but it fails to be
+     * created.
+     */
     createInitializeUserAccountAndDepositCollateralIxs(amount: BN, userTokenAccount: PublicKey, marketIndex?: number, subAccountId?: number, name?: string, fromSubAccountId?: number, referrerInfo?: ReferrerInfo, donateAmount?: BN, customMaxMarginRatio?: number, poolId?: number, overrides?: {
         /**
          * Optional external wallet to deposit from. If provided, the deposit will be made
@@ -454,74 +1423,450 @@ export declare class VelocityClient {
         ixs: TransactionInstruction[];
         userAccountPublicKey: PublicKey;
     }>;
+    /**
+     * Builds (via `createInitializeUserAccountAndDepositCollateralIxs`) and wraps the full
+     * initialize-and-deposit transaction, without sending it. See that method for parameter semantics.
+     * @returns The built (unsigned/unsent) transaction and the new user account's public key.
+     */
     createInitializeUserAccountAndDepositCollateral(amount: BN, userTokenAccount: PublicKey, marketIndex?: number, subAccountId?: number, name?: string, fromSubAccountId?: number, referrerInfo?: ReferrerInfo, donateAmount?: BN, txParams?: TxParams, customMaxMarginRatio?: number, poolId?: number, overrides?: {
         externalWallet?: PublicKey;
     }): Promise<[Transaction | VersionedTransaction, PublicKey]>;
     /**
-     * Creates the User account for a user, and deposits some initial collateral
-     * @param amount
-     * @param userTokenAccount
-     * @param marketIndex
-     * @param subAccountId
-     * @param name
-     * @param fromSubAccountId
-     * @param referrerInfo
-     * @param donateAmount
-     * @param txParams
-     * @param customMaxMarginRatio
-     * @param poolId
+     * Creates a new sub-account and deposits initial collateral into it in a single transaction, then
+     * loads and subscribes the new sub-account via `addUser`. See
+     * `createInitializeUserAccountAndDepositCollateralIxs` for full parameter semantics.
+     * @param amount - Amount to deposit, in `marketIndex`'s token precision.
+     * @param userTokenAccount - Source token account for the deposit.
+     * @param marketIndex - Spot market index to deposit into; defaults to `0` (quote/USDC).
+     * @param subAccountId - New sub-account id to create; defaults to `0`.
+     * @param name - Display name for the new sub-account.
+     * @param fromSubAccountId - If set, sources the deposit via internal transfer from this sub-account
+     * instead of `userTokenAccount`.
+     * @param referrerInfo - Referrer's `referrer`/`referrerStats` public keys, if applicable.
+     * @param donateAmount - Additional amount to donate to the (hardcoded index `1`) revenue pool.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @param customMaxMarginRatio - If set, custom margin ratio in `MARGIN_PRECISION` (1e4 = 100%).
+     * @param poolId - If set, isolated pool id to assign the sub-account to at creation time.
      * @param overrides - Optional overrides including externalWallet for depositing from a different wallet
-     * @returns
+     * @returns A tuple of `[transactionSignature, userAccountPublicKey]`.
      */
     initializeUserAccountAndDepositCollateral(amount: BN, userTokenAccount: PublicKey, marketIndex?: number, subAccountId?: number, name?: string, fromSubAccountId?: number, referrerInfo?: ReferrerInfo, donateAmount?: BN, txParams?: TxParams, customMaxMarginRatio?: number, poolId?: number, overrides?: {
         externalWallet?: PublicKey;
     }): Promise<[TransactionSignature, PublicKey]>;
+    /**
+     * Devnet/test-only convenience: mints test tokens from a `TokenFaucet` into a fresh associated
+     * token account, then creates a new sub-account and deposits the minted amount, all in one
+     * transaction. Not usable on mainnet (no faucet exists there).
+     * @param subAccountId - New sub-account id to create; defaults to `0`.
+     * @param name - Display name for the new sub-account; defaults to `DEFAULT_USER_NAME`.
+     * @param marketIndex - Spot market index to deposit the minted tokens into.
+     * @param tokenFaucet - Faucet client used to mint test tokens.
+     * @param amount - Amount to mint and deposit, in `marketIndex`'s token precision.
+     * @param referrerInfo - Referrer's `referrer`/`referrerStats` public keys, if applicable.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns A tuple of `[transactionSignature, userAccountPublicKey]`.
+     */
     initializeUserAccountForDevnet(subAccountId: number | undefined, name: string | undefined, marketIndex: number, tokenFaucet: TokenFaucet, amount: BN, referrerInfo?: ReferrerInfo, txParams?: TxParams): Promise<[TransactionSignature, PublicKey]>;
+    /**
+     * Builds the full instruction sequence for a withdrawal, without sending a transaction. If
+     * `associatedTokenAddress` equals the signer and the market is wrapped SOL, creates a temporary
+     * wrapped-SOL account to receive the withdrawal and closes it (unwrapping to native SOL) at the end
+     * of the same transaction; otherwise, creates the destination associated token account first if it
+     * doesn't already exist.
+     * @param amount - Amount to withdraw, in the spot market's own token precision.
+     * @param marketIndex - Spot market index to withdraw from.
+     * @param associatedTokenAddress - Destination token account (or the signer's own pubkey, for native
+     * SOL).
+     * @param reduceOnly - If `true`, caps the withdrawal at the sub-account's existing deposit (and the
+     * max amount withdrawable while remaining within margin requirements) so it can never flip the
+     * position into a borrow; defaults to `false`.
+     * @param subAccountId - Sub-account id to withdraw from; defaults to `this.activeSubAccountId`.
+     * @returns The ordered list of instructions (create ATA / wrap SOL, withdraw, unwrap SOL as
+     * applicable).
+     */
     getWithdrawalIxs(amount: BN, marketIndex: number, associatedTokenAddress: PublicKey, reduceOnly?: boolean, subAccountId?: number): Promise<TransactionInstruction[]>;
     /**
-     * Withdraws from a user account. If deposit doesn't already exist, creates a borrow
-     * @param amount
-     * @param marketIndex
+     * Withdraws from a user account. If deposit doesn't already exist, creates a borrow (or increases an
+     * existing one) — unless `reduceOnly` is set. Always requires the sub-account's true owning
+     * authority to sign (`this.wallet.publicKey`); a delegate cannot withdraw at all, even with
+     * `allowDelegateTransfer` enabled.
+     * @param amount - Amount to withdraw, in the spot market's own token precision (`10^mint.decimals`,
+     * e.g. QUOTE_PRECISION (1e6) for USDC).
+     * @param marketIndex - Spot market index to withdraw from.
      * @param associatedTokenAddress - the token account to withdraw to. can be the wallet public key if using native sol
-     * @param reduceOnly
+     * @param reduceOnly - If `true`, caps the withdrawal so it can never open/increase a borrow; the
+     * on-chain amount is clamped to `min(requested, max withdrawable within margin, existing deposit)`.
+     * @param subAccountId - Sub-account id to withdraw from; defaults to `this.activeSubAccountId`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `ReduceOnlyWithdrawIncreasedRisk`) if `reduceOnly` is set but the sub-account's
+     * position in this market is already a borrow (nothing to reduce).
      */
     withdraw(amount: BN, marketIndex: number, associatedTokenAddress: PublicKey, reduceOnly?: boolean, subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Fully withdraws every spot market position on a sub-account too small to be worth carrying
+     * ("dust", as determined by `User.getSpotMarketAccountsWithDustPosition`), in one transaction. Each
+     * withdrawal requests 2x the current token amount with `reduceOnly = true` so the on-chain clamp
+     * (see `withdraw`) withdraws exactly the full balance without risking a borrow, regardless of
+     * balance drift between calculation and execution.
+     * @param subAccountId - Sub-account id to sweep; defaults to `this.activeSubAccountId`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @param opts.dustPositionCountCallback - Called once with the number of dust positions found
+     * (`0` if none), before building/sending the transaction.
+     * @returns The transaction signature, or `undefined` if there were no dust positions to withdraw.
+     */
     withdrawAllDustPositions(subAccountId?: number, txParams?: TxParams, opts?: {
         dustPositionCountCallback?: (count: number) => void;
     }): Promise<TransactionSignature | undefined>;
+    /**
+     * Builds the raw `withdraw` instruction (no SOL-wrapping/ATA-creation helpers — see
+     * `getWithdrawalIxs` for the full sequence). Signed by `this.wallet.publicKey`, which must be the
+     * sub-account's true owning authority (delegates cannot withdraw).
+     * @param amount - Amount to withdraw, in the spot market's own token precision.
+     * @param marketIndex - Spot market index to withdraw from.
+     * @param userTokenAccount - Destination token account for the withdrawal.
+     * @param reduceOnly - If `true`, caps the withdrawal so it can never open/increase a borrow.
+     * @param subAccountId - Sub-account id to withdraw from; defaults to `this.activeSubAccountId`.
+     * @returns The `withdraw` instruction.
+     */
     getWithdrawIx(amount: BN, marketIndex: number, userTokenAccount: PublicKey, reduceOnly?: boolean, subAccountId?: number): Promise<TransactionInstruction>;
     /**
-     * Withdraws from the fromSubAccount and deposits into the toSubAccount
-     * @param amount
-     * @param marketIndex
-     * @param fromSubAccountId
-     * @param toSubAccountId
-     * @param txParams
+     * Transfers a spot balance directly between two sub-accounts owned by `this.wallet.publicKey`
+     * (withdraws from `fromSubAccountId`, deposits into `toSubAccountId`) without leaving the program —
+     * no token account round-trip. Signed by `this.wallet.publicKey`, which must literally be the
+     * `authority` on *both* sub-accounts (this is the owner-to-owner path; a delegate must use
+     * `transferDepositByDelegate` instead).
+     * @param amount - Amount to transfer, in the spot market's own token precision.
+     * @param marketIndex - Spot market index of the balance to transfer.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `UserBankrupt`) if either sub-account is bankrupt, or
+     * (`CantTransferBetweenSameUserAccount`) if `fromSubAccountId === toSubAccountId`.
      */
     transferDeposit(amount: BN, marketIndex: number, fromSubAccountId: number, toSubAccountId: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferDeposit` instruction. See `transferDeposit` for semantics/preconditions.
+     * Uses an already-loaded `from` sub-account's cached data if available (to build
+     * `remaining_accounts` from its current positions); otherwise fetches it directly via RPC.
+     * @param amount - Amount to transfer, in the spot market's own token precision.
+     * @param marketIndex - Spot market index of the balance to transfer.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @returns The instruction.
+     */
     getTransferDepositIx(amount: BN, marketIndex: number, fromSubAccountId: number, toSubAccountId: number): Promise<TransactionInstruction>;
+    /**
+     * Like `transferDeposit`, but signed by a *delegate* (`this.wallet.publicKey`) rather than the
+     * sub-accounts' owning authority. On-chain requires all of:
+     *   - the owner has opted in via `updateUserAllowDelegateTransfer(true)` on their `UserStats` — the
+     *     transfer is rejected outright otherwise, regardless of delegate status on the sub-accounts;
+     *   - `this.wallet.publicKey` is set as the `delegate` on **both** `fromSubAccountId` and
+     *     `toSubAccountId` (see `updateUserDelegate`) — a delegate for only one side is not sufficient;
+     *   - both sub-accounts share the same owning `authority` (this only moves funds within one owner's
+     *     sub-accounts, never across different owners);
+     *   - neither sub-account is bankrupt, and `fromSubAccountId !== toSubAccountId`.
+     * @param amount - Amount to transfer, in the spot market's own token precision.
+     * @param marketIndex - Spot market index of the balance to transfer.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @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
+     * both sub-accounts, if the sub-accounts have different owners, if either is bankrupt, or if
+     * `fromSubAccountId === toSubAccountId`.
+     */
     transferDepositByDelegate(amount: BN, marketIndex: number, fromSubAccountId: number, toSubAccountId: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferDepositByDelegate` instruction. See `transferDepositByDelegate` for the full
+     * set of on-chain preconditions. Uses an already-loaded `from` sub-account's cached data if
+     * available; otherwise fetches it directly via RPC. Sub-accounts are derived under `this.authority`
+     * (the sub-accounts' owner), not `this.wallet.publicKey` (the delegate signer).
+     * @param amount - Amount to transfer, in the spot market's own token precision.
+     * @param marketIndex - Spot market index of the balance to transfer.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @returns The instruction.
+     */
     getTransferDepositByDelegateIx(amount: BN, marketIndex: number, fromSubAccountId: number, toSubAccountId: number): Promise<TransactionInstruction>;
+    /**
+     * Moves a deposit balance and/or a borrow balance for the same underlying mint between two
+     * sub-accounts owned by `this.wallet.publicKey` that sit in *different* isolated pools, in one
+     * on-chain instruction (`transferPools`). Unlike `transferDeposit` (which only moves a single spot
+     * balance and requires same-pool markets), this requires: `depositFromMarketIndex`/
+     * `depositToMarketIndex` to share a mint but different `poolId`s, `borrowFromMarketIndex`/
+     * `borrowToMarketIndex` to likewise share a mint but different pool ids, and the deposit-from/
+     * borrow-from markets to share `fromSubAccountId`'s pool while the deposit-to/borrow-to markets
+     * share `toSubAccountId`'s pool. Both sub-accounts must be re-validated against their initial
+     * margin requirement after the move.
+     * @param depositFromMarketIndex - Spot market to debit the deposit leg from.
+     * @param depositToMarketIndex - Spot market to credit the deposit leg to (same mint, different pool).
+     * @param borrowFromMarketIndex - Spot market to credit (repay) the borrow leg from.
+     * @param borrowToMarketIndex - Spot market to debit (re-open) the borrow leg on.
+     * @param depositAmount - Deposit amount to move, in the deposit market's token precision;
+     * `undefined`/omitted moves the entire existing deposit token amount; `0` skips the deposit leg
+     * entirely.
+     * @param borrowAmount - Borrow amount to move, in the borrow market's token precision; `undefined`
+     * moves the entire existing borrow token amount; `0` skips the borrow leg entirely.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `InvalidPoolId`) if the mint/pool relationships above don't hold, or
+     * (`UserBankrupt`/`CantTransferBetweenSameUserAccount`) for the same preconditions as `transferDeposit`.
+     */
     transferPools(depositFromMarketIndex: number, depositToMarketIndex: number, borrowFromMarketIndex: number, borrowToMarketIndex: number, depositAmount: BN | undefined, borrowAmount: BN | undefined, fromSubAccountId: number, toSubAccountId: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferPools` instruction. See `transferPools` for full semantics/preconditions.
+     * @param depositFromMarketIndex - Spot market to debit the deposit leg from.
+     * @param depositToMarketIndex - Spot market to credit the deposit leg to.
+     * @param borrowFromMarketIndex - Spot market to credit (repay) the borrow leg from.
+     * @param borrowToMarketIndex - Spot market to debit (re-open) the borrow leg on.
+     * @param depositAmount - Deposit amount to move, in the deposit market's token precision;
+     * `undefined` moves the entire deposit, `0` skips the deposit leg.
+     * @param borrowAmount - Borrow amount to move, in the borrow market's token precision; `undefined`
+     * moves the entire borrow, `0` skips the borrow leg.
+     * @param fromSubAccountId - Sub-account id to debit.
+     * @param toSubAccountId - Sub-account id to credit.
+     * @param isToNewSubAccount - If `true`, skips including `toSubAccountId`'s current `UserAccount` data
+     * when building `remaining_accounts` (use when `toSubAccountId` is being created in the same
+     * transaction and has no on-chain data yet).
+     * @returns The instruction.
+     */
     getTransferPoolsIx(depositFromMarketIndex: number, depositToMarketIndex: number, borrowFromMarketIndex: number, borrowToMarketIndex: number, depositAmount: BN | undefined, borrowAmount: BN | undefined, fromSubAccountId: number, toSubAccountId: number, isToNewSubAccount?: boolean): Promise<TransactionInstruction>;
+    /**
+     * Moves all or part of an open perp position from one sub-account to another via the
+     * `transferPerpPosition` instruction, settling funding on both sides first. The signer
+     * (`this.wallet.publicKey`) must independently satisfy `can_sign_for_user` (be the owning
+     * `authority` or the sub-account's `delegate`) on *both* `fromSubAccountId` and `toSubAccountId` —
+     * unlike `transferDepositByDelegate`, there is no separate `allowDelegateTransfer` opt-in gate, and
+     * the two sub-accounts are not required to share the same owning authority.
+     * @param fromSubAccountId - Sub-account id to debit the position from.
+     * @param toSubAccountId - Sub-account id to credit the position to.
+     * @param marketIndex - Perp market index of the position to transfer.
+     * @param amount - Signed base amount to transfer, in `BASE_PRECISION` (1e9). Must have the same sign
+     * as `fromSubAccountId`'s existing position (i.e. it only reduces/closes that position, never
+     * flips it) and a magnitude at most the position's size and a multiple of the market's step size;
+     * pass `undefined` to transfer the entire position.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `UserBankrupt`/`CantTransferBetweenSameUserAccount`) for the standard transfer
+     * preconditions, or `InvalidTransferPerpPosition` if the oracle is invalid, fills are paused for
+     * `marketIndex`, `amount`'s sign/magnitude/step-size don't satisfy the constraints above, or
+     * `fromSubAccountId` has no position in `marketIndex`.
+     */
     transferPerpPosition(fromSubAccountId: number, toSubAccountId: number, marketIndex: number, amount: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferPerpPosition` instruction. See `transferPerpPosition` for full semantics.
+     * @param fromSubAccountId - Sub-account id to debit the position from.
+     * @param toSubAccountId - Sub-account id to credit the position to.
+     * @param marketIndex - Perp market index of the position to transfer.
+     * @param amount - Signed base amount to transfer, in `BASE_PRECISION` (1e9); `undefined`/`null`
+     * transfers the entire position. See `transferPerpPosition` for sign/magnitude constraints.
+     * @returns The instruction.
+     */
     getTransferPerpPositionIx(fromSubAccountId: number, toSubAccountId: number, marketIndex: number, amount: BN): Promise<TransactionInstruction>;
+    /**
+     * Special-account-only: transfers all or part of a position on the protocol's designated "vAMM
+     * hedger" account directly into the AMM's own inventory, offsetting the vAMM's synthetic position.
+     * On-chain requires `userAccountPublicKey`'s `specialUserStatus` to be `VammHedger`, the position's
+     * direction to already be opposite the AMM's net inventory (`amm.baseAssetAmountWithAmm`), and the
+     * transferred amount to fit within the AMM's available capacity for that direction. Not usable on a
+     * regular trading sub-account.
+     * @param userAccountPublicKey - The vAMM-hedger `User` PDA to transfer from; must already be loaded
+     * in `this.users` (see `getUsers`).
+     * @param marketIndex - Perp market index of the position to transfer.
+     * @param amount - Signed base amount to transfer, in `BASE_PRECISION` (1e9), matching the position's
+     * sign and capped at its size and a multiple of the market's step size; omit to transfer the entire
+     * position.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain) if the account isn't a `VammHedger`, has no (or a same-direction-as-AMM)
+     * position in `marketIndex`, or `amount` fails the sign/magnitude/step-size/AMM-capacity checks.
+     */
     specialTransferPerpPositionToVamm(userAccountPublicKey: PublicKey, marketIndex: number, amount?: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `specialTransferPerpPositionToVamm` instruction. See
+     * `specialTransferPerpPositionToVamm` for full semantics/preconditions.
+     * @param userAccountPublicKey - The vAMM-hedger `User` PDA to transfer from.
+     * @param marketIndex - Perp market index of the position to transfer.
+     * @param amount - Signed base amount to transfer, in `BASE_PRECISION` (1e9); omit to transfer the
+     * entire position.
+     * @returns The instruction.
+     * @throws if `userAccountPublicKey` isn't among `this.getUsers()`.
+     */
     getSpecialTransferPerpPositionToVammIx(userAccountPublicKey: PublicKey, marketIndex: number, amount?: BN): Promise<TransactionInstruction>;
+    /**
+     * Deposits collateral from a token account directly into an isolated perp position's own segregated
+     * balance (as opposed to `deposit`, which credits the sub-account's general/cross balance). The
+     * position's quote spot market is derived from `perpMarketIndex`'s `quoteSpotMarketIndex`.
+     * @param amount - Amount to deposit, in the position's quote spot market's token precision.
+     * @param perpMarketIndex - Perp market index of the isolated position to fund.
+     * @param userTokenAccount - Source token account for the deposit.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     * @throws (on-chain `InvalidPoolId`) if the sub-account's pool doesn't match the spot/perp markets'.
+     */
     depositIntoIsolatedPerpPosition(amount: BN, perpMarketIndex: number, userTokenAccount: PublicKey, subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `depositIntoIsolatedPerpPosition` instruction. See `depositIntoIsolatedPerpPosition` for
+     * semantics.
+     * @param amount - Amount to deposit, in the position's quote spot market's token precision.
+     * @param perpMarketIndex - Perp market index of the isolated position to fund.
+     * @param userTokenAccount - Source token account for the deposit.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @returns The instruction.
+     */
     getDepositIntoIsolatedPerpPositionIx(amount: BN, perpMarketIndex: number, userTokenAccount: PublicKey, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Moves collateral between an isolated perp position's segregated balance and the sub-account's
+     * general/cross balance, in the same underlying quote spot market (derived from `perpMarketIndex`).
+     * Positive `amount` moves collateral **from general into the isolated position**; negative moves it
+     * **from the isolated position back to general**. If the requested outflow from the isolated
+     * position would exceed its current deposit (i.e. it needs unrealized PnL to be realized first, or
+     * the caller wants to withdraw everything), prepends a `TRY_SETTLE` settle-PnL instruction for
+     * `perpMarketIndex` before the transfer.
+     * @param amount - Signed amount to move, in the quote spot market's token precision (e.g.
+     * QUOTE_PRECISION (1e6) for USDC); positive = into the isolated position, negative = out of it. Pass
+     * `MIN_I64` to move the entire isolated deposit back to general.
+     * @param perpMarketIndex - Perp market index of the isolated position.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @param trySettle - If `true`, always prepends the `TRY_SETTLE` instruction even if not otherwise
+     * inferred as necessary.
+     * @param noBuffer - If `true`, sends `amount` unmodified; otherwise (default) adds a 0.5% buffer to
+     * the requested amount to absorb price movement between build and execution. Has no effect when
+     * `amount` is `MIN_I64`.
+     * @returns The transaction signature. Sent with `skipPreflight: true`.
+     */
     transferIsolatedPerpPositionDeposit(amount: BN, perpMarketIndex: number, subAccountId?: number, txParams?: TxParams, trySettle?: boolean, noBuffer?: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferIsolatedPerpPositionDeposit` instruction (without the `TRY_SETTLE` prepend —
+     * see `transferIsolatedPerpPositionDeposit` for the full sequence). See that method for the
+     * sign/precision convention of `amount`.
+     * @param amount - Signed amount to move, in the quote spot market's token precision; positive = into
+     * the isolated position, negative = out. Pass `MIN_I64` to move the entire isolated deposit out.
+     * @param perpMarketIndex - Perp market index of the isolated position.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @param noAmountBuffer - If `true`, sends `amount` unmodified; otherwise adds a 0.5% buffer
+     * (ignored when `amount` is `MIN_I64`).
+     * @param signingAuthority - Signer for the instruction; defaults to `this.wallet.publicKey`.
+     * @returns The instruction.
+     */
     getTransferIsolatedPerpPositionDepositIx(amount: BN, perpMarketIndex: number, subAccountId?: number, noAmountBuffer?: boolean, signingAuthority?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Withdraws collateral out of the protocol directly from an isolated perp position's segregated
+     * balance to a token account (as opposed to `withdraw`, which draws from the sub-account's
+     * general/cross balance). See `getWithdrawFromIsolatedPerpPositionIxsBundle` for the settle-PnL and
+     * amount-clamping logic applied first.
+     * @param amount - Amount to withdraw, in the position's quote spot market's token precision.
+     * @param perpMarketIndex - Perp market index of the isolated position to withdraw from.
+     * @param userTokenAccount - Destination token account for the withdrawal.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     withdrawFromIsolatedPerpPosition(amount: BN, perpMarketIndex: number, userTokenAccount: PublicKey, subAccountId?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the full instruction sequence for `withdrawFromIsolatedPerpPosition`: computes the position's
+     * claimable unrealized PnL, and clamps `amount` to the isolated deposit plus that claimable PnL —
+     * the on-chain `amount` is `u64` with no "withdraw all" sentinel (unlike the sibling
+     * `transferIsolatedPerpPositionDeposit`, whose `i64` `amount` treats `i64::MIN` as one), so passing
+     * `BN` values larger than the withdrawable balance is how a caller requests "withdraw everything".
+     * Also prepends a `TRY_SETTLE` settle-PnL instruction for `perpMarketIndex` whenever the request
+     * draws into unrealized (unsettled) PnL. Note the clamp is a build-time estimate: if the settle
+     * realizes less than the claimable PnL (e.g. the market's PnL pool is short), the withdraw can still
+     * fail on-chain with `InsufficientCollateral`.
+     * @param amount - Amount to withdraw, in the position's quote spot market's token precision. Values
+     * exceeding the withdrawable balance are clamped to it (i.e. pass a huge value to withdraw all).
+     * @param perpMarketIndex - Perp market index of the isolated position to withdraw from.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @param userTokenAccount - Destination token account; defaults to the signer's own associated token
+     * account for the position's quote spot market.
+     * @returns The ordered instructions (optional settle-PnL, then withdraw).
+     * @throws if `subAccountId` has no perp position in `perpMarketIndex`, or if the position has no
+     * withdrawable collateral (deposit plus claimable PnL is zero or negative).
+     */
     getWithdrawFromIsolatedPerpPositionIxsBundle(amount: BN, perpMarketIndex: number, subAccountId?: number, userTokenAccount?: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Builds the raw `withdrawFromIsolatedPerpPosition` instruction (no settle-PnL/clamping — see
+     * `getWithdrawFromIsolatedPerpPositionIxsBundle` for the full sequence).
+     * @param amount - Amount to withdraw, in the position's quote spot market's token precision.
+     * The on-chain `amount` arg is `u64` (unsigned) with no "withdraw all" sentinel — the exact amount
+     * is withdrawn, and it must not exceed the isolated position's token balance. Use
+     * `getWithdrawFromIsolatedPerpPositionIxsBundle` for withdraw-all/clamping behavior.
+     * @param perpMarketIndex - Perp market index of the isolated position to withdraw from.
+     * @param userTokenAccount - Destination token account for the withdrawal.
+     * @param subAccountId - Sub-account id owning the position; defaults to `this.activeSubAccountId`.
+     * @returns The instruction.
+     */
     getWithdrawFromIsolatedPerpPositionIx(amount: BN, perpMarketIndex: number, userTokenAccount: PublicKey, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Permissionless crank: forces a spot market to accrue interest (updating
+     * `cumulativeDepositInterest`/`cumulativeBorrowInterest` and TWAP stats) up to the current slot. The
+     * instruction's accounts impose no authority/hot-role check beyond the transaction fee payer —
+     * anyone can call this to keep a market's interest current between organic deposit/withdraw/borrow
+     * activity.
+     * @param marketIndex - Spot market index to update.
+     * @param txParams - Optional compute-unit/priority-fee overrides for the transaction.
+     * @returns The transaction signature.
+     */
     updateSpotMarketCumulativeInterest(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketCumulativeInterest` instruction. See
+     * `updateSpotMarketCumulativeInterest` for semantics.
+     * @param marketIndex - Spot market index to update.
+     * @returns The instruction.
+     */
     updateSpotMarketCumulativeInterestIx(marketIndex: number): Promise<TransactionInstruction>;
     /**
-     * @deprecated use {@link placePerpOrder} or {@link placeAndTakePerpOrder} instead
+     * Opens/increases a perp position with a market order (or a limit order if `limitPrice` is
+     * given), filled immediately against the AMM/makers via `placeAndTakePerpOrder`.
+     * @deprecated use `placePerpOrder` or `placeAndTakePerpOrder` instead.
+     * @param direction - `LONG` or `SHORT`.
+     * @param amount - Base asset amount to trade, BASE_PRECISION (1e9).
+     * @param marketIndex - Perp market index.
+     * @param limitPrice - Optional limit price, PRICE_PRECISION (1e6); omit for a pure market order.
+     * @param subAccountId - Sub-account to trade from; defaults to the active sub-account.
+     * @returns The transaction signature.
      */
     openPosition(direction: PositionDirection, amount: BN, marketIndex: number, limitPrice?: BN, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Submits and confirms a transaction that has already been fully signed elsewhere (e.g. by an
+     * external/hardware wallet flow), skipping this client's normal build-and-sign step entirely. Not
+     * order/instruction-specific — works for any pre-signed `Transaction`/`VersionedTransaction`.
+     * @param tx - The already-signed transaction to send.
+     * @param opts - Confirmation options; defaults to `this.opts`.
+     * @returns The transaction signature.
+     */
     sendSignedTx(tx: Transaction | VersionedTransaction, opts?: ConfirmOptions): Promise<TransactionSignature>;
+    /**
+     * Builds (without sending) the set of transactions needed to place a market order and,
+     * for legacy (non-versioned) transactions, a companion transaction that fills it against
+     * the AMM. Also builds optional companion transactions to cancel the market's existing
+     * orders first and/or settle PnL after the fill. Used by `sendMarketOrderAndGetSignedFillTx`.
+     * @param orderParams - Order to place; `orderParams.baseAssetAmount` is BASE_PRECISION (1e9)
+     * for perp (token-mint precision for spot), `orderParams.price` is PRICE_PRECISION (1e6).
+     * @param userAccountPublicKey - Public key of the placing user account (used for the
+     * post-fill settle-PnL instruction).
+     * @param userAccount - Decoded user account; supplies `subAccountId` and `nextOrderId`.
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param txParams - Optional compute-unit/priority-fee overrides applied to all built transactions.
+     * @param bracketOrdersParams - Additional orders (e.g. TP/SL) placed in the same transaction as the market order.
+     * @param cancelExistingOrders - If `true` and `orderParams.marketType` is perp, also builds a
+     * transaction cancelling all existing open orders in that market — intended for auto-cancelling
+     * TP/SL orders when closing a position. Ignored for spot.
+     * @param settlePnl - If `true` and `orderParams.marketType` is perp, also builds a
+     * settle-PnL transaction for `orderParams.marketIndex`.
+     * @param positionMaxLev - If set, prepends an instruction to set a custom max-leverage margin
+     * ratio (`MARGIN_PRECISION`, 1e4, derived as `1 / positionMaxLev`) for the position before placing.
+     * @param isolatedPositionDepositAmount - If set and the order increases the position, prepends a
+     * transfer-into-isolated-position deposit instruction (token-mint precision) before placing.
+     * @returns An object with `marketOrderTx` (always present) and optional `cancelExistingOrdersTx`,
+     * `settlePnlTx`, `fillTx` (only built when `this.txVersion === 0`, i.e. legacy transactions).
+     */
     prepareMarketOrderTxs(orderParams: OptionalOrderParams, userAccountPublicKey: PublicKey, userAccount: UserAccount, makerInfo?: MakerInfo | MakerInfo[], txParams?: TxParams, bracketOrdersParams?: OptionalOrderParams[], cancelExistingOrders?: boolean, settlePnl?: boolean, positionMaxLev?: number, isolatedPositionDepositAmount?: BN): Promise<{
         cancelExistingOrdersTx?: Transaction | VersionedTransaction;
         settlePnlTx?: Transaction | VersionedTransaction;
@@ -529,15 +1874,24 @@ export declare class VelocityClient {
         marketOrderTx: Transaction | VersionedTransaction;
     }>;
     /**
-     * Sends a market order and returns a signed tx which can fill the order against the vamm, which the caller can use to fill their own order if required.
-     * @param orderParams
-     * @param userAccountPublicKey
-     * @param userAccount
-     * @param makerInfo
-     * @param txParams
-     * @param bracketOrdersParams
-     * @param cancelExistingOrders - Builds and returns an extra transaciton to cancel the existing orders in the same perp market. Intended use is to auto-cancel TP/SL orders when closing a position. Ignored if orderParams.marketType is not MarketType.PERP
-     * @returns
+     * Sends a market order transaction and, for legacy (non-versioned) transactions, also returns
+     * a co-signed fill transaction the caller can broadcast themselves to fill the order against
+     * the AMM (useful when the caller wants to control fill timing/submission rather than relying
+     * on a keeper). Internally builds transactions via `prepareMarketOrderTxs`, signs them all, then
+     * sends only `marketOrderTx`.
+     * @param orderParams - Order to place; `baseAssetAmount` is BASE_PRECISION (1e9) for perp
+     * (token-mint precision for spot), `price` is PRICE_PRECISION (1e6).
+     * @param userAccountPublicKey - Public key of the placing user account.
+     * @param userAccount - Decoded user account; supplies `subAccountId` and `nextOrderId`.
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param bracketOrdersParams - Additional orders (e.g. TP/SL) placed alongside the market order.
+     * @param cancelExistingOrders - Builds and returns an extra transaction to cancel the existing orders in the same perp market. Intended use is to auto-cancel TP/SL orders when closing a position. Ignored if orderParams.marketType is not MarketType.PERP.
+     * @param settlePnl - If `true` and the order is a perp order, also builds and returns a signed settle-PnL transaction for the order's market.
+     * @returns `txSig` for the sent market-order transaction, plus `signedFillTx` (only when
+     * `this.txVersion === 0`), `signedCancelExistingOrdersTx`, and `signedSettlePnlTx` — each
+     * `undefined` when not applicable/requested. None of the returned side transactions are sent;
+     * the caller must broadcast them.
      */
     sendMarketOrderAndGetSignedFillTx(orderParams: OptionalOrderParams, userAccountPublicKey: PublicKey, userAccount: UserAccount, makerInfo?: MakerInfo | MakerInfo[], txParams?: TxParams, bracketOrdersParams?: OptionalOrderParams[], cancelExistingOrders?: boolean, settlePnl?: boolean): Promise<{
         txSig: TransactionSignature;
@@ -545,6 +1899,20 @@ export declare class VelocityClient {
         signedCancelExistingOrdersTx?: Transaction;
         signedSettlePnlTx?: Transaction;
     }>;
+    /**
+     * Places a single perp order without attempting to fill it in the same instruction — the
+     * order rests until a keeper (or a `placeAndTake*`/signed-msg fill) matches it. Use
+     * `placeAndTakePerpOrder` instead if the caller wants an immediate attempt to fill against
+     * the AMM/makers.
+     * @param orderParams - Order to place; `baseAssetAmount` is BASE_PRECISION (1e9), `price` /
+     * `triggerPrice` / `oraclePriceOffset` (signed) / `auctionStartPrice` / `auctionEndPrice` are
+     * PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param isolatedPositionDepositAmount - If set and the order increases the position, a transfer
+     * into an isolated-margin position (token-mint precision) is prepended in the same transaction.
+     * @returns The transaction signature.
+     */
     placePerpOrder(orderParams: OptionalOrderParams, txParams?: TxParams, subAccountId?: number, isolatedPositionDepositAmount?: BN): Promise<TransactionSignature>;
     /**
      * Returns the RevenueShareEscrow account meta for the placing user when `orderParams`
@@ -564,15 +1932,58 @@ export declare class VelocityClient {
      * Throws when `takerEscrow` does not belong to `takerAuthority`.
      */
     private getTakerEscrowAccountMeta;
+    /**
+     * Builds the `placePerpOrder` instruction. See `placePerpOrder` for semantics. Automatically
+     * attaches the placing user's `RevenueShareEscrow` account when `orderParams` carries a
+     * builder code (`builderIdx`/`builderFeeTenthBps`).
+     * @param orderParams - Order to place; see `placePerpOrder` for field precisions.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param depositToTradeArgs - Pass when composing this instruction ahead of the user account
+     * actually existing on-chain yet (e.g. deposit-to-trade in the same transaction as account
+     * creation): `isMakingNewAccount` skips loading the (not-yet-existing) user account for
+     * `remainingAccounts`, and `depositMarketIndex` marks the deposit's spot market as readable.
+     * @returns The instruction.
+     */
     getPlacePerpOrderIx(orderParams: OptionalOrderParams, subAccountId?: number, depositToTradeArgs?: {
         isMakingNewAccount: boolean;
         depositMarketIndex: number;
     }): Promise<TransactionInstruction>;
     updateAMMs(marketIndexes: number[], txParams?: TxParams): Promise<TransactionSignature>;
     getUpdateAMMsIx(marketIndexes: number[]): Promise<TransactionInstruction>;
+    /**
+     * Admin instruction: finalizes settlement pricing for a perp market that has already been put
+     * into `Settlement` status (`market.status === MarketStatus.SETTLEMENT`), snapping the market's
+     * settlement price/oracle-twap so every position can subsequently be closed at that fixed price
+     * via `settlePNL`. Requires a warm- or cold-tier admin signer (`check_warm`).
+     * @param marketIndex - Perp market index to settle.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settleExpiredMarket(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `settleExpiredMarket` instruction. See `settleExpiredMarket` for semantics. Signs
+     * with `this.wallet.publicKey` when not subscribed, or the state's `coldAdmin` when subscribed —
+     * the on-chain constraint accepts either a warm- or cold-tier admin, so passing `coldAdmin`
+     * always satisfies it regardless of which tier the actual signer holds.
+     * @param marketIndex - Perp market index to settle.
+     * @returns The instruction.
+     */
     getSettleExpiredMarketIx(marketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Admin instruction: sweeps a settled (`MarketStatus.SETTLEMENT`) perp market's remaining fee
+     * pool and PnL pool balances into the quote spot market's revenue pool, once all user positions
+     * in the market have been settled out. Requires a warm- or cold-tier admin signer.
+     * @param marketIndex - Perp market index to sweep.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settleExpiredMarketPoolsToRevenuePool(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `settleExpiredMarketPoolsToRevenuePool` instruction. See
+     * `settleExpiredMarketPoolsToRevenuePool` for semantics.
+     * @param perpMarketIndex - Perp market index to sweep.
+     * @returns The instruction.
+     */
     getSettleExpiredMarketPoolsToRevenuePoolIx(perpMarketIndex: number): Promise<TransactionInstruction>;
     /**
      * Cancel an open order and broadcast the transaction.
@@ -586,7 +1997,15 @@ export declare class VelocityClient {
      * is also provided, `getOrder` will return `undefined` (the ID is unknown client-side),
      * causing the withdraw path to throw — supply an explicit `orderId` in that case.
      *
-     * @see {@link getCancelOrderIx} to obtain the instruction without sending.
+     * @param orderId - Program-assigned order ID to cancel; omit to cancel the most recently
+     * placed order (resolved on-chain via `get_last_order_id`).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @param overrides.withdrawIsolatedDepositAmount - If set and > 0, appends an isolated-margin
+     * withdrawal (token-mint precision) for the cancelled order's market in the same transaction;
+     * requires an explicit `orderId` (see note above).
+     * @returns The transaction signature.
+     * @see `getCancelOrderIx` to obtain the instruction without sending.
      */
     cancelOrder(orderId?: number, txParams?: TxParams, subAccountId?: number, overrides?: {
         withdrawIsolatedDepositAmount?: BN;
@@ -603,19 +2022,43 @@ export declare class VelocityClient {
      *
      * When `orderId` is supplied, only that specific order is cancelled.
      *
-     * @see {@link cancelOrder} to send the transaction directly.
-     * @see {@link getCancelOrderByUserIdIx} to cancel by the caller-supplied `userOrderId`.
+     * @param orderId - Program-assigned order ID to cancel; omit (or `undefined`) to cancel the
+     * most recently placed order.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @returns The instruction.
+     * @see `cancelOrder` to send the transaction directly.
+     * @see `getCancelOrderByUserIdIx` to cancel by the caller-supplied `userOrderId`.
      */
     getCancelOrderIx(orderId?: number, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Cancel an open order identified by its caller-supplied `userOrderId` and broadcast the
+     * transaction.
+     * @param userOrderId - Caller-chosen order slot (set via `OrderParams.userOrderId` at placement).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @returns The transaction signature.
+     * @see `getCancelOrderByUserIdIx` to obtain the instruction without sending.
+     */
     cancelOrderByUserId(userOrderId: number, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `cancelOrderByUserId` instruction. See `cancelOrderByUserId` for semantics.
+     * @param userOrderId - Caller-chosen order slot (set via `OrderParams.userOrderId` at placement).
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @throws If no open order with `userOrderId` is found in the cached user account (looked up
+     * client-side to resolve the order's market/oracle for `remainingAccounts`).
+     * @returns The instruction.
+     * @see `getCancelOrderIx` to cancel by the program-assigned order ID instead.
+     */
     getCancelOrderByUserIdIx(userOrderId: number, subAccountId?: number): Promise<TransactionInstruction>;
     /**
      * Sends a transaction to cancel the provided order ids.
      *
-     * @param orderIds - The order ids to cancel.
+     * @param orderIds - Program-assigned order IDs to cancel; an order ID that no longer exists is
+     * silently skipped. `undefined` sends an empty list on-chain, i.e. cancels nothing.
      * @param txParams - The transaction parameters.
      * @param subAccountId - The sub account id to cancel the orders for.
      * @param user - The user to cancel the orders for. If provided, it will be prioritized over the subAccountId.
+     * @param overrides.authority - Signing authority to use instead of `this.wallet.publicKey`.
      * @returns The transaction signature.
      */
     cancelOrdersByIds(orderIds?: number[], txParams?: TxParams, subAccountId?: number, user?: User, overrides?: {
@@ -624,67 +2067,254 @@ export declare class VelocityClient {
     /**
      * Returns the transaction instruction to cancel the provided order ids.
      *
-     * @param orderIds - The order ids to cancel.
+     * @param orderIds - Program-assigned order IDs to cancel; an order ID that no longer exists is
+     * silently skipped. `undefined` sends an empty list on-chain, i.e. cancels nothing.
      * @param subAccountId - The sub account id to cancel the orders for.
      * @param user - The user to cancel the orders for. If provided, it will be prioritized over the subAccountId.
+     * @param overrides.authority - Signing authority to use instead of `this.wallet.publicKey`.
      * @returns The transaction instruction to cancel the orders.
      */
     getCancelOrdersByIdsIx(orderIds?: number[], subAccountId?: number, user?: User, overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Cancel all of a user's open orders matching the given (optional) filters, and broadcast the
+     * transaction. Any filter left `undefined` is not applied — calling with no filters cancels
+     * every open order on the sub-account.
+     * @param marketType - Only cancel orders of this market type (`PERP`/`SPOT`); combined with
+     * `marketIndex` to scope to one perp or spot market.
+     * @param marketIndex - Only cancel orders in this market index.
+     * @param direction - Only cancel orders on this side (`LONG`/`SHORT`).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to cancel orders for; defaults to the active sub-account.
+     * @returns The transaction signature.
+     * @see `getCancelOrdersIx` to obtain the instruction without sending.
+     */
     cancelOrders(marketType?: MarketType, marketIndex?: number, direction?: PositionDirection, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `cancelOrders` instruction. See `cancelOrders` for filter semantics (`null`/`undefined`
+     * on any of `marketType`/`marketIndex`/`direction` means "don't filter on that field").
+     * @param marketType - Only cancel orders of this market type.
+     * @param marketIndex - Only cancel orders in this market index.
+     * @param direction - Only cancel orders on this side.
+     * @param subAccountId - Sub-account to cancel orders for; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getCancelOrdersIx(marketType: MarketType | null | undefined, marketIndex: number | null | undefined, direction: PositionDirection | null | undefined, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Atomically cancels orders matching the given filters and places new orders in a single
+     * transaction (cancel instruction first, then place). Useful for order replacement flows
+     * (e.g. re-quoting) where the old orders must not be fillable in the gap before the new
+     * ones land.
+     * @param cancelOrderParams - Filters for which open orders to cancel; see `cancelOrders` for
+     * semantics (`undefined` fields are not filtered on).
+     * @param placeOrderParams - Orders to place after the cancel; `baseAssetAmount` is BASE_PRECISION
+     * (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to operate on; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     cancelAndPlaceOrders(cancelOrderParams: {
         marketType?: MarketType;
         marketIndex?: number;
         direction?: PositionDirection;
     }, placeOrderParams: OrderParams[], txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Places a batch of orders (perp and/or spot) in a single instruction. None are filled
+     * in-instruction — each rests until matched by a keeper or a subsequent fill/place-and-take.
+     * @param params - Orders to place; `baseAssetAmount` is BASE_PRECISION (1e9) for perp
+     * (token-mint precision for spot), `price`/`triggerPrice`/`oraclePriceOffset` are
+     * PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @param optionalIxs - Extra instructions to prepend to the transaction.
+     * @param isolatedPositionDepositAmount - If set and `params` has exactly one perp order that
+     * increases the position, a transfer into an isolated-margin position (token-mint precision)
+     * is prepended before placing. Ignored for batches of more than one order.
+     * @returns The transaction signature.
+     */
     placeOrders(params: OrderParams[], txParams?: TxParams, subAccountId?: number, optionalIxs?: TransactionInstruction[], isolatedPositionDepositAmount?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds (without sending) the `placeOrders` transaction. See `placeOrders` for semantics.
+     * @param params - Orders to place; see `placeOrders` for field precisions.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @param optionalIxs - Extra instructions to prepend to the transaction.
+     * @param isolatedPositionDepositAmount - See `placeOrders`; only applied when `params.length === 1`.
+     * @returns An object with `placeOrdersTx`, the built (unsigned) transaction.
+     */
     preparePlaceOrdersTx(params: OrderParams[], txParams?: TxParams, subAccountId?: number, optionalIxs?: TransactionInstruction[], isolatedPositionDepositAmount?: BN): Promise<{
         placeOrdersTx: Transaction | VersionedTransaction;
     }>;
+    /**
+     * Builds the `placeOrders` instruction. See `placeOrders` for semantics. Attaches the placing
+     * user's `RevenueShareEscrow` once (not per-order) when any order in the batch carries a
+     * builder code — the on-chain handler expects a single escrow account for the whole batch.
+     * @param params - Orders to place; every entry must set `marketType`. See `placeOrders` for
+     * field precisions.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @param overrides - `authority` overrides the signing authority (defaults to `this.wallet.publicKey`).
+     * @throws If any order in `params` omits `marketType`.
+     * @returns The instruction.
+     */
     getPlaceOrdersIx(params: OptionalOrderParams[], subAccountId?: number, overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Builds a `placeOrders` instruction followed by an instruction that sets a custom max-leverage
+     * margin ratio on the position for `params[0]`'s market. Unlike `placeOrders`, this bypasses the
+     * `RevenueShareEscrow` attachment for builder-coded orders (uses the raw `program.instruction`
+     * call directly) — don't use it for batches containing a builder-coded order.
+     * @param params - Orders to place; `baseAssetAmount` is BASE_PRECISION (1e9) for perp
+     * (token-mint precision for spot), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+     * @param positionMaxLev - Max leverage to apply to the position in `params[0].marketIndex`; converted
+     * to a MARGIN_PRECISION (1e4) margin ratio as `1 / positionMaxLev`.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @returns A two-element array: `[placeOrdersIx, setPositionMaxLevIx]`.
+     */
     getPlaceOrdersAndSetPositionMaxLevIx(params: OptionalOrderParams[], positionMaxLev: number, subAccountId?: number): Promise<TransactionInstruction[]>;
     /**
-     * Place scale orders: multiple limit orders distributed across a price range
-     * @param params Scale order parameters
-     * @param txParams Optional transaction parameters
-     * @param subAccountId Optional sub account ID
-     * @returns Transaction signature
+     * Places multiple limit orders (`params.orderCount`, 2-32) distributed across a price range
+     * in a single instruction, none filled in-instruction — each rests until matched.
+     * @param params - Scale order parameters: `totalBaseAssetAmount` is BASE_PRECISION (1e9),
+     * `startPrice`/`endPrice` are PRICE_PRECISION (1e6); see `ScaleOrderParams` for the rest.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @returns The transaction signature.
      */
     placeScaleOrders(params: ScaleOrderParams, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds (without sending) the `placeScaleOrders` transaction. See `placeScaleOrders` for semantics.
+     * @param params - Scale order parameters; see `placeScaleOrders` for field precisions.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @returns An object with `placeScaleOrdersTx`, the built (unsigned) transaction.
+     */
     preparePlaceScaleOrdersTx(params: ScaleOrderParams, txParams?: TxParams, subAccountId?: number): Promise<{
         placeScaleOrdersTx: Transaction | VersionedTransaction;
     }>;
+    /**
+     * Builds the `placeScaleOrders` instruction. See `placeScaleOrders` for semantics.
+     * @param params - Scale order parameters; see `placeScaleOrders` for field precisions.
+     * @param subAccountId - Sub-account to place the orders for; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getPlaceScaleOrdersIx(params: ScaleOrderParams, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction that fills a resting DLOB perp order against one or more makers (or the
+     * AMM/vAMM when no maker matches). Permissionless — any signer can act as filler and earns the
+     * filler reward. Does not place or cancel orders itself; it only matches an order that is
+     * already on the book.
+     * @param userAccountPublicKey - Public key of the order owner's user account.
+     * @param user - Decoded user account of the order owner.
+     * @param order - The order to fill (`marketIndex`/`orderId`); defaults to the owner's most
+     * recently placed order (`nextOrderId - 1`) when omitted.
+     * @param makerInfo - Maker(s) to attempt to cross against; a single `MakerInfo` or an array.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param fillerSubAccountId - Filler's sub-account to credit; defaults to the active sub-account.
+     * @param fillerAuthority - Filler's authority, if different from this client's wallet (e.g.
+     * filling on behalf of a delegated sub-account); the filler user/user-stats PDAs are derived
+     * from this authority instead of `this.wallet.publicKey`.
+     * @param hasBuilderFee - Force-attach the taker's `RevenueShareEscrow` account, bypassing the
+     * automatic builder-code detection performed by `getFillPerpOrderIx`.
+     * @param takerEscrow - The taker's decoded `RevenueShareEscrow`. Required whenever the order
+     * carries a builder code or the taker is referred — the program rejects the fill if the escrow
+     * is owed but not attached.
+     * @returns The transaction signature.
+     */
     fillPerpOrder(userAccountPublicKey: PublicKey, user: UserAccount, order?: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], txParams?: TxParams, fillerSubAccountId?: number, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
-    getFillPerpOrderIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, order?: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], fillerSubAccountId?: number, isSignedMsg?: boolean, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
+    /**
+     * Builds the `fillPerpOrder` instruction. See `fillPerpOrder` for semantics. Assembles maker
+     * accounts and the taker's `RevenueShareEscrow` (when owed) into `remainingAccounts` in the
+     * order the on-chain handler expects: user/maker market+oracle accounts first, then each
+     * maker's `(maker, makerStats)` pair, then the taker escrow meta last.
+     * @param userAccountPublicKey - Public key of the order owner's user account.
+     * @param userAccount - Decoded user account of the order owner.
+     * @param order - The order to fill (`marketIndex`/`orderId`); defaults to the owner's most
+     * recently placed order when omitted and `isSignedMsg` is false.
+     * @param makerInfo - Maker(s) to attempt to cross against.
+     * @param fillerSubAccountId - Filler's sub-account to credit; defaults to the active sub-account.
+     * @param isSignedMsg - Whether this fills a signed-msg (swift) order that has not yet been
+     * placed on-chain; when true, `order` is not required and the builder-escrow attachment is
+     * done optimistically (the order's builder flag cannot be inspected before it lands).
+     * @param fillerAuthority - Filler's authority if different from this client's wallet; the
+     * filler user/user-stats PDAs are derived from this authority.
+     * @param hasBuilderFee - Force-attach the taker escrow regardless of the detected builder flag.
+     * @param takerEscrow - The taker's decoded `RevenueShareEscrow`. Required to attach the escrow
+     * when the order has a builder code or the taker is referred with an initialized escrow — the
+     * on-chain handler rejects the fill if an owed escrow is missing from `remainingAccounts`.
+     * @throws If no order can be resolved to fill, or (for a non-signed-msg fill) `order` is omitted.
+     * @returns The instruction.
+     */
+    getFillPerpOrderIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, order?: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], fillerSubAccountId?: number, isSignedMsg?: boolean, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount, takerIsReferred?: boolean): Promise<TransactionInstruction>;
+    /**
+     * Builds the `revertFill` instruction. Used by keepers as a same-transaction fallback after a
+     * simulated fill fails downstream (e.g. a subsequent instruction errors): it only asserts the
+     * filler's `lastActiveSlot` equals the current slot and otherwise is a no-op, letting the
+     * keeper's earlier fill CPI effects be discarded by the transaction failing cleanly rather than
+     * with a confusing downstream error.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own
+     * user account.
+     * @returns The instruction.
+     */
     getRevertFillIx(fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Disabled. Spot DLOB trading (order placement/matching) is turned off in this deployment —
+     * spot balances, deposits, withdrawals, and swaps remain available.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     placeSpotOrder(_orderParams: OptionalOrderParams, _txParams?: TxParams, _subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     preparePlaceSpotOrderTx(_orderParams: OptionalOrderParams, _txParams?: TxParams, _subAccountId?: number): Promise<void>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     getPlaceSpotOrderIx(_orderParams: OptionalOrderParams, _subAccountId?: number, _overrides?: {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     fillSpotOrder(_userAccountPublicKey: PublicKey, _user: UserAccount, _order?: Pick<Order, 'marketIndex' | 'orderId'>, _fulfillmentConfig?: unknown, _makerInfo?: MakerInfo | MakerInfo[], _txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     getFillSpotOrderIx(_userAccountPublicKey: PublicKey, _userAccount: UserAccount, _order?: Pick<Order, 'marketIndex' | 'orderId'>, _fulfillmentConfig?: unknown, _makerInfo?: MakerInfo | MakerInfo[], _fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
     /**
-     * Swap tokens in velocity account using titan or jupiter
-     * @param swapClient swap client to find routes and instructions (Titan or Jupiter)
-     * @param jupiterClient @deprecated Use swapClient instead. Legacy parameter for backward compatibility
-     * @param outMarketIndex the market index of the token you're buying
-     * @param inMarketIndex the market index of the token you're selling
-     * @param outAssociatedTokenAccount the token account to receive the token being sold on the swap provider
-     * @param inAssociatedTokenAccount the token account to
-     * @param amount the amount of TokenIn, regardless of swapMode
-     * @param slippageBps the max slippage passed to the swap provider api
-     * @param swapMode swap provider swapMode (ExactIn or ExactOut), default is ExactIn
-     * @param route the swap provider route to use for the swap
-     * @param reduceOnly specify if In or Out token on the velocity account must reduceOnly, checked at end of swap
-     * @param v6 pass in the quote response from swap provider quote's API (deprecated, use quote instead)
-     * @param quote pass in the quote response from swap provider quote's API
-     * @param txParams
+     * Swaps one spot-market token for another inside the user's velocity account: brackets the
+     * external swap provider's instructions between the program's `beginSwap`/`endSwap`
+     * 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 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 slippageBps - Max slippage in basis points passed to the swap provider's routing API.
+     * @param swapMode - `ExactIn` (default) or `ExactOut`.
+     * @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 txParams - Optional compute-unit/priority-fee overrides.
+     * @throws If neither `swapClient` nor `jupiterClient` is provided, or if `swapClient` is not a
+     * recognized client type.
+     * @returns The transaction signature.
      */
     swap({ swapClient, jupiterClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, reduceOnly, txParams, v6, quote, onlyDirectRoutes, }: {
         swapClient?: UnifiedSwapClient | SwapClient;
@@ -705,6 +2335,15 @@ export declare class VelocityClient {
         };
         quote?: UnifiedQuoteResponse;
     }): 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.
+     */
     getTitanSwapIx({ titanClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, reduceOnly, userAccountPublicKey, }: {
         titanClient: TitanClient;
         outMarketIndex: number;
@@ -721,6 +2360,17 @@ export declare class VelocityClient {
         ixs: TransactionInstruction[];
         lookupTables: AddressLookupTableAccount[];
     }>;
+    /**
+     * 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.
+     * @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.
+     */
     getJupiterSwapIxV6({ jupiterClient, outMarketIndex, inMarketIndex, outAssociatedTokenAccount, inAssociatedTokenAccount, amount, slippageBps, swapMode, onlyDirectRoutes, quote, reduceOnly, userAccountPublicKey, }: {
         jupiterClient: JupiterClient;
         outMarketIndex: number;
@@ -739,16 +2389,25 @@ export declare class VelocityClient {
         lookupTables: AddressLookupTableAccount[];
     }>;
     /**
-     * Get the velocity begin_swap and end_swap instructions
-     *
-     * @param outMarketIndex the market index of the token you're buying
-     * @param inMarketIndex the market index of the token you're selling
-     * @param amountIn the amount of the token to sell
-     * @param inTokenAccount the token account to move the tokens being sold
-     * @param outTokenAccount the token account to receive the tokens being bought
-     * @param limitPrice the limit price of the swap
-     * @param reduceOnly
-     * @param userAccountPublicKey optional, specify a custom userAccountPublicKey to use instead of getting the current user account; can be helpful if the account is being created within the current tx
+     * Builds the `beginSwap`/`endSwap` instruction pair that must bracket an external swap
+     * provider's routing instructions in the same transaction. `beginSwap` snapshots the token
+     * account balances and moves `amountIn` out of the in-market vault; `endSwap` reconciles the
+     * post-swap token balances back into the user's velocity deposits, enforces `limitPrice` and
+     * `reduceOnly`, and validates both spot markets' oracles are fresh/valid.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param amountIn - Amount of the in-token released from the vault to the swap provider, in
+     * the in-token's own mint decimals (not a fixed protocol precision).
+     * @param inTokenAccount - Token account the sold tokens are moved through.
+     * @param outTokenAccount - Token account the bought tokens are moved through.
+     * @param limitPrice - Minimum acceptable `out/in` swap price, PRICE_PRECISION (1e6); `endSwap`
+     * throws `SwapLimitPriceBreached` if the realized price is lower. Omit for no price check.
+     * @param reduceOnly - Which side (`In`/`Out`) must not increase in magnitude after the swap;
+     * enforced by `endSwap`.
+     * @param userAccountPublicKey - Optional user account override; useful when the account is
+     * being created within the same transaction and not yet resolvable via
+     * `getUserAccountPublicKey`.
+     * @returns `{ beginSwapIx, endSwapIx }` — insert the swap provider's instructions between them.
      */
     getSwapIx({ outMarketIndex, inMarketIndex, amountIn, inTokenAccount, outTokenAccount, limitPrice, reduceOnly, userAccountPublicKey, }: {
         outMarketIndex: number;
@@ -763,6 +2422,17 @@ 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;
@@ -783,128 +2453,494 @@ export declare class VelocityClient {
         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
+     * velocity deposit via `beginSwap`/`endSwap`. Sends and confirms the transaction.
+     * @param amount - Amount of wSOL to stake, in lamports (wSOL mint decimals, 1e9).
+     * @returns The transaction signature and confirmation slot.
+     */
     stakeForMSOL({ amount }: {
         amount: BN;
     }): Promise<TxSigAndSlot>;
+    /**
+     * Builds the instruction list for `stakeForMSOL`: wraps a Marinade `deposit` (wSOL to mSOL)
+     * between the velocity `beginSwap`/`endSwap` pair so the mSOL lands back in the user's velocity
+     * deposit for spot market index 2. Hardcodes wSOL as market index 1 and mSOL as market index 2.
+     * @param amount - Amount of wSOL to stake, in lamports (wSOL mint decimals, 1e9).
+     * @param userAccountPublicKey - Optional user account override; useful when the account is
+     * being created within the same transaction.
+     * @returns The ordered instruction list (WSOL ATA setup, `beginSwap`, close/recreate wSOL
+     * account around the Marinade deposit, `endSwap`).
+     */
     getStakeForMSOLIx({ amount, userAccountPublicKey, }: {
         amount: BN;
         userAccountPublicKey?: PublicKey;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Keeper instruction: activates a resting trigger order (stop/take-profit, perp or spot) once
+     * its `triggerPrice`/`triggerCondition` has been met, turning it into a fillable market/limit
+     * order. Permissionless — any signer can act as filler and earns a small keeper fee. Does not
+     * fill the order itself; a separate fill instruction (or place-and-take) is still required.
+     * @param userAccountPublicKey - Public key of the order owner's user account.
+     * @param user - Decoded user account for the order owner.
+     * @param order - The trigger order to activate (`order.orderId`, `order.marketType`, `order.marketIndex`).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The transaction signature.
+     */
     triggerOrder(userAccountPublicKey: PublicKey, user: UserAccount, order: Order, txParams?: TxParams, fillerPublicKey?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `triggerOrder` instruction. See `triggerOrder` for semantics.
+     * @param userAccountPublicKey - Public key of the order owner's user account.
+     * @param userAccount - Decoded user account for the order owner.
+     * @param order - The trigger order to activate.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The instruction.
+     */
     getTriggerOrderIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, order: Order, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: cancels a user's open, non-position-reducing orders when the user fails
+     * their initial margin requirement (reverts with `SufficientCollateral` if the user still
+     * meets it, or with `UserIsBeingLiquidated`/`UserBankrupt` if either is set). Charges the user a
+     * per-cancelled-order fee paid to the filler. Permissionless — any signer can act as filler.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param user - Decoded user account of the target user.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The transaction signature.
+     */
     forceCancelOrders(userAccountPublicKey: PublicKey, user: UserAccount, txParams?: TxParams, fillerPublicKey?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `forceCancelOrders` instruction. See `forceCancelOrders` for semantics.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param userAccount - Decoded user account of the target user.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The instruction.
+     */
     getForceCancelOrdersIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: marks a user account idle after confirming (via `validate_user_is_idle`)
+     * it has been inactive long enough — the inactivity window is shorter (accelerated) when the
+     * user's equity is below 1000 USDC (QUOTE_PRECISION, 1e6). Idle users are excluded from some
+     * keeper crank workloads. Permissionless — any signer can act as filler.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param user - Decoded user account of the target user.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @throws If the user does not yet qualify as idle.
+     * @returns The transaction signature.
+     */
     updateUserIdle(userAccountPublicKey: PublicKey, user: UserAccount, txParams?: TxParams, fillerPublicKey?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserIdle` instruction. See `updateUserIdle` for semantics.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param userAccount - Decoded user account of the target user.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The instruction.
+     */
     getUpdateUserIdleIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Debug/monitoring instruction: emits the user's equity, each non-zero spot position's signed
+     * token amount (native mint decimals), and each open perp position's unrealized PnL
+     * (QUOTE_PRECISION, 1e6) as program logs. Has no on-chain state effect. Exchange must not be
+     * paused.
+     * @param userAccountPublicKey - Public key of the user account to log.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     logUserBalances(userAccountPublicKey: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `logUserBalances` instruction. See `logUserBalances` for semantics. Fetches the
+     * user account fresh from the RPC (rather than relying on a cached/passed-in account) to build
+     * `remainingAccounts`.
+     * @param userAccountPublicKey - Public key of the user account to log.
+     * @returns The instruction.
+     */
     getLogUserBalancesIx(userAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Recomputes and updates the `isReferrer` flag on a `UserStats` account from its current
+     * referrer-related fields. Permissionless — anyone can trigger the refresh for any authority.
+     * @param userAuthority - Wallet authority whose `UserStats` PDA should be refreshed.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updateUserStatsReferrerStatus(userAuthority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserStatsReferrerStatus` instruction. See `updateUserStatsReferrerStatus`
+     * for semantics.
+     * @param userAuthority - Wallet authority whose `UserStats` PDA should be refreshed.
+     * @returns The instruction.
+     */
     getUpdateUserStatsReferrerStatusIx(userAuthority: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: recounts `user.orders` and rewrites `openOrders`/`hasOpenOrder`/
+     * `openAuctions`/`hasOpenAuction` to match the account's actual order state — a repair
+     * instruction for when these cached counters have drifted. Permissionless — any signer can act
+     * as filler.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param user - Decoded user account of the target user.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The transaction signature.
+     */
     updateUserOpenOrdersCount(userAccountPublicKey: PublicKey, user: UserAccount, txParams?: TxParams, fillerPublicKey?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserOpenOrdersCount` instruction. See `updateUserOpenOrdersCount` for
+     * semantics.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param userAccount - Decoded user account of the target user.
+     * @param fillerPublicKey - Filler's user account public key; defaults to this client's own user account.
+     * @returns The instruction.
+     */
     getUpdateUserOpenOrdersCountIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Places a perp order and immediately attempts to fill it in the same instruction against the
+     * AMM and/or the supplied `makerInfo`. `orderParams.postOnly` must be `PostOnlyParams.NONE` —
+     * the on-chain handler rejects post-only orders here (use `placeAndMakePerpOrder` instead for a
+     * post-only maker order). If the order is immediate-or-cancel (or `successCondition`/
+     * `auctionDurationPercentage` is set) and still open after the fill attempt, it is cancelled
+     * in the same instruction.
+     * @param orderParams - Order to place; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/
+     * `triggerPrice`/`oraclePriceOffset` (signed) are PRICE_PRECISION (1e6).
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param successCondition - Require the fill to be a `PartialFill` or `FullFill`; the
+     * instruction reverts with `PlaceAndTakeOrderSuccessConditionFailed` if not met. Omit for no check.
+     * @param auctionDurationPercentage - Percent (0-100, default 100) of the order's auction that
+     * must have elapsed before this fill attempt is allowed to cross the AMM/makers at the current
+     * auction price; packed on-chain into the same `u32` as `successCondition`.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param takerEscrow - The placing user's (taker's) decoded `RevenueShareEscrow`. Required to
+     * attach the escrow account when the taker is referred but the order itself carries no builder
+     * code — the builder case is detected automatically from `orderParams`.
+     * @returns The transaction signature.
+     */
     placeAndTakePerpOrder(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], successCondition?: PlaceAndTakeOrderSuccessCondition, auctionDurationPercentage?: number, txParams?: TxParams, subAccountId?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
+    /**
+     * Builds (without sending) a `placeAndTakePerpOrder` transaction bundled with optional bracket
+     * orders (e.g. TP/SL) in the same transaction, plus optional companion transactions to cancel
+     * the market's existing orders first and/or settle PnL after. Reuses a single recent blockhash
+     * across all built transactions to save RPC round trips.
+     * @param orderParams - Order to place; see `placeAndTakePerpOrder` for field precisions.
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param bracketOrdersParams - Additional orders placed in the same transaction as the place-and-take.
+     * @param txParams - Compute-unit/priority-fee overrides. Required (throws otherwise) if
+     * `txParams.useSimulatedComputeUnits` is set or `exitEarlyIfSimFails` is `true`.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param cancelExistingOrders - If `true` and the order is perp, also builds a transaction
+     * cancelling all existing open orders in that market.
+     * @param settlePnl - If `true` and the order is perp, also builds a settle-PnL transaction for the market.
+     * @param exitEarlyIfSimFails - If `true`, simulates the place-and-take transaction first and
+     * returns `null` without building the real transactions if the simulation fails.
+     * @param auctionDurationPercentage - See `placeAndTakePerpOrder`.
+     * @param optionalIxs - Extra instructions prepended to the place-and-take transaction (and to
+     * the cancel/settle-PnL transactions).
+     * @param isolatedPositionDepositAmount - If set and the order increases the position, a
+     * transfer into an isolated-margin position (token-mint precision) is prepended before placing.
+     * @returns `null` if `exitEarlyIfSimFails` triggered an early exit; otherwise an object with
+     * `placeAndTakeTx` and optional `cancelExistingOrdersTx`/`settlePnlTx` (each `undefined` when
+     * not applicable).
+     */
     preparePlaceAndTakePerpOrderWithAdditionalOrders(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], bracketOrdersParams?: OptionalOrderParams[], txParams?: TxParams, subAccountId?: number, cancelExistingOrders?: boolean, settlePnl?: boolean, exitEarlyIfSimFails?: boolean, auctionDurationPercentage?: number, optionalIxs?: TransactionInstruction[], isolatedPositionDepositAmount?: BN): Promise<{
         placeAndTakeTx: Transaction | VersionedTransaction | undefined;
         cancelExistingOrdersTx: Transaction | VersionedTransaction | undefined;
         settlePnlTx: Transaction | VersionedTransaction | undefined;
     } | null>;
+    /**
+     * Builds, signs, and sends a `placeAndTakePerpOrder` transaction bundled with bracket orders via
+     * `preparePlaceAndTakePerpOrderWithAdditionalOrders`, and returns the signed (but unsent)
+     * companion cancel/settle-PnL transactions for the caller to broadcast separately.
+     * @param orderParams - Order to place; see `placeAndTakePerpOrder` for field precisions.
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param bracketOrdersParams - Additional orders placed in the same transaction as the place-and-take.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param cancelExistingOrders - See `preparePlaceAndTakePerpOrderWithAdditionalOrders`.
+     * @param settlePnl - See `preparePlaceAndTakePerpOrderWithAdditionalOrders`.
+     * @param exitEarlyIfSimFails - If `true`, returns `null` without sending when the pre-flight
+     * simulation of the place-and-take transaction fails.
+     * @returns `null` if the simulation failed and `exitEarlyIfSimFails` was set; otherwise `txSig`
+     * for the sent place-and-take transaction plus the signed (unsent) `signedCancelExistingOrdersTx`
+     * / `signedSettlePnlTx`, each `undefined` when not applicable.
+     * @throws If `placeAndTakeTx` was not built (should not happen unless simulation-related options are misused).
+     */
     placeAndTakePerpWithAdditionalOrders(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], bracketOrdersParams?: OptionalOrderParams[], txParams?: TxParams, subAccountId?: number, cancelExistingOrders?: boolean, settlePnl?: boolean, exitEarlyIfSimFails?: boolean): Promise<{
         txSig: TransactionSignature;
         signedCancelExistingOrdersTx?: Transaction;
         signedSettlePnlTx?: Transaction;
     } | null>;
+    /**
+     * Builds the `placeAndTakePerpOrder` instruction. See `placeAndTakePerpOrder` for semantics.
+     * @param orderParams - Order to place; see `placeAndTakePerpOrder` for field precisions.
+     * @param makerInfo - Maker account(s) to include as fill counterparties, if any.
+     * @param successCondition - See `placeAndTakePerpOrder`.
+     * @param auctionDurationPercentage - See `placeAndTakePerpOrder`.
+     * @param subAccountId - Sub-account to place the order for; defaults to the active sub-account.
+     * @param overrides - `authority` overrides the signing authority (defaults to `this.wallet.publicKey`).
+     * @param takerEscrow - See `placeAndTakePerpOrder`.
+     * @returns The instruction.
+     */
     getPlaceAndTakePerpOrderIx(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], successCondition?: PlaceAndTakeOrderSuccessCondition, auctionDurationPercentage?: number, subAccountId?: number, overrides?: {
         authority?: PublicKey;
     }, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
+    /**
+     * Places a resting maker order and, in the same instruction, fills a specific counterparty
+     * taker order (`takerInfo.order`) against it. `orderParams` must be an immediate-or-cancel,
+     * post-only (not `PostOnlyParams.NONE`) limit order — the on-chain handler rejects any other
+     * shape with `InvalidOrderIOCPostOnly`.
+     * @param orderParams - Maker order to place; `baseAssetAmount` is BASE_PRECISION (1e9), `price`
+     * is PRICE_PRECISION (1e6). Must have `orderType: LIMIT`, `postOnly` set, and be IOC.
+     * @param takerInfo - The taker account/order to fill against (`takerInfo.order.orderId` must be open).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account placing the maker order; defaults to the active sub-account.
+     * @param takerEscrow - The taker's decoded `RevenueShareEscrow`. Required to attach the escrow
+     * when the taker is referred but their order carries no builder code — the builder case is
+     * detected automatically from `takerInfo.order`.
+     * @returns The transaction signature.
+     */
     placeAndMakePerpOrder(orderParams: OptionalOrderParams, takerInfo: TakerInfo, txParams?: TxParams, subAccountId?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
+    /**
+     * Builds the `placeAndMakePerpOrder` instruction. See `placeAndMakePerpOrder` for semantics.
+     * @param orderParams - Maker order to place; see `placeAndMakePerpOrder` for field precisions
+     * and required order shape.
+     * @param takerInfo - The taker account/order to fill against.
+     * @param subAccountId - Sub-account placing the maker order; defaults to the active sub-account.
+     * @param takerEscrow - See `placeAndMakePerpOrder`.
+     * @returns The instruction.
+     */
     getPlaceAndMakePerpOrderIx(orderParams: OptionalOrderParams, takerInfo: TakerInfo, subAccountId?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
+    /**
+     * Borsh-encodes a swift/signed-msg order message and signs the resulting hex-encoded buffer
+     * with `signMessage` (this client's wallet keypair by default). The returned payload is what a
+     * swift/signed-msg service or a taker-facing `placeSignedMsgTakerOrder` expects.
+     * @param orderParamsMessage - The order message to sign; use `SignedMsgOrderParamsDelegateMessage`
+     * when signing on behalf of a delegated authority (`delegateSigner: true`), otherwise
+     * `SignedMsgOrderParamsMessage`.
+     * @param delegateSigner - Whether `orderParamsMessage` is the delegate-signer variant; must match
+     * the message's actual shape or encoding/decoding elsewhere will misinterpret the buffer.
+     * @returns `{ orderParams, signature }` — `orderParams` is the hex-encoded borsh buffer as a
+     * `Buffer`, `signature` is the detached ed25519 signature over it.
+     */
     signSignedMsgOrderParamsMessage(orderParamsMessage: SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage, delegateSigner?: boolean): SignedMsgOrderParams;
     /**
-     * Builds a deposit and place request for Swift service
-     *
-     * @param depositTx - The signed tx containing a velocity deposit (e.g. see `buildSwiftDepositTx`)
-     * @param orderParamsMessage - The order parameters message to sign
-     * @param delegateSigner - Whether this is a delegate signer
-     *
-     * @returns request object for Swift service
+     * Bundles a pre-signed deposit transaction with a signed swift/signed-msg order message into
+     * the request shape the Swift service expects for a "deposit and place" flow (e.g. depositing
+     * new collateral and placing an order off-chain in one round trip before either lands on-chain).
+     * @param depositTx - The signed tx containing a velocity deposit (e.g. see `buildSwiftDepositTx`).
+     * @param orderParamsMessage - The order parameters message to sign.
+     * @param delegateSigner - Whether `orderParamsMessage` is signed by a delegate; see `signSignedMsgOrderParamsMessage`.
+     * @returns `{ deposit_tx, swift_order }` — the serialized deposit transaction and the signed order payload.
      */
     buildDepositAndPlaceSignedMsgOrderRequest(depositTx: VersionedTransaction, orderParamsMessage: SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage, delegateSigner?: boolean): {
         deposit_tx: Buffer;
         swift_order: SignedMsgOrderParams;
     };
+    /**
+     * Borsh-encodes a swift/signed-msg order message using the program's IDL type coder. Used
+     * internally by `signSignedMsgOrderParamsMessage`; call directly if you need the raw encoded
+     * bytes without also signing them.
+     * @param orderParamsMessage - The order message to encode.
+     * @param delegateSigner - Whether `orderParamsMessage` is the delegate-signer variant
+     * (`SignedMsgOrderParamsDelegateMessage`) rather than the regular one — selects which on-chain
+     * type is used to encode.
+     * @returns The borsh-encoded message bytes.
+     */
     encodeSignedMsgOrderParamsMessage(orderParamsMessage: SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage, delegateSigner?: boolean): Buffer;
+    /**
+     * Decodes a borsh-encoded swift/signed-msg order message. Zero-pads the input by 128 bytes
+     * before decoding so messages encoded by an older IDL (missing newer, all-`Option` fields)
+     * still decode instead of throwing on a too-short buffer. Note: this padding assumes any
+     * newer fields added to the message type are `Option`s — a 128+ byte non-optional field
+     * addition could still fail to decode older messages correctly.
+     * @param encodedMessage - The borsh-encoded message bytes (as produced by `encodeSignedMsgOrderParamsMessage`).
+     * @param delegateSigner - Whether to decode as the delegate-signer variant
+     * (`SignedMsgOrderParamsDelegateMessage`) rather than the regular one.
+     * @returns The decoded order message.
+     */
     decodeSignedMsgOrderParamsMessage(encodedMessage: Buffer, delegateSigner?: boolean): SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage;
+    /**
+     * Signs arbitrary bytes with a raw ed25519 detached signature (not a Solana transaction
+     * signature) — the primitive used to sign swift/signed-msg order messages.
+     * @param message - Bytes to sign.
+     * @param keypair - Keypair to sign with; defaults to `this.wallet.payer`.
+     * @throws If no keypair is available (e.g. the configured wallet has no local `payer`, such as
+     * a browser-extension wallet — that case must sign the message externally instead).
+     * @returns The detached ed25519 signature.
+     */
     signMessage(message: Uint8Array, keypair?: Keypair | undefined): Buffer;
+    /**
+     * Submits a previously off-chain-signed swift/signed-msg taker order on-chain: verifies the
+     * ed25519 signature via the sysvar-instructions program and records the order in the taker's
+     * `SignedMsgUserOrders` account (see `initializeSignedMsgUserOrders`, required beforehand).
+     * This only registers the order — it does not place or fill it against the market; a keeper
+     * (or `placeAndMakeSignedMsgPerpOrder`) still performs the actual place/fill.
+     * @param signedSignedMsgOrderParams - The signed order payload from `signSignedMsgOrderParamsMessage`.
+     * @param marketIndex - Perp market index the signed order targets.
+     * @param takerInfo - Taker's account/authority info; `signingAuthority` is the delegate or
+     * direct authority that produced the signature (compared against `takerUserAccount.delegate`
+     * to determine whether the message decodes as the delegate-signer variant).
+     * @param precedingIxs - Instructions that will precede the returned ones in the final
+     * transaction; used only to compute the correct sysvar-instructions index for signature
+     * verification (has no other effect — the caller is still responsible for including them).
+     * @param overrideCustomIxIndex - Explicit index of the ed25519-verify instruction within the
+     * final transaction; overrides the value derived from `precedingIxs.length`.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     placeSignedMsgTakerOrder(signedSignedMsgOrderParams: SignedMsgOrderParams, marketIndex: number, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
         takerUserAccount: UserAccount;
         signingAuthority: PublicKey;
     }, precedingIxs?: TransactionInstruction[], overrideCustomIxIndex?: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the two instructions for `placeSignedMsgTakerOrder`: an ed25519-signature-verify
+     * instruction (must be placed at the sysvar-instructions index this function assumes — see
+     * `precedingIxs`/`overrideCustomIxIndex`) followed by the `placeSignedMsgTakerOrder` program
+     * instruction. See `placeSignedMsgTakerOrder` for semantics.
+     * @param signedSignedMsgOrderParams - The signed order payload.
+     * @param marketIndex - Perp market index the signed order targets.
+     * @param takerInfo - Taker's account/authority info; see `placeSignedMsgTakerOrder`.
+     * @param precedingIxs - Instructions preceding these two in the final transaction (used only
+     * to compute the ed25519-verify instruction's sysvar index).
+     * @param overrideCustomIxIndex - Explicit sysvar-instructions index override.
+     * @returns `[ed25519VerifyIx, placeSignedMsgTakerOrderIx]`.
+     */
     getPlaceSignedMsgTakerPerpOrderIxs(signedSignedMsgOrderParams: SignedMsgOrderParams, marketIndex: number, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
         takerUserAccount: UserAccount;
         signingAuthority: PublicKey;
     }, precedingIxs?: TransactionInstruction[], overrideCustomIxIndex?: number): Promise<TransactionInstruction[]>;
+    /**
+     * Verifies and registers a taker's off-chain signed swift/signed-msg order (same as
+     * `placeSignedMsgTakerOrder`) and, in the same transaction, places a maker order and fills the
+     * taker order against it in one shot — the signed-msg analog of `placeAndMakePerpOrder`.
+     * `orderParams` (the maker order) is subject to the same IOC/post-only/limit requirement as
+     * `placeAndMakePerpOrder`.
+     * @param signedSignedMsgOrderParams - The taker's signed order payload.
+     * @param signedMsgOrderUuid - UUID identifying the signed-msg order, used by the program to
+     * dedupe/match it against the recorded `SignedMsgUserOrders` entry.
+     * @param takerInfo - Taker's account/authority info; see `placeSignedMsgTakerOrder`.
+     * @param orderParams - Maker order to place; `baseAssetAmount` is BASE_PRECISION (1e9), `price`
+     * is PRICE_PRECISION (1e6). Must have `orderType: LIMIT`, `postOnly` set, and be IOC.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account placing the maker order; defaults to the active sub-account.
+     * @param precedingIxs - Instructions preceding these in the final transaction (used only to
+     * compute the ed25519-verify instruction's sysvar index).
+     * @param overrideCustomIxIndex - Explicit sysvar-instructions index override.
+     * @param takerEscrow - The taker's decoded `RevenueShareEscrow`. Required to attach the escrow
+     * when the taker is referred but the signed order carries no builder code.
+     * @returns The transaction signature.
+     */
     placeAndMakeSignedMsgPerpOrder(signedSignedMsgOrderParams: SignedMsgOrderParams, signedMsgOrderUuid: Uint8Array, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
         takerUserAccount: UserAccount;
         signingAuthority: PublicKey;
     }, orderParams: OptionalOrderParams, txParams?: TxParams, subAccountId?: number, precedingIxs?: TransactionInstruction[], overrideCustomIxIndex?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
+    /**
+     * Builds the instructions for `placeAndMakeSignedMsgPerpOrder`: the taker signature-verify +
+     * registration instructions from `getPlaceSignedMsgTakerPerpOrderIxs`, followed by the
+     * `placeAndMakeSignedMsgPerpOrder` program instruction. See `placeAndMakeSignedMsgPerpOrder`
+     * for semantics.
+     * @param signedSignedMsgOrderParams - The taker's signed order payload.
+     * @param signedMsgOrderUuid - UUID identifying the signed-msg order.
+     * @param takerInfo - Taker's account/authority info.
+     * @param orderParams - Maker order to place; see `placeAndMakeSignedMsgPerpOrder` for field
+     * precisions and required order shape.
+     * @param subAccountId - Sub-account placing the maker order; defaults to the active sub-account.
+     * @param precedingIxs - Instructions preceding these in the final transaction (used only to
+     * compute the ed25519-verify instruction's sysvar index).
+     * @param overrideCustomIxIndex - Explicit sysvar-instructions index override.
+     * @param takerEscrow - See `placeAndMakeSignedMsgPerpOrder`.
+     * @returns `[ed25519VerifyIx, placeSignedMsgTakerOrderIx, placeAndMakeSignedMsgPerpOrderIx]`.
+     */
     getPlaceAndMakeSignedMsgPerpOrderIxs(signedSignedMsgOrderParams: SignedMsgOrderParams, signedMsgOrderUuid: Uint8Array, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
         takerUserAccount: UserAccount;
         signingAuthority: PublicKey;
     }, orderParams: OptionalOrderParams, subAccountId?: number, precedingIxs?: TransactionInstruction[], overrideCustomIxIndex?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction[]>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     preparePlaceAndTakeSpotOrder(_orderParams: OptionalOrderParams, _fulfillmentConfig?: unknown, _makerInfo?: MakerInfo, _txParams?: TxParams, _subAccountId?: number): Promise<void>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     placeAndTakeSpotOrder(_orderParams: OptionalOrderParams, _fulfillmentConfig?: unknown, _makerInfo?: MakerInfo, _txParams?: TxParams, _subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     getPlaceAndTakeSpotOrderIx(_orderParams: OptionalOrderParams, _fulfillmentConfig?: unknown, _makerInfo?: MakerInfo, _subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     placeAndMakeSpotOrder(_orderParams: OptionalOrderParams, _takerInfo: TakerInfo, _fulfillmentConfig?: unknown, _txParams?: TxParams, _subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Disabled. See `placeSpotOrder`.
+     * @throws Always throws with the spot-DLOB-disabled message.
+     */
     getPlaceAndMakeSpotOrderIx(_orderParams: OptionalOrderParams, _takerInfo: TakerInfo, _fulfillmentConfig?: unknown, _subAccountId?: number): Promise<TransactionInstruction>;
     /**
-     * @deprecated use {@link placePerpOrder} or {@link placeAndTakePerpOrder} instead
+     * Closes (or reduces to zero) the caller's entire perp position in `marketIndex` with a
+     * reduce-only market order (or limit order if `limitPrice` is given), filled immediately via
+     * `placeAndTakePerpOrder`.
+     * @deprecated use `placePerpOrder` or `placeAndTakePerpOrder` instead.
+     * @param marketIndex - Perp market index of the position to close.
+     * @param limitPrice - Optional limit price, PRICE_PRECISION (1e6); omit for a pure market order.
+     * @param subAccountId - Sub-account holding the position; defaults to the active sub-account.
+     * @throws If there is no open position in `marketIndex` for the sub-account.
+     * @returns The transaction signature.
      */
     closePosition(marketIndex: number, limitPrice?: BN, subAccountId?: number): Promise<TransactionSignature>;
     /**
      * Modifies an open order by closing it and replacing it with a new order.
-     * @deprecated use modifyOrder instead
-     * @param orderId: The open order to modify
-     * @param newBaseAmount: The new base amount for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @param newLimitPice: The new limit price for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @param newOraclePriceOffset: The new oracle price offset for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @returns
+     * @deprecated use `modifyOrder` instead.
+     * @param orderId - The open order to modify (program-assigned order ID).
+     * @param newBaseAmount - The new base amount for the order, BASE_PRECISION (1e9). One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @param newLimitPrice - The new limit price for the order, PRICE_PRECISION (1e6). One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @param newOraclePriceOffset - The new oracle price offset for the order, PRICE_PRECISION (1e6), signed. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @returns The transaction signature.
      */
     modifyPerpOrder(orderId: number, newBaseAmount?: BN, newLimitPrice?: BN, newOraclePriceOffset?: BN): Promise<TransactionSignature>;
     /**
      * Modifies an open order by closing it and replacing it with a new order.
-     * @deprecated use modifyOrderByUserOrderId instead
-     * @param userOrderId: The open order to modify
-     * @param newBaseAmount: The new base amount for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @param newLimitPice: The new limit price for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @param newOraclePriceOffset: The new oracle price offset for the order. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
-     * @returns
+     * @deprecated use `modifyOrderByUserOrderId` instead.
+     * @param userOrderId - The open order to modify (caller-supplied `userOrderId`).
+     * @param newBaseAmount - The new base amount for the order, BASE_PRECISION (1e9). One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @param newLimitPrice - The new limit price for the order, PRICE_PRECISION (1e6). One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @param newOraclePriceOffset - The new oracle price offset for the order, PRICE_PRECISION (1e6), signed. One of [newBaseAmount|newLimitPrice|newOraclePriceOffset] must be provided.
+     * @returns The transaction signature.
      */
     modifyPerpOrderByUserOrderId(userOrderId: number, newBaseAmount?: BN, newLimitPrice?: BN, newOraclePriceOffset?: BN): Promise<TransactionSignature>;
     /**
-     * Modifies an open order (spot or perp) by closing it and replacing it with a new order.
-     * @param orderParams.orderId: The open order to modify
-     * @param orderParams.newDirection: The new direction for the order
-     * @param orderParams.newBaseAmount: The new base amount for the order
-     * @param orderParams.newLimitPice: The new limit price for the order
-     * @param orderParams.newOraclePriceOffset: The new oracle price offset for the order
-     * @param orderParams.newTriggerPrice: Optional - Thew new trigger price for the order.
-     * @param orderParams.auctionDuration:
-     * @param orderParams.auctionStartPrice:
-     * @param orderParams.auctionEndPrice:
-     * @param orderParams.reduceOnly:
-     * @param orderParams.postOnly:
-     * @param orderParams.bitFlags:
-     * @param orderParams.policy:
-     * @param orderParams.maxTs:
-     * @returns
+     * Modifies an open order (spot or perp) by closing it and replacing it with a new order in one
+     * instruction. Only fields present (non-`undefined`) in `orderParams` are changed; the rest of
+     * the order is left as-is.
+     * @param orderParams.orderId - The open order to modify (program-assigned order ID).
+     * @param orderParams.newDirection - The new direction for the order.
+     * @param orderParams.newBaseAmount - The new base amount for the order, BASE_PRECISION (1e9).
+     * @param orderParams.newLimitPrice - The new limit price for the order, PRICE_PRECISION (1e6).
+     * @param orderParams.newOraclePriceOffset - The new oracle price offset for the order, PRICE_PRECISION (1e6), signed.
+     * @param orderParams.newTriggerPrice - Optional - the new trigger price for the order, PRICE_PRECISION (1e6).
+     * @param orderParams.auctionDuration - Slots the auction lasts; only relevant for market/oracle orders.
+     * @param orderParams.auctionStartPrice - PRICE_PRECISION (1e6), signed; only relevant for market/oracle orders.
+     * @param orderParams.auctionEndPrice - PRICE_PRECISION (1e6), signed; only relevant for market/oracle orders.
+     * @param orderParams.reduceOnly - Whether the modified order must only reduce the position.
+     * @param orderParams.postOnly - Post-only behavior for the modified order.
+     * @param orderParams.bitFlags - Bitmask, see `OrderParamsBitFlag`.
+     * @param orderParams.policy - Bitmask of `ModifyOrderPolicy` (e.g. `MustModify`, `ExcludePreviousFill`).
+     * @param orderParams.maxTs - Unix timestamp after which the order expires.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @returns The transaction signature.
      */
     modifyOrder(orderParams: {
         orderId: number;
@@ -924,10 +2960,12 @@ export declare class VelocityClient {
         policy?: number;
     }, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
     /**
-     * @param orderParams: The parameters for the order to modify.
-     * @param subAccountId: Optional - The subaccount ID of the user to modify the order for.
-     * @param userPublicKey: Optional - The public key of the user to modify the order for. This takes precedence over subAccountId.
-     * @returns
+     * Builds the `modifyOrder` instruction. See `modifyOrder` for field semantics/precisions.
+     * @param orderParams - The parameters for the order to modify.
+     * @param subAccountId - Optional - the sub-account ID of the user to modify the order for; ignored if `overrides.user` is set.
+     * @param overrides - `user` supplies a fully-loaded `User` to modify on behalf of (takes precedence over `subAccountId`); `authority` overrides the signing authority (defaults to `overrides.user`'s authority, else `this.wallet.publicKey`).
+     * @throws If `overrides.user` is provided but its `UserAccount` isn't loaded.
+     * @returns The instruction.
      */
     getModifyOrderIx({ orderId, newDirection, newBaseAmount, newLimitPrice, newOraclePriceOffset, newTriggerPrice, newTriggerCondition, auctionDuration, auctionStartPrice, auctionEndPrice, reduceOnly, postOnly, bitFlags, maxTs, policy, }: {
         orderId: number;
@@ -950,22 +2988,29 @@ export declare class VelocityClient {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
     /**
-     * Modifies an open order by closing it and replacing it with a new order.
-     * @param orderParams.userOrderId: The open order to modify
-     * @param orderParams.newDirection: The new direction for the order
-     * @param orderParams.newBaseAmount: The new base amount for the order
-     * @param orderParams.newLimitPice: The new limit price for the order
-     * @param orderParams.newOraclePriceOffset: The new oracle price offset for the order
-     * @param orderParams.newTriggerPrice: Optional - Thew new trigger price for the order.
-     * @param orderParams.auctionDuration: Only required if order type changed to market from something else
-     * @param orderParams.auctionStartPrice: Only required if order type changed to market from something else
-     * @param orderParams.auctionEndPrice: Only required if order type changed to market from something else
-     * @param orderParams.reduceOnly:
-     * @param orderParams.postOnly:
-     * @param orderParams.bitFlags:
-     * @param orderParams.policy:
-     * @param orderParams.maxTs:
-     * @returns
+     * Modifies an open order (identified by its caller-supplied `userOrderId`) by closing it and
+     * replacing it with a new order in one instruction.
+     *
+     * Note: unlike `modifyOrder`, omitted `reduceOnly`/`bitFlags` are sent as `false`/`null`
+     * respectively rather than "leave unchanged" — passing this method's `orderParams` without
+     * `reduceOnly` will explicitly clear an existing reduce-only flag on the order.
+     * @param orderParams.userOrderId - The open order to modify (caller-supplied `userOrderId`).
+     * @param orderParams.newDirection - The new direction for the order.
+     * @param orderParams.newBaseAmount - The new base amount for the order, BASE_PRECISION (1e9).
+     * @param orderParams.newLimitPrice - The new limit price for the order, PRICE_PRECISION (1e6).
+     * @param orderParams.newOraclePriceOffset - The new oracle price offset for the order, PRICE_PRECISION (1e6), signed.
+     * @param orderParams.newTriggerPrice - Optional - the new trigger price for the order, PRICE_PRECISION (1e6).
+     * @param orderParams.auctionDuration - Only required if order type changed to market from something else; slots.
+     * @param orderParams.auctionStartPrice - Only required if order type changed to market from something else; PRICE_PRECISION (1e6), signed.
+     * @param orderParams.auctionEndPrice - Only required if order type changed to market from something else; PRICE_PRECISION (1e6), signed.
+     * @param orderParams.reduceOnly - Whether the modified order must only reduce the position; defaults to `false` if omitted.
+     * @param orderParams.postOnly - Post-only behavior for the modified order.
+     * @param orderParams.bitFlags - Bitmask, see `OrderParamsBitFlag`; defaults to unset if omitted.
+     * @param orderParams.policy - `ModifyOrderPolicy` bitmask (e.g. `MustModify`, `ExcludePreviousFill`).
+     * @param orderParams.maxTs - Unix timestamp after which the order expires.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @returns The transaction signature.
      */
     modifyOrderByUserOrderId(orderParams: {
         userOrderId: number;
@@ -984,6 +3029,13 @@ export declare class VelocityClient {
         policy?: ModifyOrderPolicy;
         maxTs?: BN;
     }, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `modifyOrderByUserOrderId` instruction. See `modifyOrderByUserOrderId` for field
+     * semantics/precisions, including the `reduceOnly`/`bitFlags` default-clearing note.
+     * @param orderParams - The parameters for the order to modify.
+     * @param subAccountId - Sub-account the order belongs to; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getModifyOrderByUserIdIx({ userOrderId, newDirection, newBaseAmount, newLimitPrice, newOraclePriceOffset, newTriggerPrice, newTriggerCondition, auctionDuration, auctionStartPrice, auctionEndPrice, reduceOnly, postOnly, bitFlags, maxTs, policy, }: {
         userOrderId: number;
         newDirection?: PositionDirection;
@@ -1001,31 +3053,247 @@ export declare class VelocityClient {
         policy?: ModifyOrderPolicy;
         maxTs?: BN;
     }, subAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: settles unrealized perp PnL to/from each user's quote spot balance for
+     * every `(user, marketIndex)` pair, one `settlePnl` instruction per pair in a single
+     * transaction. Permissionless — any signer can act as the settling authority. Defaults to
+     * `computeUnits: 1_400_000` if `txParams` is not supplied, since settling several users/markets
+     * in one transaction is compute-heavy.
+     * @param users - Users to settle, each with their user account public key and decoded account.
+     * @param marketIndexes - Perp market indexes to settle for every user in `users`.
+     * @param opts.filterInvalidMarkets - When true, drops any market index whose oracle currently
+     * fails `isOracleValid` (per the on-chain oracle guard rails) before building instructions,
+     * instead of letting the transaction fail on-chain for that market.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settlePNLs(users: {
         settleeUserAccountPublicKey: PublicKey;
         settleeUserAccount: UserAccount;
     }[], marketIndexes: number[], opts?: {
         filterInvalidMarkets?: boolean;
     }, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds one `settlePnl` instruction per `(user, marketIndex)` combination in `users` x
+     * `marketIndexes`. See `settlePNL`/`settlePNLIx` for per-instruction semantics.
+     * @param users - Users to settle, each with their user account public key and decoded account.
+     * @param marketIndexes - Perp market indexes to settle for every user in `users`.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup; when a user's escrow
+     * has completed builder or referral orders on a market being settled, its `RevenueShareEscrow`
+     * and builder/referrer accounts are attached so the on-chain sweep can pay them out.
+     * @returns The ordered instruction list.
+     */
     getSettlePNLsIxs(users: {
         settleeUserAccountPublicKey: PublicKey;
         settleeUserAccount: UserAccount;
     }[], marketIndexes: number[], revenueShareEscrowMap?: RevenueShareEscrowMap): Promise<Array<TransactionInstruction>>;
+    /**
+     * Keeper instruction: settles a single user's unrealized perp PnL on one market to/from their
+     * quote spot balance. Reads the live oracle (falling back to the AMM's freshness check only if
+     * the live oracle is degraded); requires the market not be in `Settlement` status (use
+     * `settleExpiredMarket`/expired-position settlement for that) and the quote spot market vault
+     * balance to reconcile afterward. Permissionless — any signer can act as the settling authority.
+     * @param settleeUserAccountPublicKey - Public key of the user account to settle.
+     * @param settleeUserAccount - Decoded user account to settle.
+     * @param marketIndex - Perp market index to settle.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param optionalIxs - Extra instructions prepended to the settle transaction.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup; see `settlePNLIx`.
+     * @returns The transaction signature.
+     */
     settlePNL(settleeUserAccountPublicKey: PublicKey, settleeUserAccount: UserAccount, marketIndex: number, txParams?: TxParams, optionalIxs?: TransactionInstruction[], revenueShareEscrowMap?: RevenueShareEscrowMap): Promise<TransactionSignature>;
+    /**
+     * Builds the `settlePnl` instruction. See `settlePNL` for semantics. When
+     * `revenueShareEscrowMap` is passed, inspects the settlee's `RevenueShareEscrow` for
+     * completed, unpaid builder-fee or referral-reward orders on `marketIndex` and, if found,
+     * appends the escrow PDA plus each relevant builder/referrer authority to
+     * `remainingAccounts` so the on-chain sweep can pay them during settlement. Falls back to
+     * attaching just the escrow PDA (for lazy cleanup) when the settlee has any builder order but
+     * isn't present in the map (stale-cache case).
+     * @param settleeUserAccountPublicKey - Public key of the user account to settle.
+     * @param settleeUserAccount - Decoded user account to settle.
+     * @param marketIndex - Perp market index to settle.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup keyed by authority.
+     * @returns The instruction.
+     */
     settlePNLIx(settleeUserAccountPublicKey: PublicKey, settleeUserAccount: UserAccount, marketIndex: number, revenueShareEscrowMap?: RevenueShareEscrowMap): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: settles one user's unrealized perp PnL across several markets in a
+     * single `settleMultiplePnl` instruction/transaction. Fits at most ~4 markets per transaction
+     * (see `settleMultiplePNLsMultipleTxs` for more). Permissionless — any signer can act as the
+     * settling authority.
+     * @param settleeUserAccountPublicKey - Public key of the user account to settle.
+     * @param settleeUserAccount - Decoded user account to settle.
+     * @param marketIndexes - Perp market indexes to settle (all in one transaction).
+     * @param mode - `MustSettle` aborts the whole instruction if any per-market settlement fails;
+     * `TrySettle` logs and skips failures so the remaining markets still settle.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup; see `settlePNLIx`.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settleMultiplePNLs(settleeUserAccountPublicKey: PublicKey, settleeUserAccount: UserAccount, marketIndexes: number[], mode: SettlePnlMode, revenueShareEscrowMap?: RevenueShareEscrowMap, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Settles one user's unrealized perp PnL across an arbitrary number of markets by splitting
+     * `marketIndexes` into groups of 4 (more than ~4 markets' worth of accounts won't fit in a
+     * single transaction) and sending one `settleMultiplePnl` transaction per group, sequentially.
+     * Compute units scale with group size (`300_000` per market, capped at `1_400_000`).
+     * @param settleeUserAccountPublicKey - Public key of the user account to settle.
+     * @param settleeUserAccount - Decoded user account to settle.
+     * @param marketIndexes - Perp market indexes to settle, in any quantity.
+     * @param mode - `MustSettle` or `TrySettle`; see `settleMultiplePNLs`.
+     * @param txParams - Optional compute-unit/priority-fee overrides (compute units are overridden
+     * per group regardless of what is passed here).
+     * @param optionalIxs - Extra instructions prepended to every group's transaction.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup; see `settlePNLIx`.
+     * @returns One transaction signature per group of up to 4 markets, in group order.
+     */
     settleMultiplePNLsMultipleTxs(settleeUserAccountPublicKey: PublicKey, settleeUserAccount: UserAccount, marketIndexes: number[], mode: SettlePnlMode, txParams?: TxParams, optionalIxs?: TransactionInstruction[], revenueShareEscrowMap?: RevenueShareEscrowMap): Promise<TransactionSignature[]>;
+    /**
+     * Builds the `settleMultiplePnl` instruction. See `settleMultiplePNLs` for semantics. Attaches
+     * the settlee's `RevenueShareEscrow` and any relevant builder/referrer accounts when
+     * `revenueShareEscrowMap` shows completed builder/referral orders on any of `marketIndexes`
+     * (same logic as `settlePNLIx`, generalized across markets).
+     * @param settleeUserAccountPublicKey - Public key of the user account to settle.
+     * @param settleeUserAccount - Decoded user account to settle.
+     * @param marketIndexes - Perp market indexes to settle.
+     * @param mode - `MustSettle` or `TrySettle`; see `settleMultiplePNLs`.
+     * @param overrides.authority - Settling authority override, if different from this client's wallet.
+     * @param revenueShareEscrowMap - Optional builder/referral escrow lookup keyed by authority.
+     * @returns The instruction.
+     */
     settleMultiplePNLsIx(settleeUserAccountPublicKey: PublicKey, settleeUserAccount: UserAccount, marketIndexes: number[], mode: SettlePnlMode, overrides?: {
         authority?: PublicKey;
     }, revenueShareEscrowMap?: RevenueShareEscrowMap): Promise<TransactionInstruction>;
+    /**
+     * Builds the `setUserStatusToBeingLiquidated` instruction. See `setUserStatusToBeingLiquidated`
+     * for semantics.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param userAccount - Decoded user account of the target user.
+     * @returns The instruction.
+     */
     getSetUserStatusToBeingLiquidatedIx(userAccountPublicKey: PublicKey, userAccount: UserAccount): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: flags a user account as being liquidated (sets the `beingLiquidated`
+     * status bit) without performing any liquidation itself. Used to "claim" a liquidation ahead of
+     * the actual `liquidatePerp`/`liquidateSpot` call so a concurrent liquidator can't race it; the
+     * on-chain handler re-checks the user is actually below maintenance margin before setting the
+     * flag. Permissionless — any signer can act as liquidator.
+     * @param userAccountPublicKey - Public key of the target user's user account.
+     * @param userAccount - Decoded user account of the target user.
+     * @returns The transaction signature.
+     */
     setUserStatusToBeingLiquidated(userAccountPublicKey: PublicKey, userAccount: UserAccount): Promise<TransactionSignature>;
+    /**
+     * Keeper instruction: liquidates part or all of a user's perp position in `marketIndex` when the
+     * user is below maintenance margin (or already flagged `beingLiquidated`), transferring the
+     * 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.
+     * @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.
+     * @param maxBaseAssetAmount - Maximum base amount the liquidator is willing to take on, BASE_PRECISION (1e9).
+     * @param limitPrice - Optional worst acceptable price for the liquidator, PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     liquidatePerp(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, maxBaseAssetAmount: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `liquidatePerp` instruction. See `liquidatePerp` for semantics.
+     * @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.
+     * @param maxBaseAssetAmount - Maximum base amount the liquidator is willing to take on, BASE_PRECISION (1e9).
+     * @param limitPrice - Optional worst acceptable price for the liquidator, PRICE_PRECISION (1e6).
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getLiquidatePerpIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, maxBaseAssetAmount: BN, limitPrice?: BN, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: liquidates a user's perp position in `marketIndex` by filling it directly
+     * against the supplied `makerInfos` (instead of transferring it to the liquidator's own
+     * sub-account as `liquidatePerp` does). Reverts if `userAccountPublicKey` equals the liquidator's
+     * own user account. Permissionless — any signer can act as liquidator/filler.
+     * @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.
+     * @param makerInfos - Maker(s) to fill the liquidated position against.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     liquidatePerpWithFill(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, makerInfos: MakerInfo[], txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `liquidatePerpWithFill` instruction. See `liquidatePerpWithFill` for semantics.
+     * @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.
+     * @param makerInfos - Maker(s) to fill the liquidated position against; each contributes a
+     * `(maker, makerStats)` pair appended to `remainingAccounts`.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getLiquidatePerpWithFillIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, makerInfos: MakerInfo[], liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: liquidates a user's spot position by transferring `liabilityMarketIndex`
+     * 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.
+     * @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.
+     * @param liabilityMarketIndex - Spot market index of the debt the liquidator repays/absorbs.
+     * @param maxLiabilityTransfer - Maximum liability amount the liquidator is willing to take on, in
+     * the liability spot market's token (mint) precision.
+     * @param limitPrice - Optional worst acceptable asset/liability price ratio, PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     liquidateSpot(userAccountPublicKey: PublicKey, userAccount: UserAccount, assetMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `liquidateSpot` instruction. See `liquidateSpot` for semantics.
+     * @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.
+     * @param liabilityMarketIndex - Spot market index of the debt the liquidator repays/absorbs.
+     * @param maxLiabilityTransfer - Maximum liability amount the liquidator is willing to take on, in
+     * the liability spot market's token (mint) precision.
+     * @param limitPrice - Optional worst acceptable asset/liability price ratio, PRICE_PRECISION (1e6).
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getLiquidateSpotIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, assetMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Builds a Jupiter-routed spot-liquidation-with-swap instruction set: swaps the liquidator's
+     * `assetMarketIndex` proceeds into `liabilityMarketIndex` tokens via Jupiter inside a
+     * `beginSwap`/`endSwap` flash-loan sandwich (see `getLiquidateSpotWithSwapIx`), letting the
+     * liquidator repay the user's debt without needing to already hold the liability token. Fetches a
+     * quote from `jupiterClient` when `quote` is not supplied, and idempotently creates any missing
+     * associated token accounts.
+     * @param jupiterClient - Jupiter client used to fetch the quote/swap transaction.
+     * @param liabilityMarketIndex - Spot market index of the debt being repaid (swap output).
+     * @param assetMarketIndex - Spot market index of the collateral being sold (swap input).
+     * @param swapAmount - Amount of `assetMarketIndex` token to sell, in that market's mint precision.
+     * @param assetTokenAccount - Token account to debit for the swap input; defaults to this client's
+     * associated token account for `assetMarketIndex`, created if missing.
+     * @param liabilityTokenAccount - Token account to credit with the swap output; defaults to this
+     * client's associated token account for `liabilityMarketIndex`, created if missing.
+     * @param slippageBps - Max slippage in basis points passed to Jupiter.
+     * @param swapMode - Jupiter swap mode (`ExactIn`/`ExactOut`).
+     * @param onlyDirectRoutes - Restrict Jupiter to single-hop routes.
+     * @param quote - Pre-fetched Jupiter quote (skips an extra round-trip).
+     * @param userAccount - Decoded user account being liquidated.
+     * @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.
+     * @returns The ordered instructions (pre-instructions, `beginSwap`, Jupiter swap, `endSwap`) and
+     * any address lookup tables the Jupiter route requires.
+     */
     getJupiterLiquidateSpotWithSwapIxV6({ jupiterClient, liabilityMarketIndex, assetMarketIndex, swapAmount, assetTokenAccount, liabilityTokenAccount, slippageBps, swapMode, onlyDirectRoutes, quote, userAccount, userAccountPublicKey, liquidatorSubAccountId, maxAccounts, }: {
         jupiterClient: JupiterClient;
         liabilityMarketIndex: number;
@@ -1046,15 +3314,22 @@ export declare class VelocityClient {
         lookupTables: AddressLookupTableAccount[];
     }>;
     /**
-     * Get the velocity liquidate_spot_with_swap instructions
-     *
-     * @param liabilityMarketIndex the market index of the token you're buying
-     * @param assetMarketIndex the market index of the token you're selling
-     * @param amountIn the amount of the token to sell
-     * @param assetTokenAccount the token account to move the tokens being sold
-     * @param liabilityTokenAccount the token account to receive the tokens being bought
-     * @param userAccount
-     * @param userAccountPublicKey
+     * Builds the `liquidateSpotWithSwapBegin`/`...End` instruction pair that sandwiches an
+     * external swap (e.g. Jupiter) so a liquidator can repay a user's `liabilityMarketIndex` debt
+     * using proceeds from selling `assetMarketIndex` collateral within the same transaction, without
+     * pre-funding the liability token. The on-chain handler validates the liability spot market's
+     * flash-loan balance is unwound by `endSwap`. See `getJupiterLiquidateSpotWithSwapIxV6` for the
+     * Jupiter-specific wrapper that assembles the full instruction list around this pair.
+     * @param liabilityMarketIndex - Spot market index of the debt being repaid (swap output/buy side).
+     * @param assetMarketIndex - Spot market index of the collateral being sold (swap input/sell side).
+     * @param swapAmount - Amount of `assetMarketIndex` token to sell, in that market's mint precision.
+     * @param assetTokenAccount - Token account to debit for the swap input.
+     * @param liabilityTokenAccount - Token account to credit with the swap output.
+     * @param userAccount - Decoded user account being liquidated.
+     * @param userAccountPublicKey - Public key of the user account being liquidated.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns `beginSwapIx`/`endSwapIx` — the caller must place the external swap instructions
+     * between them.
      */
     getLiquidateSpotWithSwapIx({ liabilityMarketIndex, assetMarketIndex, swapAmount: swapAmount, assetTokenAccount, liabilityTokenAccount, userAccount, userAccountPublicKey, liquidatorSubAccountId, }: {
         liabilityMarketIndex: number;
@@ -1069,28 +3344,271 @@ export declare class VelocityClient {
         beginSwapIx: TransactionInstruction;
         endSwapIx: TransactionInstruction;
     }>;
+    /**
+     * Keeper instruction: liquidates a user by transferring `liabilityMarketIndex` spot debt from the
+     * user to the liquidator in exchange for a matching amount of the user's positive unsettled perp
+     * 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.
+     * @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).
+     * @param liabilityMarketIndex - Spot market index of the debt being repaid.
+     * @param maxLiabilityTransfer - Maximum liability amount the liquidator is willing to take on, in
+     * the liability spot market's token (mint) precision.
+     * @param limitPrice - Optional worst acceptable liability/PnL price ratio, PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     liquidateBorrowForPerpPnl(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `liquidateBorrowForPerpPnl` instruction. See `liquidateBorrowForPerpPnl` for semantics.
+     * @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.
+     * @param liabilityMarketIndex - Spot market index of the debt being repaid.
+     * @param maxLiabilityTransfer - Maximum liability amount the liquidator is willing to take on, in
+     * the liability spot market's token (mint) precision.
+     * @param limitPrice - Optional worst acceptable liability/PnL price ratio, PRICE_PRECISION (1e6).
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getLiquidateBorrowForPerpPnlIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: liquidates a user by transferring negative unsettled perp PnL in
+     * `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.
+     * @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.
+     * @param assetMarketIndex - Spot market index of the collateral the liquidator receives.
+     * @param maxPnlTransfer - Maximum PnL amount the liquidator is willing to absorb, QUOTE_PRECISION (1e6).
+     * @param limitPrice - Optional worst acceptable PnL/asset price ratio, PRICE_PRECISION (1e6).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     liquidatePerpPnlForDeposit(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, assetMarketIndex: number, maxPnlTransfer: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `liquidatePerpPnlForDeposit` instruction. See `liquidatePerpPnlForDeposit` for semantics.
+     * @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.
+     * @param assetMarketIndex - Spot market index of the collateral the liquidator receives.
+     * @param maxPnlTransfer - Maximum PnL amount the liquidator is willing to absorb, QUOTE_PRECISION (1e6).
+     * @param limitPrice - Optional worst acceptable PnL/asset price ratio, PRICE_PRECISION (1e6).
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getLiquidatePerpPnlForDepositIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, assetMarketIndex: number, maxPnlTransfer: BN, limitPrice?: BN, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: resolves a user's perp bankruptcy in `marketIndex` (negative equity that
+     * liquidation alone could not cover) by socializing the loss — first attempting to backstop it
+     * from the quote spot market's insurance fund, then socializing any remainder across the market's
+     * other position holders via the cumulative funding/PnL pool. Reverts if the resulting insurance
+     * payout would fully drain the insurance fund vault, or if `userAccountPublicKey` equals the
+     * liquidator's own user account. Permissionless — any signer can act as liquidator.
+     * @param userAccountPublicKey - Public key of the bankrupt user's user account.
+     * @param userAccount - Decoded user account of the bankrupt user.
+     * @param marketIndex - Perp market index of the bankrupt position.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     resolvePerpBankruptcy(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `resolvePerpBankruptcy` instruction. See `resolvePerpBankruptcy` for semantics.
+     * Always settles against the quote spot market (`QUOTE_SPOT_MARKET_INDEX`).
+     * @param userAccountPublicKey - Public key of the bankrupt user's user account.
+     * @param userAccount - Decoded user account of the bankrupt user.
+     * @param marketIndex - Perp market index of the bankrupt position.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getResolvePerpBankruptcyIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: resolves a user's spot bankruptcy (negative balance in `marketIndex` that
+     * liquidation alone could not cover) by backstopping the deficit from that spot market's
+     * insurance fund. Reverts if `userAccountPublicKey` equals the liquidator's own user account.
+     * Permissionless — any signer can act as liquidator.
+     * @param userAccountPublicKey - Public key of the bankrupt user's user account.
+     * @param userAccount - Decoded user account of the bankrupt user.
+     * @param marketIndex - Spot market index of the bankrupt balance.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The transaction signature.
+     */
     resolveSpotBankruptcy(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `resolveSpotBankruptcy` instruction. See `resolveSpotBankruptcy` for semantics.
+     * Adds the spot market's mint (and transfer-hook extra account metas, if applicable) to
+     * `remainingAccounts` for the token transfer from the insurance fund vault.
+     * @param userAccountPublicKey - Public key of the bankrupt user's user account.
+     * @param userAccount - Decoded user account of the bankrupt user.
+     * @param marketIndex - Spot market index of the bankrupt balance.
+     * @param liquidatorSubAccountId - Liquidator's sub-account to credit; defaults to the active sub-account.
+     * @returns The instruction.
+     */
     getResolveSpotBankruptcyIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, marketIndex: number, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: recomputes and applies `marketIndex`'s hourly-anchored funding rate
+     * (`cumulativeFundingRateLong`/`Short`, FUNDING_RATE_PRECISION, 1e9) from the current oracle/AMM
+     * mark-price spread, then updates the market's oracle-derived TWAP stats. No-ops (via
+     * `FundingWasNotUpdated`, which the underlying call surfaces as a failed transaction) if it is
+     * not yet time for the next update — `perp_market.market_stats.funding_period` seconds since the
+     * last update, on-the-hour aligned. Reverts if the market's funding is paused or the market is
+     * not `Active`/`ReduceOnly`. Permissionless — any signer can act as keeper.
+     * @param perpMarketIndex - Perp market index to update funding for.
+     * @param oracle - The market's oracle account (`perpMarket.oracle`).
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updateFundingRate(perpMarketIndex: number, oracle: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFundingRate` instruction. See `updateFundingRate` for semantics.
+     * @param perpMarketIndex - Perp market index to update funding for.
+     * @param oracle - The market's oracle account (`perpMarket.oracle`).
+     * @returns The instruction.
+     */
     getUpdateFundingRateIx(perpMarketIndex: number, oracle: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: refreshes a `Prelaunch`-oracle-source perp market's synthetic oracle price
+     * from its own recent trading activity (used for markets without a live external price feed,
+     * e.g. pre-listing futures). Only valid when the market's `oracleSource` is `Prelaunch`.
+     * Permissionless — any signer can act as keeper.
+     * @param perpMarketIndex - Perp market index to update; must use the `Prelaunch` oracle source.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @throws If `perpMarketIndex`'s `oracleSource` is not `Prelaunch`.
+     * @returns The transaction signature.
+     */
     updatePrelaunchOracle(perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePrelaunchOracle` instruction. See `updatePrelaunchOracle` for semantics.
+     * @param perpMarketIndex - Perp market index to update; must use the `Prelaunch` oracle source.
+     * @throws If `perpMarketIndex`'s `oracleSource` is not `Prelaunch`.
+     * @returns The instruction.
+     */
     getUpdatePrelaunchOracleIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: estimates the market's bid/ask price from the given makers' resting DLOB
+     * orders (filtered to those within `BID_ASK_TWAP_MAX_ORACLE_DIVERGENCE_PERCENT` of the oracle
+     * price) and folds the estimate into `lastBidPriceTwap`/`lastAskPriceTwap`. Restricted: the
+     * calling wallet's `UserStats` must have `canUpdateBidAskTwap` set and at least 1000 USDC
+     * (`QUOTE_PRECISION`, 1e6) staked in the insurance fund (`ifStakedQuoteAssetAmount`), or the
+     * instruction reverts.
+     * @param perpMarketIndex - Perp market index to update.
+     * @param makers - `(maker, makerStats)` pairs whose resting orders are sampled for the estimate.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updatePerpBidAskTwap(perpMarketIndex: number, makers: [PublicKey, PublicKey][], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpBidAskTwap` instruction. See `updatePerpBidAskTwap` for semantics.
+     * @param perpMarketIndex - Perp market index to update.
+     * @param makers - `(maker, makerStats)` pairs whose resting orders are sampled for the estimate.
+     * @returns The instruction.
+     */
     getUpdatePerpBidAskTwapIx(perpMarketIndex: number, makers: [PublicKey, PublicKey][]): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: settles accrued funding payments into the quote balance of every perp
+     * position the target user currently holds, using each market's latest
+     * `cumulativeFundingRateLong`/`Short` (FUNDING_RATE_PRECISION, 1e9). Fetches the user account
+     * fresh from the RPC (does not rely on this client's subscription cache) to determine which
+     * markets to include. Permissionless — any signer can act as keeper.
+     * @param userAccountPublicKey - Public key of the user account to settle funding for.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settleFundingPayment(userAccountPublicKey: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `settleFundingPayment` instruction. See `settleFundingPayment` for semantics. Fetches
+     * the user account directly via `program.account.user.fetch` and includes every market the user
+     * has a non-empty position in as a writable remaining account.
+     * @param userAccountPublicKey - Public key of the user account to settle funding for.
+     * @returns The instruction.
+     */
     getSettleFundingPaymentIx(userAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Manually emits an event on this client's internal `eventEmitter`, as if it had come from the
+     * account subscriber. Intended for tests/tooling that need to simulate account-update events;
+     * not used by normal instruction-building code paths.
+     * @param eventName - Name of the event to emit; see `VelocityClientAccountEvents`.
+     * @param data - Optional event payload.
+     */
     triggerEvent(eventName: keyof VelocityClientAccountEvents, data?: any): void;
+    /**
+     * Reads the last-known primary oracle price for a perp market from the account subscriber's
+     * cache (no RPC call). This is the raw exchange oracle price, unadjusted by the market's MM
+     * oracle — use `getMMOracleDataForPerpMarket` when you need the price the program actually uses
+     * for fills/margin.
+     * @param marketIndex - Perp market index.
+     * @throws If subscribed oracle price data is not available for `marketIndex`.
+     * @returns Oracle price data; `price`/`confidence` are PRICE_PRECISION (1e6).
+     */
     getOracleDataForPerpMarket(marketIndex: number): OraclePriceData;
+    /**
+     * Resolves the effective oracle price the program uses for `marketIndex` — the market's MM
+     * (market-maker-fed) oracle when it is fresher, valid, and not too divergent from the primary
+     * exchange oracle; otherwise falls back to the primary oracle. Mirrors the on-chain
+     * `get_mm_oracle_price_data` gating so client-side price reads (mark price, margin, liquidation
+     * previews) match what a fill/settlement will actually see.
+     *
+     * Falls back to the primary oracle (`getOracleDataForPerpMarket`) when any of the following hold:
+     *   - the MM oracle price is zero (uninitialized) or its computed `OracleValidity` is
+     *     `NonPositive`/`TooVolatile` (per `state.oracleGuardRails`);
+     *   - the primary oracle is judged more recent than the MM oracle — by sequence-id ordering when
+     *     both oracles have a usable, closely-matched `sequenceId`, otherwise by slot comparison;
+     *   - the MM and primary oracle prices diverge by more than 1% (`PERCENTAGE_PRECISION`, 1e6 scale).
+     *
+     * Otherwise returns the MM oracle's price/slot/confidence.
+     * @param marketIndex - Perp market index.
+     * @throws If subscribed oracle price data is not available for `marketIndex`.
+     * @returns Oracle price data (`price`/`confidence` at PRICE_PRECISION, 1e6) plus `isMMOracleActive`
+     * indicating whether the market has an initialized MM oracle at all (independent of which price
+     * was ultimately selected).
+     */
     getMMOracleDataForPerpMarket(marketIndex: number): MMOraclePriceData;
+    /**
+     * Reads the last-known oracle price for a spot market from the account subscriber's cache (no
+     * RPC call). Spot markets do not have an MM oracle — this is always the effective price used for
+     * margin/borrow-lending calculations.
+     * @param marketIndex - Spot market index.
+     * @throws If subscribed oracle price data is not available for `marketIndex`.
+     * @returns Oracle price data; `price`/`confidence` are PRICE_PRECISION (1e6).
+     */
     getOracleDataForSpotMarket(marketIndex: number): OraclePriceData;
+    /**
+     * Creates this wallet's `InsuranceFundStake` PDA for `marketIndex`, required once before staking
+     * into that market's insurance fund for the first time. A caller may only initialize their own
+     * stake account. Reverts if insurance-fund init is paused for the market.
+     * @param marketIndex - Spot market index whose insurance fund to stake into.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     initializeInsuranceFundStake(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeInsuranceFundStake` instruction. See `initializeInsuranceFundStake` for
+     * semantics.
+     * @param marketIndex - Spot market index whose insurance fund to stake into.
+     * @returns The instruction.
+     */
     getInitializeInsuranceFundStakeIx(marketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Builds the `addInsuranceFundStake` instruction, transferring `amount` of the market's token
+     * from `collateralAccountPublicKey` into its insurance fund vault and minting the caller's
+     * `InsuranceFundStake` the corresponding IF shares. Reverts if `amount` is zero, the spot market
+     * is not active, insurance-fund add is paused, or a withdraw request is already in progress on
+     * the stake account. See `addInsuranceFundStake`/`getAddInsuranceFundStakeIxs` for a wrapper that
+     * also handles account creation and funding from a sub-account.
+     * @param marketIndex - Spot market index whose insurance fund to stake into.
+     * @param amount - Amount to stake, in the spot market's token (mint) precision.
+     * @param collateralAccountPublicKey - Token account to debit for the stake.
+     * @returns The instruction.
+     */
     getAddInsuranceFundStakeIx(marketIndex: number, amount: BN, collateralAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
     /**
      * Add to an insurance fund stake and optionally initialize the account
@@ -1137,17 +3655,125 @@ export declare class VelocityClient {
          */
         fromSubaccount?: boolean;
     }): 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
+     * `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.
+     * @param marketIndex - Spot market index of the insurance fund stake.
+     * @param amount - Amount to request removal of, in the spot market's token (mint) precision;
+     * converted to IF shares at the current vault share price.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     requestRemoveInsuranceFundStake(marketIndex: number, amount: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Cancels this wallet's in-progress `requestRemoveInsuranceFundStake` for `marketIndex`, clearing
+     * the pending withdraw request so the stake resumes earning normally. Reverts if no withdraw
+     * request is currently in progress. A caller may only act on their own stake account.
+     * @param marketIndex - Spot market index of the insurance fund stake.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     cancelRequestRemoveInsuranceFundStake(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Completes a previously-requested insurance fund unstake for `marketIndex`, transferring the
+     * requested shares' worth of tokens from the insurance fund vault to `collateralAccountPublicKey`
+     * (creating it, and a temporary wrapped-SOL account if the market is SOL, when needed). Reverts
+     * if `spotMarket.insuranceFund.unstakingPeriod` has not yet elapsed since the matching
+     * `requestRemoveInsuranceFundStake`, or if the spot market's utilization is above the healthy
+     * threshold. A caller may only act on their own stake account.
+     * @param marketIndex - Spot market index of the insurance fund stake.
+     * @param collateralAccountPublicKey - Token account to receive the withdrawn tokens.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     removeInsuranceFundStake(marketIndex: number, collateralAccountPublicKey: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Keeper instruction: refreshes `authority`'s quote-market (`QUOTE_SPOT_MARKET_INDEX`) insurance
+     * fund stake bookkeeping (applies any pending rebase to the stake's share count/value) without
+     * adding or removing funds. `insuranceFundStake` and `userStats` must belong to the same
+     * authority. Permissionless — any signer can trigger the refresh for any staker.
+     * @param authority - Authority whose quote-market insurance fund stake to refresh.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updateUserQuoteAssetInsuranceStake(authority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserQuoteAssetInsuranceStake` instruction. See
+     * `updateUserQuoteAssetInsuranceStake` for semantics. Always targets `QUOTE_SPOT_MARKET_INDEX`.
+     * @param authority - Authority whose quote-market insurance fund stake to refresh.
+     * @returns The instruction.
+     */
     getUpdateUserQuoteAssetInsuranceStakeIx(authority: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: sweeps the market's proportional share of accumulated protocol revenue from
+     * its spot vault into its insurance fund vault. Only callable once per
+     * `spotMarket.insuranceFund.revenueSettlePeriod` seconds (on-the-hour aligned from
+     * `lastRevenueSettleTs`); reverts early with the remaining wait time otherwise. Reverts if the
+     * market has `revenueSettlePeriod <= 0` (settling to IF disabled). Permissionless — any signer
+     * can trigger the sweep.
+     * @param spotMarketIndex - Spot market index to settle revenue for.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     settleRevenueToInsuranceFund(spotMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `settleRevenueToInsuranceFund` instruction. See `settleRevenueToInsuranceFund` for
+     * semantics.
+     * @param spotMarketIndex - Spot market index to settle revenue for.
+     * @returns The instruction.
+     */
     getSettleRevenueToInsuranceFundIx(spotMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Permissionless streaming-sweep keeper instruction: materializes a perp market's accrued pending
+     * fee carveouts out of the PnL pool — `pendingProtocolFee` to the market's protocol fee pool
+     * (runs first, buffer-exempt), then `pendingIfFee` to the quote spot market's revenue pool and
+     * `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).
+     * @param perpMarketIndex - Perp market index to sweep fees for.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     sweepPerpMarketFees(perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `sweepPerpMarketFees` instruction. See `sweepPerpMarketFees` for semantics.
+     * @param perpMarketIndex - Perp market index to sweep fees for.
+     * @returns The instruction.
+     */
     getSweepPerpMarketFeesIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: backstops a perp market's negative PnL pool from the quote spot market's
+     * insurance fund (first attempting a revenue-to-IF settlement so the vault balance is
+     * up-to-date). `spotMarketIndex` must be `QUOTE_SPOT_MARKET_INDEX`. Permissionless — any signer
+     * can trigger it.
+     * @param spotMarketIndex - Spot market index backing the deficit; must be `QUOTE_SPOT_MARKET_INDEX`.
+     * @param perpMarketIndex - Perp market index whose PnL pool deficit to resolve.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @throws (on-chain) if `spotMarketIndex` is not the quote spot market.
+     * @returns The transaction signature.
+     */
     resolvePerpPnlDeficit(spotMarketIndex: number, perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `resolvePerpPnlDeficit` instruction. See `resolvePerpPnlDeficit` for semantics.
+     * @param spotMarketIndex - Spot market index backing the deficit; must be `QUOTE_SPOT_MARKET_INDEX`.
+     * @param perpMarketIndex - Perp market index whose PnL pool deficit to resolve.
+     * @returns The instruction.
+     */
     getResolvePerpPnlDeficitIx(spotMarketIndex: number, perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Builds the `depositIntoSpotMarketRevenuePool` instruction. See `depositIntoSpotMarketRevenuePool`
+     * for semantics.
+     * @param marketIndex - Spot market index whose revenue pool to donate into.
+     * @param amount - Amount to donate, in the spot market's token (mint) precision.
+     * @param userTokenAccountPublicKey - Token account to debit for the donation.
+     * @returns The instruction.
+     */
     getDepositIntoSpotMarketRevenuePoolIx(marketIndex: number, amount: BN, userTokenAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
     /**
      * This ix will donate your funds to velocity revenue pool. It does not deposit into your user account
@@ -1157,14 +3783,24 @@ export declare class VelocityClient {
      * @returns
      */
     depositIntoSpotMarketRevenuePool(marketIndex: number, amount: BN, userTokenAccountPublicKey: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Computes display/risk metadata for a perp market from currently-subscribed account state (no
+     * RPC call): minimum order size, maintenance margin ratio, PnL pool value, contract tier, and the
+     * maximum insurance available to the market.
+     * @param marketIndex - Perp market index.
+     * @returns `minOrderSize`/`marginMaintenance` in the market's native units; `pnlPoolValue` and
+     * `availableInsurance` in QUOTE_PRECISION (1e6).
+     */
     getPerpMarketExtendedInfo(marketIndex: number): PerpMarketExtendedInfo;
     /**
      * Calculates taker / maker fee (as a percentage, e.g. .001 = 10 basis points) for particular marketType
      * @param marketType
      * @param positionMarketIndex
+     * @param user
+     * @param orderParams When it carries a builder code, the builder fee (quoteAssetAmount * builderFeeTenthBps / 100_000) is added to takerFee.
      * @returns : {takerFee: number, makerFee: number} Precision None
      */
-    getMarketFees(marketType: MarketType, marketIndex?: number, user?: User): {
+    getMarketFees(marketType: MarketType, marketIndex?: number, user?: User, orderParams?: Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>): {
         takerFee: number;
         makerFee: number;
     };
@@ -1178,31 +3814,282 @@ export declare class VelocityClient {
         marketIndex: number;
         marketType: MarketType;
     } | undefined;
+    /**
+     * Posts a signed Pyth Lazer price update on-chain for one or more feeds, prepended with the
+     * Ed25519 signature-verification instruction the handler requires. Permissionless — any signer
+     * can post a valid, correctly-signed update.
+     * @param feedIds - Pyth Lazer feed IDs to update, in the same order as the encoded message.
+     * @param pythMessageHex - Hex-encoded, Pyth-signed Lazer update message.
+     * @returns The transaction signature.
+     */
     postPythLazerOracleUpdate(feedIds: number[], pythMessageHex: string): Promise<string>;
+    /**
+     * Builds the `postPythLazerOracleUpdate` instruction pair. See `postPythLazerOracleUpdate` for
+     * semantics.
+     * @param feedIds - Pyth Lazer feed IDs to update, in the same order as the encoded message.
+     * @param pythMessageHex - Hex-encoded, Pyth-signed Lazer update message.
+     * @param precedingIxs - Instructions that will be placed before the returned pair in the final
+     * transaction; only their count is used, to compute the Ed25519 verify instruction's index.
+     * @param overrideCustomIxIndex - Explicit index of the verify instruction within the transaction,
+     * overriding the `precedingIxs.length + 1` default.
+     * @returns `[verifyIx, updateIx]` — the Ed25519 signature-verification instruction followed by the
+     * oracle-update instruction; both must be included, in order, in the same transaction.
+     */
     getPostPythLazerOracleUpdateIxs(feedIds: number[], pythMessageHex: string, precedingIxs?: TransactionInstruction[], overrideCustomIxIndex?: number): Promise<TransactionInstruction[]>;
+    /**
+     * Builds the `pauseSpotMarketDepositWithdraw` instruction. See `pauseSpotMarketDepositWithdraw`
+     * for semantics.
+     * @param spotMarketIndex - Spot market index to pause.
+     * @returns The instruction.
+     */
     getPauseSpotMarketDepositWithdrawIx(spotMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Emergency circuit-breaker instruction: pauses deposits and withdrawals for a spot market, but
+     * only when the on-chain handler detects the spot market's vault invariant has already been
+     * violated (actual vault balance diverges from the market's tracked deposit/borrow balances,
+     * e.g. from an exploit) — it reverts with an error if the vault amount is still valid, so this
+     * cannot be used to arbitrarily pause a healthy market. Permissionless — any signer can trigger
+     * it once the invariant is broken.
+     * @param spotMarketIndex - Spot market index to pause.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @throws (on-chain) if the spot market's vault amount is still valid (invariant not violated).
+     * @returns The transaction signature.
+     */
     pauseSpotMarketDepositWithdraw(spotMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Updates a perp market's market-maker (MM) oracle price using the program's high-frequency
+     * custom native entrypoint (bypasses Anchor's account deserialization overhead — see
+     * `createNativeInstructionDiscriminatorBuffer`). Restricted to the state's configured
+     * `hotMmOracleCrank` signer in production (unchecked under the `anchor-test` feature) and can be
+     * disabled entirely via a state feature-bit-flag kill switch. See `getMMOracleDataForPerpMarket`
+     * for how this price is subsequently gated against the primary oracle before use.
+     * @param marketIndex - Perp market index whose MM oracle to update.
+     * @param oraclePrice - New MM oracle price, PRICE_PRECISION (1e6). A value of `0` is a no-op.
+     * @param oracleSequenceId - Monotonically increasing sequence id for this update, used for
+     * recency comparisons against the primary oracle.
+     * @returns The transaction signature.
+     */
     updateMmOracleNative(marketIndex: number, oraclePrice: BN, oracleSequenceId: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateMmOracleNative` instruction. See `updateMmOracleNative` for semantics. Hand-
+     * assembles the instruction (perp market, signer, clock sysvar, state) rather than going through
+     * `this.program.instruction`, since this targets the native (non-Anchor) entrypoint.
+     * @param marketIndex - Perp market index whose MM oracle to update.
+     * @param oraclePrice - New MM oracle price, PRICE_PRECISION (1e6). A value of `0` is a no-op.
+     * @param oracleSequenceId - Monotonically increasing sequence id for this update.
+     * @returns The instruction.
+     */
     getUpdateMmOracleNativeIx(marketIndex: number, oraclePrice: BN, oracleSequenceId: BN): Promise<TransactionInstruction>;
+    /**
+     * Updates a perp market's AMM spread adjustment using the program's high-frequency custom native
+     * entrypoint. Restricted to the state's configured `hotAmmSpreadAdjust` signer in production
+     * (unchecked under the `anchor-test` feature).
+     * @param marketIndex - Perp market index whose AMM spread adjustment to update.
+     * @param ammSpreadAdjustment - Percentage adjustment to the AMM's base long/short spread, as a
+     * signed byte (-128 to 127): negative narrows the spread by that percent, positive widens it,
+     * `0` is no adjustment.
+     * @returns The transaction signature.
+     */
     updateAmmSpreadAdjustmentNative(marketIndex: number, ammSpreadAdjustment: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateAmmSpreadAdjustmentNative` instruction. See `updateAmmSpreadAdjustmentNative`
+     * for semantics. Hand-assembles the instruction (perp market, signer, state) rather than going
+     * through `this.program.instruction`, since this targets the native (non-Anchor) entrypoint.
+     * @param marketIndex - Perp market index whose AMM spread adjustment to update.
+     * @param ammSpreadAdjustment - Percentage adjustment to the AMM's base spread, signed byte (i8).
+     * @returns The instruction.
+     */
     getUpdateAmmSpreadAdjustmentNativeIx(marketIndex: number, ammSpreadAdjustment: number): Promise<TransactionInstruction>;
+    /**
+     * Fetches an LP pool account by ID directly from the RPC (not from this client's subscription
+     * cache). An LP pool ("VLP") is a basket of spot-market "constituent" tokens that mints/redeems a
+     * pool token against deposits/withdrawals and absorbs perp AMM PnL to hedge the protocol's
+     * inventory risk (see `settlePerpToLpPool`).
+     * @param lpPoolId - LP pool ID.
+     * @returns The decoded LP pool account.
+     */
     getLpPoolAccount(lpPoolId: number): Promise<LPPoolAccount>;
+    /**
+     * Fetches the target-base weights for an LP pool's constituents directly from the RPC. Target
+     * base is each constituent's ideal share of the pool, derived from the AMMs it backs
+     * (`updateLpConstituentTargetBase`); swap/add/remove-liquidity fees are priced off deviation from
+     * these targets.
+     * @param lpPoolId - LP pool ID.
+     * @returns The decoded constituent target-base account.
+     */
     getConstituentTargetBaseAccount(lpPoolId: number): Promise<ConstituentTargetBaseAccount>;
+    /**
+     * Fetches the program's single global AMM cache account directly from the RPC — a snapshot of
+     * each hedge-enabled perp market's inventory/price/PnL used by LP pool AUM, target-base, and
+     * settlement instructions without having to reload every perp market individually.
+     * @returns The decoded AMM cache account.
+     */
     getAmmCache(): Promise<AmmCache>;
+    /**
+     * Keeper instruction: recomputes each listed constituent's target-base weight from the current
+     * AMM cache (each hedge-enabled perp market's inventory relative to its constituents), used to
+     * price LP pool swap/add/remove-liquidity fees. Requires `updateAmmCache` to have run recently
+     * for the relevant markets. Permissionless — any signer can act as keeper.
+     * @param lpPoolId - LP pool ID.
+     * @param constituents - Constituent account public keys to recompute target base for.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updateLpConstituentTargetBase(lpPoolId: number, constituents: PublicKey[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateLpConstituentTargetBase` instruction. See `updateLpConstituentTargetBase` for
+     * semantics.
+     * @param lpPoolId - LP pool ID.
+     * @param constituents - Constituent account public keys to recompute target base for, passed as
+     * read-only remaining accounts.
+     * @returns The instruction.
+     */
     getUpdateLpConstituentTargetBaseIx(lpPoolId: number, constituents: PublicKey[]): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: recomputes an LP pool's total AUM and per-constituent value from each
+     * constituent's spot market and vault balance, refreshing `lastAumSlot`. Swaps and add/remove
+     * liquidity revert with `LpPoolAumDelayed` if this has not run within `LP_POOL_SWAP_AUM_UPDATE_DELAY`
+     * slots of the action, so it must typically precede those instructions in the same transaction
+     * (see `getAllUpdateLpPoolAumIxs`). Permissionless — any signer can act as keeper.
+     * @param lpPool - Decoded LP pool account to update.
+     * @param spotMarketIndexOfConstituents - Spot market index of every constituent in the pool, in
+     * the same order the pool's constituents were configured.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     updateLpPoolAum(lpPool: LPPoolAccount, spotMarketIndexOfConstituents: number[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateLpPoolAum` instruction. See `updateLpPoolAum` for semantics.
+     * @param lpPool - Decoded LP pool account to update.
+     * @param spotMarketIndexOfConstituents - Spot market index of every constituent in the pool.
+     * @returns The instruction.
+     */
     getUpdateLpPoolAumIxs(lpPool: LPPoolAccount, spotMarketIndexOfConstituents: number[]): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: refreshes the global AMM cache's per-market inventory/price/PnL snapshot
+     * for the given hedge-enabled perp markets, feeding LP pool AUM, target-base, and settlement
+     * math. Permissionless — any signer can act as keeper.
+     * @param perpMarketIndexes - Perp market indexes to refresh; at most 50 per call.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @throws If more than 50 market indexes are supplied.
+     * @returns The transaction signature.
+     */
     updateAmmCache(perpMarketIndexes: number[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateAmmCache` instruction. See `updateAmmCache` for semantics.
+     * @param perpMarketIndexes - Perp market indexes to refresh; at most 50.
+     * @throws If more than 50 market indexes are supplied.
+     * @returns The instruction.
+     */
     getUpdateAmmCacheIx(perpMarketIndexes: number[]): Promise<TransactionInstruction>;
+    /**
+     * Keeper instruction: refreshes a single LP pool constituent's cached oracle price/slot from its
+     * spot market's oracle. Called ahead of AUM/target-base updates that need a fresh price for that
+     * constituent. Permissionless — any signer can act as keeper.
+     * @param constituent - Decoded constituent account to refresh.
+     * @returns The transaction signature.
+     */
     updateConstituentOracleInfo(constituent: ConstituentAccount): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateConstituentOracleInfo` instruction. See `updateConstituentOracleInfo` for
+     * semantics.
+     * @param constituent - Decoded constituent account to refresh.
+     * @returns The instruction.
+     */
     getUpdateConstituentOracleInfoIx(constituent: ConstituentAccount): Promise<TransactionInstruction>;
+    /**
+     * Swaps `inMarketIndex` tokens for `outMarketIndex` tokens directly against an LP pool's
+     * constituent vaults (not the DLOB/AMM), paying a fee priced off each constituent's deviation
+     * from its target-base weight. Reverts if pool swaps are disabled, `inMarketIndex` equals
+     * `outMarketIndex`, or `updateLpPoolAum` has not run within `LP_POOL_SWAP_AUM_UPDATE_DELAY` slots
+     * (see `getAllLpPoolSwapIxs` for a wrapper that prepends the required AUM refresh).
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inAmount - Amount of `inMarketIndex` token to sell, in that market's mint precision.
+     * @param minOutAmount - Minimum acceptable amount of `outMarketIndex` token to receive, in that
+     * market's mint precision.
+     * @param lpPool - LP pool public key.
+     * @param userAuthority - Authority whose associated token accounts fund/receive the swap.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     lpPoolSwap(inMarketIndex: number, outMarketIndex: number, inAmount: BN, minOutAmount: BN, lpPool: PublicKey, userAuthority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `lpPoolSwap` instruction. See `lpPoolSwap` for semantics.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inAmount - Amount of `inMarketIndex` token to sell, in that market's mint precision.
+     * @param minOutAmount - Minimum acceptable amount of `outMarketIndex` token to receive, in that
+     * market's mint precision.
+     * @param lpPool - LP pool public key.
+     * @param userAuthority - Authority whose associated token accounts fund/receive the swap.
+     * @returns The instruction.
+     */
     getLpPoolSwapIx(inMarketIndex: number, outMarketIndex: number, inAmount: BN, minOutAmount: BN, lpPool: PublicKey, userAuthority: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Simulation-only instruction: computes what `lpPoolSwap` would charge for the given swap without
+     * moving any funds (intended to be run via `simulateTransaction`/a view call, not actually
+     * confirmed on-chain). Useful for quoting a swap's fee before submitting it.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inAmount - Amount of `inMarketIndex` token to sell, in that market's mint precision.
+     * @param inTargetWeight - Assumed target-base weight for the in-constituent (PERCENTAGE_PRECISION, 1e6).
+     * @param outTargetWeight - Assumed target-base weight for the out-constituent (PERCENTAGE_PRECISION, 1e6).
+     * @param lpPool - LP pool public key.
+     * @param constituentTargetBase - The pool's constituent target-base account.
+     * @param constituentInTokenAccount - In-constituent's vault token account.
+     * @param constituentOutTokenAccount - Out-constituent's vault token account.
+     * @param inConstituent - In-constituent account.
+     * @param outConstituent - Out-constituent account.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature (intended for simulation, not confirmation).
+     */
     viewLpPoolSwapFees(inMarketIndex: number, outMarketIndex: number, inAmount: BN, inTargetWeight: BN, outTargetWeight: BN, lpPool: PublicKey, constituentTargetBase: PublicKey, constituentInTokenAccount: PublicKey, constituentOutTokenAccount: PublicKey, inConstituent: PublicKey, outConstituent: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `viewLpPoolSwapFees` instruction. See `viewLpPoolSwapFees` for semantics.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inAmount - Amount of `inMarketIndex` token to sell, in that market's mint precision.
+     * @param inTargetWeight - Assumed target-base weight for the in-constituent (PERCENTAGE_PRECISION, 1e6).
+     * @param outTargetWeight - Assumed target-base weight for the out-constituent (PERCENTAGE_PRECISION, 1e6).
+     * @param lpPool - LP pool public key.
+     * @param constituentTargetBase - The pool's constituent target-base account.
+     * @param constituentInTokenAccount - In-constituent's vault token account.
+     * @param constituentOutTokenAccount - Out-constituent's vault token account.
+     * @param inConstituent - In-constituent account.
+     * @param outConstituent - Out-constituent account.
+     * @returns The instruction.
+     */
     getViewLpPoolSwapFeesIx(inMarketIndex: number, outMarketIndex: number, inAmount: BN, inTargetWeight: BN, outTargetWeight: BN, lpPool: PublicKey, constituentTargetBase: PublicKey, constituentInTokenAccount: PublicKey, constituentOutTokenAccount: PublicKey, inConstituent: PublicKey, outConstituent: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Builds an idempotent instruction creating this wallet's associated token account for an LP
+     * pool's mint, needed before receiving pool tokens from `lpPoolAddLiquidity`.
+     * @param lpPool - Decoded LP pool account whose mint to create an account for.
+     * @returns The instruction.
+     */
     getCreateLpPoolTokenAccountIx(lpPool: LPPoolAccount): Promise<TransactionInstruction>;
+    /**
+     * Creates this wallet's associated token account for an LP pool's mint. See
+     * `getCreateLpPoolTokenAccountIx`.
+     * @param lpPool - Decoded LP pool account whose mint to create an account for.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     createLpPoolTokenAccount(lpPool: LPPoolAccount, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Deposits `inMarketIndex` tokens into an LP pool's matching constituent and mints LP pool tokens
+     * in return, priced at the pool's current AUM-derived share price. Reverts if mint/redeem is
+     * disabled, the constituent doesn't allow deposits (or is reduce-only and this isn't a
+     * reducing deposit), the pool is gated by a whitelist mint this wallet doesn't hold, or
+     * `updateLpPoolAum` has not run within `LP_POOL_SWAP_AUM_UPDATE_DELAY` slots (see
+     * `getAllLpPoolAddLiquidityIxs` for a wrapper that prepends the required AUM refresh).
+     * @param inMarketIndex - Spot market index of the token being deposited.
+     * @param inAmount - Amount to deposit, in `inMarketIndex`'s mint precision.
+     * @param minMintAmount - Minimum acceptable LP pool tokens to receive, in the pool mint's precision.
+     * @param lpPool - Decoded LP pool account to deposit into.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     lpPoolAddLiquidity({ inMarketIndex, inAmount, minMintAmount, lpPool, txParams, }: {
         inMarketIndex: number;
         inAmount: BN;
@@ -1210,23 +4097,62 @@ export declare class VelocityClient {
         lpPool: LPPoolAccount;
         txParams?: TxParams;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `lpPoolAddLiquidity` instruction (plus any needed wrapped-SOL / associated-token-
+     * account setup and teardown instructions). See `lpPoolAddLiquidity` for semantics.
+     * @param inMarketIndex - Spot market index of the token being deposited.
+     * @param inAmount - Amount to deposit, in `inMarketIndex`'s mint precision.
+     * @param minMintAmount - Minimum acceptable LP pool tokens to receive, in the pool mint's precision.
+     * @param lpPool - Decoded LP pool account to deposit into.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getLpPoolAddLiquidityIx({ inMarketIndex, inAmount, minMintAmount, lpPool, }: {
         inMarketIndex: number;
         inAmount: BN;
         minMintAmount: BN;
         lpPool: LPPoolAccount;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Simulation-only instruction: computes what `lpPoolAddLiquidity` would mint/charge for the given
+     * deposit without moving any funds (intended for `simulateTransaction`, not confirmation).
+     * @param inMarketIndex - Spot market index of the token being deposited.
+     * @param inAmount - Amount to deposit, in `inMarketIndex`'s mint precision.
+     * @param lpPool - Decoded LP pool account to deposit into.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature (intended for simulation, not confirmation).
+     */
     viewLpPoolAddLiquidityFees({ inMarketIndex, inAmount, lpPool, txParams, }: {
         inMarketIndex: number;
         inAmount: BN;
         lpPool: LPPoolAccount;
         txParams?: TxParams;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `viewLpPoolAddLiquidityFees` instruction. See `viewLpPoolAddLiquidityFees` for semantics.
+     * @param inMarketIndex - Spot market index of the token being deposited.
+     * @param inAmount - Amount to deposit, in `inMarketIndex`'s mint precision.
+     * @param lpPool - Decoded LP pool account to deposit into.
+     * @returns The instruction.
+     */
     getViewLpPoolAddLiquidityFeesIx({ inMarketIndex, inAmount, lpPool, }: {
         inMarketIndex: number;
         inAmount: BN;
         lpPool: LPPoolAccount;
     }): Promise<TransactionInstruction>;
+    /**
+     * Burns LP pool tokens and withdraws `outMarketIndex` tokens from the pool's matching constituent
+     * in return, priced at the pool's current AUM-derived share price. Reverts if mint/redeem is
+     * disabled, the constituent doesn't allow withdrawals, or `updateLpPoolAum` has not run within
+     * `LP_POOL_SWAP_AUM_UPDATE_DELAY` slots (see `getAllLpPoolRemoveLiquidityIxs` for a wrapper that
+     * prepends the required perp settlement and AUM refresh).
+     * @param outMarketIndex - Spot market index of the token being withdrawn.
+     * @param lpToBurn - Amount of LP pool tokens to burn, in the pool mint's precision.
+     * @param minAmountOut - Minimum acceptable `outMarketIndex` tokens to receive, in that market's
+     * mint precision.
+     * @param lpPool - Decoded LP pool account to withdraw from.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature.
+     */
     lpPoolRemoveLiquidity({ outMarketIndex, lpToBurn, minAmountOut, lpPool, txParams, }: {
         outMarketIndex: number;
         lpToBurn: BN;
@@ -1234,40 +4160,158 @@ export declare class VelocityClient {
         lpPool: LPPoolAccount;
         txParams?: TxParams;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `lpPoolRemoveLiquidity` instruction (plus an idempotent associated-token-account
+     * creation instruction for a wrapped-SOL output, if needed). See `lpPoolRemoveLiquidity` for
+     * semantics.
+     * @param outMarketIndex - Spot market index of the token being withdrawn.
+     * @param lpToBurn - Amount of LP pool tokens to burn, in the pool mint's precision.
+     * @param minAmountOut - Minimum acceptable `outMarketIndex` tokens to receive, in that market's
+     * mint precision.
+     * @param lpPool - Decoded LP pool account to withdraw from.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getLpPoolRemoveLiquidityIx({ outMarketIndex, lpToBurn, minAmountOut, lpPool, }: {
         outMarketIndex: number;
         lpToBurn: BN;
         minAmountOut: BN;
         lpPool: LPPoolAccount;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Simulation-only instruction: computes what `lpPoolRemoveLiquidity` would return for the given
+     * burn without moving any funds (intended for `simulateTransaction`, not confirmation).
+     * @param outMarketIndex - Spot market index of the token being withdrawn.
+     * @param lpToBurn - Amount of LP pool tokens to burn, in the pool mint's precision.
+     * @param lpPool - Decoded LP pool account to withdraw from.
+     * @param txParams - Optional compute-unit/priority-fee overrides.
+     * @returns The transaction signature (intended for simulation, not confirmation).
+     */
     viewLpPoolRemoveLiquidityFees({ outMarketIndex, lpToBurn, lpPool, txParams, }: {
         outMarketIndex: number;
         lpToBurn: BN;
         lpPool: LPPoolAccount;
         txParams?: TxParams;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `viewLpPoolRemoveLiquidityFees` instruction. See `viewLpPoolRemoveLiquidityFees` for
+     * semantics.
+     * @param outMarketIndex - Spot market index of the token being withdrawn.
+     * @param lpToBurn - Amount of LP pool tokens to burn, in the pool mint's precision.
+     * @param lpPool - Decoded LP pool account to withdraw from.
+     * @returns The instruction.
+     */
     getViewLpPoolRemoveLiquidityFeesIx({ outMarketIndex, lpToBurn, lpPool, }: {
         outMarketIndex: number;
         lpToBurn: BN;
         lpPool: LPPoolAccount;
     }): Promise<TransactionInstruction>;
+    /**
+     * Convenience wrapper that prepends the AUM refresh `lpPoolAddLiquidity` requires (an
+     * `updateConstituentOracleInfo` per constituent, then `updateLpPoolAum`) ahead of either the real
+     * add-liquidity instruction or, when `view` is set, its fee-simulation counterpart.
+     * @param inMarketIndex - Spot market index of the token being deposited.
+     * @param inAmount - Amount to deposit, in `inMarketIndex`'s mint precision.
+     * @param minMintAmount - Minimum acceptable LP pool tokens to receive, in the pool mint's precision.
+     * @param lpPool - Decoded LP pool account to deposit into.
+     * @param constituentMap - All of the pool's constituents, used to refresh oracle info and AUM.
+     * @param includeUpdateConstituentOracleInfo - Whether to prepend an oracle-info refresh per
+     * constituent; defaults to `true`.
+     * @param view - When `true`, appends `getViewLpPoolAddLiquidityFeesIx` instead of the real deposit;
+     * defaults to `false`.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllLpPoolAddLiquidityIxs({ inMarketIndex, inAmount, minMintAmount, lpPool, }: {
         inMarketIndex: number;
         inAmount: BN;
         minMintAmount: BN;
         lpPool: LPPoolAccount;
     }, constituentMap: ConstituentMap, includeUpdateConstituentOracleInfo?: boolean, view?: boolean): Promise<TransactionInstruction[]>;
+    /**
+     * Convenience wrapper that prepends what `lpPoolRemoveLiquidity` requires: settling every hedge-
+     * enabled perp market's PnL into the pool (`getAllSettlePerpToLpPoolIxs`) and refreshing AUM
+     * (`getAllUpdateLpPoolAumIxs`), ahead of either the real remove-liquidity instruction or, when
+     * `view` is set, its fee-simulation counterpart.
+     * @param outMarketIndex - Spot market index of the token being withdrawn.
+     * @param lpToBurn - Amount of LP pool tokens to burn, in the pool mint's precision.
+     * @param minAmountOut - Minimum acceptable `outMarketIndex` tokens to receive, in that market's
+     * mint precision.
+     * @param lpPool - Decoded LP pool account to withdraw from.
+     * @param constituentMap - All of the pool's constituents, used to refresh oracle info and AUM.
+     * @param includeUpdateConstituentOracleInfo - Whether to prepend an oracle-info refresh per
+     * constituent; defaults to `true`.
+     * @param view - When `true`, appends `getViewLpPoolRemoveLiquidityFeesIx` instead of the real
+     * withdrawal; defaults to `false`.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllLpPoolRemoveLiquidityIxs({ outMarketIndex, lpToBurn, minAmountOut, lpPool, }: {
         outMarketIndex: number;
         lpToBurn: BN;
         minAmountOut: BN;
         lpPool: LPPoolAccount;
     }, constituentMap: ConstituentMap, includeUpdateConstituentOracleInfo?: boolean, view?: boolean): Promise<TransactionInstruction[]>;
+    /**
+     * Builds the full instruction set to refresh an LP pool's AUM: one `updateConstituentOracleInfo`
+     * per constituent (optional) followed by `updateLpPoolAum` across all of them.
+     * @param lpPool - Decoded LP pool account to update.
+     * @param constituentMap - All of the pool's constituents.
+     * @param includeUpdateConstituentOracleInfo - Whether to prepend an oracle-info refresh per
+     * constituent; defaults to `true`. Pass `false` when a caller has already refreshed oracle info
+     * earlier in the same transaction.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllUpdateLpPoolAumIxs(lpPool: LPPoolAccount, constituentMap: ConstituentMap, includeUpdateConstituentOracleInfo?: boolean): Promise<TransactionInstruction[]>;
+    /**
+     * Builds the full instruction set to refresh an LP pool's constituent target-base weights:
+     * `updateAmmCache` for the given markets, an optional `updateConstituentOracleInfo` per
+     * constituent, `updateLpConstituentTargetBase`, then a full AUM refresh
+     * (`getAllUpdateLpPoolAumIxs`, oracle info not repeated).
+     * @param perpMarketIndexes - Hedge-enabled perp market indexes to refresh in the AMM cache.
+     * @param lpPool - Decoded LP pool account to update.
+     * @param constituentMap - All of the pool's constituents.
+     * @param includeUpdateConstituentOracleInfo - Whether to include an oracle-info refresh per
+     * constituent; defaults to `true`.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllUpdateConstituentTargetBaseIxs(perpMarketIndexes: number[], lpPool: LPPoolAccount, constituentMap: ConstituentMap, includeUpdateConstituentOracleInfo?: boolean): Promise<TransactionInstruction[]>;
+    /**
+     * Convenience wrapper that prepends the AUM refresh `lpPoolSwap` requires ahead of the swap
+     * instruction itself.
+     * @param lpPool - Decoded LP pool account to swap against.
+     * @param constituentMap - All of the pool's constituents, used to refresh AUM.
+     * @param inMarketIndex - Spot market index of the token being sold.
+     * @param outMarketIndex - Spot market index of the token being bought.
+     * @param inAmount - Amount of `inMarketIndex` token to sell, in that market's mint precision.
+     * @param minOutAmount - Minimum acceptable amount of `outMarketIndex` token to receive, in that
+     * market's mint precision.
+     * @param userAuthority - Authority whose associated token accounts fund/receive the swap.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllLpPoolSwapIxs(lpPool: LPPoolAccount, constituentMap: ConstituentMap, inMarketIndex: number, outMarketIndex: number, inAmount: BN, minOutAmount: BN, userAuthority: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Keeper instruction: settles quote PnL owed between one or more hedge-enabled perp markets' fee
+     * and PnL pools and the LP pool's quote constituent, bounded by the pool's settle cap. Requires
+     * `updateAmmCache` to have run recently for the given markets. Permissionless — any signer can
+     * act as keeper.
+     * @param lpPoolId - LP pool ID.
+     * @param perpMarketIndexes - Hedge-enabled perp market indexes to settle.
+     * @returns The transaction signature.
+     */
     settlePerpToLpPool(lpPoolId: number, perpMarketIndexes: number[]): Promise<TransactionSignature>;
+    /**
+     * Builds the `settlePerpToLpPool` instruction. See `settlePerpToLpPool` for semantics.
+     * @param lpPoolId - LP pool ID.
+     * @param perpMarketIndexes - Hedge-enabled perp market indexes to settle, passed as writable
+     * remaining accounts.
+     * @returns The instruction.
+     */
     getSettlePerpToLpPoolIx(lpPoolId: number, perpMarketIndexes: number[]): Promise<TransactionInstruction>;
+    /**
+     * Builds the full instruction set to settle perp PnL into an LP pool: `updateAmmCache` for the
+     * given markets followed by `settlePerpToLpPool`.
+     * @param lpPoolId - LP pool ID.
+     * @param marketIndexes - Hedge-enabled perp market indexes to settle.
+     * @returns The ordered instructions to include in the transaction.
+     */
     getAllSettlePerpToLpPoolIxs(lpPoolId: number, marketIndexes: number[]): Promise<TransactionInstruction[]>;
     /**
      * Below here are the transaction sending functions
@@ -1276,18 +4320,68 @@ export declare class VelocityClient {
     private handlePreSignedTransaction;
     private isVersionedTransaction;
     /**
-     * Send a transaction.
-     *
-     * @param tx
-     * @param additionalSigners
-     * @param opts :: Will fallback to VelocityClient's opts if not provided
-     * @param preSigned
-     * @returns
+     * Signs (unless `preSigned`) and sends a transaction via this client's `txSender`, dispatching to
+     * `sendVersionedTransaction` or `send` based on whether `tx` is a `VersionedTransaction`. The
+     * shared low-level send path underlying nearly every instruction-building method on this class.
+     * @param tx - Transaction to send; legacy `Transaction` or `VersionedTransaction`.
+     * @param additionalSigners - Extra signers beyond this client's wallet (e.g. newly-created accounts).
+     * @param opts - Confirmation options; falls back to `this.opts` if not provided.
+     * @param preSigned - If `true`, `tx` is assumed already fully signed and is submitted as-is.
+     * @returns The transaction signature and the slot it was confirmed at.
      */
     sendTransaction(tx: Transaction | VersionedTransaction, additionalSigners?: Array<Signer>, opts?: ConfirmOptions, preSigned?: boolean): Promise<TxSigAndSlot>;
+    /**
+     * Assembles one or more instructions into a single unsigned transaction via `this.txHandler`,
+     * applying compute-unit/priority-fee instructions from `txParams`, resolving address lookup
+     * tables for versioned transactions, and fetching a recent blockhash if not supplied. Used by
+     * nearly every instruction-building method on this class before sending.
+     * @param instructions - Instruction(s) to include.
+     * @param txParams - Optional compute-unit/priority-fee overrides; defaults to `this.txParams`.
+     * @param txVersion - Legacy (`0`) vs versioned transaction; defaults to `this.txVersion`.
+     * @param lookupTables - Additional address lookup tables to use, beyond the client's configured
+     * market lookup tables.
+     * @param forceVersionedTransaction - Force a `VersionedTransaction` even if `txVersion` implies legacy.
+     * @param recentBlockhash - Pre-fetched blockhash to reuse instead of requesting a new one.
+     * @param optionalIxs - Instructions to append opportunistically if space/compute budget allows
+     * (dropped rather than causing failure if they don't fit).
+     * @returns The assembled (unsigned) transaction.
+     */
     buildTransaction(instructions: TransactionInstruction | TransactionInstruction[], txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean, recentBlockhash?: BlockhashWithExpiryBlockHeight, optionalIxs?: TransactionInstruction[]): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Builds many independent transactions in one call — each entry in `instructions` becomes its own
+     * transaction via the same path as `buildTransaction`. An entry may build to `undefined` if the
+     * underlying `txHandler` implementation skips it (e.g. empty instruction list).
+     * @param instructions - One instruction-list per transaction to build.
+     * @param txParams - Optional compute-unit/priority-fee overrides applied to every transaction.
+     * @param txVersion - Legacy (`0`) vs versioned transaction; defaults to `this.txVersion`.
+     * @param lookupTables - Additional address lookup tables to use for every transaction.
+     * @param forceVersionedTransaction - Force `VersionedTransaction`s even if `txVersion` implies legacy.
+     * @returns The assembled (unsigned) transactions, in the same order as `instructions`.
+     */
     buildBulkTransactions(instructions: (TransactionInstruction | TransactionInstruction[])[], txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<(Transaction | VersionedTransaction | undefined)[]>;
+    /**
+     * Like `buildBulkTransactions`, but keyed by caller-chosen labels instead of array position — each
+     * value in `instructionsMap` becomes its own transaction, returned under the same key.
+     * @param instructionsMap - Instruction-list(s) to build, keyed by an arbitrary caller-defined label.
+     * @param txParams - Optional compute-unit/priority-fee overrides applied to every transaction.
+     * @param txVersion - Legacy (`0`) vs versioned transaction; defaults to `this.txVersion`.
+     * @param lookupTables - Additional address lookup tables to use for every transaction.
+     * @param forceVersionedTransaction - Force `VersionedTransaction`s even if `txVersion` implies legacy.
+     * @returns A map from each input key to its assembled (unsigned) transaction.
+     */
     buildTransactionsMap(instructionsMap: Record<string, TransactionInstruction | TransactionInstruction[]>, txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<MappedRecord<Record<string, TransactionInstruction | TransactionInstruction[]>, Transaction | VersionedTransaction>>;
+    /**
+     * Like `buildTransactionsMap`, but additionally signs every built transaction with this client's
+     * wallet before returning — useful for batching several independent, pre-signed transactions
+     * (e.g. to submit separately or hand off to `sendSignedTx`).
+     * @param instructionsMap - Instruction-list(s) to build and sign, keyed by an arbitrary
+     * caller-defined label.
+     * @param txParams - Optional compute-unit/priority-fee overrides applied to every transaction.
+     * @param txVersion - Legacy (`0`) vs versioned transaction; defaults to `this.txVersion`.
+     * @param lookupTables - Additional address lookup tables to use for every transaction.
+     * @param forceVersionedTransaction - Force `VersionedTransaction`s even if `txVersion` implies legacy.
+     * @returns A map from each input key to its signed transaction.
+     */
     buildAndSignTransactionsMap(instructionsMap: Record<string, TransactionInstruction | TransactionInstruction[]>, txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<{
         signedTxMap: Record<string, Transaction>;
         signedTxData: SignedTxData[];
@@ -1295,6 +4389,19 @@ export declare class VelocityClient {
         signedTxMap: MappedRecord<Record<string, TransactionInstruction | TransactionInstruction[]>, Transaction | VersionedTransaction>;
         signedTxData: SignedTxData[];
     }>;
+    /**
+     * Determines whether placing `orderParams` would increase the magnitude of the sub-account's
+     * existing perp position in that market (same-direction add, or opening a new position) as
+     * opposed to reducing/flattening/flipping it. Used by `placePerpOrder`/`placeOrders`/
+     * `preparePlaceOrdersTx` to decide whether an `isolatedPositionDepositAmount` transfer should be
+     * prepended — that transfer only makes sense when the order grows the position.
+     * @param orderParams - Order to evaluate; `baseAssetAmount` is BASE_PRECISION (1e9).
+     * @param subAccountId - Sub-account whose existing position to compare against; defaults to the
+     * active sub-account.
+     * @returns `true` if there is no existing position in the market, the existing position is flat
+     * (zero), or the order's signed base amount increases the position's absolute size; `false` if it
+     * reduces, flattens, or flips it.
+     */
     isOrderIncreasingPosition(orderParams: OptionalOrderParams, subAccountId?: number): boolean;
 }
 export {};