@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/auctionSubscriber/auctionSubscriber.d.ts

@@ -2,13 +2,28 @@
 import { AuctionSubscriberConfig, AuctionSubscriberEvents } from './types';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
+/**
+ * AuctionSubscriber — websocket program-account subscription scoped to
+ * `User` accounts that currently have at least one order in its auction
+ * window (`getUserWithAuctionFilter`). Used by keepers/fillers to react to
+ * auction-eligible orders (JIT-fillable or approaching the end of a Dutch
+ * auction) without scanning every user account.
+ */
 export declare class AuctionSubscriber {
     private velocityClient;
     private opts;
     private resubOpts?;
     eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
     private subscriber?;
+    /**
+     * @param velocityClient Client whose `program`/`connection` back the subscription; also supplies default `opts` if `opts` is omitted.
+     * @param opts Confirm options (commitment) for the subscription; defaults to `velocityClient.opts`.
+     * @param resubTimeoutMs Max time with no update before resubscribing.
+     * @param logResubMessages Whether to log resubscribe attempts.
+     */
     constructor({ velocityClient, opts, resubTimeoutMs, logResubMessages, }: AuctionSubscriberConfig);
+    /** Establishes the filtered program-account subscription (idempotent — reuses the existing subscriber if already created) and emits `onAccountUpdate` for each matching account update. */
     subscribe(): Promise<void>;
+    /** Tears down the subscription. No-op if never subscribed. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/auctionSubscriber/auctionSubscriber.js

@@ -4,7 +4,20 @@ exports.AuctionSubscriber = void 0;
 const memcmp_1 = require("../memcmp");
 const events_1 = require("events");
 const webSocketProgramAccountSubscriber_1 = require("../accounts/webSocketProgramAccountSubscriber");
+/**
+ * AuctionSubscriber — websocket program-account subscription scoped to
+ * `User` accounts that currently have at least one order in its auction
+ * window (`getUserWithAuctionFilter`). Used by keepers/fillers to react to
+ * auction-eligible orders (JIT-fillable or approaching the end of a Dutch
+ * auction) without scanning every user account.
+ */
 class AuctionSubscriber {
+    /**
+     * @param velocityClient Client whose `program`/`connection` back the subscription; also supplies default `opts` if `opts` is omitted.
+     * @param opts Confirm options (commitment) for the subscription; defaults to `velocityClient.opts`.
+     * @param resubTimeoutMs Max time with no update before resubscribing.
+     * @param logResubMessages Whether to log resubscribe attempts.
+     */
     constructor({ velocityClient, opts, resubTimeoutMs, logResubMessages, }) {
         // Type-system guarantees at least one of the two is supplied.
         this.velocityClient = velocityClient;
@@ -12,6 +25,7 @@ class AuctionSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.resubOpts = { resubTimeoutMs, logResubMessages };
     }
+    /** Establishes the filtered program-account subscription (idempotent — reuses the existing subscriber if already created) and emits `onAccountUpdate` for each matching account update. */
     async subscribe() {
         let subscriber = this.subscriber;
         if (!subscriber) {
@@ -25,6 +39,7 @@ class AuctionSubscriber {
             this.eventEmitter.emit('onAccountUpdate', data, accountId, context.slot);
         });
     }
+    /** Tears down the subscription. No-op if never subscribed. */
     async unsubscribe() {
         if (!this.subscriber) {
             return;

package/lib/browser/auctionSubscriber/auctionSubscriberGrpc.d.ts

@@ -2,6 +2,12 @@
 import { AuctionSubscriberConfig, AuctionSubscriberEvents } from './types';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
+/**
+ * Same as `AuctionSubscriber` (auction-eligible `User` accounts via
+ * `getUserWithAuctionFilter`) but sourced from a gRPC/Geyser stream
+ * (`grpcProgramAccountSubscriber`) instead of a websocket program-account
+ * subscription. Requires `grpcConfigs`.
+ */
 export declare class AuctionSubscriberGrpc {
     private velocityClient;
     private opts;
@@ -9,7 +15,20 @@ export declare class AuctionSubscriberGrpc {
     private grpcConfigs?;
     eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
     private subscriber?;
+    /**
+     * @param velocityClient Client whose `program` backs the subscription; also supplies default `opts` if `opts` is omitted.
+     * @param opts Confirm options (commitment) for the subscription; defaults to `velocityClient.opts`.
+     * @param grpcConfigs gRPC/Geyser endpoint config; required to call `subscribe()`.
+     * @param resubTimeoutMs Max time with no update before resubscribing.
+     * @param logResubMessages Whether to log resubscribe attempts.
+     */
     constructor({ velocityClient, opts, grpcConfigs, resubTimeoutMs, logResubMessages, }: AuctionSubscriberConfig);
+    /**
+     * Establishes the filtered gRPC subscription (idempotent) and emits
+     * `onAccountUpdate` for each matching account update.
+     * @throws If `grpcConfigs` was not provided at construction.
+     */
     subscribe(): Promise<void>;
+    /** Tears down the subscription. No-op if never subscribed. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/auctionSubscriber/auctionSubscriberGrpc.js

@@ -4,7 +4,20 @@ exports.AuctionSubscriberGrpc = void 0;
 const memcmp_1 = require("../memcmp");
 const events_1 = require("events");
 const grpcProgramAccountSubscriber_1 = require("../accounts/grpcProgramAccountSubscriber");
+/**
+ * Same as `AuctionSubscriber` (auction-eligible `User` accounts via
+ * `getUserWithAuctionFilter`) but sourced from a gRPC/Geyser stream
+ * (`grpcProgramAccountSubscriber`) instead of a websocket program-account
+ * subscription. Requires `grpcConfigs`.
+ */
 class AuctionSubscriberGrpc {
+    /**
+     * @param velocityClient Client whose `program` backs the subscription; also supplies default `opts` if `opts` is omitted.
+     * @param opts Confirm options (commitment) for the subscription; defaults to `velocityClient.opts`.
+     * @param grpcConfigs gRPC/Geyser endpoint config; required to call `subscribe()`.
+     * @param resubTimeoutMs Max time with no update before resubscribing.
+     * @param logResubMessages Whether to log resubscribe attempts.
+     */
     constructor({ velocityClient, opts, grpcConfigs, resubTimeoutMs, logResubMessages, }) {
         // Type-system guarantees at least one of the two is supplied.
         this.velocityClient = velocityClient;
@@ -13,6 +26,11 @@ class AuctionSubscriberGrpc {
         this.resubOpts = { resubTimeoutMs, logResubMessages };
         this.grpcConfigs = grpcConfigs;
     }
+    /**
+     * Establishes the filtered gRPC subscription (idempotent) and emits
+     * `onAccountUpdate` for each matching account update.
+     * @throws If `grpcConfigs` was not provided at construction.
+     */
     async subscribe() {
         let subscriber = this.subscriber;
         if (!subscriber) {
@@ -28,6 +46,7 @@ class AuctionSubscriberGrpc {
             this.eventEmitter.emit('onAccountUpdate', data, accountId, context.slot);
         });
     }
+    /** Tears down the subscription. No-op if never subscribed. */
     async unsubscribe() {
         if (!this.subscriber) {
             return;

package/lib/browser/auctionSubscriber/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Auction-eligible order tracking — filtered `User`-account subscriptions
+ * (`AuctionSubscriber` over websocket, `AuctionSubscriberGrpc` over gRPC/Geyser)
+ * scoped to accounts with at least one order currently in its auction window,
+ * for keepers/fillers reacting to JIT-fillable or expiring-auction orders.
+ */
 export * from './types';
 export * from './auctionSubscriber';
 export * from './auctionSubscriberGrpc';

package/lib/browser/auctionSubscriber/index.js

@@ -14,6 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Auction-eligible order tracking — filtered `User`-account subscriptions
+ * (`AuctionSubscriber` over websocket, `AuctionSubscriberGrpc` over gRPC/Geyser)
+ * scoped to accounts with at least one order currently in its auction window,
+ * for keepers/fillers reacting to JIT-fillable or expiring-auction orders.
+ */
 __exportStar(require("./types"), exports);
 __exportStar(require("./auctionSubscriber"), exports);
 __exportStar(require("./auctionSubscriberGrpc"), exports);

package/lib/browser/auctionSubscriber/types.d.ts

@@ -3,15 +3,22 @@ import { VelocityClient } from '../velocityClient';
 import { UserAccount } from '../types';
 import { ConfirmOptions, PublicKey } from '@solana/web3.js';
 type AuctionSubscriberConfigBase = {
+    /** Confirm options (notably `commitment`) for the underlying program-account subscription; defaults to `velocityClient.opts`. */
     opts?: ConfirmOptions;
+    /** Max time with no update before the subscription resubscribes. */
     resubTimeoutMs?: number;
+    /** Whether to log resubscribe attempts. */
     logResubMessages?: boolean;
+    /** gRPC/Geyser endpoint config; only consumed by `AuctionSubscriberGrpc`, ignored by `AuctionSubscriber`. */
     grpcConfigs?: GrpcConfigs;
 };
+/** Configuration for `AuctionSubscriber`/`AuctionSubscriberGrpc`. */
 export type AuctionSubscriberConfig = AuctionSubscriberConfigBase & {
     velocityClient: VelocityClient;
 };
+/** Events emitted on `AuctionSubscriber`/`AuctionSubscriberGrpc`'s `eventEmitter`. */
 export interface AuctionSubscriberEvents {
+    /** Fired whenever a `User` account with at least one order currently in its auction window is created or updated. */
     onAccountUpdate: (account: UserAccount, pubkey: PublicKey, slot: number) => void;
 }
 export {};

package/lib/browser/blockhashSubscriber/BlockhashSubscriber.d.ts

@@ -1,5 +1,13 @@
 import { BlockhashWithExpiryBlockHeight, Context } from '@solana/web3.js';
 import { BlockhashSubscriberConfig } from './types';
+/**
+ * BlockhashSubscriber — polls `getLatestBlockhashAndContext`/`getBlockHeight`
+ * on a fixed interval and caches a short history of recent blockhashes, so
+ * callers can grab a recent blockhash for transaction building without an
+ * RPC round-trip per transaction. Nothing is populated until `subscribe()`
+ * (or a manual `updateBlockhash()`) has completed at least once — all getters
+ * return `undefined`/empty before then.
+ */
 export declare class BlockhashSubscriber {
     private connection;
     private isSubscribed;
@@ -9,9 +17,23 @@ export declare class BlockhashSubscriber {
     private updateBlockhashIntervalId;
     private commitment;
     private updateIntervalMs;
+    /**
+     * @param config Either `connection` or `rpcUrl` must be provided (a `Connection` is created from `rpcUrl` if `connection` is omitted). `commitment` defaults to `'confirmed'`; `updateIntervalMs` defaults to 1000ms.
+     * @throws If neither `config.connection` nor `config.rpcUrl` is provided.
+     */
     constructor(config: BlockhashSubscriberConfig);
+    /** @returns The number of blockhashes currently cached (not-yet-expired, per `pruneBlockhashes`). */
     getBlockhashCacheSize(): number;
+    /**
+     * @returns The block height as of the most recent successful poll, or
+     * `undefined` if `subscribe()`/`updateBlockhash()` has not yet completed
+     * successfully at least once (including if every poll so far has errored).
+     * This value is a `getBlockHeight` snapshot taken alongside the latest
+     * blockhash fetch — it is not guaranteed to be perfectly in sync with the
+     * blockhash slot, only "recent as of the last poll".
+     */
     getLatestBlockHeight(): number | undefined;
+    /** @returns The RPC `Context` (including `slot`) captured with the most recent successful blockhash poll, or `undefined` before the first successful poll. */
     getLatestBlockHeightContext(): Context | undefined;
     /**
      * Returns the latest cached blockhash, based on an offset from the latest obtained
@@ -20,8 +42,19 @@ export declare class BlockhashSubscriber {
      * @returns Cached blockhash at the given offset, or undefined
      */
     getLatestBlockhash(offset?: number, offsetType?: 'index' | 'seconds'): BlockhashWithExpiryBlockHeight | undefined;
+    /** Drops cached blockhashes whose `lastValidBlockHeight` is at or below `latestBlockHeight` (i.e. already expired for transaction signing). Called automatically after every `updateBlockhash`. No-ops if `latestBlockHeight` hasn't been set yet. */
     pruneBlockhashes(): void;
+    /**
+     * Fetches the latest blockhash and block height in parallel and appends
+     * the blockhash to the cache (skipped if it's identical to the
+     * most-recently-cached one), then prunes expired entries. Errors (e.g. RPC
+     * failure) are caught and logged, not thrown — on error, `latestBlockHeight`
+     * is left at its previous value, but `pruneBlockhashes()` still runs in a
+     * `finally` block and may evict entries that expired in the meantime.
+     */
     updateBlockhash(): Promise<void>;
+    /** Performs an immediate `updateBlockhash()` and then starts polling on `updateIntervalMs`. Idempotent — a second call while already subscribed is a no-op. */
     subscribe(): Promise<void>;
+    /** Stops the polling interval. Cached blockhashes and `latestBlockHeight` are left in place (not cleared). */
     unsubscribe(): void;
 }

package/lib/browser/blockhashSubscriber/BlockhashSubscriber.js

@@ -2,7 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlockhashSubscriber = void 0;
 const web3_js_1 = require("@solana/web3.js");
+/**
+ * BlockhashSubscriber — polls `getLatestBlockhashAndContext`/`getBlockHeight`
+ * on a fixed interval and caches a short history of recent blockhashes, so
+ * callers can grab a recent blockhash for transaction building without an
+ * RPC round-trip per transaction. Nothing is populated until `subscribe()`
+ * (or a manual `updateBlockhash()`) has completed at least once — all getters
+ * return `undefined`/empty before then.
+ */
 class BlockhashSubscriber {
+    /**
+     * @param config Either `connection` or `rpcUrl` must be provided (a `Connection` is created from `rpcUrl` if `connection` is omitted). `commitment` defaults to `'confirmed'`; `updateIntervalMs` defaults to 1000ms.
+     * @throws If neither `config.connection` nor `config.rpcUrl` is provided.
+     */
     constructor(config) {
         var _a, _b;
         this.isSubscribed = false;
@@ -14,12 +26,22 @@ class BlockhashSubscriber {
         this.commitment = (_a = config.commitment) !== null && _a !== void 0 ? _a : 'confirmed';
         this.updateIntervalMs = (_b = config.updateIntervalMs) !== null && _b !== void 0 ? _b : 1000;
     }
+    /** @returns The number of blockhashes currently cached (not-yet-expired, per `pruneBlockhashes`). */
     getBlockhashCacheSize() {
         return this.blockhashes.length;
     }
+    /**
+     * @returns The block height as of the most recent successful poll, or
+     * `undefined` if `subscribe()`/`updateBlockhash()` has not yet completed
+     * successfully at least once (including if every poll so far has errored).
+     * This value is a `getBlockHeight` snapshot taken alongside the latest
+     * blockhash fetch — it is not guaranteed to be perfectly in sync with the
+     * blockhash slot, only "recent as of the last poll".
+     */
     getLatestBlockHeight() {
         return this.latestBlockHeight;
     }
+    /** @returns The RPC `Context` (including `slot`) captured with the most recent successful blockhash poll, or `undefined` before the first successful poll. */
     getLatestBlockHeightContext() {
         return this.latestBlockHeightContext;
     }
@@ -39,12 +61,21 @@ class BlockhashSubscriber {
         const clampedOffset = Math.max(0, Math.min(this.blockhashes.length - 1, elementOffset));
         return this.blockhashes[this.blockhashes.length - 1 - clampedOffset];
     }
+    /** Drops cached blockhashes whose `lastValidBlockHeight` is at or below `latestBlockHeight` (i.e. already expired for transaction signing). Called automatically after every `updateBlockhash`. No-ops if `latestBlockHeight` hasn't been set yet. */
     pruneBlockhashes() {
         if (this.latestBlockHeight !== undefined) {
             const latestBlockHeight = this.latestBlockHeight;
             this.blockhashes = this.blockhashes.filter((blockhash) => blockhash.lastValidBlockHeight > latestBlockHeight);
         }
     }
+    /**
+     * Fetches the latest blockhash and block height in parallel and appends
+     * the blockhash to the cache (skipped if it's identical to the
+     * most-recently-cached one), then prunes expired entries. Errors (e.g. RPC
+     * failure) are caught and logged, not thrown — on error, `latestBlockHeight`
+     * is left at its previous value, but `pruneBlockhashes()` still runs in a
+     * `finally` block and may evict entries that expired in the meantime.
+     */
     async updateBlockhash() {
         try {
             const [resp, lastConfirmedBlockHeight] = await Promise.all([
@@ -71,6 +102,7 @@ class BlockhashSubscriber {
             this.pruneBlockhashes();
         }
     }
+    /** Performs an immediate `updateBlockhash()` and then starts polling on `updateIntervalMs`. Idempotent — a second call while already subscribed is a no-op. */
     async subscribe() {
         if (this.isSubscribed) {
             return;
@@ -79,6 +111,7 @@ class BlockhashSubscriber {
         await this.updateBlockhash();
         this.updateBlockhashIntervalId = setInterval(this.updateBlockhash.bind(this), this.updateIntervalMs);
     }
+    /** Stops the polling interval. Cached blockhashes and `latestBlockHeight` are left in place (not cleared). */
     unsubscribe() {
         if (this.updateBlockhashIntervalId) {
             clearInterval(this.updateBlockhashIntervalId);

package/lib/browser/blockhashSubscriber/index.d.ts

@@ -1 +1,6 @@
+/**
+ * `BlockhashSubscriber` — polls and caches recent blockhashes/block heights so
+ * transaction builders can grab a recent blockhash without an RPC round-trip
+ * per transaction.
+ */
 export * from './BlockhashSubscriber';

package/lib/browser/blockhashSubscriber/index.js

@@ -14,4 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `BlockhashSubscriber` — polls and caches recent blockhashes/block heights so
+ * transaction builders can grab a recent blockhash without an RPC round-trip
+ * per transaction.
+ */
 __exportStar(require("./BlockhashSubscriber"), exports);

package/lib/browser/blockhashSubscriber/types.d.ts

@@ -1,7 +1,12 @@
 import { Commitment, Connection } from '@solana/web3.js';
+/** Configuration for `BlockhashSubscriber`. */
 export type BlockhashSubscriberConfig = {
+    /** RPC URL to poll block hashes from; a `Connection` is constructed from it if `connection` is not provided. One of `rpcUrl`/`connection` must be supplied. */
     rpcUrl?: string;
+    /** Existing `Connection` to poll block hashes on, taking precedence over `rpcUrl` if both are given. One of `rpcUrl`/`connection` must be supplied. */
     connection?: Connection;
+    /** Commitment level for both the blockhash and block-height polls; defaults to `'confirmed'`. */
     commitment?: Commitment;
+    /** Poll interval in milliseconds; defaults to `1000`. */
     updateIntervalMs?: number;
 };

package/lib/browser/clock/clockSubscriber.d.ts

@@ -6,9 +6,20 @@ type ClockSubscriberConfig = {
     commitment: Commitment;
     resubTimeoutMs?: number;
 };
+/** Events emitted on `ClockSubscriber.eventEmitter`. */
 export interface ClockSubscriberEvent {
+    /** Fired with the new on-chain unix timestamp (seconds) whenever a strictly-newer `Clock` sysvar update is observed. */
     clockUpdate: (ts: number) => void;
 }
+/**
+ * ClockSubscriber — tracks the on-chain unix timestamp by subscribing to the
+ * `Clock` sysvar via `connection.onAccountChange`, with an optional
+ * stall-detection resubscribe. Useful for reading "on-chain now" without a
+ * per-call RPC round-trip (e.g. for evaluating time-based order/auction
+ * conditions the same way the program would). Nothing is populated until
+ * `subscribe()` completes its first update — `currentTs`/`getUnixTs()` return
+ * `undefined` until then.
+ */
 export declare class ClockSubscriber {
     private connection;
     private _latestSlot?;
@@ -16,16 +27,29 @@ export declare class ClockSubscriber {
     private subscriptionId?;
     commitment: Commitment;
     eventEmitter: StrictEventEmitter<EventEmitter, ClockSubscriberEvent>;
+    /** Slot of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
     get latestSlot(): number | undefined;
+    /** On-chain unix timestamp (seconds) as of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
     get currentTs(): number | undefined;
     private timeoutId?;
     private resubTimeoutMs?;
     private isUnsubscribing;
     private receivingData;
+    /**
+     * @param connection RPC connection to subscribe on.
+     * @param config.commitment Commitment for the account-change subscription; defaults to `'confirmed'`.
+     * @param config.resubTimeoutMs If set to a positive value, resubscribe when no update arrives for this many ms; `0` (or unset) disables the resubscribe watchdog. Positive values below 1000ms log a warning but are still honored.
+     */
     constructor(connection: Connection, config?: ClockSubscriberConfig);
+    /** Subscribes to `Clock` sysvar account changes. Unlike `SlotSubscriber`/`SlothashSubscriber`, does not perform an initial RPC fetch — `currentTs`/`latestSlot` stay `undefined` until the first account-change notification arrives. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
     private setTimeout;
+    /** @returns The on-chain unix timestamp (seconds) as of the last update, or `undefined` if `subscribe()` hasn't received an update yet. Equivalent to the `currentTs` getter. */
     getUnixTs(): number | undefined;
+    /**
+     * Removes the `onAccountChange` listener and cancels the resub timeout.
+     * @param onResub Internal flag used when unsubscribing as part of an automatic resubscribe cycle; when `false`, also permanently disables future auto-resubscribe by clearing `resubTimeoutMs`.
+     */
     unsubscribe(onResub?: boolean): Promise<void>;
 }
 export {};

package/lib/browser/clock/clockSubscriber.js

@@ -4,13 +4,29 @@ exports.ClockSubscriber = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const events_1 = require("events");
 const anchor_1 = require("../isomorphic/anchor");
+/**
+ * ClockSubscriber — tracks the on-chain unix timestamp by subscribing to the
+ * `Clock` sysvar via `connection.onAccountChange`, with an optional
+ * stall-detection resubscribe. Useful for reading "on-chain now" without a
+ * per-call RPC round-trip (e.g. for evaluating time-based order/auction
+ * conditions the same way the program would). Nothing is populated until
+ * `subscribe()` completes its first update — `currentTs`/`getUnixTs()` return
+ * `undefined` until then.
+ */
 class ClockSubscriber {
+    /** Slot of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
     get latestSlot() {
         return this._latestSlot;
     }
+    /** On-chain unix timestamp (seconds) as of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
     get currentTs() {
         return this._currentTs;
     }
+    /**
+     * @param connection RPC connection to subscribe on.
+     * @param config.commitment Commitment for the account-change subscription; defaults to `'confirmed'`.
+     * @param config.resubTimeoutMs If set to a positive value, resubscribe when no update arrives for this many ms; `0` (or unset) disables the resubscribe watchdog. Positive values below 1000ms log a warning but are still honored.
+     */
     constructor(connection, config) {
         this.connection = connection;
         this.isUnsubscribing = false;
@@ -22,6 +38,7 @@ class ClockSubscriber {
             console.log('resubTimeoutMs should be at least 1000ms to avoid spamming resub');
         }
     }
+    /** Subscribes to `Clock` sysvar account changes. Unlike `SlotSubscriber`/`SlothashSubscriber`, does not perform an initial RPC fetch — `currentTs`/`latestSlot` stay `undefined` until the first account-change notification arrives. Idempotent while already subscribed. */
     async subscribe() {
         if (this.subscriptionId != null) {
             return;
@@ -58,9 +75,14 @@ class ClockSubscriber {
             }
         }, this.resubTimeoutMs);
     }
+    /** @returns The on-chain unix timestamp (seconds) as of the last update, or `undefined` if `subscribe()` hasn't received an update yet. Equivalent to the `currentTs` getter. */
     getUnixTs() {
         return this.currentTs;
     }
+    /**
+     * Removes the `onAccountChange` listener and cancels the resub timeout.
+     * @param onResub Internal flag used when unsubscribing as part of an automatic resubscribe cycle; when `false`, also permanently disables future auto-resubscribe by clearing `resubTimeoutMs`.
+     */
     async unsubscribe(onResub = false) {
         if (!onResub) {
             this.resubTimeoutMs = undefined;

package/lib/browser/config.d.ts

@@ -5,53 +5,107 @@ import { SpotMarketConfig } from './constants/spotMarkets';
 import { OracleInfo } from './oracles/types';
 import { Program } from './isomorphic/anchor';
 import { Velocity } from './idl/velocity';
+/** The Anchor `Program` client type for the velocity IDL, parameterized over the generated `Velocity` type. */
 export type VelocityProgram = Program<Velocity>;
+/** Supported deployment environments. */
 export type VelocityEnv = 'devnet' | 'mainnet-beta';
 /** Widened env type accepted by `initialize()`; `'master'` is a legacy alias for `'devnet'`. */
 export type LegacyVelocityEnv = VelocityEnv | 'master';
+/** Per-environment addresses, program ids, and default market lists returned by `getConfig()`/`initialize()`. */
 export interface VelocityConfig {
     ENV: VelocityEnv;
+    /** Legacy Pyth oracle mapping account address for this environment (push-oracle discovery; not used by pull/Lazer sources). */
     PYTH_ORACLE_MAPPING_ADDRESS: string;
+    /** Deployed velocity program id for this environment, base58. */
     VELOCITY_PROGRAM_ID: string;
+    /** Deployed jit-proxy program id, base58, if jit-proxy is available in this environment. */
     JIT_PROXY_PROGRAM_ID?: string;
+    /** Velocity's oracle-receiver program id (verifies/receives pushed oracle updates), base58. */
     VELOCITY_ORACLE_RECEIVER_ID: string;
+    /** Mint address of the protocol's quote asset (e.g. USDC) for this environment, base58. */
     QUOTE_MINT_ADDRESS: string;
+    /** Mint address of the legacy v2-alpha ticket token for this environment, base58. */
     V2_ALPHA_TICKET_MINT_ADDRESS: string;
+    /** Default perp market configs to subscribe to when the caller doesn't supply an explicit list. */
     PERP_MARKETS: PerpMarketConfig[];
+    /** Default spot market configs to subscribe to when the caller doesn't supply an explicit list. */
     SPOT_MARKETS: SpotMarketConfig[];
     /** @deprecated use MARKET_LOOKUP_TABLES */
     MARKET_LOOKUP_TABLE: string;
+    /** Address lookup table accounts (base58) used to fit market/oracle accounts into versioned transactions. */
     MARKET_LOOKUP_TABLES: string[];
+    /** Deployed Switchboard On-Demand program id for this environment. */
     SB_ON_DEMAND_PID: PublicKey;
 }
+/** Mainnet-beta velocity program id, base58. */
 export declare const VELOCITY_PROGRAM_ID = "vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P";
+/** Devnet velocity program id, base58. */
 export declare const VELOCITY_DEVNET_PROGRAM_ID = "vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P";
+/** Velocity's oracle-receiver program id, base58 (same across devnet and mainnet-beta). */
 export declare const VELOCITY_ORACLE_RECEIVER_ID = "G6EoTTTgpkNBtVXo96EQp2m6uwwVh2Kt6YidjkmQqoha";
+/** Pyth Lazer program id, base58. */
 export declare const PYTH_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
+/** Switchboard On-Demand program id on devnet. */
 export declare const SB_ON_DEMAND_DEVNET_PID: PublicKey;
+/** Switchboard On-Demand program id on mainnet-beta. */
 export declare const SB_ON_DEMAND_MAINNET_PID: PublicKey;
+/** Pyth Lazer storage account holding feed metadata, shared across environments. */
 export declare const PYTH_LAZER_STORAGE_ACCOUNT_KEY: PublicKey;
+/** Default `ConfirmOptions` (both preflight and confirmation at `'confirmed'` commitment) used across the SDK's tx senders unless overridden. */
 export declare const DEFAULT_CONFIRMATION_OPTS: ConfirmOptions;
+/** Built-in `VelocityConfig` presets for each supported environment. */
 export declare const configs: {
     [key in VelocityEnv]: VelocityConfig;
 };
+/**
+ * Returns the SDK's currently active `VelocityConfig` (the `devnet` preset by default, or
+ * whatever was last set via `initialize()`).
+ * @returns The active config.
+ */
 export declare const getConfig: () => VelocityConfig;
 /**
- * Allows customization of the SDK's environment and endpoints. You can pass individual settings to override the settings with your own presets.
+ * Sets the SDK's active environment/config, read thereafter via `getConfig()`. This mutates
+ * process-wide module state — call it once at startup before constructing clients, not
+ * concurrently with multiple environments in the same process.
  *
- * Defaults to master environment if you don't use this function.
- * @param props
- * @returns
+ * Defaults to the `devnet` preset if you never call this function.
+ * @param props.env - Environment to activate; `'master'` is accepted as a legacy alias for `'devnet'`.
+ * @param props.overrideEnv - Partial fields to overlay on top of the selected preset (e.g. a custom `VELOCITY_PROGRAM_ID`).
+ * @returns The resulting active `VelocityConfig` (preset merged with `overrideEnv`).
  */
 export declare const initialize: (props: {
     env: LegacyVelocityEnv;
     overrideEnv?: Partial<VelocityConfig>;
 }) => VelocityConfig;
+/**
+ * Builds the market-index and oracle-subscription lists a `VelocityClient` needs to subscribe to,
+ * from static market configs (no RPC calls) — the fast, offline alternative to
+ * `findAllMarketAndOracles`. Oracles are de-duplicated by `getOracleId` (pubkey + source), so a
+ * pubkey shared across multiple markets under the same source only appears once.
+ * @param env - Environment whose built-in market lists (`PerpMarkets[env]`/`SpotMarkets[env]`) are
+ * used as the fallback when `perpMarkets`/`spotMarkets` aren't supplied.
+ * @param perpMarkets - Explicit perp market configs to use instead of the environment default; if
+ * omitted or empty, falls back to `PerpMarkets[env]`.
+ * @param spotMarkets - Explicit spot market configs to use instead of the environment default; if
+ * omitted or empty, falls back to `SpotMarkets[env]`.
+ * @returns `perpMarketIndexes`/`spotMarketIndexes` for every market considered, and the
+ * de-duplicated `oracleInfos` needed to subscribe to their oracles.
+ */
 export declare function getMarketsAndOraclesForSubscription(env: VelocityEnv, perpMarkets?: PerpMarketConfig[], spotMarkets?: SpotMarketConfig[]): {
     perpMarketIndexes: number[];
     spotMarketIndexes: number[];
     oracleInfos: OracleInfo[];
 };
+/**
+ * Discovers every perp/spot market currently deployed under `program`'s program id via
+ * `getProgramAccounts` (`perpMarket.all()`/`spotMarket.all()`), rather than relying on a static
+ * config list — use this to pick up markets added after the SDK's bundled configs were published,
+ * or when running against a custom/unlisted deployment. Oracles are de-duplicated by `getOracleId`
+ * (pubkey + source).
+ * @param program - Anchor program client used to fetch all `PerpMarket`/`SpotMarket` accounts.
+ * @returns Market indexes and full decoded accounts for every discovered perp/spot market, plus
+ * the de-duplicated `oracleInfos` needed to subscribe to their oracles.
+ */
 export declare function findAllMarketAndOracles(program: VelocityProgram): Promise<{
     perpMarketIndexes: number[];
     perpMarketAccounts: PerpMarketAccount[];