@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/userMap/revenueShareEscrowMap.js

@@ -4,6 +4,7 @@ exports.RevenueShareEscrowMap = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const pda_1 = require("../addresses/pda");
 const memcmp_1 = require("../memcmp");
+/** In-memory cache mapping each authority to their `RevenueShareEscrow` account (builder/referral fee accrual escrow). */
 class RevenueShareEscrowMap {
     /**
      * Creates a new RevenueShareEscrowMap instance.
@@ -21,7 +22,9 @@ class RevenueShareEscrowMap {
         this.parallelSync = parallelSync !== undefined ? parallelSync : true;
     }
     /**
-     * Subscribe to all RevenueShareEscrow accounts.
+     * Populates the map via a one-time `sync()` (no-op if already populated).
+     * There is no live/push subscription here — call `sync()`/`slowSync()`
+     * again later to pick up new or updated escrow accounts.
      */
     async subscribe() {
         if (this.size() > 0) {
@@ -30,9 +33,11 @@ class RevenueShareEscrowMap {
         await this.velocityClient.subscribe();
         await this.sync();
     }
+    /** Returns true if `authorityPublicKey` has a `RevenueShareEscrow` account cached in the map. */
     has(authorityPublicKey) {
         return this.authorityEscrowMap.has(authorityPublicKey);
     }
+    /** Returns the cached `RevenueShareEscrowAccount` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
     get(authorityPublicKey) {
         return this.authorityEscrowMap.get(authorityPublicKey);
     }
@@ -48,6 +53,12 @@ class RevenueShareEscrowMap {
         }
         return this.get(authorityPublicKey);
     }
+    /**
+     * Fetches and decodes `authority`'s `RevenueShareEscrow` account directly
+     * via RPC and caches it. If the account does not exist (a normal condition
+     * — not every authority has an escrow), logs a debug message and leaves the
+     * map entry absent rather than throwing.
+     */
     async addRevenueShareEscrow(authority) {
         const escrowAccountPublicKey = (0, pda_1.getRevenueShareEscrowAccountPublicKey)(this.velocityClient.program.programId, new web3_js_1.PublicKey(authority));
         try {
@@ -62,9 +73,11 @@ class RevenueShareEscrowMap {
             console.debug(`No RevenueShareEscrow account found for authority: ${authority}`);
         }
     }
+    /** Number of `RevenueShareEscrow` accounts currently cached in the map. */
     size() {
         return this.authorityEscrowMap.size;
     }
+    /** Fully (re)populates the map via `syncAll` (a `getProgramAccounts` scan). Concurrent calls share the same in-flight promise. */
     async sync() {
         if (this.fetchPromise) {
             return this.fetchPromise;
@@ -97,6 +110,14 @@ class RevenueShareEscrowMap {
             this.authorityEscrowMap.set(authority, escrowNew);
         }
     }
+    /**
+     * Fetches and decodes every `RevenueShareEscrow` program account (via
+     * `getRevenueShareEscrowFilter`), in batches of 100 with a 10ms delay
+     * between batches to avoid overwhelming the RPC, and caches them keyed by
+     * `escrow.authority`. Batch decoding runs in parallel unless constructed
+     * with `parallelSync: false`. A decode failure for one account is logged
+     * and skipped rather than aborting the whole sync.
+     */
     async syncAll() {
         const rpcRequestArgs = [
             this.velocityClient.program.programId.toBase58(),
@@ -148,20 +169,18 @@ class RevenueShareEscrowMap {
             await new Promise((resolve) => setTimeout(resolve, 10));
         }
     }
-    /**
-     * Get all RevenueShareEscrow accounts
-     */
+    /** Returns a shallow copy of the full authority-to-escrow map (mutating the returned map does not affect the cache). */
     getAll() {
         return new Map(this.authorityEscrowMap);
     }
-    /**
-     * Get all authorities that have RevenueShareEscrow accounts
-     */
+    /** Returns the base58 authority pubkeys of every `RevenueShareEscrow` account currently cached. */
     getAuthorities() {
         return Array.from(this.authorityEscrowMap.keys());
     }
     /**
-     * Get RevenueShareEscrow accounts that have approved referrers
+     * Get `RevenueShareEscrow` accounts that have at least one entry in
+     * `approvedBuilders` — builders this user has approved to charge an order
+     * fee (not "referrers": `referrer` is a separate field on the account).
      */
     getEscrowsWithApprovedReferrers() {
         const result = new Map();
@@ -173,7 +192,9 @@ class RevenueShareEscrowMap {
         return result;
     }
     /**
-     * Get RevenueShareEscrow accounts that have active orders
+     * Get `RevenueShareEscrow` accounts with at least one entry in `orders` —
+     * the ring buffer of in-flight builder/referral fee accruals not yet
+     * settled via settle-PnL.
      */
     getEscrowsWithOrders() {
         const result = new Map();
@@ -185,7 +206,10 @@ class RevenueShareEscrowMap {
         return result;
     }
     /**
-     * Get RevenueShareEscrow account by referrer
+     * Returns the first cached `RevenueShareEscrow` account whose `referrer`
+     * field equals `referrerPublicKey`. There is no reverse index, so this is
+     * an O(n) scan over every cached escrow; prefer `getAllByReferrer` if more
+     * than one escrow may share the same referrer.
      */
     getByReferrer(referrerPublicKey) {
         for (const escrow of this.authorityEscrowMap.values()) {
@@ -196,7 +220,9 @@ class RevenueShareEscrowMap {
         return undefined;
     }
     /**
-     * Get all RevenueShareEscrow accounts for a specific referrer
+     * Returns every cached `RevenueShareEscrow` account whose `referrer` field
+     * equals `referrerPublicKey`. O(n) scan over every cached escrow (no
+     * reverse index).
      */
     getAllByReferrer(referrerPublicKey) {
         const result = [];
@@ -207,6 +233,7 @@ class RevenueShareEscrowMap {
         }
         return result;
     }
+    /** Clears the in-memory map. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
     async unsubscribe() {
         this.authorityEscrowMap.clear();
     }

package/lib/browser/userMap/userMap.d.ts

@@ -10,6 +10,7 @@ import { PublicKey } from '@solana/web3.js';
 import { UserAccountFilterCriteria as UserFilterCriteria, UserMapConfig } from './userMapConfig';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
+/** Public surface implemented by `UserMap`. */
 export interface UserMapInterface {
     eventEmitter: StrictEventEmitter<EventEmitter, UserEvents>;
     subscribe(): Promise<void>;
@@ -27,6 +28,25 @@ export interface UserMapInterface {
     entries(): IterableIterator<[string, User]>;
     entriesWithSlot(): IterableIterator<[string, DataAndSlot<User>]>;
 }
+/**
+ * In-memory cache of every `User` account on the program, keyed by the
+ * `User` account's own public key.
+ *
+ * Sync/subscription filtering (see `getFilters`) is built from memcmp
+ * filters: the base `getUserFilter()` (matches the `User` account
+ * discriminator — required, or every account on chain would match) is always
+ * present; `getNonIdleUserFilter()` is added unless `includeIdle` is set (idle
+ * accounts are excluded by default to reduce subscription volume);
+ * `getUsersWithPoolId(filterByPoolId)` is added when `filterByPoolId` is set;
+ * and any `additionalFilters` from the config are appended last. The same
+ * filter set is used for the initial `getProgramAccounts` sync and for the
+ * live websocket/gRPC subscription, so what you sync is what you keep getting
+ * updates for.
+ *
+ * Automatically does a full `sync()` whenever the program's
+ * `StateAccount.numberOfSubAccounts` changes (new/deleted user accounts),
+ * unless `disableSyncOnTotalAccountsChange` is set.
+ */
 export declare class UserMap implements UserMapInterface {
     private userMap;
     velocityClient: VelocityClient;
@@ -50,8 +70,30 @@ export declare class UserMap implements UserMapInterface {
      * Constructs a new UserMap instance.
      */
     constructor(config: UserMapConfig);
+    /**
+     * Populates the map with a full initial `sync()` (no-op if already
+     * populated) and starts the configured live subscription
+     * (`'websocket'`/`'polling'`/`'grpc'`), plus (unless
+     * `disableSyncOnTotalAccountsChange`) a listener that triggers a full
+     * re-sync whenever `StateAccount.numberOfSubAccounts` changes.
+     */
     subscribe(): Promise<void>;
+    /**
+     * Adds `userAccountPublicKey` to the map, creating a `User` for it.
+     *
+     * By default (`accountSubscription` omitted), subscribes it with a
+     * `OneShotUserAccountSubscriber` seeded from `userAccount`/`slot` rather
+     * than a live per-account websocket subscription — the map already gets
+     * live updates in bulk via its own subscription (`WebsocketSubscription`/
+     * `PollingSubscription`/`grpcSubscription`), so per-`User` subscriptions
+     * here would needlessly multiply RPC load.
+     * @param userAccount Optional pre-fetched account data to seed with, skipping an RPC fetch.
+     * @param slot Optional slot the data was observed at. Required (directly or via `userAccount`'s subscriber) — throws if no slot can be determined after subscribing.
+     * @param accountSubscription Optional override for how the created `User` subscribes; defaults to the one-shot subscriber described above.
+     * @throws If no slot is available after subscribing.
+     */
     addPubkey(userAccountPublicKey: PublicKey, userAccount?: UserAccount, slot?: number, accountSubscription?: UserSubscriptionConfig): Promise<void>;
+    /** Returns true if a `User` account keyed by `key` (the `User` account pubkey, base58) is cached in the map. */
     has(key: string): boolean;
     /**
      * gets the User for a particular userAccountPublicKey, if no User exists, undefined is returned
@@ -59,6 +101,7 @@ export declare class UserMap implements UserMapInterface {
      * @returns user User | undefined
      */
     get(key: string): User | undefined;
+    /** Like `get`, but also returns the slot at which the `User` account was last observed. */
     getWithSlot(key: string): DataAndSlot<User> | undefined;
     /**
      * gets the User for a particular userAccountPublicKey, if no User exists, new one is created
@@ -66,7 +109,9 @@ export declare class UserMap implements UserMapInterface {
      * @returns  User
      */
     mustGet(key: string, accountSubscription?: UserSubscriptionConfig): Promise<User>;
+    /** Like `mustGet`, but also returns the slot at which the `User` account was observed. */
     mustGetWithSlot(key: string, accountSubscription?: UserSubscriptionConfig): Promise<DataAndSlot<User>>;
+    /** Like `mustGet`, but returns the underlying `UserAccount` data directly (throws if the `User`'s account is not loaded). */
     mustGetUserAccount(key: string): Promise<UserAccount>;
     /**
      * gets the Authority for a particular userAccountPublicKey, if no User exists, undefined is returned
@@ -75,17 +120,29 @@ export declare class UserMap implements UserMapInterface {
      */
     getUserAuthority(key: string): PublicKey | undefined;
     /**
-     * implements the {@link DLOBSource} interface
-     * create a DLOB from all the subscribed users
-     * @param slot
+     * Implements the `DLOBSource` interface: builds a `DLOB` from every
+     * subscribed user's open orders.
+     * @param slot Slot to consider orders "current" as of (auction/trigger timing).
      */
     getDLOB(slot: number): Promise<DLOB>;
+    /** Ensures an entry exists in the map for `record.user`, adding it via `addPubkey` if not already present. */
     updateWithOrderRecord(record: OrderRecord): Promise<void>;
+    /**
+     * Incrementally updates the map in response to a single program event,
+     * ensuring an entry exists for every `User` account the event references
+     * (deposit/funding/liquidation/order/order-action/settle-pnl/new-user
+     * records). Unrecognized event types are silently ignored.
+     */
     updateWithEventRecord(record: WrappedEvent<any>): Promise<void>;
+    /** Iterates all cached `User` instances. */
     values(): IterableIterator<User>;
+    /** Like `values`, but paired with the slot each `User` was last observed at. */
     valuesWithSlot(): IterableIterator<DataAndSlot<User>>;
+    /** Iterates all `[userAccountPublicKey, User]` pairs in the map. */
     entries(): IterableIterator<[string, User]>;
+    /** Like `entries`, but paired with the slot each `User` was last observed at. */
     entriesWithSlot(): IterableIterator<[string, DataAndSlot<User>]>;
+    /** Number of `User` accounts currently cached in the map. */
     size(): number;
     /**
      * Returns a unique list of authorities for all users in the UserMap that meet the filter criteria
@@ -93,7 +150,14 @@ export declare class UserMap implements UserMapInterface {
      * @returns
      */
     getUniqueAuthorities(filterCriteria?: UserFilterCriteria): PublicKey[];
+    /** Runs a full sync using the strategy configured in `UserMapConfig.syncConfig` (`'default'` or `'paginated'` — see `SyncConfig`). */
     sync(): Promise<void>;
+    /**
+     * Builds the memcmp filter set for both the initial sync and the live
+     * subscription: always the `User`-account discriminator filter; plus a
+     * non-idle filter unless `includeIdle`; plus a pool-id filter if
+     * `filterByPoolId` is set; plus any caller-supplied `additionalFilters`.
+     */
     private getFilters;
     /**
      * Syncs the UserMap using the default sync method (single getProgramAccounts call with filters).
@@ -107,8 +171,22 @@ export declare class UserMap implements UserMapInterface {
      * @returns
      */
     private paginatedSync;
+    /**
+     * Tears down the live subscription, unsubscribes and removes every cached
+     * `User`, and (if registered) removes the `stateAccountUpdate` listener
+     * that triggers auto-resync on `numberOfSubAccounts` changes.
+     */
     unsubscribe(): Promise<void>;
+    /**
+     * Applies a fresh `userAccount` observation for `key` at `slot`. If the
+     * user is already cached, updates in place only if `slot` is at least as
+     * new as the cached slot (stale/out-of-order updates are dropped) and
+     * emits `'userUpdate'`. If not cached yet, adds it via `addPubkey`.
+     * Also advances `getSlot()`'s tracked most-recent slot.
+     */
     updateUserAccount(key: string, userAccount: UserAccount, slot: number): Promise<void>;
+    /** Advances the map's tracked most-recent slot to `slot` if it's newer. */
     updateLatestSlot(slot: number): void;
+    /** Returns the most recent slot at which any account update has been observed. */
     getSlot(): number;
 }

package/lib/browser/userMap/userMap.js

@@ -18,6 +18,25 @@ const events_1 = require("events");
 // smaller than the real account, the buffer is truncated and decodeUser reads past
 // the end (RangeError: ERR_BUFFER_OUT_OF_BOUNDS). Must be >= the on-chain User size.
 const MAX_USER_ACCOUNT_SIZE_BYTES = 4496;
+/**
+ * In-memory cache of every `User` account on the program, keyed by the
+ * `User` account's own public key.
+ *
+ * Sync/subscription filtering (see `getFilters`) is built from memcmp
+ * filters: the base `getUserFilter()` (matches the `User` account
+ * discriminator — required, or every account on chain would match) is always
+ * present; `getNonIdleUserFilter()` is added unless `includeIdle` is set (idle
+ * accounts are excluded by default to reduce subscription volume);
+ * `getUsersWithPoolId(filterByPoolId)` is added when `filterByPoolId` is set;
+ * and any `additionalFilters` from the config are appended last. The same
+ * filter set is used for the initial `getProgramAccounts` sync and for the
+ * live websocket/gRPC subscription, so what you sync is what you keep getting
+ * updates for.
+ *
+ * Automatically does a full `sync()` whenever the program's
+ * `StateAccount.numberOfSubAccounts` changes (new/deleted user accounts),
+ * unless `disableSyncOnTotalAccountsChange` is set.
+ */
 class UserMap {
     /**
      * Constructs a new UserMap instance.
@@ -98,6 +117,13 @@ class UserMap {
         this.throwOnFailedSync = (_j = config.throwOnFailedSync) !== null && _j !== void 0 ? _j : false;
         this.eventEmitter = new events_1.EventEmitter();
     }
+    /**
+     * Populates the map with a full initial `sync()` (no-op if already
+     * populated) and starts the configured live subscription
+     * (`'websocket'`/`'polling'`/`'grpc'`), plus (unless
+     * `disableSyncOnTotalAccountsChange`) a listener that triggers a full
+     * re-sync whenever `StateAccount.numberOfSubAccounts` changes.
+     */
     async subscribe() {
         if (this.size() > 0) {
             return;
@@ -110,6 +136,20 @@ class UserMap {
         }
         await this.subscription.subscribe();
     }
+    /**
+     * Adds `userAccountPublicKey` to the map, creating a `User` for it.
+     *
+     * By default (`accountSubscription` omitted), subscribes it with a
+     * `OneShotUserAccountSubscriber` seeded from `userAccount`/`slot` rather
+     * than a live per-account websocket subscription — the map already gets
+     * live updates in bulk via its own subscription (`WebsocketSubscription`/
+     * `PollingSubscription`/`grpcSubscription`), so per-`User` subscriptions
+     * here would needlessly multiply RPC load.
+     * @param userAccount Optional pre-fetched account data to seed with, skipping an RPC fetch.
+     * @param slot Optional slot the data was observed at. Required (directly or via `userAccount`'s subscriber) — throws if no slot can be determined after subscribing.
+     * @param accountSubscription Optional override for how the created `User` subscribes; defaults to the one-shot subscriber described above.
+     * @throws If no slot is available after subscribing.
+     */
     async addPubkey(userAccountPublicKey, userAccount, slot, accountSubscription) {
         var _a;
         const user = new user_1.User({
@@ -132,6 +172,7 @@ class UserMap {
         });
         this.eventEmitter.emit('userUpdate', user);
     }
+    /** Returns true if a `User` account keyed by `key` (the `User` account pubkey, base58) is cached in the map. */
     has(key) {
         return this.userMap.has(key);
     }
@@ -144,6 +185,7 @@ class UserMap {
         var _a;
         return (_a = this.userMap.get(key)) === null || _a === void 0 ? void 0 : _a.data;
     }
+    /** Like `get`, but also returns the slot at which the `User` account was last observed. */
     getWithSlot(key) {
         return this.userMap.get(key);
     }
@@ -162,6 +204,7 @@ class UserMap {
         }
         return userWithSlot.data;
     }
+    /** Like `mustGet`, but also returns the slot at which the `User` account was observed. */
     async mustGetWithSlot(key, accountSubscription) {
         if (!this.has(key)) {
             await this.addPubkey(new web3_js_1.PublicKey(key), undefined, undefined, accountSubscription);
@@ -172,6 +215,7 @@ class UserMap {
         }
         return userWithSlot;
     }
+    /** Like `mustGet`, but returns the underlying `UserAccount` data directly (throws if the `User`'s account is not loaded). */
     async mustGetUserAccount(key) {
         const user = await this.mustGet(key);
         return user.getUserAccountOrThrow();
@@ -190,20 +234,27 @@ class UserMap {
         return (_a = user.data.getUserAccount()) === null || _a === void 0 ? void 0 : _a.authority;
     }
     /**
-     * implements the {@link DLOBSource} interface
-     * create a DLOB from all the subscribed users
-     * @param slot
+     * Implements the `DLOBSource` interface: builds a `DLOB` from every
+     * subscribed user's open orders.
+     * @param slot Slot to consider orders "current" as of (auction/trigger timing).
      */
     async getDLOB(slot) {
         const dlob = new DLOB_1.DLOB();
         await dlob.initFromUserMap(this, slot);
         return dlob;
     }
+    /** Ensures an entry exists in the map for `record.user`, adding it via `addPubkey` if not already present. */
     async updateWithOrderRecord(record) {
         if (!this.has(record.user.toString())) {
             await this.addPubkey(record.user);
         }
     }
+    /**
+     * Incrementally updates the map in response to a single program event,
+     * ensuring an entry exists for every `User` account the event references
+     * (deposit/funding/liquidation/order/order-action/settle-pnl/new-user
+     * records). Unrecognized event types are silently ignored.
+     */
     async updateWithEventRecord(record) {
         if (record.eventType === 'DepositRecord') {
             const depositRecord = record;
@@ -240,22 +291,27 @@ class UserMap {
             await this.mustGet(newUserRecord.user.toString());
         }
     }
+    /** Iterates all cached `User` instances. */
     *values() {
         for (const dataAndSlot of this.userMap.values()) {
             yield dataAndSlot.data;
         }
     }
+    /** Like `values`, but paired with the slot each `User` was last observed at. */
     valuesWithSlot() {
         return this.userMap.values();
     }
+    /** Iterates all `[userAccountPublicKey, User]` pairs in the map. */
     *entries() {
         for (const [key, dataAndSlot] of this.userMap.entries()) {
             yield [key, dataAndSlot.data];
         }
     }
+    /** Like `entries`, but paired with the slot each `User` was last observed at. */
     entriesWithSlot() {
         return this.userMap.entries();
     }
+    /** Number of `User` accounts currently cached in the map. */
     size() {
         return this.userMap.size;
     }
@@ -276,6 +332,7 @@ class UserMap {
         const userAuthKeys = Array.from(userAuths).map((userAuth) => new web3_js_1.PublicKey(userAuth));
         return userAuthKeys;
     }
+    /** Runs a full sync using the strategy configured in `UserMapConfig.syncConfig` (`'default'` or `'paginated'` — see `SyncConfig`). */
     async sync() {
         if (this.syncConfig.type === 'default') {
             return this.defaultSync();
@@ -284,6 +341,12 @@ class UserMap {
             return this.paginatedSync();
         }
     }
+    /**
+     * Builds the memcmp filter set for both the initial sync and the live
+     * subscription: always the `User`-account discriminator filter; plus a
+     * non-idle filter unless `includeIdle`; plus a pool-id filter if
+     * `filterByPoolId` is set; plus any caller-supplied `additionalFilters`.
+     */
     getFilters() {
         const filters = [(0, memcmp_1.getUserFilter)()];
         if (!this.includeIdle) {
@@ -464,6 +527,11 @@ class UserMap {
             this.syncPromise = undefined;
         }
     }
+    /**
+     * Tears down the live subscription, unsubscribes and removes every cached
+     * `User`, and (if registered) removes the `stateAccountUpdate` listener
+     * that triggers auto-resync on `numberOfSubAccounts` changes.
+     */
     async unsubscribe() {
         await this.subscription.unsubscribe();
         for (const [key, user] of this.entries()) {
@@ -477,6 +545,13 @@ class UserMap {
             this.lastNumberOfSubAccounts = undefined;
         }
     }
+    /**
+     * Applies a fresh `userAccount` observation for `key` at `slot`. If the
+     * user is already cached, updates in place only if `slot` is at least as
+     * new as the cached slot (stale/out-of-order updates are dropped) and
+     * emits `'userUpdate'`. If not cached yet, adds it via `addPubkey`.
+     * Also advances `getSlot()`'s tracked most-recent slot.
+     */
     async updateUserAccount(key, userAccount, slot) {
         const userWithSlot = this.getWithSlot(key);
         this.updateLatestSlot(slot);
@@ -491,12 +566,14 @@ class UserMap {
             }
         }
         else {
-            this.addPubkey(new web3_js_1.PublicKey(key), userAccount, slot);
+            await this.addPubkey(new web3_js_1.PublicKey(key), userAccount, slot);
         }
     }
+    /** Advances the map's tracked most-recent slot to `slot` if it's newer. */
     updateLatestSlot(slot) {
         this.mostRecentSlot = Math.max(slot, this.mostRecentSlot);
     }
+    /** Returns the most recent slot at which any account update has been observed. */
     getSlot() {
         return this.mostRecentSlot;
     }

package/lib/browser/userMap/userMapConfig.d.ts

@@ -1,20 +1,32 @@
 import { Commitment, Connection, MemcmpFilter } from '@solana/web3.js';
 import { VelocityClient } from '../velocityClient';
 import { GrpcConfigs } from '../accounts/types';
+/** Passed into `UserMap.getUniqueAuthorities` to filter which users' authorities are returned. */
 export type UserAccountFilterCriteria = {
+    /** Only return users that have `hasOpenOrder` set on their `UserAccount`. */
     hasOpenOrders: boolean;
 };
+/**
+ * Selects how `UserMap`/`UserStatsMap` bulk-load accounts on sync.
+ * - `'default'`: a single `getProgramAccounts` call with server-side memcmp filters. Simple, but can hit RPC/node response-size limits when there are many accounts.
+ * - `'paginated'`: a filtered `getProgramAccounts` prefetch for just the pubkeys, followed by chunked `getMultipleAccountsInfoAndContext` calls with bounded concurrency. More RPC calls, but scales to large account counts.
+ */
 export type SyncConfig = {
     type: 'default';
 } | {
     type: 'paginated';
+    /** Number of accounts fetched per `getMultipleAccountsInfoAndContext` call. Defaults to 100. */
     chunkSize?: number;
+    /** Max number of chunk-fetch tasks in flight at once. Defaults to 10. */
     concurrencyLimit?: number;
 };
 type UserMapConfigBase = {
+    /** Connection to use specifically for this map. If omitted, uses the `VelocityClient`'s connection. */
     connection?: Connection;
+    /** How the map keeps its accounts up to date after the initial sync. */
     subscriptionConfig: {
         type: 'polling';
+        /** Milliseconds between full re-syncs. */
         frequency: number;
         commitment?: Commitment;
     } | {
@@ -28,13 +40,24 @@ type UserMapConfigBase = {
         logResubMessages?: boolean;
         commitment?: Commitment;
     };
+    /** True to skip the initial load of userAccounts via getProgramAccounts */
     skipInitialLoad?: boolean;
+    /** True to include idle users when loading. Defaults to false to decrease # of accounts subscribed to. */
     includeIdle?: boolean;
+    /** Whether to skip loading available perp/spot positions and open orders */
     fastDecode?: boolean;
+    /**
+     * If true, will not do a full sync whenever StateAccount.numberOfSubAccounts changes.
+     * default behavior is to do a full sync on changes.
+     */
     disableSyncOnTotalAccountsChange?: boolean;
+    /** Bulk-load strategy for the initial sync and subsequent full syncs. Defaults to `{ type: 'default' }`. */
     syncConfig?: SyncConfig;
+    /** Whether to throw an error if the userMap fails to sync. Defaults to false (errors are logged, not thrown). */
     throwOnFailedSync?: boolean;
+    /** Whether to filter users by poolId. Defaults to undefined (all users, all pools). */
     filterByPoolId?: number;
+    /** Extra memcmp filters ANDed onto the base `User`-account filter (and, unless `includeIdle`, the non-idle filter) for both the initial sync and the live subscription. */
     additionalFilters?: MemcmpFilter[];
 };
 export type UserMapConfig = UserMapConfigBase & {

package/lib/browser/userMap/userStatsMap.d.ts

@@ -6,6 +6,12 @@ import { BulkAccountLoader } from '../accounts/bulkAccountLoader';
 import { SyncConfig } from './userMapConfig';
 import { PublicKey } from '@solana/web3.js';
 import { UserMap } from './userMap';
+/**
+ * In-memory cache of `UserStats` accounts (one per trading authority, shared
+ * across that authority's sub-accounts), keyed by authority pubkey. Backed by
+ * a shared `BulkAccountLoader` for the default sync strategy so many
+ * `UserStats` can be fetched/polled together instead of one subscription each.
+ */
 export declare class UserStatsMap {
     /**
      * map from authority pubkey to UserStats
@@ -24,6 +30,7 @@ export declare class UserStatsMap {
      * @param {BulkAccountLoader} [bulkAccountLoader] - If not provided, a new BulkAccountLoader with polling disabled will be created.
      */
     constructor(velocityClient: VelocityClient, bulkAccountLoader?: BulkAccountLoader, syncConfig?: SyncConfig);
+    /** Populates the map for `authorities` via `sync()` (no-op if the map already has entries). */
     subscribe(authorities: PublicKey[]): Promise<void>;
     /**
      *
@@ -32,9 +39,21 @@ export declare class UserStatsMap {
      * @param skipFetch if true, will not immediately fetch the UserStatsAccount
      */
     addUserStat(authority: PublicKey, userStatsAccount?: UserStatsAccount, skipFetch?: boolean): Promise<void>;
+    /** Ensures the `UserStats` entry exists for the authority behind `record.user` (looked up/created in `userMap` first), adding it if this map doesn't have it yet. */
     updateWithOrderRecord(record: OrderRecord, userMap: UserMap): Promise<void>;
+    /**
+     * Incrementally updates the map in response to a single program event,
+     * ensuring a `UserStats` entry exists for every authority the event
+     * references (deposit/funding/new-user/IF-stake records reference an
+     * authority directly; order/liquidation/settle-pnl/order-action records
+     * reference a `User` account and require `userMap` to resolve its authority).
+     * Events whose required `userMap` is not supplied, or whose type isn't
+     * recognized, are silently ignored.
+     */
     updateWithEventRecord(record: WrappedEvent<any>, userMap?: UserMap): Promise<void>;
+    /** Returns true if `authorityPublicKey` has a `UserStats` cached in the map. */
     has(authorityPublicKey: string): boolean;
+    /** Returns the cached `UserStats` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
     get(authorityPublicKey: string): UserStats | undefined;
     /**
      * Enforce that a UserStats will exist for the given authorityPublicKey,
@@ -43,7 +62,9 @@ export declare class UserStatsMap {
      * @returns
      */
     mustGet(authorityPublicKey: string): Promise<UserStats>;
+    /** Iterates all cached `UserStats` instances. */
     values(): IterableIterator<UserStats>;
+    /** Number of authorities currently cached in the map. */
     size(): number;
     /**
      * Sync the UserStatsMap
@@ -62,5 +83,6 @@ export declare class UserStatsMap {
      * @param authorities
      */
     private paginatedSync;
+    /** Unsubscribes and removes every cached `UserStats` from the map. */
     unsubscribe(): Promise<void>;
 }