@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/adminClient.d.ts

@@ -1,10 +1,17 @@
 /**
  * AdminClient — governance and protocol administration instruction builders.
- * Extends {@link VelocityClient}; all trading/keeper methods are also available.
+ * Extends `VelocityClient`; all trading/keeper methods are also available.
  *
  * Covers: perp/spot market initialization and updates, oracle guard rail config,
  * fee structure updates, insurance fund operations, vault management, IF rebalancing,
- * pause/unpause exchange, and all ~126 admin instruction handlers in `instructions/admin.rs`.
+ * pause/unpause exchange, and all admin instruction handlers in `instructions/admin.rs`.
+ *
+ * Most methods require a specific admin tier, enforced on-chain by `state.cold_admin` /
+ * `state.warm_admin` / per-role `state.hot_*` keys (see `programs/velocity/src/auth.rs`).
+ * Tiers are additive — cold ⊇ warm ⊇ hot(role) — so the cold admin can always call a
+ * warm- or hot-gated instruction. Each method's doc below states the minimum tier
+ * required by the on-chain constraint; passing a lower-tier wallet fails the transaction
+ * with `Unauthorized`, not client-side.
  */
 import { AddressLookupTableAccount, Keypair, PublicKey, TransactionInstruction, TransactionSignature } from '@solana/web3.js';
 import { FeeStructure, OracleGuardRails, OracleSource, ExchangeStatus, SolvencyStatus, MarketStatus, ContractTier, AssetTier, TxParams, AddAmmConstituentMappingDatum, SwapReduceOnly, InitializeConstituentParams, ConstituentStatus, LPPoolAccount, TransferFeeAndPnlPoolDirection, MarketType } from './types';
@@ -13,25 +20,206 @@ import { VelocityClient } from './velocityClient';
 import { JupiterClient, QuoteResponse } from './jupiter/jupiterClient';
 import { SwapMode } from './swap/UnifiedSwapClient';
 export declare class AdminClient extends VelocityClient {
+    /**
+     * Creates the protocol's singleton `State` account (one-time setup). Fails client-side
+     * if `State` already exists. On a real mainnet build the on-chain `Initialize` accounts
+     * struct additionally locks the signer to `ids::state_init_authority` so the one-time
+     * init cannot be front-run; on devnet/localnet or the `anchor-test` build any signer may
+     * call it. Seeds `cold_admin` and `warm_admin` to the calling wallet and `pause_admin` to
+     * the default (unassigned) pubkey — rotate them afterward via `updateAdmin` /
+     * `updateWarmAdmin` / `updatePauseAdmin`.
+     * @param usdcMint - Mint of the protocol's quote asset (must have 6 decimals; becomes
+     *   `state.quoteAssetMint`).
+     * @param _adminControlsPrices - Unused; retained for call-site compatibility.
+     * @returns Tuple containing the transaction signature.
+     */
     initialize(usdcMint: PublicKey, _adminControlsPrices: boolean): Promise<[TransactionSignature]>;
+    /**
+     * Initializes a new spot market: creates the `SpotMarket` PDA plus its token vault and
+     * insurance-fund vault, and appends it at `state.numberOfSpotMarkets` (or `marketIndex`
+     * if explicitly supplied — the on-chain handler asserts it matches the next sequential
+     * index). Requires warm admin (`check_warm`); if `activeStatus` is `true` the on-chain
+     * handler additionally requires the **cold** admin specifically (a market cannot be
+     * launched active by a warm-only signer). For `oracleSource: QuoteAsset` (used only for
+     * the index-0 quote market), `oracle` must be `PublicKey.default`.
+     * @param mint - Spot market's token mint. Must have >= 5 decimals (exactly 6 for the
+     *   quote/index-0 market).
+     * @param optimalUtilization - Utilization at the borrow-rate kink, SPOT_UTILIZATION_PRECISION (1e6, 100% = 1e6).
+     * @param optimalRate - Borrow rate at `optimalUtilization`, SPOT_RATE_PRECISION (1e6, 100% APR = 1e6).
+     * @param maxRate - Borrow rate at 100% utilization, SPOT_RATE_PRECISION (1e6).
+     * @param oracle - Oracle account for this market's price feed (`PublicKey.default` for `OracleSource.QuoteAsset`).
+     * @param oracleSource - Oracle provider/format for `oracle`.
+     * @param initialAssetWeight - Initial (deposit) asset weight, SPOT_WEIGHT_PRECISION (1e4, 100% = 1e4).
+     * @param maintenanceAssetWeight - Maintenance asset weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param initialLiabilityWeight - Initial (borrow) liability weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param maintenanceLiabilityWeight - Maintenance liability weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param imfFactor - Increases weight penalty as position size grows, SPOT_IMF_PRECISION (1e6). Default 0.
+     * @param liquidatorFee - Fee paid to liquidators, LIQUIDATION_FEE_PRECISION (1e6). Default 0.
+     * @param ifLiquidationFee - Portion of the liquidation fee routed to the insurance fund, LIQUIDATION_FEE_PRECISION (1e6). Default 0.
+     * @param activeStatus - If `true`, market is `Active` immediately; otherwise `Initialized` (trading disabled until a later status update). Requires cold admin when `true`. Default `true`.
+     * @param assetTier - Collateral tier gating cross-margin usability. Default `AssetTier.COLLATERAL`.
+     * @param scaleInitialAssetWeightStart - Deposit-token-amount threshold, QUOTE_PRECISION (1e6) equivalent notional, above which `initialAssetWeight` scales down. Default 0 (disabled).
+     * @param withdrawGuardThreshold - Token-amount threshold, market's native decimals, above which large single withdraws/borrows are blocked. Default 0.
+     * @param orderTickSize - Minimum price increment for spot orders, PRICE_PRECISION (1e6). Default 1.
+     * @param orderStepSize - Minimum base size increment for spot orders, market's native decimals. Also seeds `minOrderSize`. Default 1.
+     * @param ifTotalFactor - Insurance fund fee share of the total spot fee, IF_FACTOR_PRECISION (1e6). Default 0.
+     * @param name - Market display name, UTF-8 encoded and padded/truncated to 32 bytes. Default `DEFAULT_MARKET_NAME`.
+     * @param marketIndex - Explicit spot market index; defaults to `state.numberOfSpotMarkets` (the next free slot) when omitted.
+     * @returns Transaction signature.
+     */
     initializeSpotMarket(mint: PublicKey, optimalUtilization: number, optimalRate: number, maxRate: number, oracle: PublicKey, oracleSource: OracleSource, initialAssetWeight: number, maintenanceAssetWeight: number, initialLiabilityWeight: number, maintenanceLiabilityWeight: number, imfFactor?: number, liquidatorFee?: number, ifLiquidationFee?: number, activeStatus?: boolean, assetTier?: {
         collateral: {};
     }, scaleInitialAssetWeightStart?: BN, withdrawGuardThreshold?: BN, orderTickSize?: BN, orderStepSize?: BN, ifTotalFactor?: number, name?: string, marketIndex?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeSpotMarket` instruction without sending it. See `initializeSpotMarket`
+     * for parameter units and the cold-admin-if-`activeStatus` rule. Looks up `mint`'s owning
+     * token program on-chain (throws if the mint account doesn't exist) and resolves the admin
+     * signer to `wallet.publicKey` when `useHotWalletAdmin` is set, otherwise to `state.coldAdmin`
+     * (or the wallet if not yet subscribed).
+     * @returns The unsigned `initializeSpotMarket` instruction.
+     */
     getInitializeSpotMarketIx(mint: PublicKey, optimalUtilization: number, optimalRate: number, maxRate: number, oracle: PublicKey, oracleSource: OracleSource, initialAssetWeight: number, maintenanceAssetWeight: number, initialLiabilityWeight: number, maintenanceLiabilityWeight: number, imfFactor?: number, liquidatorFee?: number, ifLiquidationFee?: number, activeStatus?: boolean, assetTier?: {
         collateral: {};
     }, scaleInitialAssetWeightStart?: BN, withdrawGuardThreshold?: BN, orderTickSize?: BN, orderStepSize?: BN, ifTotalFactor?: number, name?: string, marketIndex?: number): Promise<TransactionInstruction>;
+    /**
+     * Closes a mis-initialized spot market and refunds rent to the admin. Requires warm admin
+     * (`check_warm`). On-chain the handler only allows deleting the **most recently created**
+     * market (`marketIndex == state.numberOfSpotMarkets - 1`), still in `Initialized` status
+     * (never activated), with zero deposit and borrow balances and empty vaults — otherwise it
+     * throws `InvalidMarketAccountforDeletion`.
+     * @param marketIndex - Index of the spot market to delete; must be the last-created, unactivated, empty market.
+     * @returns Transaction signature.
+     */
     deleteInitializedSpotMarket(marketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `deleteInitializedSpotMarket` instruction without sending it. See
+     * `deleteInitializedSpotMarket` for the on-chain preconditions.
+     * @param marketIndex - Index of the spot market to delete.
+     * @returns The unsigned `deleteInitializedSpotMarket` instruction.
+     */
     getDeleteInitializedSpotMarketIx(marketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Initializes a new perp market's `PerpMarket` PDA and seeds its AMM. Requires warm admin
+     * (`check_warm`); if `activeStatus` is `true` the on-chain handler additionally requires
+     * the **cold** admin (a market cannot launch active under a warm-only signer). The handler
+     * asserts `marketIndex === state.numberOfMarkets` (must be the next sequential index) and
+     * that `baseAssetReserve === quoteAssetReserve` (the initial mark price is exactly
+     * `pegMultiplier`). Does not add the market to the AMM cache — call `addMarketToAmmCache`
+     * separately (typically before the market can be traded/cranked).
+     * @param marketIndex - New market's index; must equal `state.numberOfMarkets`.
+     * @param priceOracle - Oracle account backing this market's price feed.
+     * @param baseAssetReserve - Initial AMM base reserve, BASE_PRECISION (1e9). Must equal `quoteAssetReserve`.
+     * @param quoteAssetReserve - Initial AMM quote reserve, BASE_PRECISION (1e9, AMM-internal units, not quote-asset dollars). Must equal `baseAssetReserve`.
+     * @param periodicity - Funding period, seconds (`market.marketStats.fundingPeriod`), as a BN.
+     * @param pegMultiplier - AMM peg, PEG_PRECISION (1e6). With equal reserves this fixes the initial mark price to `pegMultiplier`. Default `PEG_PRECISION` (price = 1.0).
+     * @param oracleSource - Oracle provider/format for `priceOracle`. Default `OracleSource.PYTH_LAZER`.
+     * @param contractTier - Risk/collateral tier for the contract. Default `ContractTier.SPECULATIVE`.
+     * @param marginRatioInitial - Initial margin ratio, MARGIN_PRECISION (1e4, e.g. 2000 = 20% = 5x max leverage). Default 2000.
+     * @param marginRatioMaintenance - Maintenance margin ratio, MARGIN_PRECISION (1e4). Default 500 (5%).
+     * @param liquidatorFee - Fee paid to liquidators, LIQUIDATION_FEE_PRECISION (1e6). Default 0.
+     * @param ifLiquidatorFee - Portion of the liquidation fee routed to the insurance fund, LIQUIDATION_FEE_PRECISION (1e6). Default 10000 (1%).
+     * @param imfFactor - Increases the effective margin requirement as position size grows, PERCENTAGE_PRECISION-scaled (1e6). Default 0.
+     * @param activeStatus - If `true`, market is `Active` immediately; otherwise `Initialized`. Requires cold admin when `true`. Default `true`.
+     * @param baseSpread - Base bid/ask spread around the AMM reserve price, BID_ASK_SPREAD_PRECISION (1e6). Default 0.
+     * @param maxSpread - Maximum allowed total spread, BID_ASK_SPREAD_PRECISION (1e6). Default 142500 (14.25%).
+     * @param maxOpenInterest - Cap on base-asset open interest, BASE_PRECISION (1e9). Default 0 (unlimited — treated as no cap by downstream checks).
+     * @param maxRevenueWithdrawPerPeriod - Cap on revenue-pool withdrawals per settlement period, QUOTE_PRECISION (1e6). Default 0.
+     * @param quoteMaxInsurance - Lifetime cap on insurance draws for this market, QUOTE_PRECISION (1e6). Default 0.
+     * @param orderStepSize - Minimum base-size increment for orders, BASE_PRECISION (1e9). Default `BASE_PRECISION / 10000`.
+     * @param orderTickSize - Minimum price increment for orders, PRICE_PRECISION (1e6). Default `PRICE_PRECISION / 100000`.
+     * @param minOrderSize - Minimum base order size, BASE_PRECISION (1e9). Default `BASE_PRECISION / 10000`.
+     * @param concentrationCoefScale - Unitless divisor controlling AMM liquidity concentration around the peg (`concentrationCoef = CONCENTRATION_PRECISION + (MAX_CONCENTRATION_COEFFICIENT - CONCENTRATION_PRECISION) / scale`; must be > 0). Default `ONE` (widest allowed concentration). Larger scale narrows the depth band.
+     * @param curveUpdateIntensity - 0-100 knob controlling how aggressively the AMM curve/peg re-centers on repegs. Default 0 (disabled).
+     * @param ammJitIntensity - 0-100 knob controlling how aggressively the AMM just-in-time-fills maker orders. Default 0 (disabled).
+     * @param name - Market display name, UTF-8 encoded and padded/truncated to 32 bytes. Default `DEFAULT_MARKET_NAME`.
+     * @param lpPoolId - LP pool this market's hedge exposure is routed to; 0 means unassigned. Default 0.
+     * @param fundingClampThreshold - Dead-zone half-width before funding ramps up, basis points (BPS_PRECISION, 1e4). 0 falls back on-chain to 5 bps. Default 0.
+     * @param fundingRampSlope - Slope applied to the price spread beyond the dead zone, PERCENTAGE_PRECISION (1e6, 1e6 = 1.0x). 0 falls back on-chain to 1e6 (1.0x). Default 0.
+     * @returns Transaction signature.
+     */
     initializePerpMarket(marketIndex: number, priceOracle: PublicKey, baseAssetReserve: BN, quoteAssetReserve: BN, periodicity: BN, pegMultiplier?: BN, oracleSource?: OracleSource, contractTier?: ContractTier, marginRatioInitial?: number, marginRatioMaintenance?: number, liquidatorFee?: number, ifLiquidatorFee?: number, imfFactor?: number, activeStatus?: boolean, baseSpread?: number, maxSpread?: number, maxOpenInterest?: BN, maxRevenueWithdrawPerPeriod?: BN, quoteMaxInsurance?: BN, orderStepSize?: BN, orderTickSize?: BN, minOrderSize?: BN, concentrationCoefScale?: BN, curveUpdateIntensity?: number, ammJitIntensity?: number, name?: string, lpPoolId?: number, fundingClampThreshold?: number, fundingRampSlope?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializePerpMarket` instruction without sending it. See `initializePerpMarket`
+     * for parameter units and the cold-admin-if-`activeStatus` rule.
+     * @returns Single-element array containing the unsigned `initializePerpMarket` instruction.
+     */
     getInitializePerpMarketIx(marketIndex: number, priceOracle: PublicKey, baseAssetReserve: BN, quoteAssetReserve: BN, periodicity: BN, pegMultiplier?: BN, oracleSource?: OracleSource, contractTier?: ContractTier, marginRatioInitial?: number, marginRatioMaintenance?: number, liquidatorFee?: number, ifLiquidatorFee?: number, imfFactor?: number, activeStatus?: boolean, baseSpread?: number, maxSpread?: number, maxOpenInterest?: BN, maxRevenueWithdrawPerPeriod?: BN, quoteMaxInsurance?: BN, orderStepSize?: BN, orderTickSize?: BN, minOrderSize?: BN, concentrationCoefScale?: BN, curveUpdateIntensity?: number, ammJitIntensity?: number, name?: string, lpPoolId?: number, fundingClampThreshold?: number, fundingRampSlope?: number): Promise<TransactionInstruction[]>;
+    /**
+     * Creates the protocol-wide singleton `AmmCache` PDA (one-time setup, empty until
+     * `addMarketToAmmCache` is called per market). Requires warm admin (`check_warm`).
+     * @returns Transaction signature.
+     */
     initializeAmmCache(txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeAmmCache` instruction without sending it. See `initializeAmmCache`.
+     * @returns The unsigned `initializeAmmCache` instruction.
+     */
     getInitializeAmmCacheIx(): Promise<TransactionInstruction>;
+    /**
+     * Appends a perp market's entry to the `AmmCache` (reallocating it larger by one slot).
+     * Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if the market index
+     * is already present in the cache. A market must be added here before keeper cranks that
+     * rely on the AMM cache (e.g. LP-pool settlement) can process it.
+     * @param perpMarketIndex - Index of the perp market to add.
+     * @returns Transaction signature.
+     */
     addMarketToAmmCache(perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `addMarketToAmmCache` instruction without sending it. See `addMarketToAmmCache`.
+     * @param perpMarketIndex - Index of the perp market to add. Throws if the market is not
+     *   already tracked by the local account subscriber.
+     * @returns The unsigned `addMarketToAmmCache` instruction.
+     */
     getAddMarketToAmmCacheIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Closes the `AmmCache` PDA, refunding rent to the admin. Requires warm admin
+     * (`check_warm`). Removes tracking for every market at once — there is no per-market
+     * inverse of `addMarketToAmmCache`.
+     * @returns Transaction signature.
+     */
     deleteAmmCache(txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `deleteAmmCache` instruction without sending it. See `deleteAmmCache`.
+     * @returns The unsigned `deleteAmmCache` instruction.
+     */
     getDeleteAmmCacheIx(): Promise<TransactionInstruction>;
+    /**
+     * Refreshes the `AmmCache` entries for the given perp markets from their current on-chain
+     * state and oracle price (market stats, MM-oracle price/validity). Requires the `LpCache`
+     * hot key (or warm/cold). `perpMarketIndexes` are passed as readable perp markets in
+     * `remainingAccounts` (each market's oracle account must be resolvable via the local
+     * account subscriber); the quote spot market (index 0) is always included as readable.
+     * @param perpMarketIndexes - Perp market indexes to refresh in the cache.
+     * @returns Transaction signature.
+     */
     updateInitialAmmCacheInfo(perpMarketIndexes: number[], txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateInitialAmmCacheInfo` instruction without sending it. See
+     * `updateInitialAmmCacheInfo`.
+     * @param perpMarketIndexes - Perp market indexes to refresh in the cache.
+     * @returns The unsigned `updateInitialAmmCacheInfo` instruction.
+     */
     getUpdateInitialAmmCacheInfoIx(perpMarketIndexes: number[]): Promise<TransactionInstruction>;
+    /**
+     * Force-overwrites one market's `AmmCache` entry fields (admin escape hatch, e.g. to
+     * recover from a bad cache after an incident). Requires the `LpCache` hot key (or
+     * warm/cold). Only fields present in `params` are changed; omitted fields keep their
+     * current cached value. No-op (does not throw) if `perpMarketIndex` has no cache entry yet.
+     *
+     * Caution: despite its name, `params.lastSettleTs` is **not** forwarded to the
+     * instruction — `getOverrideAmmCacheInfoIx` expects `lastSettleSlot` and this wrapper
+     * passes `params` straight through, so any `lastSettleTs` value is silently dropped and
+     * the cache's `lastSettleSlot` is left unchanged. Call `getOverrideAmmCacheInfoIx` directly
+     * with `lastSettleSlot` if that field needs to be overridden.
+     * @param perpMarketIndex - Perp market whose cache entry to override.
+     * @param params.quoteOwedFromLpPool - Quote owed from the LP pool to this market's hedge, QUOTE_PRECISION (1e6), signed.
+     * @param params.lastSettleTs - Not applied by this method; see caution above.
+     * @param params.lastFeePoolTokenAmount - Cached fee-pool token balance, quote spot market's native decimals.
+     * @param params.lastNetPnlPoolTokenAmount - Cached net PnL-pool token balance, quote spot market's native decimals, signed.
+     * @param params.ammPositionScalar - Unitless 0-100 scalar applied to the AMM's hedge position sizing.
+     * @param params.ammInventoryLimit - Inventory limit for the AMM's hedge position, BASE_PRECISION (1e9), signed.
+     * @returns Transaction signature.
+     */
     overrideAmmCacheInfo(perpMarketIndex: number, params: {
         quoteOwedFromLpPool?: BN;
         lastSettleTs?: BN;
@@ -40,6 +228,12 @@ export declare class AdminClient extends VelocityClient {
         ammPositionScalar?: number;
         ammInventoryLimit?: BN;
     }, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `overrideAmmCacheInfo` instruction without sending it. Unlike `overrideAmmCacheInfo`,
+     * this overload's `params` correctly uses `lastSettleSlot` (not `lastSettleTs`) and does
+     * forward it. See `overrideAmmCacheInfo` for field units.
+     * @returns The unsigned `overrideAmmCacheInfo` instruction.
+     */
     getOverrideAmmCacheInfoIx(perpMarketIndex: number, params: {
         quoteOwedFromLpPool?: BN;
         lastSettleSlot?: BN;
@@ -48,218 +242,1820 @@ export declare class AdminClient extends VelocityClient {
         ammPositionScalar?: number;
         ammInventoryLimit?: BN;
     }): Promise<TransactionInstruction>;
+    /**
+     * Intended to reallocate the `AmmCache` to `state.numberOfMarkets` entries and reset it
+     * (`ResetAmmCache` accounts struct is gated on the `LpCache` hot key, or warm/cold, per
+     * `programs/velocity/src/instructions/admin.rs`). **Currently non-functional**: no
+     * `reset_amm_cache` handler is wired into the program's instruction dispatch, so this
+     * instruction does not exist in the IDL — `getResetAmmCacheIx` casts to `any` to bypass
+     * the missing type, but calling it throws at runtime (`program.instruction.resetAmmCache`
+     * is `undefined`). Use `deleteAmmCache` + `initializeAmmCache` + `addMarketToAmmCache` per
+     * market to achieve the same effect until this is wired up on-chain.
+     * @returns Transaction signature (in practice: throws before a transaction is built).
+     */
     resetAmmCache(txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the (currently non-existent) `resetAmmCache` instruction. See `resetAmmCache` —
+     * this throws because the program does not expose a `resetAmmCache` instruction.
+     * @returns Never resolves successfully; throws when the missing instruction is invoked.
+     */
     getResetAmmCacheIx(): Promise<TransactionInstruction>;
+    /**
+     * Closes a mis-initialized perp market and refunds rent to the admin. Requires warm admin
+     * (`check_warm`). On-chain the handler only allows deleting the **most recently created**
+     * market (`marketIndex == state.numberOfMarkets - 1`), still in `Initialized` status
+     * (never activated), with zero users — otherwise it throws `InvalidMarketAccountforDeletion`.
+     * @param marketIndex - Index of the perp market to delete; must be the last-created, unactivated, userless market.
+     * @returns Transaction signature.
+     */
     deleteInitializedPerpMarket(marketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `deleteInitializedPerpMarket` instruction without sending it. See
+     * `deleteInitializedPerpMarket` for the on-chain preconditions.
+     * @param marketIndex - Index of the perp market to delete.
+     * @returns The unsigned `deleteInitializedPerpMarket` instruction.
+     */
     getDeleteInitializedPerpMarketIx(marketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Directly overwrites the AMM's base/quote reserves and `sqrtK` for a perp market — an
+     * admin escape hatch to force the AMM mark price (`quoteAssetReserve / baseAssetReserve *
+     * pegMultiplier`) without going through a repeg. Requires warm admin (`check_warm`).
+     * Re-derives min/max base reserve bounds from the new `sqrtK` and re-validates the market
+     * (`validate_perp_market`) before committing, so an inconsistent reserve/peg combination
+     * fails the transaction.
+     * @param perpMarketIndex - Perp market to move.
+     * @param baseAssetReserve - New AMM base reserve, BASE_PRECISION (1e9).
+     * @param quoteAssetReserve - New AMM quote reserve, BASE_PRECISION (1e9, AMM-internal units).
+     * @param sqrtK - New invariant `sqrt(baseAssetReserve * quoteAssetReserve)`, BASE_PRECISION (1e9). Defaults to the exact square root of `baseAssetReserve * quoteAssetReserve` when omitted.
+     * @returns Transaction signature.
+     */
     moveAmmPrice(perpMarketIndex: number, baseAssetReserve: BN, quoteAssetReserve: BN, sqrtK?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `moveAmmPrice` instruction without sending it. See `moveAmmPrice` for units
+     * and the `sqrtK` default.
+     * @returns The unsigned `moveAmmPrice` instruction.
+     */
     getMoveAmmPriceIx(perpMarketIndex: number, baseAssetReserve: BN, quoteAssetReserve: BN, sqrtK?: BN): Promise<TransactionInstruction>;
+    /**
+     * Rescales a perp market's AMM invariant (`sqrtK`) while holding the mark price
+     * approximately constant, widening or tightening depth around the current peg. Requires
+     * warm admin (`check_warm`). On-chain, increasing `sqrtK` must cost the AMM's fee reserve
+     * a non-negative amount (charged against `totalFeeMinusDistributions`, capped at that
+     * balance) and decreasing it must yield a non-positive cost; the resulting price move must
+     * stay within `MAX_UPDATE_K_PRICE_CHANGE` and `sqrtK` may not increase past `MAX_SQRT_K` —
+     * violating any of these throws `InvalidUpdateK`.
+     * @param perpMarketIndex - Perp market to rescale.
+     * @param sqrtK - New invariant, BASE_PRECISION (1e9).
+     * @returns Transaction signature.
+     */
     updateK(perpMarketIndex: number, sqrtK: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateK` instruction without sending it. See `updateK` for units and the
+     * on-chain cost/price-change constraints.
+     * @returns The unsigned `updateK` instruction.
+     */
     getUpdateKIx(perpMarketIndex: number, sqrtK: BN): Promise<TransactionInstruction>;
+    /**
+     * Re-centers a perp market's AMM around a new peg and invariant while keeping the AMM's
+     * net position unchanged (`amm.recenter`) — the admin-driven counterpart of an automatic
+     * repeg, typically used to realign the AMM to the oracle after a large price move.
+     * Requires warm admin (`check_warm`). Re-derives min/max base reserve bounds and
+     * re-validates the market before committing.
+     * @param perpMarketIndex - Perp market to recenter.
+     * @param pegMultiplier - New AMM peg, PEG_PRECISION (1e6).
+     * @param sqrtK - New invariant, BASE_PRECISION (1e9).
+     * @returns Transaction signature.
+     */
     recenterPerpMarketAmm(perpMarketIndex: number, pegMultiplier: BN, sqrtK: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `recenterPerpMarketAmm` instruction without sending it. See
+     * `recenterPerpMarketAmm` for units.
+     * @returns The unsigned `recenterPerpMarketAmm` instruction.
+     */
     getRecenterPerpMarketAmmIx(perpMarketIndex: number, pegMultiplier: BN, sqrtK: BN): Promise<TransactionInstruction>;
+    /**
+     * Keeper-cranked variant of `recenterPerpMarketAmm`: derives the target peg/invariant from
+     * the current oracle price (and an optional target depth) instead of taking them as
+     * explicit params. Requires the `AmmCrank` hot key (or warm/cold).
+     * @param perpMarketIndex - Perp market to recenter.
+     * @param depth - Optional target liquidity depth to recenter around, BASE_PRECISION (1e9). Omit to use the market's existing depth.
+     * @returns Transaction signature.
+     */
     recenterPerpMarketAmmCrank(perpMarketIndex: number, depth?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `recenterPerpMarketAmmCrank` instruction without sending it. See
+     * `recenterPerpMarketAmmCrank`.
+     * @returns The unsigned `recenterPerpMarketAmmCrank` instruction.
+     */
     getRecenterPerpMarketAmmCrankIx(perpMarketIndex: number, depth?: BN): Promise<TransactionInstruction>;
+    /**
+     * Updates a perp market's AMM concentration coefficient, changing how tightly liquidity
+     * is concentrated around the peg (calls the on-chain `updatePerpMarketConcentrationCoef`
+     * instruction). Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param concentrationScale - Unitless divisor, must be > 0 (`concentrationCoef = CONCENTRATION_PRECISION + (MAX_CONCENTRATION_COEFFICIENT - CONCENTRATION_PRECISION) / concentrationScale`). Larger scale narrows the depth band; `1` yields the widest allowed concentration.
+     * @returns Transaction signature.
+     */
     updatePerpMarketConcentrationScale(perpMarketIndex: number, concentrationScale: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketConcentrationCoef` instruction without sending it. See
+     * `updatePerpMarketConcentrationScale`.
+     * @returns The unsigned `updatePerpMarketConcentrationCoef` instruction.
+     */
     getUpdatePerpMarketConcentrationScaleIx(perpMarketIndex: number, concentrationScale: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets which LP pool a perp market's hedge exposure (`hedgeConfig.poolId`) is routed to.
+     * Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param lpPoolId - Target LP pool id; 0 means unassigned.
+     * @returns Transaction signature.
+     */
     updatePerpMarketLpPoolId(perpMarketIndex: number, lpPoolId: number): Promise<string>;
+    /**
+     * Builds the `updatePerpMarketLpPoolId` instruction without sending it. See
+     * `updatePerpMarketLpPoolId`.
+     * @returns The unsigned `updatePerpMarketLpPoolId` instruction.
+     */
     getUpdatePerpMarketLpPoolIdIx(perpMarketIndex: number, lpPoolId: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's LP-pool hedge status (`hedgeConfig.status`) and immediately
+     * refreshes its `AmmCache` entry from the new market state. Requires warm admin
+     * (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param lpStatus - New hedge status bitmask/value for `hedgeConfig.status`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketLpPoolStatus(perpMarketIndex: number, lpStatus: number): Promise<string>;
+    /**
+     * Builds the `updatePerpMarketLpPoolStatus` instruction without sending it. See
+     * `updatePerpMarketLpPoolStatus`.
+     * @returns The unsigned `updatePerpMarketLpPoolStatus` instruction.
+     */
     getUpdatePerpMarketLpPoolStatusIx(perpMarketIndex: number, lpStatus: number): Promise<TransactionInstruction>;
+    /**
+     * Convenience wrapper around `moveAmmPrice`: computes, from the locally cached
+     * `PerpMarket` account, the base/quote reserves that move the AMM's mark price to
+     * `targetPrice` (holding `sqrtK` fixed at its current value) and sends that instruction.
+     * Requires warm admin (`check_warm`, same as `moveAmmPrice`). Throws if the market isn't
+     * tracked by the local account subscriber.
+     * @param perpMarketIndex - Perp market to move.
+     * @param targetPrice - Desired AMM mark price, PRICE_PRECISION (1e6).
+     * @returns Transaction signature.
+     */
     moveAmmToPrice(perpMarketIndex: number, targetPrice: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the underlying `moveAmmPrice` instruction that moves the AMM to `targetPrice`.
+     * See `moveAmmToPrice`.
+     * @returns The unsigned `moveAmmPrice` instruction.
+     */
     getMoveAmmToPriceIx(perpMarketIndex: number, targetPrice: BN): Promise<TransactionInstruction>;
+    /**
+     * Repegs a perp market's AMM toward `newPeg`, adjusting reserves to keep the invariant
+     * (`sqrtK`) fixed while moving the mark price. Requires warm admin (`check_warm`). The
+     * on-chain `repeg` routine validates the oracle (per `state.oracleGuardRails`) and charges
+     * the reserve/fee-pool the resulting `adjustment_cost`; emits `AmmCurveChanged`.
+     * @param newPeg - Candidate new AMM peg, PEG_PRECISION (1e6).
+     * @param perpMarketIndex - Perp market to repeg.
+     * @returns Transaction signature.
+     */
     repegAmmCurve(newPeg: BN, perpMarketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `repegAmmCurve` instruction without sending it. See `repegAmmCurve`. Throws
+     * if `perpMarketIndex` isn't tracked by the local account subscriber (needed to resolve
+     * the market's oracle account).
+     * @returns The unsigned `repegAmmCurve` instruction.
+     */
     getRepegAmmCurveIx(newPeg: BN, perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Nudges a perp market's cached oracle TWAP (`marketStats.historicalOracleData.lastOraclePriceTwap`,
+     * PRICE_PRECISION 1e6) toward the freshly-sampled oracle TWAP, but only accepts the move
+     * if it narrows the mark/oracle TWAP gap or flips its sign (otherwise clamps the cached
+     * TWAP to the mark TWAP). Requires warm admin (`check_warm`); throws `PriceBandsBreached`
+     * on-chain if the new gap would be strictly larger with the same sign, and `InvalidOracle`
+     * if the oracle can't be read.
+     * @param perpMarketIndex - Perp market to update.
+     * @returns Transaction signature.
+     */
     updatePerpMarketAmmOracleTwap(perpMarketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketAmmOracleTwap` instruction without sending it. See
+     * `updatePerpMarketAmmOracleTwap`.
+     * @returns The unsigned `updatePerpMarketAmmOracleTwap` instruction.
+     */
     getUpdatePerpMarketAmmOracleTwapIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Admin failsafe that force-resets a perp market's cached oracle TWAP to the current mark
+     * TWAP (unconditionally, unlike `updatePerpMarketAmmOracleTwap`'s gap-narrowing check).
+     * Requires warm admin (`check_warm`). Use when the oracle TWAP has drifted badly (e.g.
+     * after an oracle outage) and funding needs to be re-anchored immediately.
+     * @param perpMarketIndex - Perp market to reset.
+     * @returns Transaction signature.
+     */
     resetPerpMarketAmmOracleTwap(perpMarketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `resetPerpMarketAmmOracleTwap` instruction without sending it. See
+     * `resetPerpMarketAmmOracleTwap`.
+     * @returns The unsigned `resetPerpMarketAmmOracleTwap` instruction.
+     */
     getResetPerpMarketAmmOracleTwapIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Tops up a perp market's AMM fee pool: transfers `amount` from `sourceVault` (a token
+     * account the caller controls) into the quote spot market's vault via CPI, and credits
+     * the same amount to `perpMarket.amm.totalFeeMinusDistributions` / `amm.feePool`. Requires
+     * the `VaultDeposit` hot key (or warm/cold).
+     * @param perpMarketIndex - Perp market whose fee pool to credit.
+     * @param amount - Amount to deposit, quote spot market's native decimals (QUOTE_PRECISION, 1e6, for the standard USDC quote market).
+     * @param sourceVault - Token account to transfer `amount` from; `admin` must be its authority.
+     * @returns Transaction signature.
+     */
     depositIntoPerpMarketFeePool(perpMarketIndex: number, amount: BN, sourceVault: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `depositIntoPerpMarketFeePool` instruction without sending it. See
+     * `depositIntoPerpMarketFeePool`.
+     * @returns The unsigned `depositIntoPerpMarketFeePool` instruction.
+     */
     getDepositIntoPerpMarketFeePoolIx(perpMarketIndex: number, amount: BN, sourceVault: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Credits `amount` to a perp market's PnL pool balance as pure internal accounting — it
+     * does **not** move any tokens. On-chain the handler only validates that the quote spot
+     * market's actual vault balance still covers the resulting internal balances
+     * (`validate_spot_market_vault_amount`); it does not itself deposit the backing tokens, so
+     * call this only after (or together with) a real deposit that gets the tokens into the
+     * vault. Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market whose PnL pool to credit.
+     * @param amount - Amount to credit, quote spot market's native decimals (QUOTE_PRECISION, 1e6, for the standard USDC quote market).
+     * @returns Transaction signature.
+     */
     updatePerpMarketPnlPool(perpMarketIndex: number, amount: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketPnlPool` instruction without sending it. See
+     * `updatePerpMarketPnlPool` — no tokens are moved by this instruction.
+     * @returns The unsigned `updatePerpMarketPnlPool` instruction.
+     */
     getUpdatePerpMarketPnlPoolIx(perpMarketIndex: number, amount: BN): Promise<TransactionInstruction>;
+    /**
+     * Deposits `amount` from `sourceVault` (a token account the caller controls) directly into
+     * a spot market's vault via CPI and credits the market's deposit balance accordingly.
+     * Requires the `VaultDeposit` hot key (or warm/cold). Throws on-chain if the spot market
+     * has deposits paused (`SpotOperation::Deposit`).
+     * @param spotMarketIndex - Spot market whose vault to deposit into.
+     * @param amount - Amount to deposit, the spot market's native token decimals.
+     * @param sourceVault - Token account to transfer `amount` from; `admin` must be its authority.
+     * @returns Transaction signature.
+     */
     depositIntoSpotMarketVault(spotMarketIndex: number, amount: BN, sourceVault: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `depositIntoSpotMarketVault` instruction without sending it. See
+     * `depositIntoSpotMarketVault`. Automatically appends transfer-hook extra account metas
+     * when the mint requires them.
+     * @returns The unsigned `depositIntoSpotMarketVault` instruction.
+     */
     getDepositIntoSpotMarketVaultIx(spotMarketIndex: number, amount: BN, sourceVault: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Rotates the root (`state.coldAdmin`) authority — the top of the cold ⊇ warm ⊇
+     * hot(role) tier hierarchy. Cold-only: the `ColdAdminUpdateState` context requires
+     * the current signer to equal `state.coldAdmin`. This is the one-time-per-rotation
+     * root key change; `warmAdmin` and `pauseAdmin` are rotated separately via
+     * `updateWarmAdmin`/`updatePauseAdmin` (also cold-only).
+     * @param admin - New cold admin pubkey.
+     * @returns Transaction signature.
+     */
     updateAdmin(admin: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateAdmin` instruction without sending it. See `updateAdmin`.
+     * @returns The unsigned `updateAdmin` instruction.
+     */
     getUpdateAdminIx(admin: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Sets how aggressively a perp market's AMM curve auto-adjusts. Requires the market's
+     * `HotAdminUpdatePerpMarket` gate — the `check_warm` constraint on that context currently
+     * accepts cold or warm admin only (no dedicated hot role is wired to it). On-chain, values
+     * `0..=100` control repeg/formulaic-k intensity and `101..=200` additionally enable
+     * reference-price-offset intensity; values above 200 throw `DefaultError`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param curveUpdateIntensity - 0-200 intensity knob (see above for the two sub-ranges).
+     * @returns Transaction signature.
+     */
     updatePerpMarketCurveUpdateIntensity(perpMarketIndex: number, curveUpdateIntensity: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketCurveUpdateIntensity` instruction without sending it. See
+     * `updatePerpMarketCurveUpdateIntensity`.
+     * @returns The unsigned `updatePerpMarketCurveUpdateIntensity` instruction.
+     */
     getUpdatePerpMarketCurveUpdateIntensityIx(perpMarketIndex: number, curveUpdateIntensity: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the dead-band, as a percent of price, within which the AMM's reference-price offset
+     * (used to bias the AMM's quoted price away from the raw oracle/mark price) is suppressed.
+     * Gated the same as `updatePerpMarketCurveUpdateIntensity` (warm admin via
+     * `HotAdminUpdatePerpMarket`'s `check_warm` constraint). Throws `DefaultError` on-chain if
+     * `referencePriceOffsetDeadbandPct > 100`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param referencePriceOffsetDeadbandPct - 0-100 percent dead-band.
+     * @returns Transaction signature.
+     */
     updatePerpMarketReferencePriceOffsetDeadbandPct(perpMarketIndex: number, referencePriceOffsetDeadbandPct: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketReferencePriceOffsetDeadbandPct` instruction without sending
+     * it. See `updatePerpMarketReferencePriceOffsetDeadbandPct`.
+     * @returns The unsigned `updatePerpMarketReferencePriceOffsetDeadbandPct` instruction.
+     */
     getUpdatePerpMarketReferencePriceOffsetDeadbandPctIx(perpMarketIndex: number, referencePriceOffsetDeadbandPct: number): Promise<TransactionInstruction>;
+    /**
+     * **Currently non-functional**: the program does not expose an
+     * `update_perp_market_target_base_asset_amount_per_lp` instruction (no such handler is
+     * wired into `lib.rs`, and it's absent from the generated IDL). `getUpdatePerpMarketTargetBaseAssetAmountPerLpIx`
+     * casts `this.program.instruction` to `any` to bypass the missing type, but the call
+     * throws at runtime. `targetBaseAssetAmountPerLp` exists only as a legacy field in
+     * `test_utils/legacy_snapshot.rs`, not on the live `PerpMarket`/`AMM` struct.
+     * @param perpMarketIndex - Perp market that would be updated.
+     * @param targetBaseAssetAmountPerLP - Intended target base-asset-amount-per-LP value.
+     * @returns Transaction signature (in practice: throws before a transaction is built).
+     */
     updatePerpMarketTargetBaseAssetAmountPerLp(perpMarketIndex: number, targetBaseAssetAmountPerLP: number): Promise<TransactionSignature>;
+    /**
+     * Admin recalibration of a perp market's AMM fee-accounting summary stats. Requires the
+     * `AmmCrank` hot key (or warm/cold). If `netUnsettledFundingPnl` is provided it directly
+     * overwrites `perpMarket.netUnsettledFundingPnl`. If `updateAmmSummaryStats` is `true`,
+     * recomputes `amm.totalFeeMinusDistributions` from current market/spot-market/oracle state
+     * and applies the resulting delta to `amm.totalFee` and `amm.totalMmFee`; omitted or
+     * `false` leaves fee accounting untouched. Re-validates the market before committing.
+     * @param perpMarketIndex - Perp market to recalibrate.
+     * @param updateAmmSummaryStats - If `true`, recompute and correct AMM fee-accounting totals. Default: unset (no correction).
+     * @param netUnsettledFundingPnl - Overwrite for `perpMarket.netUnsettledFundingPnl`, QUOTE_PRECISION (1e6), signed. Default: unset (unchanged).
+     * @returns Transaction signature.
+     */
     updatePerpMarketAmmSummaryStats(perpMarketIndex: number, updateAmmSummaryStats?: boolean, netUnsettledFundingPnl?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketAmmSummaryStats` instruction without sending it. See
+     * `updatePerpMarketAmmSummaryStats`. Throws if `perpMarketIndex` isn't tracked by the
+     * local account subscriber (needed to resolve the market's oracle account).
+     * @returns The unsigned `updatePerpMarketAmmSummaryStats` instruction.
+     */
     getUpdatePerpMarketAmmSummaryStatsIx(perpMarketIndex: number, updateAmmSummaryStats?: boolean, netUnsettledFundingPnl?: BN): Promise<TransactionInstruction>;
+    /**
+     * Builds the (currently non-existent) `updatePerpMarketTargetBaseAssetAmountPerLp`
+     * instruction. See `updatePerpMarketTargetBaseAssetAmountPerLp` — this throws because the
+     * program does not expose that instruction.
+     * @returns Never resolves successfully; throws when the missing instruction is invoked.
+     */
     getUpdatePerpMarketTargetBaseAssetAmountPerLpIx(perpMarketIndex: number, targetBaseAssetAmountPerLP: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's initial and maintenance margin ratios (max leverage and
+     * liquidation threshold). Requires warm admin (`check_warm`). On-chain, validates the pair
+     * is internally consistent and compatible with the market's current `liquidatorFee`
+     * (`amm.validate_compatible_with_margin_ratio`) before committing.
+     * @param perpMarketIndex - Perp market to update.
+     * @param marginRatioInitial - Initial margin ratio, MARGIN_PRECISION (1e4, e.g. 2000 = 20% = 5x max leverage). Must be >= `marginRatioMaintenance`.
+     * @param marginRatioMaintenance - Maintenance margin ratio, MARGIN_PRECISION (1e4).
+     * @returns Transaction signature.
+     */
     updatePerpMarketMarginRatio(perpMarketIndex: number, marginRatioInitial: number, marginRatioMaintenance: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMarginRatio` instruction without sending it. See
+     * `updatePerpMarketMarginRatio`.
+     * @returns The unsigned `updatePerpMarketMarginRatio` instruction.
+     */
     getUpdatePerpMarketMarginRatioIx(perpMarketIndex: number, marginRatioInitial: number, marginRatioMaintenance: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's funding dead-zone: the band around the oracle TWAP within which no
+     * funding premium accrues, and the ramp applied to the premium beyond that band. Requires
+     * warm admin (`check_warm`). Unlike `initializePerpMarket` (where `0` silently falls back
+     * to defaults), the update handler validates its inputs directly and throws `DefaultError`
+     * if `fundingClampThreshold >= BPS_PRECISION` (i.e. must be < 100%) or if
+     * `fundingRampSlope === 0` (a zero slope would flatten every premium past the band to the
+     * funding-rate offset).
+     * @param perpMarketIndex - Perp market to update.
+     * @param fundingClampThreshold - Dead-zone half-width, basis points (BPS_PRECISION, 1e4). Must be < 10000.
+     * @param fundingRampSlope - Slope applied beyond the dead zone, PERCENTAGE_PRECISION (1e6, 1e6 = 1.0x). Must be > 0.
+     * @returns Transaction signature.
+     */
     updatePerpMarketFundingDeadZone(perpMarketIndex: number, fundingClampThreshold: number, fundingRampSlope: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketFundingDeadZone` instruction without sending it. See
+     * `updatePerpMarketFundingDeadZone` for units and validation.
+     * @returns The unsigned `updatePerpMarketFundingDeadZone` instruction.
+     */
     getUpdatePerpMarketFundingDeadZoneIx(perpMarketIndex: number, fundingClampThreshold: number, fundingRampSlope: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's IMF factors, which increase the effective margin requirement (and
+     * shrink unrealized-PnL asset weight) as position size grows. Requires warm admin
+     * (`check_warm`). Throws `DefaultError` on-chain if either value exceeds `SPOT_IMF_PRECISION` (1e6).
+     * @param perpMarketIndex - Perp market to update.
+     * @param imfFactor - Position-size margin penalty factor, SPOT_IMF_PRECISION (1e6). Must be <= 1e6.
+     * @param unrealizedPnlImfFactor - Position-size penalty factor applied to unrealized-PnL asset weight, SPOT_IMF_PRECISION (1e6). Must be <= 1e6.
+     * @returns Transaction signature.
+     */
     updatePerpMarketImfFactor(perpMarketIndex: number, imfFactor: number, unrealizedPnlImfFactor: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketImfFactor` instruction without sending it. See
+     * `updatePerpMarketImfFactor`.
+     * @returns The unsigned `updatePerpMarketImfFactor` instruction.
+     */
     getUpdatePerpMarketImfFactorIx(perpMarketIndex: number, imfFactor: number, unrealizedPnlImfFactor: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's base bid/ask spread around the AMM reserve price. Requires warm
+     * admin (`check_warm`). The AMM's cached `longSpread`/`shortSpread` are refreshed from
+     * this value on the next quote/fill rather than immediately.
+     * @param perpMarketIndex - Perp market to update.
+     * @param baseSpread - New base spread, BID_ASK_SPREAD_PRECISION (1e6).
+     * @returns Transaction signature.
+     */
     updatePerpMarketBaseSpread(perpMarketIndex: number, baseSpread: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketBaseSpread` instruction without sending it. See
+     * `updatePerpMarketBaseSpread`.
+     * @returns The unsigned `updatePerpMarketBaseSpread` instruction.
+     */
     getUpdatePerpMarketBaseSpreadIx(perpMarketIndex: number, baseSpread: number): Promise<TransactionInstruction>;
+    /**
+     * Sets how aggressively the AMM just-in-time-fills incoming taker orders against its own
+     * inventory before routing to the DLOB. Gated the same as `updatePerpMarketCurveUpdateIntensity`
+     * (warm admin via `HotAdminUpdatePerpMarket`'s `check_warm` constraint). Throws
+     * `DefaultError` on-chain if outside `0..=100`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param ammJitIntensity - 0-100 intensity; 0 disables AMM JIT fills.
+     * @returns Transaction signature.
+     */
     updateAmmJitIntensity(perpMarketIndex: number, ammJitIntensity: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateAmmJitIntensity` instruction without sending it. See
+     * `updateAmmJitIntensity`.
+     * @returns The unsigned `updateAmmJitIntensity` instruction.
+     */
     getUpdateAmmJitIntensityIx(perpMarketIndex: number, ammJitIntensity: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's display name. Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market to rename.
+     * @param name - New display name, UTF-8 encoded and padded/truncated to 32 bytes.
+     * @returns Transaction signature.
+     */
     updatePerpMarketName(perpMarketIndex: number, name: string): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketName` instruction without sending it. See `updatePerpMarketName`.
+     * @returns The unsigned `updatePerpMarketName` instruction.
+     */
     getUpdatePerpMarketNameIx(perpMarketIndex: number, name: string): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's display name. Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market to rename.
+     * @param name - New display name, UTF-8 encoded and padded/truncated to 32 bytes.
+     * @returns Transaction signature.
+     */
     updateSpotMarketName(spotMarketIndex: number, name: string): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketName` instruction without sending it. See `updateSpotMarketName`.
+     * @returns The unsigned `updateSpotMarketName` instruction.
+     */
     getUpdateSpotMarketNameIx(spotMarketIndex: number, name: string): Promise<TransactionInstruction>;
+    /**
+     * Sets which pool a spot market belongs to (used to segment markets, e.g. for LP-pool
+     * constituent grouping). Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param poolId - Target pool id.
+     * @returns Transaction signature.
+     */
     updateSpotMarketPoolId(spotMarketIndex: number, poolId: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketPoolId` instruction without sending it. See `updateSpotMarketPoolId`.
+     * @returns The unsigned `updateSpotMarketPoolId` instruction.
+     */
     getUpdateSpotMarketPoolIdIx(spotMarketIndex: number, poolId: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's maximum allowed total bid/ask spread. Gated the same as
+     * `updatePerpMarketCurveUpdateIntensity` (warm admin via `HotAdminUpdatePerpMarket`'s
+     * `check_warm` constraint). Throws `DefaultError` on-chain if `maxSpread` is below the
+     * market's current `baseSpread` or exceeds `marginRatioInitial * 100`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param maxSpread - New max spread, BID_ASK_SPREAD_PRECISION (1e6). Must be >= `baseSpread` and <= `marginRatioInitial * 100`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketMaxSpread(perpMarketIndex: number, maxSpread: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMaxSpread` instruction without sending it. See
+     * `updatePerpMarketMaxSpread` for units and validation.
+     * @returns The unsigned `updatePerpMarketMaxSpread` instruction.
+     */
     getUpdatePerpMarketMaxSpreadIx(perpMarketIndex: number, maxSpread: number): Promise<TransactionInstruction>;
+    /**
+     * Replaces the protocol-wide perp `FeeStructure` (fee tiers, filler reward, AMM/IF
+     * fee split) wholesale. Requires warm admin (`check_warm`). On-chain,
+     * `validate_fee_structure` rejects a structure whose `amm_fee_numerator +
+     * if_fee_numerator` (both FEE_PERCENTAGE_DENOMINATOR-scaled) exceeds 100% of the
+     * trade-fee remainder, among other tier sanity checks.
+     * @param feeStructure - Full replacement fee structure (not a partial patch).
+     * @returns Transaction signature.
+     */
     updatePerpFeeStructure(feeStructure: FeeStructure): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpFeeStructure` instruction without sending it. See
+     * `updatePerpFeeStructure`.
+     * @returns The unsigned `updatePerpFeeStructure` instruction.
+     */
     getUpdatePerpFeeStructureIx(feeStructure: FeeStructure): Promise<TransactionInstruction>;
+    /**
+     * Replaces the protocol-wide spot `FeeStructure` wholesale. Requires warm admin
+     * (`check_warm`); see `updatePerpFeeStructure` for validation.
+     * @param feeStructure - Full replacement fee structure (not a partial patch).
+     * @returns Transaction signature.
+     */
     updateSpotFeeStructure(feeStructure: FeeStructure): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotFeeStructure` instruction without sending it. See
+     * `updateSpotFeeStructure`.
+     * @returns The unsigned `updateSpotFeeStructure` instruction.
+     */
     getUpdateSpotFeeStructureIx(feeStructure: FeeStructure): Promise<TransactionInstruction>;
+    /**
+     * Sets the fraction of a liquidatable position that may be closed immediately
+     * (before the `updateLiquidationDuration` ramp phases in the rest). Requires warm
+     * admin (`check_warm`). On-chain the liquidatable fraction ramps linearly from this
+     * floor up to 100% over `liquidationDuration` slots since the user's last active
+     * slot (see `calculate_max_pct_to_liquidate`); shortages under 50 QUOTE_PRECISION
+     * always liquidate in full regardless of this setting.
+     * @param initialPctToLiquidate - Initial liquidatable fraction, LIQUIDATION_PCT_PRECISION (1e4, e.g. 2500 = 25%).
+     * @returns Transaction signature.
+     */
     updateInitialPctToLiquidate(initialPctToLiquidate: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateInitialPctToLiquidate` instruction without sending it. See
+     * `updateInitialPctToLiquidate`.
+     * @returns The unsigned `updateInitialPctToLiquidate` instruction.
+     */
     getUpdateInitialPctToLiquidateIx(initialPctToLiquidate: number): Promise<TransactionInstruction>;
+    /**
+     * Sets how many slots it takes for a liquidation's max-closeable fraction to ramp
+     * from `initialPctToLiquidate` up to 100% (see `updateInitialPctToLiquidate`).
+     * Requires warm admin (`check_warm`).
+     * @param liquidationDuration - Ramp duration, slots (comment in `calculate_max_pct_to_liquidate` notes ~150 slots ≈ 1 minute at 400ms/slot).
+     * @returns Transaction signature.
+     */
     updateLiquidationDuration(liquidationDuration: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateLiquidationDuration` instruction without sending it. See
+     * `updateLiquidationDuration`.
+     * @returns The unsigned `updateLiquidationDuration` instruction.
+     */
     getUpdateLiquidationDurationIx(liquidationDuration: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the extra maintenance-margin buffer applied when deciding whether a user is
+     * liquidatable, on top of the market's own maintenance margin ratio — a safety
+     * margin so liquidation triggers before a user is fully underwater. Requires warm
+     * admin (`check_warm`).
+     * @param updateLiquidationMarginBufferRatio - Extra margin buffer, MARGIN_PRECISION (1e4).
+     * @returns Transaction signature.
+     */
     updateLiquidationMarginBufferRatio(updateLiquidationMarginBufferRatio: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateLiquidationMarginBufferRatio` instruction without sending it.
+     * See `updateLiquidationMarginBufferRatio`.
+     * @returns The unsigned `updateLiquidationMarginBufferRatio` instruction.
+     */
     getUpdateLiquidationMarginBufferRatioIx(updateLiquidationMarginBufferRatio: number): Promise<TransactionInstruction>;
+    /**
+     * Replaces the protocol-wide `OracleGuardRails` (validity/confidence/divergence
+     * thresholds used to gate oracle-price-driven actions across every market).
+     * Requires warm admin (`check_warm`).
+     * @param oracleGuardRails - Full replacement guard-rail config (not a partial patch).
+     * @returns Transaction signature.
+     */
     updateOracleGuardRails(oracleGuardRails: OracleGuardRails): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateOracleGuardRails` instruction without sending it. See
+     * `updateOracleGuardRails`.
+     * @returns The unsigned `updateOracleGuardRails` instruction.
+     */
     getUpdateOracleGuardRailsIx(oracleGuardRails: OracleGuardRails): Promise<TransactionInstruction>;
+    /**
+     * Sets the buffer (past a perp market's `expiry_ts`) that must elapse before user
+     * positions in a `Settlement`-status market can be settled at the expiry price.
+     * Requires warm admin (`check_warm`).
+     * @param settlementDuration - Post-expiry settlement buffer, seconds.
+     * @returns Transaction signature.
+     */
     updateStateSettlementDuration(settlementDuration: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateStateSettlementDuration` instruction without sending it. See
+     * `updateStateSettlementDuration`.
+     * @returns The unsigned `updateStateSettlementDuration` instruction.
+     */
     getUpdateStateSettlementDurationIx(settlementDuration: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the protocol-wide cap on sub-accounts per authority
+     * (`state.maxNumberOfSubAccounts`) and, via `get_init_user_fee`, the denominator
+     * against which `state.numberOfSubAccounts` utilization phases in the
+     * `initializeUser` anti-spam fee (see `updateStateMaxInitializeUserFee`). Requires
+     * warm admin (`check_warm`).
+     * @param maxNumberOfSubAccounts - New protocol-wide sub-account cap.
+     * @returns Transaction signature.
+     */
     updateStateMaxNumberOfSubAccounts(maxNumberOfSubAccounts: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateStateMaxNumberOfSubAccounts` instruction without sending it.
+     * See `updateStateMaxNumberOfSubAccounts`.
+     * @returns The unsigned `updateStateMaxNumberOfSubAccounts` instruction.
+     */
     getUpdateStateMaxNumberOfSubAccountsIx(maxNumberOfSubAccounts: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the cap on the anti-spam fee `initializeUser` may charge as
+     * `state.numberOfSubAccounts` approaches `state.maxNumberOfSubAccounts`. On-chain
+     * (`State::get_init_user_fee`) the fee is 0 below ~80% utilization and then scales
+     * up to this cap by the time the cap is reached; `0` disables the fee entirely.
+     * Requires warm admin (`check_warm`).
+     * @param maxInitializeUserFee - Fee cap, hundredths of a SOL (e.g. `100` = 1 SOL, `1` = 0.01 SOL).
+     * @returns Transaction signature.
+     */
     updateStateMaxInitializeUserFee(maxInitializeUserFee: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateStateMaxInitializeUserFee` instruction without sending it. See
+     * `updateStateMaxInitializeUserFee`.
+     * @returns The unsigned `updateStateMaxInitializeUserFee` instruction.
+     */
     getUpdateStateMaxInitializeUserFeeIx(maxInitializeUserFee: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's withdraw guard threshold — the token-amount cap above which a
+     * single withdraw/borrow is blocked. Requires warm admin (`check_warm`, on the
+     * `AdminUpdateSpotMarketWithdrawGuardThreshold` context). On-chain the notional is priced
+     * with the max of the live oracle price and the 5-minute oracle TWAP (`StrictOraclePrice`),
+     * so a momentarily-manipulated-down oracle can't let an oversized threshold through;
+     * `validate_withdraw_guard_threshold` then re-derives the implied cap and rejects an
+     * inconsistent value.
+     * @param spotMarketIndex - Spot market to update.
+     * @param withdrawGuardThreshold - New threshold, the market's native token decimals.
+     * @param oracle - Must equal `spotMarket.oracle` — the account struct's `has_one = oracle`
+     *   constraint (`ErrorCode::InvalidOracle`) enforces this on-chain, so it is not a way to
+     *   point at a different price feed. When omitted, this is resolved automatically from the
+     *   local account cache (or, if not subscribed, by fetching and decoding the `SpotMarket`
+     *   account directly) — pass it explicitly only to avoid that extra lookup.
+     * @returns Transaction signature.
+     */
     updateWithdrawGuardThreshold(spotMarketIndex: number, withdrawGuardThreshold: BN, oracle?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateWithdrawGuardThreshold` instruction without sending it. See
+     * `updateWithdrawGuardThreshold` — in particular, the `oracle` param must equal
+     * `spotMarket.oracle` (enforced by the `has_one` constraint) and is auto-resolved when
+     * omitted. Throws if the spot market account can't be found when not subscribed.
+     * @returns The unsigned `updateWithdrawGuardThreshold` instruction.
+     */
     getUpdateWithdrawGuardThresholdIx(spotMarketIndex: number, withdrawGuardThreshold: BN, oracle?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's lending-gain carveouts: the share of deposit interest routed to the
+     * insurance fund (`ifFeeFactor`) and to the withdrawable protocol fee pool
+     * (`protocolFeeFactor`); lenders keep the remainder. Requires warm admin (`check_warm`).
+     * Throws `DefaultError` on-chain if the two factors don't sum to strictly less than 100%
+     * (a full 100% carveout would zero out lender interest and freeze the entire accrual path,
+     * including the IF/protocol credits themselves).
+     * @param spotMarketIndex - Spot market to update; must match the market account passed.
+     * @param ifFeeFactor - Insurance-fund carveout, IF_FACTOR_PRECISION (1e6).
+     * @param protocolFeeFactor - Protocol-fee-pool carveout, IF_FACTOR_PRECISION (1e6). `ifFeeFactor + protocolFeeFactor` must be < 1e6.
+     * @returns Transaction signature.
+     */
     updateSpotMarketIfFactor(spotMarketIndex: number, ifFeeFactor: number, protocolFeeFactor: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketIfFactor` instruction without sending it. See
+     * `updateSpotMarketIfFactor` for units and validation.
+     * @returns The unsigned `updateSpotMarketIfFactor` instruction.
+     */
     getUpdateSpotMarketIfFactorIx(spotMarketIndex: number, ifFeeFactor: number, protocolFeeFactor: number): Promise<TransactionInstruction>;
+    /**
+     * Sets how often a spot market's revenue pool may be settled to the insurance fund.
+     * Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param revenueSettlePeriod - Minimum interval between revenue settlements, seconds.
+     * @returns Transaction signature.
+     */
     updateSpotMarketRevenueSettlePeriod(spotMarketIndex: number, revenueSettlePeriod: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketRevenueSettlePeriod` instruction without sending it. See
+     * `updateSpotMarketRevenueSettlePeriod`.
+     * @returns The unsigned `updateSpotMarketRevenueSettlePeriod` instruction.
+     */
     getUpdateSpotMarketRevenueSettlePeriodIx(spotMarketIndex: number, revenueSettlePeriod: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's maximum total deposit balance. Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param maxTokenDeposits - New deposit cap, the market's native token decimals. `0` disables the cap.
+     * @returns Transaction signature.
+     */
     updateSpotMarketMaxTokenDeposits(spotMarketIndex: number, maxTokenDeposits: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketMaxTokenDeposits` instruction without sending it. See
+     * `updateSpotMarketMaxTokenDeposits`.
+     * @returns The unsigned `updateSpotMarketMaxTokenDeposits` instruction.
+     */
     getUpdateSpotMarketMaxTokenDepositsIx(spotMarketIndex: number, maxTokenDeposits: BN): Promise<TransactionInstruction>;
+    /**
+     * Caps a spot market's total borrows as a fraction of its `maxTokenDeposits`, rather than
+     * an absolute token amount. Requires warm admin (`check_warm`). On-chain, the effective cap
+     * is `maxTokenDeposits * maxTokenBorrowsFraction / 10000`; the handler throws
+     * `InvalidSpotMarketInitialization` if current borrows already exceed the new cap.
+     * @param spotMarketIndex - Spot market to update.
+     * @param maxTokenBorrowsFraction - Fraction of `maxTokenDeposits` borrowable, in hundredths of a percent (10000 = 100%).
+     * @returns Transaction signature.
+     */
     updateSpotMarketMaxTokenBorrows(spotMarketIndex: number, maxTokenBorrowsFraction: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketMaxTokenBorrows` instruction without sending it. See
+     * `updateSpotMarketMaxTokenBorrows`.
+     * @returns The unsigned `updateSpotMarketMaxTokenBorrows` instruction.
+     */
     getUpdateSpotMarketMaxTokenBorrowsIx(spotMarketIndex: number, maxTokenBorrowsFraction: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the deposit-notional threshold above which a spot market's `initialAssetWeight`
+     * scales down (see `initializeSpotMarket`'s `scaleInitialAssetWeightStart`). Requires warm
+     * admin (`check_warm`). `0` disables scaling.
+     * @param spotMarketIndex - Spot market to update.
+     * @param scaleInitialAssetWeightStart - Deposit-notional threshold, QUOTE_PRECISION (1e6). `0` disables scaling.
+     * @returns Transaction signature.
+     */
     updateSpotMarketScaleInitialAssetWeightStart(spotMarketIndex: number, scaleInitialAssetWeightStart: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketScaleInitialAssetWeightStart` instruction without sending it.
+     * See `updateSpotMarketScaleInitialAssetWeightStart`.
+     * @returns The unsigned `updateSpotMarketScaleInitialAssetWeightStart` instruction.
+     */
     getUpdateSpotMarketScaleInitialAssetWeightStartIx(spotMarketIndex: number, scaleInitialAssetWeightStart: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets how long an insurance-fund staker's unstake request must sit in escrow before it can
+     * be completed for a given spot market. Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market whose insurance fund to update.
+     * @param insuranceWithdrawEscrowPeriod - Unstaking escrow duration, seconds.
+     * @returns Transaction signature.
+     */
     updateInsuranceFundUnstakingPeriod(spotMarketIndex: number, insuranceWithdrawEscrowPeriod: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateInsuranceFundUnstakingPeriod` instruction without sending it. See
+     * `updateInsuranceFundUnstakingPeriod`.
+     * @returns The unsigned `updateInsuranceFundUnstakingPeriod` instruction.
+     */
     getUpdateInsuranceFundUnstakingPeriodIx(spotMarketIndex: number, insuranceWithdrawEscrowPeriod: BN): Promise<TransactionInstruction>;
+    /**
+     * Swaps a perp market's oracle account/source. Requires **cold** admin
+     * (`AdminUpdatePerpMarketOracle`'s `check_cold` constraint) — a lesser admin swapping the
+     * oracle could re-price margin/liquidation math and any `AmmCache`-derived value at will.
+     * On-chain the handler reads both the new and current (`oldOracle`) oracle prices and,
+     * unless `skipInvaraintCheck` is `true`, throws `DefaultError` if the new price is
+     * non-positive or diverges more than 10% from the old one. If the market is present in the
+     * `AmmCache`, its cached fields are refreshed from the new oracle in the same instruction.
+     * @param perpMarketIndex - Perp market to update.
+     * @param oracle - New oracle account.
+     * @param oracleSource - Oracle provider/format for `oracle`.
+     * @param skipInvaraintCheck - If `true`, skips the on-chain non-positive/10%-divergence sanity check against the current oracle price. Default `false`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketOracle(perpMarketIndex: number, oracle: PublicKey, oracleSource: OracleSource, skipInvaraintCheck?: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketOracle` instruction without sending it. See
+     * `updatePerpMarketOracle`. Resolves `oldOracle` from the locally-cached perp market account
+     * (throws if `perpMarketIndex` isn't tracked by the account subscriber) and passes the
+     * program's singleton `AmmCache` PDA.
+     * @returns The unsigned `updatePerpMarketOracle` instruction.
+     */
     getUpdatePerpMarketOracleIx(perpMarketIndex: number, oracle: PublicKey, oracleSource: OracleSource, skipInvaraintCheck?: boolean): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's minimum base-size increment and minimum price increment for orders.
+     * Requires warm admin (`check_warm`). On-chain, throws `DefaultError` unless both are > 0
+     * and `stepSize <= 2_000_000_000` (kept below `i32::MAX` for the LP's remainder-base-asset
+     * accounting).
+     * @param perpMarketIndex - Perp market to update.
+     * @param stepSize - Minimum base-size increment, BASE_PRECISION (1e9).
+     * @param tickSize - Minimum price increment, PRICE_PRECISION (1e6).
+     * @returns Transaction signature.
+     */
     updatePerpMarketStepSizeAndTickSize(perpMarketIndex: number, stepSize: BN, tickSize: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketStepSizeAndTickSize` instruction without sending it. See
+     * `updatePerpMarketStepSizeAndTickSize`.
+     * @returns The unsigned `updatePerpMarketStepSizeAndTickSize` instruction.
+     */
     getUpdatePerpMarketStepSizeAndTickSizeIx(perpMarketIndex: number, stepSize: BN, tickSize: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's minimum order base size (`market.marketStats.minOrderSize`). Requires
+     * warm admin (`check_warm`). On-chain, throws `DefaultError` unless `orderSize > 0`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param orderSize - Minimum base order size, BASE_PRECISION (1e9).
+     * @returns Transaction signature.
+     */
     updatePerpMarketMinOrderSize(perpMarketIndex: number, orderSize: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMinOrderSize` instruction without sending it. See
+     * `updatePerpMarketMinOrderSize`.
+     * @returns The unsigned `updatePerpMarketMinOrderSize` instruction.
+     */
     getUpdatePerpMarketMinOrderSizeIx(perpMarketIndex: number, orderSize: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's minimum base-size increment and minimum price increment for orders.
+     * Requires warm admin (`check_warm`). On-chain, the quote/index-0 market (`marketIndex ===
+     * 0`) is exempt from the `> 0` check other spot markets must satisfy.
+     * @param spotMarketIndex - Spot market to update.
+     * @param stepSize - Minimum base-size increment, market's native token decimals.
+     * @param tickSize - Minimum price increment, PRICE_PRECISION (1e6).
+     * @returns Transaction signature.
+     */
     updateSpotMarketStepSizeAndTickSize(spotMarketIndex: number, stepSize: BN, tickSize: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketStepSizeAndTickSize` instruction without sending it. See
+     * `updateSpotMarketStepSizeAndTickSize`.
+     * @returns The unsigned `updateSpotMarketStepSizeAndTickSize` instruction.
+     */
     getUpdateSpotMarketStepSizeAndTickSizeIx(spotMarketIndex: number, stepSize: BN, tickSize: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's minimum order base size. Requires warm admin (`check_warm`). On-chain,
+     * the quote/index-0 market is exempt from the `> 0` check other spot markets must satisfy.
+     * @param spotMarketIndex - Spot market to update.
+     * @param orderSize - Minimum base order size, market's native token decimals.
+     * @returns Transaction signature.
+     */
     updateSpotMarketMinOrderSize(spotMarketIndex: number, orderSize: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketMinOrderSize` instruction without sending it. See
+     * `updateSpotMarketMinOrderSize`.
+     * @returns The unsigned `updateSpotMarketMinOrderSize` instruction.
+     */
     getUpdateSpotMarketMinOrderSizeIx(spotMarketIndex: number, orderSize: BN): Promise<TransactionInstruction>;
+    /**
+     * Schedules a perp market for expiry: sets `expiryTs` and immediately flips the market to
+     * `MarketStatus.ReduceOnly` (existing positions can only be reduced from this point).
+     * Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if `expiryTs` is not
+     * strictly after the current on-chain clock timestamp. This does not settle or delist the
+     * market — see `settleExpiredMarketPoolsToRevenuePool` for the later teardown step.
+     * @param perpMarketIndex - Perp market to schedule for expiry.
+     * @param expiryTs - Unix timestamp (seconds) after which the market is expired; must be in the future.
+     * @returns Transaction signature.
+     */
     updatePerpMarketExpiry(perpMarketIndex: number, expiryTs: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketExpiry` instruction without sending it. See
+     * `updatePerpMarketExpiry`.
+     * @returns The unsigned `updatePerpMarketExpiry` instruction.
+     */
     getUpdatePerpMarketExpiryIx(perpMarketIndex: number, expiryTs: BN): Promise<TransactionInstruction>;
+    /**
+     * Swaps a spot market's oracle account/source. Requires **cold** admin
+     * (`AdminUpdateSpotMarketOracle`'s `check_cold` constraint) — a lesser admin swapping the
+     * oracle could re-price the withdraw guard threshold notional cap and all margin math at
+     * will. On-chain the handler reads both the new and current (`oldOracle`) oracle prices and,
+     * unless `skipInvaraintCheck` is `true`, throws `DefaultError` if the new price is
+     * non-positive or diverges more than 10% from the old one.
+     * @param spotMarketIndex - Spot market to update.
+     * @param oracle - New oracle account.
+     * @param oracleSource - Oracle provider/format for `oracle`.
+     * @param skipInvaraintCheck - If `true`, skips the on-chain non-positive/10%-divergence sanity check against the current oracle price. Default `false`.
+     * @returns Transaction signature.
+     */
     updateSpotMarketOracle(spotMarketIndex: number, oracle: PublicKey, oracleSource: OracleSource, skipInvaraintCheck?: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketOracle` instruction without sending it. See
+     * `updateSpotMarketOracle`. Resolves `oldOracle` from the locally-cached spot market account
+     * (throws if `spotMarketIndex` isn't tracked by the account subscriber).
+     * @returns The unsigned `updateSpotMarketOracle` instruction.
+     */
     getUpdateSpotMarketOracleIx(spotMarketIndex: number, oracle: PublicKey, oracleSource: OracleSource, skipInvaraintCheck?: boolean): Promise<TransactionInstruction>;
+    /**
+     * Enables or disables limit-order placement/fills on a spot market (`spotMarket.ordersEnabled`).
+     * Requires warm admin (`check_warm`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param ordersEnabled - Whether spot orders are enabled for this market.
+     * @returns Transaction signature.
+     */
     updateSpotMarketOrdersEnabled(spotMarketIndex: number, ordersEnabled: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketOrdersEnabled` instruction without sending it. See
+     * `updateSpotMarketOrdersEnabled`.
+     * @returns The unsigned `updateSpotMarketOrdersEnabled` instruction.
+     */
     getUpdateSpotMarketOrdersEnabledIx(spotMarketIndex: number, ordersEnabled: boolean): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's insurance-fund operation pause bitmask (`InsuranceFundOperation`:
+     * `Init` 0b0001, `Add` 0b0010, `RequestRemove` 0b0100, `Remove` 0b1000). Gated by
+     * `PauseAdminUpdateSpotMarket` — callable by cold, warm, or the dedicated `pause_admin`; a
+     * caller authorized only via `pause_admin` (not warm/cold) may only *add* pause bits, never
+     * clear existing ones (`require_pause_only_added`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param pausedOperations - New `InsuranceFundOperation` bitmask.
+     * @returns Transaction signature.
+     */
     updateSpotMarketIfPausedOperations(spotMarketIndex: number, pausedOperations: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketIfPausedOperations` instruction without sending it. See
+     * `updateSpotMarketIfPausedOperations`.
+     * @returns The unsigned `updateSpotMarketIfPausedOperations` instruction.
+     */
     getUpdateSpotMarketIfPausedOperationsIx(spotMarketIndex: number, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Schedules a spot market for expiry: sets `expiryTs` and immediately flips the market to
+     * `MarketStatus.ReduceOnly`. Requires warm admin (`check_warm`). Throws `DefaultError`
+     * on-chain if `expiryTs` is not strictly after the current on-chain clock timestamp.
+     * @param spotMarketIndex - Spot market to schedule for expiry.
+     * @param expiryTs - Unix timestamp (seconds) after which the market is expired; must be in the future.
+     * @returns Transaction signature.
+     */
     updateSpotMarketExpiry(spotMarketIndex: number, expiryTs: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketExpiry` instruction without sending it. See
+     * `updateSpotMarketExpiry`.
+     * @returns The unsigned `updateSpotMarketExpiry` instruction.
+     */
     getUpdateSpotMarketExpiryIx(spotMarketIndex: number, expiryTs: BN): Promise<TransactionInstruction>;
+    /**
+     * @deprecated The `update_whitelist_mint` instruction handler exists in the Rust
+     * program (`handle_update_whitelist_mint`) but its `#[program]` entry point is
+     * currently commented out in `lib.rs`, so it is absent from the deployed program
+     * and from the generated IDL. Calling this (or `getUpdateWhitelistMintIx`) throws
+     * at runtime — `this.program.instruction` has no `updateWhitelistMint` member —
+     * regardless of the `as any` cast used to bypass the TS type check. Do not call
+     * until the on-chain entry point is re-enabled.
+     * @param whitelistMint - Intended new `state.whitelistMint` (unused while dead).
+     * @returns Transaction signature (never reached).
+     */
     updateWhitelistMint(whitelistMint?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @deprecated See `updateWhitelistMint` — the underlying `update_whitelist_mint`
+     * instruction is not wired up on-chain and is missing from the IDL; this throws
+     * at runtime.
+     * @returns Never resolves successfully.
+     */
     getUpdateWhitelistMintIx(whitelistMint?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Sets `state.discountMint` — a token that grants trade-fee discounts to holders
+     * (checked against the `FeeTier` discount rules at fill time). Requires warm admin
+     * (`check_warm`).
+     * @param discountMint - New discount-token mint.
+     * @returns Transaction signature.
+     */
     updateDiscountMint(discountMint: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateDiscountMint` instruction without sending it. See
+     * `updateDiscountMint`.
+     * @returns The unsigned `updateDiscountMint` instruction.
+     */
     getUpdateDiscountMintIx(discountMint: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's deposit/borrow margin weights and IMF factor. Requires warm admin
+     * (`check_warm`). On-chain, `validate_margin_weights` enforces the standard invariants
+     * (asset weights <= SPOT_WEIGHT_PRECISION, liability weights >= SPOT_WEIGHT_PRECISION,
+     * initial at least as conservative as maintenance, and consistency with `imfFactor`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param initialAssetWeight - Initial (deposit) asset weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param maintenanceAssetWeight - Maintenance asset weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param initialLiabilityWeight - Initial (borrow) liability weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param maintenanceLiabilityWeight - Maintenance liability weight, SPOT_WEIGHT_PRECISION (1e4).
+     * @param imfFactor - Increases weight penalty as position size grows, SPOT_IMF_PRECISION (1e6). Default 0.
+     * @returns Transaction signature.
+     */
     updateSpotMarketMarginWeights(spotMarketIndex: number, initialAssetWeight: number, maintenanceAssetWeight: number, initialLiabilityWeight: number, maintenanceLiabilityWeight: number, imfFactor?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketMarginWeights` instruction without sending it. See
+     * `updateSpotMarketMarginWeights`.
+     * @returns The unsigned `updateSpotMarketMarginWeights` instruction.
+     */
     getUpdateSpotMarketMarginWeightsIx(spotMarketIndex: number, initialAssetWeight: number, maintenanceAssetWeight: number, initialLiabilityWeight: number, maintenanceLiabilityWeight: number, imfFactor?: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's interest-rate curve: the utilization/rate kink plus the max rate at
+     * 100% utilization. Requires warm admin (`check_warm`). On-chain, `validate_borrow_rate`
+     * checks the curve is well-formed (kink within bounds, rates monotonically increasing,
+     * `min_borrow_rate` at or below `optimal_borrow_rate`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param optimalUtilization - Utilization at the borrow-rate kink, SPOT_UTILIZATION_PRECISION (1e6, 100% = 1e6).
+     * @param optimalBorrowRate - Borrow rate at `optimalUtilization`, SPOT_RATE_PRECISION (1e6, 100% APR = 1e6).
+     * @param optimalMaxRate - Borrow rate at 100% utilization, SPOT_RATE_PRECISION (1e6).
+     * @param minBorrowRate - Floor borrow rate at 0% utilization, in units of 0.5% (i.e. `SPOT_RATE_PRECISION / 200` per unit); omit to leave `spotMarket.minBorrowRate` unchanged.
+     * @returns Transaction signature.
+     */
     updateSpotMarketBorrowRate(spotMarketIndex: number, optimalUtilization: number, optimalBorrowRate: number, optimalMaxRate: number, minBorrowRate?: number | undefined): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketBorrowRate` instruction without sending it. See
+     * `updateSpotMarketBorrowRate`.
+     * @returns The unsigned `updateSpotMarketBorrowRate` instruction.
+     */
     getUpdateSpotMarketBorrowRateIx(spotMarketIndex: number, optimalUtilization: number, optimalBorrowRate: number, optimalMaxRate: number, minBorrowRate?: number | undefined): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's `AssetTier` (collateral-usability gate for cross-margin). Requires
+     * warm admin (`check_warm`). On-chain, if `spotMarket.initialAssetWeight > 0` (the market is
+     * currently usable as collateral), the new tier must be `AssetTier.COLLATERAL` or
+     * `AssetTier.PROTECTED` — otherwise it throws `DefaultError`; zero the initial asset weight
+     * first to move a market to a lesser tier.
+     * @param spotMarketIndex - Spot market to update.
+     * @param assetTier - New asset tier.
+     * @returns Transaction signature.
+     */
     updateSpotMarketAssetTier(spotMarketIndex: number, assetTier: AssetTier): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketAssetTier` instruction without sending it. See
+     * `updateSpotMarketAssetTier`.
+     * @returns The unsigned `updateSpotMarketAssetTier` instruction.
+     */
     getUpdateSpotMarketAssetTierIx(spotMarketIndex: number, assetTier: AssetTier): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's `MarketStatus` directly. Requires warm admin (`check_warm`). Unlike
+     * `updatePerpMarketStatus`, the spot handler applies no restriction on the target status —
+     * `Delisted`/`Settlement` can be set here directly (there is no separate spot
+     * settlement-teardown instruction).
+     * @param spotMarketIndex - Spot market to update.
+     * @param marketStatus - New market status.
+     * @returns Transaction signature.
+     */
     updateSpotMarketStatus(spotMarketIndex: number, marketStatus: MarketStatus): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketStatus` instruction without sending it. See
+     * `updateSpotMarketStatus`.
+     * @returns The unsigned `updateSpotMarketStatus` instruction.
+     */
     getUpdateSpotMarketStatusIx(spotMarketIndex: number, marketStatus: MarketStatus): Promise<TransactionInstruction>;
+    /**
+     * Sets a spot market's operation pause bitmask (`SpotOperation`: `UpdateCumulativeInterest`
+     * 0b00001, `Fill` 0b00010, `Deposit` 0b00100, `Withdraw` 0b01000, `Liquidation` 0b10000).
+     * Gated by `PauseAdminUpdateSpotMarket` — callable by cold, warm, or the dedicated
+     * `pause_admin`; a caller authorized only via `pause_admin` may only *add* pause bits, never
+     * clear existing ones (`require_pause_only_added`).
+     * @param spotMarketIndex - Spot market to update.
+     * @param pausedOperations - New `SpotOperation` bitmask.
+     * @returns Transaction signature.
+     */
     updateSpotMarketPausedOperations(spotMarketIndex: number, pausedOperations: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketPausedOperations` instruction without sending it. See
+     * `updateSpotMarketPausedOperations`.
+     * @returns The unsigned `updateSpotMarketPausedOperations` instruction.
+     */
     getUpdateSpotMarketPausedOperationsIx(spotMarketIndex: number, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's `MarketStatus` directly. Requires warm admin (`check_warm`). On-chain,
+     * throws `DefaultError` if the target status is `Delisted` or `Settlement` — those are only
+     * reached through the market-expiry lifecycle (`updatePerpMarketExpiry` -> `ReduceOnly`,
+     * then the keeper's `settleExpiredMarket` -> `Settlement`, then
+     * `settleExpiredMarketPoolsToRevenuePool` -> `Delisted`), never set directly here.
+     * @param perpMarketIndex - Perp market to update.
+     * @param marketStatus - New market status; must not be `Delisted` or `Settlement`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketStatus(perpMarketIndex: number, marketStatus: MarketStatus): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketStatus` instruction without sending it. See
+     * `updatePerpMarketStatus`.
+     * @returns The unsigned `updatePerpMarketStatus` instruction.
+     */
     getUpdatePerpMarketStatusIx(perpMarketIndex: number, marketStatus: MarketStatus): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's operation pause bitmask (`PerpOperation`: `UpdateFunding` 0b00000001,
+     * `AmmFill` 0b00000010, `Fill` 0b00000100, `SettlePnl` 0b00001000, `SettlePnlWithPosition`
+     * 0b00010000, `Liquidation` 0b00100000, `AmmImmediateFill` 0b01000000, `SettleRevPool`
+     * 0b10000000). Gated by `PauseAdminUpdatePerpMarket` — callable by cold, warm, or the
+     * dedicated `pause_admin`. Authority matrix on-chain: **cold** may set any value; **warm**
+     * may only flip the `UpdateFunding` / `SettleRevPool` bits, all others must be preserved
+     * (throws `DefaultError` otherwise); **pause_admin** may set any bit but only *add* pause
+     * bits, never clear them (`require_pause_only_added`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param pausedOperations - New `PerpOperation` bitmask.
+     * @returns Transaction signature.
+     */
     updatePerpMarketPausedOperations(perpMarketIndex: number, pausedOperations: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketPausedOperations` instruction without sending it. See
+     * `updatePerpMarketPausedOperations`.
+     * @returns The unsigned `updatePerpMarketPausedOperations` instruction.
+     */
     getUpdatePerpMarketPausedOperationsIx(perpMarketIndex: number, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's `ContractTier` (risk/collateral classification). Requires warm admin
+     * (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param contractTier - New contract tier.
+     * @returns Transaction signature.
+     */
     updatePerpMarketContractTier(perpMarketIndex: number, contractTier: ContractTier): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketContractTier` instruction without sending it. See
+     * `updatePerpMarketContractTier`.
+     * @returns The unsigned `updatePerpMarketContractTier` instruction.
+     */
     getUpdatePerpMarketContractTierIx(perpMarketIndex: number, contractTier: ContractTier): Promise<TransactionInstruction>;
+    /**
+     * Sets `state.exchangeStatus`, the protocol-wide pause bitmask (`ExchangeStatus`).
+     * Reachable by cold, warm, or `pauseAdmin` (`PauseAdminUpdateState`'s
+     * `check_pause`), but the handler enforces `require_pause_only_added`: a caller
+     * authorised only via `pauseAdmin` (not warm/cold) may add pause bits but never
+     * clear one — cold/warm can set any value, including unpausing. The `admin`
+     * account below defaults to `coldAdmin`; a pause-admin-only caller must override it
+     * with their own pubkey.
+     * @param exchangeStatus - New pause bitmask, `ExchangeStatus` (bit values; `PAUSED` = 255 pauses everything).
+     * @returns Transaction signature.
+     */
     updateExchangeStatus(exchangeStatus: ExchangeStatus): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateExchangeStatus` instruction without sending it. See
+     * `updateExchangeStatus`.
+     * @returns The unsigned `updateExchangeStatus` instruction.
+     */
     getUpdateExchangeStatusIx(exchangeStatus: ExchangeStatus): Promise<TransactionInstruction>;
+    /**
+     * Sets `state.solvencyStatus` (`SolvencyStatus`), gating internal solvency-repair
+     * flows (bankruptcy / pnl-deficit resolution) independently of
+     * `ExchangeStatus.WITHDRAW_PAUSED`. Cold-only — unlike `updateExchangeStatus`, the
+     * `ColdAdminUpdateState` context accepts only `state.coldAdmin`; there is no
+     * pause-admin or warm-admin path and no bit-add-only restriction.
+     * @param solvencyStatus - New bitmask, `SolvencyStatus` (currently one bit: `SOLVENCY_REPAIR_PAUSED`).
+     * @returns Transaction signature.
+     */
     updateSolvencyStatus(solvencyStatus: SolvencyStatus): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSolvencyStatus` instruction without sending it. See
+     * `updateSolvencyStatus`.
+     * @returns The unsigned `updateSolvencyStatus` instruction.
+     */
     getUpdateSolvencyStatusIx(solvencyStatus: SolvencyStatus): Promise<TransactionInstruction>;
+    /**
+     * Sets the protocol-wide default minimum perp-order auction duration
+     * (`state.minPerpAuctionDuration`) — orders placed without an explicit longer
+     * auction fall back to this floor. Requires warm admin (`check_warm`).
+     * @param minDuration - Minimum auction duration, slots.
+     * @returns Transaction signature.
+     */
     updatePerpAuctionDuration(minDuration: BN | number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpAuctionDuration` instruction without sending it. See
+     * `updatePerpAuctionDuration`.
+     * @returns The unsigned `updatePerpAuctionDuration` instruction.
+     */
     getUpdatePerpAuctionDurationIx(minDuration: BN | number): Promise<TransactionInstruction>;
+    /**
+     * Sets the protocol-wide default spot-order auction duration
+     * (`state.defaultSpotAuctionDuration`). Requires warm admin (`check_warm`).
+     * @param defaultAuctionDuration - Default auction duration, slots.
+     * @returns Transaction signature.
+     */
     updateSpotAuctionDuration(defaultAuctionDuration: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotAuctionDuration` instruction without sending it. See
+     * `updateSpotAuctionDuration`.
+     * @returns The unsigned `updateSpotAuctionDuration` instruction.
+     */
     getUpdateSpotAuctionDurationIx(defaultAuctionDuration: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the fraction of a perp market's AMM base reserve a single fill may consume
+     * (`amm.maxFillReserveFraction`; a single fill is capped at
+     * `baseAssetReserve / maxFillReserveFraction`, further bounded by half the AMM's
+     * per-side available liquidity). Requires warm admin (`check_warm`). Throws `DefaultError`
+     * on-chain if `maxBaseAssetAmountRatio` is 0. Smaller values allow larger single fills.
+     * @param perpMarketIndex - Perp market to update.
+     * @param maxBaseAssetAmountRatio - Divisor applied to `baseAssetReserve` to cap a single fill's size; must be > 0.
+     * @returns Transaction signature.
+     */
     updatePerpMarketMaxFillReserveFraction(perpMarketIndex: number, maxBaseAssetAmountRatio: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMaxFillReserveFraction` instruction without sending it. See
+     * `updatePerpMarketMaxFillReserveFraction`.
+     * @returns The unsigned `updatePerpMarketMaxFillReserveFraction` instruction.
+     */
     getUpdatePerpMarketMaxFillReserveFractionIx(perpMarketIndex: number, maxBaseAssetAmountRatio: number): Promise<TransactionInstruction>;
+    /**
+     * **Currently broken and a dead config knob even if fixed.** Intended to set a perp market's
+     * `amm.maxSlippageRatio` (on-chain default 50, i.e. ~2% per the seed comment in
+     * `initializePerpMarket`'s default config) — but `getUpdateMaxSlippageRatioIx` calls
+     * `this.program.instruction.updateMaxSlippageRatio` (cast to `any` to bypass the missing
+     * type); the actual on-chain/IDL instruction is named `updatePerpMarketMaxSlippageRatio`, so
+     * this throws at runtime (`... is not a function`). Separately, even the correctly-named
+     * instruction's target field, `amm.maxSlippageRatio`, is not read by any fill/slippage-check
+     * path in the program — it is write-only. Requires warm admin (`check_warm`) on the
+     * `update_perp_market_max_slippage_ratio` handler.
+     * @param perpMarketIndex - Perp market that would be updated.
+     * @param maxSlippageRatio - Intended `amm.maxSlippageRatio` value, unitless (would validate `> 0`).
+     * @returns Transaction signature (in practice: throws before a transaction is built).
+     */
     updateMaxSlippageRatio(perpMarketIndex: number, maxSlippageRatio: number): Promise<TransactionSignature>;
+    /**
+     * Builds the (currently broken) `updateMaxSlippageRatio` instruction. See
+     * `updateMaxSlippageRatio` — this throws because the program has no `updateMaxSlippageRatio`
+     * instruction (the real name is `updatePerpMarketMaxSlippageRatio`). Throws if
+     * `perpMarketIndex` isn't tracked by the local account subscriber, before it even reaches
+     * the bad instruction-name call.
+     * @returns Never resolves successfully; throws when the missing instruction is invoked.
+     */
     getUpdateMaxSlippageRatioIx(perpMarketIndex: number, maxSlippageRatio: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the asset weights applied to a user's unrealized (unsettled) perp PnL when it counts
+     * toward free collateral. Requires warm admin (`check_warm`). On-chain, both weights must be
+     * <= SPOT_WEIGHT_PRECISION and `unrealizedInitialAssetWeight <= unrealizedMaintenanceAssetWeight`,
+     * or the handler throws `DefaultError`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param unrealizedInitialAssetWeight - Initial-margin weight on unrealized PnL, SPOT_WEIGHT_PRECISION (1e4).
+     * @param unrealizedMaintenanceAssetWeight - Maintenance-margin weight on unrealized PnL, SPOT_WEIGHT_PRECISION (1e4). Must be >= the initial weight.
+     * @returns Transaction signature.
+     */
     updatePerpMarketUnrealizedAssetWeight(perpMarketIndex: number, unrealizedInitialAssetWeight: number, unrealizedMaintenanceAssetWeight: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketUnrealizedAssetWeight` instruction without sending it. See
+     * `updatePerpMarketUnrealizedAssetWeight`.
+     * @returns The unsigned `updatePerpMarketUnrealizedAssetWeight` instruction.
+     */
     getUpdatePerpMarketUnrealizedAssetWeightIx(perpMarketIndex: number, unrealizedInitialAssetWeight: number, unrealizedMaintenanceAssetWeight: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's insurance/revenue-pool caps. Requires warm admin (`check_warm`).
+     * On-chain, all three are bounded by the tier-specific `INSURANCE_{A,B,C,SPECULATIVE}_MAX`
+     * constant for the market's current `contractTier` (`maxRevenueWithdrawPerPeriod` may
+     * alternatively be as large as `FEE_POOL_TO_REVENUE_POOL_THRESHOLD` if that's bigger than
+     * the tier max), and `quoteMaxInsurance` must be >= the market's already-settled insurance
+     * claim — violating either throws `DefaultError`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param unrealizedMaxImbalance - Cap on unrealized-PnL imbalance eligible for insurance backing, QUOTE_PRECISION (1e6).
+     * @param maxRevenueWithdrawPerPeriod - Cap on revenue-pool withdrawals per settlement period, QUOTE_PRECISION (1e6).
+     * @param quoteMaxInsurance - Lifetime cap on insurance draws for this market, QUOTE_PRECISION (1e6). Must be >= the market's already-settled insurance claim.
+     * @returns Transaction signature.
+     */
     updatePerpMarketMaxImbalances(perpMarketIndex: number, unrealizedMaxImbalance: BN, maxRevenueWithdrawPerPeriod: BN, quoteMaxInsurance: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMaxImbalances` instruction without sending it. See
+     * `updatePerpMarketMaxImbalances`.
+     * @returns The unsigned `updatePerpMarketMaxImbalances` instruction.
+     */
     getUpdatePerpMarketMaxImbalancesIx(perpMarketIndex: number, unrealizedMaxImbalance: BN, maxRevenueWithdrawPerPeriod: BN, quoteMaxInsurance: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's open-interest cap. Requires warm admin (`check_warm`). Throws
+     * `DefaultError` on-chain unless `maxOpenInterest` is an exact multiple of the market's
+     * `orderStepSize`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param maxOpenInterest - Cap on base-asset open interest, BASE_PRECISION (1e9). Must be a multiple of `orderStepSize`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketMaxOpenInterest(perpMarketIndex: number, maxOpenInterest: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketMaxOpenInterest` instruction without sending it. See
+     * `updatePerpMarketMaxOpenInterest`.
+     * @returns The unsigned `updatePerpMarketMaxOpenInterest` instruction.
+     */
     getUpdatePerpMarketMaxOpenInterestIx(perpMarketIndex: number, maxOpenInterest: BN): Promise<TransactionInstruction>;
+    /**
+     * Directly overwrites a perp market's user-count counters (`numberOfUsers` /
+     * `numberOfUsersWithBase`), used to correct drift from the incrementally-maintained
+     * counters. Requires warm admin (`check_warm`). Either counter can be omitted to leave it
+     * unchanged. On-chain, throws `DefaultError` if the resulting `numberOfUsers <
+     * numberOfUsersWithBase`.
+     * @param perpMarketIndex - Perp market to update.
+     * @param numberOfUsers - New total open-position-or-order user count. Omit to leave unchanged.
+     * @param numberOfUsersWithBase - New count of users with a nonzero base position. Omit to leave unchanged. Must not exceed `numberOfUsers`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketNumberOfUser(perpMarketIndex: number, numberOfUsers?: number, numberOfUsersWithBase?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketNumberOfUsers` instruction without sending it. See
+     * `updatePerpMarketNumberOfUser`.
+     * @returns The unsigned `updatePerpMarketNumberOfUsers` instruction.
+     */
     getUpdatePerpMarketNumberOfUsersIx(perpMarketIndex: number, numberOfUsers?: number, numberOfUsersWithBase?: number): Promise<TransactionInstruction>;
+    /**
+     * Scales a perp market's taker fee and maker rebate up or down by a percentage of the base
+     * fee tier. Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if
+     * `abs(feeAdjustment) > FEE_ADJUSTMENT_MAX` (100).
+     * @param perpMarketIndex - Perp market to update.
+     * @param feeAdjustment - Percent adjustment applied to the base taker fee / maker rebate, -100..100 (negative reduces, positive increases; 0 = no adjustment).
+     * @returns Transaction signature.
+     */
     updatePerpMarketFeeAdjustment(perpMarketIndex: number, feeAdjustment: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketFeeAdjustment` instruction without sending it. See
+     * `updatePerpMarketFeeAdjustment`.
+     * @returns The unsigned `updatePerpMarketFeeAdjustment` instruction.
+     */
     getUpdatePerpMarketFeeAdjustmentIx(perpMarketIndex: number, feeAdjustment: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the retention buffer the streaming fee sweep leaves in a perp market's pnl pool on top
+     * of `max(netUserPnl, 0)` before the IF/AMM-provision drains take their cut (the protocol
+     * drain is exempt and always runs). Requires warm admin (`check_warm`). See
+     * `perp_market.fee_pool_buffer_target`'s doc comment for why the buffer exists (a swept pool
+     * is short on the next adverse oracle tick, and sweeps are a one-way valve).
+     * @param perpMarketIndex - Perp market to update.
+     * @param feePoolBufferTarget - Pnl-pool retention buffer, QUOTE_PRECISION (1e6).
+     * @returns Transaction signature.
+     */
     updatePerpMarketFeePoolBufferTarget(perpMarketIndex: number, feePoolBufferTarget: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketFeePoolBufferTarget` instruction without sending it. See
+     * `updatePerpMarketFeePoolBufferTarget`.
+     * @returns The unsigned `updatePerpMarketFeePoolBufferTarget` instruction.
+     */
     getUpdatePerpMarketFeePoolBufferTargetIx(perpMarketIndex: number, feePoolBufferTarget: BN): Promise<TransactionInstruction>;
+    /**
+     * Scales a spot market's taker fee and maker rebate up or down by a percentage of the base
+     * fee tier. Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if
+     * `abs(feeAdjustment) > FEE_ADJUSTMENT_MAX` (100). Note: the first parameter is a **spot**
+     * market index despite being named `perpMarketIndex` here.
+     * @param perpMarketIndex - Spot market index to update (misnamed; not a perp market index).
+     * @param feeAdjustment - Percent adjustment applied to the base taker fee / maker rebate, -100..100 (negative reduces, positive increases; 0 = no adjustment).
+     * @returns Transaction signature.
+     */
     updateSpotMarketFeeAdjustment(perpMarketIndex: number, feeAdjustment: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketFeeAdjustment` instruction without sending it. See
+     * `updateSpotMarketFeeAdjustment`.
+     * @returns The unsigned `updateSpotMarketFeeAdjustment` instruction.
+     */
     getUpdateSpotMarketFeeAdjustmentIx(spotMarketIndex: number, feeAdjustment: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the three-way split of a perp market's liquidation fee: the cut paid to the
+     * liquidator, the cut routed to the insurance fund, and the cut kept by the protocol.
+     * Requires warm admin (`check_warm`). On-chain, throws `DefaultError` unless
+     * `liquidatorFee + ifLiquidationFee + protocolLiquidationFee < LIQUIDATION_FEE_PRECISION`,
+     * `ifLiquidationFee < LIQUIDATION_FEE_PRECISION`, and `protocolLiquidationFee <=
+     * LIQUIDATION_FEE_PRECISION / 10` (10%); also re-validates `liquidatorFee` against the
+     * market's current margin ratios (`amm.validate_compatible_with_liquidation_fee`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param liquidatorFee - Fee paid to the liquidator, LIQUIDATION_FEE_PRECISION (1e6).
+     * @param ifLiquidationFee - Portion routed to the insurance fund, LIQUIDATION_FEE_PRECISION (1e6).
+     * @param protocolLiquidationFee - Portion kept by the protocol, LIQUIDATION_FEE_PRECISION (1e6). Max 10% of precision. Default 0.
+     * @returns Transaction signature.
+     */
     updatePerpMarketLiquidationFee(perpMarketIndex: number, liquidatorFee: number, ifLiquidationFee: number, protocolLiquidationFee?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketLiquidationFee` instruction without sending it. See
+     * `updatePerpMarketLiquidationFee`.
+     * @returns The unsigned `updatePerpMarketLiquidationFee` instruction.
+     */
     getUpdatePerpMarketLiquidationFeeIx(perpMarketIndex: number, liquidatorFee: number, ifLiquidationFee: number, protocolLiquidationFee?: number): Promise<TransactionInstruction>;
+    /**
+     * Sets the three-way split of a spot market's liquidation fee: the cut paid to the
+     * liquidator, the cut routed to the insurance fund, and the cut kept by the protocol.
+     * Requires warm admin (`check_warm`). On-chain, throws `DefaultError` unless
+     * `liquidatorFee + ifLiquidationFee + protocolLiquidationFee < LIQUIDATION_FEE_PRECISION`,
+     * and both `ifLiquidationFee` and `protocolLiquidationFee` are each
+     * <= `LIQUIDATION_FEE_PRECISION / 10` (10%).
+     * @param spotMarketIndex - Spot market to update.
+     * @param liquidatorFee - Fee paid to the liquidator, LIQUIDATION_FEE_PRECISION (1e6).
+     * @param ifLiquidationFee - Portion routed to the insurance fund, LIQUIDATION_FEE_PRECISION (1e6). Max 10% of precision.
+     * @param protocolLiquidationFee - Portion kept by the protocol, LIQUIDATION_FEE_PRECISION (1e6). Max 10% of precision. Default 0.
+     * @returns Transaction signature.
+     */
     updateSpotMarketLiquidationFee(spotMarketIndex: number, liquidatorFee: number, ifLiquidationFee: number, protocolLiquidationFee?: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpotMarketLiquidationFee` instruction without sending it. See
+     * `updateSpotMarketLiquidationFee`.
+     * @returns The unsigned `updateSpotMarketLiquidationFee` instruction.
+     */
     getUpdateSpotMarketLiquidationFeeIx(spotMarketIndex: number, liquidatorFee: number, ifLiquidationFee: number, protocolLiquidationFee?: number): Promise<TransactionInstruction>;
+    /**
+     * Cold-only. Sets the treasury pubkey that `withdrawProtocolFeesPerp` /
+     * `withdrawProtocolFeesSpot` pay out to. Perp (quote-denominated) and spot
+     * (per-market-token) recipients are independent — `marketType` selects which one
+     * this call updates. Withdrawals for a market type are inert (the fee-withdraw ix
+     * always fails) until its recipient is set to a non-default pubkey.
+     * @param protocolFeeRecipient - New recipient wallet; its ATA (per mint) receives future withdrawals.
+     * @param marketType - Which recipient slot to update, `MarketType.PERP` or `MarketType.SPOT`.
+     * @returns Transaction signature.
+     */
     updateProtocolFeeRecipient(protocolFeeRecipient: PublicKey, marketType: MarketType): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateProtocolFeeRecipient` instruction without sending it. See
+     * `updateProtocolFeeRecipient`.
+     * @returns The unsigned `updateProtocolFeeRecipient` instruction.
+     */
     getUpdateProtocolFeeRecipientIx(protocolFeeRecipient: PublicKey, marketType: MarketType): Promise<TransactionInstruction>;
+    /**
+     * Withdraws a spot market's accrued protocol fees (lending-interest + spot-liquidation
+     * carveouts, tracked in `spotMarket.protocolFeePool`) from its vault to
+     * `state.protocolFeeRecipientSpot`'s ATA. Requires `HotRole.FeeWithdraw` (cold, warm,
+     * or the configured fee-withdraw hot key) — `this.wallet` must hold that role, since
+     * `getWithdrawProtocolFeesSpotIx` signs as `this.wallet.publicKey` for both `payer`
+     * and `authority`. The recipient ATA is created (`init_if_needed`) if missing. The
+     * withdrawn amount is capped at whatever is actually available, and the vault must
+     * still fully cover depositor backing afterward or the instruction fails.
+     * @param marketIndex - Spot market to withdraw protocol fees from.
+     * @param amount - Requested amount, the market's native token decimals (clamped down to the available balance on-chain).
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
     withdrawProtocolFeesSpot(marketIndex: number, amount: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `withdrawProtocolFeesSpot` instruction without sending it. Also wires
+     * up transfer-hook remaining accounts if the market's mint requires them. See
+     * `withdrawProtocolFeesSpot`.
+     * @returns The unsigned `withdrawProtocolFeesSpot` instruction.
+     */
     getWithdrawProtocolFeesSpotIx(marketIndex: number, amount: BN): Promise<TransactionInstruction>;
+    /**
+     * Withdraws a perp market's accrued protocol fees (quote-denominated, tracked in
+     * `perpMarket.protocolFeePool`) from the quote spot market's vault to
+     * `state.protocolFeeRecipientPerp`'s ATA. Requires `HotRole.FeeWithdraw` — see
+     * `withdrawProtocolFeesSpot` for the same signer/ATA/clamping/vault-invariant
+     * behavior (this mirrors it against the perp market's quote-denominated pool
+     * instead of a spot market's own token).
+     * @param marketIndex - Perp market to withdraw protocol fees from.
+     * @param amount - Requested amount, QUOTE_PRECISION (1e6) (clamped down to the available balance on-chain).
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
     withdrawProtocolFeesPerp(marketIndex: number, amount: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `withdrawProtocolFeesPerp` instruction without sending it. Also wires
+     * up transfer-hook remaining accounts if the quote market's mint requires them. See
+     * `withdrawProtocolFeesPerp`.
+     * @returns The unsigned `withdrawProtocolFeesPerp` instruction.
+     */
     getWithdrawProtocolFeesPerpIx(marketIndex: number, amount: BN): Promise<TransactionInstruction>;
+    /**
+     * Creates a market-local synthetic "oracle" account (`PrelaunchOracle`) for a perp market
+     * that has no real price feed yet (e.g. a pre-launch/pre-listing market), seeded with an
+     * admin-supplied price. Requires warm admin (`check_warm`). Set the market's `oracle` to
+     * this account's address (via `updatePerpMarketOracle`, with a matching `OracleSource`) to
+     * use it. `PrelaunchOracle::validate` runs at the end of the handler and throws
+     * `InvalidOracle` if `price` or `maxPrice` end up `0` (both are zero-initialized and only
+     * set when the corresponding argument is provided) or if `price > maxPrice` — in practice
+     * both must be supplied and satisfy `price <= maxPrice`.
+     * @param perpMarketIndex - Perp market this oracle backs; fixes the PDA seed.
+     * @param price - Initial synthetic price, PRICE_PRECISION (1e6). Must be nonzero and <= `maxPrice`.
+     * @param maxPrice - Ceiling the price is allowed to move to, PRICE_PRECISION (1e6). Must be nonzero and >= `price`.
+     * @returns Transaction signature.
+     */
     initializePrelaunchOracle(perpMarketIndex: number, price?: BN, maxPrice?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializePrelaunchOracle` instruction without sending it. See
+     * `initializePrelaunchOracle`.
+     * @returns The unsigned `initializePrelaunchOracle` instruction.
+     */
     getInitializePrelaunchOracleIx(perpMarketIndex: number, price?: BN, maxPrice?: BN): Promise<TransactionInstruction>;
+    /**
+     * Updates a perp market's `PrelaunchOracle` price and/or ceiling. Requires warm admin
+     * (`check_warm`). If `price` is provided, this **also directly overwrites the perp market's
+     * mark-price TWAPs** (`lastMarkPriceTwap`, `lastMarkPriceTwap5min`, and clamps
+     * `lastBidPriceTwap`/`lastAskPriceTwap` toward the new price) and their timestamp — a much
+     * broader side effect than the field name suggests. `PrelaunchOracle::validate` re-runs at
+     * the end and throws `InvalidOracle` if the resulting `price`/`maxPrice` are `0` or
+     * `price > maxPrice`. Either argument omitted leaves that field (and, for `price`, the TWAPs)
+     * unchanged.
+     * @param perpMarketIndex - Perp market whose prelaunch oracle to update.
+     * @param price - New synthetic price, PRICE_PRECISION (1e6). Also overwrites the market's mark-price TWAPs when provided. Omit to leave unchanged.
+     * @param maxPrice - New price ceiling, PRICE_PRECISION (1e6). Omit to leave unchanged.
+     * @returns Transaction signature.
+     */
     updatePrelaunchOracleParams(perpMarketIndex: number, price?: BN, maxPrice?: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePrelaunchOracleParams` instruction without sending it. See
+     * `updatePrelaunchOracleParams`.
+     * @returns The unsigned `updatePrelaunchOracleParams` instruction.
+     */
     getUpdatePrelaunchOracleParamsIx(perpMarketIndex: number, price?: BN, maxPrice?: BN): Promise<TransactionInstruction>;
+    /**
+     * Closes a perp market's `PrelaunchOracle` account and refunds rent to the admin. Requires
+     * warm admin (`check_warm`). On-chain, throws `DefaultError` if the oracle is still the
+     * market's active `oracle` — repoint the market to a different oracle first (via
+     * `updatePerpMarketOracle`).
+     *
+     * **Currently broken**: `getDeletePrelaunchOracleIx` builds a `PrelaunchOracleParams`-shaped
+     * object (`{ perpMarketIndex, price, maxPrice }`) as the instruction argument, but the
+     * on-chain `deletePrelaunchOracle` instruction (and its IDL) takes a single `u16`
+     * `perpMarketIndex` scalar, not that object — this throws when the Borsh encoder tries to
+     * serialize an object where a `u16` is expected.
+     * @param perpMarketIndex - Perp market whose prelaunch oracle to delete; must not be the market's current oracle.
+     * @returns Transaction signature (in practice: throws before a transaction is built).
+     */
     deletePrelaunchOracle(perpMarketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the (currently broken) `deletePrelaunchOracle` instruction. See
+     * `deletePrelaunchOracle` — throws because the argument shape doesn't match the IDL's `u16`.
+     * `price`/`maxPrice` are accepted but unused; the underlying call never reads them.
+     * @returns Never resolves successfully; throws when the malformed instruction args are encoded.
+     */
     getDeletePrelaunchOracleIx(perpMarketIndex: number, price?: BN, maxPrice?: BN): Promise<TransactionInstruction>;
+    /**
+     * Overrides how many slots of oracle delay a perp market tolerates before its "low-risk"
+     * oracle-staleness check (`OracleValidity`'s `is_stale_for_amm_low_risk`, consumed by margin
+     * calculations, order fills, AMM repeg/refresh, and the AMM cache) trips. Gated on
+     * `HotAdminUpdatePerpMarket`, whose account constraint is actually `check_warm` — this
+     * requires **warm** admin (or cold), not a dedicated hot key, despite the struct's name.
+     * `0` (the default) means no override — the market falls back to the global
+     * `state.oracleGuardRails.validity.slotsBeforeStaleForAmm`; a nonzero value is clamped to
+     * `>= 0` and used as the slot threshold directly.
+     * @param perpMarketIndex - Perp market to update.
+     * @param oracleLowRiskSlotDelayOverride - Slots of oracle delay tolerated for low-risk AMM actions before staleness trips. `0` = use the global default; negative values are treated as `0`.
+     * @returns Transaction signature.
+     */
     updatePerpMarketOracleLowRiskSlotDelayOverride(perpMarketIndex: number, oracleLowRiskSlotDelayOverride: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketOracleLowRiskSlotDelayOverride` instruction without sending it.
+     * See `updatePerpMarketOracleLowRiskSlotDelayOverride`.
+     * @returns The unsigned `updatePerpMarketOracleLowRiskSlotDelayOverride` instruction.
+     */
     getUpdatePerpMarketOracleLowRiskSlotDelayOverrideIx(perpMarketIndex: number, oracleLowRiskSlotDelayOverride: number): Promise<TransactionInstruction>;
+    /**
+     * Overrides how many slots of oracle delay a perp market tolerates before its "immediate"
+     * per-fill staleness check trips (used for AMM-immediate fills; the on-chain field is
+     * `perpMarket.oracleSlotDelayOverride`, default `-1`). Gated on `HotAdminUpdatePerpMarket`,
+     * whose account constraint is actually `check_warm` — this requires **warm** admin (or
+     * cold), not a dedicated hot key. `0` means the market is always treated as stale for
+     * immediate AMM actions; any other value is clamped to `>= 0` and used as the slot threshold
+     * (delay > threshold is stale).
+     * @param perpMarketIndex - Perp market to update.
+     * @param oracleSlotDelay - Slots of oracle delay tolerated before the immediate-fill staleness check trips. `0` = always stale; negative input is clamped to `0` on-chain.
+     * @returns Transaction signature.
+     */
     updatePerpMarketOracleSlotDelayOverride(perpMarketIndex: number, oracleSlotDelay: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketOracleSlotDelayOverride` instruction without sending it. See
+     * `updatePerpMarketOracleSlotDelayOverride`.
+     * @returns The unsigned `updatePerpMarketOracleSlotDelayOverride` instruction.
+     */
     getUpdatePerpMarketOracleSlotDelayOverrideIx(perpMarketIndex: number, oracleSlotDelay: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's manual spread-widening scalars. Gated on `HotAdminUpdatePerpMarket`,
+     * whose account constraint is actually `check_warm` — this requires **warm** admin (or
+     * cold), not a dedicated hot key. **`referencePriceOffset` is accepted for wire/IDL
+     * compatibility but ignored on-chain** — `amm.referencePriceOffset` is a per-crank output
+     * recomputed from inventory and market stats by
+     * `crate::vlp::amm::math::spread::update_amm_quote_state`, not an admin-settable value; pass
+     * any value.
+     * @param perpMarketIndex - Perp market to update.
+     * @param ammSpreadAdjustment - Signed scalar on the AMM's base spread, same convention as `fee_adjustment` (-100 = spread scaled to 0, 100 = spread doubled, 0 = no adjustment).
+     * @param ammInventorySpreadAdjustment - Signed scalar on the inventory-skew component of the spread, same -100..100 convention.
+     * @param referencePriceOffset - Ignored on-chain; retained only for instruction-argument compatibility.
+     * @returns Transaction signature.
+     */
     updatePerpMarketAmmSpreadAdjustment(perpMarketIndex: number, ammSpreadAdjustment: number, ammInventorySpreadAdjustment: number, referencePriceOffset: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketAmmSpreadAdjustment` instruction without sending it. See
+     * `updatePerpMarketAmmSpreadAdjustment`.
+     * @returns The unsigned `updatePerpMarketAmmSpreadAdjustment` instruction.
+     */
     getUpdatePerpMarketAmmSpreadAdjustmentIx(perpMarketIndex: number, ammSpreadAdjustment: number, ammInventorySpreadAdjustment: number, referencePriceOffset: number): Promise<TransactionInstruction>;
+    /**
+     * Sets how much a perp market's paying-side spread widens while the vAMM's inventory is
+     * paying funding: `amm.fundingBiasSensitivity = s` gives multiplier `β(f) = 1 + s/100 * ρ(f)`
+     * (at full ramp, `ρ = 1`: 50 -> 1.5x, 100 -> 2x). Gated on `HotAdminUpdatePerpMarket`, whose
+     * account constraint is actually `check_warm` — this requires **warm** admin (or cold), not
+     * a dedicated hot key.
+     * @param perpMarketIndex - Perp market to update.
+     * @param fundingBiasSensitivity - Sensitivity `s`, in hundredths (value/100 is the multiplier slope); `0` disables the bias. `u8` range caps `s` at 2.55.
+     * @returns Transaction signature.
+     */
     updatePerpMarketFundingBiasSensitivity(perpMarketIndex: number, fundingBiasSensitivity: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketFundingBiasSensitivity` instruction without sending it. See
+     * `updatePerpMarketFundingBiasSensitivity`.
+     * @returns The unsigned `updatePerpMarketFundingBiasSensitivity` instruction.
+     */
     getUpdatePerpMarketFundingBiasSensitivityIx(perpMarketIndex: number, fundingBiasSensitivity: number): Promise<TransactionInstruction>;
+    /**
+     * Creates the zero'd `PythLazerOracle` PDA for a Pyth Lazer feed id (one-time setup
+     * before that feed can be pushed to via `updatePythLazerOracle`/keeper cranks).
+     * Requires warm admin (`check_warm`, `InitPythLazerOracle` context). Idempotent per
+     * `feedId` — a second call for the same id fails (`init` on an existing PDA).
+     * @param feedId - Pyth Lazer feed id; seeds the `PythLazerOracle` PDA (`getPythLazerOraclePublicKey`).
+     * @returns Transaction signature.
+     */
     initializePythLazerOracle(feedId: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializePythLazerOracle` instruction without sending it. See
+     * `initializePythLazerOracle`.
+     * @returns The unsigned `initializePythLazerOracle` instruction.
+     */
     getInitializePythLazerOracleIx(feedId: number): Promise<TransactionInstruction>;
+    /**
+     * Deposits tokens from an admin-controlled token account directly into a user's
+     * spot balance, recorded as a `DepositExplanation.Reward` deposit (e.g. crediting a
+     * promotional/reward balance without the user signing). Requires
+     * `HotRole.VaultDeposit` (cold, warm, or the configured vault-deposit hot key) —
+     * `this.wallet` signs as `admin` and must hold that role.
+     * @param marketIndex - Spot market to deposit into.
+     * @param amount - Deposit amount, the market's native token decimals.
+     * @param depositUserAccount - User account (`User` PDA pubkey) to credit.
+     * @param adminTokenAccount - Source token account (must belong to `this.wallet`). Defaults to `this.wallet`'s associated token account for the market's mint.
+     * @returns Transaction signature.
+     */
     adminDeposit(marketIndex: number, amount: BN, depositUserAccount: PublicKey, adminTokenAccount?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `adminDeposit` instruction without sending it. Also wires up the
+     * mint and transfer-hook remaining accounts the deposit needs. See `adminDeposit`.
+     * @returns The unsigned `adminDeposit` instruction.
+     */
     getAdminDepositIx(marketIndex: number, amount: BN, depositUserAccount: PublicKey, adminTokenAccount?: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Resets a perp market's push-oracle ("MM oracle") state — `marketStats.mmOraclePrice`,
+     * `mmOracleSequenceId`, and `mmOracleSlot` — all to `0`. Requires warm admin (the
+     * `HotAdminUpdatePerpMarket` context's `check_warm` constraint — despite the name,
+     * no dedicated hot role is wired to it; see `updatePerpMarketCurveUpdateIntensity`
+     * for the same gate). Use to force the next `updateMmOracleNative` push to be
+     * treated as a fresh bootstrap (its step-size cap is skipped when the previous
+     * price is `0`).
+     * @param marketIndex - Perp market whose MM oracle fields to zero.
+     * @returns Transaction signature.
+     */
     zeroMMOracleFields(marketIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `zeroMMOracleFields` instruction without sending it. See
+     * `zeroMMOracleFields`.
+     * @returns The unsigned `zeroMmOracleFields` instruction.
+     */
     getZeroMMOracleFieldsIx(marketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Toggles the `FeatureBitFlags.MM_ORACLE_UPDATE` bit on `state.featureBitFlags`,
+     * which gates the native (non-Anchor) `updateMmOracleNative` push-oracle
+     * dispatch — the on-chain handler asserts this bit before accepting a push.
+     * Requires `HotRole.FeatureFlag` (`HotAdminUpdateState`'s `check_hot`) to disable,
+     * but **enabling requires `state.coldAdmin` specifically** — the handler rejects
+     * `enable: true` from any other signer, even one otherwise authorised for the
+     * `FeatureFlag` role, so a compromised feature-flag hot key can only trip this
+     * kill switch, never clear it.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsMMOracle(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsMMOracle` instruction without sending it. See
+     * `updateFeatureBitFlagsMMOracle`.
+     * @returns The unsigned `updateFeatureBitFlagsMmOracle` instruction.
+     */
     getUpdateFeatureBitFlagsMMOracleIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Toggles the `FeatureBitFlags.BUILDER_CODES` bit on `state.featureBitFlags`
+     * (gates builder-code fee-attribution instructions protocol-wide). Same
+     * kill-switch gating as `updateFeatureBitFlagsMMOracle`: `HotRole.FeatureFlag` may
+     * disable, only `coldAdmin` may enable.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsBuilderCodes(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsBuilderCodes` instruction without sending it.
+     * See `updateFeatureBitFlagsBuilderCodes`.
+     * @returns The unsigned `updateFeatureBitFlagsBuilderCodes` instruction.
+     */
     getUpdateFeatureBitFlagsBuilderCodesIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * @deprecated There is no `BuilderReferral` bit in the on-chain `FeatureBitFlags`
+     * enum (only `MmOracleUpdate`, `MedianTriggerPrice`, `BuilderCodes` exist) and no
+     * `update_feature_bit_flags_builder_referral` instruction is defined in the
+     * program or present in the IDL. Calling this (or
+     * `getUpdateFeatureBitFlagsBuilderReferralIx`) throws at runtime — hence the
+     * `as any` cast on `this.program.instruction` used to bypass the TS type check.
+     * Do not call until (and unless) a matching on-chain instruction ships.
+     * @param enable - Intended flag state (unused while dead).
+     * @returns Transaction signature (never reached).
+     */
     updateFeatureBitFlagsBuilderReferral(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * @deprecated See `updateFeatureBitFlagsBuilderReferral` — no matching instruction
+     * exists on-chain or in the IDL; this throws at runtime.
+     * @returns Never resolves successfully.
+     */
     getUpdateFeatureBitFlagsBuilderReferralIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Toggles the `FeatureBitFlags.MEDIAN_TRIGGER_PRICE` bit on
+     * `state.featureBitFlags` (gates using a median of price sources for trigger-order
+     * evaluation). Same kill-switch gating as `updateFeatureBitFlagsMMOracle`:
+     * `HotRole.FeatureFlag` may disable, only `coldAdmin` may enable.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsMedianTriggerPrice(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsMedianTriggerPrice` instruction without sending
+     * it. See `updateFeatureBitFlagsMedianTriggerPrice`.
+     * @returns The unsigned `updateFeatureBitFlagsMedianTriggerPrice` instruction.
+     */
     getUpdateFeatureBitFlagsMedianTriggerPriceIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Toggles the `LpPoolFeatureBitFlags.SettleLpPool`-equivalent bit on
+     * `state.lpPoolFeatureBitFlags` (gates `settlePerpToLpPool`/LP-pool settlement
+     * protocol-wide). Same kill-switch gating as `updateFeatureBitFlagsMMOracle`:
+     * `HotRole.FeatureFlag` may disable, only `coldAdmin` may enable.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsSettleLpPool(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsSettleLpPool` instruction without sending it.
+     * See `updateFeatureBitFlagsSettleLpPool`.
+     * @returns The unsigned `updateFeatureBitFlagsSettleLpPool` instruction.
+     */
     getUpdateFeatureBitFlagsSettleLpPoolIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Toggles the LP-pool swap-enabled bit on `state.lpPoolFeatureBitFlags` (gates
+     * `lpPoolSwap`/begin-end swap flows protocol-wide). Same kill-switch gating as
+     * `updateFeatureBitFlagsMMOracle`: `HotRole.FeatureFlag` may disable, only
+     * `coldAdmin` may enable.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsSwapLpPool(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsSwapLpPool` instruction without sending it. See
+     * `updateFeatureBitFlagsSwapLpPool`.
+     * @returns The unsigned `updateFeatureBitFlagsSwapLpPool` instruction.
+     */
     getUpdateFeatureBitFlagsSwapLpPoolIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Toggles the LP-pool mint/redeem-enabled bit on `state.lpPoolFeatureBitFlags`
+     * (gates `lpPoolAddLiquidity`/`lpPoolRemoveLiquidity` protocol-wide). Same
+     * kill-switch gating as `updateFeatureBitFlagsMMOracle`: `HotRole.FeatureFlag` may
+     * disable, only `coldAdmin` may enable.
+     * @param enable - `true` to enable (cold-admin-only), `false` to disable (any `FeatureFlag`-authorised signer).
+     * @returns Transaction signature.
+     */
     updateFeatureBitFlagsMintRedeemLpPool(enable: boolean): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateFeatureBitFlagsMintRedeemLpPool` instruction without sending
+     * it. See `updateFeatureBitFlagsMintRedeemLpPool`.
+     * @returns The unsigned `updateFeatureBitFlagsMintRedeemLpPool` instruction.
+     */
     getUpdateFeatureBitFlagsMintRedeemLpPoolIx(enable: boolean): Promise<TransactionInstruction>;
+    /**
+     * Sets a user's `UserStats.pausedOperations` bitmask. Reachable by cold, warm,
+     * `HotRole.UserFlag`, or `pauseAdmin` (`PauseAdminUpdateUserStats`'s constraint
+     * ORs `check_pause` with `check_hot(.., UserFlag)`). A caller authorised only via
+     * `pauseAdmin` (i.e. not cold/warm/`UserFlag`) may add pause bits but never clear
+     * one; cold/warm/`UserFlag` may set any value. The `admin` account below defaults
+     * to `coldAdmin`; other roles must override it with their own pubkey.
+     * @param authority - Wallet authority whose `UserStats` PDA to update (derives the PDA).
+     * @param pausedOperations - New pause bitmask for the user's stats account.
+     * @returns Transaction signature.
+     */
     adminUpdateUserStatsPausedOperations(authority: PublicKey, pausedOperations: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `adminUpdateUserStatsPausedOperations` instruction without sending
+     * it. See `adminUpdateUserStatsPausedOperations`.
+     * @returns The unsigned `adminUpdateUserStatsPausedOperations` instruction.
+     */
     getAdminUpdateUserStatsPausedOperationsIx(authority: PublicKey, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Creates a new LP pool: mints its 6-decimal LP-token mint (fresh `mint` keypair,
+     * mint authority set to the `lpPool` PDA), then initializes the `LPPool` account
+     * plus its (initially empty) `AmmConstituentMapping`, `ConstituentTargetBase`, and
+     * `ConstituentCorrelations` side accounts. Requires warm admin (`check_warm`).
+     * Constituents (backing spot-market assets) are added afterward via
+     * `initializeConstituent`.
+     * @param lpPoolId - New pool's id byte; seeds the `LPPool` PDA (`getLpPoolPublicKey`).
+     * @param minMintFee - Minimum fee floor charged on mint, signed, PERCENTAGE_PRECISION (1e6).
+     * @param maxAum - AUM cap above which minting new LP tokens is rejected, QUOTE_PRECISION (1e6).
+     * @param maxSettleQuoteAmountPerMarket - Per-perp-market cap on quote settled into/out of the pool per settlement, QUOTE_PRECISION (1e6).
+     * @param mint - Fresh keypair for the pool's LP-token mint; funded and initialized by this call, and must co-sign.
+     * @param whitelistMint - Optional token that gates who may mint/redeem this pool's LP token (see `updateLpPoolParams`). Defaults to `PublicKey.default` (no gating).
+     * @returns Transaction signature.
+     */
     initializeLpPool(lpPoolId: number, minMintFee: BN, maxAum: BN, maxSettleQuoteAmountPerMarket: BN, mint: Keypair, whitelistMint?: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `createAccount` + `initializeMint2` + `initializeLpPool` instructions
+     * without sending them. See `initializeLpPool`.
+     * @returns The unsigned instructions (mint account creation, mint init, pool init) in order; `mint` must also sign the transaction.
+     */
     getInitializeLpPoolIx(lpPoolId: number, minMintFee: BN, maxAum: BN, maxSettleQuoteAmountPerMarket: BN, mint: Keypair, whitelistMint?: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Adds a new constituent (backing spot-market asset) to an existing LP pool:
+     * creates its `Constituent` PDA + token vault, appends a slot to
+     * `ConstituentTargetBase`, and records its correlation row in
+     * `ConstituentCorrelations`. Requires warm admin (`check_warm`). On-chain,
+     * `newConstituentCorrelations`'s length must equal the pool's current constituent
+     * count *before* this call (one correlation entry per existing constituent); the
+     * new constituent's `constituentIndex` is assigned as the next sequential index.
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param initializeConstituentParams - Constituent configuration; see `InitializeConstituentParams` for per-field precision.
+     * @returns Transaction signature.
+     */
     initializeConstituent(lpPoolId: number, initializeConstituentParams: InitializeConstituentParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `initializeConstituent` instruction without sending it. See
+     * `initializeConstituent`.
+     * @returns The unsigned `initializeConstituent` instruction, as a single-element array.
+     */
     getInitializeConstituentIx(lpPoolId: number, initializeConstituentParams: InitializeConstituentParams): Promise<TransactionInstruction[]>;
+    /**
+     * Sets an LP-pool constituent's lifecycle `status` (`ConstituentStatus`: `ACTIVE`,
+     * `REDUCE_ONLY`, or `DECOMMISSIONED`). Requires warm admin (`check_warm`).
+     * `REDUCE_ONLY` restricts flows to only shrink the constituent toward its target
+     * weight; `DECOMMISSIONED` marks it as having no remaining participants.
+     * @param constituent - Constituent PDA to update.
+     * @param constituentStatus - New status.
+     * @returns Transaction signature.
+     */
     updateConstituentStatus(constituent: PublicKey, constituentStatus: ConstituentStatus): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateConstituentStatus` instruction without sending it. See
+     * `updateConstituentStatus`.
+     * @returns The unsigned `updateConstituentStatus` instruction.
+     */
     getUpdateConstituentStatusIx(constituent: PublicKey, constituentStatus: ConstituentStatus): Promise<TransactionInstruction>;
+    /**
+     * Sets an LP-pool constituent's `pausedOperations` bitmask (`ConstituentLpOperation`:
+     * `Swap`/`Deposit`/`Withdraw`). Requires warm admin (`check_warm`) — despite the
+     * `useHotWalletAdmin` flag name used for the default `admin` account below, no
+     * dedicated hot role exists for this ix; the signer must be cold or warm.
+     * @param constituent - Constituent PDA to update.
+     * @param pausedOperations - New pause bitmask, `ConstituentLpOperation` bit values.
+     * @returns Transaction signature.
+     */
     updateConstituentPausedOperations(constituent: PublicKey, pausedOperations: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateConstituentPausedOperations` instruction without sending it.
+     * See `updateConstituentPausedOperations`.
+     * @returns The unsigned `updateConstituentPausedOperations` instruction.
+     */
     getUpdateConstituentPausedOperationsIx(constituent: PublicKey, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Patches an LP-pool constituent's tunable params — each field is optional and
+     * only the ones provided overwrite the on-chain value (see `ConstituentAccount`
+     * for per-field precision, which matches these params 1:1). Requires warm admin
+     * (`check_warm`); the underlying ix builder resolves `admin` as `this.wallet`
+     * directly (no cold/warm fallback), so `this.wallet` must itself hold that role.
+     * @param lpPoolId - Constituent's parent LP pool id byte.
+     * @param constituentPublicKey - Constituent PDA to patch.
+     * @param updateConstituentParams - Partial param patch; unset fields are left unchanged. `costToTradeBps` is bps and lives on the pool's `ConstituentTargetBase`, not the `Constituent` account itself.
+     * @returns Transaction signature.
+     */
     updateConstituentParams(lpPoolId: number, constituentPublicKey: PublicKey, updateConstituentParams: {
         maxWeightDeviation?: BN;
         swapFeeMin?: BN;
@@ -274,6 +2070,15 @@ export declare class AdminClient extends VelocityClient {
         gammaInventory?: number;
         xi?: number;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateConstituentParams` instruction without sending it. Note this
+     * method's parameter type omits `costToTradeBps` even though the public
+     * `updateConstituentParams` wrapper's type includes it and forwards it through
+     * unchanged at runtime — call via `updateConstituentParams` (or add the field
+     * manually) if you need to set it while calling this builder directly. See
+     * `updateConstituentParams`.
+     * @returns The unsigned `updateConstituentParams` instruction, as a single-element array.
+     */
     getUpdateConstituentParamsIx(lpPoolId: number, constituentPublicKey: PublicKey, updateConstituentParams: {
         maxWeightDeviation?: BN;
         swapFeeMin?: BN;
@@ -287,6 +2092,15 @@ export declare class AdminClient extends VelocityClient {
         gammaInventory?: number;
         xi?: number;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Patches an LP pool's tunable params — each field is optional and only the ones
+     * provided overwrite the on-chain value. Requires warm admin (`check_warm`). If
+     * `maxAum` is provided, on-chain validation rejects lowering it below the pool's
+     * current `maxAum` (the cap may only be raised via this ix).
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param updateLpPoolParams - Partial param patch; unset fields are left unchanged. `maxSettleQuoteAmount` and `maxAum` are QUOTE_PRECISION (1e6); `volatility` is PERCENTAGE_PRECISION (1e6); `whitelistMint` gates who may mint/redeem the pool's LP token.
+     * @returns Transaction signature.
+     */
     updateLpPoolParams(lpPoolId: number, updateLpPoolParams: {
         maxSettleQuoteAmount?: BN;
         volatility?: BN;
@@ -295,6 +2109,11 @@ export declare class AdminClient extends VelocityClient {
         whitelistMint?: PublicKey;
         maxAum?: BN;
     }): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateLpPoolParams` instruction without sending it. See
+     * `updateLpPoolParams`.
+     * @returns The unsigned `updateLpPoolParams` instruction, as a single-element array.
+     */
     getUpdateLpPoolParamsIx(lpPoolId: number, updateLpPoolParams: {
         maxSettleQuoteAmount?: BN;
         volatility?: BN;
@@ -303,13 +2122,75 @@ export declare class AdminClient extends VelocityClient {
         whitelistMint?: PublicKey;
         maxAum?: BN;
     }): Promise<TransactionInstruction[]>;
+    /**
+     * Adds new (perp market, constituent) weight entries to an LP pool's
+     * `AmmConstituentMapping` — routing that fraction of the perp market's hedge flow
+     * into the given constituent. Requires warm admin (`check_warm`). On-chain,
+     * inserting a `(perpMarketIndex, constituentIndex)` pair that already exists fails
+     * (`InvalidAmmConstituentMappingArgument`) — use `updateAmmConstituentMappingData`
+     * to change an existing entry's weight instead.
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param addAmmConstituentMappingData - New entries to add; see `AddAmmConstituentMappingDatum` (`weight` is PERCENTAGE_PRECISION, 1e6).
+     * @returns Transaction signature.
+     */
     addAmmConstituentMappingData(lpPoolId: number, addAmmConstituentMappingData: AddAmmConstituentMappingDatum[]): Promise<TransactionSignature>;
+    /**
+     * Builds the `addAmmConstituentMappingData` instruction without sending it (the
+     * `as any` cast works around a generated-type mismatch, not a missing on-chain
+     * instruction — `add_amm_constituent_mapping_data` is present in the IDL). See
+     * `addAmmConstituentMappingData`.
+     * @returns The unsigned `addAmmConstituentMappingData` instruction, as a single-element array.
+     */
     getAddAmmConstituentMappingDataIx(lpPoolId: number, addAmmConstituentMappingData: AddAmmConstituentMappingDatum[]): Promise<TransactionInstruction[]>;
+    /**
+     * Updates the weight (and refreshes `lastSlot`) of existing entries in an LP
+     * pool's `AmmConstituentMapping`. Requires warm admin (`check_warm`). On-chain,
+     * every `(perpMarketIndex, constituentIndex)` pair must already exist — an unknown
+     * pair fails with `InvalidAmmConstituentMappingArgument` (use
+     * `addAmmConstituentMappingData` to create new entries).
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param addAmmConstituentMappingData - Entries to update in place; see `AddAmmConstituentMappingDatum` (`weight` is PERCENTAGE_PRECISION, 1e6).
+     * @returns Transaction signature.
+     */
     updateAmmConstituentMappingData(lpPoolId: number, addAmmConstituentMappingData: AddAmmConstituentMappingDatum[]): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateAmmConstituentMappingData` instruction without sending it. See
+     * `updateAmmConstituentMappingData`.
+     * @returns The unsigned `updateAmmConstituentMappingData` instruction, as a single-element array.
+     */
     getUpdateAmmConstituentMappingDataIx(lpPoolId: number, addAmmConstituentMappingData: AddAmmConstituentMappingDatum[]): Promise<TransactionInstruction[]>;
+    /**
+     * Removes a single `(perpMarketIndex, constituentIndex)` entry from an LP pool's
+     * `AmmConstituentMapping`. Requires warm admin (`check_warm`). Fails
+     * (`InvalidAmmConstituentMappingArgument`) if no matching entry exists.
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param perpMarketIndex - Perp market side of the entry to remove.
+     * @param constituentIndex - Constituent side of the entry to remove.
+     * @returns Transaction signature.
+     */
     removeAmmConstituentMappingData(lpPoolId: number, perpMarketIndex: number, constituentIndex: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `removeAmmConstituentMappingData` instruction without sending it. See
+     * `removeAmmConstituentMappingData`.
+     * @returns The unsigned `removeAmmConstituentMappingData` instruction, as a single-element array.
+     */
     getRemoveAmmConstituentMappingDataIx(lpPoolId: number, perpMarketIndex: number, constituentIndex: number): Promise<TransactionInstruction[]>;
+    /**
+     * Sets the correlation between two constituents in an LP pool's
+     * `ConstituentCorrelations` matrix (symmetric — updates both `(index1, index2)`
+     * and `(index2, index1)`). Requires warm admin (`check_warm`).
+     * @param lpPoolId - Target LP pool's id byte.
+     * @param index1 - First constituent's index.
+     * @param index2 - Second constituent's index.
+     * @param correlation - New correlation, PERCENTAGE_PRECISION (1e6), signed.
+     * @returns Transaction signature.
+     */
     updateConstituentCorrelationData(lpPoolId: number, index1: number, index2: number, correlation: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateConstituentCorrelationData` instruction without sending it.
+     * See `updateConstituentCorrelationData`.
+     * @returns The unsigned `updateConstituentCorrelationData` instruction, as a single-element array.
+     */
     getUpdateConstituentCorrelationDataIx(lpPoolId: number, index1: number, index2: number, correlation: BN): Promise<TransactionInstruction[]>;
     /**
      * Get the velocity begin_swap and end_swap instructions
@@ -337,6 +2218,24 @@ export declare class AdminClient extends VelocityClient {
         beginSwapIx: TransactionInstruction;
         endSwapIx: TransactionInstruction;
     }>;
+    /**
+     * Builds a flash-loan-style LP-pool swap that routes the actual trade through
+     * Jupiter: wraps a Jupiter swap quote/instruction set between the same
+     * `beginLpSwap`/`endLpSwap` instruction pair `getSwapIx` uses, so the LP pool's
+     * constituent vaults temporarily fund the swap and are repaid by the end of the
+     * transaction (`endLpSwap` fails if the constituents aren't made whole). Fetches
+     * a quote from `jupiterClient` if one isn't passed in.
+     * @param jupiterClient - Jupiter client used to fetch the quote/swap transaction and lookup tables.
+     * @param outMarketIndex - Spot market of the token being bought.
+     * @param inMarketIndex - Spot market of the token being sold.
+     * @param amount - Swap amount, in-market's native decimals (interpreted as exact-in or exact-out per `swapMode`).
+     * @param slippageBps - Optional slippage tolerance passed to Jupiter, basis points.
+     * @param swapMode - Optional `'ExactIn'` / `'ExactOut'`; also inferred from `quote.swapMode` if a quote is supplied.
+     * @param onlyDirectRoutes - Optional, restricts the Jupiter quote to single-hop routes.
+     * @param quote - Optional pre-fetched Jupiter quote; skips the internal fetch if provided.
+     * @param lpPoolId - LP pool id byte the swap routes through.
+     * @returns The unsigned instruction sequence (begin-swap, Jupiter swap instructions, end-swap) and any address lookup tables the Jupiter instructions require.
+     */
     getLpJupiterSwapIxV6({ jupiterClient, outMarketIndex, inMarketIndex, amount, slippageBps, swapMode, onlyDirectRoutes, quote, lpPoolId, }: {
         jupiterClient: JupiterClient;
         outMarketIndex: number;
@@ -353,38 +2252,271 @@ export declare class AdminClient extends VelocityClient {
         ixs: TransactionInstruction[];
         lookupTables: AddressLookupTableAccount[];
     }>;
+    /**
+     * Devnet/test-only helper: builds a plain SPL-token transfer pair simulating an
+     * external counterparty swapping against `this.wallet`'s own token accounts (not
+     * an atomic on-chain program instruction, and not gated by any admin tier — it's
+     * ordinary token transfers assembled for local test flows, typically alongside
+     * `getSwapIx`'s begin/end pair as in `getAllDevnetLpSwapIxs`). Also idempotently
+     * creates the external user's in/out ATAs.
+     * @param amountIn - Amount `this.wallet` sends of the in-market token, that market's native decimals.
+     * @param amountOut - Amount `this.wallet` receives of the out-market token, that market's native decimals.
+     * @param externalUserAuthority - The simulated counterparty's wallet authority.
+     * @param externalUserInTokenAccount - Counterparty's ATA that receives the in-market token.
+     * @param externalUserOutTokenAccount - Counterparty's ATA that sends the out-market token.
+     * @param inSpotMarketIndex - Spot market of the token `this.wallet` sends.
+     * @param outSpotMarketIndex - Spot market of the token `this.wallet` receives.
+     * @returns Unsigned instructions: create both ATAs, then the two transfers.
+     */
     getDevnetLpSwapIxs(amountIn: BN, amountOut: BN, externalUserAuthority: PublicKey, externalUserInTokenAccount: PublicKey, externalUserOutTokenAccount: PublicKey, inSpotMarketIndex: number, outSpotMarketIndex: number): Promise<TransactionInstruction[]>;
+    /**
+     * Devnet/test-only helper: wraps `getSwapIx`'s begin/end LP-pool swap pair around
+     * `getDevnetLpSwapIxs`'s simulated-counterparty transfers, producing the full
+     * instruction sequence for an end-to-end devnet LP-pool swap test.
+     * @param lpPoolId - LP pool id byte the swap routes through.
+     * @param inMarketIndex - Spot market of the token going in.
+     * @param outMarketIndex - Spot market of the token coming out.
+     * @param inAmount - Amount going in, in-market's native decimals.
+     * @param minOutAmount - Minimum acceptable amount out, out-market's native decimals (also used as the simulated counterparty's exact transfer amount).
+     * @param externalUserAuthority - The simulated counterparty's wallet authority.
+     * @returns Unsigned instructions: begin-swap, the simulated transfer pair, end-swap, in order.
+     */
     getAllDevnetLpSwapIxs(lpPoolId: number, inMarketIndex: number, outMarketIndex: number, inAmount: BN, minOutAmount: BN, externalUserAuthority: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Atomically moves an LP-pool constituent's idle tokens into a spot market's
+     * lending vault (earning yield) and borrows another constituent's tokens back out
+     * of a (possibly different) spot market's vault, in one transaction. Requires
+     * `HotRole.LpSwap` on both legs (`DepositProgramVault`/`WithdrawProgramVault`
+     * contexts) — `this.wallet` signs as `admin` directly and must hold that role.
+     * Each leg re-validates the constituent's borrow/token-amount invariants
+     * on-chain; the withdraw leg additionally caps the transfer at
+     * `constituent.maxBorrowTokenAmount` (+5% buffer).
+     * @param lpPoolId - LP pool whose constituents to move tokens for.
+     * @param depositMarketIndex - Spot market (and matching constituent) to deposit into.
+     * @param borrowMarketIndex - Spot market (and matching constituent) to borrow/withdraw from.
+     * @param amountToDeposit - Deposit amount, the deposit market's native decimals.
+     * @param amountToBorrow - Withdraw amount, the borrow market's native decimals.
+     * @returns Transaction signature.
+     */
     depositWithdrawToProgramVault(lpPoolId: number, depositMarketIndex: number, borrowMarketIndex: number, amountToDeposit: BN, amountToBorrow: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `depositToProgramVault` and `withdrawFromProgramVault` instructions
+     * without sending them. See `depositWithdrawToProgramVault`; also the building
+     * block for `getDepositToProgramVaultIx`/`getWithdrawFromProgramVaultIx`
+     * (each of which calls this with the unused leg's amount set to `0`).
+     * @returns The unsigned `{ depositIx, withdrawIx }` pair.
+     */
     getDepositWithdrawToProgramVaultIxs(lpPoolId: number, depositMarketIndex: number, borrowMarketIndex: number, amountToDeposit: BN, amountToBorrow: BN): Promise<{
         depositIx: TransactionInstruction;
         withdrawIx: TransactionInstruction;
     }>;
+    /**
+     * Deposits an LP-pool constituent's idle tokens into its spot market's lending
+     * vault, on its own (single-leg version of `depositWithdrawToProgramVault`).
+     * Requires `HotRole.LpSwap`; `this.wallet` must hold that role.
+     * @param lpPoolId - LP pool whose constituent to deposit from.
+     * @param depositMarketIndex - Spot market (and matching constituent) to deposit into.
+     * @param amountToDeposit - Deposit amount, the market's native decimals.
+     * @returns Transaction signature.
+     */
     depositToProgramVault(lpPoolId: number, depositMarketIndex: number, amountToDeposit: BN): Promise<TransactionSignature>;
+    /**
+     * Borrows tokens from a spot market's lending vault back into an LP-pool
+     * constituent, on its own (single-leg version of `depositWithdrawToProgramVault`).
+     * Requires `HotRole.LpSwap`; `this.wallet` must hold that role. On-chain, capped
+     * at `constituent.maxBorrowTokenAmount` (+5% buffer).
+     * @param lpPoolId - LP pool whose constituent to borrow into.
+     * @param borrowMarketIndex - Spot market (and matching constituent) to borrow from.
+     * @param amountToWithdraw - Withdraw amount, the market's native decimals.
+     * @returns Transaction signature.
+     */
     withdrawFromProgramVault(lpPoolId: number, borrowMarketIndex: number, amountToWithdraw: BN): Promise<TransactionSignature>;
+    /**
+     * Builds the `depositToProgramVault` instruction without sending it, via
+     * `getDepositWithdrawToProgramVaultIxs` with a `0` withdraw amount (the
+     * accompanying zero-amount withdraw instruction is discarded, not sent). See
+     * `depositToProgramVault`.
+     * @returns The unsigned `depositToProgramVault` instruction.
+     */
     getDepositToProgramVaultIx(lpPoolId: number, depositMarketIndex: number, amountToDeposit: BN): Promise<TransactionInstruction>;
+    /**
+     * Builds the `withdrawFromProgramVault` instruction without sending it, via
+     * `getDepositWithdrawToProgramVaultIxs` with a `0` deposit amount (the
+     * accompanying zero-amount deposit instruction is discarded, not sent). See
+     * `withdrawFromProgramVault`.
+     * @returns The unsigned `withdrawFromProgramVault` instruction.
+     */
     getWithdrawFromProgramVaultIx(lpPoolId: number, borrowMarketIndex: number, amountToWithdraw: BN): Promise<TransactionInstruction>;
+    /**
+     * Patches a perp market's `hedgeConfig` fee-routing scalars that control how much
+     * of the AMM's fee growth is swept to its LP pool (see `sweepPerpMarketFees`).
+     * Requires warm admin (the `HotAdminUpdatePerpMarketDlp` context's `check_warm`
+     * constraint). Both params are optional; only the ones provided are updated.
+     * @param marketIndex - Perp market to update.
+     * @param lpFeeTransferScalar - `hedgeConfig.feeTransferScalar`, percent 0-100 (divided by 100 on-chain) of AMM fee-pool growth routed to the LP pool.
+     * @param lpExchangeFeeExcluscionScalar - `hedgeConfig.exchangeFeeExclusionScalar`, percent 0-100 of the period's exchange-fee growth excluded from that sweep.
+     * @returns Transaction signature.
+     */
     updatePerpMarketLpPoolFeeTransferScalar(marketIndex: number, lpFeeTransferScalar?: number, lpExchangeFeeExcluscionScalar?: number): Promise<string>;
+    /**
+     * Builds the `updatePerpMarketLpPoolFeeTransferScalar` instruction without
+     * sending it. See `updatePerpMarketLpPoolFeeTransferScalar`.
+     * @returns The unsigned `updatePerpMarketLpPoolFeeTransferScalar` instruction.
+     */
     getUpdatePerpMarketLpPoolFeeTransferScalarIx(marketIndex: number, lpFeeTransferScalar?: number, lpExchangeFeeExcluscionScalar?: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a perp market's `hedgeConfig.pausedOperations` bitmask
+     * (`ConstituentLpOperation`: `Swap`/`Deposit`/`Withdraw`), pausing that market's
+     * side of LP-pool hedge flow. Reachable by cold, warm, or `pauseAdmin`
+     * (`PauseAdminUpdatePerpMarket`'s `check_pause`), with the same bit-add-only
+     * restriction for a pause-admin-only caller as `updateExchangeStatus`. The
+     * `admin` account below defaults to `coldAdmin`; other roles must override it.
+     * @param marketIndex - Perp market to update.
+     * @param pausedOperations - New pause bitmask, `ConstituentLpOperation` bit values.
+     * @returns Transaction signature.
+     */
     updatePerpMarketLpPoolPausedOperations(marketIndex: number, pausedOperations: number): Promise<string>;
+    /**
+     * Builds the `updatePerpMarketLpPoolPausedOperations` instruction without
+     * sending it. See `updatePerpMarketLpPoolPausedOperations`.
+     * @returns The unsigned `updatePerpMarketLpPoolPausedOperations` instruction.
+     */
     getUpdatePerpMarketLpPoolPausedOperationsIx(marketIndex: number, pausedOperations: number): Promise<TransactionInstruction>;
+    /**
+     * Mints `1000` units of an LP pool's `whitelistMint` to `authority`'s associated
+     * token account, creating the ATA if needed. This is a plain SPL-token mint, not
+     * a velocity program instruction — no `HotRole`/tier gate applies; instead the
+     * token program itself requires `this.wallet` to be the mint's authority (set
+     * whenever the whitelist mint was created — typically the same admin that called
+     * `initializeLpPool`/`updateLpPoolParams` to configure it). Holding units of the
+     * whitelist mint is what gates `authority`'s ability to mint/redeem this pool's LP
+     * token, if `lpPool.whitelistMint` is set to a non-default pubkey.
+     * @param lpPool - LP pool whose `whitelistMint` to mint from.
+     * @param authority - Wallet to receive the whitelist tokens.
+     * @returns Transaction signature.
+     */
     mintLpWhitelistToken(lpPool: LPPoolAccount, authority: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the ATA-creation and `mintTo` instructions without sending them. See
+     * `mintLpWhitelistToken`.
+     * @returns The unsigned instructions: idempotent ATA creation, then mint-to, in order.
+     */
     getMintLpWhitelistTokenIx(lpPool: LPPoolAccount, authority: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Sets a perp market's `marketConfig` bitmask (currently one bit:
+     * `MarketConfigFlag.DisableFormulaicKUpdate`, which turns off the AMM's automatic
+     * k-adjustment for the market). Requires warm admin (the `HotAdminUpdatePerpMarket`
+     * context's `check_warm` constraint), but **setting any bit (a non-zero value)
+     * requires `state.coldAdmin` specifically** — a warm-only signer may only pass `0`
+     * (clear all bits). Unknown bits are rejected (`InvalidPerpMarketConfig`).
+     * @param marketIndex - Perp market to update.
+     * @param marketConfig - New bitmask; non-zero values require cold admin.
+     * @returns Transaction signature.
+     */
     updatePerpMarketConfig(marketIndex: number, marketConfig: number): Promise<string>;
+    /**
+     * Builds the `updatePerpMarketConfig` instruction without sending it. See
+     * `updatePerpMarketConfig`.
+     * @returns The unsigned `updatePerpMarketConfig` instruction.
+     */
     getUpdatePerpMarketConfigIx(marketIndex: number, marketConfig: number): Promise<TransactionInstruction>;
+    /**
+     * Moves quote value between one perp market's protocol fee pool and another (or
+     * the same) perp market's pnl pool — a pure internal ledger transfer against the
+     * shared quote spot market's scaled balances, no tokens actually move. Requires
+     * warm admin (`check_warm`). On-chain, the transfer is capped at the source
+     * pool's available token amount. For a same-market move the AMM's
+     * `totalFeeMinusDistributions` ledger is left untouched (equity-neutral within
+     * one market's perimeter); for a cross-market move, the fee-pool market's ledger
+     * is adjusted to reflect quote leaving/entering its perimeter (reconciled later
+     * by the summary-stats recompute ix).
+     * @param perpMarketIndexWithFeePool - Perp market whose fee pool is the transfer source/destination.
+     * @param perpMarketIndexWithPnlPool - Perp market whose pnl pool is the transfer destination/source.
+     * @param amount - Amount to move, QUOTE_PRECISION (1e6) (clamped down to the source pool's available balance on-chain).
+     * @param direction - `TransferFeeAndPnlPoolDirection.FEE_TO_PNL_POOL` or `.PNL_TO_FEE_POOL`.
+     * @returns Transaction signature.
+     */
     transferFeeAndPnlPool(perpMarketIndexWithFeePool: number, perpMarketIndexWithPnlPool: number, amount: BN, direction: TransferFeeAndPnlPoolDirection): Promise<TransactionSignature>;
+    /**
+     * Builds the `transferFeeAndPnlPool` instruction without sending it. See
+     * `transferFeeAndPnlPool`.
+     * @returns The unsigned `transferFeeAndPnlPool` instruction.
+     */
     getTransferFeeAndPnlPoolIx(perpMarketIndexWithFeePool: number, perpMarketIndexWithPnlPool: number, amount: BN, direction: TransferFeeAndPnlPoolDirection): Promise<TransactionInstruction>;
+    /**
+     * Sets a `User` account's `specialUserStatus` bitmask (`SpecialUserStatus`;
+     * currently one bit, `VAMM_HEDGER`, marking the account the protocol's own
+     * vAMM-hedging bot trades from). Requires `HotRole.UserFlag` (cold, warm, or the
+     * configured user-flag hot key), but **setting any bit (a non-zero value)
+     * requires `state.coldAdmin` specifically** — a `UserFlag`-hot-only signer may
+     * only pass `0` (clear all bits). Unknown bits are rejected (`DefaultError`).
+     * @param userAccountPublicKey - `User` PDA to update.
+     * @param status - New bitmask; non-zero values require cold admin.
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
     updateSpecialUserStatus(userAccountPublicKey: PublicKey, status: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateSpecialUserStatus` instruction without sending it. See
+     * `updateSpecialUserStatus`.
+     * @returns The unsigned `updateSpecialUserStatus` instruction.
+     */
     getUpdateSpecialUserStatusIx(userAccountPublicKey: PublicKey, status: number): Promise<TransactionInstruction>;
+    /**
+     * Rotates `state.warmAdmin`, the operational (multisig+timelock) tier that can
+     * rotate every hot-role key (`updateHotAdmin`). Cold-only: the `UpdateWarmAdmin`
+     * context requires `state.coldAdmin == admin.key()`.
+     * @param newWarmAdmin - New warm admin pubkey. `PublicKey.default()` unsets the role — only `coldAdmin` can then act where warm was accepted.
+     * @returns Transaction signature.
+     */
     updateWarmAdmin(newWarmAdmin: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateWarmAdmin` instruction without sending it. See
+     * `updateWarmAdmin`.
+     * @returns The unsigned `updateWarmAdmin` instruction.
+     */
     getUpdateWarmAdminIx(newWarmAdmin: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Rotates `state.pauseAdmin`, the no-timelock emergency-pause key authorised (in
+     * addition to cold/warm) for handlers that flip pause bitmasks
+     * (`updateExchangeStatus`, per-market/per-user paused-operations updates) —
+     * restricted at the handler level to *adding* pause bits, never clearing them.
+     * Cold-only: the `UpdatePauseAdmin` context requires `state.coldAdmin ==
+     * admin.key()`.
+     * @param newPauseAdmin - New pause admin pubkey. `PublicKey.default()` unsets the role — only cold/warm can then pause.
+     * @returns Transaction signature.
+     */
+    updatePauseAdmin(newPauseAdmin: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePauseAdmin` instruction without sending it. See
+     * `updatePauseAdmin`.
+     * @returns The unsigned `updatePauseAdmin` instruction.
+     */
+    getUpdatePauseAdminIx(newPauseAdmin: PublicKey): Promise<TransactionInstruction>;
+    /**
+     * Rotates one purpose-specific hot-role key on `state` (e.g. `hotFeeWithdraw`,
+     * `hotVaultDeposit`). Warm-or-cold: the `UpdateHotAdmin` context requires
+     * `state.isWarm(admin.key())`. Compromise of one hot key only exposes the
+     * instructions gated on that specific `HotRole` — rotating it here fully revokes
+     * the old key for that role.
+     * @param role - Which hot role's key to rotate.
+     * @param newPubkey - New key for that role. `PublicKey.default()` unsets it — only warm/cold can then call handlers gated on that role.
+     * @returns Transaction signature.
+     */
     updateHotAdmin(role: HotRole, newPubkey: PublicKey): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateHotAdmin` instruction without sending it. See
+     * `updateHotAdmin`.
+     * @returns The unsigned `updateHotAdmin` instruction.
+     */
     getUpdateHotAdminIx(role: HotRole, newPubkey: PublicKey): Promise<TransactionInstruction>;
 }
 /**
  * Hot-admin role identifier. Each role is a separate purpose-specific signer key
- * stored on the `AdminAuthorityConfig` PDA. Compromise of one role's key only
- * enables that role's instructions.
+ * stored directly on the `State` account (one `hot*` pubkey field per role, e.g.
+ * `state.hotFeeWithdraw` for `FeeWithdraw`) — there is no separate
+ * "AdminAuthorityConfig" account. Compromise of one role's key only enables that
+ * role's instructions (see `updateHotAdmin` to rotate one).
  */
 export declare enum HotRole {
     AmmCrank = "ammCrank",