@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/userMap/userMapConfig.ts

@@ -2,28 +2,37 @@ import { Commitment, Connection, MemcmpFilter } from '@solana/web3.js';
 import { VelocityClient } from '../velocityClient';
 import { GrpcConfigs } from '../accounts/types';
 
-// passed into UserMap.getUniqueAuthorities to filter users
+/** Passed into `UserMap.getUniqueAuthorities` to filter which users' authorities are returned. */
 export type UserAccountFilterCriteria = {
-	// only return users that have open orders
+	/** Only return users that have `hasOpenOrder` set on their `UserAccount`. */
 	hasOpenOrders: boolean;
 };
 
+/**
+ * Selects how `UserMap`/`UserStatsMap` bulk-load accounts on sync.
+ * - `'default'`: a single `getProgramAccounts` call with server-side memcmp filters. Simple, but can hit RPC/node response-size limits when there are many accounts.
+ * - `'paginated'`: a filtered `getProgramAccounts` prefetch for just the pubkeys, followed by chunked `getMultipleAccountsInfoAndContext` calls with bounded concurrency. More RPC calls, but scales to large account counts.
+ */
 export type SyncConfig =
 	| {
 			type: 'default';
 	  }
 	| {
 			type: 'paginated';
+			/** Number of accounts fetched per `getMultipleAccountsInfoAndContext` call. Defaults to 100. */
 			chunkSize?: number;
+			/** Max number of chunk-fetch tasks in flight at once. Defaults to 10. */
 			concurrencyLimit?: number;
 	  };
 
 type UserMapConfigBase = {
-	// connection object to use specifically for the UserMap. If undefined, will use the velocityClient's connection
+	/** Connection to use specifically for this map. If omitted, uses the `VelocityClient`'s connection. */
 	connection?: Connection;
+	/** How the map keeps its accounts up to date after the initial sync. */
 	subscriptionConfig:
 		| {
 				type: 'polling';
+				/** Milliseconds between full re-syncs. */
 				frequency: number;
 				commitment?: Commitment;
 		  }
@@ -40,27 +49,31 @@ type UserMapConfigBase = {
 				commitment?: Commitment;
 		  };
 
-	// True to skip the initial load of userAccounts via getProgramAccounts
+	/** True to skip the initial load of userAccounts via getProgramAccounts */
 	skipInitialLoad?: boolean;
 
-	// True to include idle users when loading. Defaults to false to decrease # of accounts subscribed to.
+	/** True to include idle users when loading. Defaults to false to decrease # of accounts subscribed to. */
 	includeIdle?: boolean;
 
-	// Whether to skip loading available perp/spot positions and open orders
+	/** Whether to skip loading available perp/spot positions and open orders */
 	fastDecode?: boolean;
 
-	// If true, will not do a full sync whenever StateAccount.numberOfSubAccounts changes.
-	// default behavior is to do a full sync on changes.
+	/**
+	 * If true, will not do a full sync whenever StateAccount.numberOfSubAccounts changes.
+	 * default behavior is to do a full sync on changes.
+	 */
 	disableSyncOnTotalAccountsChange?: boolean;
 
+	/** Bulk-load strategy for the initial sync and subsequent full syncs. Defaults to `{ type: 'default' }`. */
 	syncConfig?: SyncConfig;
 
-	// Whether to throw an error if the userMap fails to sync. Defaults to true.
+	/** Whether to throw an error if the userMap fails to sync. Defaults to false (errors are logged, not thrown). */
 	throwOnFailedSync?: boolean;
 
-	// Whether to filter users by poolId. Defaults to false (all users).
+	/** Whether to filter users by poolId. Defaults to undefined (all users, all pools). */
 	filterByPoolId?: number;
 
+	/** Extra memcmp filters ANDed onto the base `User`-account filter (and, unless `includeIdle`, the non-idle filter) for both the initial sync and the live subscription. */
 	additionalFilters?: MemcmpFilter[];
 };
 

package/src/userMap/userStatsMap.ts

@@ -21,6 +21,12 @@ import { PublicKey } from '@solana/web3.js';
 
 import { UserMap } from './userMap';
 
+/**
+ * In-memory cache of `UserStats` accounts (one per trading authority, shared
+ * across that authority's sub-accounts), keyed by authority pubkey. Backed by
+ * a shared `BulkAccountLoader` for the default sync strategy so many
+ * `UserStats` can be fetched/polled together instead of one subscription each.
+ */
 export class UserStatsMap {
 	/**
 	 * map from authority pubkey to UserStats
@@ -66,6 +72,7 @@ export class UserStatsMap {
 		);
 	}
 
+	/** Populates the map for `authorities` via `sync()` (no-op if the map already has entries). */
 	public async subscribe(authorities: PublicKey[]) {
 		if (this.size() > 0) {
 			return;
@@ -108,6 +115,7 @@ export class UserStatsMap {
 		this.userStatsMap.set(authority.toString(), userStat);
 	}
 
+	/** Ensures the `UserStats` entry exists for the authority behind `record.user` (looked up/created in `userMap` first), adding it if this map doesn't have it yet. */
 	public async updateWithOrderRecord(record: OrderRecord, userMap: UserMap) {
 		const user = await userMap.mustGet(record.user.toString());
 		if (!this.has(user.getUserAccountOrThrow().authority.toString())) {
@@ -119,6 +127,15 @@ export class UserStatsMap {
 		}
 	}
 
+	/**
+	 * Incrementally updates the map in response to a single program event,
+	 * ensuring a `UserStats` entry exists for every authority the event
+	 * references (deposit/funding/new-user/IF-stake records reference an
+	 * authority directly; order/liquidation/settle-pnl/order-action records
+	 * reference a `User` account and require `userMap` to resolve its authority).
+	 * Events whose required `userMap` is not supplied, or whose type isn't
+	 * recognized, are silently ignored.
+	 */
 	public async updateWithEventRecord(
 		record: WrappedEvent<any>,
 		userMap?: UserMap
@@ -181,10 +198,12 @@ export class UserStatsMap {
 		}
 	}
 
+	/** Returns true if `authorityPublicKey` has a `UserStats` cached in the map. */
 	public has(authorityPublicKey: string): boolean {
 		return this.userStatsMap.has(authorityPublicKey);
 	}
 
+	/** Returns the cached `UserStats` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
 	public get(authorityPublicKey: string): UserStats | undefined {
 		return this.userStatsMap.get(authorityPublicKey);
 	}
@@ -212,10 +231,12 @@ export class UserStatsMap {
 		return userStats;
 	}
 
+	/** Iterates all cached `UserStats` instances. */
 	public values(): IterableIterator<UserStats> {
 		return this.userStatsMap.values();
 	}
 
+	/** Number of authorities currently cached in the map. */
 	public size(): number {
 		return this.userStatsMap.size;
 	}
@@ -362,6 +383,7 @@ export class UserStatsMap {
 		}
 	}
 
+	/** Unsubscribes and removes every cached `UserStats` from the map. */
 	public async unsubscribe() {
 		for (const [key, userStats] of this.userStatsMap.entries()) {
 			await userStats.unsubscribe();

package/src/userName.ts

@@ -1,8 +1,19 @@
+/** Maximum length, in characters/bytes, of a `User`/`SpotMarket`/`PerpMarket` name field on-chain. */
 export const MAX_NAME_LENGTH = 32;
 
+/** Default name assigned to a user's first sub-account (id 0) when none is supplied. */
 export const DEFAULT_USER_NAME = 'Main Account';
+/** Default name used for a market when no explicit name is configured. */
 export const DEFAULT_MARKET_NAME = 'Default Market Name';
 
+/**
+ * Encodes a name into the fixed 32-byte, space-padded on-chain representation used by `User`,
+ * `PerpMarket`, and `SpotMarket` name fields.
+ * @param name - Name to encode; must be at most `MAX_NAME_LENGTH` (32) characters.
+ * @returns A 32-element array of bytes: the UTF-8 encoding of `name` followed by space (`0x20`)
+ * padding to fill the remaining length.
+ * @throws Error if `name` is longer than `MAX_NAME_LENGTH`.
+ */
 export function encodeName(name: string): number[] {
 	if (name.length > MAX_NAME_LENGTH) {
 		throw Error(`Name (${name}) longer than 32 characters`);
@@ -15,6 +26,11 @@ export function encodeName(name: string): number[] {
 	return Array(...buffer);
 }
 
+/**
+ * Decodes a fixed 32-byte on-chain name field back into a trimmed string, reversing `encodeName`.
+ * @param bytes - The raw 32-byte name field as read from an account.
+ * @returns The name with trailing (and leading) whitespace padding removed.
+ */
 export function decodeName(bytes: number[]): string {
 	const buffer = Buffer.from(bytes);
 	return buffer.toString('utf8').trim();

package/src/userStats.ts

@@ -65,6 +65,11 @@ export class UserStats {
 		}
 	}
 
+	/**
+	 * Subscribes to this authority's `UserStats` account.
+	 * @param userStatsAccount Optional pre-fetched account to seed the subscriber with, skipping the initial RPC fetch.
+	 * @returns True once the underlying subscriber reports subscribed.
+	 */
 	public async subscribe(
 		userStatsAccount?: UserStatsAccount
 	): Promise<boolean> {
@@ -74,25 +79,35 @@ export class UserStats {
 		return this.isSubscribed;
 	}
 
+	/** Forces the account subscriber to re-fetch the `UserStats` account from RPC. */
 	public async fetchAccounts(): Promise<void> {
 		await this.accountSubscriber.fetch();
 	}
 
+	/** Tears down the `UserStats` account subscription. */
 	public async unsubscribe(): Promise<void> {
 		await this.accountSubscriber.unsubscribe();
 		this.isSubscribed = false;
 	}
 
+	/** Like `getAccount`, but also returns the slot at which the account was last observed. Same `undefined`-when-not-found contract. */
 	public getAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined {
 		return this.accountSubscriber.getUserStatsAccountAndSlot();
 	}
 
+	/**
+	 * Returns the cached `UserStats` account, or `undefined` if it has not been
+	 * loaded yet (e.g. `subscribe()` has not resolved, or the account does not
+	 * exist on chain). Unlike `User.getUserAccount`, this does not throw
+	 * `NotSubscribedError` when called before subscribing — it simply returns
+	 * `undefined` from the subscriber's initial (empty) state.
+	 */
 	public getAccount(): UserStatsAccount | undefined {
 		return this.accountSubscriber.getUserStatsAccountAndSlot()?.data;
 	}
 
 	/**
-	 * Like {@link getAccount} but throws a named error instead of returning
+	 * Like `getAccount` but throws a named error instead of returning
 	 * `undefined` when the stats account has not been loaded yet.
 	 */
 	public getAccountOrThrow(): UserStatsAccount {
@@ -103,6 +118,11 @@ export class UserStats {
 		return account;
 	}
 
+	/**
+	 * Returns the addresses of this user's referrer's `User` (sub-account 0)
+	 * and `UserStats` accounts, or `undefined` if the account is not loaded or
+	 * has no referrer set (`referrer` is the default/zero pubkey).
+	 */
 	public getReferrerInfo(): ReferrerInfo | undefined {
 		const account = this.getAccount();
 		if (!account || account.referrer.equals(PublicKey.default)) {
@@ -122,6 +142,13 @@ export class UserStats {
 		}
 	}
 
+	/**
+	 * Returns the earliest of the account's three rolling-30-day activity
+	 * timestamps (filler, maker, taker volume), i.e. the oldest evidence of
+	 * account activity — used to estimate account age for deletion-eligibility
+	 * checks (see `User.canBeDeleted`).
+	 * @returns Unix timestamp in seconds.
+	 */
 	public static getOldestActionTs(account: UserStatsAccount): number {
 		return Math.min(
 			account.lastFillerVolume30DTs.toNumber(),

package/src/util/TransactionConfirmationManager.ts

@@ -51,6 +51,21 @@ export class TransactionConfirmationManager {
 		this.connection = connection;
 	}
 
+	/**
+	 * Waits for a transaction to reach `desiredConfirmationStatus` using a `connection.onSignature`
+	 * websocket subscription, racing it against a one-shot `getSignatureStatuses` check (in case
+	 * the transaction already confirmed before the subscription was established) and a timeout.
+	 * The websocket listener is always removed before returning/throwing.
+	 * @param txSig - Transaction signature to confirm.
+	 * @param timeout - Milliseconds to wait before giving up; defaults to 30000 (30s).
+	 * @param desiredConfirmationStatus - Confirmation level to wait for (`'processed'` <
+	 * `'confirmed'` < `'finalized'`); defaults to `DEFAULT_CONFIRMATION_OPTS.commitment` (`'confirmed'`).
+	 * @returns The RPC response once `txSig` reaches (or exceeds) `desiredConfirmationStatus`.
+	 * @throws Error via `throwTransactionError` if the one-shot status check finds the transaction
+	 * already failed on-chain; `TxSendError` (code `NOT_CONFIRMED_ERROR_CODE`) if neither the
+	 * one-shot check nor the websocket confirms it within `timeout` — in that case the transaction's
+	 * actual outcome is unknown, not necessarily failed.
+	 */
 	async confirmTransactionWebSocket(
 		txSig: string,
 		timeout = 30000,
@@ -157,6 +172,24 @@ export class TransactionConfirmationManager {
 		return response;
 	}
 
+	/**
+	 * Waits for a transaction to reach `desiredConfirmationStatus` by polling
+	 * `getSignatureStatuses` on a shared 100ms tick (see class doc) rather than a
+	 * per-transaction interval — this call registers `txSig` and starts the shared loop if it
+	 * isn't already running.
+	 * @param txSig - Transaction signature to confirm.
+	 * @param desiredConfirmationStatus - Confirmation level to wait for; defaults to
+	 * `DEFAULT_CONFIRMATION_OPTS.commitment` (`'confirmed'`).
+	 * @param timeout - Milliseconds to wait before rejecting; defaults to 30000 (30s).
+	 * @param pollInterval - How often (ms) to actually check this transaction's status against the
+	 * shared 100ms tick; must be at least 400 and a multiple of 100. Defaults to 1000 (1s).
+	 * @param searchTransactionHistory - Whether to also search already-purged ledger history for
+	 * this signature (passed to `getSignatureStatuses`); defaults to `false`. If any transaction
+	 * batched into the same poll round requests this, the whole batch's RPC call requests it.
+	 * @returns The `SignatureStatus` once `txSig` reaches (or exceeds) `desiredConfirmationStatus`.
+	 * @throws Error if `pollInterval` is invalid, if the poll times out, or if the transaction is
+	 * found to have failed on-chain (rejected with the resolved transaction error).
+	 */
 	async confirmTransactionPolling(
 		txSig: string,
 		desiredConfirmationStatus = DEFAULT_CONFIRMATION_OPTS.commitment as TransactionConfirmationStatus,

package/src/util/chainClock.ts

@@ -1,22 +1,34 @@
 import { Commitment } from '@solana/web3.js';
 
+/** Last-known chain progress at a given commitment level: block height, slot, and unix timestamp (seconds). Any field may be absent if never observed. */
 export type ChainClockProgress = {
 	blockHeight?: number;
 	slot?: number;
 	ts?: number;
 };
 
+/** A `ChainClockProgress` update tagged with the commitment level it was observed at. */
 export type ChainClockUpdateProps = {
 	commitment: Commitment;
 } & ChainClockProgress;
 
+/** Internal state map: one `ChainClockProgress` per `Commitment` level. */
 export type ChainClockState = Map<Commitment, ChainClockProgress>;
 
+/** Initial per-commitment progress values to seed a `ChainClock` with. */
 export type ChainClickInitialisationProps = ChainClockUpdateProps[];
 
+/**
+ * Tracks the most recently observed block height/slot/timestamp per commitment level, so callers
+ * (e.g. tx senders deciding whether a blockhash has expired) can read the latest known chain
+ * progress without an RPC round-trip.
+ */
 export class ChainClock {
 	private _state: ChainClockState;
 
+	/**
+	 * @param props - Initial progress values, one entry per commitment level to track.
+	 */
 	constructor(props: ChainClickInitialisationProps) {
 		this._state = new Map<Commitment, ChainClockUpdateProps>();
 		props.forEach((prop) => {
@@ -24,6 +36,13 @@ export class ChainClock {
 		});
 	}
 
+	/**
+	 * Merges a new observation into the tracked state for `props.commitment`. Only fields present
+	 * on `props` are updated (falsy/omitted `blockHeight`/`slot`/`ts` leave the existing stored
+	 * value untouched, including `0` being treated as absent); the commitment level is created if
+	 * not already tracked.
+	 * @param props - New progress observation, tagged with its commitment level.
+	 */
 	update(props: ChainClockUpdateProps): void {
 		const state = this._state.get(props.commitment);
 		if (state) {
@@ -35,6 +54,11 @@ export class ChainClock {
 		}
 	}
 
+	/**
+	 * Reads the last-known progress at a commitment level.
+	 * @param commitment - Commitment level to read.
+	 * @returns The tracked `ChainClockProgress`, or `undefined` if nothing has been observed yet at that level.
+	 */
 	public getState(commitment: Commitment): ChainClockProgress | undefined {
 		return this._state.get(commitment);
 	}

package/src/util/computeUnits.ts

@@ -6,6 +6,19 @@ import {
 	TransactionInstruction,
 } from '@solana/web3.js';
 
+/**
+ * Fetches a confirmed transaction and extracts, from its log messages, every "consumed compute
+ * units" line attributable to `programId`. A transaction can invoke the same program more than
+ * once (e.g. via CPI or multiple instructions), so this returns one entry per matching log line
+ * rather than a single total.
+ * @param programId - Program whose compute-unit consumption to extract.
+ * @param connection - RPC connection used to fetch the transaction.
+ * @param txSignature - Signature of the transaction to inspect.
+ * @param commitment - Finality level to fetch the transaction at; defaults to `'confirmed'`.
+ * @returns The consumed-compute-unit counts (as strings, parsed straight from the log text) for
+ * each invocation of `programId` found in the transaction's logs; empty if the transaction has no
+ * log messages (e.g. not yet available at the requested commitment).
+ */
 export async function findComputeUnitConsumption(
 	programId: PublicKey,
 	connection: Connection,
@@ -30,6 +43,12 @@ export async function findComputeUnitConsumption(
 	return computeUnits;
 }
 
+/**
+ * Checks whether `ix` is a `ComputeBudgetProgram.setComputeUnitLimit` instruction, by matching
+ * the program id and the instruction discriminator byte (`2`).
+ * @param ix - Instruction to check.
+ * @returns `true` if `ix` sets the transaction's compute unit limit.
+ */
 export function isSetComputeUnitsIx(ix: TransactionInstruction): boolean {
 	// Compute budget program discriminator is first byte
 	// 2: set compute unit limit
@@ -44,6 +63,12 @@ export function isSetComputeUnitsIx(ix: TransactionInstruction): boolean {
 	return false;
 }
 
+/**
+ * Checks whether `ix` is a `ComputeBudgetProgram.setComputeUnitPrice` instruction, by matching
+ * the program id and the instruction discriminator byte (`3`).
+ * @param ix - Instruction to check.
+ * @returns `true` if `ix` sets the transaction's compute unit price (priority fee).
+ */
 export function isSetComputeUnitPriceIx(ix: TransactionInstruction): boolean {
 	// Compute budget program discriminator is first byte
 	// 2: set compute unit limit
@@ -58,6 +83,13 @@ export function isSetComputeUnitPriceIx(ix: TransactionInstruction): boolean {
 	return false;
 }
 
+/**
+ * Checks a list of instructions for the presence of compute-budget limit/price instructions —
+ * used by tx builders to avoid appending a duplicate `setComputeUnitLimit`/`setComputeUnitPrice`
+ * instruction when the caller already supplied one.
+ * @param ixs - Instructions to scan (typically an in-progress transaction's instruction list).
+ * @returns Whether a `setComputeUnitLimit` and/or `setComputeUnitPrice` instruction is present.
+ */
 export function containsComputeUnitIxs(ixs: TransactionInstruction[]): {
 	hasSetComputeUnitLimitIx: boolean;
 	hasSetComputeUnitPriceIx: boolean;

package/src/util/digest.ts

@@ -1,16 +1,33 @@
 import { createHash } from 'crypto';
 import { nanoid } from 'nanoid';
 
+/**
+ * Computes the raw SHA-256 digest of arbitrary data.
+ * @param data - Bytes to hash.
+ * @returns The 32-byte SHA-256 digest.
+ */
 export function digest(data: Buffer): Buffer {
 	const hash = createHash('sha256');
 	hash.update(data);
 	return hash.digest();
 }
 
+/**
+ * Computes a base64-encoded SHA-256 digest of a signature, used as a compact, collision-resistant
+ * dedup/lookup key for signed messages (e.g. swift/signed-message orders) without storing the full
+ * signature.
+ * @param signature - Raw signature bytes to hash.
+ * @returns The base64-encoded SHA-256 digest.
+ */
 export function digestSignature(signature: Uint8Array): string {
 	return createHash('sha256').update(signature).digest('base64');
 }
 
+/**
+ * Generates a random 8-character uuid for tagging a signed-message (swift) order, matching the
+ * `uuid: Uint8Array` field expected on-chain/by the swift server.
+ * @returns 8 raw bytes (the ASCII/UTF-8 encoding of an 8-character nanoid string).
+ */
 export function generateSignedMsgUuid(): Uint8Array {
 	return Uint8Array.from(Buffer.from(nanoid(8)));
 }

package/src/util/ed25519Utils.ts

@@ -36,12 +36,22 @@ const ED25519_INSTRUCTION_LAYOUT = BufferLayout.struct<
 ]);
 
 /**
- * Constructs a minimal Ed25519 verification instruction that references the data
- * inside the velocity custom instruction (e.g. postPythLazerOracleUpdate, placeSignedMsgTakerOrder).
+ * Constructs a minimal Ed25519 verification instruction that, instead of embedding its own copy
+ * of the signature/pubkey/message, points its offsets at data already present inside another
+ * instruction in the same transaction (e.g. `postPythLazerOracleUpdate`, `placeSignedMsgTakerOrder`).
+ * This lets the native ed25519 program verify a signature the velocity program also needs to read,
+ * without duplicating the signed payload in the transaction (which would blow the size limit for
+ * larger payloads like Lazer updates). The Solana runtime requires this ed25519 verify instruction
+ * to be a sibling instruction (not a CPI) executed before the instruction that relies on it.
  *
  * @param customInstructionIndex The index of the custom instruction in the transaction (e.g. if tx contains compute budget limit, compute budget price, ed25519 verify, custom ix, this would be 3).
  * @param messageOffset The offset within the custom instruction data where the signed message begins.
  * @param customInstructionData The entire instruction data array for the custom instruction.
+ * @param magicLen Length, in bytes, of a "magic"/tag prefix between `messageOffset` and the
+ * start of the 64-byte signature; defaults to `MAGIC_LEN` (4) if omitted.
+ * @returns A `TransactionInstruction` targeting `Ed25519Program` with no accounts, whose data
+ * encodes offsets (not copies) of the signature/pubkey/message living inside the referenced
+ * custom instruction.
  */
 export function createMinimalEd25519VerifyIx(
 	customInstructionIndex: number,

package/src/util/promiseTimeout.ts

@@ -1,3 +1,12 @@
+/**
+ * Races `promise` against a timer, resolving to `null` instead of rejecting/hanging if `promise`
+ * doesn't settle within `timeoutMs`. `promise` itself is not cancelled — it keeps running in the
+ * background and its eventual result/rejection is discarded once the race is decided.
+ * @param promise - The promise to await.
+ * @param timeoutMs - Timeout in milliseconds.
+ * @returns `promise`'s resolved value, or `null` if it didn't settle before `timeoutMs` elapsed.
+ * Rejects if `promise` rejects before the timeout.
+ */
 export function promiseTimeout<T>(
 	promise: Promise<T>,
 	timeoutMs: number