@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/core/instructions/perpOrders.ts

@@ -5,6 +5,19 @@ import type {
 } 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 async function buildPlacePerpOrderInstruction(args: {
 	program: VelocityProgram;
 	orderParams: any;
@@ -28,6 +41,22 @@ export async function buildPlacePerpOrderInstruction(args: {
 	);
 }
 
+/**
+ * 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 async function buildPlaceAndTakePerpOrderInstruction(args: {
 	program: VelocityProgram;
 	orderParams: any;
@@ -53,6 +82,23 @@ export async function buildPlaceAndTakePerpOrderInstruction(args: {
 	);
 }
 
+/**
+ * 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 async function buildPlaceAndMakePerpOrderInstruction(args: {
 	program: VelocityProgram;
 	orderParams: any;
@@ -95,6 +141,14 @@ export async 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 async function buildCancelOrderInstruction(args: {
 	program: VelocityProgram;
@@ -114,6 +168,19 @@ export async function buildCancelOrderInstruction(args: {
 	});
 }
 
+/**
+ * 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 async function buildCancelOrderByUserIdInstruction(args: {
 	program: VelocityProgram;
 	userOrderId: number;
@@ -137,6 +204,19 @@ export async function buildCancelOrderByUserIdInstruction(args: {
 	);
 }
 
+/**
+ * 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 async function buildCancelOrdersByIdsInstruction(args: {
 	program: VelocityProgram;
 	orderIds: number[] | undefined;
@@ -155,6 +235,19 @@ export async function buildCancelOrdersByIdsInstruction(args: {
 	});
 }
 
+/**
+ * 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 async function buildModifyOrderInstruction(args: {
 	program: VelocityProgram;
 	orderId: number;
@@ -180,6 +273,19 @@ export async function buildModifyOrderInstruction(args: {
 	);
 }
 
+/**
+ * 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 async function buildModifyOrderByUserIdInstruction(args: {
 	program: VelocityProgram;
 	userOrderId: number;

package/src/core/instructions/settlement.ts

@@ -5,6 +5,20 @@ import type {
 } 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 async function buildSettlePnlInstruction(args: {
 	program: VelocityProgram;
 	marketIndex: number;

package/src/core/instructions/trigger.ts

@@ -5,6 +5,21 @@ import type {
 } 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 async function buildTriggerOrderInstruction(args: {
 	program: VelocityProgram;
 	orderId: number;

package/src/core/instructions/withdraw.ts

@@ -6,6 +6,27 @@ import type {
 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 async function buildWithdrawInstruction(args: {
 	program: VelocityProgram;
 	marketIndex: number;

package/src/core/remainingAccounts.ts

@@ -9,36 +9,80 @@ import type {
 	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 function getRemainingAccounts(
 	ctx: RemainingAccountsContext,
 	params: RemainingAccountParams

package/src/core/signedMsg.ts

@@ -4,11 +4,32 @@ import type {
 	SignedMsgOrderParamsMessage,
 } from '../types';
 
+/**
+ * Minimal shape of an Anchor `program.coder.types` needed to (de)serialize the
+ * `signedMsgOrderParamsMessage` / `signedMsgOrderParamsDelegateMessage` IDL types —
+ * lets these helpers accept a plain coder without depending on a full `Program`.
+ */
 export type AnchorTypesCoder = {
 	encode: (typeName: string, value: any) => Buffer;
 	decode: (typeName: string, buffer: Buffer) => any;
 };
 
+/**
+ * Borsh-encodes a Swift signed-order message envelope: an 8-byte Anchor type
+ * discriminator (`sha256("global:SignedMsgOrderParamsMessage" | "...Delegate...")[0..8]`)
+ * followed by the Borsh-serialized message body. This is the exact byte layout the
+ * taker/delegate signs off-chain and the Swift server / `placeAndMakeSignedMsgPerpOrder`
+ * verifies and decodes on submission.
+ *
+ * `maxMarginRatio`/`isolatedPositionDeposit` default to `null` when omitted, and
+ * `builderIdx`/`builderFeeTenthBps` default to `null` when omitted — both for
+ * Borsh-Option compatibility with the IDL type, which requires the fields be present.
+ *
+ * @param args.coderTypes - an Anchor types coder (or `AnchorTypesCoder`) that knows the `signedMsgOrderParamsMessage`/`signedMsgOrderParamsDelegateMessage` IDL types.
+ * @param args.orderParamsMessage - the order params message to encode; a plain `SignedMsgOrderParamsMessage` or, if `delegateSigner` is true, a `SignedMsgOrderParamsDelegateMessage`.
+ * @param args.delegateSigner - whether this message is signed by a delegate rather than the account owner; selects both the discriminator and the IDL type used to encode the body. Defaults to `false`.
+ * @returns the discriminator-prefixed Borsh buffer, ready to be signed and submitted.
+ */
 export function encodeSignedMsgOrderParamsMessage(args: {
 	coderTypes: AnchorTypesCoder;
 	orderParamsMessage:
@@ -56,6 +77,23 @@ export function encodeSignedMsgOrderParamsMessage(args: {
 	return Buffer.concat([prefix, body]);
 }
 
+/**
+ * Decodes a Swift signed-order message envelope produced by
+ * `encodeSignedMsgOrderParamsMessage`: strips the leading 8-byte discriminator and
+ * Borsh-deserializes the remainder as either `signedMsgOrderParamsMessage` or
+ * `signedMsgOrderParamsDelegateMessage`.
+ *
+ * Zero-pads the buffer with 128 extra bytes before decoding, so a message encoded by an
+ * older/smaller IDL (missing newer optional fields) still deserializes instead of
+ * throwing on a short read. This only works because new fields are `Option`s — if the
+ * current IDL's type were ever more than 128 bytes larger than the incoming message,
+ * decoding would still fail.
+ *
+ * @param args.coderTypes - an Anchor types coder (or `AnchorTypesCoder`) that knows the `signedMsgOrderParamsMessage`/`signedMsgOrderParamsDelegateMessage` IDL types.
+ * @param args.encodedMessage - the discriminator-prefixed buffer to decode (as produced by `encodeSignedMsgOrderParamsMessage`).
+ * @param args.delegateSigner - whether to decode as a `SignedMsgOrderParamsDelegateMessage` rather than `SignedMsgOrderParamsMessage`. Must match how the message was encoded. Defaults to `false`.
+ * @returns the decoded `SignedMsgOrderParamsMessage` or `SignedMsgOrderParamsDelegateMessage`.
+ */
 export function decodeSignedMsgOrderParamsMessage(args: {
 	coderTypes: AnchorTypesCoder;
 	encodedMessage: Buffer;

package/src/decode/customCoder.ts

@@ -7,6 +7,13 @@ import {
 	BorshCoder,
 } from '../isomorphic/anchor';
 
+/**
+ * Drop-in replacement for Anchor's `BorshCoder` that swaps in `CustomBorshAccountsCoder` for
+ * account (de)serialization while delegating instruction/event/type coding to the stock Anchor
+ * coder. Use this as the `coder` passed to `new Program(idl, provider, coder)` wherever an
+ * account may be re-encoded (e.g. test fixtures), since the stock coder's `encode()` can
+ * under-allocate its buffer for large accounts (see `CustomBorshAccountsCoder.encode`).
+ */
 export class CustomBorshCoder<
 	A extends string = string,
 	_T extends string = string,
@@ -55,6 +62,18 @@ export class CustomBorshAccountsCoder<A extends string = string> {
 		this.idl = idl;
 	}
 
+	/**
+	 * Encodes an account struct to its on-chain byte representation (8-byte discriminator +
+	 * Borsh-serialized fields). Unlike Anchor's stock `BorshAccountsCoder.encode` — which
+	 * allocates a hardcoded 1000-byte scratch buffer and silently truncates/corrupts any account
+	 * larger than that (e.g. `User` at ~4.5KB, `PerpMarket`) — this computes the buffer size from
+	 * the IDL layout via `this.baseCoder.size(accountName)` (floored at 1000 bytes for small
+	 * accounts) so large accounts encode correctly.
+	 * @param accountName - IDL account type name (e.g. `"User"`, `"PerpMarket"`).
+	 * @param account - The decoded account value to serialize.
+	 * @returns The encoded account bytes, discriminator included.
+	 * @throws Error if `accountName` is not present in the IDL's account layouts.
+	 */
 	public async encode<T = any>(accountName: A, account: T): Promise<Buffer> {
 		const layout = (this.baseCoder as any)['accountLayouts'].get(accountName);
 		if (!layout) {
@@ -71,30 +90,54 @@ export class CustomBorshAccountsCoder<A extends string = string> {
 	}
 
 	// Delegate all other methods to the base coder
+	/** Decodes and validates an account's discriminator, delegating to Anchor's `BorshAccountsCoder.decode`. */
 	public decode<T = any>(accountName: A, data: Buffer): T {
 		return this.baseCoder.decode(accountName, data);
 	}
 
+	/** Decodes an account by inspecting its discriminator to determine its type, delegating to Anchor's `BorshAccountsCoder.decodeAny`. */
 	public decodeAny<T = any>(data: Buffer): T {
 		return this.baseCoder.decodeAny(data);
 	}
 
+	/** Decodes an account without discriminator validation, delegating to Anchor's `BorshAccountsCoder.decodeUnchecked`. */
 	public decodeUnchecked<T = any>(accountName: A, ix: Buffer): T {
 		return this.baseCoder.decodeUnchecked(accountName, ix);
 	}
 
+	/** Builds a memcmp filter for `accountName`'s discriminator (optionally with `appendData`), delegating to Anchor's `BorshAccountsCoder.memcmp`. */
 	public memcmp(accountName: A, appendData?: Buffer): any {
 		return this.baseCoder.memcmp(accountName, appendData);
 	}
 
+	/** Returns the fixed on-chain byte size (including discriminator) of `accountName`, delegating to Anchor's `BorshAccountsCoder.size`. */
 	public size(accountName: A | string): number {
 		return this.baseCoder.size(accountName as A);
 	}
 
 	/**
-	 * Calculates and returns a unique 8 byte discriminator prepended to all anchor accounts.
-	 *
-	 * @param name The name of the account to get the discriminator of.
+	 * Returns the 8-byte account discriminator for `accountName`, read from the IDL-derived
+	 * account layout (Anchor 0.32+ derives discriminators from the IDL rather than a static
+	 * `sha256("account:Name")` hash). This is the instance-scoped counterpart to the throwing
+	 * static `accountDiscriminator` stub.
+	 * @param accountName - IDL account type name (e.g. `"User"`, `"PerpMarket"`).
+	 * @throws Error if `accountName` is not present in the IDL's account layouts.
+	 */
+	public accountDiscriminator(accountName: A): Buffer {
+		const layout = (this.baseCoder as any)['accountLayouts'].get(accountName);
+		if (!layout) {
+			throw new Error(`Unknown account: ${accountName}`);
+		}
+		return Buffer.from(layout.discriminator);
+	}
+
+	/**
+	 * Always throws. Anchor 0.32+ derives account discriminators from the IDL rather than a
+	 * static `sha256("account:Name")` hash, so no *static* method can compute one without an
+	 * IDL instance — this stub exists only to satisfy code written against Anchor's older static
+	 * `BorshAccountsCoder.accountDiscriminator(name)` API.
+	 * @param _name - Unused.
+	 * @throws Error always; use the instance-scoped `accountDiscriminator` on a coder built from an IDL instead.
 	 */
 	public static accountDiscriminator(_name: string): Buffer {
 		// Delegate to an instance method since anchor 0.32 uses IDL discriminators

package/src/decode/user.ts

@@ -29,6 +29,28 @@ function readSignedBigInt64LE(buffer: Buffer, offset: number): BN {
 	}
 }
 
+/**
+ * Hand-rolled, offset-based decoder for the `User` account, used as a fast path instead of
+ * Anchor's generic Borsh decoder in hot paths (e.g. bulk DLOB/account-map refreshes). Byte offsets
+ * here are hardcoded to the current on-chain `User` layout and must be kept in sync with any
+ * change to `programs/velocity/src/state/user.rs` — see the offset notes in `../memcmp.ts`
+ * (`USER_IDLE_OFFSET` etc.), which mirror this same layout and will silently return zero matches
+ * if this decoder and those offsets drift apart.
+ *
+ * Empty slots are skipped without full-field decoding: a spot position is treated as unused when
+ * `scaledBalance == 0 && openOrders == 0`; a perp position when `baseAssetAmount`,
+ * `quoteAssetAmount`, and `isolatedPositionScaledBalance` are all 0, `openOrders == 0`, and
+ * neither `BeingLiquidated` nor `Bankruptcy` position flags are set; an order slot when its
+ * `status` byte isn't `1` (`OrderStatus.OPEN`) — in all three cases the skipped slot is omitted
+ * from the returned array entirely (only active entries are pushed), so the array length may be
+ * less than the on-chain fixed slot count.
+ * @param buffer - Raw `User` account data, including its 8-byte Anchor discriminator (skipped internally).
+ * @returns The decoded `UserAccount`. Amount/price fields retain on-chain precision (e.g.
+ * `baseAssetAmount`/`openBids`/`openAsks` in BASE_PRECISION 1e9, `quoteAssetAmount` and other
+ * quote-denominated fields in QUOTE_PRECISION 1e6, order `price`/`triggerPrice`/auction prices in
+ * PRICE_PRECISION 1e6) — this function only re-parses bytes, it does not rescale anything.
+ * @throws Error if an order's encoded `status`, `orderType`, or `triggerCondition` byte doesn't match a known enum value.
+ */
 export function decodeUser(buffer: Buffer): UserAccount {
 	let offset = 8;
 	const authority = new PublicKey(buffer.slice(offset, offset + 32));