@velocity-exchange/sdk 0.4.0 → 0.6.0

package/src/userConfig.ts

@@ -1,38 +0,0 @@
-import { VelocityClient } from './velocityClient';
-import { Commitment, PublicKey } from '@solana/web3.js';
-import { BulkAccountLoader } from './accounts/bulkAccountLoader';
-import { GrpcConfigs, UserAccountSubscriber } from './accounts/types';
-import { WebSocketProgramAccountSubscriber } from './accounts/webSocketProgramAccountSubscriber';
-import { UserAccount } from './types';
-import { grpcMultiUserAccountSubscriber } from './accounts/grpcMultiUserAccountSubscriber';
-
-type UserConfigBase = {
-	accountSubscription?: UserSubscriptionConfig;
-	userAccountPublicKey: PublicKey;
-};
-
-export type UserConfig = UserConfigBase & { velocityClient: VelocityClient };
-
-export type UserSubscriptionConfig =
-	| {
-			type: 'grpc';
-			resubTimeoutMs?: number;
-			logResubMessages?: boolean;
-			grpcConfigs: GrpcConfigs;
-			grpcMultiUserAccountSubscriber?: grpcMultiUserAccountSubscriber;
-	  }
-	| {
-			type: 'websocket';
-			resubTimeoutMs?: number;
-			logResubMessages?: boolean;
-			commitment?: Commitment;
-			programUserAccountSubscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
-	  }
-	| {
-			type: 'polling';
-			accountLoader: BulkAccountLoader;
-	  }
-	| {
-			type: 'custom';
-			userAccountSubscriber: UserAccountSubscriber;
-	  };

package/src/userMap/PollingSubscription.ts

@@ -1,61 +0,0 @@
-import { UserMap } from './userMap';
-
-/**
- * `UserMap`'s `'polling'` subscription strategy: re-runs a full `userMap.sync()`
- * on a fixed `setTimeout` interval (self-rescheduling, so syncs never overlap).
- * Internal to `UserMap` — not part of the SDK's public exports.
- */
-export class PollingSubscription {
-	private userMap: UserMap;
-	private frequency: number;
-	private skipInitialLoad: boolean;
-
-	intervalId?: ReturnType<typeof setTimeout>;
-	private active = false;
-
-	constructor({
-		userMap,
-		frequency,
-		skipInitialLoad = false,
-	}: {
-		userMap: UserMap;
-		/** Milliseconds to wait after one sync completes before starting the next. */
-		frequency: number;
-		/** If true, does not sync immediately on `subscribe()` — the first sync happens after `frequency` ms. */
-		skipInitialLoad?: boolean;
-		includeIdle?: boolean;
-	}) {
-		this.userMap = userMap;
-		this.frequency = frequency;
-		this.skipInitialLoad = skipInitialLoad;
-	}
-
-	/** Starts the polling loop. No-op if already started or `frequency <= 0`. */
-	public async subscribe(): Promise<void> {
-		if (this.active || this.frequency <= 0) {
-			return;
-		}
-		this.active = true;
-
-		const executeSync = async () => {
-			await this.userMap.sync();
-			if (this.active) {
-				this.intervalId = setTimeout(executeSync, this.frequency);
-			}
-		};
-
-		if (!this.skipInitialLoad) {
-			await this.userMap.sync();
-		}
-		executeSync();
-	}
-
-	/** Stops the polling loop. */
-	public async unsubscribe(): Promise<void> {
-		this.active = false;
-		if (this.intervalId) {
-			clearInterval(this.intervalId);
-			this.intervalId = undefined;
-		}
-	}
-}

package/src/userMap/WebsocketSubscription.ts

@@ -1,93 +0,0 @@
-import { UserMap } from './userMap';
-import { getNonIdleUserFilter, getUserFilter } from '../memcmp';
-import { WebSocketProgramAccountSubscriber } from '../accounts/webSocketProgramAccountSubscriber';
-import { UserAccount } from '../types';
-import { Commitment, Context, MemcmpFilter, PublicKey } from '@solana/web3.js';
-import { ResubOpts } from '../accounts/types';
-
-/**
- * `UserMap`'s `'websocket'` subscription strategy: uses
- * `WebSocketProgramAccountSubscriber` with the map's memcmp filters (base
- * `User` filter, plus non-idle unless `includeIdle`, plus any
- * `additionalFilters`) to receive push updates for every matching account,
- * feeding them into `userMap.updateUserAccount`. Internal to `UserMap` — not
- * part of the SDK's public exports.
- */
-export class WebsocketSubscription {
-	private userMap: UserMap;
-	private commitment: Commitment;
-	private skipInitialLoad: boolean;
-	private resubOpts?: ResubOpts;
-	private includeIdle?: boolean;
-	private additionalFilters?: MemcmpFilter[];
-	private decodeFn: (name: string, data: Buffer) => UserAccount;
-
-	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
-
-	constructor({
-		userMap,
-		commitment,
-		skipInitialLoad = false,
-		resubOpts,
-		includeIdle = false,
-		decodeFn,
-		additionalFilters = undefined,
-	}: {
-		userMap: UserMap;
-		commitment: Commitment;
-		skipInitialLoad?: boolean;
-		resubOpts?: ResubOpts;
-		includeIdle?: boolean;
-		decodeFn: (name: string, data: Buffer) => UserAccount;
-		additionalFilters?: MemcmpFilter[];
-	}) {
-		this.userMap = userMap;
-		this.commitment = commitment;
-		this.skipInitialLoad = skipInitialLoad;
-		this.resubOpts = resubOpts;
-		this.includeIdle = includeIdle || false;
-		this.decodeFn = decodeFn;
-		this.additionalFilters = additionalFilters;
-	}
-
-	/** Starts the websocket program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
-	public async subscribe(): Promise<void> {
-		if (!this.subscriber) {
-			const filters = [getUserFilter()];
-			if (!this.includeIdle) {
-				filters.push(getNonIdleUserFilter());
-			}
-			if (this.additionalFilters) {
-				filters.push(...this.additionalFilters);
-			}
-			this.subscriber = new WebSocketProgramAccountSubscriber<UserAccount>(
-				'UserMap',
-				'user',
-				this.userMap.velocityClient.program,
-				this.decodeFn,
-				{
-					filters,
-					commitment: this.commitment,
-				},
-				this.resubOpts
-			);
-		}
-
-		await this.subscriber.subscribe(
-			(accountId: PublicKey, account: UserAccount, context: Context) => {
-				const userKey = accountId.toBase58();
-				this.userMap.updateUserAccount(userKey, account, context.slot);
-			}
-		);
-
-		if (!this.skipInitialLoad) {
-			await this.userMap.sync();
-		}
-	}
-
-	public async unsubscribe(): Promise<void> {
-		if (!this.subscriber) return;
-		await this.subscriber.unsubscribe();
-		this.subscriber = undefined;
-	}
-}

package/src/userMap/grpcSubscription.ts

@@ -1,93 +0,0 @@
-import { UserMap } from './userMap';
-import { getNonIdleUserFilter, getUserFilter } from '../memcmp';
-import { WebSocketProgramAccountSubscriber } from '../accounts/webSocketProgramAccountSubscriber';
-import { UserAccount } from '../types';
-import { Context, MemcmpFilter, PublicKey } from '@solana/web3.js';
-import { GrpcConfigs, ResubOpts } from '../accounts/types';
-import { grpcProgramAccountSubscriber } from '../accounts/grpcProgramAccountSubscriber';
-
-/**
- * `UserMap`'s `'grpc'` subscription strategy: mirrors `WebsocketSubscription`
- * but subscribes via a Geyser gRPC stream (`grpcProgramAccountSubscriber`)
- * using the same memcmp filter set, feeding updates into
- * `userMap.updateUserAccount`. Internal to `UserMap` — not part of the SDK's
- * public exports.
- */
-export class grpcSubscription {
-	private grpcConfigs: GrpcConfigs;
-	private userMap: UserMap;
-	private skipInitialLoad: boolean;
-	private resubOpts?: ResubOpts;
-	private includeIdle?: boolean;
-	private additionalFilters?: MemcmpFilter[];
-	private decodeFn: (name: string, data: Buffer) => UserAccount;
-
-	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
-
-	constructor({
-		grpcConfigs,
-		userMap,
-		skipInitialLoad = false,
-		resubOpts,
-		includeIdle = false,
-		decodeFn,
-		additionalFilters = undefined,
-	}: {
-		grpcConfigs: GrpcConfigs;
-		userMap: UserMap;
-		skipInitialLoad?: boolean;
-		resubOpts?: ResubOpts;
-		includeIdle?: boolean;
-		decodeFn: (name: string, data: Buffer) => UserAccount;
-		additionalFilters?: MemcmpFilter[];
-	}) {
-		this.userMap = userMap;
-		this.skipInitialLoad = skipInitialLoad;
-		this.resubOpts = resubOpts;
-		this.includeIdle = includeIdle || false;
-		this.decodeFn = decodeFn;
-		this.grpcConfigs = grpcConfigs;
-		this.additionalFilters = additionalFilters;
-	}
-
-	/** Starts the gRPC program-account subscription, then (unless `skipInitialLoad`) runs an initial full `userMap.sync()`. */
-	public async subscribe(): Promise<void> {
-		if (!this.subscriber) {
-			const filters = [getUserFilter()];
-			if (!this.includeIdle) {
-				filters.push(getNonIdleUserFilter());
-			}
-			if (this.additionalFilters) {
-				filters.push(...this.additionalFilters);
-			}
-			this.subscriber = await grpcProgramAccountSubscriber.create<UserAccount>(
-				this.grpcConfigs,
-				'UserMap',
-				'user',
-				this.userMap.velocityClient.program,
-				this.decodeFn,
-				{
-					filters,
-				},
-				this.resubOpts
-			);
-		}
-
-		await this.subscriber.subscribe(
-			(accountId: PublicKey, account: UserAccount, context: Context) => {
-				const userKey = accountId.toBase58();
-				this.userMap.updateUserAccount(userKey, account, context.slot);
-			}
-		);
-
-		if (!this.skipInitialLoad) {
-			await this.userMap.sync();
-		}
-	}
-
-	public async unsubscribe(): Promise<void> {
-		if (!this.subscriber) return;
-		await this.subscriber.unsubscribe();
-		this.subscriber = undefined;
-	}
-}

package/src/userMap/referrerMap.ts

@@ -1,360 +0,0 @@
-import {
-	MemcmpFilter,
-	PublicKey,
-	RpcResponseAndContext,
-} from '@solana/web3.js';
-import { VelocityClient } from '../velocityClient';
-import { ReferrerInfo } from '../types';
-import {
-	getUserAccountPublicKeySync,
-	getUserStatsAccountPublicKey,
-} from '../addresses/pda';
-import {
-	getUserStatsFilter,
-	getUserStatsIsReferredFilter,
-	getUserStatsIsReferredOrReferrerFilter,
-} from '../memcmp';
-import { isBuilderReferral } from '../math/builder';
-import bs58 from 'bs58';
-
-const DEFAULT_PUBLIC_KEY = PublicKey.default.toBase58();
-// Byte offset of `UserStats.referrer_status` (u8). Matches the memcmp filters.
-const REFERRER_STATUS_OFFSET = 188;
-
-/**
- * In-memory cache mapping each trading authority to their referrer, built by
- * scanning `UserStats` accounts with memcmp filters on the referrer-status
- * byte (see `syncAll`/`syncReferrer`) rather than subscribing to every
- * account's full data.
- */
-export class ReferrerMap {
-	/**
-	 * map from authority pubkey to referrer pubkey.
-	 */
-	private authorityReferrerMap = new Map<string, string>();
-	/**
-	 * map from referrer pubkey to ReferrerInfo.
-	 * Will be undefined if the referrer is not in the map yet.
-	 */
-	private referrerReferrerInfoMap = new Map<string, ReferrerInfo>();
-	/**
-	 * map from authority pubkey to whether its escrow was initialized with a
-	 * referrer (the `BuilderReferral` status bit). Only populated by the lazy
-	 * full-account path (`addReferrer` / `mustGetIsBuilderReferral`) — the bulk
-	 * sync uses narrow data slices that don't cover `referrer_status`.
-	 */
-	private authorityBuilderReferralMap = new Map<string, boolean>();
-	private velocityClient: VelocityClient;
-	private parallelSync: boolean;
-
-	private fetchPromise?: Promise<void>;
-	private fetchPromiseResolver: () => void = () => {};
-
-	/**
-	 * Creates a new ReferrerMap instance.
-	 *
-	 * @param {VelocityClient} velocityClient - The VelocityClient instance.
-	 */
-	constructor(velocityClient: VelocityClient, parallelSync?: boolean) {
-		this.velocityClient = velocityClient;
-		this.parallelSync = parallelSync !== undefined ? parallelSync : true;
-	}
-
-	/**
-	 * Populates the map via a one-time `sync()` (no-op if already populated).
-	 * There is no live/push subscription here — call `sync()` again later to
-	 * pick up new referrers.
-	 */
-	public async subscribe() {
-		if (this.size() > 0) {
-			return;
-		}
-
-		await this.velocityClient.subscribe();
-		await this.sync();
-	}
-
-	/** Returns true if `authorityPublicKey` has been synced into the map (has a known referrer, even if that referrer is "none"). */
-	public has(authorityPublicKey: string): boolean {
-		return this.authorityReferrerMap.has(authorityPublicKey);
-	}
-
-	/** Alias for `getReferrer`. */
-	public get(authorityPublicKey: string): ReferrerInfo | undefined {
-		return this.getReferrer(authorityPublicKey);
-	}
-
-	/**
-	 * Records `authority`'s referrer. If `referrer` is omitted, fetches the
-	 * authority's `UserStats` account directly via RPC and reads the referrer
-	 * pubkey out of its raw bytes (offset 40..72, immediately after the
-	 * discriminator + authority fields) rather than fully decoding the account.
-	 * @throws If `referrer` is omitted and no `UserStats` account exists on chain for `authority`.
-	 */
-	public async addReferrer(authority: string, referrer?: string) {
-		if (referrer) {
-			this.authorityReferrerMap.set(authority, referrer);
-		} else if (referrer === undefined) {
-			const userStatsAccountPublicKey = getUserStatsAccountPublicKey(
-				this.velocityClient.program.programId,
-				new PublicKey(authority)
-			);
-			const accountInfo = await this.velocityClient.connection.getAccountInfo(
-				userStatsAccountPublicKey,
-				'processed'
-			);
-			if (!accountInfo) {
-				throw new Error(
-					`ReferrerMap: UserStats account not found for authority ${authority}`
-				);
-			}
-			const buffer = accountInfo.data;
-
-			this.authorityBuilderReferralMap.set(
-				authority,
-				isBuilderReferral({ referrerStatus: buffer[REFERRER_STATUS_OFFSET] })
-			);
-
-			const referrer = bs58.encode(buffer.subarray(40, 72));
-
-			this.addReferrer(authority, referrer);
-		}
-	}
-
-	/**
-	 * True when the authority's escrow was initialized with a referrer (the
-	 * `BuilderReferral` status bit). Returns `false` until the authority's
-	 * UserStats has been read via the lazy path; use {@link mustGetIsBuilderReferral}
-	 * to force a read.
-	 */
-	public isBuilderReferral(authorityPublicKey: string): boolean {
-		return this.authorityBuilderReferralMap.get(authorityPublicKey) ?? false;
-	}
-
-	/**
-	 * Like {@link isBuilderReferral} but reads the authority's UserStats from the
-	 * chain if the status hasn't been cached yet. Throws if the UserStats account
-	 * cannot be loaded (same as {@link addReferrer}).
-	 */
-	public async mustGetIsBuilderReferral(
-		authorityPublicKey: string
-	): Promise<boolean> {
-		if (!this.authorityBuilderReferralMap.has(authorityPublicKey)) {
-			await this.addReferrer(authorityPublicKey);
-		}
-		return this.isBuilderReferral(authorityPublicKey);
-	}
-
-	/**
-	 * Enforce that a UserStats will exist for the given authorityPublicKey,
-	 * reading one from the blockchain if necessary.
-	 * @param authorityPublicKey
-	 * @returns
-	 */
-	public async mustGet(
-		authorityPublicKey: string
-	): Promise<ReferrerInfo | undefined> {
-		if (!this.has(authorityPublicKey)) {
-			await this.addReferrer(authorityPublicKey);
-		}
-		return this.getReferrer(authorityPublicKey);
-	}
-
-	/**
-	 * Resolves `authorityPublicKey`'s referrer to a `ReferrerInfo` (the
-	 * referrer's `User` sub-account-0 and `UserStats` addresses), caching the
-	 * derived addresses per referrer pubkey.
-	 * @returns `undefined` if `authorityPublicKey` isn't in the map yet, or if it has no referrer (default/zero pubkey).
-	 */
-	public getReferrer(authorityPublicKey: string): ReferrerInfo | undefined {
-		const referrer = this.authorityReferrerMap.get(authorityPublicKey);
-		if (!referrer) {
-			// return undefined if the referrer is not in the map
-			return undefined;
-		}
-
-		if (referrer === DEFAULT_PUBLIC_KEY) {
-			return undefined;
-		}
-
-		if (this.referrerReferrerInfoMap.has(referrer)) {
-			return this.referrerReferrerInfoMap.get(referrer);
-		}
-
-		const referrerKey = new PublicKey(referrer);
-		const referrerInfo = {
-			referrer: getUserAccountPublicKeySync(
-				this.velocityClient.program.programId,
-				referrerKey,
-				0
-			),
-			referrerStats: getUserStatsAccountPublicKey(
-				this.velocityClient.program.programId,
-				referrerKey
-			),
-		};
-
-		this.referrerReferrerInfoMap.set(referrer, referrerInfo);
-		return referrerInfo;
-	}
-
-	/** Number of authorities synced into the map (referred or not). */
-	public size(): number {
-		return this.authorityReferrerMap.size;
-	}
-
-	/** Number of synced authorities that actually have a referrer set (excludes those with the default/zero pubkey). */
-	public numberOfReferred(): number {
-		return Array.from(this.authorityReferrerMap.values()).filter(
-			(referrer) => referrer !== DEFAULT_PUBLIC_KEY
-		).length;
-	}
-
-	/**
-	 * Fully (re)populates the map: `syncAll` seeds every `UserStats` authority
-	 * with a default ("no referrer") entry, then `syncReferrer` overwrites
-	 * entries for authorities matching the is-referred and
-	 * is-referred-or-referrer memcmp filters with their actual referrer. Runs
-	 * the three passes in parallel by default (`parallelSync`), or serially if
-	 * constructed with `parallelSync: false`. Concurrent calls share the same
-	 * in-flight promise.
-	 */
-	public async sync(): Promise<void> {
-		if (this.fetchPromise) {
-			return this.fetchPromise;
-		}
-
-		this.fetchPromise = new Promise((resolver) => {
-			this.fetchPromiseResolver = resolver;
-		});
-
-		try {
-			if (this.parallelSync) {
-				await Promise.all([
-					this.syncAll(),
-					this.syncReferrer(getUserStatsIsReferredFilter()),
-					this.syncReferrer(getUserStatsIsReferredOrReferrerFilter()),
-				]);
-			} else {
-				await this.syncAll();
-				await this.syncReferrer(getUserStatsIsReferredFilter());
-				await this.syncReferrer(getUserStatsIsReferredOrReferrerFilter());
-			}
-		} finally {
-			this.fetchPromiseResolver();
-			this.fetchPromise = undefined;
-		}
-	}
-
-	/**
-	 * Fetches every `UserStats` account pubkey (via a `getUserStatsFilter`
-	 * memcmp filter, with a zero-length `dataSlice` so no account data is
-	 * transferred) and seeds a default ("no referrer") entry for any authority
-	 * not already present in the map.
-	 */
-	public async syncAll(): Promise<void> {
-		const rpcRequestArgs = [
-			this.velocityClient.program.programId.toBase58(),
-			{
-				commitment: this.velocityClient.opts?.commitment,
-				filters: [getUserStatsFilter()],
-				encoding: 'base64',
-				dataSlice: {
-					offset: 0,
-					length: 0,
-				},
-				withContext: true,
-			},
-		];
-
-		const rpcJSONResponse: any =
-			// @ts-ignore
-			await this.velocityClient.connection._rpcRequest(
-				'getProgramAccounts',
-				rpcRequestArgs
-			);
-
-		const rpcResponseAndContext: RpcResponseAndContext<
-			Array<{
-				pubkey: string;
-				account: {
-					data: [string, string];
-				};
-			}>
-		> = rpcJSONResponse.result;
-
-		for (const account of rpcResponseAndContext.value) {
-			// only add if it isn't already in the map
-			// so that if syncReferrer already set it, we dont overwrite
-			if (!this.has(account.pubkey)) {
-				this.addReferrer(account.pubkey, DEFAULT_PUBLIC_KEY);
-			}
-		}
-	}
-
-	/**
-	 * Fetches `UserStats` accounts matching `referrerFilter` combined with the
-	 * base `UserStats` discriminator filter, with a `dataSlice` of exactly the
-	 * bytes needed (offset 0, length 72 — discriminator + authority + referrer)
-	 * to avoid transferring full account data. Decodes `authority`/`referrer`
-	 * directly from the byte offsets and unconditionally sets them in the map
-	 * (in batches of 1000, yielding to the event loop between batches).
-	 * @param referrerFilter A memcmp filter selecting which referrer-status accounts to sync, e.g. from `getUserStatsIsReferredFilter`/`getUserStatsIsReferredOrReferrerFilter`.
-	 */
-	async syncReferrer(referrerFilter: MemcmpFilter): Promise<void> {
-		const rpcRequestArgs = [
-			this.velocityClient.program.programId.toBase58(),
-			{
-				commitment: this.velocityClient.opts?.commitment,
-				filters: [getUserStatsFilter(), referrerFilter],
-				encoding: 'base64',
-				dataSlice: {
-					offset: 0,
-					length: 72,
-				},
-				withContext: true,
-			},
-		];
-
-		const rpcJSONResponse: any =
-			// @ts-ignore
-			await this.velocityClient.connection._rpcRequest(
-				'getProgramAccounts',
-				rpcRequestArgs
-			);
-
-		const rpcResponseAndContext: RpcResponseAndContext<
-			Array<{
-				pubkey: string;
-				account: {
-					data: [string, string];
-				};
-			}>
-		> = rpcJSONResponse.result;
-
-		const batchSize = 1000;
-		for (let i = 0; i < rpcResponseAndContext.value.length; i += batchSize) {
-			const batch = rpcResponseAndContext.value.slice(i, i + batchSize);
-			await Promise.all(
-				batch.map(async (programAccount) => {
-					// @ts-ignore
-					const buffer = Buffer.from(
-						programAccount.account.data[0],
-						programAccount.account.data[1] as BufferEncoding
-					);
-					const authority = bs58.encode(buffer.subarray(8, 40));
-					const referrer = bs58.encode(buffer.subarray(40, 72));
-
-					this.addReferrer(authority, referrer);
-				})
-			);
-			await new Promise((resolve) => setTimeout(resolve, 0));
-		}
-	}
-
-	/** Clears the in-memory maps. Does not tear down any RPC subscriptions (this class has none — `subscribe` only triggers a one-time sync). */
-	public async unsubscribe() {
-		this.authorityReferrerMap.clear();
-		this.referrerReferrerInfoMap.clear();
-	}
-}