@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/auctionSubscriber/auctionSubscriber.ts

@@ -8,6 +8,13 @@ import { ConfirmOptions, Context, PublicKey } from '@solana/web3.js';
 import { WebSocketProgramAccountSubscriber } from '../accounts/webSocketProgramAccountSubscriber';
 import { ResubOpts } from '../accounts/types';
 
+/**
+ * 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 class AuctionSubscriber {
 	private velocityClient: VelocityClient;
 	private opts: ConfirmOptions;
@@ -16,6 +23,12 @@ export class AuctionSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
 	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
 
+	/**
+	 * @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,
@@ -29,6 +42,7 @@ export class AuctionSubscriber {
 		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. */
 	public async subscribe() {
 		let subscriber = this.subscriber;
 		if (!subscriber) {
@@ -62,6 +76,7 @@ export class AuctionSubscriber {
 		);
 	}
 
+	/** Tears down the subscription. No-op if never subscribed. */
 	public async unsubscribe() {
 		if (!this.subscriber) {
 			return;

package/src/auctionSubscriber/auctionSubscriberGrpc.ts

@@ -9,6 +9,12 @@ import { WebSocketProgramAccountSubscriber } from '../accounts/webSocketProgramA
 import { GrpcConfigs, ResubOpts } from '../accounts/types';
 import { grpcProgramAccountSubscriber } from '../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`.
+ */
 export class AuctionSubscriberGrpc {
 	private velocityClient: VelocityClient;
 	private opts: ConfirmOptions;
@@ -18,6 +24,13 @@ export class AuctionSubscriberGrpc {
 	eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
 	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
 
+	/**
+	 * @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,
@@ -33,6 +46,11 @@ export class AuctionSubscriberGrpc {
 		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.
+	 */
 	public async subscribe() {
 		let subscriber = this.subscriber;
 		if (!subscriber) {
@@ -71,6 +89,7 @@ export class AuctionSubscriberGrpc {
 		);
 	}
 
+	/** Tears down the subscription. No-op if never subscribed. */
 	public async unsubscribe() {
 		if (!this.subscriber) {
 			return;

package/src/auctionSubscriber/index.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/src/auctionSubscriber/types.ts

@@ -4,17 +4,24 @@ 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,

package/src/blockhashSubscriber/BlockhashSubscriber.ts

@@ -6,6 +6,14 @@ import {
 } 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 class BlockhashSubscriber {
 	private connection: Connection;
 	private isSubscribed = false;
@@ -16,6 +24,10 @@ export class BlockhashSubscriber {
 	private commitment: Commitment;
 	private updateIntervalMs: number;
 
+	/**
+	 * @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) {
 		if (!config.connection && !config.rpcUrl) {
 			throw new Error(
@@ -27,14 +39,24 @@ export class BlockhashSubscriber {
 		this.updateIntervalMs = config.updateIntervalMs ?? 1000;
 	}
 
+	/** @returns The number of blockhashes currently cached (not-yet-expired, per `pruneBlockhashes`). */
 	getBlockhashCacheSize(): number {
 		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(): number | undefined {
 		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(): Context | undefined {
 		return this.latestBlockHeightContext;
 	}
@@ -66,6 +88,7 @@ export class BlockhashSubscriber {
 		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;
@@ -75,6 +98,14 @@ export class BlockhashSubscriber {
 		}
 	}
 
+	/**
+	 * 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([
@@ -104,6 +135,7 @@ export class BlockhashSubscriber {
 		}
 	}
 
+	/** 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;
@@ -117,6 +149,7 @@ export class BlockhashSubscriber {
 		);
 	}
 
+	/** Stops the polling interval. Cached blockhashes and `latestBlockHeight` are left in place (not cleared). */
 	unsubscribe() {
 		if (this.updateBlockhashIntervalId) {
 			clearInterval(this.updateBlockhashIntervalId);

package/src/blockhashSubscriber/index.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/src/blockhashSubscriber/types.ts

@@ -1,12 +1,13 @@
 import { Commitment, Connection } from '@solana/web3.js';
 
+/** Configuration for `BlockhashSubscriber`. */
 export type BlockhashSubscriberConfig = {
-	/// rpcUrl to poll block hashes from, one of rpcUrl or Connection must provided
+	/** 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;
-	/// connection to poll block hashes from, one of rpcUrl or Connection must provided
+	/** 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 to poll block hashes with, default is 'confirmed'
+	/** Commitment level for both the blockhash and block-height polls; defaults to `'confirmed'`. */
 	commitment?: Commitment;
-	/// interval to poll block hashes, default is 1000 ms
+	/** Poll interval in milliseconds; defaults to `1000`. */
 	updateIntervalMs?: number;
 };

package/src/clock/clockSubscriber.ts

@@ -9,10 +9,21 @@ type ClockSubscriberConfig = {
 	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 class ClockSubscriber {
 	private _latestSlot?: number;
 	private _currentTs?: number;
@@ -20,10 +31,12 @@ export class ClockSubscriber {
 	commitment: Commitment;
 	eventEmitter: StrictEventEmitter<EventEmitter, ClockSubscriberEvent>;
 
+	/** Slot of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
 	public get latestSlot(): number | undefined {
 		return this._latestSlot;
 	}
 
+	/** On-chain unix timestamp (seconds) as of the most recently observed `Clock` sysvar update, or `undefined` before the first update. */
 	public get currentTs(): number | undefined {
 		return this._currentTs;
 	}
@@ -34,6 +47,11 @@ export class ClockSubscriber {
 	private isUnsubscribing = false;
 	private receivingData = false;
 
+	/**
+	 * @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.
+	 */
 	public constructor(
 		private connection: Connection,
 		config?: ClockSubscriberConfig
@@ -48,6 +66,7 @@ export class ClockSubscriber {
 		}
 	}
 
+	/** 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. */
 	public async subscribe(): Promise<void> {
 		if (this.subscriptionId != null) {
 			return;
@@ -99,10 +118,15 @@ export 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. */
 	public getUnixTs(): number | undefined {
 		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`.
+	 */
 	public async unsubscribe(onResub = false): Promise<void> {
 		if (!onResub) {
 			this.resubTimeoutMs = undefined;

package/src/config.ts

@@ -1,5 +1,10 @@
 import { ConfirmOptions, PublicKey } from '@solana/web3.js';
-import { PerpMarketAccount, SpotMarketAccount } from './types';
+import {
+	isVariant,
+	OracleSource,
+	PerpMarketAccount,
+	SpotMarketAccount,
+} from './types';
 import {
 	DevnetPerpMarkets,
 	MainnetPerpMarkets,
@@ -17,56 +22,78 @@ import { Program, ProgramAccount } from './isomorphic/anchor';
 import { getOracleId } from './oracles/oracleId';
 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 const VELOCITY_PROGRAM_ID =
 	'vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P';
 
+/** Devnet velocity program id, base58. */
 export const VELOCITY_DEVNET_PROGRAM_ID =
 	'vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P';
 
+/** Velocity's oracle-receiver program id, base58 (same across devnet and mainnet-beta). */
 export const VELOCITY_ORACLE_RECEIVER_ID =
 	'G6EoTTTgpkNBtVXo96EQp2m6uwwVh2Kt6YidjkmQqoha';
 
+/** Pyth Lazer program id, base58. */
 export const PYTH_LAZER_PROGRAM_ID =
 	'pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt';
 
+/** Switchboard On-Demand program id on devnet. */
 export const SB_ON_DEMAND_DEVNET_PID = new PublicKey(
 	'Aio4gaXjXzJNVLtzwtNVmSqGKpANtXhybbkhtAC94ji2'
 );
+/** Switchboard On-Demand program id on mainnet-beta. */
 export const SB_ON_DEMAND_MAINNET_PID = new PublicKey(
 	'SBondMDrcV3K4kxZR1HNVT7osZxAHVHgYXL5Ze1oMUv'
 );
+/** Pyth Lazer storage account holding feed metadata, shared across environments. */
 export const PYTH_LAZER_STORAGE_ACCOUNT_KEY = new PublicKey(
 	'3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL'
 );
 
+/** Default `ConfirmOptions` (both preflight and confirmation at `'confirmed'` commitment) used across the SDK's tx senders unless overridden. */
 export const DEFAULT_CONFIRMATION_OPTS: ConfirmOptions = {
 	preflightCommitment: 'confirmed',
 	commitment: 'confirmed',
 };
 
+/** Built-in `VelocityConfig` presets for each supported environment. */
 export const configs: { [key in VelocityEnv]: VelocityConfig } = {
 	devnet: {
 		ENV: 'devnet',
@@ -89,7 +116,9 @@ export const configs: { [key in VelocityEnv]: VelocityConfig } = {
 		PYTH_ORACLE_MAPPING_ADDRESS: 'AHtgzX45WTKfkPG53L6WYhGEXwQkN1BVknET3sVsLL8J',
 		VELOCITY_PROGRAM_ID,
 		JIT_PROXY_PROGRAM_ID: 'J1TnP8zvVxbtF5KFp5xRmWuvG9McnhzmBd9XGfCyuxFP',
-		QUOTE_MINT_ADDRESS: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+		// Relaunch quote market (spot 0) is USDT — see
+		// deploy-scripts/params/relaunch-spot-markets.json.
+		QUOTE_MINT_ADDRESS: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
 		V2_ALPHA_TICKET_MINT_ADDRESS:
 			'Cmvhycb6LQvvzaShGw4iDHRLzeSSryioAsU98DSSkMNa',
 		PERP_MARKETS: MainnetPerpMarkets,
@@ -105,16 +134,25 @@ export const configs: { [key in VelocityEnv]: VelocityConfig } = {
 	},
 };
 
+/** Module-level active config; defaults to the `devnet` preset until `initialize()` is called. */
 let currentConfig: VelocityConfig = configs.devnet;
 
+/**
+ * Returns the SDK's currently active `VelocityConfig` (the `devnet` preset by default, or
+ * whatever was last set via `initialize()`).
+ * @returns The active config.
+ */
 export const getConfig = (): VelocityConfig => currentConfig;
 
 /**
- * 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 const initialize = (props: {
 	env: LegacyVelocityEnv;
@@ -128,6 +166,37 @@ export const initialize = (props: {
 	return currentConfig;
 };
 
+/**
+ * Whether the SDK can construct an `OracleClient` for `source` — mirrors the throwing branches in
+ * `getOracleClient`. Markets whose oracle source is unsupported (retired Switchboard feeds and
+ * removed Pyth pull feeds) are still listed/indexed, but their oracles must not be added to
+ * subscription lists, since building a client for them throws and would abort the whole subscribe.
+ */
+function isOracleSourceSubscribable(source: OracleSource): boolean {
+	return !(
+		isVariant(source, 'deprecatedSwitchboard') ||
+		isVariant(source, 'deprecatedSwitchboardOnDemand') ||
+		isVariant(source, 'pythPull') ||
+		isVariant(source, 'pyth1KPull') ||
+		isVariant(source, 'pyth1MPull') ||
+		isVariant(source, 'pythStableCoinPull')
+	);
+}
+
+/**
+ * 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 function getMarketsAndOraclesForSubscription(
 	env: VelocityEnv,
 	perpMarkets?: PerpMarketConfig[],
@@ -152,18 +221,22 @@ export function getMarketsAndOraclesForSubscription(
 
 	for (const market of perpMarketsToUse) {
 		perpMarketIndexes.push(market.marketIndex);
-		oracleInfos.set(getOracleId(market.oracle, market.oracleSource), {
-			publicKey: market.oracle,
-			source: market.oracleSource,
-		});
+		if (isOracleSourceSubscribable(market.oracleSource)) {
+			oracleInfos.set(getOracleId(market.oracle, market.oracleSource), {
+				publicKey: market.oracle,
+				source: market.oracleSource,
+			});
+		}
 	}
 
 	for (const spotMarket of spotMarketsToUse) {
 		spotMarketIndexes.push(spotMarket.marketIndex);
-		oracleInfos.set(getOracleId(spotMarket.oracle, spotMarket.oracleSource), {
-			publicKey: spotMarket.oracle,
-			source: spotMarket.oracleSource,
-		});
+		if (isOracleSourceSubscribable(spotMarket.oracleSource)) {
+			oracleInfos.set(getOracleId(spotMarket.oracle, spotMarket.oracleSource), {
+				publicKey: spotMarket.oracle,
+				source: spotMarket.oracleSource,
+			});
+		}
 	}
 
 	return {
@@ -173,6 +246,16 @@ export function getMarketsAndOraclesForSubscription(
 	};
 }
 
+/**
+ * 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 async function findAllMarketAndOracles(
 	program: VelocityProgram
 ): Promise<{
@@ -196,19 +279,23 @@ export async function findAllMarketAndOracles(
 	for (const perpMarketProgramAccount of perpMarketProgramAccounts) {
 		const perpMarket = perpMarketProgramAccount.account as PerpMarketAccount;
 		perpMarketIndexes.push(perpMarket.marketIndex);
-		oracleInfos.set(getOracleId(perpMarket.oracle, perpMarket.oracleSource), {
-			publicKey: perpMarket.oracle,
-			source: perpMarket.oracleSource,
-		});
+		if (isOracleSourceSubscribable(perpMarket.oracleSource)) {
+			oracleInfos.set(getOracleId(perpMarket.oracle, perpMarket.oracleSource), {
+				publicKey: perpMarket.oracle,
+				source: perpMarket.oracleSource,
+			});
+		}
 	}
 
 	for (const spotMarketProgramAccount of spotMarketProgramAccounts) {
 		const spotMarket = spotMarketProgramAccount.account as SpotMarketAccount;
 		spotMarketIndexes.push(spotMarket.marketIndex);
-		oracleInfos.set(getOracleId(spotMarket.oracle, spotMarket.oracleSource), {
-			publicKey: spotMarket.oracle,
-			source: spotMarket.oracleSource,
-		});
+		if (isOracleSourceSubscribable(spotMarket.oracleSource)) {
+			oracleInfos.set(getOracleId(spotMarket.oracle, spotMarket.oracleSource), {
+				publicKey: spotMarket.oracle,
+				source: spotMarket.oracleSource,
+			});
+		}
 	}
 
 	return {