@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/node/math/utils.js

@@ -3,10 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.numberToSafeBN = exports.isBNSafe = exports.checkSameDate = exports.timeRemainingUntilUpdate = exports.sigNum = exports.divCeil = exports.squareRootBN = exports.clampBN = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
+/**
+ * Clamps `x` to the inclusive range `[min, max]`.
+ *
+ * @param {BN} x - The value to clamp
+ * @param {BN} min - The lower bound
+ * @param {BN} max - The upper bound
+ * @return {BN} `x` if within range, otherwise `min` or `max`
+ */
 function clampBN(x, min, max) {
     return anchor_1.BN.max(min, anchor_1.BN.min(x, max));
 }
 exports.clampBN = clampBN;
+/**
+ * Integer square root via binary recursion, floored to the nearest integer (i.e.
+ * `squareRootBN(n) === Math.floor(Math.sqrt(n))` for values representable as a double). Used
+ * throughout the AMM math wherever the program takes an integer sqrt of the constant-product
+ * invariant.
+ *
+ * @param {BN} n - A non-negative integer
+ * @return {BN} `floor(sqrt(n))`
+ * @throws {Error} If `n` is negative
+ */
 const squareRootBN = (n) => {
     if (n.lt(new anchor_1.BN(0))) {
         throw new Error('Sqrt only works on non-negtiave inputs');
@@ -24,6 +42,17 @@ const squareRootBN = (n) => {
     }
 };
 exports.squareRootBN = squareRootBN;
+/**
+ * Integer division rounded up (ceiling), mirroring the program's unsigned `safe_div_ceil` (e.g.
+ * used for borrow token amounts, where rounding up favors the protocol/lenders over the
+ * borrower). Only meaningful for non-negative operands — `bn.js`'s `.mod()` returns a remainder
+ * with the sign of the dividend, so this is not a general-purpose ceiling division for signed
+ * inputs.
+ *
+ * @param {BN} a - The dividend (expected non-negative)
+ * @param {BN} b - The divisor (expected positive)
+ * @return {BN} `ceil(a / b)`
+ */
 const divCeil = (a, b) => {
     const quotient = a.div(b);
     const remainder = a.mod(b);
@@ -35,17 +64,27 @@ const divCeil = (a, b) => {
     }
 };
 exports.divCeil = divCeil;
+/**
+ * Sign function returning ±1 (never 0).
+ *
+ * @param {BN} x - The value to test
+ * @return {BN} `-1` if `x` is negative, otherwise `1` (including for zero)
+ */
 const sigNum = (x) => {
     return x.isNeg() ? new anchor_1.BN(-1) : new anchor_1.BN(1);
 };
 exports.sigNum = sigNum;
 /**
- * calculates the time remaining until the next update based on a rounded, "on-the-hour" update schedule
- * this schedule is used for Perpetual Funding Rate and Revenue -> Insurance Updates
- * @param now: current blockchain unix timestamp
- * @param lastUpdateTs: the unix timestamp of the last update
- * @param updatePeriod: desired interval between updates (in seconds)
- * @returns: timeRemainingUntilUpdate (in seconds)
+ * Calculates the time remaining until the next update is eligible under a rounded, "on-the-hour"
+ * update schedule. Used for perp funding rate updates and revenue-to-insurance-fund sweeps: if the
+ * last update landed within 1/3 of `updatePeriod` of an hour boundary, the next update is allowed
+ * on that boundary; otherwise it's pushed to the following boundary (two periods out) to avoid
+ * drifting the schedule off-hour. Returns zero once the wait has already elapsed.
+ *
+ * @param {BN} now - Current unix timestamp, seconds
+ * @param {BN} lastUpdateTs - Unix timestamp of the last update, seconds
+ * @param {BN} updatePeriod - Desired interval between updates, seconds
+ * @return {BN} Seconds remaining until the next update is eligible (zero if already due)
  */
 function timeRemainingUntilUpdate(now, lastUpdateTs, updatePeriod) {
     const timeSinceLastUpdate = now.sub(lastUpdateTs);
@@ -77,6 +116,15 @@ function timeRemainingUntilUpdate(now, lastUpdateTs, updatePeriod) {
     return timeRemainingUntilUpdate;
 }
 exports.timeRemainingUntilUpdate = timeRemainingUntilUpdate;
+/**
+ * Compares two date strings for equality by calendar day (year/month/date), ignoring
+ * time-of-day. Uses the local `getDate()`/`getMonth()`/`getFullYear()` getters, so the
+ * comparison is against the process's local-timezone calendar day (not UTC).
+ *
+ * @param {string} dateString1 - A date string parseable by `new Date()`
+ * @param {string} dateString2 - A date string parseable by `new Date()`
+ * @return {boolean} Whether both parse to the same calendar day
+ */
 const checkSameDate = (dateString1, dateString2) => {
     const date1 = new Date(dateString1);
     const date2 = new Date(dateString2);
@@ -86,14 +134,28 @@ const checkSameDate = (dateString1, dateString2) => {
     return isSameDate;
 };
 exports.checkSameDate = checkSameDate;
+/**
+ * True if `number` is within `Number.MAX_SAFE_INTEGER` (2^53 - 1), i.e. safe to convert to a
+ * `BN` via a JS `number` without losing precision.
+ *
+ * @param {number} number - The value to check (typically already multiplied by a target precision)
+ * @return {boolean} Whether `number` can be represented exactly as a JS number
+ */
 function isBNSafe(number) {
     return number <= 0x1fffffffffffff;
 }
 exports.isBNSafe = isBNSafe;
 /**
- * Converts a number to BN makes sure the number is safe to convert to BN (that it does not overflow number after multiplying by precision)
- * @param number the number to convert to BN
- * @param precision the BN precision to use (i.e. QUOTE_PRECISION and BASE_PRECISION from velocity sdk)
+ * Converts a human-readable JS `number` into a `BN` scaled by `precision`, routing through a
+ * string conversion (`number.toString()` for whole numbers) instead of `number * precision` when
+ * the naive multiplication would exceed `Number.MAX_SAFE_INTEGER` (per `isBNSafe`), avoiding
+ * silent floating-point precision loss for large inputs. Note a fractional input whose scaled
+ * value exceeds `Number.MAX_SAFE_INTEGER` has its fractional part truncated (`bn.js` accepts only
+ * integer numbers); this is intentional and pinned by `tests/bn/test.ts`.
+ *
+ * @param {number} number - The human-readable amount to convert
+ * @param {BN} precision - The target fixed-point precision (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `number` scaled by `precision`
  */
 function numberToSafeBN(number, precision) {
     // check if number has decimals

package/lib/node/memcmp.d.ts

@@ -1,18 +1,112 @@
 import { MemcmpFilter, PublicKey } from '@solana/web3.js';
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `User` account type at offset 0. Use to fetch all `User` (sub-account) accounts.
+ * @returns A memcmp filter for `User` accounts.
+ */
 export declare function getUserFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `idle` flag (offset 4470) is `false`.
+ * Idle sub-accounts have no open positions/orders and have been inactive past the idle threshold;
+ * this filter excludes them, e.g. when scanning for accounts that need active monitoring.
+ * @returns A memcmp filter for non-idle `User` accounts.
+ */
 export declare function getNonIdleUserFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `true`
+ * — i.e. at least one live order. Used by the DLOB to fetch only accounts that can populate the
+ * order book.
+ * @returns A memcmp filter for `User` accounts with at least one open order.
+ */
 export declare function getUserWithOrderFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `false`
+ * — i.e. no live orders.
+ * @returns A memcmp filter for `User` accounts with no open orders.
+ */
 export declare function getUserWithoutOrderFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenAuction` (offset 4474) set to
+ * `true` — i.e. at least one order still in its Dutch-auction window.
+ * @returns A memcmp filter for `User` accounts with an active order auction.
+ */
 export declare function getUserWithAuctionFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `name` field (32 bytes, offset 72) equals
+ * `name` once encoded/padded the same way as on-chain.
+ * @param name - Human-readable sub-account name to match; encoded via `encodeName` (UTF-8,
+ * space-padded/truncated to 32 bytes) before comparison.
+ * @returns A memcmp filter for `User` accounts with the given name.
+ */
 export declare function getUserWithName(name: string): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `poolId` (single byte, offset 4475) equals
+ * `poolId`. Used to scope account scans to a specific isolated pool.
+ * @param poolId - Pool id byte (0 = main/cross pool) to match.
+ * @returns A memcmp filter for `User` accounts in the given pool.
+ */
 export declare function getUsersWithPoolId(poolId: number): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `UserStats` account type at offset 0. Use to fetch all `UserStats` accounts.
+ * @returns A memcmp filter for `UserStats` accounts.
+ */
 export declare function getUserStatsFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly `ReferrerStatus.IsReferred` (2) — i.e. the account was referred and is *not*
+ * also flagged `IsReferrer`. Because memcmp does an exact byte match rather than a bitwise test,
+ * this excludes accounts that are both `IsReferrer` and `IsReferred` (byte value 3); use
+ * `getUserStatsIsReferredOrReferrerFilter` for that combined case.
+ * @returns A memcmp filter for `UserStats` accounts referred by (but not also referring) another user.
+ */
 export declare function getUserStatsIsReferredFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly 3 — i.e. `ReferrerStatus.IsReferrer | ReferrerStatus.IsReferred` both set on the
+ * same account. Despite the name, this is an exact-byte match (memcmp can't test bits in
+ * isolation), so it does *not* match an account that is only `IsReferrer` (1) or only `IsReferred`
+ * (2) — use `getUserStatsIsReferredFilter` for the referred-only case.
+ * @returns A memcmp filter for `UserStats` accounts with both the referrer and referred flags set.
+ */
 export declare function getUserStatsIsReferredOrReferrerFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SignedMsgUserOrders` account type at offset 0. Use to fetch all swift/signed-message order
+ * accounts.
+ * @returns A memcmp filter for `SignedMsgUserOrders` accounts.
+ */
 export declare function getSignedMsgUserOrdersFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `PerpMarket` account type at offset 0. Use to fetch all perp market accounts.
+ * @returns A memcmp filter for `PerpMarket` accounts.
+ */
 export declare function getPerpMarketAccountsFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SpotMarket` account type at offset 0. Use to fetch all spot market accounts.
+ * @returns A memcmp filter for `SpotMarket` accounts.
+ */
 export declare function getSpotMarketAccountsFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `RevenueShareEscrow` account type at offset 0. Use to fetch all revenue-share escrow accounts
+ * (builder-fee approvals/referral state).
+ * @returns A memcmp filter for `RevenueShareEscrow` accounts.
+ */
 export declare function getRevenueShareEscrowFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `Constituent` account type at offset 0. Use to fetch all LP-pool constituent accounts.
+ * @returns A memcmp filter for `Constituent` accounts.
+ */
 export declare function getConstituentFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `Constituent` accounts belonging to a specific LP pool, by
+ * comparing the `lpPool` pubkey field (32 bytes, offset 72) against `lpPoolPublicKey`.
+ * @param lpPoolPublicKey - The `LpPool` account's pubkey to match constituents against.
+ * @returns A memcmp filter for `Constituent` accounts of the given LP pool.
+ */
 export declare function getConstituentLpPoolFilter(lpPoolPublicKey: PublicKey): MemcmpFilter;
 //# sourceMappingURL=memcmp.d.ts.map

package/lib/node/memcmp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memcmp.d.ts","sourceRoot":"","sources":["../../src/memcmp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK1D,wBAAgB,aAAa,IAAI,YAAY,CAO5C;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAOnD;AAED,wBAAgB,sBAAsB,IAAI,YAAY,CAOrD;AAED,wBAAgB,yBAAyB,IAAI,YAAY,CAOxD;AAED,wBAAgB,wBAAwB,IAAI,YAAY,CAOvD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAO1D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAO/D;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAOjD;AAED,wBAAgB,4BAA4B,IAAI,YAAY,CAO3D;AAED,wBAAgB,sCAAsC,IAAI,YAAY,CAOrE;AAED,wBAAgB,4BAA4B,IAAI,YAAY,CAS3D;AAED,wBAAgB,2BAA2B,IAAI,YAAY,CAO1D;AACD,wBAAgB,2BAA2B,IAAI,YAAY,CAO1D;AAED,wBAAgB,2BAA2B,IAAI,YAAY,CAS1D;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CASnD;AAED,wBAAgB,0BAA0B,CACzC,eAAe,EAAE,SAAS,GACxB,YAAY,CAOd"}
+{"version":3,"file":"memcmp.d.ts","sourceRoot":"","sources":["../../src/memcmp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK1D;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAO5C;AAwBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,CAOnD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,CAOrD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,YAAY,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,YAAY,CAOvD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAOjD;AAUD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,IAAI,YAAY,CAO3D;AAED;;;;;;;GAOG;AACH,wBAAgB,sCAAsC,IAAI,YAAY,CAOrE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,YAAY,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,YAAY,CAO1D;AACD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,YAAY,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,YAAY,CAS1D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,eAAe,EAAE,SAAS,GACxB,YAAY,CAOd"}

package/lib/node/memcmp.js

@@ -7,6 +7,11 @@ exports.getConstituentLpPoolFilter = exports.getConstituentFilter = exports.getR
 const bs58_1 = __importDefault(require("bs58"));
 const anchor29_1 = require("./isomorphic/anchor29");
 const userName_1 = require("./userName");
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `User` account type at offset 0. Use to fetch all `User` (sub-account) accounts.
+ * @returns A memcmp filter for `User` accounts.
+ */
 function getUserFilter() {
     return {
         memcmp: {
@@ -16,42 +21,92 @@ function getUserFilter() {
     };
 }
 exports.getUserFilter = getUserFilter;
+/*
+ * Byte offsets of the trailing scalar flags in the `User` account.
+ *
+ * These MUST match the on-chain `User` layout decoded in `decode/user.ts`. The
+ * current Velocity layout is 4496 bytes, with the tail block laid out as
+ * consecutive single bytes:
+ *   status(4468) isMarginTradingEnabled(4469) idle(4470) openOrders(4471)
+ *   hasOpenOrder(4472) openAuctions(4473) hasOpenAuction(4474) poolId(4475)
+ *   specialUserStatus(4476)
+ *
+ * NOTE: these were previously hardcoded to the older (4376-byte) layout
+ * (idle@4350, hasOpenOrder@4352, ...). After Velocity added fields to
+ * `PerpPosition`, the account grew by 120 bytes and these flags shifted, but
+ * the filters were not updated — so `getUserWithOrderFilter()` matched zero
+ * accounts and the DLOB order book never populated. Keep these in sync with
+ * `decode/user.ts` if the `User` layout changes again.
+ */
+const USER_IDLE_OFFSET = 4470;
+const USER_HAS_OPEN_ORDER_OFFSET = 4472;
+const USER_HAS_OPEN_AUCTION_OFFSET = 4474;
+const USER_POOL_ID_OFFSET = 4475;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `idle` flag (offset 4470) is `false`.
+ * Idle sub-accounts have no open positions/orders and have been inactive past the idle threshold;
+ * this filter excludes them, e.g. when scanning for accounts that need active monitoring.
+ * @returns A memcmp filter for non-idle `User` accounts.
+ */
 function getNonIdleUserFilter() {
     return {
         memcmp: {
-            offset: 4350,
+            offset: USER_IDLE_OFFSET,
             bytes: bs58_1.default.encode(Uint8Array.from([0])),
         },
     };
 }
 exports.getNonIdleUserFilter = getNonIdleUserFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `true`
+ * — i.e. at least one live order. Used by the DLOB to fetch only accounts that can populate the
+ * order book.
+ * @returns A memcmp filter for `User` accounts with at least one open order.
+ */
 function getUserWithOrderFilter() {
     return {
         memcmp: {
-            offset: 4352,
+            offset: USER_HAS_OPEN_ORDER_OFFSET,
             bytes: bs58_1.default.encode(Uint8Array.from([1])),
         },
     };
 }
 exports.getUserWithOrderFilter = getUserWithOrderFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `false`
+ * — i.e. no live orders.
+ * @returns A memcmp filter for `User` accounts with no open orders.
+ */
 function getUserWithoutOrderFilter() {
     return {
         memcmp: {
-            offset: 4352,
+            offset: USER_HAS_OPEN_ORDER_OFFSET,
             bytes: bs58_1.default.encode(Uint8Array.from([0])),
         },
     };
 }
 exports.getUserWithoutOrderFilter = getUserWithoutOrderFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenAuction` (offset 4474) set to
+ * `true` — i.e. at least one order still in its Dutch-auction window.
+ * @returns A memcmp filter for `User` accounts with an active order auction.
+ */
 function getUserWithAuctionFilter() {
     return {
         memcmp: {
-            offset: 4354,
+            offset: USER_HAS_OPEN_AUCTION_OFFSET,
             bytes: bs58_1.default.encode(Uint8Array.from([1])),
         },
     };
 }
 exports.getUserWithAuctionFilter = getUserWithAuctionFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `name` field (32 bytes, offset 72) equals
+ * `name` once encoded/padded the same way as on-chain.
+ * @param name - Human-readable sub-account name to match; encoded via `encodeName` (UTF-8,
+ * space-padded/truncated to 32 bytes) before comparison.
+ * @returns A memcmp filter for `User` accounts with the given name.
+ */
 function getUserWithName(name) {
     return {
         memcmp: {
@@ -61,15 +116,26 @@ function getUserWithName(name) {
     };
 }
 exports.getUserWithName = getUserWithName;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `poolId` (single byte, offset 4475) equals
+ * `poolId`. Used to scope account scans to a specific isolated pool.
+ * @param poolId - Pool id byte (0 = main/cross pool) to match.
+ * @returns A memcmp filter for `User` accounts in the given pool.
+ */
 function getUsersWithPoolId(poolId) {
     return {
         memcmp: {
-            offset: 4356,
+            offset: USER_POOL_ID_OFFSET,
             bytes: bs58_1.default.encode(Uint8Array.from([poolId])),
         },
     };
 }
 exports.getUsersWithPoolId = getUsersWithPoolId;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `UserStats` account type at offset 0. Use to fetch all `UserStats` accounts.
+ * @returns A memcmp filter for `UserStats` accounts.
+ */
 function getUserStatsFilter() {
     return {
         memcmp: {
@@ -79,24 +145,53 @@ function getUserStatsFilter() {
     };
 }
 exports.getUserStatsFilter = getUserStatsFilter;
+/*
+ * Byte offset of `referrer_status` in the `UserStats` account: 8 (discriminator)
+ * + authority(32) + referrer(32) + fees(32) + maker/taker/filler volume 30d(24)
+ * + last maker/taker/filler volume 30d ts(24) + if_staked_quote_asset_amount(8)
+ * + number_of_sub_accounts(2) + number_of_sub_accounts_created(2) = 164.
+ */
+const USER_STATS_REFERRER_STATUS_OFFSET = 164;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly `ReferrerStatus.IsReferred` (2) — i.e. the account was referred and is *not*
+ * also flagged `IsReferrer`. Because memcmp does an exact byte match rather than a bitwise test,
+ * this excludes accounts that are both `IsReferrer` and `IsReferred` (byte value 3); use
+ * `getUserStatsIsReferredOrReferrerFilter` for that combined case.
+ * @returns A memcmp filter for `UserStats` accounts referred by (but not also referring) another user.
+ */
 function getUserStatsIsReferredFilter() {
     return {
         memcmp: {
-            offset: 188,
+            offset: USER_STATS_REFERRER_STATUS_OFFSET,
             bytes: bs58_1.default.encode(Buffer.from(Uint8Array.from([2]))),
         },
     };
 }
 exports.getUserStatsIsReferredFilter = getUserStatsIsReferredFilter;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly 3 — i.e. `ReferrerStatus.IsReferrer | ReferrerStatus.IsReferred` both set on the
+ * same account. Despite the name, this is an exact-byte match (memcmp can't test bits in
+ * isolation), so it does *not* match an account that is only `IsReferrer` (1) or only `IsReferred`
+ * (2) — use `getUserStatsIsReferredFilter` for the referred-only case.
+ * @returns A memcmp filter for `UserStats` accounts with both the referrer and referred flags set.
+ */
 function getUserStatsIsReferredOrReferrerFilter() {
     return {
         memcmp: {
-            offset: 188,
+            offset: USER_STATS_REFERRER_STATUS_OFFSET,
             bytes: bs58_1.default.encode(Buffer.from(Uint8Array.from([3]))),
         },
     };
 }
 exports.getUserStatsIsReferredOrReferrerFilter = getUserStatsIsReferredOrReferrerFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SignedMsgUserOrders` account type at offset 0. Use to fetch all swift/signed-message order
+ * accounts.
+ * @returns A memcmp filter for `SignedMsgUserOrders` accounts.
+ */
 function getSignedMsgUserOrdersFilter() {
     return {
         memcmp: {
@@ -106,6 +201,11 @@ function getSignedMsgUserOrdersFilter() {
     };
 }
 exports.getSignedMsgUserOrdersFilter = getSignedMsgUserOrdersFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `PerpMarket` account type at offset 0. Use to fetch all perp market accounts.
+ * @returns A memcmp filter for `PerpMarket` accounts.
+ */
 function getPerpMarketAccountsFilter() {
     return {
         memcmp: {
@@ -115,6 +215,11 @@ function getPerpMarketAccountsFilter() {
     };
 }
 exports.getPerpMarketAccountsFilter = getPerpMarketAccountsFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SpotMarket` account type at offset 0. Use to fetch all spot market accounts.
+ * @returns A memcmp filter for `SpotMarket` accounts.
+ */
 function getSpotMarketAccountsFilter() {
     return {
         memcmp: {
@@ -124,6 +229,12 @@ function getSpotMarketAccountsFilter() {
     };
 }
 exports.getSpotMarketAccountsFilter = getSpotMarketAccountsFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `RevenueShareEscrow` account type at offset 0. Use to fetch all revenue-share escrow accounts
+ * (builder-fee approvals/referral state).
+ * @returns A memcmp filter for `RevenueShareEscrow` accounts.
+ */
 function getRevenueShareEscrowFilter() {
     return {
         memcmp: {
@@ -133,6 +244,11 @@ function getRevenueShareEscrowFilter() {
     };
 }
 exports.getRevenueShareEscrowFilter = getRevenueShareEscrowFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `Constituent` account type at offset 0. Use to fetch all LP-pool constituent accounts.
+ * @returns A memcmp filter for `Constituent` accounts.
+ */
 function getConstituentFilter() {
     return {
         memcmp: {
@@ -142,6 +258,12 @@ function getConstituentFilter() {
     };
 }
 exports.getConstituentFilter = getConstituentFilter;
+/**
+ * Builds a memcmp filter matching `Constituent` accounts belonging to a specific LP pool, by
+ * comparing the `lpPool` pubkey field (32 bytes, offset 72) against `lpPoolPublicKey`.
+ * @param lpPoolPublicKey - The `LpPool` account's pubkey to match constituents against.
+ * @returns A memcmp filter for `Constituent` accounts of the given LP pool.
+ */
 function getConstituentLpPoolFilter(lpPoolPublicKey) {
     return {
         memcmp: {

package/lib/node/oracles/oracleClientCache.d.ts

@@ -2,9 +2,25 @@ import { OracleClient } from './types';
 import { OracleSource } from '../types';
 import { Connection } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
+/**
+ * Caches one `OracleClient` instance per oracle *source kind* (not per account), so repeated
+ * lookups for the same `OracleSource` variant (e.g. every `pyth1KPull` market) reuse a single
+ * adapter instead of constructing a new one each time.
+ */
 export declare class OracleClientCache {
     cache: Map<string, OracleClient>;
     constructor();
+    /**
+     * Returns the cached `OracleClient` for `oracleSource`'s variant key, constructing and caching
+     * one via `getOracleClient` on first use.
+     * @param oracleSource - Oracle source variant (its top-level key, e.g. `"pyth"`, is the cache key —
+     * note this means all sources sharing a variant name share one client instance regardless of any
+     * other fields on the variant).
+     * @param connection - RPC connection passed through to the client on construction.
+     * @param program - Velocity Anchor program, used by clients that decode via the program's IDL coder.
+     * @returns The `OracleClient` for this source variant.
+     * @throws Error (via `getOracleClient`) if `oracleSource` is not a recognized variant.
+     */
     get(oracleSource: OracleSource, connection: Connection, program: VelocityProgram): OracleClient | undefined;
 }
 //# sourceMappingURL=oracleClientCache.d.ts.map

package/lib/node/oracles/oracleClientCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oracleClientCache.d.ts","sourceRoot":"","sources":["../../../src/oracles/oracleClientCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,qBAAa,iBAAiB;IAC7B,KAAK,4BAAmC;;IAGjC,GAAG,CACT,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,eAAe;CAWzB"}
+{"version":3,"file":"oracleClientCache.d.ts","sourceRoot":"","sources":["../../../src/oracles/oracleClientCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,iBAAiB;IAC7B,KAAK,4BAAmC;;IAGxC;;;;;;;;;;OAUG;IACI,GAAG,CACT,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,eAAe;CAWzB"}

package/lib/node/oracles/oracleClientCache.js

@@ -2,10 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OracleClientCache = void 0;
 const oracleClient_1 = require("../factory/oracleClient");
+/**
+ * Caches one `OracleClient` instance per oracle *source kind* (not per account), so repeated
+ * lookups for the same `OracleSource` variant (e.g. every `pyth1KPull` market) reuse a single
+ * adapter instead of constructing a new one each time.
+ */
 class OracleClientCache {
     constructor() {
         this.cache = new Map();
     }
+    /**
+     * Returns the cached `OracleClient` for `oracleSource`'s variant key, constructing and caching
+     * one via `getOracleClient` on first use.
+     * @param oracleSource - Oracle source variant (its top-level key, e.g. `"pyth"`, is the cache key —
+     * note this means all sources sharing a variant name share one client instance regardless of any
+     * other fields on the variant).
+     * @param connection - RPC connection passed through to the client on construction.
+     * @param program - Velocity Anchor program, used by clients that decode via the program's IDL coder.
+     * @returns The `OracleClient` for this source variant.
+     * @throws Error (via `getOracleClient`) if `oracleSource` is not a recognized variant.
+     */
     get(oracleSource, connection, program) {
         const key = Object.keys(oracleSource)[0];
         if (this.cache.has(key)) {

package/lib/node/oracles/oracleId.d.ts

@@ -1,8 +1,39 @@
 import { PublicKey } from '@solana/web3.js';
 import { OracleSource } from '../types';
+/**
+ * Maps an `OracleSource` enum-object (e.g. `{ pyth: {} }`) to its stable numeric encoding
+ * (`OracleSourceNum`) used as part of an oracle id string. This encoding is SDK-internal — it
+ * is not the on-chain Borsh discriminant (see `OracleSourceNum`).
+ * @param source - The oracle source variant.
+ * @returns The corresponding `OracleSourceNum` value.
+ * @throws Error if `source` doesn't match any known variant.
+ */
 export declare function getOracleSourceNum(source: OracleSource): number;
+/**
+ * Inverse of `getOracleSourceNum`: maps a numeric `OracleSourceNum` back to its `OracleSource`
+ * enum-object.
+ * @param sourceNum - Numeric oracle source encoding.
+ * @returns The corresponding `OracleSource` variant.
+ * @throws Error if `sourceNum` doesn't match any known `OracleSourceNum` value.
+ */
 export declare function getOracleSourceFromNum(sourceNum: number): OracleSource;
+/**
+ * Builds a stable string id for an oracle account, uniquely identifying it by both its address
+ * and the source/decoding scheme to use — the same pubkey can be interpreted under different
+ * `OracleSource`s (e.g. `pyth` vs `pyth1K`) with different results, so the pubkey alone is not a
+ * safe cache/map key.
+ * @param publicKey - The oracle account's address.
+ * @param source - The oracle source variant to decode it as.
+ * @returns A string of the form `"<base58 pubkey>-<OracleSourceNum>"`.
+ */
 export declare function getOracleId(publicKey: PublicKey, source: OracleSource): string;
+/**
+ * Inverse of `getOracleId`: parses an oracle id string back into its pubkey and `OracleSource`.
+ * @param oracleId - An id string previously produced by `getOracleId`.
+ * @returns The decoded `publicKey` and `source`.
+ * @throws Error if the encoded source number doesn't match any known `OracleSourceNum` value, or
+ * `PublicKey` construction fails on a malformed id.
+ */
 export declare function getPublicKeyAndSourceFromOracleId(oracleId: string): {
     publicKey: PublicKey;
     source: OracleSource;

package/lib/node/oracles/oracleId.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oracleId.d.ts","sourceRoot":"","sources":["../../../src/oracles/oracleId.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAC;AAEzD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAqB/D;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAqBtE;AAED,wBAAgB,WAAW,CAC1B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,GAClB,MAAM,CAER;AAED,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG;IACpE,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACrB,CAMA"}
+{"version":3,"file":"oracleId.d.ts","sourceRoot":"","sources":["../../../src/oracles/oracleId.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAsB/D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAsBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,GAClB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG;IACpE,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACrB,CAMA"}