@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/accounts/grpcMultiAccountSubscriber.js

@@ -43,6 +43,15 @@ function commitmentLevelToCommitment(commitmentLevel) {
             return 'confirmed';
     }
 }
+/**
+ * Multiplexes many accounts of the same Anchor type onto a single gRPC Geyser subscribe stream,
+ * rather than one `grpcAccountSubscriber` per account. Optional generic `U` ("account props")
+ * lets a caller attach metadata (e.g. `OracleInfo`) per pubkey — or per **array** of `U` values
+ * for a pubkey backing multiple logical entries (see `accountPropsMap`, used when several oracle
+ * ids share one underlying account). Construct via the static `create` factory, not the
+ * constructor directly, since establishing the gRPC client is asynchronous. Accounts can be added/
+ * removed from an already-open stream via `addAccounts`/`removeAccounts` without a full resubscribe.
+ */
 class grpcMultiAccountSubscriber {
     get stream() {
         if (!this._stream) {
@@ -69,6 +78,18 @@ class grpcMultiAccountSubscriber {
             this.accountPropsMap = accountPropsMap;
         }
     }
+    /**
+     * Creates a gRPC client (or reuses `clientProp`) and constructs a `grpcMultiAccountSubscriber`.
+     * Does not itself start streaming — call `subscribe(accounts, onChange)` on the result.
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param accountName Anchor account type name all multiplexed accounts share, used for decoding via the program coder absent `decodeBuffer`.
+     * @param program Anchor program providing the connection (for `fetch()`) and coder.
+     * @param decodeBuffer Optional custom decode function receiving the buffer, the account's base58 pubkey, and its `accountProps` entry (or one element of it, if an array); defaults to `program.coder.accounts.decode(accountName, buffer)`.
+     * @param resubOpts Resubscription watchdog options; `resubTimeoutMs` triggers a full unsubscribe on inactivity (no automatic resubscribe here — see `onUnsubscribe`).
+     * @param clientProp Optional existing gRPC client to reuse instead of creating a new connection.
+     * @param onUnsubscribe Optional callback invoked after `unsubscribe()` completes (or the resub-timeout-driven unsubscribe fires), typically used by callers to drive their own resubscribe logic.
+     * @param accountPropsMap Optional per-pubkey metadata (or array of metadata, for a shared pubkey) passed through to `decodeBuffer` and the `subscribe`/`addAccounts` change callback.
+     */
     static async create(grpcConfigs, accountName, program, decodeBuffer, resubOpts, clientProp, onUnsubscribe, accountPropsMap) {
         var _a, _b;
         const client = clientProp
@@ -79,15 +100,31 @@ class grpcMultiAccountSubscriber {
         (_b = grpcConfigs.commitmentLevel) !== null && _b !== void 0 ? _b : grpc_1.CommitmentLevel.CONFIRMED;
         return new grpcMultiAccountSubscriber(client, commitmentLevel, accountName, program, decodeBuffer, resubOpts, onUnsubscribe, accountPropsMap);
     }
+    /**
+     * Seeds or overwrites the cached data for one account, bypassing gRPC/RPC. Used to inject
+     * data the caller already has (e.g. from an initial batch fetch) before the stream delivers
+     * live updates.
+     * @param accountPubkey Base58 pubkey of the account.
+     * @param data Decoded account data to store.
+     * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     setAccountData(accountPubkey, data, slot) {
         this.dataMap.set(accountPubkey, { data, slot: slot !== null && slot !== void 0 ? slot : 0 });
     }
+    /** Returns the cached data/slot for one account, or undefined if not yet loaded. */
     getAccountData(accountPubkey) {
         return this.dataMap.get(accountPubkey);
     }
+    /** Returns the full map of base58 pubkey to cached data/slot for every multiplexed account. */
     getAccountDataMap() {
         return this.dataMap;
     }
+    /**
+     * Fetches every subscribed account once via chunked `getMultipleAccountsInfoAndContext` calls
+     * (100 pubkeys per chunk, processed concurrently), updating `dataMap`/`bufferMap` for any
+     * account whose buffer changed at a non-decreasing slot. Errors are logged (if
+     * `resubOpts.logResubMessages`) and swallowed rather than thrown.
+     */
     async fetch() {
         var _a;
         try {
@@ -100,6 +137,7 @@ class grpcMultiAccountSubscriber {
             }
             // Process all chunks concurrently
             await Promise.all(chunks.map(async (chunk) => {
+                var _a;
                 const accountAddresses = chunk.map((accountId) => new web3_js_1.PublicKey(accountId));
                 const rpcResponseAndContext = await this.program.provider.connection.getMultipleAccountsInfoAndContext(accountAddresses, {
                     commitment: commitmentLevelToCommitment(this.commitmentLevel),
@@ -125,7 +163,18 @@ class grpcMultiAccountSubscriber {
                             buffer: newBuffer,
                             slot: currentSlot,
                         });
-                        const accountDecoded = this.program.coder.accounts.decode(this.accountName, newBuffer);
+                        // decode via the injected decoder (with accountProps) so backfill
+                        // matches the live-update decode path — the stock program coder
+                        // can't decode custom-decoder accounts (e.g. oracle buffers). For a
+                        // pubkey backing multiple props, seed from the first (dataMap is
+                        // keyed by pubkey; see the accountPropsMap notes above).
+                        const accountProps = (_a = this.accountPropsMap) === null || _a === void 0 ? void 0 : _a.get(accountId);
+                        const decodeProps = Array.isArray(accountProps)
+                            ? accountProps[0]
+                            : accountProps;
+                        const accountDecoded = this.decodeBufferFn
+                            ? this.decodeBufferFn(newBuffer, accountId, decodeProps)
+                            : this.program.coder.accounts.decode(this.accountName, newBuffer);
                         this.setAccountData(accountId, accountDecoded, currentSlot);
                     }
                 }
@@ -137,6 +186,13 @@ class grpcMultiAccountSubscriber {
             }
         }
     }
+    /**
+     * Opens a single gRPC subscribe stream covering all of `accounts`. Each update is decoded and
+     * cached (via `setAccountData`) before `onChange` is invoked. Idempotent: a no-op if already
+     * subscribed or mid-unsubscribe.
+     * @param accounts Pubkeys to include in the stream filter.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context` (including `slot`), the raw buffer, and any `accountProps` metadata registered for that pubkey.
+     */
     async subscribe(accounts, onChange) {
         var _a;
         if ((_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.logResubMessages) {
@@ -254,10 +310,24 @@ class grpcMultiAccountSubscriber {
             throw reason;
         });
     }
-    async addAccounts(accounts) {
+    /**
+     * Extends the already-open stream's filter to include `accounts` (re-writing the full
+     * accumulated filter set, since the gRPC protocol has no incremental "add" primitive), then
+     * immediately calls `fetch()` to backfill their initial data.
+     * @param accounts Additional pubkeys to start tracking.
+     * @param accountProps Optional per-pubkey metadata to merge into `accountPropsMap` so the
+     *   injected decoder can decode the newly added accounts (without it, a new `(pubkey, source)`
+     *   oracle would decode with missing `accountProps` and throw).
+     */
+    async addAccounts(accounts, accountProps) {
         for (const pk of accounts) {
             this.subscribedAccounts.add(pk.toBase58());
         }
+        if (accountProps) {
+            for (const [key, props] of accountProps.entries()) {
+                this.accountPropsMap.set(key, props);
+            }
+        }
         const request = {
             slots: {},
             accounts: {
@@ -287,6 +357,11 @@ class grpcMultiAccountSubscriber {
         });
         await this.fetch();
     }
+    /**
+     * Removes `accounts` from `subscribedAccounts`/`onChangeMap` and re-writes the stream's filter
+     * to exclude them. Does not clear their cached data from `dataMap`/`bufferMap`.
+     * @param accounts Pubkeys to stop tracking.
+     */
     async removeAccounts(accounts) {
         for (const pk of accounts) {
             const k = pk.toBase58();
@@ -321,49 +396,55 @@ class grpcMultiAccountSubscriber {
             });
         });
     }
+    /** Writes an empty subscribe request to clear the stream's account filter, cancels any pending resub timeout, and invokes `onUnsubscribe` if one was registered at construction. */
     async unsubscribe() {
         this.isUnsubscribing = true;
         clearTimeout(this.timeoutId);
         this.timeoutId = undefined;
-        if (this.listenerId != null) {
-            const promise = new Promise((resolve, reject) => {
-                const request = {
-                    slots: {},
-                    accounts: {},
-                    transactions: {},
-                    blocks: {},
-                    blocksMeta: {},
-                    accountsDataSlice: [],
-                    entry: {},
-                    transactionsStatus: {},
-                };
-                this.stream.write(request, (err) => {
-                    if (err === null || err === undefined) {
-                        this.listenerId = undefined;
-                        this.isUnsubscribing = false;
-                        resolve();
-                    }
-                    else {
-                        reject(err);
-                    }
+        try {
+            if (this.listenerId != null) {
+                await new Promise((resolve, reject) => {
+                    const request = {
+                        slots: {},
+                        accounts: {},
+                        transactions: {},
+                        blocks: {},
+                        blocksMeta: {},
+                        accountsDataSlice: [],
+                        entry: {},
+                        transactionsStatus: {},
+                    };
+                    this.stream.write(request, (err) => {
+                        if (err === null || err === undefined) {
+                            this.listenerId = undefined;
+                            resolve();
+                        }
+                        else {
+                            reject(err);
+                        }
+                    });
+                }).catch((reason) => {
+                    console.error(reason);
+                    throw reason;
                 });
-            }).catch((reason) => {
-                console.error(reason);
-                throw reason;
-            });
-            return promise;
-        }
-        else {
-            this.isUnsubscribing = false;
-        }
-        if (this.onUnsubscribe) {
-            try {
-                await this.onUnsubscribe();
             }
-            catch (e) {
-                console.error(e);
+            // invoke onUnsubscribe on the normal path too (previously it only ran when
+            // listenerId was already null, so the resubscribe hook never fired on the
+            // standard unsubscribe path)
+            if (this.onUnsubscribe) {
+                try {
+                    await this.onUnsubscribe();
+                }
+                catch (e) {
+                    console.error(e);
+                }
             }
         }
+        finally {
+            // clear the flag on every exit path, including a failed stream.write, so
+            // the instance isn't wedged and can resubscribe
+            this.isUnsubscribing = false;
+        }
     }
     setTimeout() {
         var _a;

package/lib/node/accounts/grpcMultiUserAccountSubscriber.d.ts

@@ -3,6 +3,13 @@ import { PublicKey } from '@solana/web3.js';
 import { UserAccount } from '../types';
 import { VelocityProgram } from '../config';
 import { grpcMultiAccountSubscriber } from './grpcMultiAccountSubscriber';
+/**
+ * Multiplexes many `UserAccount` subscriptions onto a single `grpcMultiAccountSubscriber`,
+ * exposing a per-user `UserAccountSubscriber` facade via `forUser()` so callers (e.g. `User`
+ * instances) can interact with it as if each had its own subscription. New `forUser()` keys
+ * registered while already subscribed are debounced (`debounceMs`, 20ms) and flushed in a single
+ * batched `addAccounts` call rather than one gRPC round trip per user.
+ */
 export declare class grpcMultiUserAccountSubscriber {
     private program;
     private _multiSubscriber?;
@@ -13,13 +20,38 @@ export declare class grpcMultiUserAccountSubscriber {
     private pendingAddKeys;
     private debounceTimer?;
     private debounceMs;
+    /** Maximum time to wait in `subscribe()` for every registered user key to appear in the multi-subscriber's data map before giving up. */
+    private static readonly SUBSCRIBE_DATA_TIMEOUT_MS;
     private isMultiSubscribed;
     private userAccountSubscribers;
     private grpcConfigs;
     resubOpts?: ResubOpts;
     private handleAccountChange;
+    /**
+     * @param program Anchor program used for the per-user `fetch()` fallback.
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcMultiAccountSubscriber`.
+     * @param multiSubscriber Optional pre-constructed `grpcMultiAccountSubscriber` to reuse instead of creating a new one in `subscribe()`.
+     */
     constructor(program: VelocityProgram, grpcConfigs: GrpcConfigs, resubOpts?: ResubOpts, multiSubscriber?: grpcMultiAccountSubscriber<UserAccount>);
+    /**
+     * Creates the shared `grpcMultiAccountSubscriber` (if not injected at construction),
+     * subscribes every per-user facade already registered via `forUser()`, flushes any pending
+     * user keys into the underlying gRPC stream, and blocks until the multi-subscriber's account
+     * data map contains an entry for every registered user key (polling at `debounceMs` intervals),
+     * up to `SUBSCRIBE_DATA_TIMEOUT_MS`.
+     * @throws if any registered user key is still missing from the data map once the timeout elapses.
+     */
     subscribe(): Promise<void>;
+    /**
+     * Returns a `UserAccountSubscriber` facade for `userAccountPublicKey`, creating one on first
+     * call (subsequent calls for the same pubkey return the same instance). The facade's
+     * `subscribe()`/`unsubscribe()` register/deregister interest in this shared multi-subscriber
+     * rather than opening their own gRPC stream; the underlying account is only actually removed
+     * from the shared stream once every facade sharing that key has unsubscribed. Its `fetch()`
+     * bypasses the shared stream and issues a direct one-off `program.account.user.fetch` call.
+     * @param userAccountPublicKey Address of the `UserAccount` to get (or create) a facade for.
+     */
     forUser(userAccountPublicKey: PublicKey): UserAccountSubscriber;
     private scheduleFlush;
     private flushPending;

package/lib/node/accounts/grpcMultiUserAccountSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpcMultiUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcMultiUserAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,WAAW,EAEX,SAAS,EAET,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAW,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAE1E,qBAAa,8BAA8B;IAC1C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,gBAAgB,CAAC,CAA0C;IACnE,OAAO,KAAK,eAAe,GAO1B;IAED,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,SAAS,CAGb;IACJ,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAC,CAAgC;IACtD,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,sBAAsB,CAA4C;IAC1E,OAAO,CAAC,WAAW,CAAc;IACjC,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,OAAO,CAAC,mBAAmB,CAgBzB;gBAGD,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,SAAS,EACrB,eAAe,CAAC,EAAE,0BAA0B,CAAC,WAAW,CAAC;IAU7C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA0ChC,OAAO,CAAC,oBAAoB,EAAE,SAAS,GAAG,qBAAqB;IAoGtE,OAAO,CAAC,aAAa;YAOP,YAAY;CAmE1B"}
+{"version":3,"file":"grpcMultiUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcMultiUserAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,WAAW,EAEX,SAAS,EAET,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAW,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;;;;;GAMG;AACH,qBAAa,8BAA8B;IAC1C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,gBAAgB,CAAC,CAA0C;IACnE,OAAO,KAAK,eAAe,GAO1B;IAED,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,SAAS,CAGb;IACJ,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAC,CAAgC;IACtD,OAAO,CAAC,UAAU,CAAM;IACxB,yIAAyI;IACzI,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAU;IAC3D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,sBAAsB,CAA4C;IAC1E,OAAO,CAAC,WAAW,CAAc;IACjC,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,OAAO,CAAC,mBAAmB,CAgBzB;IAEF;;;;;OAKG;gBAEF,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,SAAS,EACrB,eAAe,CAAC,EAAE,0BAA0B,CAAC,WAAW,CAAC;IAU1D;;;;;;;OAOG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAgDvC;;;;;;;;OAQG;IACI,OAAO,CAAC,oBAAoB,EAAE,SAAS,GAAG,qBAAqB;IAoGtE,OAAO,CAAC,aAAa;YAOP,YAAY;CAmE1B"}

package/lib/node/accounts/grpcMultiUserAccountSubscriber.js

@@ -5,6 +5,13 @@ const types_1 = require("./types");
 const events_1 = require("events");
 const web3_js_1 = require("@solana/web3.js");
 const grpcMultiAccountSubscriber_1 = require("./grpcMultiAccountSubscriber");
+/**
+ * Multiplexes many `UserAccount` subscriptions onto a single `grpcMultiAccountSubscriber`,
+ * exposing a per-user `UserAccountSubscriber` facade via `forUser()` so callers (e.g. `User`
+ * instances) can interact with it as if each had its own subscription. New `forUser()` keys
+ * registered while already subscribed are debounced (`debounceMs`, 20ms) and flushed in a single
+ * batched `addAccounts` call rather than one gRPC round trip per user.
+ */
 class grpcMultiUserAccountSubscriber {
     get multiSubscriber() {
         if (!this._multiSubscriber) {
@@ -12,6 +19,12 @@ class grpcMultiUserAccountSubscriber {
         }
         return this._multiSubscriber;
     }
+    /**
+     * @param program Anchor program used for the per-user `fetch()` fallback.
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcMultiAccountSubscriber`.
+     * @param multiSubscriber Optional pre-constructed `grpcMultiAccountSubscriber` to reuse instead of creating a new one in `subscribe()`.
+     */
     constructor(program, grpcConfigs, resubOpts, multiSubscriber) {
         this.userData = new Map();
         this.listeners = new Map();
@@ -38,6 +51,14 @@ class grpcMultiUserAccountSubscriber {
         this.grpcConfigs = grpcConfigs;
         this.resubOpts = resubOpts;
     }
+    /**
+     * Creates the shared `grpcMultiAccountSubscriber` (if not injected at construction),
+     * subscribes every per-user facade already registered via `forUser()`, flushes any pending
+     * user keys into the underlying gRPC stream, and blocks until the multi-subscriber's account
+     * data map contains an entry for every registered user key (polling at `debounceMs` intervals),
+     * up to `SUBSCRIBE_DATA_TIMEOUT_MS`.
+     * @throws if any registered user key is still missing from the data map once the timeout elapses.
+     */
     async subscribe() {
         if (!this._multiSubscriber) {
             this._multiSubscriber =
@@ -53,23 +74,28 @@ class grpcMultiUserAccountSubscriber {
         const targetKeys = Array.from(this.listeners.keys());
         if (targetKeys.length === 0)
             return;
-        // Poll until all keys are present in dataMap
+        // Poll until all keys are present in dataMap, bounded by a deadline so a key that never
+        // arrives (e.g. dropped subscription) fails loudly instead of hanging forever.
         // Use debounceMs as the polling cadence to avoid introducing new magic numbers
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            const map = this.multiSubscriber.getAccountDataMap();
-            let allPresent = true;
-            for (const k of targetKeys) {
-                if (!map.has(k)) {
-                    allPresent = false;
-                    break;
-                }
+        const deadline = Date.now() + grpcMultiUserAccountSubscriber.SUBSCRIBE_DATA_TIMEOUT_MS;
+        let missingKeys = targetKeys.filter((k) => !this.multiSubscriber.getAccountDataMap().has(k));
+        while (missingKeys.length > 0) {
+            if (Date.now() >= deadline) {
+                throw new Error(`grpcMultiUserAccountSubscriber: timed out after ${grpcMultiUserAccountSubscriber.SUBSCRIBE_DATA_TIMEOUT_MS}ms waiting for account data for keys: ${missingKeys.join(', ')}`);
             }
-            if (allPresent)
-                break;
             await new Promise((resolve) => setTimeout(resolve, this.debounceMs));
+            missingKeys = targetKeys.filter((k) => !this.multiSubscriber.getAccountDataMap().has(k));
         }
     }
+    /**
+     * Returns a `UserAccountSubscriber` facade for `userAccountPublicKey`, creating one on first
+     * call (subsequent calls for the same pubkey return the same instance). The facade's
+     * `subscribe()`/`unsubscribe()` register/deregister interest in this shared multi-subscriber
+     * rather than opening their own gRPC stream; the underlying account is only actually removed
+     * from the shared stream once every facade sharing that key has unsubscribed. Its `fetch()`
+     * bypasses the shared stream and issues a direct one-off `program.account.user.fetch` call.
+     * @param userAccountPublicKey Address of the `UserAccount` to get (or create) a facade for.
+     */
     forUser(userAccountPublicKey) {
         if (this.userAccountSubscribers.has(userAccountPublicKey.toBase58())) {
             return this.userAccountSubscribers.get(userAccountPublicKey.toBase58());
@@ -208,3 +234,5 @@ class grpcMultiUserAccountSubscriber {
     }
 }
 exports.grpcMultiUserAccountSubscriber = grpcMultiUserAccountSubscriber;
+/** Maximum time to wait in `subscribe()` for every registered user key to appear in the multi-subscriber's data map before giving up. */
+grpcMultiUserAccountSubscriber.SUBSCRIBE_DATA_TIMEOUT_MS = 30000;

package/lib/node/accounts/grpcProgramAccountSubscriber.d.ts

@@ -4,6 +4,14 @@ import { ResubOpts, GrpcConfigs } from './types';
 import { Context, MemcmpFilter, PublicKey } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
 import { WebSocketProgramAccountSubscriber } from './webSocketProgramAccountSubscriber';
+/**
+ * `ProgramAccountSubscriber` that streams every account owned by the program (optionally
+ * filtered by `memcmp`) via a gRPC Geyser plugin instead of `connection.onProgramAccountChange`.
+ * Extends `WebSocketProgramAccountSubscriber` to reuse its per-account buffering/decode/resub-
+ * timer logic — only the transport (`subscribe`/`unsubscribe`) is replaced. Construct via the
+ * static `create` factory, not the constructor directly, since establishing the gRPC client is
+ * asynchronous.
+ */
 export declare class grpcProgramAccountSubscriber<T> extends WebSocketProgramAccountSubscriber<T> {
     private client;
     private _stream?;
@@ -11,10 +19,35 @@ export declare class grpcProgramAccountSubscriber<T> extends WebSocketProgramAcc
     private commitmentLevel;
     listenerId?: number;
     private constructor();
+    /**
+     * Creates a gRPC client and constructs a `grpcProgramAccountSubscriber`. Forces zstd
+     * compression and an adaptive HTTP/2 window on the channel (in addition to any caller-supplied
+     * `channelOptions`), since program-wide account streams can be high-volume. Does not itself
+     * start streaming — call `subscribe(onChange)` on the result.
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param subscriptionName Human-readable name for logging.
+     * @param accountDiscriminator Anchor account type name passed to `decodeBufferFn` for each update.
+     * @param program Anchor program whose accounts to stream (filtered to `program.programId` as owner).
+     * @param decodeBufferFn Decode function for each account's raw buffer.
+     * @param options `filters.memcmp` filters narrowing which program accounts are streamed; empty streams every account owned by the program.
+     * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+     */
     static create<U>(grpcConfigs: GrpcConfigs, subscriptionName: string, accountDiscriminator: string, program: VelocityProgram, decodeBufferFn: (accountName: string, ix: Buffer) => U, options?: {
         filters: MemcmpFilter[];
     }, resubOpts?: ResubOpts): Promise<grpcProgramAccountSubscriber<U>>;
+    /**
+     * Opens a gRPC subscribe stream filtered to accounts owned by `program.programId` (further
+     * narrowed by the `filters` passed to `create`). Idempotent: a no-op if already subscribed or
+     * mid-unsubscribe. Unlike `grpcAccountSubscriber`, does not perform an initial `fetch()` — the
+     * caller must fetch any pre-existing matching accounts separately if needed.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context`, and the raw buffer.
+     */
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
+    /**
+     * Writes an empty subscribe request to clear the stream's filter and cancels any pending
+     * resub timeout.
+     * @param onResub Internal flag set to `true` when called as part of an automatic resubscribe cycle, which preserves `resubOpts.resubTimeoutMs` instead of clearing it. Callers should omit this.
+     */
     unsubscribe(onResub?: boolean): Promise<void>;
 }
 //# sourceMappingURL=grpcProgramAccountSubscriber.d.ts.map

package/lib/node/accounts/grpcProgramAccountSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpcProgramAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcProgramAccountSubscriber.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AASxF,qBAAa,4BAA4B,CACxC,CAAC,CACA,SAAQ,iCAAiC,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAC,CAA2C;IAC3D,OAAO,KAAK,MAAM,GAOjB;IACD,OAAO,CAAC,eAAe,CAAkB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE3B,OAAO;WAwBa,MAAM,CAAC,CAAC,EAC3B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,CAAC,EACtD,OAAO,GAAE;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAEjC,EACD,SAAS,CAAC,EAAE,SAAS,GACnB,OAAO,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;IA2BrC,SAAS,CACd,QAAQ,EAAE,CACT,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,KACV,IAAI,GACP,OAAO,CAAC,IAAI,CAAC;IA+FH,WAAW,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAsCxD"}
+{"version":3,"file":"grpcProgramAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcProgramAccountSubscriber.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AASxF;;;;;;;GAOG;AACH,qBAAa,4BAA4B,CACxC,CAAC,CACA,SAAQ,iCAAiC,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAC,CAA2C;IAC3D,OAAO,KAAK,MAAM,GAOjB;IACD,OAAO,CAAC,eAAe,CAAkB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE3B,OAAO;IAwBP;;;;;;;;;;;;OAYG;WACiB,MAAM,CAAC,CAAC,EAC3B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,CAAC,EACtD,OAAO,GAAE;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAEjC,EACD,SAAS,CAAC,EAAE,SAAS,GACnB,OAAO,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;IA2B3C;;;;;;OAMG;IACG,SAAS,CACd,QAAQ,EAAE,CACT,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,KACV,IAAI,GACP,OAAO,CAAC,IAAI,CAAC;IA+FhB;;;;OAIG;IACU,WAAW,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAsCxD"}

package/lib/node/accounts/grpcProgramAccountSubscriber.js

@@ -28,6 +28,14 @@ const web3_js_1 = require("@solana/web3.js");
 const Buffer = __importStar(require("buffer"));
 const webSocketProgramAccountSubscriber_1 = require("./webSocketProgramAccountSubscriber");
 const grpc_1 = require("../isomorphic/grpc");
+/**
+ * `ProgramAccountSubscriber` that streams every account owned by the program (optionally
+ * filtered by `memcmp`) via a gRPC Geyser plugin instead of `connection.onProgramAccountChange`.
+ * Extends `WebSocketProgramAccountSubscriber` to reuse its per-account buffering/decode/resub-
+ * timer logic — only the transport (`subscribe`/`unsubscribe`) is replaced. Construct via the
+ * static `create` factory, not the constructor directly, since establishing the gRPC client is
+ * asynchronous.
+ */
 class grpcProgramAccountSubscriber extends webSocketProgramAccountSubscriber_1.WebSocketProgramAccountSubscriber {
     get stream() {
         if (!this._stream) {
@@ -42,6 +50,19 @@ class grpcProgramAccountSubscriber extends webSocketProgramAccountSubscriber_1.W
         this.client = client;
         this.commitmentLevel = commitmentLevel;
     }
+    /**
+     * Creates a gRPC client and constructs a `grpcProgramAccountSubscriber`. Forces zstd
+     * compression and an adaptive HTTP/2 window on the channel (in addition to any caller-supplied
+     * `channelOptions`), since program-wide account streams can be high-volume. Does not itself
+     * start streaming — call `subscribe(onChange)` on the result.
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param subscriptionName Human-readable name for logging.
+     * @param accountDiscriminator Anchor account type name passed to `decodeBufferFn` for each update.
+     * @param program Anchor program whose accounts to stream (filtered to `program.programId` as owner).
+     * @param decodeBufferFn Decode function for each account's raw buffer.
+     * @param options `filters.memcmp` filters narrowing which program accounts are streamed; empty streams every account owned by the program.
+     * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+     */
     static async create(grpcConfigs, subscriptionName, accountDiscriminator, program, decodeBufferFn, options = {
         filters: [],
     }, resubOpts) {
@@ -57,6 +78,13 @@ class grpcProgramAccountSubscriber extends webSocketProgramAccountSubscriber_1.W
         (_b = grpcConfigs.commitmentLevel) !== null && _b !== void 0 ? _b : grpc_1.CommitmentLevel.CONFIRMED;
         return new grpcProgramAccountSubscriber(client, commitmentLevel, subscriptionName, accountDiscriminator, program, decodeBufferFn, options, resubOpts);
     }
+    /**
+     * Opens a gRPC subscribe stream filtered to accounts owned by `program.programId` (further
+     * narrowed by the `filters` passed to `create`). Idempotent: a no-op if already subscribed or
+     * mid-unsubscribe. Unlike `grpcAccountSubscriber`, does not perform an initial `fetch()` — the
+     * caller must fetch any pre-existing matching accounts separately if needed.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context`, and the raw buffer.
+     */
     async subscribe(onChange) {
         if (this.listenerId != null || this.isUnsubscribing) {
             return;
@@ -142,6 +170,11 @@ class grpcProgramAccountSubscriber extends webSocketProgramAccountSubscriber_1.W
             throw reason;
         });
     }
+    /**
+     * Writes an empty subscribe request to clear the stream's filter and cancels any pending
+     * resub timeout.
+     * @param onResub Internal flag set to `true` when called as part of an automatic resubscribe cycle, which preserves `resubOpts.resubTimeoutMs` instead of clearing it. Callers should omit this.
+     */
     async unsubscribe(onResub = false) {
         if (!onResub && this.resubOpts) {
             this.resubOpts.resubTimeoutMs = undefined;

package/lib/node/accounts/grpcUserAccountSubscriber.d.ts

@@ -3,9 +3,24 @@ import { PublicKey } from '@solana/web3.js';
 import { UserAccount } from '../types';
 import { WebSocketUserAccountSubscriber } from './webSocketUserAccountSubscriber';
 import { VelocityProgram } from '../config';
+/**
+ * `UserAccountSubscriber` variant of `WebSocketUserAccountSubscriber` that tracks the
+ * `UserAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 export declare class grpcUserAccountSubscriber extends WebSocketUserAccountSubscriber {
     private grpcConfigs;
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program providing the connection and coder.
+     * @param userAccountPublicKey Address of the `UserAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+     */
     constructor(grpcConfigs: GrpcConfigs, program: VelocityProgram, userAccountPublicKey: PublicKey, resubOpts?: ResubOpts);
+    /**
+     * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
 }
 //# sourceMappingURL=grpcUserAccountSubscriber.d.ts.map

package/lib/node/accounts/grpcUserAccountSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpcUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcUserAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAElF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,qBAAa,yBAA0B,SAAQ,8BAA8B;IAC5E,OAAO,CAAC,WAAW,CAAc;gBAGhC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,oBAAoB,EAAE,SAAS,EAC/B,SAAS,CAAC,EAAE,SAAS;IAMhB,SAAS,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA2B5D"}
+{"version":3,"file":"grpcUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcUserAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAElF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,8BAA8B;IAC5E,OAAO,CAAC,WAAW,CAAc;IAEjC;;;;;OAKG;gBAEF,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,oBAAoB,EAAE,SAAS,EAC/B,SAAS,CAAC,EAAE,SAAS;IAMtB;;;;OAIG;IACG,SAAS,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA2B5D"}

package/lib/node/accounts/grpcUserAccountSubscriber.js

@@ -3,11 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.grpcUserAccountSubscriber = void 0;
 const webSocketUserAccountSubscriber_1 = require("./webSocketUserAccountSubscriber");
 const grpcAccountSubscriber_1 = require("./grpcAccountSubscriber");
+/**
+ * `UserAccountSubscriber` variant of `WebSocketUserAccountSubscriber` that tracks the
+ * `UserAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 class grpcUserAccountSubscriber extends webSocketUserAccountSubscriber_1.WebSocketUserAccountSubscriber {
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program providing the connection and coder.
+     * @param userAccountPublicKey Address of the `UserAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+     */
     constructor(grpcConfigs, program, userAccountPublicKey, resubOpts) {
         super(program, userAccountPublicKey, resubOpts);
         this.grpcConfigs = grpcConfigs;
     }
+    /**
+     * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     async subscribe(userAccount) {
         if (this.isSubscribed) {
             return true;

package/lib/node/accounts/grpcUserStatsAccountSubscriber.d.ts

@@ -3,9 +3,24 @@ import { PublicKey } from '@solana/web3.js';
 import { UserStatsAccount } from '../types';
 import { WebSocketUserStatsAccountSubscriber } from './webSocketUserStatsAccountSubsriber';
 import { VelocityProgram } from '../config';
+/**
+ * `UserStatsAccountSubscriber` variant of `WebSocketUserStatsAccountSubscriber` that tracks the
+ * `UserStatsAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 export declare class grpcUserStatsAccountSubscriber extends WebSocketUserStatsAccountSubscriber {
     private grpcConfigs;
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program providing the connection and coder.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+     */
     constructor(grpcConfigs: GrpcConfigs, program: VelocityProgram, userStatsAccountPublicKey: PublicKey, resubOpts?: ResubOpts);
+    /**
+     * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
 }
 //# sourceMappingURL=grpcUserStatsAccountSubscriber.d.ts.map

package/lib/node/accounts/grpcUserStatsAccountSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpcUserStatsAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcUserStatsAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,mCAAmC,EAAE,MAAM,sCAAsC,CAAC;AAE3F,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,qBAAa,8BAA+B,SAAQ,mCAAmC;IACtF,OAAO,CAAC,WAAW,CAAc;gBAGhC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,yBAAyB,EAAE,SAAS,EACpC,SAAS,CAAC,EAAE,SAAS;IAMhB,SAAS,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CA6BtE"}
+{"version":3,"file":"grpcUserStatsAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcUserStatsAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,mCAAmC,EAAE,MAAM,sCAAsC,CAAC;AAE3F,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,qBAAa,8BAA+B,SAAQ,mCAAmC;IACtF,OAAO,CAAC,WAAW,CAAc;IAEjC;;;;;OAKG;gBAEF,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,yBAAyB,EAAE,SAAS,EACpC,SAAS,CAAC,EAAE,SAAS;IAMtB;;;;OAIG;IACG,SAAS,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CA6BtE"}

package/lib/node/accounts/grpcUserStatsAccountSubscriber.js

@@ -3,11 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.grpcUserStatsAccountSubscriber = void 0;
 const webSocketUserStatsAccountSubsriber_1 = require("./webSocketUserStatsAccountSubsriber");
 const grpcAccountSubscriber_1 = require("./grpcAccountSubscriber");
+/**
+ * `UserStatsAccountSubscriber` variant of `WebSocketUserStatsAccountSubscriber` that tracks the
+ * `UserStatsAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 class grpcUserStatsAccountSubscriber extends webSocketUserStatsAccountSubsriber_1.WebSocketUserStatsAccountSubscriber {
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program providing the connection and coder.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+     */
     constructor(grpcConfigs, program, userStatsAccountPublicKey, resubOpts) {
         super(program, userStatsAccountPublicKey, resubOpts);
         this.grpcConfigs = grpcConfigs;
     }
+    /**
+     * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     async subscribe(userStatsAccount) {
         if (this.isSubscribed) {
             return true;