@velocity-exchange/sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @velocity-exchange/sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- [#197](https://github.com/velocity-exchange/velocity-v1/pull/197) [`900c07d`](https://github.com/velocity-exchange/velocity-v1/commit/900c07d9da7e106c82fbe65b3d92226d090bdee9) Thanks [@jordy25519](https://github.com/jordy25519)! - Attach the taker's `RevenueShareEscrow` on perp fills for referred takers. `getFillPerpOrderIx` gains an optional `takerIsReferred` flag; when set (or when the order carries a builder code) the deterministic escrow PDA is added to the fill. This mirrors the on-chain fill gate, which reads `UserStats.referrerStatus` (the `BuilderReferral` bit), so referred takers' fills no longer revert with `UnableToLoadRevenueShareAccount`. `ReferrerMap` gains `isBuilderReferral(authority)` and `mustGetIsBuilderReferral(authority)`, sourcing the bit from the UserStats fetch it already performs.
+
+- [#189](https://github.com/velocity-exchange/velocity-v1/pull/189) [`8df28ac`](https://github.com/velocity-exchange/velocity-v1/commit/8df28ac6d113760ae4a8cdff4ad438cb25efce2c) Thanks [@ChesterSim](https://github.com/ChesterSim)! - Program↔SDK parity fixes from the 2026-07-02 audit: renamed deprecated Switchboard
+  OracleSource keys to match the IDL (fixes a decode crash on affected markets), applied
+  the $100 initial-margin unrealized-PnL cap, standardized auction/limit prices to order
+  tick size across the DLOB, isolated-position handling in bankruptcy/liquidation math,
+  corrected MM-oracle validity gating, referrer_status memcmp offset, PerpOperation and
+  OrderBitFlag bit values, wired five missing event records into EventSubscriber, fixed
+  withdraw-limit divisors, multi-pool margin segregation, referee/builder fee estimation,
+  and added AdminClient.updatePauseAdmin plus admin CLI commands for pause-admin rotation
+  and fee-pool transfers. Also fixed withdrawFromIsolatedPerpPosition's withdraw-all path:
+  it substituted the MIN_I64 sentinel into the instruction's unsigned u64 amount (serializing
+  as 2^63, so full withdrawals always failed on-chain with InsufficientCollateral); it now
+  clamps the request to the position's deposit plus claimable PnL.
+
+  Follow-up completeness fixes: DLOBSubscriber.getL2/getL3 (and the dlob-server publisher) now
+  thread orderTickSize so the public book view is tick-standardized like on-chain; added
+  hasIsolatedMarginBankrupt and wired isolated-only bankruptcy detection into keeper resolution
+  (isIsolatedPositionBankrupt now guards against non-isolated indices); getMarketFees applies the
+  referee discount and calculateFeeForQuoteAmount accepts builder params so both public fee-prediction
+  entry points match on-chain; and isFallbackAvailableLiquiditySource now fully mirrors
+  amm_fill_gates_ok, adding the market-drawdown and MM-vs-exchange oracle volatility gates.
+
+  Low-risk parity follow-ups: MarginCategory now includes 'Fill' as a single shared type, handled
+  across perp margin ratio / unrealized-asset-weight and spot asset/liability weights (the
+  integer-averaged midpoint of initial and maintenance, mirroring get_margin_ratio /
+  get_asset_weight / get_liability_weight) instead of throwing or returning undefined; the
+  worst-tier taker-fee estimate in calculateEntriesEffectOnFreeCollateral now ceil-divides to match
+  calculate_taker_fee; MM-oracle validity is computed with the raw exchange confidence (matching
+  get_mm_oracle_price_data) while the returned MM price keeps its diff-adjusted confidence; and
+  corrected the OracleSourceNum doc (it is an SDK-internal oracle-id encoding, not the on-chain
+  Borsh discriminant).
+
+  Visible/breaking API changes in this release: `OracleSource.SWITCHBOARD` /
+  `OracleSource.SWITCHBOARD_ON_DEMAND` (and the corresponding `OracleSourceNum` entries) are renamed
+  to `DEPRECATED_SWITCHBOARD` / `DEPRECATED_SWITCHBOARD_ON_DEMAND` with no aliases kept for the old
+  names; `ContractType.FUTURE` is renamed to `DEPRECATED_FUTURE`; and `FeatureBitFlags.BUILDER_REFERRAL`
+  is removed outright, since no such on-chain flag exists. Separately, `getLimitPrice` gained a new
+  optional trailing `tickSize` parameter — the existing `fallbackPrice` parameter stays in its original
+  4th position, so old 4-argument call sites keep working unchanged.
+
+### Patch Changes
+
+- [#199](https://github.com/velocity-exchange/velocity-v1/pull/199) [`dff8a47`](https://github.com/velocity-exchange/velocity-v1/commit/dff8a4754f6b736fed330b2ab4fa5685db4f8159) Thanks [@jordy25519](https://github.com/jordy25519)! - Add BTC-PERP (index 1) and ETH-PERP (index 2) to `DevnetPerpMarkets`, reflecting the two Pyth-Lazer perp markets re-created on devnet. ETH-PERP uses lazer feed 2 (real ETH price feed).
+
+- [#193](https://github.com/velocity-exchange/velocity-v1/pull/193) [`bafd699`](https://github.com/velocity-exchange/velocity-v1/commit/bafd6990f8322f232d2f0d17042beb0e9c567164) Thanks [@jordy25519](https://github.com/jordy25519)! - Remove the stale `FettyRIP` (marketIndex 2) entry from `DevnetPerpMarkets`. That perp market was deleted on-chain, but the hand-maintained devnet config still listed it, so consumers that enumerate all perp markets (keeper-bots-v2, dlob-server) crashed with `Perp market config for 2 not found` when resolving the nonexistent market. The devnet config now mirrors on-chain state (SOL-PERP at index 0 only).
+
 ## 0.3.0
 
 ### Minor Changes

package/lib/browser/accounts/basicUserAccountSubscriber.d.ts

@@ -15,15 +15,33 @@ export declare class BasicUserAccountSubscriber implements UserAccountSubscriber
     callbackId?: string;
     errorCallbackId?: string;
     user?: DataAndSlot<UserAccount>;
+    /**
+     * @param userAccountPublicKey Address of the `UserAccount` this subscriber represents (not fetched — used only for identity).
+     * @param data Optional decoded account data to seed with; if omitted, `getUserAccountAndSlot()` returns undefined until `updateData` is called.
+     * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     constructor(userAccountPublicKey: PublicKey, data?: UserAccount, slot?: number);
+    /** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
     subscribe(_userAccount?: UserAccount): Promise<boolean>;
     addToAccountLoader(): Promise<void>;
+    /** No-op; this subscriber never fetches. Data only changes via `updateData`. */
     fetch(): Promise<void>;
+    /** Type predicate: true once `user` has been seeded or set via `updateData`, narrowing `this.user` to non-undefined. */
     doesAccountExist(): this is {
         user: DataAndSlot<UserAccount>;
     };
+    /** No-op; there is no live subscription to tear down. */
     unsubscribe(): Promise<void>;
+    /** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
     assertIsSubscribed(): void;
+    /** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
     getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
+    /**
+     * Applies an externally-obtained account update if `slot` is not older than the currently
+     * cached slot, emitting `userAccountUpdate`/`update` on acceptance. This is the only way this
+     * subscriber's data changes after construction.
+     * @param userAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount: UserAccount, slot: number): void;
 }

package/lib/browser/accounts/basicUserAccountSubscriber.js

@@ -7,6 +7,11 @@ const events_1 = require("events");
  * data during initialization and will not fetch or subscribe to updates.
  */
 class BasicUserAccountSubscriber {
+    /**
+     * @param userAccountPublicKey Address of the `UserAccount` this subscriber represents (not fetched — used only for identity).
+     * @param data Optional decoded account data to seed with; if omitted, `getUserAccountAndSlot()` returns undefined until `updateData` is called.
+     * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     constructor(userAccountPublicKey, data, slot) {
         this.isSubscribed = true;
         this.eventEmitter = new events_1.EventEmitter();
@@ -15,19 +20,32 @@ class BasicUserAccountSubscriber {
         // slot (0 = oldest-possible sentinel, overwritten by the first real fetch).
         this.user = data ? { data, slot: slot !== null && slot !== void 0 ? slot : 0 } : undefined;
     }
+    /** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
     async subscribe(_userAccount) {
         return true;
     }
     async addToAccountLoader() { }
+    /** No-op; this subscriber never fetches. Data only changes via `updateData`. */
     async fetch() { }
+    /** Type predicate: true once `user` has been seeded or set via `updateData`, narrowing `this.user` to non-undefined. */
     doesAccountExist() {
         return this.user !== undefined;
     }
+    /** No-op; there is no live subscription to tear down. */
     async unsubscribe() { }
+    /** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
     assertIsSubscribed() { }
+    /** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
     getUserAccountAndSlot() {
         return this.user;
     }
+    /**
+     * Applies an externally-obtained account update if `slot` is not older than the currently
+     * cached slot, emitting `userAccountUpdate`/`update` on acceptance. This is the only way this
+     * subscriber's data changes after construction.
+     * @param userAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount, slot) {
         if (!this.user || slot >= this.user.slot) {
             this.user = { data: userAccount, slot };

package/lib/browser/accounts/basicUserStatsAccountSubscriber.d.ts

@@ -15,15 +15,33 @@ export declare class BasicUserStatsAccountSubscriber implements UserStatsAccount
     callbackId?: string;
     errorCallbackId?: string;
     userStats?: DataAndSlot<UserStatsAccount>;
+    /**
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` this subscriber represents (not fetched — used only for identity).
+     * @param data Optional decoded account data to seed with; if omitted, `getUserStatsAccountAndSlot()` returns undefined until `updateData` is called.
+     * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     constructor(userStatsAccountPublicKey: PublicKey, data?: UserStatsAccount, slot?: number);
+    /** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
     subscribe(_userStatsAccount?: UserStatsAccount): Promise<boolean>;
     addToAccountLoader(): Promise<void>;
+    /** No-op; this subscriber never fetches. Data only changes via `updateData`. */
     fetch(): Promise<void>;
+    /** Type predicate: true once `userStats` has been seeded or set via `updateData`, narrowing `this.userStats` to non-undefined. */
     doesAccountExist(): this is {
         userStats: DataAndSlot<UserStatsAccount>;
     };
+    /** No-op; there is no live subscription to tear down. */
     unsubscribe(): Promise<void>;
+    /** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
     assertIsSubscribed(): void;
+    /** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
     getUserStatsAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
+    /**
+     * Applies an externally-obtained account update if `slot` is not older than the currently
+     * cached slot, emitting `userStatsAccountUpdate`/`update` on acceptance. This is the only way
+     * this subscriber's data changes after construction.
+     * @param userStatsAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userStatsAccount: UserStatsAccount, slot: number): void;
 }

package/lib/browser/accounts/basicUserStatsAccountSubscriber.js

@@ -7,6 +7,11 @@ const events_1 = require("events");
  * data during initialization and will not fetch or subscribe to updates.
  */
 class BasicUserStatsAccountSubscriber {
+    /**
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` this subscriber represents (not fetched — used only for identity).
+     * @param data Optional decoded account data to seed with; if omitted, `getUserStatsAccountAndSlot()` returns undefined until `updateData` is called.
+     * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     constructor(userStatsAccountPublicKey, data, slot) {
         this.isSubscribed = true;
         this.eventEmitter = new events_1.EventEmitter();
@@ -15,19 +20,32 @@ class BasicUserStatsAccountSubscriber {
         // slot (0 = oldest-possible sentinel, overwritten by the first real fetch).
         this.userStats = data ? { data, slot: slot !== null && slot !== void 0 ? slot : 0 } : undefined;
     }
+    /** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
     async subscribe(_userStatsAccount) {
         return true;
     }
     async addToAccountLoader() { }
+    /** No-op; this subscriber never fetches. Data only changes via `updateData`. */
     async fetch() { }
+    /** Type predicate: true once `userStats` has been seeded or set via `updateData`, narrowing `this.userStats` to non-undefined. */
     doesAccountExist() {
         return this.userStats !== undefined;
     }
+    /** No-op; there is no live subscription to tear down. */
     async unsubscribe() { }
+    /** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
     assertIsSubscribed() { }
+    /** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
     getUserStatsAccountAndSlot() {
         return this.userStats;
     }
+    /**
+     * Applies an externally-obtained account update if `slot` is not older than the currently
+     * cached slot, emitting `userStatsAccountUpdate`/`update` on acceptance. This is the only way
+     * this subscriber's data changes after construction.
+     * @param userStatsAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userStatsAccount, slot) {
         if (!this.userStats || slot >= this.userStats.slot) {
             this.userStats = { data: userStatsAccount, slot };

package/lib/browser/accounts/bulkAccountLoader.d.ts

@@ -3,10 +3,22 @@
 import { Commitment, PublicKey } from '@solana/web3.js';
 import { BufferAndSlot } from './types';
 import { Connection } from '../bankrun/bankrunConnection';
+/** An account registered with a `BulkAccountLoader`, along with every callback subscribed to its updates (keyed by callback id). */
 export type AccountToLoad = {
     publicKey: PublicKey;
     callbacks: Map<string, (buffer: Buffer, slot: number) => void>;
 };
+/**
+ * Batches many accounts behind a single periodic `getMultipleAccounts` RPC poll instead of one
+ * WebSocket subscription per account. Multiple independent callbacks (e.g. from different
+ * `PollingUserAccountSubscriber`/`PollingVelocityClientAccountSubscriber` instances) can register
+ * against the same `publicKey`; polling starts automatically on the first `addAccount` and stops
+ * when the last callback for the last account is removed. A buffer is only re-delivered to
+ * callbacks when its slot is not older than the last-seen slot for that account and its bytes
+ * actually changed, so a callback never observes a stale or duplicate update. `load()` calls are
+ * coalesced: concurrent callers share one in-flight RPC batch rather than issuing redundant
+ * requests.
+ */
 export declare class BulkAccountLoader {
     connection: Connection;
     commitment: Commitment;
@@ -19,19 +31,59 @@ export declare class BulkAccountLoader {
     private loadPromiseResolver;
     lastTimeLoadingPromiseCleared: number;
     mostRecentSlot: number;
+    /**
+     * @param connection Connection (or bankrun-compatible shim) used for the batched `getMultipleAccounts` polls.
+     * @param commitment Commitment level applied to every poll.
+     * @param pollingFrequency Poll interval in ms; `0` disables automatic polling (`startPolling` becomes a no-op), useful when the loader is driven manually via `load()`.
+     */
     constructor(connection: Connection, commitment: Commitment, pollingFrequency: number);
+    /**
+     * Registers a callback to be invoked whenever `publicKey`'s account data changes on a poll.
+     * Multiple callbacks may be registered for the same account. Starts polling automatically if
+     * this is the loader's first account. Awaits any in-flight `load()` before returning so a
+     * caller can immediately follow with its own `load()` without racing the poll interval.
+     * @param publicKey Account to track.
+     * @param callback Invoked with the raw account buffer and the slot it was fetched at whenever the buffer changes at a non-decreasing slot.
+     * @returns A callback id to pass to `removeAccount` later.
+     */
     addAccount(publicKey: PublicKey, callback: (buffer: Buffer, slot: number) => void): Promise<string>;
+    /**
+     * Unregisters a callback previously returned by `addAccount`. Once an account has no
+     * remaining callbacks, its cached buffer/slot is dropped and it stops being polled; if no
+     * accounts remain at all, polling stops entirely. A no-op if `callbackId` is undefined.
+     * @param publicKey Account the callback was registered against.
+     * @param callbackId Id returned by `addAccount`.
+     */
     removeAccount(publicKey: PublicKey, callbackId: string | undefined): void;
+    /**
+     * Registers a callback invoked whenever a `load()` batch throws (e.g. RPC failure or timeout).
+     * The loader continues polling afterward; errors do not stop the interval.
+     * @returns A callback id to pass to `removeErrorCallbacks` later.
+     */
     addErrorCallbacks(callback: (error: Error) => void): string;
+    /** Unregisters an error callback previously returned by `addErrorCallbacks`. A no-op if `callbackId` is undefined. */
     removeErrorCallbacks(callbackId: string | undefined): void;
     chunks<T>(array: readonly T[], size: number): T[][];
+    /**
+     * Fetches every registered account in one or more chunked, concurrent `getMultipleAccounts`
+     * batches (via `loadChunk`) and dispatches changed accounts to their callbacks. Concurrent
+     * calls while a load is already in flight share that same in-flight promise rather than
+     * issuing a duplicate RPC batch, unless the previous load has been running for over a minute
+     * (treated as stuck and restarted). On failure, invokes every registered error callback
+     * instead of throwing.
+     */
     load(): Promise<void>;
     loadChunk(accountsToLoadChunks: AccountToLoad[][]): Promise<void>;
     handleAccountCallbacks(accountToLoad: AccountToLoad, buffer: Buffer | undefined, slot: number): void;
+    /** Returns the last-fetched raw buffer/slot for `publicKey`, or undefined if it has never been loaded. */
     getBufferAndSlot(publicKey: PublicKey): BufferAndSlot | undefined;
+    /** Returns the highest slot number observed across any account fetched by this loader so far. */
     getSlot(): number;
+    /** Starts the polling interval if not already running and `pollingFrequency !== 0`. Called automatically by `addAccount`. */
     startPolling(): void;
+    /** Stops the polling interval, if running. Called automatically by `removeAccount` once no accounts remain. */
     stopPolling(): void;
     log(msg: string): void;
+    /** Restarts polling at a new interval (ms), preserving all registered accounts and callbacks. */
     updatePollingFrequency(pollingFrequency: number): void;
 }

package/lib/browser/accounts/bulkAccountLoader.js

@@ -5,7 +5,23 @@ const uuid_1 = require("uuid");
 const promiseTimeout_1 = require("../util/promiseTimeout");
 const numericConstants_1 = require("../constants/numericConstants");
 const oneMinute = 60 * 1000;
+/**
+ * Batches many accounts behind a single periodic `getMultipleAccounts` RPC poll instead of one
+ * WebSocket subscription per account. Multiple independent callbacks (e.g. from different
+ * `PollingUserAccountSubscriber`/`PollingVelocityClientAccountSubscriber` instances) can register
+ * against the same `publicKey`; polling starts automatically on the first `addAccount` and stops
+ * when the last callback for the last account is removed. A buffer is only re-delivered to
+ * callbacks when its slot is not older than the last-seen slot for that account and its bytes
+ * actually changed, so a callback never observes a stale or duplicate update. `load()` calls are
+ * coalesced: concurrent callers share one in-flight RPC batch rather than issuing redundant
+ * requests.
+ */
 class BulkAccountLoader {
+    /**
+     * @param connection Connection (or bankrun-compatible shim) used for the batched `getMultipleAccounts` polls.
+     * @param commitment Commitment level applied to every poll.
+     * @param pollingFrequency Poll interval in ms; `0` disables automatic polling (`startPolling` becomes a no-op), useful when the loader is driven manually via `load()`.
+     */
     constructor(connection, commitment, pollingFrequency) {
         this.accountsToLoad = new Map();
         this.bufferAndSlotMap = new Map();
@@ -17,6 +33,15 @@ class BulkAccountLoader {
         this.commitment = commitment;
         this.pollingFrequency = pollingFrequency;
     }
+    /**
+     * Registers a callback to be invoked whenever `publicKey`'s account data changes on a poll.
+     * Multiple callbacks may be registered for the same account. Starts polling automatically if
+     * this is the loader's first account. Awaits any in-flight `load()` before returning so a
+     * caller can immediately follow with its own `load()` without racing the poll interval.
+     * @param publicKey Account to track.
+     * @param callback Invoked with the raw account buffer and the slot it was fetched at whenever the buffer changes at a non-decreasing slot.
+     * @returns A callback id to pass to `removeAccount` later.
+     */
     async addAccount(publicKey, callback) {
         if (!publicKey) {
             console.trace(`Caught adding blank publickey to bulkAccountLoader`);
@@ -43,6 +68,13 @@ class BulkAccountLoader {
         await this.loadPromise;
         return callbackId;
     }
+    /**
+     * Unregisters a callback previously returned by `addAccount`. Once an account has no
+     * remaining callbacks, its cached buffer/slot is dropped and it stops being polled; if no
+     * accounts remain at all, polling stops entirely. A no-op if `callbackId` is undefined.
+     * @param publicKey Account the callback was registered against.
+     * @param callbackId Id returned by `addAccount`.
+     */
     removeAccount(publicKey, callbackId) {
         if (callbackId === undefined) {
             return;
@@ -59,11 +91,17 @@ class BulkAccountLoader {
             this.stopPolling();
         }
     }
+    /**
+     * Registers a callback invoked whenever a `load()` batch throws (e.g. RPC failure or timeout).
+     * The loader continues polling afterward; errors do not stop the interval.
+     * @returns A callback id to pass to `removeErrorCallbacks` later.
+     */
     addErrorCallbacks(callback) {
         const callbackId = (0, uuid_1.v4)();
         this.errorCallbacks.set(callbackId, callback);
         return callbackId;
     }
+    /** Unregisters an error callback previously returned by `addErrorCallbacks`. A no-op if `callbackId` is undefined. */
     removeErrorCallbacks(callbackId) {
         if (callbackId === undefined) {
             return;
@@ -76,6 +114,14 @@ class BulkAccountLoader {
             .map((_, index) => index * size)
             .map((begin) => array.slice(begin, begin + size));
     }
+    /**
+     * Fetches every registered account in one or more chunked, concurrent `getMultipleAccounts`
+     * batches (via `loadChunk`) and dispatches changed accounts to their callbacks. Concurrent
+     * calls while a load is already in flight share that same in-flight promise rather than
+     * issuing a duplicate RPC batch, unless the previous load has been running for over a minute
+     * (treated as stuck and restarted). On failure, invokes every registered error callback
+     * instead of throwing.
+     */
     async load() {
         if (this.loadPromise) {
             const now = Date.now();
@@ -200,12 +246,15 @@ class BulkAccountLoader {
             }
         }
     }
+    /** Returns the last-fetched raw buffer/slot for `publicKey`, or undefined if it has never been loaded. */
     getBufferAndSlot(publicKey) {
         return this.bufferAndSlotMap.get(publicKey.toString());
     }
+    /** Returns the highest slot number observed across any account fetched by this loader so far. */
     getSlot() {
         return this.mostRecentSlot;
     }
+    /** Starts the polling interval if not already running and `pollingFrequency !== 0`. Called automatically by `addAccount`. */
     startPolling() {
         if (this.intervalId) {
             return;
@@ -213,6 +262,7 @@ class BulkAccountLoader {
         if (this.pollingFrequency !== 0)
             this.intervalId = setInterval(this.load.bind(this), this.pollingFrequency);
     }
+    /** Stops the polling interval, if running. Called automatically by `removeAccount` once no accounts remain. */
     stopPolling() {
         if (this.intervalId) {
             clearInterval(this.intervalId);
@@ -222,6 +272,7 @@ class BulkAccountLoader {
     log(msg) {
         console.log(msg);
     }
+    /** Restarts polling at a new interval (ms), preserving all registered accounts and callbacks. */
     updatePollingFrequency(pollingFrequency) {
         this.stopPolling();
         this.pollingFrequency = pollingFrequency;

package/lib/browser/accounts/bulkUserStatsSubscription.d.ts

@@ -1,7 +1,14 @@
 import { UserStats } from '../userStats';
 import { BulkAccountLoader } from './bulkAccountLoader';
 /**
- * @param userStats
- * @param accountLoader
+ * Subscribes many `UserStats`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `UserStats.subscribe()` triggering its own `addAccount`/`load()`. Registers
+ * every account's `PollingUserStatsAccountSubscriber` with the loader first, issues one `load()`
+ * to seed all of them from a single batched `getMultipleAccounts` call, and only then calls
+ * `userStat.subscribe()` (which becomes a fast no-op fetch since data is already cached). If
+ * `userStats` is empty, still calls `accountLoader.load()` so any other accounts already
+ * registered on the loader get polled.
+ * @param userStats `UserStats` instances to subscribe; each must already be constructed with a `PollingUserStatsAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 export declare function bulkPollingUserStatsSubscribe(userStats: UserStats[], accountLoader: BulkAccountLoader): Promise<void>;

package/lib/browser/accounts/bulkUserStatsSubscription.js

@@ -2,8 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bulkPollingUserStatsSubscribe = void 0;
 /**
- * @param userStats
- * @param accountLoader
+ * Subscribes many `UserStats`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `UserStats.subscribe()` triggering its own `addAccount`/`load()`. Registers
+ * every account's `PollingUserStatsAccountSubscriber` with the loader first, issues one `load()`
+ * to seed all of them from a single batched `getMultipleAccounts` call, and only then calls
+ * `userStat.subscribe()` (which becomes a fast no-op fetch since data is already cached). If
+ * `userStats` is empty, still calls `accountLoader.load()` so any other accounts already
+ * registered on the loader get polled.
+ * @param userStats `UserStats` instances to subscribe; each must already be constructed with a `PollingUserStatsAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 async function bulkPollingUserStatsSubscribe(userStats, accountLoader) {
     if (userStats.length === 0) {

package/lib/browser/accounts/bulkUserSubscription.d.ts

@@ -1,7 +1,13 @@
 import { User } from '../user';
 import { BulkAccountLoader } from './bulkAccountLoader';
 /**
- * @param users
- * @param accountLoader
+ * Subscribes many `User`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `User.subscribe()` triggering its own `addAccount`/`load()`. Registers every
+ * user's `PollingUserAccountSubscriber` with the loader first, issues one `load()` to seed all of
+ * them from a single batched `getMultipleAccounts` call, and only then calls `user.subscribe()`
+ * (which becomes a fast no-op fetch since data is already cached). If `users` is empty, still
+ * calls `accountLoader.load()` so any other accounts already registered on the loader get polled.
+ * @param users Users to subscribe; each must already be constructed with a `PollingUserAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 export declare function bulkPollingUserSubscribe(users: User[], accountLoader: BulkAccountLoader): Promise<void>;

package/lib/browser/accounts/bulkUserSubscription.js

@@ -2,8 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bulkPollingUserSubscribe = void 0;
 /**
- * @param users
- * @param accountLoader
+ * Subscribes many `User`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `User.subscribe()` triggering its own `addAccount`/`load()`. Registers every
+ * user's `PollingUserAccountSubscriber` with the loader first, issues one `load()` to seed all of
+ * them from a single batched `getMultipleAccounts` call, and only then calls `user.subscribe()`
+ * (which becomes a fast no-op fetch since data is already cached). If `users` is empty, still
+ * calls `accountLoader.load()` so any other accounts already registered on the loader get polled.
+ * @param users Users to subscribe; each must already be constructed with a `PollingUserAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 async function bulkPollingUserSubscribe(users, accountLoader) {
     if (users.length === 0) {

package/lib/browser/accounts/customizedCadenceBulkAccountLoader.d.ts

@@ -2,14 +2,29 @@
 /// <reference types="node" />
 import { BulkAccountLoader } from './bulkAccountLoader';
 import { Commitment, Connection, PublicKey } from '@solana/web3.js';
+/**
+ * `BulkAccountLoader` variant where each account can be polled at its own cadence instead of a
+ * single shared `pollingFrequency`. Overrides the base class's single `setInterval` with a
+ * per-account `accountFrequencies` map: `handleAccountLoading()` only includes an account in a
+ * given tick if `Date.now() - lastPollingTime >= frequency` for that account, then delegates to
+ * the inherited chunked `loadChunk` for the actual `getMultipleAccounts` batch. The interval
+ * itself always runs at the fastest frequency across all registered accounts (see `startPolling`),
+ * so slower accounts simply get skipped on ticks that fire before they're due.
+ */
 export declare class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
     private customIntervalId;
     private currentPollingFrequency;
     private accountFrequencies;
     private lastPollingTimes;
     private defaultPollingFrequency;
+    /**
+     * @param connection Connection used for the batched `getMultipleAccounts` polls.
+     * @param commitment Commitment level applied to every poll.
+     * @param defaultPollingFrequency Polling cadence in ms (see base `BulkAccountLoader`) used for any account added without an explicit `customPollingFrequency`, and as the floor when computing the shared interval in `startPolling`.
+     */
     constructor(connection: Connection, commitment: Commitment, defaultPollingFrequency: number);
     private getAccountsToLoad;
+    /** Immediately runs one due-account loading pass, bypassing the interval timer. Unlike the base class's `load()`, this does not force-load every registered account — only those currently due per their own cadence. */
     load(): Promise<void>;
     private handleAccountLoading;
     /**
@@ -36,9 +51,31 @@ export declare class CustomizedCadenceBulkAccountLoader extends BulkAccountLoade
      * 4. Automatically restart polling if this account needs a faster frequency than existing accounts
      */
     addAccount(publicKey: PublicKey, callback: (buffer: Buffer, slot: number) => void, customPollingFrequency?: number): Promise<string>;
+    /**
+     * Unregisters a callback previously returned by `addAccount`. Once an account has no
+     * remaining callbacks, its cached buffer/slot and cadence bookkeeping (`accountFrequencies`,
+     * `lastPollingTimes`) are dropped; if no accounts remain at all, polling stops entirely,
+     * otherwise polling is restarted in case the removed account held the fastest cadence.
+     * @param publicKey Account the callback was registered against.
+     * @param callbackId Id returned by `addAccount`.
+     */
     removeAccount(publicKey: PublicKey, callbackId: string): void;
+    /** Returns the polling cadence in ms currently set for `publicKey` (custom or default), or `null` if the account isn't registered. */
     getAccountCadence(publicKey: PublicKey): number | null;
+    /**
+     * Starts the shared interval timer, ticking at the fastest cadence among all registered
+     * accounts (or `defaultPollingFrequency` if none are registered). Each tick runs
+     * `handleAccountLoading()`, which loads only the accounts due at that moment. A no-op if
+     * already running; call `stopPolling()` first to pick up a new minimum frequency.
+     */
     startPolling(): void;
+    /** Stops the shared interval timer (and the base class's, via `super.stopPolling()`) and clears `lastPollingTimes` so every account is treated as due again once polling restarts. */
     stopPolling(): void;
+    /**
+     * Clears all per-account cadence bookkeeping. Because `getAccountsToLoad()` only considers
+     * accounts with an entry in `accountFrequencies`, this stops polling for every registered
+     * account until a cadence is re-established via `setCustomPollingFrequency` or `addAccount`.
+     * Registered accounts/callbacks themselves are untouched.
+     */
     clearAccountFrequencies(): void;
 }

package/lib/browser/accounts/customizedCadenceBulkAccountLoader.js

@@ -4,7 +4,21 @@ exports.CustomizedCadenceBulkAccountLoader = void 0;
 const numericConstants_1 = require("../constants/numericConstants");
 const bulkAccountLoader_1 = require("./bulkAccountLoader");
 const uuid_1 = require("uuid");
+/**
+ * `BulkAccountLoader` variant where each account can be polled at its own cadence instead of a
+ * single shared `pollingFrequency`. Overrides the base class's single `setInterval` with a
+ * per-account `accountFrequencies` map: `handleAccountLoading()` only includes an account in a
+ * given tick if `Date.now() - lastPollingTime >= frequency` for that account, then delegates to
+ * the inherited chunked `loadChunk` for the actual `getMultipleAccounts` batch. The interval
+ * itself always runs at the fastest frequency across all registered accounts (see `startPolling`),
+ * so slower accounts simply get skipped on ticks that fire before they're due.
+ */
 class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccountLoader {
+    /**
+     * @param connection Connection used for the batched `getMultipleAccounts` polls.
+     * @param commitment Commitment level applied to every poll.
+     * @param defaultPollingFrequency Polling cadence in ms (see base `BulkAccountLoader`) used for any account added without an explicit `customPollingFrequency`, and as the floor when computing the shared interval in `startPolling`.
+     */
     constructor(connection, commitment, defaultPollingFrequency) {
         super(connection, commitment, defaultPollingFrequency);
         this.customIntervalId = null;
@@ -28,6 +42,7 @@ class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccount
         }
         return accountsToLoad;
     }
+    /** Immediately runs one due-account loading pass, bypassing the interval timer. Unlike the base class's `load()`, this does not force-load every registered account — only those currently due per their own cadence. */
     async load() {
         return this.handleAccountLoading();
     }
@@ -100,6 +115,14 @@ class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccount
         this.restartPollingIfNeeded(updatedFrequency);
         return callbackId;
     }
+    /**
+     * Unregisters a callback previously returned by `addAccount`. Once an account has no
+     * remaining callbacks, its cached buffer/slot and cadence bookkeeping (`accountFrequencies`,
+     * `lastPollingTimes`) are dropped; if no accounts remain at all, polling stops entirely,
+     * otherwise polling is restarted in case the removed account held the fastest cadence.
+     * @param publicKey Account the callback was registered against.
+     * @param callbackId Id returned by `addAccount`.
+     */
     removeAccount(publicKey, callbackId) {
         const existingAccountToLoad = this.accountsToLoad.get(publicKey.toString());
         if (existingAccountToLoad) {
@@ -120,10 +143,17 @@ class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccount
             this.restartPollingIfNeeded(this.defaultPollingFrequency);
         }
     }
+    /** Returns the polling cadence in ms currently set for `publicKey` (custom or default), or `null` if the account isn't registered. */
     getAccountCadence(publicKey) {
         const key = publicKey.toBase58();
         return this.accountFrequencies.get(key) || null;
     }
+    /**
+     * Starts the shared interval timer, ticking at the fastest cadence among all registered
+     * accounts (or `defaultPollingFrequency` if none are registered). Each tick runs
+     * `handleAccountLoading()`, which loads only the accounts due at that moment. A no-op if
+     * already running; call `stopPolling()` first to pick up a new minimum frequency.
+     */
     startPolling() {
         if (this.customIntervalId) {
             return;
@@ -136,6 +166,7 @@ class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccount
             });
         }, minFrequency);
     }
+    /** Stops the shared interval timer (and the base class's, via `super.stopPolling()`) and clears `lastPollingTimes` so every account is treated as due again once polling restarts. */
     stopPolling() {
         super.stopPolling();
         if (this.customIntervalId) {
@@ -145,6 +176,12 @@ class CustomizedCadenceBulkAccountLoader extends bulkAccountLoader_1.BulkAccount
         }
         this.lastPollingTimes.clear();
     }
+    /**
+     * Clears all per-account cadence bookkeeping. Because `getAccountsToLoad()` only considers
+     * accounts with an entry in `accountFrequencies`, this stops polling for every registered
+     * account until a cadence is re-established via `setCustomPollingFrequency` or `addAccount`.
+     * Registered accounts/callbacks themselves are untouched.
+     */
     clearAccountFrequencies() {
         this.accountFrequencies.clear();
     }