@velocity-exchange/sdk 0.0.1

package/src/orderSubscriber/types.ts

@@ -0,0 +1,55 @@
+import { Commitment, PublicKey } from '@solana/web3.js';
+import { Order, UserAccount } from '../types';
+import { VelocityClient } from '../velocityClient';
+import { GrpcConfigs } from '../accounts/types';
+
+export type OrderSubscriberConfig = {
+	driftClient: VelocityClient;
+	subscriptionConfig:
+		| {
+				type: 'polling';
+				frequency: number;
+				commitment?: Commitment;
+		  }
+		| {
+				type: 'websocket';
+				skipInitialLoad?: boolean;
+				resubTimeoutMs?: number;
+				logResubMessages?: boolean;
+				resyncIntervalMs?: number;
+				commitment?: Commitment;
+		  }
+		| {
+				type: 'grpc';
+				grpcConfigs: GrpcConfigs;
+				skipInitialLoad?: boolean;
+				resubTimeoutMs?: number;
+				logResubMessages?: boolean;
+				resyncIntervalMs?: number;
+				commitment?: Commitment;
+		  };
+	fastDecode?: boolean;
+	decodeData?: boolean;
+	fetchAllNonIdleUsers?: boolean;
+};
+
+export interface OrderSubscriberEvents {
+	orderCreated: (
+		account: UserAccount,
+		updatedOrders: Order[],
+		pubkey: PublicKey,
+		slot: number,
+		dataType: 'raw' | 'decoded' | 'buffer'
+	) => void;
+	userUpdated: (
+		account: UserAccount,
+		pubkey: PublicKey,
+		slot: number,
+		dataType: 'raw' | 'decoded' | 'buffer'
+	) => void;
+	updateReceived: (
+		pubkey: PublicKey,
+		slot: number,
+		dataType: 'raw' | 'decoded' | 'buffer'
+	) => void;
+}

package/src/priorityFee/averageOverSlotsStrategy.ts

@@ -0,0 +1,16 @@
+import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
+import { PriorityFeeStrategy } from './types';
+
+export class AverageOverSlotsStrategy implements PriorityFeeStrategy {
+	calculate(samples: SolanaPriorityFeeResponse[]): number {
+		if (samples.length === 0) {
+			return 0;
+		}
+		let runningSumFees = 0;
+
+		for (let i = 0; i < samples.length; i++) {
+			runningSumFees += samples[i].prioritizationFee;
+		}
+		return runningSumFees / samples.length;
+	}
+}

package/src/priorityFee/averageStrategy.ts

@@ -0,0 +1,12 @@
+import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
+import { PriorityFeeStrategy } from './types';
+
+export class AverageStrategy implements PriorityFeeStrategy {
+	calculate(samples: SolanaPriorityFeeResponse[]): number {
+		return (
+			samples.reduce((a, b) => {
+				return a + b.prioritizationFee;
+			}, 0) / samples.length
+		);
+	}
+}

package/src/priorityFee/ewmaStrategy.ts

@@ -0,0 +1,41 @@
+import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
+import { PriorityFeeStrategy } from './types';
+
+class EwmaStrategy implements PriorityFeeStrategy {
+	private halfLife: number;
+
+	/**
+	 * @param halfLife The half life of the EWMA in slots. Default is 25 slots, approx 10 seconds.
+	 */
+	constructor(halfLife = 25) {
+		this.halfLife = halfLife;
+	}
+
+	// samples provided in desc slot order
+	calculate(samples: SolanaPriorityFeeResponse[]): number {
+		if (samples.length === 0) {
+			return 0;
+		}
+		if (samples.length === 1) {
+			return samples[0].prioritizationFee;
+		}
+
+		let ewma = 0;
+
+		const samplesReversed = samples.slice().reverse();
+		for (let i = 0; i < samplesReversed.length; i++) {
+			if (i === 0) {
+				ewma = samplesReversed[i].prioritizationFee;
+				continue;
+			}
+			const gap = samplesReversed[i].slot - samplesReversed[i - 1].slot;
+			const alpha = 1 - Math.exp((Math.log(0.5) / this.halfLife) * gap);
+
+			ewma = alpha * samplesReversed[i].prioritizationFee + (1 - alpha) * ewma;
+		}
+
+		return ewma;
+	}
+}
+
+export { EwmaStrategy };

package/src/priorityFee/heliusPriorityFeeMethod.ts

@@ -0,0 +1,57 @@
+import fetch from 'node-fetch';
+
+export enum HeliusPriorityLevel {
+	MIN = 'min', // 25th percentile
+	LOW = 'low', // 25th percentile
+	MEDIUM = 'medium', // 50th percentile
+	HIGH = 'high', // 75th percentile
+	VERY_HIGH = 'veryHigh', // 95th percentile
+	UNSAFE_MAX = 'unsafeMax', // 100th percentile
+}
+
+export type HeliusPriorityFeeLevels = {
+	[key in HeliusPriorityLevel]: number;
+};
+
+export type HeliusPriorityFeeResponse = {
+	jsonrpc: string;
+	result: {
+		priorityFeeEstimate?: number;
+		priorityFeeLevels?: HeliusPriorityFeeLevels;
+	};
+	id: string;
+};
+
+/// Fetches the priority fee from the Helius API
+/// https://docs.helius.dev/solana-rpc-nodes/alpha-priority-fee-api
+export async function fetchHeliusPriorityFee(
+	heliusRpcUrl: string,
+	lookbackDistance: number,
+	addresses: string[]
+): Promise<HeliusPriorityFeeResponse> {
+	try {
+		const response = await fetch(heliusRpcUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				jsonrpc: '2.0',
+				id: '1',
+				method: 'getPriorityFeeEstimate',
+				params: [
+					{
+						accountKeys: addresses,
+						options: {
+							includeAllPriorityFeeLevels: true,
+							lookbackSlots: lookbackDistance,
+						},
+					},
+				],
+			}),
+		});
+		return await response.json();
+	} catch (err) {
+		console.error(err);
+	}
+
+	return undefined;
+}

package/src/priorityFee/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Priority fee estimation strategies for Solana transactions.
+ * Implementations: average, EWMA, max-over-slots, max. Injected via VelocityClientConfig.
+ * Select a strategy based on congestion tolerance vs. cost sensitivity.
+ */
+export * from './averageOverSlotsStrategy';
+export * from './averageStrategy';
+export * from './ewmaStrategy';
+export * from './maxOverSlotsStrategy';
+export * from './maxStrategy';
+export * from './priorityFeeSubscriber';
+export * from './priorityFeeSubscriberMap';
+export * from './solanaPriorityFeeMethod';
+export * from './heliusPriorityFeeMethod';
+export * from './velocityPriorityFeeMethod';
+export * from './types';

package/src/priorityFee/maxOverSlotsStrategy.ts

@@ -0,0 +1,17 @@
+import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
+import { PriorityFeeStrategy } from './types';
+
+export class MaxOverSlotsStrategy implements PriorityFeeStrategy {
+	calculate(samples: SolanaPriorityFeeResponse[]): number {
+		if (samples.length === 0) {
+			return 0;
+		}
+		// Assuming samples are sorted in descending order of slot.
+		let currMaxFee = samples[0].prioritizationFee;
+
+		for (let i = 0; i < samples.length; i++) {
+			currMaxFee = Math.max(samples[i].prioritizationFee, currMaxFee);
+		}
+		return currMaxFee;
+	}
+}

package/src/priorityFee/maxStrategy.ts

@@ -0,0 +1,7 @@
+import { PriorityFeeStrategy } from './types';
+
+export class MaxStrategy implements PriorityFeeStrategy {
+	calculate(samples: { slot: number; prioritizationFee: number }[]): number {
+		return Math.max(...samples.map((result) => result.prioritizationFee));
+	}
+}

package/src/priorityFee/priorityFeeSubscriber.ts

@@ -0,0 +1,256 @@
+import { Connection, PublicKey } from '@solana/web3.js';
+import {
+	DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS,
+	PriorityFeeMethod,
+	PriorityFeeStrategy,
+	PriorityFeeSubscriberConfig,
+} from './types';
+import { AverageOverSlotsStrategy } from './averageOverSlotsStrategy';
+import { MaxOverSlotsStrategy } from './maxOverSlotsStrategy';
+import { fetchSolanaPriorityFee } from './solanaPriorityFeeMethod';
+import {
+	HeliusPriorityFeeLevels,
+	HeliusPriorityLevel,
+	fetchHeliusPriorityFee,
+} from './heliusPriorityFeeMethod';
+import {
+	fetchVelocityPriorityFee,
+	VelocityMarketInfo,
+} from './velocityPriorityFeeMethod';
+
+export class PriorityFeeSubscriber {
+	connection: Connection;
+	frequencyMs: number;
+	addresses: string[];
+	driftMarkets?: VelocityMarketInfo[];
+	customStrategy?: PriorityFeeStrategy;
+	averageStrategy = new AverageOverSlotsStrategy();
+	maxStrategy = new MaxOverSlotsStrategy();
+	priorityFeeMethod = PriorityFeeMethod.SOLANA;
+	lookbackDistance: number;
+	maxFeeMicroLamports?: number;
+	priorityFeeMultiplier?: number;
+
+	velocityPriorityFeeEndpoint?: string;
+	/** @deprecated Use `velocityPriorityFeeEndpoint` instead. `driftPriorityFeeEndpoint` will be removed in a future major. */
+	public get driftPriorityFeeEndpoint(): string | undefined {
+		return this.velocityPriorityFeeEndpoint;
+	}
+	heliusRpcUrl?: string;
+	lastHeliusSample?: HeliusPriorityFeeLevels;
+
+	intervalId?: ReturnType<typeof setTimeout>;
+
+	latestPriorityFee = 0;
+	lastCustomStrategyResult = 0;
+	lastAvgStrategyResult = 0;
+	lastMaxStrategyResult = 0;
+	lastSlotSeen = 0;
+
+	public constructor(config: PriorityFeeSubscriberConfig) {
+		this.connection = config.connection;
+		this.frequencyMs =
+			config.frequencyMs ?? DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS;
+		this.addresses = config.addresses
+			? config.addresses.map((address) => address.toBase58())
+			: [];
+		this.driftMarkets = config.driftMarkets;
+
+		if (config.customStrategy) {
+			this.customStrategy = config.customStrategy;
+		} else {
+			this.customStrategy = this.averageStrategy;
+		}
+		this.lookbackDistance = config.slotsToCheck ?? 50;
+
+		if (config.priorityFeeMethod) {
+			this.priorityFeeMethod = config.priorityFeeMethod;
+
+			if (this.priorityFeeMethod === PriorityFeeMethod.HELIUS) {
+				if (config.heliusRpcUrl === undefined) {
+					if (this.connection.rpcEndpoint.includes('helius')) {
+						this.heliusRpcUrl = this.connection.rpcEndpoint;
+					} else {
+						throw new Error(
+							'Connection must be helius, or heliusRpcUrl must be provided to use PriorityFeeMethod.HELIUS'
+						);
+					}
+				} else {
+					this.heliusRpcUrl = config.heliusRpcUrl;
+				}
+			} else if (this.priorityFeeMethod === PriorityFeeMethod.DRIFT) {
+				this.velocityPriorityFeeEndpoint =
+					config.velocityPriorityFeeEndpoint ?? config.driftPriorityFeeEndpoint;
+			}
+		}
+
+		if (this.priorityFeeMethod === PriorityFeeMethod.SOLANA) {
+			if (this.connection === undefined) {
+				throw new Error(
+					'connection must be provided to use SOLANA priority fee API'
+				);
+			}
+		}
+
+		this.maxFeeMicroLamports = config.maxFeeMicroLamports;
+		this.priorityFeeMultiplier = config.priorityFeeMultiplier ?? 1.0;
+	}
+
+	public async subscribe(): Promise<void> {
+		if (this.intervalId) {
+			return;
+		}
+
+		this.intervalId = setInterval(this.load.bind(this), this.frequencyMs); // we set the intervalId first, preventing a side effect of unsubscribing failing during the race condition where unsubscribes happens before subscribe is finished
+		await this.load();
+	}
+
+	private async loadForSolana(): Promise<void> {
+		const samples = await fetchSolanaPriorityFee(
+			this.connection!,
+			this.lookbackDistance,
+			this.addresses
+		);
+		if (samples.length > 0) {
+			this.latestPriorityFee = samples[0].prioritizationFee;
+			this.lastSlotSeen = samples[0].slot;
+
+			this.lastAvgStrategyResult = this.averageStrategy.calculate(samples);
+			this.lastMaxStrategyResult = this.maxStrategy.calculate(samples);
+			if (this.customStrategy) {
+				this.lastCustomStrategyResult = this.customStrategy.calculate(samples);
+			}
+		}
+	}
+
+	private async loadForHelius(): Promise<void> {
+		const sample = await fetchHeliusPriorityFee(
+			this.heliusRpcUrl,
+			this.lookbackDistance,
+			this.addresses
+		);
+		this.lastHeliusSample = sample?.result?.priorityFeeLevels ?? undefined;
+
+		if (this.lastHeliusSample) {
+			this.lastAvgStrategyResult =
+				this.lastHeliusSample[HeliusPriorityLevel.MEDIUM];
+			this.lastMaxStrategyResult =
+				this.lastHeliusSample[HeliusPriorityLevel.UNSAFE_MAX];
+			if (this.customStrategy) {
+				this.lastCustomStrategyResult = this.customStrategy.calculate(sample!);
+			}
+		}
+	}
+
+	private async loadForDrift(): Promise<void> {
+		if (!this.driftMarkets) {
+			return;
+		}
+		const sample = await fetchVelocityPriorityFee(
+			this.velocityPriorityFeeEndpoint!,
+			this.driftMarkets.map((m) => m.marketType),
+			this.driftMarkets.map((m) => m.marketIndex)
+		);
+		if (sample.length > 0) {
+			this.lastAvgStrategyResult = sample[HeliusPriorityLevel.MEDIUM];
+			this.lastMaxStrategyResult = sample[HeliusPriorityLevel.UNSAFE_MAX];
+			if (this.customStrategy) {
+				this.lastCustomStrategyResult = this.customStrategy.calculate(sample);
+			}
+		}
+	}
+
+	public getMaxPriorityFee(): number | undefined {
+		return this.maxFeeMicroLamports;
+	}
+
+	public updateMaxPriorityFee(newMaxFee: number | undefined) {
+		this.maxFeeMicroLamports = newMaxFee;
+	}
+
+	public getPriorityFeeMultiplier(): number {
+		return this.priorityFeeMultiplier ?? 1.0;
+	}
+
+	public updatePriorityFeeMultiplier(newPriorityFeeMultiplier: number) {
+		this.priorityFeeMultiplier = newPriorityFeeMultiplier;
+	}
+
+	public updateCustomStrategy(newStrategy: PriorityFeeStrategy) {
+		this.customStrategy = newStrategy;
+	}
+
+	public getHeliusPriorityFeeLevel(
+		level: HeliusPriorityLevel = HeliusPriorityLevel.MEDIUM
+	): number {
+		if (this.lastHeliusSample === undefined) {
+			return 0;
+		}
+		if (this.maxFeeMicroLamports !== undefined) {
+			return Math.min(this.maxFeeMicroLamports, this.lastHeliusSample[level]);
+		}
+		return this.lastHeliusSample[level];
+	}
+
+	public getCustomStrategyResult(): number {
+		const result =
+			this.lastCustomStrategyResult * this.getPriorityFeeMultiplier();
+		if (this.maxFeeMicroLamports !== undefined) {
+			return Math.min(this.maxFeeMicroLamports, result);
+		}
+		return result;
+	}
+
+	public getAvgStrategyResult(): number {
+		const result = this.lastAvgStrategyResult * this.getPriorityFeeMultiplier();
+		if (this.maxFeeMicroLamports !== undefined) {
+			return Math.min(this.maxFeeMicroLamports, result);
+		}
+		return result;
+	}
+
+	public getMaxStrategyResult(): number {
+		const result = this.lastMaxStrategyResult * this.getPriorityFeeMultiplier();
+		if (this.maxFeeMicroLamports !== undefined) {
+			return Math.min(this.maxFeeMicroLamports, result);
+		}
+		return result;
+	}
+
+	public async load(): Promise<void> {
+		try {
+			if (this.priorityFeeMethod === PriorityFeeMethod.SOLANA) {
+				await this.loadForSolana();
+			} else if (this.priorityFeeMethod === PriorityFeeMethod.HELIUS) {
+				await this.loadForHelius();
+			} else if (this.priorityFeeMethod === PriorityFeeMethod.DRIFT) {
+				await this.loadForDrift();
+			} else {
+				throw new Error(`${this.priorityFeeMethod} load not implemented`);
+			}
+		} catch (err) {
+			const e = err as Error;
+			console.error(
+				`Error loading priority fee ${this.priorityFeeMethod}: ${e.message}\n${
+					e.stack ? e.stack : ''
+				}`
+			);
+			return;
+		}
+	}
+
+	public async unsubscribe(): Promise<void> {
+		if (this.intervalId) {
+			clearInterval(this.intervalId);
+			this.intervalId = undefined;
+		}
+	}
+
+	public updateAddresses(addresses: PublicKey[]) {
+		this.addresses = addresses.map((k) => k.toBase58());
+	}
+
+	public updateMarketTypeAndIndex(driftMarkets: VelocityMarketInfo[]) {
+		this.driftMarkets = driftMarkets;
+	}
+}

package/src/priorityFee/priorityFeeSubscriberMap.ts

@@ -0,0 +1,125 @@
+import {
+	VelocityMarketInfo,
+	VelocityPriorityFeeLevels,
+	VelocityPriorityFeeResponse,
+	fetchVelocityPriorityFee,
+} from './velocityPriorityFeeMethod';
+import {
+	DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS,
+	PriorityFeeSubscriberMapConfig,
+} from './types';
+
+/**
+ * takes advantage of /batchPriorityFees endpoint from drift hosted priority fee service
+ */
+export class PriorityFeeSubscriberMap {
+	frequencyMs: number;
+	intervalId?: ReturnType<typeof setTimeout>;
+
+	driftMarkets?: VelocityMarketInfo[];
+	velocityPriorityFeeEndpoint?: string;
+	/** @deprecated Use `velocityPriorityFeeEndpoint` instead. `driftPriorityFeeEndpoint` will be removed in a future major. */
+	public get driftPriorityFeeEndpoint(): string | undefined {
+		return this.velocityPriorityFeeEndpoint;
+	}
+	feesMap: Map<string, Map<number, VelocityPriorityFeeLevels>>; // marketType -> marketIndex -> priority fee
+
+	public constructor(config: PriorityFeeSubscriberMapConfig) {
+		this.frequencyMs = config.frequencyMs;
+		this.frequencyMs =
+			config.frequencyMs ?? DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS;
+		const endpoint =
+			config.velocityPriorityFeeEndpoint ?? config.driftPriorityFeeEndpoint;
+		if (!endpoint) {
+			throw new Error(
+				'PriorityFeeSubscriberMap: velocityPriorityFeeEndpoint (or deprecated driftPriorityFeeEndpoint) must be provided'
+			);
+		}
+		this.velocityPriorityFeeEndpoint = endpoint;
+		this.driftMarkets = config.driftMarkets;
+		this.feesMap = new Map<string, Map<number, VelocityPriorityFeeLevels>>();
+		this.feesMap.set('perp', new Map<number, VelocityPriorityFeeLevels>());
+		this.feesMap.set('spot', new Map<number, VelocityPriorityFeeLevels>());
+	}
+
+	private updateFeesMap(
+		velocityPriorityFeeResponse: VelocityPriorityFeeResponse
+	) {
+		velocityPriorityFeeResponse.forEach((fee: VelocityPriorityFeeLevels) => {
+			this.feesMap.get(fee.marketType)!.set(fee.marketIndex, fee);
+		});
+	}
+
+	public async subscribe(): Promise<void> {
+		if (this.intervalId) {
+			return;
+		}
+
+		await this.load();
+		this.intervalId = setInterval(this.load.bind(this), this.frequencyMs);
+	}
+
+	public async unsubscribe(): Promise<void> {
+		if (this.intervalId) {
+			clearInterval(this.intervalId);
+			this.intervalId = undefined;
+		}
+	}
+
+	public async load(): Promise<void> {
+		try {
+			if (!this.driftMarkets) {
+				return;
+			}
+			const fees = await fetchVelocityPriorityFee(
+				this.velocityPriorityFeeEndpoint!,
+				this.driftMarkets.map((m) => m.marketType),
+				this.driftMarkets.map((m) => m.marketIndex)
+			);
+			this.updateFeesMap(fees);
+		} catch (e) {
+			console.error('Error fetching drift priority fees', e);
+		}
+	}
+
+	public updateMarketTypeAndIndex(driftMarkets: VelocityMarketInfo[]) {
+		this.driftMarkets = driftMarkets;
+	}
+
+	public getPriorityFees(
+		marketType: string,
+		marketIndex: number
+	): VelocityPriorityFeeLevels | undefined {
+		return this.feesMap.get(marketType)?.get(marketIndex);
+	}
+}
+
+/** Example usage:
+async function main() {
+    const driftMarkets: VelocityMarketInfo[] = [
+        { marketType: 'perp', marketIndex: 0 },
+        { marketType: 'perp', marketIndex: 1 },
+        { marketType: 'spot', marketIndex: 2 }
+    ];
+
+    const subscriber = new PriorityFeeSubscriberMap({
+        velocityPriorityFeeEndpoint: 'https://dlob.drift.trade',
+        frequencyMs: 5000,
+        driftMarkets
+    });
+    await subscriber.subscribe();
+
+    for (let i = 0; i < 20; i++) {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        driftMarkets.forEach(market => {
+            const fees = subscriber.getPriorityFees(market.marketType, market.marketIndex);
+            console.log(`Priority fees for ${market.marketType} market ${market.marketIndex}:`, fees);
+        });
+    }
+
+
+    await subscriber.unsubscribe();
+}
+
+main().catch(console.error);
+*/

package/src/priorityFee/solanaPriorityFeeMethod.ts

@@ -0,0 +1,34 @@
+import { Connection } from '@solana/web3.js';
+
+export type SolanaPriorityFeeResponse = {
+	slot: number;
+	prioritizationFee: number;
+};
+
+export async function fetchSolanaPriorityFee(
+	connection: Connection,
+	lookbackDistance: number,
+	addresses: string[]
+): Promise<SolanaPriorityFeeResponse[]> {
+	try {
+		// @ts-ignore
+		const rpcJSONResponse: any = await connection._rpcRequest(
+			'getRecentPrioritizationFees',
+			[addresses]
+		);
+
+		const results: SolanaPriorityFeeResponse[] = rpcJSONResponse?.result;
+
+		if (!results.length) return;
+
+		// Sort and filter results based on the slot lookback setting
+		const descResults = results.sort((a, b) => b.slot - a.slot);
+		const cutoffSlot = descResults[0].slot - lookbackDistance;
+
+		return descResults.filter((result) => result.slot >= cutoffSlot);
+	} catch (err) {
+		console.error(err);
+	}
+
+	return [];
+}