@velocity-exchange/sdk 0.3.0 → 0.6.0

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

@@ -1,15 +1,25 @@
 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 declare class PollingSubscription {
     private userMap;
     private frequency;
     private skipInitialLoad;
     intervalId?: ReturnType<typeof setTimeout>;
+    private active;
     constructor({ userMap, frequency, skipInitialLoad, }: {
         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;
     });
+    /** Starts the polling loop. No-op if already started or `frequency <= 0`. */
     subscribe(): Promise<void>;
+    /** Stops the polling loop. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/userMap/PollingSubscription.js

@@ -1,26 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingSubscription = void 0;
+/**
+ * `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.
+ */
 class PollingSubscription {
     constructor({ userMap, frequency, skipInitialLoad = false, }) {
+        this.active = false;
         this.userMap = userMap;
         this.frequency = frequency;
         this.skipInitialLoad = skipInitialLoad;
     }
+    /** Starts the polling loop. No-op if already started or `frequency <= 0`. */
     async subscribe() {
-        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) {
             await this.userMap.sync();
         }
         executeSync();
     }
+    /** Stops the polling loop. */
     async unsubscribe() {
+        this.active = false;
         if (this.intervalId) {
             clearInterval(this.intervalId);
             this.intervalId = undefined;

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

@@ -4,6 +4,14 @@ import { UserMap } from './userMap';
 import { UserAccount } from '../types';
 import { Commitment, MemcmpFilter } 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 declare class WebsocketSubscription {
     private userMap;
     private commitment;
@@ -22,6 +30,7 @@ export declare class WebsocketSubscription {
         decodeFn: (name: string, data: Buffer) => UserAccount;
         additionalFilters?: MemcmpFilter[];
     });
+    /** Starts the websocket program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
 }

package/lib/browser/userMap/WebsocketSubscription.js

@@ -3,6 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebsocketSubscription = void 0;
 const memcmp_1 = require("../memcmp");
 const webSocketProgramAccountSubscriber_1 = require("../accounts/webSocketProgramAccountSubscriber");
+/**
+ * `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.
+ */
 class WebsocketSubscription {
     constructor({ userMap, commitment, skipInitialLoad = false, resubOpts, includeIdle = false, decodeFn, additionalFilters = undefined, }) {
         this.userMap = userMap;
@@ -13,6 +21,7 @@ class WebsocketSubscription {
         this.decodeFn = decodeFn;
         this.additionalFilters = additionalFilters;
     }
+    /** Starts the websocket program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
     async subscribe() {
         if (!this.subscriber) {
             const filters = [(0, memcmp_1.getUserFilter)()];

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

@@ -4,6 +4,13 @@ import { UserMap } from './userMap';
 import { UserAccount } from '../types';
 import { MemcmpFilter } from '@solana/web3.js';
 import { GrpcConfigs, ResubOpts } from '../accounts/types';
+/**
+ * `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 declare class grpcSubscription {
     private grpcConfigs;
     private userMap;
@@ -22,6 +29,7 @@ export declare class grpcSubscription {
         decodeFn: (name: string, data: Buffer) => UserAccount;
         additionalFilters?: MemcmpFilter[];
     });
+    /** Starts the gRPC program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
 }

package/lib/browser/userMap/grpcSubscription.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.grpcSubscription = void 0;
 const memcmp_1 = require("../memcmp");
 const grpcProgramAccountSubscriber_1 = require("../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.
+ */
 class grpcSubscription {
     constructor({ grpcConfigs, userMap, skipInitialLoad = false, resubOpts, includeIdle = false, decodeFn, additionalFilters = undefined, }) {
         this.userMap = userMap;
@@ -13,6 +20,7 @@ class grpcSubscription {
         this.grpcConfigs = grpcConfigs;
         this.additionalFilters = additionalFilters;
     }
+    /** Starts the gRPC program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
     async subscribe() {
         if (!this.subscriber) {
             const filters = [(0, memcmp_1.getUserFilter)()];

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

@@ -1,6 +1,12 @@
 import { MemcmpFilter } from '@solana/web3.js';
 import { VelocityClient } from '../velocityClient';
 import { ReferrerInfo } from '../types';
+/**
+ * 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 declare class ReferrerMap {
     /**
      * map from authority pubkey to referrer pubkey.
@@ -11,23 +17,54 @@ export declare class ReferrerMap {
      * Will be undefined if the referrer is not in the map yet.
      */
     private referrerReferrerInfoMap;
+    /**
+     * 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;
     private velocityClient;
     private parallelSync;
     private fetchPromise?;
     private fetchPromiseResolver;
     /**
-     * Creates a new UserStatsMap instance.
+     * Creates a new ReferrerMap instance.
      *
      * @param {VelocityClient} velocityClient - The VelocityClient instance.
      */
     constructor(velocityClient: VelocityClient, parallelSync?: boolean);
     /**
-     * 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.
      */
     subscribe(): Promise<void>;
+    /** Returns true if `authorityPublicKey` has been synced into the map (has a known referrer, even if that referrer is "none"). */
     has(authorityPublicKey: string): boolean;
+    /** Alias for `getReferrer`. */
     get(authorityPublicKey: string): ReferrerInfo | undefined;
+    /**
+     * 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`.
+     */
     addReferrer(authority: string, referrer?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    isBuilderReferral(authorityPublicKey: string): boolean;
+    /**
+     * 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}).
+     */
+    mustGetIsBuilderReferral(authorityPublicKey: string): Promise<boolean>;
     /**
      * Enforce that a UserStats will exist for the given authorityPublicKey,
      * reading one from the blockchain if necessary.
@@ -35,11 +72,44 @@ export declare class ReferrerMap {
      * @returns
      */
     mustGet(authorityPublicKey: string): Promise<ReferrerInfo | undefined>;
+    /**
+     * 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).
+     */
     getReferrer(authorityPublicKey: string): ReferrerInfo | undefined;
+    /** Number of authorities synced into the map (referred or not). */
     size(): number;
+    /** Number of synced authorities that actually have a referrer set (excludes those with the default/zero pubkey). */
     numberOfReferred(): number;
+    /**
+     * 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.
+     */
     sync(): Promise<void>;
+    /**
+     * 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.
+     */
     syncAll(): Promise<void>;
+    /**
+     * 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`.
+     */
     syncReferrer(referrerFilter: MemcmpFilter): Promise<void>;
+    /** Clears the in-memory maps. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/userMap/referrerMap.js

@@ -7,11 +7,20 @@ exports.ReferrerMap = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const pda_1 = require("../addresses/pda");
 const memcmp_1 = require("../memcmp");
+const builder_1 = require("../math/builder");
 const bs58_1 = __importDefault(require("bs58"));
 const DEFAULT_PUBLIC_KEY = web3_js_1.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.
+ */
 class ReferrerMap {
     /**
-     * Creates a new UserStatsMap instance.
+     * Creates a new ReferrerMap instance.
      *
      * @param {VelocityClient} velocityClient - The VelocityClient instance.
      */
@@ -25,12 +34,21 @@ class ReferrerMap {
          * Will be undefined if the referrer is not in the map yet.
          */
         this.referrerReferrerInfoMap = new Map();
+        /**
+         * 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`.
+         */
+        this.authorityBuilderReferralMap = new Map();
         this.fetchPromiseResolver = () => { };
         this.velocityClient = velocityClient;
         this.parallelSync = parallelSync !== undefined ? parallelSync : true;
     }
     /**
-     * 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.
      */
     async subscribe() {
         if (this.size() > 0) {
@@ -39,12 +57,21 @@ class ReferrerMap {
         await this.velocityClient.subscribe();
         await this.sync();
     }
+    /** Returns true if `authorityPublicKey` has been synced into the map (has a known referrer, even if that referrer is "none"). */
     has(authorityPublicKey) {
         return this.authorityReferrerMap.has(authorityPublicKey);
     }
+    /** Alias for `getReferrer`. */
     get(authorityPublicKey) {
         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`.
+     */
     async addReferrer(authority, referrer) {
         if (referrer) {
             this.authorityReferrerMap.set(authority, referrer);
@@ -56,10 +83,32 @@ class ReferrerMap {
                 throw new Error(`ReferrerMap: UserStats account not found for authority ${authority}`);
             }
             const buffer = accountInfo.data;
+            this.authorityBuilderReferralMap.set(authority, (0, builder_1.isBuilderReferral)({ referrerStatus: buffer[REFERRER_STATUS_OFFSET] }));
             const referrer = bs58_1.default.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.
+     */
+    isBuilderReferral(authorityPublicKey) {
+        var _a;
+        return (_a = this.authorityBuilderReferralMap.get(authorityPublicKey)) !== null && _a !== void 0 ? _a : 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}).
+     */
+    async mustGetIsBuilderReferral(authorityPublicKey) {
+        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.
@@ -72,6 +121,12 @@ 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).
+     */
     getReferrer(authorityPublicKey) {
         const referrer = this.authorityReferrerMap.get(authorityPublicKey);
         if (!referrer) {
@@ -92,12 +147,23 @@ class ReferrerMap {
         this.referrerReferrerInfoMap.set(referrer, referrerInfo);
         return referrerInfo;
     }
+    /** Number of authorities synced into the map (referred or not). */
     size() {
         return this.authorityReferrerMap.size;
     }
+    /** Number of synced authorities that actually have a referrer set (excludes those with the default/zero pubkey). */
     numberOfReferred() {
         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.
+     */
     async sync() {
         if (this.fetchPromise) {
             return this.fetchPromise;
@@ -124,6 +190,12 @@ class ReferrerMap {
             this.fetchPromise = undefined;
         }
     }
+    /**
+     * 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.
+     */
     async syncAll() {
         var _a;
         const rpcRequestArgs = [
@@ -151,6 +223,15 @@ 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) {
         var _a;
         const rpcRequestArgs = [
@@ -183,6 +264,7 @@ class ReferrerMap {
             await new Promise((resolve) => setTimeout(resolve, 0));
         }
     }
+    /** Clears the in-memory maps. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
     async unsubscribe() {
         this.authorityReferrerMap.clear();
         this.referrerReferrerInfoMap.clear();

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

@@ -1,5 +1,6 @@
 import { VelocityClient } from '../velocityClient';
 import { RevenueShareEscrowAccount } from '../types';
+/** In-memory cache mapping each authority to their `RevenueShareEscrow` account (builder/referral fee accrual escrow). */
 export declare class RevenueShareEscrowMap {
     /**
      * map from authority pubkey to RevenueShareEscrow account data.
@@ -17,10 +18,14 @@ export declare class RevenueShareEscrowMap {
      */
     constructor(velocityClient: VelocityClient, parallelSync?: boolean);
     /**
-     * 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.
      */
     subscribe(): Promise<void>;
+    /** Returns true if `authorityPublicKey` has a `RevenueShareEscrow` account cached in the map. */
     has(authorityPublicKey: string): boolean;
+    /** Returns the cached `RevenueShareEscrowAccount` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
     get(authorityPublicKey: string): RevenueShareEscrowAccount | undefined;
     /**
      * Enforce that a RevenueShareEscrow will exist for the given authorityPublicKey,
@@ -29,38 +34,60 @@ export declare class RevenueShareEscrowMap {
      * @returns
      */
     mustGet(authorityPublicKey: string): Promise<RevenueShareEscrowAccount | undefined>;
+    /**
+     * 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.
+     */
     addRevenueShareEscrow(authority: string): Promise<void>;
+    /** Number of `RevenueShareEscrow` accounts currently cached in the map. */
     size(): number;
+    /** Fully (re)populates the map via `syncAll` (a `getProgramAccounts` scan). Concurrent calls share the same in-flight promise. */
     sync(): Promise<void>;
     /**
      * A slow, bankrun test friendly version of sync(), uses getAccountInfo on every cached account to refresh data
      * @returns
      */
     slowSync(): Promise<void>;
-    syncAll(): Promise<void>;
     /**
-     * Get all RevenueShareEscrow accounts
+     * 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.
      */
+    syncAll(): Promise<void>;
+    /** Returns a shallow copy of the full authority-to-escrow map (mutating the returned map does not affect the cache). */
     getAll(): Map<string, RevenueShareEscrowAccount>;
-    /**
-     * Get all authorities that have RevenueShareEscrow accounts
-     */
+    /** Returns the base58 authority pubkeys of every `RevenueShareEscrow` account currently cached. */
     getAuthorities(): string[];
     /**
-     * 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(): Map<string, RevenueShareEscrowAccount>;
     /**
-     * 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(): Map<string, RevenueShareEscrowAccount>;
     /**
-     * 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: string): RevenueShareEscrowAccount | 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: string): RevenueShareEscrowAccount[];
+    /** Clears the in-memory map. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
     unsubscribe(): Promise<void>;
 }