@velocity-exchange/sdk 0.0.1

package/src/events/eventSubscriber.ts

@@ -0,0 +1,382 @@
+/**
+ * EventSubscriber — streams and parses Drift 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, PublicKey, TransactionSignature } from '@solana/web3.js';
+import { Program } from '../isomorphic/anchor';
+import {
+	DefaultEventSubscriptionOptions,
+	EventSubscriptionOptions,
+	EventType,
+	WrappedEvents,
+	EventMap,
+	LogProvider,
+	EventSubscriberEvents,
+	WebSocketLogProviderConfig,
+	EventsServerLogProviderConfig,
+	LogProviderType,
+	StreamingLogProviderConfig,
+	PollingLogProviderConfig,
+} from './types';
+import { TxEventCache } from './txEventCache';
+import { EventList } from './eventList';
+import { PollingLogProvider } from './pollingLogProvider';
+import { fetchLogs } from './fetchLogs';
+import { WebSocketLogProvider } from './webSocketLogProvider';
+import { EventEmitter } from 'events';
+import StrictEventEmitter from 'strict-event-emitter-types';
+import { getSortFn } from './sort';
+import { parseLogs } from './parse';
+import { EventsServerLogProvider } from './eventsServerLogProvider';
+
+export class EventSubscriber {
+	private address: PublicKey;
+	private eventListMap: Map<EventType, EventList<EventType>>;
+	private txEventCache: TxEventCache;
+	private awaitTxPromises = new Map<string, Promise<void>>();
+	private awaitTxResolver = new Map<string, () => void>();
+	private logProvider: LogProvider;
+	private _currentProviderType: LogProviderType;
+	public eventEmitter: StrictEventEmitter<EventEmitter, EventSubscriberEvents>;
+	private lastSeenSlot: number;
+	private lastSeenBlockTime: number | undefined;
+	public lastSeenTxSig: string;
+
+	public constructor(
+		private connection: Connection,
+		private program: Program,
+		private options: EventSubscriptionOptions = DefaultEventSubscriptionOptions
+	) {
+		this.options = Object.assign({}, DefaultEventSubscriptionOptions, options);
+		this.address = this.options.address ?? program.programId;
+		this.txEventCache = new TxEventCache(this.options.maxTx);
+		this.eventListMap = new Map<EventType, EventList<EventType>>();
+		this.eventEmitter = new EventEmitter();
+
+		this._currentProviderType = this.options.logProviderConfig.type;
+		this.initializeLogProvider();
+	}
+
+	get currentProviderType() {
+		return this._currentProviderType;
+	}
+
+	private initializeLogProvider(subscribe = false) {
+		const logProviderConfig = this.options.logProviderConfig;
+
+		if (this._currentProviderType === 'websocket') {
+			this.logProvider = new WebSocketLogProvider(
+				// @ts-ignore
+				this.connection,
+				this.address,
+				this.options.commitment,
+				(
+					this.options.logProviderConfig as WebSocketLogProviderConfig
+				).resubTimeoutMs
+			);
+		} else if (this._currentProviderType === 'polling') {
+			const frequency =
+				'frequency' in logProviderConfig
+					? (logProviderConfig as PollingLogProviderConfig).frequency
+					: (logProviderConfig as StreamingLogProviderConfig).fallbackFrequency;
+			const batchSize =
+				'batchSize' in logProviderConfig
+					? (logProviderConfig as PollingLogProviderConfig).batchSize
+					: (logProviderConfig as StreamingLogProviderConfig).fallbackBatchSize;
+
+			this.logProvider = new PollingLogProvider(
+				// @ts-ignore
+				this.connection,
+				this.address,
+				this.options.commitment,
+				frequency,
+				batchSize
+			);
+		} else if (this._currentProviderType === 'events-server') {
+			this.logProvider = new EventsServerLogProvider(
+				(logProviderConfig as EventsServerLogProviderConfig).url,
+				this.options.eventTypes,
+				this.options.address ? this.options.address.toString() : undefined
+			);
+		} else {
+			throw new Error(
+				`Invalid log provider type: ${this._currentProviderType}`
+			);
+		}
+
+		if (subscribe) {
+			this.logProvider.subscribe(
+				(txSig, slot, logs, mostRecentBlockTime, txSigIndex) => {
+					this.handleTxLogs(
+						txSig,
+						slot,
+						logs,
+						mostRecentBlockTime,
+						this._currentProviderType === 'events-server',
+						txSigIndex
+					);
+				},
+				true
+			);
+		}
+	}
+
+	private populateInitialEventListMap() {
+		for (const eventType of this.options.eventTypes) {
+			this.eventListMap.set(
+				eventType,
+				new EventList(
+					eventType,
+					this.options.maxEventsPerType,
+					getSortFn(this.options.orderBy, this.options.orderDir),
+					this.options.orderDir
+				)
+			);
+		}
+	}
+
+	/**
+	 * Implements fallback logic for reconnecting to LogProvider. Currently terminates at polling,
+	 * could be improved to try the original type again after some cooldown.
+	 */
+	private updateFallbackProviderType(
+		reconnectAttempts: number,
+		maxReconnectAttempts: number
+	) {
+		if (reconnectAttempts < maxReconnectAttempts) {
+			return;
+		}
+
+		let nextProviderType = this._currentProviderType;
+		if (this._currentProviderType === 'events-server') {
+			nextProviderType = 'websocket';
+		} else if (this._currentProviderType === 'websocket') {
+			nextProviderType = 'polling';
+		} else if (this._currentProviderType === 'polling') {
+			nextProviderType = 'polling';
+		}
+
+		console.log(
+			`EventSubscriber: Failing over providerType ${this._currentProviderType} to ${nextProviderType}`
+		);
+		this._currentProviderType = nextProviderType;
+	}
+
+	public async subscribe(): Promise<boolean> {
+		try {
+			if (this.logProvider.isSubscribed()) {
+				return true;
+			}
+
+			this.populateInitialEventListMap();
+
+			if (
+				this.options.logProviderConfig.type === 'websocket' ||
+				this.options.logProviderConfig.type === 'events-server'
+			) {
+				const logProviderConfig = this.options
+					.logProviderConfig as StreamingLogProviderConfig;
+
+				if (this.logProvider.eventEmitter) {
+					this.logProvider.eventEmitter.on(
+						'reconnect',
+						async (reconnectAttempts) => {
+							if (reconnectAttempts > logProviderConfig.maxReconnectAttempts) {
+								console.log(
+									`EventSubscriber: Reconnect attempts ${reconnectAttempts}/${logProviderConfig.maxReconnectAttempts}, reconnecting...`
+								);
+								this.logProvider.eventEmitter.removeAllListeners('reconnect');
+								await this.unsubscribe();
+								this.updateFallbackProviderType(
+									reconnectAttempts,
+									logProviderConfig.maxReconnectAttempts
+								);
+								this.initializeLogProvider(true);
+							}
+						}
+					);
+				}
+			}
+			this.logProvider.subscribe(
+				(txSig, slot, logs, mostRecentBlockTime, txSigIndex) => {
+					this.handleTxLogs(
+						txSig,
+						slot,
+						logs,
+						mostRecentBlockTime,
+						this._currentProviderType === 'events-server',
+						txSigIndex
+					);
+				},
+				true
+			);
+
+			return true;
+		} catch (e) {
+			console.error('Error fetching previous txs in event subscriber');
+			console.error(e);
+			return false;
+		}
+	}
+
+	private handleTxLogs(
+		txSig: TransactionSignature,
+		slot: number,
+		logs: string[],
+		mostRecentBlockTime: number | undefined,
+		fromEventsServer = false,
+		txSigIndex: number | undefined = undefined
+	): void {
+		if (!fromEventsServer && this.txEventCache.has(txSig)) {
+			return;
+		}
+
+		const wrappedEvents = this.parseEventsFromLogs(
+			txSig,
+			slot,
+			logs,
+			txSigIndex
+		);
+
+		for (const wrappedEvent of wrappedEvents) {
+			this.eventListMap.get(wrappedEvent.eventType).insert(wrappedEvent);
+		}
+
+		// dont emit event till we've added all the events to the eventListMap
+		for (const wrappedEvent of wrappedEvents) {
+			this.eventEmitter.emit('newEvent', wrappedEvent);
+		}
+
+		if (this.awaitTxPromises.has(txSig)) {
+			this.awaitTxPromises.delete(txSig);
+			this.awaitTxResolver.get(txSig)();
+			this.awaitTxResolver.delete(txSig);
+		}
+
+		if (!this.lastSeenSlot || slot > this.lastSeenSlot) {
+			this.lastSeenTxSig = txSig;
+			this.lastSeenSlot = slot;
+		}
+
+		if (
+			this.lastSeenBlockTime === undefined ||
+			mostRecentBlockTime > this.lastSeenBlockTime
+		) {
+			this.lastSeenBlockTime = mostRecentBlockTime;
+		}
+
+		this.txEventCache.add(txSig, wrappedEvents);
+	}
+
+	public async fetchPreviousTx(fetchMax?: boolean): Promise<void> {
+		if (!this.options.untilTx && !fetchMax) {
+			return;
+		}
+
+		let txFetched = 0;
+		let beforeTx: TransactionSignature = undefined;
+		const untilTx: TransactionSignature = this.options.untilTx;
+		while (txFetched < this.options.maxTx) {
+			const response = await fetchLogs(
+				// @ts-ignore
+				this.connection,
+				this.address,
+				this.options.commitment === 'finalized' ? 'finalized' : 'confirmed',
+				beforeTx,
+				untilTx
+			);
+
+			if (response === undefined) {
+				break;
+			}
+
+			txFetched += response.transactionLogs.length;
+			beforeTx = response.earliestTx;
+
+			for (const { txSig, slot, logs } of response.transactionLogs) {
+				this.handleTxLogs(txSig, slot, logs, response.mostRecentBlockTime);
+			}
+		}
+	}
+
+	public async unsubscribe(): Promise<boolean> {
+		this.eventListMap.clear();
+		this.txEventCache.clear();
+		this.awaitTxPromises.clear();
+		this.awaitTxResolver.clear();
+
+		return await this.logProvider.unsubscribe(true);
+	}
+
+	private parseEventsFromLogs(
+		txSig: TransactionSignature,
+		slot: number,
+		logs: string[],
+		txSigIndex: number | undefined
+	): WrappedEvents {
+		const records = [];
+		// @ts-ignore
+		const events = 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) {
+				event.data.txSig = txSig;
+				event.data.slot = slot;
+				event.data.eventType = pascalName;
+				event.data.txSigIndex =
+					txSigIndex !== undefined ? txSigIndex : runningEventIndex;
+				records.push(event.data);
+			}
+			runningEventIndex++;
+		}
+		return records;
+	}
+
+	public awaitTx(txSig: TransactionSignature): Promise<void> {
+		if (this.awaitTxPromises.has(txSig)) {
+			return this.awaitTxPromises.get(txSig);
+		}
+
+		if (this.txEventCache.has(txSig)) {
+			return Promise.resolve();
+		}
+
+		const promise = new Promise<void>((resolve) => {
+			this.awaitTxResolver.set(txSig, resolve);
+		});
+		this.awaitTxPromises.set(txSig, promise);
+		return promise;
+	}
+
+	public getEventList<Type extends keyof EventMap>(
+		eventType: Type
+	): EventList<Type> {
+		return this.eventListMap.get(eventType) as EventList<Type>;
+	}
+
+	/**
+	 * This requires the EventList be cast to an array, which requires reallocation of memory.
+	 * Would bias to using getEventList over getEvents
+	 *
+	 * @param eventType
+	 */
+	public getEventsArray<Type extends EventType>(
+		eventType: Type
+	): EventMap[Type][] {
+		return this.eventListMap.get(eventType).toArray() as EventMap[Type][];
+	}
+
+	public getEventsByTx(txSig: TransactionSignature): WrappedEvents | undefined {
+		return this.txEventCache.get(txSig);
+	}
+}

package/src/events/eventsServerLogProvider.ts

@@ -0,0 +1,152 @@
+// import WebSocket from 'ws';
+import { logProviderCallback, EventType, LogProvider } from './types';
+import { EventEmitter } from 'events';
+
+// browser support
+let WebSocketImpl: typeof WebSocket;
+if (typeof window !== 'undefined' && window.WebSocket) {
+	WebSocketImpl = window.WebSocket;
+} else {
+	WebSocketImpl = require('ws');
+}
+
+const EVENT_SERVER_HEARTBEAT_INTERVAL_MS = 5000;
+const ALLOWED_MISSED_HEARTBEATS = 3;
+
+export class EventsServerLogProvider implements LogProvider {
+	private ws?: WebSocket;
+	private callback?: logProviderCallback;
+	private isUnsubscribing = false;
+	private externalUnsubscribe = false;
+	private lastHeartbeat = 0;
+	private timeoutId?: ReturnType<typeof setTimeout>;
+	private reconnectAttempts = 0;
+	eventEmitter?: EventEmitter;
+
+	public constructor(
+		private readonly url: string,
+		private readonly eventTypes: EventType[],
+		private readonly userAccount?: string
+	) {
+		this.eventEmitter = new EventEmitter();
+	}
+
+	public isSubscribed(): boolean {
+		return this.ws !== undefined;
+	}
+
+	public async subscribe(callback: logProviderCallback): Promise<boolean> {
+		if (this.ws !== undefined) {
+			return true;
+		}
+		this.ws = new WebSocketImpl(this.url);
+
+		this.callback = callback;
+		this.ws.addEventListener('open', () => {
+			for (const channel of this.eventTypes) {
+				const subscribeMessage = {
+					type: 'subscribe',
+					channel: channel,
+				};
+				if (this.userAccount) {
+					subscribeMessage['user'] = this.userAccount;
+				}
+				this.ws.send(JSON.stringify(subscribeMessage));
+			}
+			this.reconnectAttempts = 0;
+		});
+
+		this.ws.addEventListener('message', (data) => {
+			try {
+				if (!this.isUnsubscribing) {
+					clearTimeout(this.timeoutId);
+					this.setTimeout();
+					if (this.reconnectAttempts > 0) {
+						console.log(
+							'eventsServerLogProvider: Resetting reconnect attempts to 0'
+						);
+					}
+					this.reconnectAttempts = 0;
+				}
+
+				const parsedData = JSON.parse(data.data.toString());
+				if (parsedData.channel === 'heartbeat') {
+					this.lastHeartbeat = Date.now();
+					return;
+				}
+				if (parsedData.message !== undefined) {
+					return;
+				}
+				const event = JSON.parse(parsedData.data);
+				this.callback(
+					event.txSig,
+					event.slot,
+					[
+						'Program dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH invoke [1]',
+						event.rawLog,
+						'Program dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH success',
+					],
+					undefined,
+					event.txSigIndex
+				);
+			} catch (error) {
+				console.error('Error parsing message:', error);
+			}
+		});
+
+		this.ws.addEventListener('close', () => {
+			console.log('eventsServerLogProvider: WebSocket closed');
+		});
+
+		this.ws.addEventListener('error', (error) => {
+			console.error('eventsServerLogProvider: WebSocket error:', error);
+		});
+
+		this.setTimeout();
+
+		return true;
+	}
+
+	public async unsubscribe(external = false): Promise<boolean> {
+		this.isUnsubscribing = true;
+		this.externalUnsubscribe = external;
+		if (this.timeoutId) {
+			clearInterval(this.timeoutId);
+			this.timeoutId = undefined;
+		}
+
+		if (this.ws !== undefined) {
+			this.ws.close();
+			this.ws = undefined;
+			return true;
+		} else {
+			this.isUnsubscribing = false;
+			return true;
+		}
+	}
+
+	private setTimeout(): void {
+		this.timeoutId = setTimeout(async () => {
+			if (this.isUnsubscribing || this.externalUnsubscribe) {
+				// If we are in the process of unsubscribing, do not attempt to resubscribe
+				return;
+			}
+
+			const timeSinceLastHeartbeat = Date.now() - this.lastHeartbeat;
+			if (
+				timeSinceLastHeartbeat >
+				EVENT_SERVER_HEARTBEAT_INTERVAL_MS * ALLOWED_MISSED_HEARTBEATS
+			) {
+				console.log(
+					`eventServerLogProvider: No heartbeat in ${timeSinceLastHeartbeat}ms, resubscribing on attempt ${
+						this.reconnectAttempts + 1
+					}`
+				);
+				await this.unsubscribe();
+				this.reconnectAttempts++;
+				this.eventEmitter.emit('reconnect', this.reconnectAttempts);
+				this.subscribe(this.callback);
+			}
+		}, EVENT_SERVER_HEARTBEAT_INTERVAL_MS * 2);
+	}
+}

package/src/events/fetchLogs.ts

@@ -0,0 +1,169 @@
+import { Program } from '../isomorphic/anchor';
+import {
+	Connection,
+	Finality,
+	PublicKey,
+	TransactionResponse,
+	TransactionSignature,
+	VersionedTransactionResponse,
+} from '@solana/web3.js';
+import { WrappedEvents } from './types';
+import { promiseTimeout } from '../util/promiseTimeout';
+import { parseLogs } from './parse';
+
+type Log = { txSig: TransactionSignature; slot: number; logs: string[] };
+type FetchLogsResponse = {
+	earliestTx: string;
+	mostRecentTx: string;
+	earliestSlot: number;
+	mostRecentSlot: number;
+	transactionLogs: Log[];
+	mostRecentBlockTime: number | undefined;
+};
+
+function mapTransactionResponseToLog(
+	transaction: TransactionResponse | VersionedTransactionResponse
+): Log {
+	return {
+		txSig: transaction.transaction.signatures[0],
+		slot: transaction.slot,
+		logs: transaction.meta.logMessages,
+	};
+}
+
+export async function fetchLogs(
+	connection: Connection,
+	address: PublicKey,
+	finality: Finality,
+	beforeTx?: TransactionSignature,
+	untilTx?: TransactionSignature,
+	limit?: number,
+	batchSize = 25
+): Promise<FetchLogsResponse> {
+	const signatures = await connection.getSignaturesForAddress(
+		address,
+		{
+			before: beforeTx,
+			until: untilTx,
+			limit,
+		},
+		finality
+	);
+
+	const sortedSignatures = signatures.sort((a, b) =>
+		a.slot === b.slot ? 0 : a.slot < b.slot ? -1 : 1
+	);
+
+	const filteredSignatures = sortedSignatures.filter(
+		(signature) => !signature.err
+	);
+
+	if (filteredSignatures.length === 0) {
+		return undefined;
+	}
+
+	const chunkedSignatures = chunk(filteredSignatures, batchSize);
+
+	const transactionLogs = (
+		await Promise.all(
+			chunkedSignatures.map(async (chunk) => {
+				return await fetchTransactionLogs(
+					connection,
+					chunk.map((confirmedSignature) => confirmedSignature.signature),
+					finality
+				);
+			})
+		)
+	).flat();
+
+	const earliest = filteredSignatures[0];
+	const mostRecent = filteredSignatures[filteredSignatures.length - 1];
+
+	return {
+		transactionLogs: transactionLogs,
+		earliestTx: earliest.signature,
+		mostRecentTx: mostRecent.signature,
+		earliestSlot: earliest.slot,
+		mostRecentSlot: mostRecent.slot,
+		mostRecentBlockTime: mostRecent.blockTime,
+	};
+}
+
+export async function fetchTransactionLogs(
+	connection: Connection,
+	signatures: TransactionSignature[],
+	finality: Finality
+): Promise<Log[]> {
+	const requests = new Array<{ methodName: string; args: any }>();
+	for (const signature of signatures) {
+		const args = [
+			signature,
+			{ commitment: finality, maxSupportedTransactionVersion: 0 },
+		];
+
+		requests.push({
+			methodName: 'getTransaction',
+			args,
+		});
+	}
+
+	const rpcResponses: any | null = await promiseTimeout(
+		// @ts-ignore
+		connection._rpcBatchRequest(requests),
+		10 * 1000 // 10 second timeout
+	);
+
+	if (rpcResponses === null) {
+		return Promise.reject('RPC request timed out fetching transactions');
+	}
+
+	const logs = new Array<Log>();
+	for (const rpcResponse of rpcResponses) {
+		if (rpcResponse.result) {
+			logs.push(mapTransactionResponseToLog(rpcResponse.result));
+		}
+	}
+
+	return logs;
+}
+
+function chunk<T>(array: readonly T[], size: number): T[][] {
+	return new Array(Math.ceil(array.length / size))
+		.fill(null)
+		.map((_, index) => index * size)
+		.map((begin) => array.slice(begin, begin + size));
+}
+
+export class LogParser {
+	private program: Program;
+
+	constructor(program: Program) {
+		this.program = program;
+	}
+
+	public parseEventsFromTransaction(
+		transaction: TransactionResponse
+	): WrappedEvents {
+		const transactionLogObject = mapTransactionResponseToLog(transaction);
+
+		return this.parseEventsFromLogs(transactionLogObject);
+	}
+
+	public parseEventsFromLogs(event: Log): WrappedEvents {
+		const records: WrappedEvents = [];
+
+		if (!event.logs) return records;
+
+		let runningEventIndex = 0;
+		for (const eventLog of parseLogs(this.program, event.logs)) {
+			eventLog.data.txSig = event.txSig;
+			eventLog.data.slot = event.slot;
+			eventLog.data.eventType = eventLog.name;
+			eventLog.data.txSigIndex = runningEventIndex;
+			// @ts-ignore
+			records.push(eventLog.data);
+			runningEventIndex++;
+		}
+		return records;
+	}
+}