@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/events/parse.ts

@@ -9,6 +9,17 @@ const PROGRAM_LOG_START_INDEX = PROGRAM_LOG.length;
 const PROGRAM_DATA_START_INDEX = PROGRAM_DATA.length;
 const PROGRAM_INSTRUCTION_START_INDEX = PROGRAM_INSTRUCTION.length;
 
+/**
+ * Decodes Anchor events from a transaction's raw log lines. Walks the log
+ * lines tracking the CPI call stack so only `msg!`/`sol_log_data` lines
+ * logged while the Velocity program is the currently-executing program are
+ * treated as candidate events; lines after `'Log truncated'` are ignored
+ * (the RPC node cut off the log before printing exceeded 10KB).
+ * @param program Anchor `Program` whose IDL coder decodes the event discriminator/payload.
+ * @param logs Raw `logMessages` for one transaction.
+ * @param programId Program ID whose logs are decoded; defaults to the Velocity program.
+ * @returns Decoded Anchor `Event`s in log order (does not include `slot`/`txSig`/`txSigIndex` — callers such as `EventSubscriber` attach those).
+ */
 export function parseLogs(
 	program: Program,
 	logs: string[],
@@ -18,6 +29,7 @@ export function parseLogs(
 	return events;
 }
 
+/** Same as `parseLogs`, but also returns the raw log line each event was decoded from (parallel-indexed to `events`), for callers that need to keep the original log text. */
 export function parseLogsWithRaw(
 	program: Program,
 	logs: string[],
@@ -151,6 +163,17 @@ class ExecutionContext {
 	}
 }
 
+/**
+ * Extracts per-instruction compute-unit usage from a transaction's raw logs
+ * by matching `Program log: Instruction: <name>` and
+ * `Program <id> consumed N of M compute units` lines while `programId` is
+ * the currently-executing program. Unlike `parseLogs`, this is not decoding
+ * a real on-chain `#[event]` — `CuUsage` is a synthetic event shape for
+ * client-side profiling.
+ * @param logs Raw `logMessages` for one transaction.
+ * @param programId Program ID whose CU consumption is measured; defaults to the Velocity program.
+ * @returns One `Event<CuUsage>` per top-level instruction invoking that program, in log order. `cuUsage` is in compute units.
+ */
 export function parseLogsForCuUsage(
 	logs: string[],
 	programId = velocityProgramId

package/src/events/pollingLogProvider.ts

@@ -8,6 +8,14 @@ import {
 } from '@solana/web3.js';
 import { fetchLogs } from './fetchLogs';
 
+/**
+ * `LogProvider` that polls `fetchLogs` (`getSignaturesForAddress` +
+ * `getTransaction`) on a fixed interval instead of holding a websocket open.
+ * Used both as the default fallback provider after repeated websocket
+ * reconnect failures and as an explicit choice for RPCs without reliable log
+ * subscriptions. Only one poll runs at a time (a simple mutex flag skips an
+ * overlapping tick if the previous fetch hasn't finished).
+ */
 export class PollingLogProvider implements LogProvider {
 	private finality: Finality;
 	private intervalId?: ReturnType<typeof setTimeout>;
@@ -15,6 +23,13 @@ export class PollingLogProvider implements LogProvider {
 	private mutex = 0;
 	private firstFetch = true;
 
+	/**
+	 * @param connection RPC connection to poll on.
+	 * @param address Account/program address to poll logs for.
+	 * @param commitment Commitment level; anything other than `'finalized'` is treated as `'confirmed'` for the underlying `fetchLogs` calls.
+	 * @param frequency Poll interval in milliseconds; defaults to 15000 (15s).
+	 * @param batchSize Max `getTransaction` calls batched per `fetchLogs` round-trip.
+	 */
 	public constructor(
 		private connection: Connection,
 		private address: PublicKey,
@@ -25,6 +40,14 @@ export class PollingLogProvider implements LogProvider {
 		this.finality = commitment === 'finalized' ? 'finalized' : 'confirmed';
 	}
 
+	/**
+	 * Starts the polling interval; the first tick fires immediately per
+	 * `setInterval` semantics only after `frequency` ms (there is no
+	 * immediate initial fetch). Idempotent — a second call while already
+	 * subscribed is a no-op.
+	 * @param skipHistory On the first poll only, fetches just the single most recent transaction instead of the full backlog since `mostRecentSeenTx`.
+	 * @returns Always resolves `true`.
+	 */
 	public async subscribe(
 		callback: logProviderCallback,
 		skipHistory?: boolean
@@ -79,6 +102,7 @@ export class PollingLogProvider implements LogProvider {
 		return this.intervalId !== undefined;
 	}
 
+	/** Stops the polling interval. Always resolves `true`. */
 	public async unsubscribe(): Promise<boolean> {
 		if (this.intervalId !== undefined) {
 			clearInterval(this.intervalId);

package/src/events/sort.ts

@@ -14,6 +14,7 @@ function clientSortDescFn(): 'greater than' {
 	return 'greater than';
 }
 
+/** Orders events by `slot`, breaking ties by `txSigIndex` (position within the same transaction). Reproducible regardless of delivery order. */
 function blockchainSortFn(
 	currentEvent: EventMap[EventType],
 	newEvent: EventMap[EventType]
@@ -27,6 +28,17 @@ function blockchainSortFn(
 	return currentEvent.slot < newEvent.slot ? 'less than' : 'greater than';
 }
 
+/**
+ * Selects the `SortFn` an `EventList` uses to place newly inserted events.
+ * `orderBy: 'client'` always inserts at the position matching `orderDir`
+ * (head for `'asc'`, tail for `'desc'`) regardless of the events' own
+ * slot/index — i.e. pure arrival order. `orderBy: 'blockchain'` always uses
+ * `blockchainSortFn` (slot, then `txSigIndex`); `orderDir` is ignored in that
+ * case — blockchain order is always ascending by slot/`txSigIndex`.
+ * @param orderBy Whether to sort by client arrival order or blockchain-produced order.
+ * @param orderDir Sort direction; ignored when `orderBy` is `'blockchain'`.
+ * @returns The `SortFn` to pass to `EventList`.
+ */
 export function getSortFn(
 	orderBy: EventSubscriptionOrderBy,
 	orderDir: EventSubscriptionOrderDirection

package/src/events/txEventCache.ts

@@ -10,16 +10,25 @@ class Node {
 }
 
 // lru cache
+/**
+ * LRU cache of decoded events keyed by transaction signature, used by
+ * `EventSubscriber` both to serve `getEventsByTx`/`awaitTx` and to dedup
+ * redeliveries of the same transaction from a log provider. Evicts the
+ * least-recently-used entry once `maxTx` is exceeded (`add()` refreshes an
+ * existing key's recency by moving it back to the head).
+ */
 export class TxEventCache {
 	size = 0;
 	head?: Node;
 	tail?: Node;
-	cacheMap: { [key: string]: Node } = {};
+	cacheMap = new Map<string, Node>();
 
+	/** @param maxTx Max number of transactions retained; defaults to 1024. */
 	constructor(public maxTx = 1024) {}
 
+	/** Inserts (or refreshes, if `key` already exists) the events for transaction `key` at the head, evicting the tail if this exceeds `maxTx`. */
 	public add(key: string, events: WrappedEvent<EventType>[]): void {
-		const existingNode = this.cacheMap[key];
+		const existingNode = this.cacheMap.get(key);
 		if (existingNode) {
 			this.detach(existingNode);
 			this.size--;
@@ -30,7 +39,7 @@ export class TxEventCache {
 					'TxEventCache.add: cache at capacity but tail is unset'
 				);
 			}
-			delete this.cacheMap[tail.key];
+			this.cacheMap.delete(tail.key);
 			this.detach(tail);
 			this.size--;
 		}
@@ -45,16 +54,18 @@ export class TxEventCache {
 		}
 
 		// update cacheMap with LinkedList key and Node reference
-		this.cacheMap[key] = this.head;
+		this.cacheMap.set(key, this.head);
 		this.size++;
 	}
 
+	/** Whether transaction `key` is currently cached. */
 	public has(key: string): boolean {
-		return this.cacheMap.hasOwnProperty(key);
+		return this.cacheMap.has(key);
 	}
 
+	/** @returns The cached events for transaction `key`, or `undefined` if not cached (never seen, or evicted). */
 	public get(key: string): WrappedEvent<EventType>[] | undefined {
-		return this.cacheMap[key]?.value;
+		return this.cacheMap.get(key)?.value;
 	}
 
 	detach(node: Node): void {
@@ -71,10 +82,11 @@ export class TxEventCache {
 		}
 	}
 
+	/** Empties the cache. */
 	public clear(): void {
 		this.head = undefined;
 		this.tail = undefined;
 		this.size = 0;
-		this.cacheMap = {};
+		this.cacheMap.clear();
 	}
 }

package/src/events/types.ts

@@ -20,23 +20,44 @@ import {
 	LPSettleRecord,
 	LPSwapRecord,
 	LPBorrowLendDepositRecord,
+	PerpMarketFeeSweepRecord,
+	ProtocolFeeWithdrawRecord,
+	RevenueShareSettleRecord,
+	TransferFeeAndPnlPoolRecord,
 } from '../types';
 import { EventEmitter } from 'events';
 
+/**
+ * Configuration for `EventSubscriber`. Unset fields fall back to the matching
+ * field in `DefaultEventSubscriptionOptions`.
+ */
 export type EventSubscriptionOptions = {
+	/** Program/account whose logs are parsed for events. Defaults to the Velocity program ID. */
 	address?: PublicKey;
+	/** Event names to decode and retain; events not in this list are dropped even if present in the logs. */
 	eventTypes?: EventType[];
+	/** Max events retained per event type in the in-memory `EventList` (oldest evicted first once exceeded). */
 	maxEventsPerType?: number;
+	/** Whether `EventList`s are sorted by the order the blockchain produced events (`'blockchain'`, by slot/txSigIndex) or the order the client received them (`'client'`). */
 	orderBy?: EventSubscriptionOrderBy;
+	/** Sort direction applied on top of `orderBy`. */
 	orderDir?: EventSubscriptionOrderDirection;
+	/** Commitment level used for both the live log subscription and any `fetchPreviousTx` backfill. */
 	commitment?: Commitment;
+	/** Max number of past transactions to backfill via `fetchPreviousTx`, and the `TxEventCache` LRU size. */
 	maxTx?: number;
+	/** Which `LogProvider` implementation streams new events: websocket, polling, or the Velocity events-server. */
 	logProviderConfig?: LogProviderConfig;
-	// when the subscription starts, client might want to backtrack and fetch old tx's
-	// this specifies how far to backtrack
+	/** When the subscription starts, backtrack and fetch historical transactions until this signature (exclusive) is reached. Only consulted by `fetchPreviousTx`. */
 	untilTx?: TransactionSignature;
 };
 
+/**
+ * Default `EventSubscriptionOptions`: all known event types (including the
+ * fee-sweep/revenue-share/LP-borrow-lend records), 4096 events retained per
+ * type, blockchain-order ascending sort, `confirmed` commitment, and a
+ * websocket log provider.
+ */
 export const DefaultEventSubscriptionOptions: EventSubscriptionOptions = {
 	eventTypes: [
 		'DepositRecord',
@@ -58,6 +79,11 @@ export const DefaultEventSubscriptionOptions: EventSubscriptionOptions = {
 		'LPMintRedeemRecord',
 		'LPSettleRecord',
 		'LPSwapRecord',
+		'LPBorrowLendDepositRecord',
+		'PerpMarketFeeSweepRecord',
+		'ProtocolFeeWithdrawRecord',
+		'RevenueShareSettleRecord',
+		'TransferFeeAndPnlPoolRecord',
 	],
 	maxEventsPerType: 4096,
 	orderBy: 'blockchain',
@@ -69,22 +95,53 @@ export const DefaultEventSubscriptionOptions: EventSubscriptionOptions = {
 	},
 };
 
-// Whether we sort events based on order blockchain produced events or client receives events
+/**
+ * `'blockchain'` sorts by the order the chain produced events (slot, then
+ * `txSigIndex` within a tx) — stable across reconnects/replays. `'client'`
+ * sorts purely by arrival order at this process, which is cheaper but not
+ * reproducible if the client reconnects or replays history.
+ */
 export type EventSubscriptionOrderBy = 'blockchain' | 'client';
+
+/** Direction applied on top of `EventSubscriptionOrderBy`: `'asc'` sorts oldest/lowest-order-key first, `'desc'` newest first. */
 export type EventSubscriptionOrderDirection = 'asc' | 'desc';
 
+/**
+ * A decoded program event record `T` (e.g. `DepositRecord`, `OrderRecord`)
+ * augmented with the transaction it was emitted in.
+ */
 export type Event<T> = T & {
+	/** Signature of the transaction that emitted this event. */
 	txSig: TransactionSignature;
+	/** Slot the transaction landed in. */
 	slot: number;
-	txSigIndex: number; // Unique index for each event inside a tx
+	/** Index of this event among all decoded events in the same transaction; used to break slot ties when sorting and for dedup. */
+	txSigIndex: number;
 };
 
+/** An `Event` tagged with its `EventMap` key, as emitted on `EventSubscriber.eventEmitter`'s `'newEvent'`. */
 export type WrappedEvent<Type extends EventType> = EventMap[Type] & {
 	eventType: Type;
 };
 
+/** An array of `WrappedEvent`s of any `EventType`, e.g. as returned by `getEventsByTx`/`LogParser.parseEventsFromLogs`. */
 export type WrappedEvents = WrappedEvent<EventType>[];
 
+/**
+ * Maps each on-chain event name (as declared in `state/events.rs` and emitted
+ * via Anchor's `emit!`) to its decoded, transaction-augmented shape. See
+ * `../types.ts` for each record's field-level precisions. Five entries were
+ * newly wired in this parity pass: `LPBorrowLendDepositRecord` (LP pool
+ * borrow/lend deposit or withdraw against a constituent, token-amount
+ * precision per the constituent's spot market), `PerpMarketFeeSweepRecord`
+ * (streaming fee-sweep drains from a perp market's pnl pool — insurance,
+ * protocol, and AMM-provision cuts — quote-token amounts, `QUOTE_PRECISION`),
+ * `ProtocolFeeWithdrawRecord` (admin withdrawal from a perp or spot market's
+ * protocol fee pool, token-amount precision of the source spot market),
+ * `RevenueShareSettleRecord` (builder/referrer revenue-share settlement, fee
+ * amounts in `QUOTE_PRECISION`), and `TransferFeeAndPnlPoolRecord` (internal
+ * transfer between a market's fee pool and pnl pool, `QUOTE_PRECISION`).
+ */
 export type EventMap = {
 	DepositRecord: Event<DepositRecord>;
 	FundingPaymentRecord: Event<FundingPaymentRecord>;
@@ -105,10 +162,26 @@ export type EventMap = {
 	LPSettleRecord: Event<LPSettleRecord>;
 	LPMintRedeemRecord: Event<LPMintRedeemRecord>;
 	LPSwapRecord: Event<LPSwapRecord>;
+	/** LP pool borrow/lend deposit or withdraw against a constituent's spot market. */
+	LPBorrowLendDepositRecord: Event<LPBorrowLendDepositRecord>;
+	/** Streaming sweep of a perp market's accrued fee ledger into the insurance, protocol, and AMM fee pools. Amounts are quote-token, `QUOTE_PRECISION` (1e6). */
+	PerpMarketFeeSweepRecord: Event<PerpMarketFeeSweepRecord>;
+	/** Admin withdrawal from a perp or spot market's protocol fee pool to a recipient token account. */
+	ProtocolFeeWithdrawRecord: Event<ProtocolFeeWithdrawRecord>;
+	/** Builder/referrer fee revenue-share settlement for a market. Fee amounts are quote-token, `QUOTE_PRECISION` (1e6). */
+	RevenueShareSettleRecord: Event<RevenueShareSettleRecord>;
+	/** Internal transfer of quote token between a perp market's fee pool and pnl pool. */
+	TransferFeeAndPnlPoolRecord: Event<TransferFeeAndPnlPoolRecord>;
 };
 
+/** Union of all decodable event names — the keys of `EventMap`. */
 export type EventType = keyof EventMap;
 
+/**
+ * Union of every possible decoded event shape (all `EventMap` value types
+ * plus the synthetic `CuUsage` event, which is not a program event and is
+ * only produced by `parseLogsForCuUsage`, not by `EventSubscriber`).
+ */
 export type VelocityEvent =
 	| Event<DepositRecord>
 	| Event<FundingPaymentRecord>
@@ -130,17 +203,38 @@ export type VelocityEvent =
 	| Event<LPMintRedeemRecord>
 	| Event<LPSwapRecord>
 	| Event<LPBorrowLendDepositRecord>
+	| Event<PerpMarketFeeSweepRecord>
+	| Event<ProtocolFeeWithdrawRecord>
+	| Event<RevenueShareSettleRecord>
+	| Event<TransferFeeAndPnlPoolRecord>
 	| Event<CuUsage>;
 
+/** Events emitted on `EventSubscriber.eventEmitter`. */
 export interface EventSubscriberEvents {
+	/** Fired once per decoded event, after it has been inserted into the subscriber's `EventList` for its type. */
 	newEvent: (event: WrappedEvent<EventType>) => void;
 }
 
+/**
+ * Comparator used by `EventList` to keep events ordered. Returns whether
+ * `newRecord` sorts before (`'less than'`) or after (`'greater than'`)
+ * `currentRecord`; see `getSortFn` for the concrete `'blockchain'`/`'client'`
+ * implementations.
+ */
 export type SortFn = (
 	currentRecord: EventMap[EventType],
 	newRecord: EventMap[EventType]
 ) => 'less than' | 'greater than';
 
+/**
+ * Callback a `LogProvider` invokes once per transaction containing raw
+ * program logs, before they are decoded into typed events.
+ * @param txSig Signature of the transaction the logs came from.
+ * @param slot Slot the transaction landed in.
+ * @param logs Raw log lines for the transaction.
+ * @param mostRecentBlockTime Unix timestamp (seconds) of the most recent block seen by the provider, if known.
+ * @param txSigIndex Explicit event index within the tx, if the provider can supply one (e.g. events-server); otherwise the consumer numbers events by decode order.
+ */
 export type logProviderCallback = (
 	txSig: TransactionSignature,
 	slot: number,
@@ -149,52 +243,75 @@ export type logProviderCallback = (
 	txSigIndex: number | undefined
 ) => void;
 
+/**
+ * Common interface implemented by each log transport (`WebSocketLogProvider`,
+ * `PollingLogProvider`, `EventsServerLogProvider`) that `EventSubscriber`
+ * drives to receive raw transaction logs.
+ */
 export interface LogProvider {
+	/** Whether the provider currently has an active subscription/connection. */
 	isSubscribed(): boolean;
+	/**
+	 * Starts streaming logs, invoking `callback` per transaction.
+	 * @param skipHistory If true, only the most recent log (not full backlog) is fetched on initial subscribe, where supported.
+	 * @returns `true` once the subscription is established.
+	 */
 	subscribe(
 		callback: logProviderCallback,
 		skipHistory?: boolean
 	): Promise<boolean>;
+	/**
+	 * Tears down the subscription.
+	 * @param external Whether this is a caller-initiated unsubscribe (as opposed to an internal one during a reconnect); suppresses auto-resubscribe when true.
+	 */
 	unsubscribe(external?: boolean): Promise<boolean>;
+	/** Emits `'reconnect'` with the current attempt count when a streaming provider detects a stall and is about to resubscribe. Only set on streaming (websocket/events-server) providers. */
 	eventEmitter?: EventEmitter;
 }
 
+/** Which `LogProvider` implementation backs an `EventSubscriber`. */
 export type LogProviderType = 'websocket' | 'polling' | 'events-server';
 
+/** Shared reconnect/fallback options for streaming (websocket, events-server) log providers. */
 export type StreamingLogProviderConfig = {
-	/// Max number of times to try reconnecting before failing over to fallback provider
+	/** Max reconnect attempts before `EventSubscriber` fails over to the next provider in the chain (events-server → websocket → polling); default `Infinity` (never fails over). */
 	maxReconnectAttempts?: number;
-	/// used for PollingLogProviderConfig on fallback
+	/** Poll interval (ms) for the `PollingLogProviderConfig` used once failed over to polling. */
 	fallbackFrequency?: number;
-	/// used for PollingLogProviderConfig on fallback
+	/** `getTransaction` batch size for the `PollingLogProviderConfig` used once failed over to polling. */
 	fallbackBatchSize?: number;
 };
 
+/** Configures `EventSubscriber` to stream events via `connection.onLogs`. */
 export type WebSocketLogProviderConfig = StreamingLogProviderConfig & {
 	type: 'websocket';
-	/// Max time to wait before resubscribing
+	/** Resubscribe if no log data arrives within this many ms; left unset, the websocket never auto-resubscribes. */
 	resubTimeoutMs?: number;
 };
 
+/** Configures `EventSubscriber` to poll for new transactions via `getSignaturesForAddress`/`getTransaction` on an interval. */
 export type PollingLogProviderConfig = {
 	type: 'polling';
-	/// frequency to poll for new events
+	/** Poll interval in milliseconds. */
 	frequency: number;
-	/// max number of events to fetch per poll
+	/** Max `getTransaction` calls batched per poll round-trip; defaults to 25 (see `fetchLogs`). */
 	batchSize?: number;
 };
 
+/** Configures `EventSubscriber` to receive pre-decoded events pushed over a websocket from the Velocity-hosted events server, instead of raw RPC logs. */
 export type EventsServerLogProviderConfig = StreamingLogProviderConfig & {
 	type: 'events-server';
-	/// url of the events server
+	/** Websocket URL of the Velocity events server. */
 	url: string;
 };
 
+/** Discriminated union of the three supported log-transport configs; the `type` field selects which `LogProvider` is constructed. */
 export type LogProviderConfig =
 	| WebSocketLogProviderConfig
 	| PollingLogProviderConfig
 	| EventsServerLogProviderConfig;
 
+/** IDL-style event descriptor used to synthesize the `CuUsage` pseudo-event decoded by `parseLogsForCuUsage`; not a real on-chain `#[event]`. */
 export type CuUsageEvent = {
 	name: 'CuUsage';
 	fields: [
@@ -211,7 +328,10 @@ export type CuUsageEvent = {
 	];
 };
 
+/** Compute-unit usage for one instruction, derived from `Program ... consumed N of M compute units` log lines (see `parseLogsForCuUsage`). Not emitted by the program itself. */
 export type CuUsage = {
+	/** Instruction name, as logged by `Program log: Instruction: <name>`. */
 	instruction: string;
+	/** Compute units consumed by that instruction. */
 	cuUsage: number;
 };

package/src/events/webSocketLogProvider.ts

@@ -8,6 +8,16 @@ import {
 } from '@solana/web3.js';
 import { EventEmitter } from 'events';
 
+/**
+ * `LogProvider` backed by `connection.onLogs` — a raw Solana websocket log
+ * subscription for `address`. Delivers only new logs from the point of
+ * subscribe (no history) and does not attempt any batching; errored
+ * transactions (`logs.err !== null`) are dropped. If `resubTimeoutMs` is set,
+ * the provider watches for a gap with no log data and automatically
+ * unsubscribes/resubscribes, emitting `'reconnect'` on `eventEmitter` with
+ * the running attempt count each time — `EventSubscriber` uses that to fail
+ * over to `PollingLogProvider` after enough attempts.
+ */
 export class WebSocketLogProvider implements LogProvider {
 	private subscriptionId?: number;
 	private isUnsubscribing = false;
@@ -17,6 +27,12 @@ export class WebSocketLogProvider implements LogProvider {
 	private reconnectAttempts = 0;
 	eventEmitter?: EventEmitter;
 	private callback?: logProviderCallback;
+	/**
+	 * @param connection RPC connection to subscribe on.
+	 * @param address Account/program address to receive logs for.
+	 * @param commitment Commitment level for the log subscription.
+	 * @param resubTimeoutMs If set, resubscribe when no log data arrives for this many ms; also enables `eventEmitter`/`'reconnect'`. Left unset, the provider never auto-resubscribes and `eventEmitter` stays `undefined`.
+	 */
 	public constructor(
 		private connection: Connection,
 		private address: PublicKey,
@@ -28,11 +44,18 @@ export class WebSocketLogProvider implements LogProvider {
 		}
 	}
 
+	/** Establishes the `onLogs` subscription (retrying once after 2s if the websocket isn't ready yet). Always resolves `true`; `skipHistory` is accepted for `LogProvider` interface compatibility but has no effect here (this provider never delivers history). */
 	public async subscribe(callback: logProviderCallback): Promise<boolean> {
 		if (this.subscriptionId != null) {
 			return true;
 		}
 
+		// reset teardown flags for a fresh subscription cycle — a caller-initiated
+		// unsubscribe(true) leaves externalUnsubscribe set, which would otherwise
+		// permanently suppress the heartbeat-driven resubscribe watchdog here
+		this.isUnsubscribing = false;
+		this.externalUnsubscribe = false;
+
 		this.callback = callback;
 		try {
 			this.setSubscription(callback);
@@ -48,6 +71,7 @@ export class WebSocketLogProvider implements LogProvider {
 		return true;
 	}
 
+	/** Raw `connection.onLogs` registration used internally by `subscribe` (and to reconnect). Filters out errored transactions before invoking `callback`. */
 	public setSubscription(callback: logProviderCallback): void {
 		this.subscriptionId = this.connection.onLogs(
 			this.address,
@@ -74,6 +98,11 @@ export class WebSocketLogProvider implements LogProvider {
 		return this.subscriptionId != null;
 	}
 
+	/**
+	 * Removes the websocket log listener and clears the resub timeout.
+	 * @param external Whether this is a caller-initiated unsubscribe rather than an internal one during a reconnect cycle; controls whether the resub timeout is allowed to fire again afterward.
+	 * @returns `true` on success (including when already unsubscribed), `false` if `removeOnLogsListener` threw (logged to console).
+	 */
 	public async unsubscribe(external = false): Promise<boolean> {
 		this.isUnsubscribing = true;
 		this.externalUnsubscribe = external;

package/src/factory/oracleClient.ts

@@ -47,8 +47,8 @@ export function getOracleClient(
 	}
 
 	if (
-		isVariant(oracleSource, 'switchboard') ||
-		isVariant(oracleSource, 'switchboardOnDemand')
+		isVariant(oracleSource, 'deprecatedSwitchboard') ||
+		isVariant(oracleSource, 'deprecatedSwitchboardOnDemand')
 	) {
 		throw new Error('Switchboard oracle support has been removed from the SDK');
 	}

package/src/idl/velocity.json

@@ -11068,6 +11068,35 @@
         }
       ]
     },
+    {
+      "name": "update_solvency_status",
+      "discriminator": [
+        81,
+        136,
+        15,
+        6,
+        24,
+        165,
+        44,
+        133
+      ],
+      "accounts": [
+        {
+          "name": "state",
+          "writable": true
+        },
+        {
+          "name": "admin",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "solvency_status",
+          "type": "u8"
+        }
+      ]
+    },
     {
       "name": "update_special_user_status",
       "discriminator": [
@@ -15972,6 +16001,16 @@
       "code": 6354,
       "name": "InsufficientProtocolFees",
       "msg": "Insufficient protocol fees available to withdraw"
+    },
+    {
+      "code": 6355,
+      "name": "InvalidNativeStateAccount",
+      "msg": "Native dispatch: supplied state account is not the canonical Velocity state PDA"
+    },
+    {
+      "code": 6356,
+      "name": "InvalidNativePerpMarketAccount",
+      "msg": "Native dispatch: supplied market account is not a Velocity perp market"
     }
   ],
   "types": [
@@ -23207,6 +23246,16 @@
             "name": "lp_pool_feature_bit_flags",
             "type": "u8"
           },
+          {
+            "name": "solvency_status",
+            "docs": [
+              "Bitmask of `SolvencyStatus` flags. Gates internal solvency-repair flows",
+              "(bankruptcy / pnl-deficit resolution) independently of `WithdrawPaused`,",
+              "so user withdrawals can be halted while repair keeps running, or repair",
+              "can be frozen on its own when an oracle is suspect. `0` = repair allowed."
+            ],
+            "type": "u8"
+          },
           {
             "name": "protocol_fee_recipient_perp",
             "docs": [
@@ -23241,7 +23290,7 @@
             "type": {
               "array": [
                 "u8",
-                272
+                271
               ]
             }
           }