@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/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/browser/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/browser/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/browser/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/browser/decode/user.d.ts

@@ -1,4 +1,26 @@
 /// <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;

package/lib/browser/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));
@@ -311,7 +333,10 @@ function decodeUser(buffer) {
     offset += 1;
     const specialUserStatus = buffer.readUInt8(offset);
     offset += 1;
-    offset += 14; // padding
+    offset += 3; // padding
+    const equityFloor = readUnsignedBigInt64LE(buffer, offset);
+    offset += 8;
+    offset += 8; // padding2
     return {
         authority,
         delegate,
@@ -340,6 +365,7 @@ function decodeUser(buffer) {
         hasOpenAuction,
         poolId,
         specialUserStatus,
+        equityFloor,
     };
 }
 exports.decodeUser = decodeUser;