@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/node/wallet.d.ts

@@ -1,17 +1,54 @@
 import { Keypair, PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
 import { IWallet, IVersionedWallet } from './types';
+/**
+ * Local-keypair implementation of `IWallet`/`IVersionedWallet` that signs directly with an
+ * in-memory `Keypair` (no external wallet/RPC round-trip). Suitable for keeper bots, scripts, and
+ * tests; not for browser dapps holding user funds.
+ */
 export declare class Wallet implements IWallet, IVersionedWallet {
     readonly payer: Keypair;
     constructor(payer: Keypair);
+    /**
+     * Partially signs a legacy `Transaction` with this wallet's keypair, leaving any other
+     * required signatures untouched.
+     * @param tx - Transaction to sign; mutated in place.
+     * @returns The same transaction instance, now signed by `payer`.
+     */
     signTransaction(tx: Transaction): Promise<Transaction>;
+    /**
+     * Signs a `VersionedTransaction` with this wallet's keypair.
+     * @param tx - Transaction to sign; mutated in place.
+     * @returns The same transaction instance, now signed by `payer`.
+     */
     signVersionedTransaction(tx: VersionedTransaction): Promise<VersionedTransaction>;
+    /**
+     * Partially signs a batch of legacy `Transaction`s with this wallet's keypair.
+     * @param txs - Transactions to sign; each is mutated in place.
+     * @returns The same transaction instances, now signed by `payer`.
+     */
     signAllTransactions(txs: Transaction[]): Promise<Transaction[]>;
+    /**
+     * Signs a batch of `VersionedTransaction`s with this wallet's keypair.
+     * @param txs - Transactions to sign; each is mutated in place.
+     * @returns The same transaction instances, now signed by `payer`.
+     */
     signAllVersionedTransactions(txs: VersionedTransaction[]): Promise<VersionedTransaction[]>;
+    /** The wallet's public key, i.e. `payer.publicKey`. */
     get publicKey(): PublicKey;
 }
+/**
+ * `Wallet` variant that additionally supports raw message signing (`signMessage`), needed for
+ * flows like swift/signed-message orders that sign an ed25519 payload outside of a transaction.
+ */
 export declare class WalletV2 extends Wallet {
     readonly payer: Keypair;
     constructor(payer: Keypair);
+    /**
+     * Signs an arbitrary message with this wallet's ed25519 secret key (detached signature, not a
+     * transaction).
+     * @param message - Raw bytes to sign.
+     * @returns The 64-byte detached ed25519 signature.
+     */
     signMessage(message: Uint8Array): Promise<Uint8Array>;
 }
 //# sourceMappingURL=wallet.d.ts.map

package/lib/node/wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,OAAO,EACP,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGpD,qBAAa,MAAO,YAAW,OAAO,EAAE,gBAAgB;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;IAE7B,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAKtD,wBAAwB,CAC7B,EAAE,EAAE,oBAAoB,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAK1B,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAO/D,4BAA4B,CACjC,GAAG,EAAE,oBAAoB,EAAE,GACzB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAOlC,IAAI,SAAS,IAAI,SAAS,CAEzB;CACD;AAED,qBAAa,QAAS,SAAQ,MAAM;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;IAI7B,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAG3D"}
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,OAAO,EACP,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGpD;;;;GAIG;AACH,qBAAa,MAAO,YAAW,OAAO,EAAE,gBAAgB;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;IAEnC;;;;;OAKG;IACG,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAK5D;;;;OAIG;IACG,wBAAwB,CAC7B,EAAE,EAAE,oBAAoB,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAKhC;;;;OAIG;IACG,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOrE;;;;OAIG;IACG,4BAA4B,CACjC,GAAG,EAAE,oBAAoB,EAAE,GACzB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAOlC,uDAAuD;IACvD,IAAI,SAAS,IAAI,SAAS,CAEzB;CACD;AAED;;;GAGG;AACH,qBAAa,QAAS,SAAQ,MAAM;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;IAInC;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAG3D"}

package/lib/node/wallet.js

@@ -5,40 +5,77 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WalletV2 = exports.Wallet = void 0;
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
+/**
+ * Local-keypair implementation of `IWallet`/`IVersionedWallet` that signs directly with an
+ * in-memory `Keypair` (no external wallet/RPC round-trip). Suitable for keeper bots, scripts, and
+ * tests; not for browser dapps holding user funds.
+ */
 class Wallet {
     constructor(payer) {
         this.payer = payer;
     }
+    /**
+     * Partially signs a legacy `Transaction` with this wallet's keypair, leaving any other
+     * required signatures untouched.
+     * @param tx - Transaction to sign; mutated in place.
+     * @returns The same transaction instance, now signed by `payer`.
+     */
     async signTransaction(tx) {
         tx.partialSign(this.payer);
         return tx;
     }
+    /**
+     * Signs a `VersionedTransaction` with this wallet's keypair.
+     * @param tx - Transaction to sign; mutated in place.
+     * @returns The same transaction instance, now signed by `payer`.
+     */
     async signVersionedTransaction(tx) {
         tx.sign([this.payer]);
         return tx;
     }
+    /**
+     * Partially signs a batch of legacy `Transaction`s with this wallet's keypair.
+     * @param txs - Transactions to sign; each is mutated in place.
+     * @returns The same transaction instances, now signed by `payer`.
+     */
     async signAllTransactions(txs) {
         return txs.map((t) => {
             t.partialSign(this.payer);
             return t;
         });
     }
+    /**
+     * Signs a batch of `VersionedTransaction`s with this wallet's keypair.
+     * @param txs - Transactions to sign; each is mutated in place.
+     * @returns The same transaction instances, now signed by `payer`.
+     */
     async signAllVersionedTransactions(txs) {
         return txs.map((t) => {
             t.sign([this.payer]);
             return t;
         });
     }
+    /** The wallet's public key, i.e. `payer.publicKey`. */
     get publicKey() {
         return this.payer.publicKey;
     }
 }
 exports.Wallet = Wallet;
+/**
+ * `Wallet` variant that additionally supports raw message signing (`signMessage`), needed for
+ * flows like swift/signed-message orders that sign an ed25519 payload outside of a transaction.
+ */
 class WalletV2 extends Wallet {
     constructor(payer) {
         super(payer);
         this.payer = payer;
     }
+    /**
+     * Signs an arbitrary message with this wallet's ed25519 secret key (detached signature, not a
+     * transaction).
+     * @param message - Raw bytes to sign.
+     * @returns The 64-byte detached ed25519 signature.
+     */
     async signMessage(message) {
         return Buffer.from(tweetnacl_1.default.sign.detached(message, this.payer.secretKey));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@velocity-exchange/sdk",
-	"version": "0.2.5",
+	"version": "0.4.0",
 	"main": "lib/node/index.js",
 	"types": "lib/node/index.d.ts",
 	"module": "./lib/browser/index.js",
@@ -19,6 +19,7 @@
 		"test:inspect": "mocha --inspect-brk -r ts-node/register tests/**/*.ts",
 		"test:bignum": "mocha -r ts-node/register tests/bn/**/*.ts",
 		"test:ci": "mocha -r ts-node/register tests/ci/**/*.ts",
+		"test:parity": "mocha -r ts-node/register 'tests/sdkParity/**/*.ts' 'tests/oracles/**/*.ts' 'tests/amm/**/*.ts' 'tests/builder/**/*.ts' 'tests/liquidation/**/*.ts' 'tests/exchangeStatus/**/*.ts' 'tests/spot/**/*.ts' 'tests/user/**/*.ts' tests/dlob/tickSizeStandardization.ts",
 		"test:dlob": "mocha -r ts-node/register tests/dlob/**/*.ts",
 		"test:events": "mocha -r ts-node/register tests/events/**/*.ts",
 		"test:velocitycore": "bun test tests/VelocityCore",

package/src/accounts/basicUserAccountSubscriber.ts

@@ -18,6 +18,11 @@ export class BasicUserAccountSubscriber implements UserAccountSubscriber {
 
 	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,
@@ -31,26 +36,39 @@ export class BasicUserAccountSubscriber implements UserAccountSubscriber {
 		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 };

package/src/accounts/basicUserStatsAccountSubscriber.ts

@@ -24,6 +24,11 @@ export class BasicUserStatsAccountSubscriber
 
 	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,
@@ -37,28 +42,41 @@ export class BasicUserStatsAccountSubscriber
 		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 };

package/src/accounts/bulkAccountLoader.ts

@@ -5,6 +5,7 @@ import { promiseTimeout } from '../util/promiseTimeout';
 import { Connection } from '../bankrun/bankrunConnection';
 import { GET_MULTIPLE_ACCOUNTS_CHUNK_SIZE } from '../constants/numericConstants';
 
+/** An account registered with a `BulkAccountLoader`, along with every callback subscribed to its updates (keyed by callback id). */
 export type AccountToLoad = {
 	publicKey: PublicKey;
 	callbacks: Map<string, (buffer: Buffer, slot: number) => void>;
@@ -12,6 +13,17 @@ export type AccountToLoad = {
 
 const oneMinute = 60 * 1000;
 
+/**
+ * Batches many accounts behind a single periodic `getMultipleAccounts` RPC poll instead of one
+ * WebSocket subscription per account. Multiple independent callbacks (e.g. from different
+ * `PollingUserAccountSubscriber`/`PollingVelocityClientAccountSubscriber` instances) can register
+ * against the same `publicKey`; polling starts automatically on the first `addAccount` and stops
+ * when the last callback for the last account is removed. A buffer is only re-delivered to
+ * callbacks when its slot is not older than the last-seen slot for that account and its bytes
+ * actually changed, so a callback never observes a stale or duplicate update. `load()` calls are
+ * coalesced: concurrent callers share one in-flight RPC batch rather than issuing redundant
+ * requests.
+ */
 export class BulkAccountLoader {
 	connection: Connection;
 	commitment: Commitment;
@@ -26,6 +38,11 @@ export class BulkAccountLoader {
 	lastTimeLoadingPromiseCleared = Date.now();
 	mostRecentSlot = 0;
 
+	/**
+	 * @param connection Connection (or bankrun-compatible shim) used for the batched `getMultipleAccounts` polls.
+	 * @param commitment Commitment level applied to every poll.
+	 * @param pollingFrequency Poll interval in ms; `0` disables automatic polling (`startPolling` becomes a no-op), useful when the loader is driven manually via `load()`.
+	 */
 	public constructor(
 		connection: Connection,
 		commitment: Commitment,
@@ -36,6 +53,15 @@ export class BulkAccountLoader {
 		this.pollingFrequency = pollingFrequency;
 	}
 
+	/**
+	 * Registers a callback to be invoked whenever `publicKey`'s account data changes on a poll.
+	 * Multiple callbacks may be registered for the same account. Starts polling automatically if
+	 * this is the loader's first account. Awaits any in-flight `load()` before returning so a
+	 * caller can immediately follow with its own `load()` without racing the poll interval.
+	 * @param publicKey Account to track.
+	 * @param callback Invoked with the raw account buffer and the slot it was fetched at whenever the buffer changes at a non-decreasing slot.
+	 * @returns A callback id to pass to `removeAccount` later.
+	 */
 	public async addAccount(
 		publicKey: PublicKey,
 		callback: (buffer: Buffer, slot: number) => void
@@ -73,6 +99,13 @@ export class BulkAccountLoader {
 		return callbackId;
 	}
 
+	/**
+	 * Unregisters a callback previously returned by `addAccount`. Once an account has no
+	 * remaining callbacks, its cached buffer/slot is dropped and it stops being polled; if no
+	 * accounts remain at all, polling stops entirely. A no-op if `callbackId` is undefined.
+	 * @param publicKey Account the callback was registered against.
+	 * @param callbackId Id returned by `addAccount`.
+	 */
 	public removeAccount(
 		publicKey: PublicKey,
 		callbackId: string | undefined
@@ -94,12 +127,18 @@ export class BulkAccountLoader {
 		}
 	}
 
+	/**
+	 * Registers a callback invoked whenever a `load()` batch throws (e.g. RPC failure or timeout).
+	 * The loader continues polling afterward; errors do not stop the interval.
+	 * @returns A callback id to pass to `removeErrorCallbacks` later.
+	 */
 	public addErrorCallbacks(callback: (error: Error) => void): string {
 		const callbackId = uuidv4();
 		this.errorCallbacks.set(callbackId, callback);
 		return callbackId;
 	}
 
+	/** Unregisters an error callback previously returned by `addErrorCallbacks`. A no-op if `callbackId` is undefined. */
 	public removeErrorCallbacks(callbackId: string | undefined): void {
 		if (callbackId === undefined) {
 			return;
@@ -114,6 +153,14 @@ export class BulkAccountLoader {
 			.map((begin) => array.slice(begin, begin + size));
 	}
 
+	/**
+	 * Fetches every registered account in one or more chunked, concurrent `getMultipleAccounts`
+	 * batches (via `loadChunk`) and dispatches changed accounts to their callbacks. Concurrent
+	 * calls while a load is already in flight share that same in-flight promise rather than
+	 * issuing a duplicate RPC batch, unless the previous load has been running for over a minute
+	 * (treated as stuck and restarted). On failure, invokes every registered error callback
+	 * instead of throwing.
+	 */
 	public async load(): Promise<void> {
 		if (this.loadPromise) {
 			const now = Date.now();
@@ -265,14 +312,17 @@ export class BulkAccountLoader {
 		}
 	}
 
+	/** Returns the last-fetched raw buffer/slot for `publicKey`, or undefined if it has never been loaded. */
 	public getBufferAndSlot(publicKey: PublicKey): BufferAndSlot | undefined {
 		return this.bufferAndSlotMap.get(publicKey.toString());
 	}
 
+	/** Returns the highest slot number observed across any account fetched by this loader so far. */
 	public getSlot(): number {
 		return this.mostRecentSlot;
 	}
 
+	/** Starts the polling interval if not already running and `pollingFrequency !== 0`. Called automatically by `addAccount`. */
 	public startPolling(): void {
 		if (this.intervalId) {
 			return;
@@ -285,6 +335,7 @@ export class BulkAccountLoader {
 			);
 	}
 
+	/** Stops the polling interval, if running. Called automatically by `removeAccount` once no accounts remain. */
 	public stopPolling(): void {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
@@ -296,6 +347,7 @@ export class BulkAccountLoader {
 		console.log(msg);
 	}
 
+	/** Restarts polling at a new interval (ms), preserving all registered accounts and callbacks. */
 	public updatePollingFrequency(pollingFrequency: number): void {
 		this.stopPolling();
 		this.pollingFrequency = pollingFrequency;

package/src/accounts/bulkUserStatsSubscription.ts

@@ -3,8 +3,15 @@ import { BulkAccountLoader } from './bulkAccountLoader';
 import { PollingUserStatsAccountSubscriber } from './pollingUserStatsAccountSubscriber';
 
 /**
- * @param userStats
- * @param accountLoader
+ * Subscribes many `UserStats`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `UserStats.subscribe()` triggering its own `addAccount`/`load()`. Registers
+ * every account's `PollingUserStatsAccountSubscriber` with the loader first, issues one `load()`
+ * to seed all of them from a single batched `getMultipleAccounts` call, and only then calls
+ * `userStat.subscribe()` (which becomes a fast no-op fetch since data is already cached). If
+ * `userStats` is empty, still calls `accountLoader.load()` so any other accounts already
+ * registered on the loader get polled.
+ * @param userStats `UserStats` instances to subscribe; each must already be constructed with a `PollingUserStatsAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 export async function bulkPollingUserStatsSubscribe(
 	userStats: UserStats[],

package/src/accounts/bulkUserSubscription.ts

@@ -3,8 +3,14 @@ import { BulkAccountLoader } from './bulkAccountLoader';
 import { PollingUserAccountSubscriber } from './pollingUserAccountSubscriber';
 
 /**
- * @param users
- * @param accountLoader
+ * Subscribes many `User`s that share a single `BulkAccountLoader` in one batched round trip,
+ * instead of each `User.subscribe()` triggering its own `addAccount`/`load()`. Registers every
+ * user's `PollingUserAccountSubscriber` with the loader first, issues one `load()` to seed all of
+ * them from a single batched `getMultipleAccounts` call, and only then calls `user.subscribe()`
+ * (which becomes a fast no-op fetch since data is already cached). If `users` is empty, still
+ * calls `accountLoader.load()` so any other accounts already registered on the loader get polled.
+ * @param users Users to subscribe; each must already be constructed with a `PollingUserAccountSubscriber`.
+ * @param accountLoader Shared `BulkAccountLoader` batching the underlying RPC polls.
  */
 export async function bulkPollingUserSubscribe(
 	users: User[],

package/src/accounts/customizedCadenceBulkAccountLoader.ts

@@ -3,6 +3,15 @@ import { BulkAccountLoader } from './bulkAccountLoader';
 import { Commitment, Connection, PublicKey } from '@solana/web3.js';
 import { v4 as uuidv4 } from 'uuid';
 
+/**
+ * `BulkAccountLoader` variant where each account can be polled at its own cadence instead of a
+ * single shared `pollingFrequency`. Overrides the base class's single `setInterval` with a
+ * per-account `accountFrequencies` map: `handleAccountLoading()` only includes an account in a
+ * given tick if `Date.now() - lastPollingTime >= frequency` for that account, then delegates to
+ * the inherited chunked `loadChunk` for the actual `getMultipleAccounts` batch. The interval
+ * itself always runs at the fastest frequency across all registered accounts (see `startPolling`),
+ * so slower accounts simply get skipped on ticks that fire before they're due.
+ */
 export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 	private customIntervalId: NodeJS.Timeout | null;
 	private currentPollingFrequency: number | null;
@@ -10,6 +19,11 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 	private lastPollingTimes: Map<string, number>;
 	private defaultPollingFrequency: number;
 
+	/**
+	 * @param connection Connection used for the batched `getMultipleAccounts` polls.
+	 * @param commitment Commitment level applied to every poll.
+	 * @param defaultPollingFrequency Polling cadence in ms (see base `BulkAccountLoader`) used for any account added without an explicit `customPollingFrequency`, and as the floor when computing the shared interval in `startPolling`.
+	 */
 	constructor(
 		connection: Connection,
 		commitment: Commitment,
@@ -47,6 +61,7 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 		return accountsToLoad;
 	}
 
+	/** Immediately runs one due-account loading pass, bypassing the interval timer. Unlike the base class's `load()`, this does not force-load every registered account — only those currently due per their own cadence. */
 	public async load(): Promise<void> {
 		return this.handleAccountLoading();
 	}
@@ -149,6 +164,14 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 		return callbackId;
 	}
 
+	/**
+	 * Unregisters a callback previously returned by `addAccount`. Once an account has no
+	 * remaining callbacks, its cached buffer/slot and cadence bookkeeping (`accountFrequencies`,
+	 * `lastPollingTimes`) are dropped; if no accounts remain at all, polling stops entirely,
+	 * otherwise polling is restarted in case the removed account held the fastest cadence.
+	 * @param publicKey Account the callback was registered against.
+	 * @param callbackId Id returned by `addAccount`.
+	 */
 	public removeAccount(publicKey: PublicKey, callbackId: string): void {
 		const existingAccountToLoad = this.accountsToLoad.get(publicKey.toString());
 
@@ -172,11 +195,18 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 		}
 	}
 
+	/** Returns the polling cadence in ms currently set for `publicKey` (custom or default), or `null` if the account isn't registered. */
 	public getAccountCadence(publicKey: PublicKey): number | null {
 		const key = publicKey.toBase58();
 		return this.accountFrequencies.get(key) || null;
 	}
 
+	/**
+	 * Starts the shared interval timer, ticking at the fastest cadence among all registered
+	 * accounts (or `defaultPollingFrequency` if none are registered). Each tick runs
+	 * `handleAccountLoading()`, which loads only the accounts due at that moment. A no-op if
+	 * already running; call `stopPolling()` first to pick up a new minimum frequency.
+	 */
 	public startPolling(): void {
 		if (this.customIntervalId) {
 			return;
@@ -196,6 +226,7 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 		}, minFrequency);
 	}
 
+	/** Stops the shared interval timer (and the base class's, via `super.stopPolling()`) and clears `lastPollingTimes` so every account is treated as due again once polling restarts. */
 	public stopPolling(): void {
 		super.stopPolling();
 
@@ -207,6 +238,12 @@ export class CustomizedCadenceBulkAccountLoader extends BulkAccountLoader {
 		this.lastPollingTimes.clear();
 	}
 
+	/**
+	 * Clears all per-account cadence bookkeeping. Because `getAccountsToLoad()` only considers
+	 * accounts with an entry in `accountFrequencies`, this stops polling for every registered
+	 * account until a cadence is re-established via `setCustomPollingFrequency` or `addAccount`.
+	 * Registered accounts/callbacks themselves are untouched.
+	 */
 	public clearAccountFrequencies(): void {
 		this.accountFrequencies.clear();
 	}

package/src/accounts/fetch.ts

@@ -13,6 +13,15 @@ import {
 } from '../addresses/pda';
 import { VelocityProgram } from '../config';
 
+/**
+ * Fetches every `UserAccount` (sub-account) belonging to `authority`, from sub-account id `0`
+ * up to `limit - 1`, in a single batched `getMultipleAccountsInfo` RPC call.
+ * @param connection Connection used for the batched fetch.
+ * @param program Anchor program used to derive PDAs and decode account data.
+ * @param authority Wallet/authority pubkey whose sub-accounts to fetch.
+ * @param limit Number of sub-account ids to check, starting at 0. Defaults to 8.
+ * @returns One entry per sub-account id in order; `undefined` where no account exists at that id.
+ */
 export async function fetchUserAccounts(
 	connection: Connection,
 	program: VelocityProgram,
@@ -29,6 +38,15 @@ export async function fetchUserAccounts(
 	return fetchUserAccountsUsingKeys(connection, program, userAccountPublicKeys);
 }
 
+/**
+ * Fetches and decodes a specific list of `UserAccount` pubkeys in one batched
+ * `getMultipleAccountsInfo` RPC call. Unlike `fetchUserAccounts`, the caller supplies the exact
+ * addresses rather than deriving them by sub-account id.
+ * @param connection Connection used for the batched fetch.
+ * @param program Anchor program used to decode account data.
+ * @param userAccountPublicKeys Addresses to fetch, in order.
+ * @returns One entry per input pubkey, in the same order; `undefined` where no account exists at that address.
+ */
 export async function fetchUserAccountsUsingKeys(
 	connection: Connection,
 	program: VelocityProgram,
@@ -50,6 +68,13 @@ export async function fetchUserAccountsUsingKeys(
 	});
 }
 
+/**
+ * Fetches and decodes the `UserStatsAccount` for `authority`, if one exists.
+ * @param connection Connection used for the fetch.
+ * @param program Anchor program used to derive the PDA and decode account data.
+ * @param authority Wallet/authority pubkey the stats account belongs to.
+ * @returns The decoded account, or `undefined` if it hasn't been initialized on-chain.
+ */
 export async function fetchUserStatsAccount(
 	connection: Connection,
 	program: VelocityProgram,
@@ -72,6 +97,14 @@ export async function fetchUserStatsAccount(
 		: undefined;
 }
 
+/**
+ * Fetches and decodes the `RevenueShareAccount` for `authority` (tracks referral/builder revenue
+ * share balances), if one exists.
+ * @param connection Connection used for the fetch.
+ * @param program Anchor program used to derive the PDA and decode account data.
+ * @param authority Wallet/authority pubkey the revenue share account belongs to.
+ * @returns The decoded account, or `null` if it hasn't been initialized on-chain.
+ */
 export async function fetchRevenueShareAccount(
 	connection: Connection,
 	program: VelocityProgram,
@@ -91,6 +124,14 @@ export async function fetchRevenueShareAccount(
 	) as RevenueShareAccount;
 }
 
+/**
+ * Fetches and decodes the `RevenueShareEscrowAccount` for `authority` (holds escrowed
+ * revenue-share amounts pending distribution), if one exists.
+ * @param connection Connection used for the fetch.
+ * @param program Anchor program used to derive the PDA and decode account data.
+ * @param authority Wallet/authority pubkey the escrow account belongs to.
+ * @returns The decoded account, or `null` if it hasn't been initialized on-chain.
+ */
 export async function fetchRevenueShareEscrowAccount(
 	connection: Connection,
 	program: VelocityProgram,
@@ -115,11 +156,20 @@ export async function fetchRevenueShareEscrowAccount(
 	return escrowAccount;
 }
 
+/** Options accepted by `fetchAccount`/`fetchAccounts`. */
 export type FetchAccountOptions = {
+	/** Commitment level for the underlying `getAccountInfo`/`getMultipleAccountsInfo` call; defaults to the connection's configured commitment if omitted. */
 	commitment?: Parameters<Connection['getAccountInfo']>[1];
 };
 
-/** Raw account data buffer (no Anchor decode). */
+/**
+ * Fetches an account's raw data buffer without decoding it (no Anchor coder involved), for
+ * callers that only need the bytes.
+ * @param connection Connection used for the fetch.
+ * @param publicKey Account address to fetch.
+ * @param opts Optional commitment override.
+ * @returns The raw account data, or `null` if the account doesn't exist.
+ */
 export async function fetchAccount(
 	connection: Connection,
 	publicKey: PublicKey,
@@ -129,7 +179,14 @@ export async function fetchAccount(
 	return info?.data ?? null;
 }
 
-/** Batch variant of {@link fetchAccount}. */
+/**
+ * Batch variant of `fetchAccount` — fetches raw data buffers for multiple accounts in one
+ * `getMultipleAccountsInfo` call.
+ * @param connection Connection used for the fetch.
+ * @param publicKeys Account addresses to fetch, in order.
+ * @param opts Optional commitment override.
+ * @returns One entry per input pubkey, in the same order; `null` where the account doesn't exist.
+ */
 export async function fetchAccounts(
 	connection: Connection,
 	publicKeys: PublicKey[],