@velocity-exchange/sdk 0.4.0 → 0.6.0

package/src/accounts/README_WebSocketAccountSubscriberV2.md

@@ -1,95 +0,0 @@
-# WebSocketAccountSubscriberV2
-
-This is a new implementation of the WebSocket account subscriber that utilizes the [gill](https://www.npmjs.com/package/gill) library for improved RPC and WebSocket functionality.
-
-## Overview
-
-The `WebSocketAccountSubscriberV2` class provides the same interface as the original `WebSocketAccountSubscriber` but uses gill's modern TypeScript client library for Solana blockchain interactions.
-
-## Usage
-
-The usage is identical to the original `WebSocketAccountSubscriber`:
-
-```typescript
-import { WebSocketAccountSubscriberV2 } from './accounts/webSocketAccountSubscriberV2';
-
-const subscriber = new WebSocketAccountSubscriberV2(
-	'userAccount', // account name
-	program, // Anchor program instance
-	userAccountPublicKey, // PublicKey of the account to subscribe to
-	decodeBuffer, // optional custom decode function
-	resubOpts, // optional resubscription options
-	commitment // optional commitment level
-);
-
-// Subscribe to account changes
-await subscriber.subscribe((data) => {
-	console.log('Account updated:', data);
-});
-
-// Unsubscribe when done
-await subscriber.unsubscribe();
-```
-
-### Polling Instead of Resubscribing
-
-For accounts that rarely update (like long-tail markets), you can use polling instead of resubscribing to reduce resource usage:
-
-```typescript
-const resubOpts = {
-	resubTimeoutMs: 30000, // 30 seconds
-	logResubMessages: true,
-	usePollingInsteadOfResub: true, // Enable polling mode
-	pollingIntervalMs: 30000, // Poll every 30 seconds (optional, defaults to 30000)
-};
-
-const subscriber = new WebSocketAccountSubscriberV2(
-	'perpMarket', // account name
-	program,
-	marketPublicKey,
-	undefined, // decodeBuffer
-	resubOpts
-);
-```
-
-**How it works:**
-1. Initially subscribes to WebSocket updates
-2. If no WebSocket data is received for `resubTimeoutMs` (30s), switches to websocket+polling mode if `usePollingInsteadOfResub` is specified true, else just resubscribes(unsub, sub).
-3. Polls every `pollingIntervalMs` (alongside websocket connection) to check for updates by:
-   - Storing current account buffer state
-   - Fetching latest account data
-   - Comparing buffers to detect any missed updates
-4. If polling detects new data (indicating missed WebSocket events):
-   - Immediately stops polling
-   - Resubscribes to WebSocket to restore real-time updates
-   - This helps recover from degraded WebSocket connections
-5. If a WebSocket event is received while polling:
-   - Polling is automatically stopped
-   - System continues with normal WebSocket updates
-6. This approach provides:
-   - Efficient handling of rarely-updated accounts
-   - Automatic recovery from WebSocket connection issues
-   - Seamless fallback between polling and WebSocket modes
-
-## Implementation Details
-
-### Gill Integration
-
-The implementation uses gill's `createSolanaClient` function to create RPC and WebSocket clients:
-
-```typescript
-import { createSolanaClient } from 'gill';
-
-const { rpc, rpcSubscriptions } = createSolanaClient({
-	urlOrMoniker: rpcUrl, // or "mainnet", "devnet", etc.
-});
-```
-
-### Key Differences from Original
-
-1. **RPC Client**: Uses gill's `rpc` client for account fetching
-2. **WebSocket Subscriptions**: Uses gill's `rpcSubscriptions` for real-time updates
-3. **Address Handling**: Converts `PublicKey` to gill's `Address` type for compatibility
-4. **Response Formatting**: Converts gill responses to match the expected `AccountInfo<Buffer>` format
-5. **Abort Signal**: Utilizes AbortSignal nodejs/web class to shutdown websocket connection synchronously
-6. **Polling Mode**: Optional polling mechanism for accounts that rarely update

package/src/accounts/README_WebSocketProgramAccountSubscriberV2.md

@@ -1,135 +0,0 @@
-# WebSocketProgramAccountSubscriberV2
-
-This is a new implementation of the WebSocket program account subscriber that utilizes the [gill](https://www.npmjs.com/package/gill) library for improved RPC and WebSocket functionality, with additional smart polling logic for specific accounts.
-
-## Overview
-
-The `WebSocketProgramAccountSubscriberV2` class provides the same interface as the original `WebSocketProgramAccountSubscriber` but uses gill's modern TypeScript client library for Solana blockchain interactions. Additionally, it implements smart polling logic for accounts that don't update frequently (like long-tail markets) to prevent missing updates.
-
-## Key Features
-
-1. **Gill Integration**: Uses gill's `createSolanaClient` for RPC and WebSocket functionality
-2. **Smart Polling**: Optional polling for specific accounts that don't update frequently
-3. **Missed Update Detection**: Automatically detects when updates are missed and resubscribes
-4. **Configurable Polling**: 30-second default polling interval, customizable per instance
-
-## Usage
-
-The usage is similar to the original `WebSocketProgramAccountSubscriber` with additional options:
-
-```typescript
-import { WebSocketProgramAccountSubscriberV2 } from './accounts/webSocketProgramAccountSubscriberV2';
-
-// Create subscriber with optional accounts to poll
-const subscriber = new WebSocketProgramAccountSubscriberV2(
-	'perpMarket', // account name
-	'perpMarket', // account discriminator
-	program, // Anchor program instance
-	decodeBuffer, // decode function
-	{ filters: [] }, // options
-	resubOpts, // optional resubscription options
-	[longTailMarket1, longTailMarket2] // optional list of accounts to poll
-);
-
-// Subscribe to program account changes
-await subscriber.subscribe((accountId, data, context, buffer) => {
-	console.log('Account updated:', accountId.toBase58(), data);
-});
-
-// Add more accounts to poll dynamically
-subscriber.addAccountToPoll(newMarketPublicKey);
-
-// Remove accounts from polling
-subscriber.removeAccountFromPoll(oldMarketPublicKey);
-
-// Change polling interval
-subscriber.setPollingInterval(60000); // 60 seconds
-
-// Unsubscribe when done
-await subscriber.unsubscribe();
-```
-
-## Implementation Details
-
-### Gill Integration
-
-The implementation uses gill's `createSolanaClient` function to create RPC and WebSocket clients:
-
-```typescript
-import { createSolanaClient } from 'gill';
-
-const { rpc, rpcSubscriptions } = createSolanaClient({
-	urlOrMoniker: rpcUrl, // or "mainnet", "devnet", etc.
-});
-```
-
-### Smart Polling Logic
-
-1. **Account Selection**: Only accounts in the `accountsToMonitor` set are monitored
-2. **Monitoring Period**: Default 30 seconds before starting to poll an account
-3. **WebSocket Tracking**: Tracks the last WebSocket notification time for each account
-4. **Conditional Polling**: Only starts polling if no WebSocket notification received in 30 seconds
-5. **Batch Polling**: Uses `getMultipleAccounts` to poll all accounts in a single RPC call
-6. **Dynamic Polling**: Stops polling individual accounts when WebSocket notifications are received
-7. **Missed Update Detection**: Compares current slot and buffer with cached data
-8. **Automatic Resubscription**: If a missed update is detected, the entire subscription is resubscribed
-
-### Key Differences from Original
-
-1. **RPC Client**: Uses gill's `rpc` client for account fetching
-2. **WebSocket Subscriptions**: Uses gill's `rpcSubscriptions` for real-time updates
-3. **Address Handling**: Converts `PublicKey` to gill's `Address` type for compatibility
-4. **Response Formatting**: Converts gill responses to match the expected `AccountInfo<Buffer>` format
-5. **Abort Signal**: Utilizes AbortSignal nodejs/web class to shutdown websocket connection synchronously
-6. **Smart Polling**: Implements polling logic for specific accounts to prevent missed updates
-
-## Configuration Options
-
-### Constructor Parameters
-
-- `subscriptionName`: Name for logging purposes
-- `accountDiscriminator`: Account discriminator for decoding
-- `program`: Anchor program instance
-- `decodeBufferFn`: Function to decode account data
-- `options`: Subscription options (filters, commitment)
-- `resubOpts`: Resubscription options
-- `accountsToPoll`: Optional array of PublicKeys to poll
-
-### Polling Configuration
-
-- **Default Monitoring Period**: 30 seconds before starting to poll
-- **WebSocket Tracking**: Records timestamp of last WebSocket notification per account
-- **Conditional Polling**: Only polls accounts that haven't received WebSocket updates recently
-- **Batch Polling**: Uses `getMultipleAccounts` for efficient polling of multiple accounts
-- **Dynamic Management**: Automatically starts/stops polling based on WebSocket activity
-- **Detection Logic**: Compares slot numbers and buffer contents
-- **Resubscription**: Triggers when missed updates are detected
-- **Logging**: Optional logging of polling events
-
-## Current Limitations
-
-1. **Gill API Compatibility**: Some type mismatches exist with the current gill version
-2. **Account Key Handling**: The account key extraction from gill notifications needs refinement
-3. **Encoding Types**: Some encoding type comparisons need to be resolved
-
-## Future Improvements
-
-1. **Better Gill Integration**: Resolve remaining type compatibility issues
-2. **Enhanced Logging**: More detailed logging for debugging
-3. **Performance Optimization**: Optimize polling frequency based on account activity
-4. **Batch Polling**: Poll multiple accounts in a single RPC call
-
-## Migration from V1
-
-The V2 implementation maintains the same interface as V1, making migration straightforward:
-
-```typescript
-// V1
-const subscriber = new WebSocketProgramAccountSubscriber(...);
-
-// V2 (same interface)
-const subscriber = new WebSocketProgramAccountSubscriberV2(...);
-
-// V2 with polling (new feature)
-const subscriber = new WebSocketProgramAccountSubscriberV2(..., accountsToPoll);
-```

package/src/accounts/basicUserAccountSubscriber.ts

@@ -1,79 +0,0 @@
-import { DataAndSlot, UserAccountEvents, UserAccountSubscriber } from './types';
-import { PublicKey } from '@solana/web3.js';
-import StrictEventEmitter from 'strict-event-emitter-types';
-import { EventEmitter } from 'events';
-import { UserAccount } from '../types';
-
-/**
- * Basic implementation of UserAccountSubscriber. It will only take in UserAccount
- * data during initialization and will not fetch or subscribe to updates.
- */
-export class BasicUserAccountSubscriber implements UserAccountSubscriber {
-	isSubscribed: boolean;
-	eventEmitter: StrictEventEmitter<EventEmitter, UserAccountEvents>;
-	userAccountPublicKey: PublicKey;
-
-	callbackId?: string;
-	errorCallbackId?: string;
-
-	user?: DataAndSlot<UserAccount>;
-
-	/**
-	 * @param userAccountPublicKey Address of the `UserAccount` this subscriber represents (not fetched — used only for identity).
-	 * @param data Optional decoded account data to seed with; if omitted, `getUserAccountAndSlot()` returns undefined until `updateData` is called.
-	 * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
-	 */
-	public constructor(
-		userAccountPublicKey: PublicKey,
-		data?: UserAccount,
-		slot?: number
-	) {
-		this.isSubscribed = true;
-		this.eventEmitter = new EventEmitter();
-		this.userAccountPublicKey = userAccountPublicKey;
-		// `slot ?? 0` keeps {data, slot} atomic: a seeded account always carries a
-		// slot (0 = oldest-possible sentinel, overwritten by the first real fetch).
-		this.user = data ? { data, slot: slot ?? 0 } : undefined;
-	}
-
-	/** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
-	async subscribe(_userAccount?: UserAccount): Promise<boolean> {
-		return true;
-	}
-
-	async addToAccountLoader(): Promise<void> {}
-
-	/** No-op; this subscriber never fetches. Data only changes via `updateData`. */
-	async fetch(): Promise<void> {}
-
-	/** Type predicate: true once `user` has been seeded or set via `updateData`, narrowing `this.user` to non-undefined. */
-	doesAccountExist(): this is { user: DataAndSlot<UserAccount> } {
-		return this.user !== undefined;
-	}
-
-	/** No-op; there is no live subscription to tear down. */
-	async unsubscribe(): Promise<void> {}
-
-	/** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
-	assertIsSubscribed(): void {}
-
-	/** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
-	public getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined {
-		return this.user;
-	}
-
-	/**
-	 * Applies an externally-obtained account update if `slot` is not older than the currently
-	 * cached slot, emitting `userAccountUpdate`/`update` on acceptance. This is the only way this
-	 * subscriber's data changes after construction.
-	 * @param userAccount Decoded account data to apply.
-	 * @param slot Slot the data was observed at.
-	 */
-	public updateData(userAccount: UserAccount, slot: number): void {
-		if (!this.user || slot >= this.user.slot) {
-			this.user = { data: userAccount, slot };
-			this.eventEmitter.emit('userAccountUpdate', userAccount);
-			this.eventEmitter.emit('update');
-		}
-	}
-}

package/src/accounts/basicUserStatsAccountSubscriber.ts

@@ -1,87 +0,0 @@
-import {
-	DataAndSlot,
-	UserStatsAccountEvents,
-	UserStatsAccountSubscriber,
-} from './types';
-import { PublicKey } from '@solana/web3.js';
-import StrictEventEmitter from 'strict-event-emitter-types';
-import { EventEmitter } from 'events';
-import { UserStatsAccount } from '../types';
-
-/**
- * Basic implementation of UserStatsAccountSubscriber. It will only take in UserStatsAccount
- * data during initialization and will not fetch or subscribe to updates.
- */
-export class BasicUserStatsAccountSubscriber
-	implements UserStatsAccountSubscriber
-{
-	isSubscribed: boolean;
-	eventEmitter: StrictEventEmitter<EventEmitter, UserStatsAccountEvents>;
-	userStatsAccountPublicKey: PublicKey;
-
-	callbackId?: string;
-	errorCallbackId?: string;
-
-	userStats?: DataAndSlot<UserStatsAccount>;
-
-	/**
-	 * @param userStatsAccountPublicKey Address of the `UserStatsAccount` this subscriber represents (not fetched — used only for identity).
-	 * @param data Optional decoded account data to seed with; if omitted, `getUserStatsAccountAndSlot()` returns undefined until `updateData` is called.
-	 * @param slot Slot `data` was observed at; defaults to 0 (the seeded sentinel) if omitted.
-	 */
-	public constructor(
-		userStatsAccountPublicKey: PublicKey,
-		data?: UserStatsAccount,
-		slot?: number
-	) {
-		this.isSubscribed = true;
-		this.eventEmitter = new EventEmitter();
-		this.userStatsAccountPublicKey = userStatsAccountPublicKey;
-		// `slot ?? 0` keeps {data, slot} atomic: a seeded account always carries a
-		// slot (0 = oldest-possible sentinel, overwritten by the first real fetch).
-		this.userStats = data ? { data, slot: slot ?? 0 } : undefined;
-	}
-
-	/** No-op; this subscriber never performs network I/O. Always resolves `true` since `isSubscribed` is already `true` from construction. */
-	async subscribe(_userStatsAccount?: UserStatsAccount): Promise<boolean> {
-		return true;
-	}
-
-	async addToAccountLoader(): Promise<void> {}
-
-	/** No-op; this subscriber never fetches. Data only changes via `updateData`. */
-	async fetch(): Promise<void> {}
-
-	/** Type predicate: true once `userStats` has been seeded or set via `updateData`, narrowing `this.userStats` to non-undefined. */
-	doesAccountExist(): this is { userStats: DataAndSlot<UserStatsAccount> } {
-		return this.userStats !== undefined;
-	}
-
-	/** No-op; there is no live subscription to tear down. */
-	async unsubscribe(): Promise<void> {}
-
-	/** No-op; this subscriber is always considered subscribed and never throws `NotSubscribedError`. */
-	assertIsSubscribed(): void {}
-
-	/** Returns the currently cached data/slot, or undefined if never seeded/updated. Never throws (unlike other implementations, this subscriber has no "not subscribed" state). */
-	public getUserStatsAccountAndSlot():
-		| DataAndSlot<UserStatsAccount>
-		| undefined {
-		return this.userStats;
-	}
-
-	/**
-	 * Applies an externally-obtained account update if `slot` is not older than the currently
-	 * cached slot, emitting `userStatsAccountUpdate`/`update` on acceptance. This is the only way
-	 * this subscriber's data changes after construction.
-	 * @param userStatsAccount Decoded account data to apply.
-	 * @param slot Slot the data was observed at.
-	 */
-	public updateData(userStatsAccount: UserStatsAccount, slot: number): void {
-		if (!this.userStats || slot >= this.userStats.slot) {
-			this.userStats = { data: userStatsAccount, slot };
-			this.eventEmitter.emit('userStatsAccountUpdate', userStatsAccount);
-			this.eventEmitter.emit('update');
-		}
-	}
-}