@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/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/browser/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/browser/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/browser/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/browser/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/browser/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/browser/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/browser/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/browser/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: {

package/lib/browser/core/remainingAccounts.d.ts

@@ -1,27 +1,71 @@
 import { PublicKey, type AccountMeta } from '@solana/web3.js';
 import type { UserAccount, SpotMarketAccount, PerpMarketAccount } from '../types';
+/**
+ * Per-call inputs to `getRemainingAccounts`, describing which markets and users' open
+ * positions must be represented in the built `remainingAccounts` list.
+ */
 export type RemainingAccountParams = {
+    /** Every open (non-available) spot/perp position across these accounts is included — this is how a `User`'s own margined positions get their market + oracle accounts passed to an instruction. */
     userAccounts: UserAccount[];
+    /** Perp market indexes to include as writable (plus their oracle and quote spot market), in addition to whatever `userAccounts`' positions already require. */
     writablePerpMarketIndexes?: number[];
+    /** Spot market indexes to include as writable (plus their oracle), in addition to whatever `userAccounts`' positions already require. */
     writableSpotMarketIndexes?: number[];
+    /** Perp market index(es) to include as read-only (plus their oracle and quote spot market) — typically the market(s) an instruction is acting on. */
     readablePerpMarketIndex?: number | number[];
+    /** Spot market indexes to include as read-only (plus their oracle). */
     readableSpotMarketIndexes?: number[];
+    /** If true, also re-includes any market still tracked in `ctx.perpMarketLastSlotCache` / `ctx.spotMarketLastSlotCache` whose cached slot is newer than the resolved user's last-active slot — a cache-invalidation guard so a market touched by a very recent instruction doesn't get dropped from the very next one before its state can be considered "seen" by the user account. Stale cache entries (slot ≤ the user's last-active slot) are evicted as a side effect. */
     useMarketLastSlotCache?: boolean;
 };
+/**
+ * Caller-supplied hooks and mutable state `getRemainingAccounts` needs to resolve market
+ * accounts and apply cache-invalidation logic without depending on a subscribed
+ * `VelocityClient`. All fields are read (and the `Map`/`Set` fields also mutated in
+ * place — entries may be added or evicted) by `getRemainingAccounts`; the caller owns
+ * their lifetime and should typically persist them across calls for the caches to be
+ * useful.
+ */
 export type RemainingAccountsContext = {
-    /** Used to resolve market accounts. */
+    /** Resolves a perp market index to its loaded `PerpMarketAccount` (including `pubkey`, `oracle`, `oracleSource`, `quoteSpotMarketIndex`). Should throw or the caller should ensure the market is loaded before calling. */
     getPerpMarketAccount: (marketIndex: number) => PerpMarketAccount;
+    /** Resolves a spot market index to its loaded `SpotMarketAccount` (including `pubkey` and `oracle`). */
     getSpotMarketAccount: (marketIndex: number) => SpotMarketAccount;
-    /** Used to resolve user's last slot for cache invalidation. */
+    /** Resolves a user's most recent on-chain-active slot, used to decide whether cached markets from `perpMarketLastSlotCache`/`spotMarketLastSlotCache` are still relevant. Returns `undefined` if the user account isn't known/loaded, in which case cache entries are treated as stale and dropped. */
     getUserAccountAndSlot: (subAccountId: number | undefined, authority: PublicKey) => {
         slot: number;
     } | undefined;
+    /** Sub-account id used (together with `authority`) to look up the acting user when `params.userAccounts` is empty and `useMarketLastSlotCache` is set. */
     activeSubAccountId: number | undefined;
+    /** Wallet authority used (together with `activeSubAccountId`) for the same lookup. */
     authority: PublicKey;
-    /** Mutable caches + forced-market sets (owned by caller). */
+    /** Mutable cache of perp market index → last slot it was touched at; consulted (and pruned) only when `params.useMarketLastSlotCache` is true. Owned by the caller. */
     perpMarketLastSlotCache: Map<number, number>;
+    /** Mutable cache of spot market index → last slot it was touched at; consulted (and pruned) only when `params.useMarketLastSlotCache` is true. Owned by the caller. */
     spotMarketLastSlotCache: Map<number, number>;
+    /** Perp market indexes that must always be included as read-only, regardless of `params` (e.g. markets forced in by other in-flight instructions in the same transaction). Owned by the caller. */
     mustIncludePerpMarketIndexes: Set<number>;
+    /** Spot market indexes that must always be included as read-only, regardless of `params`. Owned by the caller. */
     mustIncludeSpotMarketIndexes: Set<number>;
 };
+/**
+ * Builds the ordered `remainingAccounts: AccountMeta[]` that Velocity trading/keeper
+ * instructions require — one `AccountMeta` per oracle, then per spot market, then per
+ * perp market, deduplicated by pubkey/index. This is the pure, subscription-free
+ * equivalent of `VelocityClient`'s internal remaining-accounts builder: pass it whatever
+ * markets/positions are relevant and it derives the same account set an instruction
+ * builder (`buildDepositInstruction`, `buildPlacePerpOrderInstruction`, etc.) expects in
+ * its `remainingAccounts` argument.
+ *
+ * Every open position on `params.userAccounts` contributes its market (+ oracle); open
+ * spot positions with resting orders (`openAsks`/`openBids` non-zero) also pull in the
+ * quote spot market so margin can be computed against it. `params.writable*`/`readable*`
+ * indexes are added on top, and an oracle is marked writable only for a perp market on a
+ * `prelaunch` oracle source being written to (needed so the prelaunch oracle CPI can
+ * update its own account).
+ *
+ * @param ctx - resolver hooks and caller-owned mutable caches (see `RemainingAccountsContext`).
+ * @param params - which markets/positions to include for this call (see `RemainingAccountParams`).
+ * @returns the deduplicated `AccountMeta[]`, ordered oracles → spot markets → perp markets.
+ */
 export declare function getRemainingAccounts(ctx: RemainingAccountsContext, params: RemainingAccountParams): AccountMeta[];

package/lib/browser/core/remainingAccounts.js

@@ -6,6 +6,26 @@ const types_1 = require("../types");
 const numericConstants_1 = require("../constants/numericConstants");
 const spotPosition_1 = require("../math/spotPosition");
 const position_1 = require("../math/position");
+/**
+ * Builds the ordered `remainingAccounts: AccountMeta[]` that Velocity trading/keeper
+ * instructions require — one `AccountMeta` per oracle, then per spot market, then per
+ * perp market, deduplicated by pubkey/index. This is the pure, subscription-free
+ * equivalent of `VelocityClient`'s internal remaining-accounts builder: pass it whatever
+ * markets/positions are relevant and it derives the same account set an instruction
+ * builder (`buildDepositInstruction`, `buildPlacePerpOrderInstruction`, etc.) expects in
+ * its `remainingAccounts` argument.
+ *
+ * Every open position on `params.userAccounts` contributes its market (+ oracle); open
+ * spot positions with resting orders (`openAsks`/`openBids` non-zero) also pull in the
+ * quote spot market so margin can be computed against it. `params.writable*`/`readable*`
+ * indexes are added on top, and an oracle is marked writable only for a perp market on a
+ * `prelaunch` oracle source being written to (needed so the prelaunch oracle CPI can
+ * update its own account).
+ *
+ * @param ctx - resolver hooks and caller-owned mutable caches (see `RemainingAccountsContext`).
+ * @param params - which markets/positions to include for this call (see `RemainingAccountParams`).
+ * @returns the deduplicated `AccountMeta[]`, ordered oracles → spot markets → perp markets.
+ */
 function getRemainingAccounts(ctx, params) {
     var _a;
     const { oracleAccountMap, spotMarketAccountMap, perpMarketAccountMap } = getRemainingAccountMapsForUsers(ctx, params.userAccounts);