@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/core/instructions/orders.d.ts

@@ -1,5 +1,18 @@
 import type { AccountMeta, PublicKey, TransactionInstruction } from '@solana/web3.js';
 import type { VelocityProgram } from '../../config';
+/**
+ * Builds a `placeOrders` instruction, placing a batch of up to 32 perp and/or spot
+ * orders in one instruction. None of the orders may be immediate-or-cancel — IOC orders
+ * are only valid via `placeAndTake`/`placeAndMake` — or the instruction throws.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.formattedParams - array of `OrderParams`: `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account the orders are placed on; `authority` must own or be a delegate of it.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `place_orders` accounts (only `state`/`user`/`authority` are used).
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` covering every order's market, plus the placing user's `RevenueShareEscrow` account when any order carries a `builderIdx` and builder codes are enabled protocol-wide.
+ * @returns the unsigned `placeOrders` `TransactionInstruction`.
+ */
 export declare function buildPlaceOrdersInstruction(args: {
     program: VelocityProgram;
     formattedParams: any[];
@@ -9,6 +22,21 @@ export declare function buildPlaceOrdersInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `cancelOrders` instruction, cancelling every open order on `user` that
+ * matches all of the given (optional) filters. `null`/`undefined` on a filter means
+ * "don't filter on this dimension" — leaving all three `null` cancels every open order.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketType - only cancel orders of this `MarketType` (`Perp`/`Spot`), or `null` for both.
+ * @param args.marketIndex - only cancel orders on this market index, or `null` for all markets.
+ * @param args.direction - only cancel orders with this `PositionDirection`, or `null` for both.
+ * @param args.user - the `User` account whose orders are cancelled.
+ * @param args.state - the global `State` PDA.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `cancel_orders` accounts (only `state`/`user`/`authority` are used).
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive auction/oracle-offset prices for the cancelled orders.
+ * @returns the unsigned `cancelOrders` `TransactionInstruction`.
+ */
 export declare function buildCancelOrdersInstruction(args: {
     program: VelocityProgram;
     marketType: any;

package/lib/node/core/instructions/orders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/orders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,eAAe,CAAC;IACzB,eAAe,EAAE,GAAG,EAAE,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAalC;AAED,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,GAAG,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAelC"}
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/orders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,eAAe,CAAC;IACzB,eAAe,EAAE,GAAG,EAAE,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAalC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,GAAG,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAelC"}

package/lib/node/core/instructions/orders.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildCancelOrdersInstruction = exports.buildPlaceOrdersInstruction = void 0;
+/**
+ * Builds a `placeOrders` instruction, placing a batch of up to 32 perp and/or spot
+ * orders in one instruction. None of the orders may be immediate-or-cancel — IOC orders
+ * are only valid via `placeAndTake`/`placeAndMake` — or the instruction throws.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.formattedParams - array of `OrderParams`: `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account the orders are placed on; `authority` must own or be a delegate of it.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `place_orders` accounts (only `state`/`user`/`authority` are used).
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` covering every order's market, plus the placing user's `RevenueShareEscrow` account when any order carries a `builderIdx` and builder codes are enabled protocol-wide.
+ * @returns the unsigned `placeOrders` `TransactionInstruction`.
+ */
 async function buildPlaceOrdersInstruction(args) {
     return await args.program.instruction.placeOrders(args.formattedParams, {
         accounts: {
@@ -13,6 +26,21 @@ async function buildPlaceOrdersInstruction(args) {
     });
 }
 exports.buildPlaceOrdersInstruction = buildPlaceOrdersInstruction;
+/**
+ * Builds a `cancelOrders` instruction, cancelling every open order on `user` that
+ * matches all of the given (optional) filters. `null`/`undefined` on a filter means
+ * "don't filter on this dimension" — leaving all three `null` cancels every open order.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketType - only cancel orders of this `MarketType` (`Perp`/`Spot`), or `null` for both.
+ * @param args.marketIndex - only cancel orders on this market index, or `null` for all markets.
+ * @param args.direction - only cancel orders with this `PositionDirection`, or `null` for both.
+ * @param args.user - the `User` account whose orders are cancelled.
+ * @param args.state - the global `State` PDA.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `cancel_orders` accounts (only `state`/`user`/`authority` are used).
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive auction/oracle-offset prices for the cancelled orders.
+ * @returns the unsigned `cancelOrders` `TransactionInstruction`.
+ */
 async function buildCancelOrdersInstruction(args) {
     return await args.program.instruction.cancelOrders(args.marketType, args.marketIndex, args.direction, {
         accounts: {

package/lib/node/core/instructions/perpOrders.d.ts

@@ -1,5 +1,18 @@
 import type { AccountMeta, PublicKey, TransactionInstruction } from '@solana/web3.js';
 import type { VelocityProgram } from '../../config';
+/**
+ * Builds a `placePerpOrder` instruction, placing a single resting perp order. Rejects
+ * immediate-or-cancel orders (`InvalidOrderIOC`) — use `buildPlaceAndTakePerpOrderInstruction`
+ * or `buildPlaceAndMakePerpOrderInstruction` for IOC orders instead.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account the order is placed on.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `place_perp_order` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for `orderParams.marketIndex`, plus the placing user's `RevenueShareEscrow` account if the order carries a `builderIdx` and builder codes are enabled protocol-wide.
+ * @returns the unsigned `placePerpOrder` `TransactionInstruction`.
+ */
 export declare function buildPlacePerpOrderInstruction(args: {
     program: VelocityProgram;
     orderParams: any;
@@ -9,6 +22,22 @@ export declare function buildPlacePerpOrderInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `placeAndTakePerpOrder` instruction: places an order and immediately attempts
+ * to fill it as a taker against the AMM and/or the supplied maker accounts.
+ * `orderParams.postOnly` must be `PostOnlyParam.None` (`InvalidOrderPostOnly` otherwise).
+ * Any portion left unfilled is auto-cancelled when the order is (or becomes, via
+ * `optionalParams`) immediate-or-cancel.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.optionalParams - packed `u32` combining a `PlaceAndTakeOrderSuccessCondition` (fail the tx if not at least partially/fully filled) and an auction-duration percentage override; `null` for default behavior. Passing any non-null value also forces IOC cancel-remainder semantics.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the taker's `User` account.
+ * @param args.userStats - the taker's `UserStats` PDA.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `orderParams.marketIndex`, followed by maker/referrer `(User, UserStats)` pairs, followed by the taker's `RevenueShareEscrow` account if builder codes are enabled.
+ * @returns the unsigned `placeAndTakePerpOrder` `TransactionInstruction`.
+ */
 export declare function buildPlaceAndTakePerpOrderInstruction(args: {
     program: VelocityProgram;
     orderParams: any;
@@ -19,6 +48,23 @@ export declare function buildPlaceAndTakePerpOrderInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `placeAndMakePerpOrder` instruction: posts an immediate-or-cancel, post-only
+ * `Limit` order for `user` and immediately fills it as the maker against `taker`'s
+ * existing resting order (`InvalidOrderIOCPostOnly` if `orderParams` isn't IOC + post-only
+ * + `Limit`). Any unfilled remainder of the just-placed maker order is auto-cancelled.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.takerOrderId - the on-chain order ID of `taker`'s resting order being filled.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the maker's `User` account.
+ * @param args.userStats - the maker's `UserStats` PDA.
+ * @param args.taker - the taker's `User` account (order owner being filled).
+ * @param args.takerStats - the taker's `UserStats` PDA.
+ * @param args.authority - signer that must own or be a registered delegate of `user` (the maker).
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `orderParams.marketIndex`, followed by any additional maker/referrer `(User, UserStats)` pairs needed to fill `taker`'s order, followed by `taker`'s `RevenueShareEscrow` account if builder codes are enabled.
+ * @returns the unsigned `placeAndMakePerpOrder` `TransactionInstruction`.
+ */
 export declare function buildPlaceAndMakePerpOrderInstruction(args: {
     program: VelocityProgram;
     orderParams: any;
@@ -44,6 +90,14 @@ export declare function buildPlaceAndMakePerpOrderInstruction(args: {
  * The on-chain `order_id` counter is a monotonically incrementing u32 on the user
  * account, so `get_last_order_id` reliably points to the order placed in the preceding
  * instruction of the same transaction.
+ *
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the order to cancel, or `null` per the above.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled order's auction/oracle-offset price.
+ * @returns the unsigned `cancelOrder` `TransactionInstruction`.
  */
 export declare function buildCancelOrderInstruction(args: {
     program: VelocityProgram;
@@ -53,6 +107,19 @@ export declare function buildCancelOrderInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `cancelOrderByUserId` instruction, cancelling the order matching the
+ * caller-assigned `userOrderId` (the `OrderParams.userOrderId` tag set at placement)
+ * rather than the program-assigned order ID.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.userOrderId - the caller-assigned order tag (`u8`) supplied when the order was placed.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.oracle - accepted for forward-compatibility but not required by the current on-chain `cancel_order_by_user_id` accounts (only `state`/`user`/`authority` are used).
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled order's auction/oracle-offset price.
+ * @returns the unsigned `cancelOrderByUserId` `TransactionInstruction`.
+ */
 export declare function buildCancelOrderByUserIdInstruction(args: {
     program: VelocityProgram;
     userOrderId: number;
@@ -62,6 +129,19 @@ export declare function buildCancelOrderByUserIdInstruction(args: {
     oracle: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `cancelOrdersByIds` instruction, cancelling multiple orders by their
+ * program-assigned order IDs in one instruction (loops `cancel_order_by_order_id`
+ * on-chain, one order at a time — an order ID that no longer exists is silently
+ * skipped rather than failing the whole instruction).
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderIds - order IDs to cancel; passing `undefined` sends an empty list on-chain (cancels nothing).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose orders are cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled orders' auction/oracle-offset prices.
+ * @returns the unsigned `cancelOrdersByIds` `TransactionInstruction`.
+ */
 export declare function buildCancelOrdersByIdsInstruction(args: {
     program: VelocityProgram;
     orderIds: number[] | undefined;
@@ -70,6 +150,19 @@ export declare function buildCancelOrdersByIdsInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `modifyOrder` instruction, mutating an existing resting order in place (e.g.
+ * new price/size/trigger) rather than cancel-and-replace.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the program-assigned order ID to modify (use `buildModifyOrderByUserIdInstruction` to target by the caller-assigned tag instead).
+ * @param args.modifyParams - a `ModifyOrderParams` object; any `baseAssetAmount`/`price`/`triggerPrice` overrides use BASE_PRECISION (1e9) / PRICE_PRECISION (1e6) respectively.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is modified.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `modify_order` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `modifyOrder` `TransactionInstruction`.
+ */
 export declare function buildModifyOrderInstruction(args: {
     program: VelocityProgram;
     orderId: number;
@@ -80,6 +173,19 @@ export declare function buildModifyOrderInstruction(args: {
     authority: PublicKey;
     remainingAccounts: AccountMeta[];
 }): Promise<TransactionInstruction>;
+/**
+ * Builds a `modifyOrderByUserId` instruction, same as `buildModifyOrderInstruction` but
+ * targeting the order by its caller-assigned `userOrderId` tag.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.userOrderId - the caller-assigned order tag (`u8`) supplied when the order was placed.
+ * @param args.modifyParams - a `ModifyOrderParams` object; any `baseAssetAmount`/`price`/`triggerPrice` overrides use BASE_PRECISION (1e9) / PRICE_PRECISION (1e6) respectively.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is modified.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `modify_order_by_user_id` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `modifyOrderByUserId` `TransactionInstruction`.
+ */
 export declare function buildModifyOrderByUserIdInstruction(args: {
     program: VelocityProgram;
     userOrderId: number;

package/lib/node/core/instructions/perpOrders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perpOrders.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/perpOrders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"perpOrders.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/perpOrders.ts"],"names":[],"mappings":"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"}

package/lib/node/core/instructions/perpOrders.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildModifyOrderByUserIdInstruction = exports.buildModifyOrderInstruction = exports.buildCancelOrdersByIdsInstruction = exports.buildCancelOrderByUserIdInstruction = exports.buildCancelOrderInstruction = exports.buildPlaceAndMakePerpOrderInstruction = exports.buildPlaceAndTakePerpOrderInstruction = exports.buildPlacePerpOrderInstruction = void 0;
+/**
+ * Builds a `placePerpOrder` instruction, placing a single resting perp order. Rejects
+ * immediate-or-cancel orders (`InvalidOrderIOC`) — use `buildPlaceAndTakePerpOrderInstruction`
+ * or `buildPlaceAndMakePerpOrderInstruction` for IOC orders instead.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account the order is placed on.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `place_perp_order` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for `orderParams.marketIndex`, plus the placing user's `RevenueShareEscrow` account if the order carries a `builderIdx` and builder codes are enabled protocol-wide.
+ * @returns the unsigned `placePerpOrder` `TransactionInstruction`.
+ */
 async function buildPlacePerpOrderInstruction(args) {
     return await args.program.instruction.placePerpOrder(args.orderParams, {
         accounts: {
@@ -13,6 +26,22 @@ async function buildPlacePerpOrderInstruction(args) {
     });
 }
 exports.buildPlacePerpOrderInstruction = buildPlacePerpOrderInstruction;
+/**
+ * Builds a `placeAndTakePerpOrder` instruction: places an order and immediately attempts
+ * to fill it as a taker against the AMM and/or the supplied maker accounts.
+ * `orderParams.postOnly` must be `PostOnlyParam.None` (`InvalidOrderPostOnly` otherwise).
+ * Any portion left unfilled is auto-cancelled when the order is (or becomes, via
+ * `optionalParams`) immediate-or-cancel.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`triggerPrice`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.optionalParams - packed `u32` combining a `PlaceAndTakeOrderSuccessCondition` (fail the tx if not at least partially/fully filled) and an auction-duration percentage override; `null` for default behavior. Passing any non-null value also forces IOC cancel-remainder semantics.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the taker's `User` account.
+ * @param args.userStats - the taker's `UserStats` PDA.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `orderParams.marketIndex`, followed by maker/referrer `(User, UserStats)` pairs, followed by the taker's `RevenueShareEscrow` account if builder codes are enabled.
+ * @returns the unsigned `placeAndTakePerpOrder` `TransactionInstruction`.
+ */
 async function buildPlaceAndTakePerpOrderInstruction(args) {
     return await args.program.instruction.placeAndTakePerpOrder(args.orderParams, args.optionalParams, {
         accounts: {
@@ -25,6 +54,23 @@ async function buildPlaceAndTakePerpOrderInstruction(args) {
     });
 }
 exports.buildPlaceAndTakePerpOrderInstruction = buildPlaceAndTakePerpOrderInstruction;
+/**
+ * Builds a `placeAndMakePerpOrder` instruction: posts an immediate-or-cancel, post-only
+ * `Limit` order for `user` and immediately fills it as the maker against `taker`'s
+ * existing resting order (`InvalidOrderIOCPostOnly` if `orderParams` isn't IOC + post-only
+ * + `Limit`). Any unfilled remainder of the just-placed maker order is auto-cancelled.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderParams - an `OrderParams` object; `baseAssetAmount` is BASE_PRECISION (1e9), `price`/`oraclePriceOffset` are PRICE_PRECISION (1e6).
+ * @param args.takerOrderId - the on-chain order ID of `taker`'s resting order being filled.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the maker's `User` account.
+ * @param args.userStats - the maker's `UserStats` PDA.
+ * @param args.taker - the taker's `User` account (order owner being filled).
+ * @param args.takerStats - the taker's `UserStats` PDA.
+ * @param args.authority - signer that must own or be a registered delegate of `user` (the maker).
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `orderParams.marketIndex`, followed by any additional maker/referrer `(User, UserStats)` pairs needed to fill `taker`'s order, followed by `taker`'s `RevenueShareEscrow` account if builder codes are enabled.
+ * @returns the unsigned `placeAndMakePerpOrder` `TransactionInstruction`.
+ */
 async function buildPlaceAndMakePerpOrderInstruction(args) {
     return await args.program.instruction.placeAndMakePerpOrder(args.orderParams, args.takerOrderId, {
         accounts: {
@@ -52,6 +98,14 @@ exports.buildPlaceAndMakePerpOrderInstruction = buildPlaceAndMakePerpOrderInstru
  * The on-chain `order_id` counter is a monotonically incrementing u32 on the user
  * account, so `get_last_order_id` reliably points to the order placed in the preceding
  * instruction of the same transaction.
+ *
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the order to cancel, or `null` per the above.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled order's auction/oracle-offset price.
+ * @returns the unsigned `cancelOrder` `TransactionInstruction`.
  */
 async function buildCancelOrderInstruction(args) {
     return await args.program.instruction.cancelOrder(args.orderId, {
@@ -64,6 +118,19 @@ async function buildCancelOrderInstruction(args) {
     });
 }
 exports.buildCancelOrderInstruction = buildCancelOrderInstruction;
+/**
+ * Builds a `cancelOrderByUserId` instruction, cancelling the order matching the
+ * caller-assigned `userOrderId` (the `OrderParams.userOrderId` tag set at placement)
+ * rather than the program-assigned order ID.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.userOrderId - the caller-assigned order tag (`u8`) supplied when the order was placed.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.oracle - accepted for forward-compatibility but not required by the current on-chain `cancel_order_by_user_id` accounts (only `state`/`user`/`authority` are used).
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled order's auction/oracle-offset price.
+ * @returns the unsigned `cancelOrderByUserId` `TransactionInstruction`.
+ */
 async function buildCancelOrderByUserIdInstruction(args) {
     return await args.program.instruction.cancelOrderByUserId(args.userOrderId, {
         accounts: {
@@ -76,6 +143,19 @@ async function buildCancelOrderByUserIdInstruction(args) {
     });
 }
 exports.buildCancelOrderByUserIdInstruction = buildCancelOrderByUserIdInstruction;
+/**
+ * Builds a `cancelOrdersByIds` instruction, cancelling multiple orders by their
+ * program-assigned order IDs in one instruction (loops `cancel_order_by_order_id`
+ * on-chain, one order at a time — an order ID that no longer exists is silently
+ * skipped rather than failing the whole instruction).
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderIds - order IDs to cancel; passing `undefined` sends an empty list on-chain (cancels nothing).
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose orders are cancelled.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` needed to re-derive the cancelled orders' auction/oracle-offset prices.
+ * @returns the unsigned `cancelOrdersByIds` `TransactionInstruction`.
+ */
 async function buildCancelOrdersByIdsInstruction(args) {
     return await args.program.instruction.cancelOrdersByIds(args.orderIds, {
         accounts: {
@@ -87,6 +167,19 @@ async function buildCancelOrdersByIdsInstruction(args) {
     });
 }
 exports.buildCancelOrdersByIdsInstruction = buildCancelOrdersByIdsInstruction;
+/**
+ * Builds a `modifyOrder` instruction, mutating an existing resting order in place (e.g.
+ * new price/size/trigger) rather than cancel-and-replace.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the program-assigned order ID to modify (use `buildModifyOrderByUserIdInstruction` to target by the caller-assigned tag instead).
+ * @param args.modifyParams - a `ModifyOrderParams` object; any `baseAssetAmount`/`price`/`triggerPrice` overrides use BASE_PRECISION (1e9) / PRICE_PRECISION (1e6) respectively.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is modified.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `modify_order` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `modifyOrder` `TransactionInstruction`.
+ */
 async function buildModifyOrderInstruction(args) {
     return await args.program.instruction.modifyOrder(args.orderId, args.modifyParams, {
         accounts: {
@@ -99,6 +192,19 @@ async function buildModifyOrderInstruction(args) {
     });
 }
 exports.buildModifyOrderInstruction = buildModifyOrderInstruction;
+/**
+ * Builds a `modifyOrderByUserId` instruction, same as `buildModifyOrderInstruction` but
+ * targeting the order by its caller-assigned `userOrderId` tag.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.userOrderId - the caller-assigned order tag (`u8`) supplied when the order was placed.
+ * @param args.modifyParams - a `ModifyOrderParams` object; any `baseAssetAmount`/`price`/`triggerPrice` overrides use BASE_PRECISION (1e9) / PRICE_PRECISION (1e6) respectively.
+ * @param args.state - the global `State` PDA.
+ * @param args.user - the `User` account whose order is modified.
+ * @param args.userStats - accepted for forward-compatibility but not required by the current on-chain `modify_order_by_user_id` accounts.
+ * @param args.authority - signer that must own or be a registered delegate of `user`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `modifyOrderByUserId` `TransactionInstruction`.
+ */
 async function buildModifyOrderByUserIdInstruction(args) {
     return await args.program.instruction.modifyOrderByUserId(args.userOrderId, args.modifyParams, {
         accounts: {

package/lib/node/core/instructions/settlement.d.ts

@@ -1,5 +1,19 @@
 import type { AccountMeta, PublicKey, TransactionInstruction } from '@solana/web3.js';
 import type { VelocityProgram } from '../../config';
+/**
+ * Builds a `settlePnl` instruction, settling `user`'s realized (or, if the market is in
+ * `Settlement` status, expired) perp PnL on `marketIndex` against the quote spot market
+ * vault. Fully permissionless: `authority` does not need to own or be a delegate of
+ * `user` — any signer can crank this.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketIndex - the perp market whose position PnL is settled.
+ * @param args.state - the global `State` PDA.
+ * @param args.authority - any signer; not required to own `user`.
+ * @param args.user - the `User` account being settled.
+ * @param args.spotMarketVault - the quote (market index 0) spot market's token vault PDA.
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `marketIndex`, plus the writable quote spot market, plus (if builder codes are enabled) `user`'s `RevenueShareEscrow` and the revenue-share market map needed to sweep completed builder fees.
+ * @returns the unsigned `settlePnl` `TransactionInstruction`.
+ */
 export declare function buildSettlePnlInstruction(args: {
     program: VelocityProgram;
     marketIndex: number;

package/lib/node/core/instructions/settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACrD,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,eAAe,EAAE,SAAS,CAAC;IAC3B,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAUlC"}
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACrD,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,eAAe,EAAE,SAAS,CAAC;IAC3B,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAUlC"}

package/lib/node/core/instructions/settlement.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSettlePnlInstruction = void 0;
+/**
+ * Builds a `settlePnl` instruction, settling `user`'s realized (or, if the market is in
+ * `Settlement` status, expired) perp PnL on `marketIndex` against the quote spot market
+ * vault. Fully permissionless: `authority` does not need to own or be a delegate of
+ * `user` — any signer can crank this.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketIndex - the perp market whose position PnL is settled.
+ * @param args.state - the global `State` PDA.
+ * @param args.authority - any signer; not required to own `user`.
+ * @param args.user - the `User` account being settled.
+ * @param args.spotMarketVault - the quote (market index 0) spot market's token vault PDA.
+ * @param args.remainingAccounts - writable perp market + oracle `AccountMeta[]` for `marketIndex`, plus the writable quote spot market, plus (if builder codes are enabled) `user`'s `RevenueShareEscrow` and the revenue-share market map needed to sweep completed builder fees.
+ * @returns the unsigned `settlePnl` `TransactionInstruction`.
+ */
 async function buildSettlePnlInstruction(args) {
     return await args.program.instruction.settlePnl(args.marketIndex, {
         accounts: {

package/lib/node/core/instructions/trigger.d.ts

@@ -1,5 +1,20 @@
 import type { AccountMeta, PublicKey, TransactionInstruction } from '@solana/web3.js';
 import type { VelocityProgram } from '../../config';
+/**
+ * Builds a `triggerOrder` instruction, flipping a resting trigger order (stop-loss /
+ * take-profit) into a fillable order once its trigger condition is met against the
+ * oracle price. Permissionless: `user` (the order owner) does not need to sign — only
+ * `authority` (owner/delegate of `filler`) does. Does not fill the order itself; a
+ * subsequent `fillPerpOrder` (or a `placeAndTake`) is needed to execute it.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the trigger order's on-chain order ID.
+ * @param args.state - the global `State` PDA.
+ * @param args.filler - the keeper's `User` account submitting the trigger.
+ * @param args.user - the order owner's `User` account.
+ * @param args.authority - signer that must own or be a registered delegate of `filler`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `triggerOrder` `TransactionInstruction`.
+ */
 export declare function buildTriggerOrderInstruction(args: {
     program: VelocityProgram;
     orderId: number;

package/lib/node/core/instructions/trigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trigger.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/trigger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAUlC"}
+{"version":3,"file":"trigger.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/trigger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAUlC"}

package/lib/node/core/instructions/trigger.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildTriggerOrderInstruction = void 0;
+/**
+ * Builds a `triggerOrder` instruction, flipping a resting trigger order (stop-loss /
+ * take-profit) into a fillable order once its trigger condition is met against the
+ * oracle price. Permissionless: `user` (the order owner) does not need to sign — only
+ * `authority` (owner/delegate of `filler`) does. Does not fill the order itself; a
+ * subsequent `fillPerpOrder` (or a `placeAndTake`) is needed to execute it.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.orderId - the trigger order's on-chain order ID.
+ * @param args.state - the global `State` PDA.
+ * @param args.filler - the keeper's `User` account submitting the trigger.
+ * @param args.user - the order owner's `User` account.
+ * @param args.authority - signer that must own or be a registered delegate of `filler`.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for the order's market.
+ * @returns the unsigned `triggerOrder` `TransactionInstruction`.
+ */
 async function buildTriggerOrderInstruction(args) {
     return await args.program.instruction.triggerOrder(args.orderId, {
         accounts: {

package/lib/node/core/instructions/withdraw.d.ts

@@ -1,6 +1,27 @@
 import type { AccountMeta, PublicKey, TransactionInstruction } from '@solana/web3.js';
 import type { BN } from '../../isomorphic/anchor';
 import type { VelocityProgram } from '../../config';
+/**
+ * Builds a `withdraw` instruction, transferring tokens from the protocol's
+ * `spotMarketVault` to `userTokenAccount` and debiting (or borrowing against) `user`'s
+ * spot position. Unlike deposit, `authority` must equal `user`'s own `authority` field
+ * (and `userStats`'s) — delegates cannot withdraw.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketIndex - source spot market index.
+ * @param args.amount - withdrawal amount, in the spot market's mint's native token precision.
+ * @param args.reduceOnly - if true (or the market is reduce-only), caps the withdrawal to the user's current deposit balance so it can only reduce a deposit, never open/increase a borrow.
+ * @param args.state - the global `State` PDA.
+ * @param args.spotMarket - the source `SpotMarket` PDA.
+ * @param args.spotMarketVault - the spot market's token vault PDA (transfer source).
+ * @param args.velocitySigner - the program's PDA signer authority; must equal `state.signer` or the instruction throws (used as the CPI signer for the vault-to-user transfer).
+ * @param args.user - the `User` account being debited; its `authority` must equal `args.authority`.
+ * @param args.userStats - the withdrawing user's `UserStats` PDA; its `authority` must also equal `args.authority`.
+ * @param args.userTokenAccount - destination token account; must share a mint with `spotMarketVault`.
+ * @param args.authority - signer that must equal `user.authority` (and `userStats.authority`).
+ * @param args.tokenProgram - the SPL Token or Token-2022 program owning the mint.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for `marketIndex`, plus the withdrawn mint account, plus any Token-2022 transfer-hook accounts.
+ * @returns the unsigned `withdraw` `TransactionInstruction`.
+ */
 export declare function buildWithdrawInstruction(args: {
     program: VelocityProgram;
     marketIndex: number;

package/lib/node/core/instructions/withdraw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdraw.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/withdraw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACpD,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,EAAE,CAAC;IACX,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,SAAS,CAAC;IACtB,eAAe,EAAE,SAAS,CAAC;IAC3B,cAAc,EAAE,SAAS,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,SAAS,CAAC;IACxB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBlC"}
+{"version":3,"file":"withdraw.d.ts","sourceRoot":"","sources":["../../../../src/core/instructions/withdraw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACpD,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,EAAE,CAAC;IACX,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,SAAS,CAAC;IACtB,eAAe,EAAE,SAAS,CAAC;IAC3B,cAAc,EAAE,SAAS,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,SAAS,CAAC;IACxB,iBAAiB,EAAE,WAAW,EAAE,CAAC;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBlC"}

package/lib/node/core/instructions/withdraw.js

@@ -1,6 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildWithdrawInstruction = void 0;
+/**
+ * Builds a `withdraw` instruction, transferring tokens from the protocol's
+ * `spotMarketVault` to `userTokenAccount` and debiting (or borrowing against) `user`'s
+ * spot position. Unlike deposit, `authority` must equal `user`'s own `authority` field
+ * (and `userStats`'s) — delegates cannot withdraw.
+ * @param args.program - Anchor `Program<Velocity>` used to build the instruction.
+ * @param args.marketIndex - source spot market index.
+ * @param args.amount - withdrawal amount, in the spot market's mint's native token precision.
+ * @param args.reduceOnly - if true (or the market is reduce-only), caps the withdrawal to the user's current deposit balance so it can only reduce a deposit, never open/increase a borrow.
+ * @param args.state - the global `State` PDA.
+ * @param args.spotMarket - the source `SpotMarket` PDA.
+ * @param args.spotMarketVault - the spot market's token vault PDA (transfer source).
+ * @param args.velocitySigner - the program's PDA signer authority; must equal `state.signer` or the instruction throws (used as the CPI signer for the vault-to-user transfer).
+ * @param args.user - the `User` account being debited; its `authority` must equal `args.authority`.
+ * @param args.userStats - the withdrawing user's `UserStats` PDA; its `authority` must also equal `args.authority`.
+ * @param args.userTokenAccount - destination token account; must share a mint with `spotMarketVault`.
+ * @param args.authority - signer that must equal `user.authority` (and `userStats.authority`).
+ * @param args.tokenProgram - the SPL Token or Token-2022 program owning the mint.
+ * @param args.remainingAccounts - oracle/market `AccountMeta[]` for `marketIndex`, plus the withdrawn mint account, plus any Token-2022 transfer-hook accounts.
+ * @returns the unsigned `withdraw` `TransactionInstruction`.
+ */
 async function buildWithdrawInstruction(args) {
     return await args.program.instruction.withdraw(args.marketIndex, args.amount, args.reduceOnly, {
         accounts: {