@velocity-exchange/sdk 0.2.5 → 0.4.0

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

@@ -1,24 +1,41 @@
 /// <reference types="node" />
-/**
- * EventSubscriber — streams and parses Velocity program events from transaction logs.
- *
- * Decodes all program events (OrderActionRecord, DepositRecord, LiquidationRecord,
- * FundingPaymentRecord, etc.) from `state/events.rs` into typed TypeScript objects.
- * Supports WebSocket and polling log providers; events are surfaced via an EventEmitter.
- * See `events/types.ts` for the full event type union and `events/parse.ts` for log parsing.
- */
 import { Connection, TransactionSignature } from '@solana/web3.js';
 import { Program } from '../isomorphic/anchor';
 import { EventSubscriptionOptions, EventType, WrappedEvents, EventMap, EventSubscriberEvents, LogProviderType } from './types';
 import { EventList } from './eventList';
 import { EventEmitter } from 'events';
 import StrictEventEmitter from 'strict-event-emitter-types';
+/**
+ * EventSubscriber — streams and decodes Velocity program events from
+ * transaction logs (all records emitted via `emit!` from `state/events.rs`:
+ * `DepositRecord`, `OrderActionRecord`, `LiquidationRecord`,
+ * `FundingPaymentRecord`, etc. — see `EventMap` for the full set), via a
+ * pluggable `LogProvider` (websocket, polling, or the Velocity events server),
+ * and surfaces them both through per-type `EventList`s and a `'newEvent'`
+ * `eventEmitter`.
+ *
+ * Ordering and dedup: each decoded event is tagged with `slot` and a
+ * `txSigIndex` (its position among decoded events within the same
+ * transaction); the per-event-type `EventList`s use these to sort either by
+ * blockchain order (slot, then `txSigIndex`) or by client arrival order, per
+ * `EventSubscriptionOptions.orderBy`. Whole transactions are deduped by
+ * signature via an internal LRU (`TxEventCache`, sized by `options.maxTx`):
+ * a transaction already in the cache is skipped entirely on a subsequent
+ * delivery from the *same* log provider, which protects against a
+ * websocket/polling provider redelivering the same tx. Events pushed by the
+ * events-server provider bypass this cache (it dedups upstream and supplies
+ * an authoritative `txSigIndex`). Event names are also normalized from the
+ * `@coral-xyz/anchor` 0.32+ camelCase IDL form back to the PascalCase used by
+ * `EventType`/`EventMap` before being matched against the subscribed types.
+ */
 export declare class EventSubscriber {
     private connection;
     private program;
     private options;
     private address;
     private eventListMap;
+    /** Case-insensitive lookup from decoded (camelCase) IDL event names to subscribed `EventType` keys. */
+    private eventTypeByLowercaseName;
     private txEventCache;
     private awaitTxPromises;
     private awaitTxResolver;
@@ -29,9 +46,15 @@ export declare class EventSubscriber {
     private lastSeenBlockTime;
     lastSeenTxSig: string | undefined;
     private get logProvider();
+    /**
+     * @param connection RPC connection used by the polling/websocket log providers and by `fetchPreviousTx`.
+     * @param program Anchor `Program` whose IDL coder decodes event logs (see `parse.ts`).
+     * @param options Subscription options; merged over `DefaultEventSubscriptionOptions` so any field left unset uses the default.
+     */
     constructor(connection: Connection, program: Program, options?: EventSubscriptionOptions);
     private getLogProviderConfig;
     private getEventTypes;
+    /** The `LogProviderType` currently in use. May differ from the configured type after a fallback failover (see `updateFallbackProviderType`). */
     get currentProviderType(): LogProviderType;
     private initializeLogProvider;
     private populateInitialEventListMap;
@@ -40,19 +63,73 @@ export declare class EventSubscriber {
      * could be improved to try the original type again after some cooldown.
      */
     private updateFallbackProviderType;
+    /**
+     * Starts streaming events via the configured `LogProvider`. Idempotent —
+     * returns `true` immediately if already subscribed. (Re)initializes the
+     * per-event-type `EventList`s, so any events retained from a prior
+     * subscribe/unsubscribe cycle are discarded. For streaming providers
+     * (websocket, events-server), also wires up automatic failover: if the
+     * provider emits more than `maxReconnectAttempts` (default `Infinity`,
+     * i.e. never) reconnect attempts, the subscriber tears down and
+     * reinitializes with the next provider in the fallback chain
+     * (events-server → websocket → polling; polling has no further fallback).
+     * Does not itself backfill history — call `fetchPreviousTx` for that.
+     * @returns `true` once subscribed, or `false` if an error occurred while starting the subscription (logged to console, not thrown).
+     */
     subscribe(): Promise<boolean>;
     private handleTxLogs;
+    /**
+     * Backfills historical events by walking transactions for `address` via
+     * `getSignaturesForAddress`/`getTransaction`, newest-first, until either
+     * `options.untilTx` is reached or `options.maxTx` transactions have been
+     * fetched. Each fetched transaction is decoded and inserted into the
+     * event lists exactly like a live update, so `newEvent` fires for
+     * backfilled events too. No-ops if neither `untilTx` is set nor
+     * `fetchMax` is true — the subscriber does not backfill by default.
+     * @param fetchMax If true, backfill up to `maxTx` transactions even without an `untilTx` cutoff.
+     */
     fetchPreviousTx(fetchMax?: boolean): Promise<void>;
+    /**
+     * Stops the log provider and clears all in-memory state: the per-event-type
+     * `EventList`s, the `TxEventCache`, and any pending `awaitTx` promises
+     * (which are left unresolved/unrejected — callers awaiting a tx signature
+     * across an unsubscribe will hang).
+     * @returns Whatever the underlying `LogProvider.unsubscribe` returns.
+     */
     unsubscribe(): Promise<boolean>;
     private parseEventsFromLogs;
+    /**
+     * Resolves once the subscriber has observed and decoded events for `txSig`
+     * (immediately if it's already in the `TxEventCache`). Useful for waiting
+     * on the events of a transaction the caller just sent, before reading them
+     * via `getEventsByTx`. Never rejects; a transaction that never arrives
+     * (e.g. it failed, or the subscriber isn't subscribed) leaves the returned
+     * promise pending forever.
+     * @param txSig Signature to wait for.
+     * @returns A promise that resolves (with no value) once that transaction's events have been processed.
+     */
     awaitTx(txSig: TransactionSignature): Promise<void>;
-    getEventList<Type extends keyof EventMap>(eventType: Type): EventList<Type>;
+    /**
+     * Returns the live `EventList` for `eventType` — the ordered, size-bounded
+     * (`maxEventsPerType`) linked list the subscriber inserts new events into.
+     * Prefer this over `getEventsArray` to iterate without copying.
+     * @param eventType Event type to look up; must be one of `options.eventTypes` (subscribed types).
+     * @returns The `EventList` for that type, or `undefined` if `eventType` was never subscribed (list not yet populated by `subscribe()`).
+     */
+    getEventList<Type extends keyof EventMap>(eventType: Type): EventList<Type> | undefined;
     /**
      * This requires the EventList be cast to an array, which requires reallocation of memory.
      * Would bias to using getEventList over getEvents
      *
-     * @param eventType
+     * @param eventType Event type to snapshot.
+     * @returns All currently retained events of that type, in the `EventList`'s sort order (see `EventSubscriptionOptions.orderBy`/`orderDir`).
+     * @throws If `eventType` has no `EventList` (i.e. it isn't in `options.eventTypes`).
      */
     getEventsArray<Type extends EventType>(eventType: Type): EventMap[Type][];
+    /**
+     * Looks up the decoded events previously observed for a transaction.
+     * @param txSig Transaction signature to look up.
+     * @returns The wrapped events emitted by that transaction, or `undefined` if the transaction has aged out of the `TxEventCache` (bounded by `options.maxTx`) or was never observed.
+     */
     getEventsByTx(txSig: TransactionSignature): WrappedEvents | undefined;
 }

package/lib/browser/events/eventSubscriber.js

@@ -11,6 +11,29 @@ const events_1 = require("events");
 const sort_1 = require("./sort");
 const parse_1 = require("./parse");
 const eventsServerLogProvider_1 = require("./eventsServerLogProvider");
+/**
+ * EventSubscriber — streams and decodes Velocity program events from
+ * transaction logs (all records emitted via `emit!` from `state/events.rs`:
+ * `DepositRecord`, `OrderActionRecord`, `LiquidationRecord`,
+ * `FundingPaymentRecord`, etc. — see `EventMap` for the full set), via a
+ * pluggable `LogProvider` (websocket, polling, or the Velocity events server),
+ * and surfaces them both through per-type `EventList`s and a `'newEvent'`
+ * `eventEmitter`.
+ *
+ * Ordering and dedup: each decoded event is tagged with `slot` and a
+ * `txSigIndex` (its position among decoded events within the same
+ * transaction); the per-event-type `EventList`s use these to sort either by
+ * blockchain order (slot, then `txSigIndex`) or by client arrival order, per
+ * `EventSubscriptionOptions.orderBy`. Whole transactions are deduped by
+ * signature via an internal LRU (`TxEventCache`, sized by `options.maxTx`):
+ * a transaction already in the cache is skipped entirely on a subsequent
+ * delivery from the *same* log provider, which protects against a
+ * websocket/polling provider redelivering the same tx. Events pushed by the
+ * events-server provider bypass this cache (it dedups upstream and supplies
+ * an authoritative `txSigIndex`). Event names are also normalized from the
+ * `@coral-xyz/anchor` 0.32+ camelCase IDL form back to the PascalCase used by
+ * `EventType`/`EventMap` before being matched against the subscribed types.
+ */
 class EventSubscriber {
     get logProvider() {
         if (!this._logProvider) {
@@ -18,11 +41,18 @@ class EventSubscriber {
         }
         return this._logProvider;
     }
+    /**
+     * @param connection RPC connection used by the polling/websocket log providers and by `fetchPreviousTx`.
+     * @param program Anchor `Program` whose IDL coder decodes event logs (see `parse.ts`).
+     * @param options Subscription options; merged over `DefaultEventSubscriptionOptions` so any field left unset uses the default.
+     */
     constructor(connection, program, options = types_1.DefaultEventSubscriptionOptions) {
         var _a;
         this.connection = connection;
         this.program = program;
         this.options = options;
+        /** Case-insensitive lookup from decoded (camelCase) IDL event names to subscribed `EventType` keys. */
+        this.eventTypeByLowercaseName = new Map();
         this.awaitTxPromises = new Map();
         this.awaitTxResolver = new Map();
         this.options = Object.assign({}, types_1.DefaultEventSubscriptionOptions, options);
@@ -45,6 +75,7 @@ class EventSubscriber {
         }
         return this.options.eventTypes;
     }
+    /** The `LogProviderType` currently in use. May differ from the configured type after a fallback failover (see `updateFallbackProviderType`). */
     get currentProviderType() {
         return this._currentProviderType;
     }
@@ -90,6 +121,7 @@ class EventSubscriber {
         }
         for (const eventType of this.getEventTypes()) {
             this.eventListMap.set(eventType, new eventList_1.EventList(eventType, maxEventsPerType, (0, sort_1.getSortFn)(orderBy, orderDir), orderDir));
+            this.eventTypeByLowercaseName.set(eventType.toLowerCase(), eventType);
         }
     }
     /**
@@ -113,6 +145,19 @@ class EventSubscriber {
         console.log(`EventSubscriber: Failing over providerType ${this._currentProviderType} to ${nextProviderType}`);
         this._currentProviderType = nextProviderType;
     }
+    /**
+     * Starts streaming events via the configured `LogProvider`. Idempotent —
+     * returns `true` immediately if already subscribed. (Re)initializes the
+     * per-event-type `EventList`s, so any events retained from a prior
+     * subscribe/unsubscribe cycle are discarded. For streaming providers
+     * (websocket, events-server), also wires up automatic failover: if the
+     * provider emits more than `maxReconnectAttempts` (default `Infinity`,
+     * i.e. never) reconnect attempts, the subscriber tears down and
+     * reinitializes with the next provider in the fallback chain
+     * (events-server → websocket → polling; polling has no further fallback).
+     * Does not itself backfill history — call `fetchPreviousTx` for that.
+     * @returns `true` once subscribed, or `false` if an error occurred while starting the subscription (logged to console, not thrown).
+     */
     async subscribe() {
         var _a;
         try {
@@ -186,6 +231,16 @@ class EventSubscriber {
         }
         this.txEventCache.add(txSig, wrappedEvents);
     }
+    /**
+     * Backfills historical events by walking transactions for `address` via
+     * `getSignaturesForAddress`/`getTransaction`, newest-first, until either
+     * `options.untilTx` is reached or `options.maxTx` transactions have been
+     * fetched. Each fetched transaction is decoded and inserted into the
+     * event lists exactly like a live update, so `newEvent` fires for
+     * backfilled events too. No-ops if neither `untilTx` is set nor
+     * `fetchMax` is true — the subscriber does not backfill by default.
+     * @param fetchMax If true, backfill up to `maxTx` transactions even without an `untilTx` cutoff.
+     */
     async fetchPreviousTx(fetchMax) {
         if (!this.options.untilTx && !fetchMax) {
             return;
@@ -211,6 +266,13 @@ class EventSubscriber {
             }
         }
     }
+    /**
+     * Stops the log provider and clears all in-memory state: the per-event-type
+     * `EventList`s, the `TxEventCache`, and any pending `awaitTx` promises
+     * (which are left unresolved/unrejected — callers awaiting a tx signature
+     * across an unsubscribe will hang).
+     * @returns Whatever the underlying `LogProvider.unsubscribe` returns.
+     */
     async unsubscribe() {
         this.eventListMap.clear();
         this.txEventCache.clear();
@@ -224,15 +286,14 @@ class EventSubscriber {
         const events = (0, parse_1.parseLogs)(this.program, logs);
         let runningEventIndex = 0;
         for (const event of events) {
-            // @coral-xyz/anchor 0.32+ converts IDL names to camelCase; normalize
-            // back to PascalCase so EventType keys remain consistent.
-            const pascalName = event.name.charAt(0).toUpperCase() + event.name.slice(1);
-            // @ts-ignore
-            const expectRecordType = this.eventListMap.has(pascalName);
-            if (expectRecordType) {
+            // @coral-xyz/anchor 0.32+ converts IDL names to camelCase; match
+            // case-insensitively so names with leading acronyms (LPSwapRecord →
+            // lpSwapRecord) still resolve to their PascalCase EventType keys.
+            const eventType = this.eventTypeByLowercaseName.get(event.name.toLowerCase());
+            if (eventType) {
                 event.data.txSig = txSig;
                 event.data.slot = slot;
-                event.data.eventType = pascalName;
+                event.data.eventType = eventType;
                 event.data.txSigIndex =
                     txSigIndex !== undefined ? txSigIndex : runningEventIndex;
                 records.push(event.data);
@@ -241,6 +302,16 @@ class EventSubscriber {
         }
         return records;
     }
+    /**
+     * Resolves once the subscriber has observed and decoded events for `txSig`
+     * (immediately if it's already in the `TxEventCache`). Useful for waiting
+     * on the events of a transaction the caller just sent, before reading them
+     * via `getEventsByTx`. Never rejects; a transaction that never arrives
+     * (e.g. it failed, or the subscriber isn't subscribed) leaves the returned
+     * promise pending forever.
+     * @param txSig Signature to wait for.
+     * @returns A promise that resolves (with no value) once that transaction's events have been processed.
+     */
     awaitTx(txSig) {
         const existingPromise = this.awaitTxPromises.get(txSig);
         if (existingPromise !== undefined) {
@@ -255,6 +326,13 @@ class EventSubscriber {
         this.awaitTxPromises.set(txSig, promise);
         return promise;
     }
+    /**
+     * Returns the live `EventList` for `eventType` — the ordered, size-bounded
+     * (`maxEventsPerType`) linked list the subscriber inserts new events into.
+     * Prefer this over `getEventsArray` to iterate without copying.
+     * @param eventType Event type to look up; must be one of `options.eventTypes` (subscribed types).
+     * @returns The `EventList` for that type, or `undefined` if `eventType` was never subscribed (list not yet populated by `subscribe()`).
+     */
     getEventList(eventType) {
         return this.eventListMap.get(eventType);
     }
@@ -262,7 +340,9 @@ class EventSubscriber {
      * This requires the EventList be cast to an array, which requires reallocation of memory.
      * Would bias to using getEventList over getEvents
      *
-     * @param eventType
+     * @param eventType Event type to snapshot.
+     * @returns All currently retained events of that type, in the `EventList`'s sort order (see `EventSubscriptionOptions.orderBy`/`orderDir`).
+     * @throws If `eventType` has no `EventList` (i.e. it isn't in `options.eventTypes`).
      */
     getEventsArray(eventType) {
         const eventList = this.eventListMap.get(eventType);
@@ -271,6 +351,11 @@ class EventSubscriber {
         }
         return eventList.toArray();
     }
+    /**
+     * Looks up the decoded events previously observed for a transaction.
+     * @param txSig Transaction signature to look up.
+     * @returns The wrapped events emitted by that transaction, or `undefined` if the transaction has aged out of the `TxEventCache` (bounded by `options.maxTx`) or was never observed.
+     */
     getEventsByTx(txSig) {
         return this.txEventCache.get(txSig);
     }

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

@@ -1,6 +1,17 @@
 /// <reference types="node" />
 import { logProviderCallback, EventType, LogProvider } from './types';
 import { EventEmitter } from 'events';
+/**
+ * `LogProvider` backed by the Velocity-hosted events server: a websocket
+ * that pushes pre-parsed events per subscribed channel (event type),
+ * optionally filtered to one user account, instead of raw RPC logs. Expects
+ * a heartbeat message on channel `'heartbeat'` at least every
+ * `EVENT_SERVER_HEARTBEAT_INTERVAL_MS` (5s); if none arrives within 3 missed
+ * intervals it closes and resubscribes, emitting `'reconnect'` on
+ * `eventEmitter` with the attempt count. Each received event is repackaged
+ * as a synthetic 3-line log array (`invoke` / raw log / `success`) so it can
+ * be run back through the same `parseLogs` pipeline as RPC-sourced logs.
+ */
 export declare class EventsServerLogProvider implements LogProvider {
     private readonly url;
     private readonly eventTypes;
@@ -13,9 +24,20 @@ export declare class EventsServerLogProvider implements LogProvider {
     private timeoutId?;
     private reconnectAttempts;
     eventEmitter: EventEmitter;
+    /**
+     * @param url Websocket URL of the Velocity events server.
+     * @param eventTypes Event type channels to subscribe to (one `subscribe` message sent per type on connect).
+     * @param userAccount If provided, scopes the subscription server-side to events for this user account (base58 pubkey string).
+     */
     constructor(url: string, eventTypes: EventType[], userAccount?: string | undefined);
     isSubscribed(): boolean;
+    /** Opens the websocket and sends a `subscribe` message per configured event type once connected. `skipHistory` is accepted for `LogProvider` interface compatibility but has no effect (the server only ever pushes new events). Always resolves `true`; malformed inbound messages are caught and logged, not thrown. */
     subscribe(callback: logProviderCallback): Promise<boolean>;
+    /**
+     * Closes the websocket and clears the heartbeat timeout.
+     * @param external Whether this is a caller-initiated unsubscribe rather than an internal one during a reconnect cycle.
+     * @returns Always resolves `true`.
+     */
     unsubscribe(external?: boolean): Promise<boolean>;
     private setTimeout;
 }

package/lib/browser/events/eventsServerLogProvider.js

@@ -12,7 +12,23 @@ else {
 }
 const EVENT_SERVER_HEARTBEAT_INTERVAL_MS = 5000;
 const ALLOWED_MISSED_HEARTBEATS = 3;
+/**
+ * `LogProvider` backed by the Velocity-hosted events server: a websocket
+ * that pushes pre-parsed events per subscribed channel (event type),
+ * optionally filtered to one user account, instead of raw RPC logs. Expects
+ * a heartbeat message on channel `'heartbeat'` at least every
+ * `EVENT_SERVER_HEARTBEAT_INTERVAL_MS` (5s); if none arrives within 3 missed
+ * intervals it closes and resubscribes, emitting `'reconnect'` on
+ * `eventEmitter` with the attempt count. Each received event is repackaged
+ * as a synthetic 3-line log array (`invoke` / raw log / `success`) so it can
+ * be run back through the same `parseLogs` pipeline as RPC-sourced logs.
+ */
 class EventsServerLogProvider {
+    /**
+     * @param url Websocket URL of the Velocity events server.
+     * @param eventTypes Event type channels to subscribe to (one `subscribe` message sent per type on connect).
+     * @param userAccount If provided, scopes the subscription server-side to events for this user account (base58 pubkey string).
+     */
     constructor(url, eventTypes, userAccount) {
         this.url = url;
         this.eventTypes = eventTypes;
@@ -26,12 +42,18 @@ class EventsServerLogProvider {
     isSubscribed() {
         return this.ws !== undefined;
     }
+    /** Opens the websocket and sends a `subscribe` message per configured event type once connected. `skipHistory` is accepted for `LogProvider` interface compatibility but has no effect (the server only ever pushes new events). Always resolves `true`; malformed inbound messages are caught and logged, not thrown. */
     async subscribe(callback) {
         if (this.ws !== undefined) {
             return true;
         }
         const ws = new WebSocketImpl(this.url);
         this.ws = ws;
+        // reset teardown flags for a fresh subscription cycle — the `ws !== undefined`
+        // unsubscribe path (e.g. a heartbeat-timeout resubscribe) leaves isUnsubscribing
+        // set, which would otherwise disable the watchdog and reconnect on this new socket
+        this.isUnsubscribing = false;
+        this.externalUnsubscribe = false;
         this.callback = callback;
         ws.addEventListener('open', () => {
             for (const channel of this.eventTypes) {
@@ -87,6 +109,11 @@ class EventsServerLogProvider {
         this.setTimeout();
         return true;
     }
+    /**
+     * Closes the websocket and clears the heartbeat timeout.
+     * @param external Whether this is a caller-initiated unsubscribe rather than an internal one during a reconnect cycle.
+     * @returns Always resolves `true`.
+     */
     async unsubscribe(external = false) {
         this.isUnsubscribing = true;
         this.externalUnsubscribe = external;

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

@@ -14,12 +14,43 @@ type FetchLogsResponse = {
     transactionLogs: Log[];
     mostRecentBlockTime: number | undefined;
 };
+/**
+ * Fetches raw transaction logs for `address`, newest-first from
+ * `getSignaturesForAddress` then batch-fetched via `getTransaction`. Used by
+ * both `PollingLogProvider` (incremental polling) and
+ * `EventSubscriber.fetchPreviousTx` (historical backfill). Failed
+ * transactions (with an `err`) are filtered out before fetching logs.
+ * @param connection RPC connection.
+ * @param address Account/program address to fetch signatures for.
+ * @param finality Commitment for both the signature list and the transaction fetches.
+ * @param beforeTx Only return signatures older than this one (pagination cursor).
+ * @param untilTx Stop at (exclusive of) this signature.
+ * @param limit Max signatures to request from `getSignaturesForAddress`; RPC default applies if omitted.
+ * @param batchSize Number of `getTransaction` calls batched per RPC round-trip; defaults to 25.
+ * @returns `undefined` if no non-failed signatures were found in range; otherwise the transaction logs plus the earliest/most-recent signature, slot, and block time observed, for use as the next `beforeTx`/`mostRecentSeenTx` cursor.
+ */
 export declare function fetchLogs(connection: Connection, address: PublicKey, finality: Finality, beforeTx?: TransactionSignature, untilTx?: TransactionSignature, limit?: number, batchSize?: number): Promise<FetchLogsResponse | undefined>;
+/**
+ * Fetches `getTransaction` for a batch of signatures in a single RPC batch
+ * request, with a 10-second overall timeout.
+ * @param connection RPC connection.
+ * @param signatures Signatures to fetch (fetched as `maxSupportedTransactionVersion: 0`).
+ * @param finality Commitment to fetch each transaction at.
+ * @returns One `Log` per signature that returned a result (signatures the RPC couldn't resolve are silently dropped, not padded with placeholders).
+ * @throws (rejects) if the batch RPC call doesn't complete within 10 seconds.
+ */
 export declare function fetchTransactionLogs(connection: Connection, signatures: TransactionSignature[], finality: Finality): Promise<Log[]>;
+/**
+ * Standalone helper to decode events out of an already-fetched transaction or
+ * log object, without going through `EventSubscriber`. Useful for one-off
+ * decoding (e.g. re-parsing a transaction fetched elsewhere).
+ */
 export declare class LogParser {
     private program;
     constructor(program: Program);
+    /** Decodes the events emitted in a fetched `TransactionResponse`. Assigns `txSigIndex` by decode order (0-based), not by any provider-supplied index. */
     parseEventsFromTransaction(transaction: TransactionResponse): WrappedEvents;
+    /** Decodes the events in a `{ txSig, slot, logs }` log object. Returns an empty array if `logs` is falsy. Assigns `txSigIndex` by decode order (0-based). */
     parseEventsFromLogs(event: Log): WrappedEvents;
 }
 export {};

package/lib/browser/events/fetchLogs.js

@@ -1,8 +1,20 @@
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LogParser = exports.fetchTransactionLogs = exports.fetchLogs = void 0;
+const types_1 = require("./types");
 const promiseTimeout_1 = require("../util/promiseTimeout");
 const parse_1 = require("./parse");
+/**
+ * Case-insensitive lookup from decoded (camelCase) IDL event names to
+ * PascalCase `EventType` keys, mirroring `EventSubscriber`'s
+ * `eventTypeByLowercaseName` — `@coral-xyz/anchor` 0.32+ decodes event names
+ * in camelCase, but the rest of the SDK keys off the PascalCase `EventType`.
+ */
+const eventTypeByLowercaseName = new Map(((_a = types_1.DefaultEventSubscriptionOptions.eventTypes) !== null && _a !== void 0 ? _a : []).map((eventType) => [
+    eventType.toLowerCase(),
+    eventType,
+]));
 function mapTransactionResponseToLog(transaction) {
     var _a, _b;
     return {
@@ -11,6 +23,21 @@ function mapTransactionResponseToLog(transaction) {
         logs: (_b = (_a = transaction.meta) === null || _a === void 0 ? void 0 : _a.logMessages) !== null && _b !== void 0 ? _b : [],
     };
 }
+/**
+ * Fetches raw transaction logs for `address`, newest-first from
+ * `getSignaturesForAddress` then batch-fetched via `getTransaction`. Used by
+ * both `PollingLogProvider` (incremental polling) and
+ * `EventSubscriber.fetchPreviousTx` (historical backfill). Failed
+ * transactions (with an `err`) are filtered out before fetching logs.
+ * @param connection RPC connection.
+ * @param address Account/program address to fetch signatures for.
+ * @param finality Commitment for both the signature list and the transaction fetches.
+ * @param beforeTx Only return signatures older than this one (pagination cursor).
+ * @param untilTx Stop at (exclusive of) this signature.
+ * @param limit Max signatures to request from `getSignaturesForAddress`; RPC default applies if omitted.
+ * @param batchSize Number of `getTransaction` calls batched per RPC round-trip; defaults to 25.
+ * @returns `undefined` if no non-failed signatures were found in range; otherwise the transaction logs plus the earliest/most-recent signature, slot, and block time observed, for use as the next `beforeTx`/`mostRecentSeenTx` cursor.
+ */
 async function fetchLogs(connection, address, finality, beforeTx, untilTx, limit, batchSize = 25) {
     var _a;
     const signatures = await connection.getSignaturesForAddress(address, {
@@ -39,6 +66,15 @@ async function fetchLogs(connection, address, finality, beforeTx, untilTx, limit
     };
 }
 exports.fetchLogs = fetchLogs;
+/**
+ * Fetches `getTransaction` for a batch of signatures in a single RPC batch
+ * request, with a 10-second overall timeout.
+ * @param connection RPC connection.
+ * @param signatures Signatures to fetch (fetched as `maxSupportedTransactionVersion: 0`).
+ * @param finality Commitment to fetch each transaction at.
+ * @returns One `Log` per signature that returned a result (signatures the RPC couldn't resolve are silently dropped, not padded with placeholders).
+ * @throws (rejects) if the batch RPC call doesn't complete within 10 seconds.
+ */
 async function fetchTransactionLogs(connection, signatures, finality) {
     const requests = new Array();
     for (const signature of signatures) {
@@ -73,15 +109,23 @@ function chunk(array, size) {
         .map((_, index) => index * size)
         .map((begin) => array.slice(begin, begin + size));
 }
+/**
+ * Standalone helper to decode events out of an already-fetched transaction or
+ * log object, without going through `EventSubscriber`. Useful for one-off
+ * decoding (e.g. re-parsing a transaction fetched elsewhere).
+ */
 class LogParser {
     constructor(program) {
         this.program = program;
     }
+    /** Decodes the events emitted in a fetched `TransactionResponse`. Assigns `txSigIndex` by decode order (0-based), not by any provider-supplied index. */
     parseEventsFromTransaction(transaction) {
         const transactionLogObject = mapTransactionResponseToLog(transaction);
         return this.parseEventsFromLogs(transactionLogObject);
     }
+    /** Decodes the events in a `{ txSig, slot, logs }` log object. Returns an empty array if `logs` is falsy. Assigns `txSigIndex` by decode order (0-based). */
     parseEventsFromLogs(event) {
+        var _a;
         const records = [];
         if (!event.logs)
             return records;
@@ -89,7 +133,8 @@ class LogParser {
         for (const eventLog of (0, parse_1.parseLogs)(this.program, event.logs)) {
             eventLog.data.txSig = event.txSig;
             eventLog.data.slot = event.slot;
-            eventLog.data.eventType = eventLog.name;
+            eventLog.data.eventType =
+                (_a = eventTypeByLowercaseName.get(eventLog.name.toLowerCase())) !== null && _a !== void 0 ? _a : eventLog.name;
             eventLog.data.txSigIndex = runningEventIndex;
             // @ts-ignore
             records.push(eventLog.data);

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

@@ -1,8 +1,31 @@
 import { Program, Event } from '../isomorphic/anchor';
 import { CuUsageEvent } from './types';
+/**
+ * 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 declare function parseLogs(program: Program, logs: string[], programId?: string): Event[];
+/** 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 declare function parseLogsWithRaw(program: Program, logs: string[], programId?: string): {
     events: Event[];
     rawLogs: string[];
 };
+/**
+ * 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 declare function parseLogsForCuUsage(logs: string[], programId?: string): Event<any, CuUsageEvent>[];

package/lib/browser/events/parse.js

@@ -8,11 +8,23 @@ const PROGRAM_DATA = 'Program data: ';
 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).
+ */
 function parseLogs(program, logs, programId = velocityProgramId) {
     const { events } = parseLogsWithRaw(program, logs, programId);
     return events;
 }
 exports.parseLogs = parseLogs;
+/** 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. */
 function parseLogsWithRaw(program, logs, programId = velocityProgramId) {
     const events = [];
     const rawLogs = [];
@@ -119,6 +131,17 @@ class ExecutionContext {
         this.ixStack.pop();
     }
 }
+/**
+ * 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.
+ */
 function parseLogsForCuUsage(logs, programId = velocityProgramId) {
     const cuUsageEvents = [];
     const execution = new ExecutionContext();