@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/events/pollingLogProvider.d.ts

@@ -1,5 +1,13 @@
 import { LogProvider, logProviderCallback } from './types';
 import { Commitment, Connection, PublicKey } from '@solana/web3.js';
+/**
+ * `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 declare class PollingLogProvider implements LogProvider {
     private connection;
     private address;
@@ -10,8 +18,24 @@ export declare class PollingLogProvider implements LogProvider {
     private mostRecentSeenTx?;
     private mutex;
     private firstFetch;
+    /**
+     * @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.
+     */
     constructor(connection: Connection, address: PublicKey, commitment: Commitment, frequency?: number, batchSize?: number | undefined);
+    /**
+     * 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`.
+     */
     subscribe(callback: logProviderCallback, skipHistory?: boolean): Promise<boolean>;
     isSubscribed(): boolean;
+    /** Stops the polling interval. Always resolves `true`. */
     unsubscribe(): Promise<boolean>;
 }

package/lib/browser/events/pollingLogProvider.js

@@ -2,7 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingLogProvider = void 0;
 const fetchLogs_1 = require("./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).
+ */
 class PollingLogProvider {
+    /**
+     * @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.
+     */
     constructor(connection, address, commitment, frequency = 15 * 1000, batchSize) {
         this.connection = connection;
         this.address = address;
@@ -12,6 +27,14 @@ class PollingLogProvider {
         this.firstFetch = true;
         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`.
+     */
     async subscribe(callback, skipHistory) {
         if (this.intervalId) {
             return true;
@@ -48,6 +71,7 @@ class PollingLogProvider {
     isSubscribed() {
         return this.intervalId !== undefined;
     }
+    /** Stops the polling interval. Always resolves `true`. */
     async unsubscribe() {
         if (this.intervalId !== undefined) {
             clearInterval(this.intervalId);

package/lib/browser/events/sort.d.ts

@@ -1,2 +1,13 @@
 import { EventSubscriptionOrderBy, EventSubscriptionOrderDirection, SortFn } from './types';
+/**
+ * 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 declare function getSortFn(orderBy: EventSubscriptionOrderBy, orderDir: EventSubscriptionOrderDirection): SortFn;

package/lib/browser/events/sort.js

@@ -7,6 +7,7 @@ function clientSortAscFn() {
 function clientSortDescFn() {
     return 'greater than';
 }
+/** Orders events by `slot`, breaking ties by `txSigIndex` (position within the same transaction). Reproducible regardless of delivery order. */
 function blockchainSortFn(currentEvent, newEvent) {
     if (currentEvent.slot == newEvent.slot) {
         return currentEvent.txSigIndex < newEvent.txSigIndex
@@ -15,6 +16,17 @@ function blockchainSortFn(currentEvent, newEvent) {
     }
     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`.
+ */
 function getSortFn(orderBy, orderDir) {
     if (orderBy === 'client') {
         return orderDir === 'asc' ? clientSortAscFn : clientSortDescFn;

package/lib/browser/events/txEventCache.d.ts

@@ -6,19 +6,29 @@ declare class Node {
     prev?: Node | undefined;
     constructor(key: string, value: WrappedEvent<EventType>[], next?: Node | undefined, prev?: Node | undefined);
 }
+/**
+ * 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 declare class TxEventCache {
     maxTx: number;
     size: number;
     head?: Node;
     tail?: Node;
-    cacheMap: {
-        [key: string]: Node;
-    };
+    cacheMap: Map<string, Node>;
+    /** @param maxTx Max number of transactions retained; defaults to 1024. */
     constructor(maxTx?: number);
+    /** Inserts (or refreshes, if `key` already exists) the events for transaction `key` at the head, evicting the tail if this exceeds `maxTx`. */
     add(key: string, events: WrappedEvent<EventType>[]): void;
+    /** Whether transaction `key` is currently cached. */
     has(key: string): boolean;
+    /** @returns The cached events for transaction `key`, or `undefined` if not cached (never seen, or evicted). */
     get(key: string): WrappedEvent<EventType>[] | undefined;
     detach(node: Node): void;
+    /** Empties the cache. */
     clear(): void;
 }
 export {};

package/lib/browser/events/txEventCache.js

@@ -10,14 +10,23 @@ 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).
+ */
 class TxEventCache {
+    /** @param maxTx Max number of transactions retained; defaults to 1024. */
     constructor(maxTx = 1024) {
         this.maxTx = maxTx;
         this.size = 0;
-        this.cacheMap = {};
+        this.cacheMap = new Map();
     }
+    /** Inserts (or refreshes, if `key` already exists) the events for transaction `key` at the head, evicting the tail if this exceeds `maxTx`. */
     add(key, events) {
-        const existingNode = this.cacheMap[key];
+        const existingNode = this.cacheMap.get(key);
         if (existingNode) {
             this.detach(existingNode);
             this.size--;
@@ -27,7 +36,7 @@ class TxEventCache {
             if (tail === undefined) {
                 throw new Error('TxEventCache.add: cache at capacity but tail is unset');
             }
-            delete this.cacheMap[tail.key];
+            this.cacheMap.delete(tail.key);
             this.detach(tail);
             this.size--;
         }
@@ -41,15 +50,17 @@ class TxEventCache {
             this.head = node;
         }
         // 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. */
     has(key) {
-        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). */
     get(key) {
         var _a;
-        return (_a = this.cacheMap[key]) === null || _a === void 0 ? void 0 : _a.value;
+        return (_a = this.cacheMap.get(key)) === null || _a === void 0 ? void 0 : _a.value;
     }
     detach(node) {
         if (node.prev !== undefined) {
@@ -65,11 +76,12 @@ class TxEventCache {
             this.tail = node.prev;
         }
     }
+    /** Empties the cache. */
     clear() {
         this.head = undefined;
         this.tail = undefined;
         this.size = 0;
-        this.cacheMap = {};
+        this.cacheMap.clear();
     }
 }
 exports.TxEventCache = TxEventCache;

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

@@ -1,30 +1,80 @@
 /// <reference types="node" />
 import { Commitment, PublicKey, TransactionSignature } from '@solana/web3.js';
-import { DepositRecord, FundingPaymentRecord, FundingRateRecord, LiquidationRecord, NewUserRecord, OrderActionRecord, OrderRecord, SettlePnlRecord, InsuranceFundRecord, SpotInterestRecord, InsuranceFundStakeRecord, AmmCurveChanged, SwapRecord, SpotMarketVaultDepositRecord, SignedMsgOrderRecord, DeleteUserRecord, LPMintRedeemRecord, LPSettleRecord, LPSwapRecord, LPBorrowLendDepositRecord } from '../types';
+import { DepositRecord, FundingPaymentRecord, FundingRateRecord, LiquidationRecord, NewUserRecord, OrderActionRecord, OrderRecord, SettlePnlRecord, InsuranceFundRecord, SpotInterestRecord, InsuranceFundStakeRecord, AmmCurveChanged, SwapRecord, SpotMarketVaultDepositRecord, SignedMsgOrderRecord, DeleteUserRecord, LPMintRedeemRecord, 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, 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 declare const DefaultEventSubscriptionOptions: EventSubscriptionOptions;
+/**
+ * `'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;
+    /** 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>;
@@ -45,40 +95,103 @@ 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;
-export type VelocityEvent = Event<DepositRecord> | Event<FundingPaymentRecord> | Event<LiquidationRecord> | Event<FundingRateRecord> | Event<OrderRecord> | Event<OrderActionRecord> | Event<SettlePnlRecord> | Event<NewUserRecord> | Event<InsuranceFundRecord> | Event<SpotInterestRecord> | Event<InsuranceFundStakeRecord> | Event<AmmCurveChanged> | Event<SwapRecord> | Event<SpotMarketVaultDepositRecord> | Event<SignedMsgOrderRecord> | Event<DeleteUserRecord> | Event<LPSettleRecord> | Event<LPMintRedeemRecord> | Event<LPSwapRecord> | Event<LPBorrowLendDepositRecord> | Event<CuUsage>;
+/**
+ * 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> | Event<LiquidationRecord> | Event<FundingRateRecord> | Event<OrderRecord> | Event<OrderActionRecord> | Event<SettlePnlRecord> | Event<NewUserRecord> | Event<InsuranceFundRecord> | Event<SpotInterestRecord> | Event<InsuranceFundStakeRecord> | Event<AmmCurveChanged> | Event<SwapRecord> | Event<SpotMarketVaultDepositRecord> | Event<SignedMsgOrderRecord> | Event<DeleteUserRecord> | Event<LPSettleRecord> | 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, logs: string[], mostRecentBlockTime: number | undefined, 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 reconnect attempts before `EventSubscriber` fails over to the next provider in the chain (events-server → websocket → polling); default `Infinity` (never fails over). */
     maxReconnectAttempts?: number;
+    /** Poll interval (ms) for the `PollingLogProviderConfig` used once failed over to polling. */
     fallbackFrequency?: number;
+    /** `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';
+    /** 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';
+    /** Poll interval in milliseconds. */
     frequency: number;
+    /** 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';
+    /** 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: [
@@ -94,7 +207,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/lib/browser/events/types.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultEventSubscriptionOptions = void 0;
+/**
+ * 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.
+ */
 exports.DefaultEventSubscriptionOptions = {
     eventTypes: [
         'DepositRecord',
@@ -22,6 +28,11 @@ exports.DefaultEventSubscriptionOptions = {
         'LPMintRedeemRecord',
         'LPSettleRecord',
         'LPSwapRecord',
+        'LPBorrowLendDepositRecord',
+        'PerpMarketFeeSweepRecord',
+        'ProtocolFeeWithdrawRecord',
+        'RevenueShareSettleRecord',
+        'TransferFeeAndPnlPoolRecord',
     ],
     maxEventsPerType: 4096,
     orderBy: 'blockchain',

package/lib/browser/events/webSocketLogProvider.d.ts

@@ -2,6 +2,16 @@
 import { LogProvider, logProviderCallback } from './types';
 import { Commitment, Connection, PublicKey } 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 declare class WebSocketLogProvider implements LogProvider {
     private connection;
     private address;
@@ -15,10 +25,23 @@ export declare class WebSocketLogProvider implements LogProvider {
     private reconnectAttempts;
     eventEmitter?: EventEmitter;
     private callback?;
+    /**
+     * @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`.
+     */
     constructor(connection: Connection, address: PublicKey, commitment: Commitment, resubTimeoutMs?: number | undefined);
+    /** 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). */
     subscribe(callback: logProviderCallback): Promise<boolean>;
+    /** Raw `connection.onLogs` registration used internally by `subscribe` (and to reconnect). Filters out errored transactions before invoking `callback`. */
     setSubscription(callback: logProviderCallback): void;
     isSubscribed(): boolean;
+    /**
+     * 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).
+     */
     unsubscribe(external?: boolean): Promise<boolean>;
     private setTimeout;
 }

package/lib/browser/events/webSocketLogProvider.js

@@ -2,7 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketLogProvider = void 0;
 const events_1 = require("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.
+ */
 class WebSocketLogProvider {
+    /**
+     * @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`.
+     */
     constructor(connection, address, commitment, resubTimeoutMs) {
         this.connection = connection;
         this.address = address;
@@ -16,10 +32,16 @@ class WebSocketLogProvider {
             this.eventEmitter = new events_1.EventEmitter();
         }
     }
+    /** 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). */
     async subscribe(callback) {
         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);
@@ -33,6 +55,7 @@ class WebSocketLogProvider {
         }
         return true;
     }
+    /** Raw `connection.onLogs` registration used internally by `subscribe` (and to reconnect). Filters out errored transactions before invoking `callback`. */
     setSubscription(callback) {
         this.subscriptionId = this.connection.onLogs(this.address, (logs, ctx) => {
             if (this.resubTimeoutMs && !this.isUnsubscribing) {
@@ -53,6 +76,11 @@ class WebSocketLogProvider {
     isSubscribed() {
         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).
+     */
     async unsubscribe(external = false) {
         this.isUnsubscribing = true;
         this.externalUnsubscribe = external;

package/lib/browser/factory/oracleClient.js

@@ -32,8 +32,8 @@ function getOracleClient(oracleSource, connection, program) {
         (0, types_1.isVariant)(oracleSource, 'pythStableCoinPull')) {
         throw new Error('Pyth pull oracle support has been removed from the SDK');
     }
-    if ((0, types_1.isVariant)(oracleSource, 'switchboard') ||
-        (0, types_1.isVariant)(oracleSource, 'switchboardOnDemand')) {
+    if ((0, types_1.isVariant)(oracleSource, 'deprecatedSwitchboard') ||
+        (0, types_1.isVariant)(oracleSource, 'deprecatedSwitchboardOnDemand')) {
         throw new Error('Switchboard oracle support has been removed from the SDK');
     }
     if ((0, types_1.isVariant)(oracleSource, 'pythLazer')) {

package/lib/browser/idl/velocity.d.ts

@@ -11087,13 +11087,13 @@ export type Velocity = {
                 133
             ];
             "accounts": [
-                {
-                    "name": "admin";
-                    "signer": true;
-                },
                 {
                     "name": "state";
                     "writable": true;
+                },
+                {
+                    "name": "admin";
+                    "signer": true;
                 }
             ];
             "args": [

package/lib/browser/idl/velocity.json

@@ -11081,13 +11081,13 @@
                 133
             ],
             "accounts": [
-                {
-                    "name": "admin",
-                    "signer": true
-                },
                 {
                     "name": "state",
                     "writable": true
+                },
+                {
+                    "name": "admin",
+                    "signer": true
                 }
             ],
             "args": [

package/lib/browser/keypair.d.ts

@@ -1,2 +1,10 @@
 import { Keypair } from '@solana/web3.js';
+/**
+ * Loads a Solana `Keypair` from a private key given in any of the common CLI/env formats.
+ * @param privateKey - One of: a filesystem path to a JSON keypair file (checked first via
+ * `fs.existsSync`); a JSON array string (e.g. `"[1,2,3,...]"`); a comma-separated list of byte
+ * values (e.g. `"1,2,3,..."`); or a base58-encoded secret key string (whitespace is stripped).
+ * @returns The decoded `Keypair`.
+ * @throws Error (from `Keypair.fromSecretKey`) if the decoded bytes are not a valid 64-byte secret key.
+ */
 export declare function loadKeypair(privateKey: string): Keypair;

package/lib/browser/keypair.js

@@ -7,6 +7,14 @@ exports.loadKeypair = void 0;
 const fs_1 = __importDefault(require("fs"));
 const bs58_1 = __importDefault(require("bs58"));
 const web3_js_1 = require("@solana/web3.js");
+/**
+ * Loads a Solana `Keypair` from a private key given in any of the common CLI/env formats.
+ * @param privateKey - One of: a filesystem path to a JSON keypair file (checked first via
+ * `fs.existsSync`); a JSON array string (e.g. `"[1,2,3,...]"`); a comma-separated list of byte
+ * values (e.g. `"1,2,3,..."`); or a base58-encoded secret key string (whitespace is stripped).
+ * @returns The decoded `Keypair`.
+ * @throws Error (from `Keypair.fromSecretKey`) if the decoded bytes are not a valid 64-byte secret key.
+ */
 function loadKeypair(privateKey) {
     // try to load privateKey as a filepath
     let loadedKey;