@velocity-exchange/sdk 0.2.5 → 0.4.0

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

@@ -1,28 +1,72 @@
 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[];
 //# sourceMappingURL=remainingAccounts.d.ts.map

package/lib/node/core/remainingAccounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remainingAccounts.d.ts","sourceRoot":"","sources":["../../../src/core/remainingAccounts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAK9D,OAAO,KAAK,EACX,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,sBAAsB,GAAG;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,uBAAuB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5C,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACtC,uCAAuC;IACvC,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACjE,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,iBAAiB,CAAC;IAEjE,+DAA+D;IAC/D,qBAAqB,EAAE,CACtB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,SAAS,KAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAElC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,SAAS,EAAE,SAAS,CAAC;IAErB,6DAA6D;IAC7D,uBAAuB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,uBAAuB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,wBAAwB,EAC7B,MAAM,EAAE,sBAAsB,GAC5B,WAAW,EAAE,CA6Hf"}
+{"version":3,"file":"remainingAccounts.d.ts","sourceRoot":"","sources":["../../../src/core/remainingAccounts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAK9D,OAAO,KAAK,EACX,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,MAAM,UAAU,CAAC;AAElB;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,mMAAmM;IACnM,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,+JAA+J;IAC/J,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,yIAAyI;IACzI,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,qJAAqJ;IACrJ,uBAAuB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5C,uEAAuE;IACvE,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,8cAA8c;IAC9c,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACtC,2NAA2N;IAC3N,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACjE,wGAAwG;IACxG,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,iBAAiB,CAAC;IAEjE,uSAAuS;IACvS,qBAAqB,EAAE,CACtB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,SAAS,KAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAElC,0JAA0J;IAC1J,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,sFAAsF;IACtF,SAAS,EAAE,SAAS,CAAC;IAErB,uKAAuK;IACvK,uBAAuB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,uKAAuK;IACvK,uBAAuB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,mMAAmM;IACnM,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,kHAAkH;IAClH,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,wBAAwB,EAC7B,MAAM,EAAE,sBAAsB,GAC5B,WAAW,EAAE,CA6Hf"}

package/lib/node/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);

package/lib/node/core/signedMsg.d.ts

@@ -1,15 +1,53 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import type { SignedMsgOrderParamsDelegateMessage, 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 declare function encodeSignedMsgOrderParamsMessage(args: {
     coderTypes: AnchorTypesCoder;
     orderParamsMessage: SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage;
     delegateSigner?: boolean;
 }): Buffer;
+/**
+ * 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 declare function decodeSignedMsgOrderParamsMessage(args: {
     coderTypes: AnchorTypesCoder;
     encodedMessage: Buffer;

package/lib/node/core/signedMsg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signedMsg.d.ts","sourceRoot":"","sources":["../../../src/core/signedMsg.ts"],"names":[],"mappings":";;AACA,OAAO,KAAK,EACX,mCAAmC,EACnC,2BAA2B,EAC3B,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC;IACjD,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,CAAC;CAClD,CAAC;AAEF,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,kBAAkB,EACf,2BAA2B,GAC3B,mCAAmC,CAAC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,MAAM,CAuCT;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,2BAA2B,GAAG,mCAAmC,CAQpE"}
+{"version":3,"file":"signedMsg.d.ts","sourceRoot":"","sources":["../../../src/core/signedMsg.ts"],"names":[],"mappings":";;AACA,OAAO,KAAK,EACX,mCAAmC,EACnC,2BAA2B,EAC3B,MAAM,UAAU,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC;IACjD,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,CAAC;CAClD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,kBAAkB,EACf,2BAA2B,GAC3B,mCAAmC,CAAC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,MAAM,CAuCT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,2BAA2B,GAAG,mCAAmC,CAQpE"}

package/lib/node/core/signedMsg.js

@@ -2,6 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeSignedMsgOrderParamsMessage = exports.encodeSignedMsgOrderParamsMessage = void 0;
 const sha256_1 = require("@noble/hashes/sha256");
+/**
+ * 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.
+ */
 function encodeSignedMsgOrderParamsMessage(args) {
     const { coderTypes, delegateSigner } = args;
     const orderParamsMessage = { ...args.orderParamsMessage };
@@ -30,6 +46,23 @@ function encodeSignedMsgOrderParamsMessage(args) {
     return Buffer.concat([prefix, body]);
 }
 exports.encodeSignedMsgOrderParamsMessage = encodeSignedMsgOrderParamsMessage;
+/**
+ * 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`.
+ */
 function decodeSignedMsgOrderParamsMessage(args) {
     const decodeStr = args.delegateSigner
         ? 'signedMsgOrderParamsDelegateMessage'

package/lib/node/decode/customCoder.d.ts

@@ -2,6 +2,13 @@
 /// <reference types="node" />
 import { Buffer } from 'buffer';
 import { Idl, BorshEventCoder, BorshInstructionCoder } 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 declare class CustomBorshCoder<A extends string = string, _T extends string = string> {
     readonly idl: Idl;
     /**
@@ -29,16 +36,45 @@ export declare class CustomBorshAccountsCoder<A extends string = string> {
     private baseCoder;
     private idl;
     constructor(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.
+     */
     encode<T = any>(accountName: A, account: T): Promise<Buffer>;
+    /** Decodes and validates an account's discriminator, delegating to Anchor's `BorshAccountsCoder.decode`. */
     decode<T = any>(accountName: A, data: Buffer): T;
+    /** Decodes an account by inspecting its discriminator to determine its type, delegating to Anchor's `BorshAccountsCoder.decodeAny`. */
     decodeAny<T = any>(data: Buffer): T;
+    /** Decodes an account without discriminator validation, delegating to Anchor's `BorshAccountsCoder.decodeUnchecked`. */
     decodeUnchecked<T = any>(accountName: A, ix: Buffer): T;
+    /** Builds a memcmp filter for `accountName`'s discriminator (optionally with `appendData`), delegating to Anchor's `BorshAccountsCoder.memcmp`. */
     memcmp(accountName: A, appendData?: Buffer): any;
+    /** Returns the fixed on-chain byte size (including discriminator) of `accountName`, delegating to Anchor's `BorshAccountsCoder.size`. */
     size(accountName: A | string): number;
     /**
-     * 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.
+     */
+    accountDiscriminator(accountName: A): Buffer;
+    /**
+     * 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.
      */
     static accountDiscriminator(_name: string): Buffer;
 }

package/lib/node/decode/customCoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"customCoder.d.ts","sourceRoot":"","sources":["../../../src/decode/customCoder.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EACN,GAAG,EAEH,eAAe,EACf,qBAAqB,EAErB,MAAM,sBAAsB,CAAC;AAE9B,qBAAa,gBAAgB,CAC5B,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,EAAE,SAAS,MAAM,GAAG,MAAM;IAE1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;gBAER,GAAG,EAAE,GAAG;CAQpB;AAED;;GAEG;AACH,qBAAa,wBAAwB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC9D,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,GAAG,CAAM;gBAEE,GAAG,EAAE,GAAG;IAKd,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBlE,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAIhD,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAInC,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC;IAIvD,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,GAAG;IAIhD,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,GAAG,MAAM;IAI5C;;;;OAIG;WACW,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAMzD"}
+{"version":3,"file":"customCoder.d.ts","sourceRoot":"","sources":["../../../src/decode/customCoder.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EACN,GAAG,EAEH,eAAe,EACf,qBAAqB,EAErB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,qBAAa,gBAAgB,CAC5B,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,EAAE,SAAS,MAAM,GAAG,MAAM;IAE1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;gBAER,GAAG,EAAE,GAAG;CAQpB;AAED;;GAEG;AACH,qBAAa,wBAAwB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC9D,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,GAAG,CAAM;gBAEE,GAAG,EAAE,GAAG;IAK3B;;;;;;;;;;;OAWG;IACU,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBzE,4GAA4G;IACrG,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAIvD,uIAAuI;IAChI,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAI1C,wHAAwH;IACjH,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC;IAI9D,mJAAmJ;IAC5I,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,GAAG;IAIvD,yIAAyI;IAClI,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,GAAG,MAAM;IAI5C;;;;;;;OAOG;IACI,oBAAoB,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM;IAQnD;;;;;;;OAOG;WACW,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAMzD"}

package/lib/node/decode/customCoder.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomBorshAccountsCoder = exports.CustomBorshCoder = void 0;
 const buffer_1 = require("buffer");
 const anchor_1 = require("../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`).
+ */
 class CustomBorshCoder {
     constructor(idl) {
         const baseCoder = new anchor_1.BorshCoder(idl);
@@ -22,6 +29,18 @@ class CustomBorshAccountsCoder {
         this.baseCoder = new anchor_1.BorshAccountsCoder(idl);
         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.
+     */
     async encode(accountName, account) {
         const layout = this.baseCoder['accountLayouts'].get(accountName);
         if (!layout) {
@@ -36,25 +55,48 @@ class CustomBorshAccountsCoder {
         return buffer_1.Buffer.concat([discriminator, accountData]);
     }
     // Delegate all other methods to the base coder
+    /** Decodes and validates an account's discriminator, delegating to Anchor's `BorshAccountsCoder.decode`. */
     decode(accountName, data) {
         return this.baseCoder.decode(accountName, data);
     }
+    /** Decodes an account by inspecting its discriminator to determine its type, delegating to Anchor's `BorshAccountsCoder.decodeAny`. */
     decodeAny(data) {
         return this.baseCoder.decodeAny(data);
     }
+    /** Decodes an account without discriminator validation, delegating to Anchor's `BorshAccountsCoder.decodeUnchecked`. */
     decodeUnchecked(accountName, ix) {
         return this.baseCoder.decodeUnchecked(accountName, ix);
     }
+    /** Builds a memcmp filter for `accountName`'s discriminator (optionally with `appendData`), delegating to Anchor's `BorshAccountsCoder.memcmp`. */
     memcmp(accountName, appendData) {
         return this.baseCoder.memcmp(accountName, appendData);
     }
+    /** Returns the fixed on-chain byte size (including discriminator) of `accountName`, delegating to Anchor's `BorshAccountsCoder.size`. */
     size(accountName) {
         return this.baseCoder.size(accountName);
     }
     /**
-     * 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.
+     */
+    accountDiscriminator(accountName) {
+        const layout = this.baseCoder['accountLayouts'].get(accountName);
+        if (!layout) {
+            throw new Error(`Unknown account: ${accountName}`);
+        }
+        return buffer_1.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.
      */
     static accountDiscriminator(_name) {
         // Delegate to an instance method since anchor 0.32 uses IDL discriminators

package/lib/node/decode/user.d.ts

@@ -1,5 +1,27 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { UserAccount } from '../types';
+/**
+ * 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 declare function decodeUser(buffer: Buffer): UserAccount;
 //# sourceMappingURL=user.d.ts.map

package/lib/node/decode/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/decode/user.ts"],"names":[],"mappings":";;AACA,OAAO,EAWN,WAAW,EACX,MAAM,UAAU,CAAC;AAkBlB,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA2VtD"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/decode/user.ts"],"names":[],"mappings":";;AACA,OAAO,EAWN,WAAW,EACX,MAAM,UAAU,CAAC;AAkBlB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA2VtD"}

package/lib/node/decode/user.js

@@ -18,6 +18,28 @@ function readSignedBigInt64LE(buffer, offset) {
         return unsignedValue;
     }
 }
+/**
+ * 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.
+ */
 function decodeUser(buffer) {
     let offset = 8;
     const authority = new web3_js_1.PublicKey(buffer.slice(offset, offset + 32));