@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/userMap/userStatsMap.js

@@ -6,6 +6,12 @@ const userStats_1 = require("../userStats");
 const bulkAccountLoader_1 = require("../accounts/bulkAccountLoader");
 const memcmp_1 = require("../memcmp");
 const web3_js_1 = require("@solana/web3.js");
+/**
+ * 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.
+ */
 class UserStatsMap {
     /**
      * Creates a new UserStatsMap instance.
@@ -30,6 +36,7 @@ class UserStatsMap {
         };
         this.decode = this.velocityClient.program.account.userStats.coder.accounts.decodeUnchecked.bind(this.velocityClient.program.account.userStats.coder.accounts);
     }
+    /** Populates the map for `authorities` via `sync()` (no-op if the map already has entries). */
     async subscribe(authorities) {
         if (this.size() > 0) {
             return;
@@ -60,12 +67,22 @@ 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. */
     async updateWithOrderRecord(record, userMap) {
         const user = await userMap.mustGet(record.user.toString());
         if (!this.has(user.getUserAccountOrThrow().authority.toString())) {
             await this.addUserStat(user.getUserAccountOrThrow().authority, undefined, false);
         }
     }
+    /**
+     * 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.
+     */
     async updateWithEventRecord(record, userMap) {
         if (record.eventType === 'DepositRecord') {
             const depositRecord = record;
@@ -123,9 +140,11 @@ class UserStatsMap {
             await this.mustGet(ifStakeRecord.userAuthority.toString());
         }
     }
+    /** Returns true if `authorityPublicKey` has a `UserStats` cached in the map. */
     has(authorityPublicKey) {
         return this.userStatsMap.has(authorityPublicKey);
     }
+    /** Returns the cached `UserStats` for `authorityPublicKey`, or `undefined` if not (yet) in the map. */
     get(authorityPublicKey) {
         return this.userStatsMap.get(authorityPublicKey);
     }
@@ -145,9 +164,11 @@ class UserStatsMap {
         }
         return userStats;
     }
+    /** Iterates all cached `UserStats` instances. */
     values() {
         return this.userStatsMap.values();
     }
+    /** Number of authorities currently cached in the map. */
     size() {
         return this.userStatsMap.size;
     }
@@ -261,6 +282,7 @@ class UserStatsMap {
             this.syncPromise = undefined;
         }
     }
+    /** Unsubscribes and removes every cached `UserStats` from the map. */
     async unsubscribe() {
         for (const [key, userStats] of this.userStatsMap.entries()) {
             await userStats.unsubscribe();

package/lib/browser/userName.d.ts

@@ -1,5 +1,21 @@
+/** Maximum length, in characters/bytes, of a `User`/`SpotMarket`/`PerpMarket` name field on-chain. */
 export declare const MAX_NAME_LENGTH = 32;
+/** Default name assigned to a user's first sub-account (id 0) when none is supplied. */
 export declare const DEFAULT_USER_NAME = "Main Account";
+/** Default name used for a market when no explicit name is configured. */
 export declare 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 declare function encodeName(name: string): number[];
+/**
+ * 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 declare function decodeName(bytes: number[]): string;

package/lib/browser/userName.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeName = exports.encodeName = exports.DEFAULT_MARKET_NAME = exports.DEFAULT_USER_NAME = exports.MAX_NAME_LENGTH = void 0;
+/** Maximum length, in characters/bytes, of a `User`/`SpotMarket`/`PerpMarket` name field on-chain. */
 exports.MAX_NAME_LENGTH = 32;
+/** Default name assigned to a user's first sub-account (id 0) when none is supplied. */
 exports.DEFAULT_USER_NAME = 'Main Account';
+/** Default name used for a market when no explicit name is configured. */
 exports.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`.
+ */
 function encodeName(name) {
     if (name.length > exports.MAX_NAME_LENGTH) {
         throw Error(`Name (${name}) longer than 32 characters`);
@@ -14,6 +25,11 @@ function encodeName(name) {
     return Array(...buffer);
 }
 exports.encodeName = encodeName;
+/**
+ * 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.
+ */
 function decodeName(bytes) {
     const buffer = Buffer.from(bytes);
     return buffer.toString('utf8').trim();

package/lib/browser/userStats.d.ts

@@ -14,16 +14,43 @@ export declare class UserStats {
     accountSubscriber: UserStatsAccountSubscriber;
     isSubscribed: boolean;
     constructor(config: UserStatsConfig);
+    /**
+     * 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.
+     */
     subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
+    /** Forces the account subscriber to re-fetch the `UserStats` account from RPC. */
     fetchAccounts(): Promise<void>;
+    /** Tears down the `UserStats` account subscription. */
     unsubscribe(): Promise<void>;
+    /** Like `getAccount`, but also returns the slot at which the account was last observed. Same `undefined`-when-not-found contract. */
     getAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
+    /**
+     * 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.
+     */
     getAccount(): UserStatsAccount | undefined;
     /**
-     * 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.
      */
     getAccountOrThrow(): UserStatsAccount;
+    /**
+     * 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).
+     */
     getReferrerInfo(): ReferrerInfo | undefined;
+    /**
+     * 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.
+     */
     static getOldestActionTs(account: UserStatsAccount): number;
 }

package/lib/browser/userStats.js

@@ -38,26 +38,41 @@ class UserStats {
             throw new Error(`Unknown user stats account subscription type: ${exhaustiveCheck}`);
         }
     }
+    /**
+     * 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.
+     */
     async subscribe(userStatsAccount) {
         this.isSubscribed = await this.accountSubscriber.subscribe(userStatsAccount);
         return this.isSubscribed;
     }
+    /** Forces the account subscriber to re-fetch the `UserStats` account from RPC. */
     async fetchAccounts() {
         await this.accountSubscriber.fetch();
     }
+    /** Tears down the `UserStats` account subscription. */
     async unsubscribe() {
         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. */
     getAccountAndSlot() {
         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.
+     */
     getAccount() {
         var _a;
         return (_a = this.accountSubscriber.getUserStatsAccountAndSlot()) === null || _a === void 0 ? void 0 : _a.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.
      */
     getAccountOrThrow() {
@@ -67,6 +82,11 @@ 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).
+     */
     getReferrerInfo() {
         const account = this.getAccount();
         if (!account || account.referrer.equals(web3_js_1.PublicKey.default)) {
@@ -79,6 +99,13 @@ 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.
+     */
     static getOldestActionTs(account) {
         return Math.min(account.lastFillerVolume30DTs.toNumber(), account.lastMakerVolume30DTs.toNumber(), account.lastTakerVolume30DTs.toNumber());
     }

package/lib/browser/util/TransactionConfirmationManager.d.ts

@@ -7,7 +7,40 @@ export declare class TransactionConfirmationManager {
     private pendingConfirmations;
     private intervalId;
     constructor(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.
+     */
     confirmTransactionWebSocket(txSig: string, timeout?: number, desiredConfirmationStatus?: TransactionConfirmationStatus): Promise<RpcResponseAndContext<SignatureResult>>;
+    /**
+     * 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).
+     */
     confirmTransactionPolling(txSig: string, desiredConfirmationStatus?: TransactionConfirmationStatus, timeout?: number, pollInterval?: number, searchTransactionHistory?: boolean): Promise<SignatureStatus>;
     private startConfirmationLoop;
     private checkPendingConfirmations;

package/lib/browser/util/TransactionConfirmationManager.js

@@ -20,6 +20,21 @@ class TransactionConfirmationManager {
         this.intervalId = null;
         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, timeout = 30000, desiredConfirmationStatus = config_1.DEFAULT_CONFIRMATION_OPTS.commitment) {
         const start = Date.now();
         const subscriptionCommitment = desiredConfirmationStatus || config_1.DEFAULT_CONFIRMATION_OPTS.commitment;
@@ -88,6 +103,24 @@ 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, desiredConfirmationStatus = config_1.DEFAULT_CONFIRMATION_OPTS.commitment, timeout = 30000, pollInterval = 1000, searchTransactionHistory = false) {
         // Interval must be > 400ms and a multiple of 100ms
         if (pollInterval < 400 || pollInterval % 100 !== 0) {

package/lib/browser/util/chainClock.d.ts

@@ -1,17 +1,41 @@
 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 declare class ChainClock {
     private _state;
+    /**
+     * @param props - Initial progress values, one entry per commitment level to track.
+     */
     constructor(props: ChainClickInitialisationProps);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
     getState(commitment: Commitment): ChainClockProgress | undefined;
 }

package/lib/browser/util/chainClock.js

@@ -1,13 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChainClock = void 0;
+/**
+ * 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.
+ */
 class ChainClock {
+    /**
+     * @param props - Initial progress values, one entry per commitment level to track.
+     */
     constructor(props) {
         this._state = new Map();
         props.forEach((prop) => {
             this._state.set(prop.commitment, prop);
         });
     }
+    /**
+     * 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) {
         const state = this._state.get(props.commitment);
         if (state) {
@@ -22,6 +37,11 @@ class ChainClock {
             this._state.set(props.commitment, props);
         }
     }
+    /**
+     * 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.
+     */
     getState(commitment) {
         return this._state.get(commitment);
     }

package/lib/browser/util/computeUnits.d.ts

@@ -1,7 +1,39 @@
 import { Connection, Finality, PublicKey, 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 declare function findComputeUnitConsumption(programId: PublicKey, connection: Connection, txSignature: string, commitment?: Finality): Promise<string[]>;
+/**
+ * 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 declare function isSetComputeUnitsIx(ix: TransactionInstruction): boolean;
+/**
+ * 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 declare function isSetComputeUnitPriceIx(ix: TransactionInstruction): boolean;
+/**
+ * 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 declare function containsComputeUnitIxs(ixs: TransactionInstruction[]): {
     hasSetComputeUnitLimitIx: boolean;
     hasSetComputeUnitPriceIx: boolean;

package/lib/browser/util/computeUnits.js

@@ -2,6 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.containsComputeUnitIxs = exports.isSetComputeUnitPriceIx = exports.isSetComputeUnitsIx = exports.findComputeUnitConsumption = void 0;
 const web3_js_1 = require("@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).
+ */
 async function findComputeUnitConsumption(programId, connection, txSignature, commitment = 'confirmed') {
     var _a;
     const tx = await connection.getTransaction(txSignature, { commitment });
@@ -20,6 +33,12 @@ async function findComputeUnitConsumption(programId, connection, txSignature, co
     return computeUnits;
 }
 exports.findComputeUnitConsumption = findComputeUnitConsumption;
+/**
+ * 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.
+ */
 function isSetComputeUnitsIx(ix) {
     // Compute budget program discriminator is first byte
     // 2: set compute unit limit
@@ -32,6 +51,12 @@ function isSetComputeUnitsIx(ix) {
     return false;
 }
 exports.isSetComputeUnitsIx = isSetComputeUnitsIx;
+/**
+ * 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).
+ */
 function isSetComputeUnitPriceIx(ix) {
     // Compute budget program discriminator is first byte
     // 2: set compute unit limit
@@ -44,6 +69,13 @@ function isSetComputeUnitPriceIx(ix) {
     return false;
 }
 exports.isSetComputeUnitPriceIx = isSetComputeUnitPriceIx;
+/**
+ * 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.
+ */
 function containsComputeUnitIxs(ixs) {
     return {
         hasSetComputeUnitLimitIx: ixs.some(isSetComputeUnitsIx),

package/lib/browser/util/digest.d.ts

@@ -1,5 +1,22 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/**
+ * Computes the raw SHA-256 digest of arbitrary data.
+ * @param data - Bytes to hash.
+ * @returns The 32-byte SHA-256 digest.
+ */
 export declare function digest(data: Buffer): Buffer;
+/**
+ * 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 declare function digestSignature(signature: Uint8Array): string;
+/**
+ * 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 declare function generateSignedMsgUuid(): Uint8Array;

package/lib/browser/util/digest.js

@@ -3,16 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSignedMsgUuid = exports.digestSignature = exports.digest = void 0;
 const crypto_1 = require("crypto");
 const nanoid_1 = require("nanoid");
+/**
+ * Computes the raw SHA-256 digest of arbitrary data.
+ * @param data - Bytes to hash.
+ * @returns The 32-byte SHA-256 digest.
+ */
 function digest(data) {
     const hash = (0, crypto_1.createHash)('sha256');
     hash.update(data);
     return hash.digest();
 }
 exports.digest = 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.
+ */
 function digestSignature(signature) {
     return (0, crypto_1.createHash)('sha256').update(signature).digest('base64');
 }
 exports.digestSignature = digestSignature;
+/**
+ * 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).
+ */
 function generateSignedMsgUuid() {
     return Uint8Array.from(Buffer.from((0, nanoid_1.nanoid)(8)));
 }

package/lib/browser/util/ed25519Utils.d.ts

@@ -1,10 +1,20 @@
 import { TransactionInstruction } from '@solana/web3.js';
 /**
- * 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 declare function createMinimalEd25519VerifyIx(customInstructionIndex: number, messageOffset: number, customInstructionData: Uint8Array, magicLen?: number): TransactionInstruction;

package/lib/browser/util/ed25519Utils.js

@@ -46,12 +46,22 @@ const ED25519_INSTRUCTION_LAYOUT = BufferLayout.struct([
     BufferLayout.u16('messageInstructionIndex'),
 ]);
 /**
- * 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.
  */
 function createMinimalEd25519VerifyIx(customInstructionIndex, messageOffset, customInstructionData, magicLen) {
     const signatureOffset = messageOffset + (magicLen === undefined ? MAGIC_LEN : magicLen);

package/lib/browser/util/promiseTimeout.d.ts

@@ -1 +1,10 @@
+/**
+ * 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 declare function promiseTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null>;