@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/userMap/PollingSubscription.ts

@@ -1,11 +1,17 @@
 import { UserMap } from './userMap';
 
+/**
+ * `UserMap`'s `'polling'` subscription strategy: re-runs a full `userMap.sync()`
+ * on a fixed `setTimeout` interval (self-rescheduling, so syncs never overlap).
+ * Internal to `UserMap` — not part of the SDK's public exports.
+ */
 export class PollingSubscription {
 	private userMap: UserMap;
 	private frequency: number;
 	private skipInitialLoad: boolean;
 
 	intervalId?: ReturnType<typeof setTimeout>;
+	private active = false;
 
 	constructor({
 		userMap,
@@ -13,7 +19,9 @@ export class PollingSubscription {
 		skipInitialLoad = false,
 	}: {
 		userMap: UserMap;
+		/** Milliseconds to wait after one sync completes before starting the next. */
 		frequency: number;
+		/** If true, does not sync immediately on `subscribe()` — the first sync happens after `frequency` ms. */
 		skipInitialLoad?: boolean;
 		includeIdle?: boolean;
 	}) {
@@ -22,14 +30,18 @@ export class PollingSubscription {
 		this.skipInitialLoad = skipInitialLoad;
 	}
 
+	/** Starts the polling loop. No-op if already started or `frequency <= 0`. */
 	public async subscribe(): Promise<void> {
-		if (this.intervalId || this.frequency <= 0) {
+		if (this.active || this.frequency <= 0) {
 			return;
 		}
+		this.active = true;
 
 		const executeSync = async () => {
 			await this.userMap.sync();
-			this.intervalId = setTimeout(executeSync, this.frequency);
+			if (this.active) {
+				this.intervalId = setTimeout(executeSync, this.frequency);
+			}
 		};
 
 		if (!this.skipInitialLoad) {
@@ -38,7 +50,9 @@ export class PollingSubscription {
 		executeSync();
 	}
 
+	/** Stops the polling loop. */
 	public async unsubscribe(): Promise<void> {
+		this.active = false;
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
 			this.intervalId = undefined;

package/src/userMap/WebsocketSubscription.ts

@@ -5,6 +5,14 @@ import { UserAccount } from '../types';
 import { Commitment, Context, MemcmpFilter, PublicKey } from '@solana/web3.js';
 import { ResubOpts } from '../accounts/types';
 
+/**
+ * `UserMap`'s `'websocket'` subscription strategy: uses
+ * `WebSocketProgramAccountSubscriber` with the map's memcmp filters (base
+ * `User` filter, plus non-idle unless `includeIdle`, plus any
+ * `additionalFilters`) to receive push updates for every matching account,
+ * feeding them into `userMap.updateUserAccount`. Internal to `UserMap` — not
+ * part of the SDK's public exports.
+ */
 export class WebsocketSubscription {
 	private userMap: UserMap;
 	private commitment: Commitment;
@@ -42,6 +50,7 @@ export class WebsocketSubscription {
 		this.additionalFilters = additionalFilters;
 	}
 
+	/** Starts the websocket program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
 	public async subscribe(): Promise<void> {
 		if (!this.subscriber) {
 			const filters = [getUserFilter()];

package/src/userMap/grpcSubscription.ts

@@ -6,6 +6,13 @@ import { Context, MemcmpFilter, PublicKey } from '@solana/web3.js';
 import { GrpcConfigs, ResubOpts } from '../accounts/types';
 import { grpcProgramAccountSubscriber } from '../accounts/grpcProgramAccountSubscriber';
 
+/**
+ * `UserMap`'s `'grpc'` subscription strategy: mirrors `WebsocketSubscription`
+ * but subscribes via a Geyser gRPC stream (`grpcProgramAccountSubscriber`)
+ * using the same memcmp filter set, feeding updates into
+ * `userMap.updateUserAccount`. Internal to `UserMap` — not part of the SDK's
+ * public exports.
+ */
 export class grpcSubscription {
 	private grpcConfigs: GrpcConfigs;
 	private userMap: UserMap;
@@ -43,6 +50,7 @@ export class grpcSubscription {
 		this.additionalFilters = additionalFilters;
 	}
 
+	/** Starts the gRPC program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
 	public async subscribe(): Promise<void> {
 		if (!this.subscriber) {
 			const filters = [getUserFilter()];

package/src/userMap/referrerMap.ts

@@ -14,10 +14,19 @@ import {
 	getUserStatsIsReferredFilter,
 	getUserStatsIsReferredOrReferrerFilter,
 } from '../memcmp';
+import { isBuilderReferral } from '../math/builder';
 import bs58 from 'bs58';
 
 const DEFAULT_PUBLIC_KEY = PublicKey.default.toBase58();
-
+// Byte offset of `UserStats.referrer_status` (u8). Matches the memcmp filters.
+const REFERRER_STATUS_OFFSET = 188;
+
+/**
+ * In-memory cache mapping each trading authority to their referrer, built by
+ * scanning `UserStats` accounts with memcmp filters on the referrer-status
+ * byte (see `syncAll`/`syncReferrer`) rather than subscribing to every
+ * account's full data.
+ */
 export class ReferrerMap {
 	/**
 	 * map from authority pubkey to referrer pubkey.
@@ -28,6 +37,13 @@ export class ReferrerMap {
 	 * Will be undefined if the referrer is not in the map yet.
 	 */
 	private referrerReferrerInfoMap = new Map<string, ReferrerInfo>();
+	/**
+	 * map from authority pubkey to whether its escrow was initialized with a
+	 * referrer (the `BuilderReferral` status bit). Only populated by the lazy
+	 * full-account path (`addReferrer` / `mustGetIsBuilderReferral`) — the bulk
+	 * sync uses narrow data slices that don't cover `referrer_status`.
+	 */
+	private authorityBuilderReferralMap = new Map<string, boolean>();
 	private velocityClient: VelocityClient;
 	private parallelSync: boolean;
 
@@ -35,7 +51,7 @@ export class ReferrerMap {
 	private fetchPromiseResolver: () => void = () => {};
 
 	/**
-	 * Creates a new UserStatsMap instance.
+	 * Creates a new ReferrerMap instance.
 	 *
 	 * @param {VelocityClient} velocityClient - The VelocityClient instance.
 	 */
@@ -45,7 +61,9 @@ export class ReferrerMap {
 	}
 
 	/**
-	 * Subscribe to all UserStats accounts.
+	 * Populates the map via a one-time `sync()` (no-op if already populated).
+	 * There is no live/push subscription here — call `sync()` again later to
+	 * pick up new referrers.
 	 */
 	public async subscribe() {
 		if (this.size() > 0) {
@@ -56,14 +74,23 @@ export class ReferrerMap {
 		await this.sync();
 	}
 
+	/** Returns true if `authorityPublicKey` has been synced into the map (has a known referrer, even if that referrer is "none"). */
 	public has(authorityPublicKey: string): boolean {
 		return this.authorityReferrerMap.has(authorityPublicKey);
 	}
 
+	/** Alias for `getReferrer`. */
 	public get(authorityPublicKey: string): ReferrerInfo | undefined {
 		return this.getReferrer(authorityPublicKey);
 	}
 
+	/**
+	 * Records `authority`'s referrer. If `referrer` is omitted, fetches the
+	 * authority's `UserStats` account directly via RPC and reads the referrer
+	 * pubkey out of its raw bytes (offset 40..72, immediately after the
+	 * discriminator + authority fields) rather than fully decoding the account.
+	 * @throws If `referrer` is omitted and no `UserStats` account exists on chain for `authority`.
+	 */
 	public async addReferrer(authority: string, referrer?: string) {
 		if (referrer) {
 			this.authorityReferrerMap.set(authority, referrer);
@@ -83,12 +110,41 @@ export class ReferrerMap {
 			}
 			const buffer = accountInfo.data;
 
+			this.authorityBuilderReferralMap.set(
+				authority,
+				isBuilderReferral({ referrerStatus: buffer[REFERRER_STATUS_OFFSET] })
+			);
+
 			const referrer = bs58.encode(buffer.subarray(40, 72));
 
 			this.addReferrer(authority, referrer);
 		}
 	}
 
+	/**
+	 * True when the authority's escrow was initialized with a referrer (the
+	 * `BuilderReferral` status bit). Returns `false` until the authority's
+	 * UserStats has been read via the lazy path; use {@link mustGetIsBuilderReferral}
+	 * to force a read.
+	 */
+	public isBuilderReferral(authorityPublicKey: string): boolean {
+		return this.authorityBuilderReferralMap.get(authorityPublicKey) ?? false;
+	}
+
+	/**
+	 * Like {@link isBuilderReferral} but reads the authority's UserStats from the
+	 * chain if the status hasn't been cached yet. Throws if the UserStats account
+	 * cannot be loaded (same as {@link addReferrer}).
+	 */
+	public async mustGetIsBuilderReferral(
+		authorityPublicKey: string
+	): Promise<boolean> {
+		if (!this.authorityBuilderReferralMap.has(authorityPublicKey)) {
+			await this.addReferrer(authorityPublicKey);
+		}
+		return this.isBuilderReferral(authorityPublicKey);
+	}
+
 	/**
 	 * Enforce that a UserStats will exist for the given authorityPublicKey,
 	 * reading one from the blockchain if necessary.
@@ -104,6 +160,12 @@ export class ReferrerMap {
 		return this.getReferrer(authorityPublicKey);
 	}
 
+	/**
+	 * Resolves `authorityPublicKey`'s referrer to a `ReferrerInfo` (the
+	 * referrer's `User` sub-account-0 and `UserStats` addresses), caching the
+	 * derived addresses per referrer pubkey.
+	 * @returns `undefined` if `authorityPublicKey` isn't in the map yet, or if it has no referrer (default/zero pubkey).
+	 */
 	public getReferrer(authorityPublicKey: string): ReferrerInfo | undefined {
 		const referrer = this.authorityReferrerMap.get(authorityPublicKey);
 		if (!referrer) {
@@ -136,16 +198,27 @@ export class ReferrerMap {
 		return referrerInfo;
 	}
 
+	/** Number of authorities synced into the map (referred or not). */
 	public size(): number {
 		return this.authorityReferrerMap.size;
 	}
 
+	/** Number of synced authorities that actually have a referrer set (excludes those with the default/zero pubkey). */
 	public numberOfReferred(): number {
 		return Array.from(this.authorityReferrerMap.values()).filter(
 			(referrer) => referrer !== DEFAULT_PUBLIC_KEY
 		).length;
 	}
 
+	/**
+	 * Fully (re)populates the map: `syncAll` seeds every `UserStats` authority
+	 * with a default ("no referrer") entry, then `syncReferrer` overwrites
+	 * entries for authorities matching the is-referred and
+	 * is-referred-or-referrer memcmp filters with their actual referrer. Runs
+	 * the three passes in parallel by default (`parallelSync`), or serially if
+	 * constructed with `parallelSync: false`. Concurrent calls share the same
+	 * in-flight promise.
+	 */
 	public async sync(): Promise<void> {
 		if (this.fetchPromise) {
 			return this.fetchPromise;
@@ -173,6 +246,12 @@ export class ReferrerMap {
 		}
 	}
 
+	/**
+	 * Fetches every `UserStats` account pubkey (via a `getUserStatsFilter`
+	 * memcmp filter, with a zero-length `dataSlice` so no account data is
+	 * transferred) and seeds a default ("no referrer") entry for any authority
+	 * not already present in the map.
+	 */
 	public async syncAll(): Promise<void> {
 		const rpcRequestArgs = [
 			this.velocityClient.program.programId.toBase58(),
@@ -213,6 +292,15 @@ export class ReferrerMap {
 		}
 	}
 
+	/**
+	 * Fetches `UserStats` accounts matching `referrerFilter` combined with the
+	 * base `UserStats` discriminator filter, with a `dataSlice` of exactly the
+	 * bytes needed (offset 0, length 72 — discriminator + authority + referrer)
+	 * to avoid transferring full account data. Decodes `authority`/`referrer`
+	 * directly from the byte offsets and unconditionally sets them in the map
+	 * (in batches of 1000, yielding to the event loop between batches).
+	 * @param referrerFilter A memcmp filter selecting which referrer-status accounts to sync, e.g. from `getUserStatsIsReferredFilter`/`getUserStatsIsReferredOrReferrerFilter`.
+	 */
 	async syncReferrer(referrerFilter: MemcmpFilter): Promise<void> {
 		const rpcRequestArgs = [
 			this.velocityClient.program.programId.toBase58(),
@@ -264,6 +352,7 @@ export class ReferrerMap {
 		}
 	}
 
+	/** Clears the in-memory maps. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
 	public async unsubscribe() {
 		this.authorityReferrerMap.clear();
 		this.referrerReferrerInfoMap.clear();

package/src/userMap/revenueShareEscrowMap.ts

@@ -4,6 +4,7 @@ import { RevenueShareEscrowAccount } from '../types';
 import { getRevenueShareEscrowAccountPublicKey } from '../addresses/pda';
 import { getRevenueShareEscrowFilter } from '../memcmp';
 
+/** In-memory cache mapping each authority to their `RevenueShareEscrow` account (builder/referral fee accrual escrow). */
 export class RevenueShareEscrowMap {
 	/**
 	 * map from authority pubkey to RevenueShareEscrow account data.
@@ -27,7 +28,9 @@ export class RevenueShareEscrowMap {
 	}
 
 	/**
-	 * 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.
 	 */
 	public async subscribe() {
 		if (this.size() > 0) {
@@ -38,10 +41,12 @@ export class RevenueShareEscrowMap {
 		await this.sync();
 	}
 
+	/** Returns true if `authorityPublicKey` has a `RevenueShareEscrow` account cached in the map. */
 	public has(authorityPublicKey: string): boolean {
 		return this.authorityEscrowMap.has(authorityPublicKey);
 	}
 
+	/** Returns the cached `RevenueShareEscrowAccount` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
 	public get(
 		authorityPublicKey: string
 	): RevenueShareEscrowAccount | undefined {
@@ -63,6 +68,12 @@ export 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.
+	 */
 	public async addRevenueShareEscrow(authority: string) {
 		const escrowAccountPublicKey = getRevenueShareEscrowAccountPublicKey(
 			this.velocityClient.program.programId,
@@ -93,10 +104,12 @@ export class RevenueShareEscrowMap {
 		}
 	}
 
+	/** Number of `RevenueShareEscrow` accounts currently cached in the map. */
 	public size(): number {
 		return this.authorityEscrowMap.size;
 	}
 
+	/** Fully (re)populates the map via `syncAll` (a `getProgramAccounts` scan). Concurrent calls share the same in-flight promise. */
 	public async sync(): Promise<void> {
 		if (this.fetchPromise) {
 			return this.fetchPromise;
@@ -145,6 +158,14 @@ export class RevenueShareEscrowMap {
 		}
 	}
 
+	/**
+	 * 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.
+	 */
 	public async syncAll(): Promise<void> {
 		const rpcRequestArgs = [
 			this.velocityClient.program.programId.toBase58(),
@@ -237,22 +258,20 @@ export class RevenueShareEscrowMap {
 		}
 	}
 
-	/**
-	 * Get all RevenueShareEscrow accounts
-	 */
+	/** Returns a shallow copy of the full authority-to-escrow map (mutating the returned map does not affect the cache). */
 	public getAll(): Map<string, RevenueShareEscrowAccount> {
 		return new Map(this.authorityEscrowMap);
 	}
 
-	/**
-	 * Get all authorities that have RevenueShareEscrow accounts
-	 */
+	/** Returns the base58 authority pubkeys of every `RevenueShareEscrow` account currently cached. */
 	public getAuthorities(): string[] {
 		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).
 	 */
 	public getEscrowsWithApprovedReferrers(): Map<
 		string,
@@ -268,7 +287,9 @@ export class RevenueShareEscrowMap {
 	}
 
 	/**
-	 * 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.
 	 */
 	public getEscrowsWithOrders(): Map<string, RevenueShareEscrowAccount> {
 		const result = new Map<string, RevenueShareEscrowAccount>();
@@ -281,7 +302,10 @@ export class RevenueShareEscrowMap {
 	}
 
 	/**
-	 * 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.
 	 */
 	public getByReferrer(
 		referrerPublicKey: string
@@ -295,7 +319,9 @@ export class RevenueShareEscrowMap {
 	}
 
 	/**
-	 * 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).
 	 */
 	public getAllByReferrer(
 		referrerPublicKey: string
@@ -309,6 +335,7 @@ export 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). */
 	public async unsubscribe() {
 		this.authorityEscrowMap.clear();
 	}

package/src/userMap/userMap.ts

@@ -50,6 +50,7 @@ import { EventEmitter } from 'events';
 // the end (RangeError: ERR_BUFFER_OUT_OF_BOUNDS). Must be >= the on-chain User size.
 const MAX_USER_ACCOUNT_SIZE_BYTES = 4496;
 
+/** Public surface implemented by `UserMap`. */
 export interface UserMapInterface {
 	eventEmitter: StrictEventEmitter<EventEmitter, UserEvents>;
 	subscribe(): Promise<void>;
@@ -79,6 +80,25 @@ export interface UserMapInterface {
 	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 class UserMap implements UserMapInterface {
 	private userMap = new Map<string, DataAndSlot<User>>();
 	velocityClient: VelocityClient;
@@ -186,6 +206,13 @@ export class UserMap implements UserMapInterface {
 		this.eventEmitter = new 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.
+	 */
 	public async subscribe() {
 		if (this.size() > 0) {
 			return;
@@ -204,6 +231,20 @@ export class UserMap implements UserMapInterface {
 		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.
+	 */
 	public async addPubkey(
 		userAccountPublicKey: PublicKey,
 		userAccount?: UserAccount,
@@ -239,6 +280,7 @@ export class UserMap implements UserMapInterface {
 		this.eventEmitter.emit('userUpdate', user);
 	}
 
+	/** Returns true if a `User` account keyed by `key` (the `User` account pubkey, base58) is cached in the map. */
 	public has(key: string): boolean {
 		return this.userMap.has(key);
 	}
@@ -251,6 +293,7 @@ export class UserMap implements UserMapInterface {
 	public get(key: string): User | undefined {
 		return this.userMap.get(key)?.data;
 	}
+	/** Like `get`, but also returns the slot at which the `User` account was last observed. */
 	public getWithSlot(key: string): DataAndSlot<User> | undefined {
 		return this.userMap.get(key);
 	}
@@ -278,6 +321,7 @@ export class UserMap implements UserMapInterface {
 		}
 		return userWithSlot.data;
 	}
+	/** Like `mustGet`, but also returns the slot at which the `User` account was observed. */
 	public async mustGetWithSlot(
 		key: string,
 		accountSubscription?: UserSubscriptionConfig
@@ -297,6 +341,7 @@ export class UserMap implements UserMapInterface {
 		return userWithSlot;
 	}
 
+	/** Like `mustGet`, but returns the underlying `UserAccount` data directly (throws if the `User`'s account is not loaded). */
 	public async mustGetUserAccount(key: string): Promise<UserAccount> {
 		const user = await this.mustGet(key);
 		return user.getUserAccountOrThrow();
@@ -316,9 +361,9 @@ export class UserMap implements UserMapInterface {
 	}
 
 	/**
-	 * 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).
 	 */
 	public async getDLOB(slot: number): Promise<DLOB> {
 		const dlob = new DLOB();
@@ -326,12 +371,19 @@ export class UserMap implements UserMapInterface {
 		return dlob;
 	}
 
+	/** Ensures an entry exists in the map for `record.user`, adding it via `addPubkey` if not already present. */
 	public async updateWithOrderRecord(record: OrderRecord) {
 		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.
+	 */
 	public async updateWithEventRecord(record: WrappedEvent<any>) {
 		if (record.eventType === 'DepositRecord') {
 			const depositRecord = record as DepositRecord;
@@ -365,24 +417,29 @@ export class UserMap implements UserMapInterface {
 		}
 	}
 
+	/** Iterates all cached `User` instances. */
 	public *values(): IterableIterator<User> {
 		for (const dataAndSlot of this.userMap.values()) {
 			yield dataAndSlot.data;
 		}
 	}
+	/** Like `values`, but paired with the slot each `User` was last observed at. */
 	public valuesWithSlot(): IterableIterator<DataAndSlot<User>> {
 		return this.userMap.values();
 	}
 
+	/** Iterates all `[userAccountPublicKey, User]` pairs in the map. */
 	public *entries(): IterableIterator<[string, User]> {
 		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. */
 	public entriesWithSlot(): IterableIterator<[string, DataAndSlot<User>]> {
 		return this.userMap.entries();
 	}
 
+	/** Number of `User` accounts currently cached in the map. */
 	public size(): number {
 		return this.userMap.size;
 	}
@@ -413,6 +470,7 @@ export class UserMap implements UserMapInterface {
 		return userAuthKeys;
 	}
 
+	/** Runs a full sync using the strategy configured in `UserMapConfig.syncConfig` (`'default'` or `'paginated'` — see `SyncConfig`). */
 	public async sync() {
 		if (this.syncConfig.type === 'default') {
 			return this.defaultSync();
@@ -421,6 +479,12 @@ export class UserMap implements UserMapInterface {
 		}
 	}
 
+	/**
+	 * 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(): MemcmpFilter[] {
 		const filters = [getUserFilter()];
 		if (!this.includeIdle) {
@@ -655,6 +719,11 @@ export class UserMap implements UserMapInterface {
 		}
 	}
 
+	/**
+	 * 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.
+	 */
 	public async unsubscribe() {
 		await this.subscription.unsubscribe();
 
@@ -675,6 +744,13 @@ export class UserMap implements UserMapInterface {
 		}
 	}
 
+	/**
+	 * 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.
+	 */
 	public async updateUserAccount(
 		key: string,
 		userAccount: UserAccount,
@@ -692,14 +768,16 @@ export class UserMap implements UserMapInterface {
 				this.eventEmitter.emit('userUpdate', userWithSlot.data);
 			}
 		} else {
-			this.addPubkey(new PublicKey(key), userAccount, slot);
+			await this.addPubkey(new PublicKey(key), userAccount, slot);
 		}
 	}
 
+	/** Advances the map's tracked most-recent slot to `slot` if it's newer. */
 	updateLatestSlot(slot: number): void {
 		this.mostRecentSlot = Math.max(slot, this.mostRecentSlot);
 	}
 
+	/** Returns the most recent slot at which any account update has been observed. */
 	public getSlot(): number {
 		return this.mostRecentSlot;
 	}