@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/memcmp.ts

@@ -3,6 +3,11 @@ import bs58 from 'bs58';
 import { BorshAccountsCoder } from './isomorphic/anchor29';
 import { encodeName } from './userName';
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `User` account type at offset 0. Use to fetch all `User` (sub-account) accounts.
+ * @returns A memcmp filter for `User` accounts.
+ */
 export function getUserFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -12,42 +17,93 @@ export function getUserFilter(): MemcmpFilter {
 	};
 }
 
+/*
+ * Byte offsets of the trailing scalar flags in the `User` account.
+ *
+ * These MUST match the on-chain `User` layout decoded in `decode/user.ts`. The
+ * current Velocity layout is 4496 bytes, with the tail block laid out as
+ * consecutive single bytes:
+ *   status(4468) isMarginTradingEnabled(4469) idle(4470) openOrders(4471)
+ *   hasOpenOrder(4472) openAuctions(4473) hasOpenAuction(4474) poolId(4475)
+ *   specialUserStatus(4476)
+ *
+ * NOTE: these were previously hardcoded to the older (4376-byte) layout
+ * (idle@4350, hasOpenOrder@4352, ...). After Velocity added fields to
+ * `PerpPosition`, the account grew by 120 bytes and these flags shifted, but
+ * the filters were not updated — so `getUserWithOrderFilter()` matched zero
+ * accounts and the DLOB order book never populated. Keep these in sync with
+ * `decode/user.ts` if the `User` layout changes again.
+ */
+const USER_IDLE_OFFSET = 4470;
+const USER_HAS_OPEN_ORDER_OFFSET = 4472;
+const USER_HAS_OPEN_AUCTION_OFFSET = 4474;
+const USER_POOL_ID_OFFSET = 4475;
+
+/**
+ * Builds a memcmp filter matching `User` accounts whose `idle` flag (offset 4470) is `false`.
+ * Idle sub-accounts have no open positions/orders and have been inactive past the idle threshold;
+ * this filter excludes them, e.g. when scanning for accounts that need active monitoring.
+ * @returns A memcmp filter for non-idle `User` accounts.
+ */
 export function getNonIdleUserFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 4350,
+			offset: USER_IDLE_OFFSET,
 			bytes: bs58.encode(Uint8Array.from([0])),
 		},
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `true`
+ * — i.e. at least one live order. Used by the DLOB to fetch only accounts that can populate the
+ * order book.
+ * @returns A memcmp filter for `User` accounts with at least one open order.
+ */
 export function getUserWithOrderFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 4352,
+			offset: USER_HAS_OPEN_ORDER_OFFSET,
 			bytes: bs58.encode(Uint8Array.from([1])),
 		},
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `false`
+ * — i.e. no live orders.
+ * @returns A memcmp filter for `User` accounts with no open orders.
+ */
 export function getUserWithoutOrderFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 4352,
+			offset: USER_HAS_OPEN_ORDER_OFFSET,
 			bytes: bs58.encode(Uint8Array.from([0])),
 		},
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenAuction` (offset 4474) set to
+ * `true` — i.e. at least one order still in its Dutch-auction window.
+ * @returns A memcmp filter for `User` accounts with an active order auction.
+ */
 export function getUserWithAuctionFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 4354,
+			offset: USER_HAS_OPEN_AUCTION_OFFSET,
 			bytes: bs58.encode(Uint8Array.from([1])),
 		},
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `User` accounts whose `name` field (32 bytes, offset 72) equals
+ * `name` once encoded/padded the same way as on-chain.
+ * @param name - Human-readable sub-account name to match; encoded via `encodeName` (UTF-8,
+ * space-padded/truncated to 32 bytes) before comparison.
+ * @returns A memcmp filter for `User` accounts with the given name.
+ */
 export function getUserWithName(name: string): MemcmpFilter {
 	return {
 		memcmp: {
@@ -57,15 +113,26 @@ export function getUserWithName(name: string): MemcmpFilter {
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `User` accounts whose `poolId` (single byte, offset 4475) equals
+ * `poolId`. Used to scope account scans to a specific isolated pool.
+ * @param poolId - Pool id byte (0 = main/cross pool) to match.
+ * @returns A memcmp filter for `User` accounts in the given pool.
+ */
 export function getUsersWithPoolId(poolId: number): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 4356,
+			offset: USER_POOL_ID_OFFSET,
 			bytes: bs58.encode(Uint8Array.from([poolId])),
 		},
 	};
 }
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `UserStats` account type at offset 0. Use to fetch all `UserStats` accounts.
+ * @returns A memcmp filter for `UserStats` accounts.
+ */
 export function getUserStatsFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -75,24 +142,54 @@ export function getUserStatsFilter(): MemcmpFilter {
 	};
 }
 
+/*
+ * Byte offset of `referrer_status` in the `UserStats` account: 8 (discriminator)
+ * + authority(32) + referrer(32) + fees(32) + maker/taker/filler volume 30d(24)
+ * + last maker/taker/filler volume 30d ts(24) + if_staked_quote_asset_amount(8)
+ * + number_of_sub_accounts(2) + number_of_sub_accounts_created(2) = 164.
+ */
+const USER_STATS_REFERRER_STATUS_OFFSET = 164;
+
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly `ReferrerStatus.IsReferred` (2) — i.e. the account was referred and is *not*
+ * also flagged `IsReferrer`. Because memcmp does an exact byte match rather than a bitwise test,
+ * this excludes accounts that are both `IsReferrer` and `IsReferred` (byte value 3); use
+ * `getUserStatsIsReferredOrReferrerFilter` for that combined case.
+ * @returns A memcmp filter for `UserStats` accounts referred by (but not also referring) another user.
+ */
 export function getUserStatsIsReferredFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 188,
+			offset: USER_STATS_REFERRER_STATUS_OFFSET,
 			bytes: bs58.encode(Buffer.from(Uint8Array.from([2]))),
 		},
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly 3 — i.e. `ReferrerStatus.IsReferrer | ReferrerStatus.IsReferred` both set on the
+ * same account. Despite the name, this is an exact-byte match (memcmp can't test bits in
+ * isolation), so it does *not* match an account that is only `IsReferrer` (1) or only `IsReferred`
+ * (2) — use `getUserStatsIsReferredFilter` for the referred-only case.
+ * @returns A memcmp filter for `UserStats` accounts with both the referrer and referred flags set.
+ */
 export function getUserStatsIsReferredOrReferrerFilter(): MemcmpFilter {
 	return {
 		memcmp: {
-			offset: 188,
+			offset: USER_STATS_REFERRER_STATUS_OFFSET,
 			bytes: bs58.encode(Buffer.from(Uint8Array.from([3]))),
 		},
 	};
 }
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SignedMsgUserOrders` account type at offset 0. Use to fetch all swift/signed-message order
+ * accounts.
+ * @returns A memcmp filter for `SignedMsgUserOrders` accounts.
+ */
 export function getSignedMsgUserOrdersFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -104,6 +201,11 @@ export function getSignedMsgUserOrdersFilter(): MemcmpFilter {
 	};
 }
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `PerpMarket` account type at offset 0. Use to fetch all perp market accounts.
+ * @returns A memcmp filter for `PerpMarket` accounts.
+ */
 export function getPerpMarketAccountsFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -112,6 +214,11 @@ export function getPerpMarketAccountsFilter(): MemcmpFilter {
 		},
 	};
 }
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SpotMarket` account type at offset 0. Use to fetch all spot market accounts.
+ * @returns A memcmp filter for `SpotMarket` accounts.
+ */
 export function getSpotMarketAccountsFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -121,6 +228,12 @@ export function getSpotMarketAccountsFilter(): MemcmpFilter {
 	};
 }
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `RevenueShareEscrow` account type at offset 0. Use to fetch all revenue-share escrow accounts
+ * (builder-fee approvals/referral state).
+ * @returns A memcmp filter for `RevenueShareEscrow` accounts.
+ */
 export function getRevenueShareEscrowFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -132,6 +245,11 @@ export function getRevenueShareEscrowFilter(): MemcmpFilter {
 	};
 }
 
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `Constituent` account type at offset 0. Use to fetch all LP-pool constituent accounts.
+ * @returns A memcmp filter for `Constituent` accounts.
+ */
 export function getConstituentFilter(): MemcmpFilter {
 	return {
 		memcmp: {
@@ -143,6 +261,12 @@ export function getConstituentFilter(): MemcmpFilter {
 	};
 }
 
+/**
+ * Builds a memcmp filter matching `Constituent` accounts belonging to a specific LP pool, by
+ * comparing the `lpPool` pubkey field (32 bytes, offset 72) against `lpPoolPublicKey`.
+ * @param lpPoolPublicKey - The `LpPool` account's pubkey to match constituents against.
+ * @returns A memcmp filter for `Constituent` accounts of the given LP pool.
+ */
 export function getConstituentLpPoolFilter(
 	lpPoolPublicKey: PublicKey
 ): MemcmpFilter {

package/src/oracles/oracleClientCache.ts

@@ -4,10 +4,26 @@ import { getOracleClient } from '../factory/oracleClient';
 import { Connection } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
 
+/**
+ * Caches one `OracleClient` instance per oracle *source kind* (not per account), so repeated
+ * lookups for the same `OracleSource` variant (e.g. every `pyth1KPull` market) reuse a single
+ * adapter instead of constructing a new one each time.
+ */
 export class OracleClientCache {
 	cache = new Map<string, OracleClient>();
 	public constructor() {}
 
+	/**
+	 * Returns the cached `OracleClient` for `oracleSource`'s variant key, constructing and caching
+	 * one via `getOracleClient` on first use.
+	 * @param oracleSource - Oracle source variant (its top-level key, e.g. `"pyth"`, is the cache key —
+	 * note this means all sources sharing a variant name share one client instance regardless of any
+	 * other fields on the variant).
+	 * @param connection - RPC connection passed through to the client on construction.
+	 * @param program - Velocity Anchor program, used by clients that decode via the program's IDL coder.
+	 * @returns The `OracleClient` for this source variant.
+	 * @throws Error (via `getOracleClient`) if `oracleSource` is not a recognized variant.
+	 */
 	public get(
 		oracleSource: OracleSource,
 		connection: Connection,

package/src/oracles/oracleId.ts

@@ -1,6 +1,14 @@
 import { PublicKey } from '@solana/web3.js';
 import { OracleSource, OracleSourceNum } from '../types';
 
+/**
+ * Maps an `OracleSource` enum-object (e.g. `{ pyth: {} }`) to its stable numeric encoding
+ * (`OracleSourceNum`) used as part of an oracle id string. This encoding is SDK-internal — it
+ * is not the on-chain Borsh discriminant (see `OracleSourceNum`).
+ * @param source - The oracle source variant.
+ * @returns The corresponding `OracleSourceNum` value.
+ * @throws Error if `source` doesn't match any known variant.
+ */
 export function getOracleSourceNum(source: OracleSource): number {
 	if ('pyth' in source) return OracleSourceNum.PYTH;
 	if ('pyth1K' in source) return OracleSourceNum.PYTH_1K;
@@ -8,14 +16,15 @@ export function getOracleSourceNum(source: OracleSource): number {
 	if ('pythPull' in source) return OracleSourceNum.PYTH_PULL;
 	if ('pyth1KPull' in source) return OracleSourceNum.PYTH_1K_PULL;
 	if ('pyth1MPull' in source) return OracleSourceNum.PYTH_1M_PULL;
-	if ('switchboard' in source) return OracleSourceNum.SWITCHBOARD;
+	if ('deprecatedSwitchboard' in source)
+		return OracleSourceNum.DEPRECATED_SWITCHBOARD;
 	if ('quoteAsset' in source) return OracleSourceNum.QUOTE_ASSET;
 	if ('pythStableCoin' in source) return OracleSourceNum.PYTH_STABLE_COIN;
 	if ('pythStableCoinPull' in source)
 		return OracleSourceNum.PYTH_STABLE_COIN_PULL;
 	if ('prelaunch' in source) return OracleSourceNum.PRELAUNCH;
-	if ('switchboardOnDemand' in source)
-		return OracleSourceNum.SWITCHBOARD_ON_DEMAND;
+	if ('deprecatedSwitchboardOnDemand' in source)
+		return OracleSourceNum.DEPRECATED_SWITCHBOARD_ON_DEMAND;
 	if ('pythLazer' in source) return OracleSourceNum.PYTH_LAZER;
 	if ('pythLazer1K' in source) return OracleSourceNum.PYTH_LAZER_1K;
 	if ('pythLazer1M' in source) return OracleSourceNum.PYTH_LAZER_1M;
@@ -24,6 +33,13 @@ export function getOracleSourceNum(source: OracleSource): number {
 	throw new Error('Invalid oracle source');
 }
 
+/**
+ * Inverse of `getOracleSourceNum`: maps a numeric `OracleSourceNum` back to its `OracleSource`
+ * enum-object.
+ * @param sourceNum - Numeric oracle source encoding.
+ * @returns The corresponding `OracleSource` variant.
+ * @throws Error if `sourceNum` doesn't match any known `OracleSourceNum` value.
+ */
 export function getOracleSourceFromNum(sourceNum: number): OracleSource {
 	if (sourceNum === OracleSourceNum.PYTH) return 'pyth';
 	if (sourceNum === OracleSourceNum.PYTH_1K) return 'pyth1K';
@@ -31,14 +47,15 @@ export function getOracleSourceFromNum(sourceNum: number): OracleSource {
 	if (sourceNum === OracleSourceNum.PYTH_PULL) return 'pythPull';
 	if (sourceNum === OracleSourceNum.PYTH_1K_PULL) return 'pyth1KPull';
 	if (sourceNum === OracleSourceNum.PYTH_1M_PULL) return 'pyth1MPull';
-	if (sourceNum === OracleSourceNum.SWITCHBOARD) return 'switchboard';
+	if (sourceNum === OracleSourceNum.DEPRECATED_SWITCHBOARD)
+		return 'deprecatedSwitchboard';
 	if (sourceNum === OracleSourceNum.QUOTE_ASSET) return 'quoteAsset';
 	if (sourceNum === OracleSourceNum.PYTH_STABLE_COIN) return 'pythStableCoin';
 	if (sourceNum === OracleSourceNum.PYTH_STABLE_COIN_PULL)
 		return 'pythStableCoinPull';
 	if (sourceNum === OracleSourceNum.PRELAUNCH) return 'prelaunch';
-	if (sourceNum === OracleSourceNum.SWITCHBOARD_ON_DEMAND)
-		return 'switchboardOnDemand';
+	if (sourceNum === OracleSourceNum.DEPRECATED_SWITCHBOARD_ON_DEMAND)
+		return 'deprecatedSwitchboardOnDemand';
 	if (sourceNum === OracleSourceNum.PYTH_LAZER) return 'pythLazer';
 	if (sourceNum === OracleSourceNum.PYTH_LAZER_1K) return 'pythLazer1K';
 	if (sourceNum === OracleSourceNum.PYTH_LAZER_1M) return 'pythLazer1M';
@@ -47,6 +64,15 @@ export function getOracleSourceFromNum(sourceNum: number): OracleSource {
 	throw new Error('Invalid oracle source');
 }
 
+/**
+ * Builds a stable string id for an oracle account, uniquely identifying it by both its address
+ * and the source/decoding scheme to use — the same pubkey can be interpreted under different
+ * `OracleSource`s (e.g. `pyth` vs `pyth1K`) with different results, so the pubkey alone is not a
+ * safe cache/map key.
+ * @param publicKey - The oracle account's address.
+ * @param source - The oracle source variant to decode it as.
+ * @returns A string of the form `"<base58 pubkey>-<OracleSourceNum>"`.
+ */
 export function getOracleId(
 	publicKey: PublicKey,
 	source: OracleSource
@@ -54,6 +80,13 @@ export function getOracleId(
 	return `${publicKey.toBase58()}-${getOracleSourceNum(source)}`;
 }
 
+/**
+ * Inverse of `getOracleId`: parses an oracle id string back into its pubkey and `OracleSource`.
+ * @param oracleId - An id string previously produced by `getOracleId`.
+ * @returns The decoded `publicKey` and `source`.
+ * @throws Error if the encoded source number doesn't match any known `OracleSourceNum` value, or
+ * `PublicKey` construction fails on a malformed id.
+ */
 export function getPublicKeyAndSourceFromOracleId(oracleId: string): {
 	publicKey: PublicKey;
 	source: OracleSource;

package/src/oracles/prelaunchOracleClient.ts

@@ -4,6 +4,11 @@ import { VelocityProgram } from '../config';
 import { PrelaunchOracle } from '../types';
 import { getOracleAccountDataOrThrow } from './utils';
 
+/**
+ * `OracleClient` for the `PrelaunchOracle` account type — a synthetic, program-managed "oracle"
+ * used for perp markets that have not yet listed on a real price feed. Its price is admin/keeper
+ * set (via `updatePrelaunchOracleParams`) rather than fed by an external network.
+ */
 export class PrelaunchOracleClient implements OracleClient {
 	private connection: Connection;
 	private program: VelocityProgram;
@@ -13,6 +18,12 @@ export class PrelaunchOracleClient implements OracleClient {
 		this.program = program;
 	}
 
+	/**
+	 * Fetches and decodes a `PrelaunchOracle` account's current price data.
+	 * @param pricePublicKey - The `PrelaunchOracle` account's address (see `getPrelaunchOraclePublicKey`).
+	 * @returns The decoded price data.
+	 * @throws Error if the account does not exist.
+	 */
 	public async getOraclePriceData(
 		pricePublicKey: PublicKey
 	): Promise<OraclePriceData> {
@@ -24,6 +35,15 @@ export class PrelaunchOracleClient implements OracleClient {
 		return this.getOraclePriceDataFromBuffer(data);
 	}
 
+	/**
+	 * Decodes raw `PrelaunchOracle` account bytes into normalized `OraclePriceData`. Note `slot` is
+	 * populated from `ammLastUpdateSlot` (the last time the paired AMM used this price), not a
+	 * slot recorded by the oracle account itself, and `hasSufficientNumberOfDataPoints` is always
+	 * `true` since there is no publisher-count concept for this source.
+	 * @param buffer - Raw `PrelaunchOracle` account data.
+	 * @returns Price (`price`), confidence (`confidence`, both PRICE_PRECISION 1e6), and the
+	 * prelaunch-only upper bound (`maxPrice`, PRICE_PRECISION 1e6).
+	 */
 	public getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData {
 		const prelaunchOracle = (
 			this.program.account as any

package/src/oracles/pythClient.ts

@@ -10,11 +10,27 @@ import {
 } from '../constants/numericConstants';
 import { getOracleAccountDataOrThrow } from './utils';
 
+/**
+ * `OracleClient` for legacy (push-model) Pyth price accounts, decoded via `@pythnetwork/client`'s
+ * `parsePriceData`. Backs the `pyth`, `pyth1K`, `pyth1M`, and `pythStableCoin` `OracleSource`
+ * variants — the `pythPull`/`pyth1KPull`/`pyth1MPull`/`pythStableCoinPull` (Pyth pull-oracle)
+ * variants have been removed from the SDK and throw in `getOracleClient`.
+ */
 export class PythClient implements OracleClient {
 	private connection: Connection;
 	private multiple: BN;
 	private stableCoin: boolean;
 
+	/**
+	 * @param connection - RPC connection used to fetch oracle account data.
+	 * @param multiple - Divisor applied to the raw Pyth precision before rescaling to
+	 * PRICE_PRECISION; pass `1000`/`1000000` for the `pyth1K`/`pyth1M` source variants (feeds
+	 * quoted per 1,000 / 1,000,000 units of the underlying), or the default `ONE` (1) for a
+	 * standard per-unit feed.
+	 * @param stableCoin - When `true` (the `pythStableCoin` variant), snaps the decoded price to
+	 * exactly `QUOTE_PRECISION` (1.0) whenever it is within 5bps (or within `confidence` if
+	 * tighter) of peg — see `getStableCoinPrice`.
+	 */
 	public constructor(
 		connection: Connection,
 		multiple = ONE,
@@ -25,6 +41,12 @@ export class PythClient implements OracleClient {
 		this.stableCoin = stableCoin;
 	}
 
+	/**
+	 * Fetches and decodes a Pyth price account's current price data.
+	 * @param pricePublicKey - The Pyth price account's address.
+	 * @returns The decoded, normalized price data.
+	 * @throws Error if the account does not exist.
+	 */
 	public async getOraclePriceData(
 		pricePublicKey: PublicKey
 	): Promise<OraclePriceData> {
@@ -36,6 +58,15 @@ export class PythClient implements OracleClient {
 		return this.getOraclePriceDataFromBuffer(data);
 	}
 
+	/**
+	 * Decodes raw Pyth price account bytes into normalized `OraclePriceData`, rescaling from
+	 * Pyth's native exponent to PRICE_PRECISION (1e6) via `convertPythPrice`. `confidence` defaults
+	 * to 0 if the account has no confidence field (e.g. uninitialized), and `hasSufficientNumberOfDataPoints`
+	 * is `true` only when the number of active quoters is at least `min(numComponentPrices, 3)`.
+	 * @param buffer - Raw Pyth price account data.
+	 * @returns `price`, `confidence`, `twap`, `twapConfidence` (all PRICE_PRECISION 1e6), `slot`
+	 * (the price account's last update slot), and `hasSufficientNumberOfDataPoints`.
+	 */
 	public getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData {
 		const priceData = parsePriceData(buffer);
 		// `confidence` is absent on uninitialized/invalid price accounts. Base passed it
@@ -86,7 +117,7 @@ function convertPythPrice(price: number, exponent: number, multiple: BN): BN {
 
 const fiveBPS = new BN(500);
 function getStableCoinPrice(price: BN, confidence: BN): BN {
-	if (price.sub(QUOTE_PRECISION).abs().lt(BN.min(confidence, fiveBPS))) {
+	if (price.sub(QUOTE_PRECISION).abs().lte(BN.min(confidence, fiveBPS))) {
 		return QUOTE_PRECISION;
 	} else {
 		return price;

package/src/oracles/pythLazerClient.ts

@@ -13,6 +13,12 @@ import { Wallet } from '../wallet';
 import velocityIDL from '../idl/velocity.json';
 import { getOracleAccountDataOrThrow } from './utils';
 
+/**
+ * `OracleClient` for `PythLazerOracle` accounts — Velocity's on-chain cache of a Pyth Lazer
+ * push-update feed, decoded via the velocity program's own Anchor coder (Lazer has no dedicated
+ * client account layout package, unlike legacy Pyth). Backs the `pythLazer`, `pythLazer1K`,
+ * `pythLazer1M`, and `pythLazerStableCoin` `OracleSource` variants.
+ */
 export class PythLazerClient implements OracleClient {
 	private connection: Connection;
 	private multiple: BN;
@@ -20,6 +26,17 @@ export class PythLazerClient implements OracleClient {
 	private program: VelocityProgram;
 	readonly decodeFunc: (name: string, data: Buffer) => any;
 
+	/**
+	 * @param connection - RPC connection used to fetch oracle account data; also used to spin up a
+	 * throwaway `AnchorProvider`/`Program` (with a fresh random keypair, never used to sign) purely
+	 * to get access to the IDL's `pythLazerOracle` account coder.
+	 * @param multiple - Divisor applied to the raw Lazer precision before rescaling to
+	 * PRICE_PRECISION; pass `1000`/`1000000` for the `pythLazer1K`/`pythLazer1M` source variants, or
+	 * the default `ONE` (1) for a standard per-unit feed.
+	 * @param stableCoin - When `true` (the `pythLazerStableCoin` variant), snaps the decoded price
+	 * to exactly `QUOTE_PRECISION` (1.0) whenever it is within 5bps (or within `confidence` if
+	 * tighter) of peg — see `getStableCoinPrice`.
+	 */
 	public constructor(
 		connection: Connection,
 		multiple = ONE,
@@ -44,6 +61,12 @@ export class PythLazerClient implements OracleClient {
 		);
 	}
 
+	/**
+	 * Fetches and decodes a `PythLazerOracle` account's current price data.
+	 * @param pricePublicKey - The `PythLazerOracle` account's address (see `getPythLazerOraclePublicKey`).
+	 * @returns The decoded, normalized price data.
+	 * @throws Error if the account does not exist.
+	 */
 	public async getOraclePriceData(
 		pricePublicKey: PublicKey
 	): Promise<OraclePriceData> {
@@ -55,6 +78,17 @@ export class PythLazerClient implements OracleClient {
 		return this.getOraclePriceDataFromBuffer(data);
 	}
 
+	/**
+	 * Decodes raw `PythLazerOracle` account bytes into normalized `OraclePriceData`, rescaling from
+	 * the feed's native exponent to PRICE_PRECISION (1e6) via `convertPythPrice`. Unlike legacy
+	 * Pyth, Lazer has no separate TWAP field on-chain, so `twap`/`twapConfidence` are both set to
+	 * the same converted live `price`/`conf` rather than a genuine time-weighted average.
+	 * `hasSufficientNumberOfDataPoints` is always `true` (no publisher-count concept for this
+	 * source), and `sequenceId` is set to the feed's `publishTime` for staleness/ordering checks.
+	 * @param buffer - Raw `PythLazerOracle` account data.
+	 * @returns `price`, `confidence`, `twap`, `twapConfidence` (all PRICE_PRECISION 1e6), `slot`
+	 * (`postedSlot`, the slot the update landed on-chain), and `sequenceId` (`publishTime`).
+	 */
 	public getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData {
 		const priceData = this.decodeFunc('pythLazerOracle', buffer);
 		const confidence = convertPythPrice(
@@ -99,7 +133,7 @@ function convertPythPrice(price: BN, exponent: number, multiple: BN): BN {
 
 const fiveBPS = new BN(500);
 function getStableCoinPrice(price: BN, confidence: BN): BN {
-	if (price.sub(QUOTE_PRECISION).abs().lt(BN.min(confidence, fiveBPS))) {
+	if (price.sub(QUOTE_PRECISION).abs().lte(BN.min(confidence, fiveBPS))) {
 		return QUOTE_PRECISION;
 	} else {
 		return price;

package/src/oracles/quoteAssetOracleClient.ts

@@ -3,6 +3,11 @@ import { OracleClient, OraclePriceData } from './types';
 import { BN } from '../isomorphic/anchor';
 import { PRICE_PRECISION } from '../constants/numericConstants';
 
+/**
+ * Fixed price of exactly 1.0 (PRICE_PRECISION, 1e6) with a minimal confidence band, returned by
+ * `QuoteAssetOracleClient` for any oracle lookup. Represents the quote asset (e.g. USDC) pegged
+ * 1:1 to itself with no real oracle needed.
+ */
 export const QUOTE_ORACLE_PRICE_DATA: OraclePriceData = {
 	price: PRICE_PRECISION,
 	slot: new BN(0),
@@ -10,15 +15,28 @@ export const QUOTE_ORACLE_PRICE_DATA: OraclePriceData = {
 	hasSufficientNumberOfDataPoints: true,
 };
 
+/**
+ * `OracleClient` for the `quoteAsset` `OracleSource` variant — the spot market whose asset *is*
+ * the protocol's quote currency. Ignores its inputs entirely and always returns the constant
+ * `QUOTE_ORACLE_PRICE_DATA` (price 1.0); never makes an RPC call.
+ */
 export class QuoteAssetOracleClient implements OracleClient {
 	public constructor() {}
 
+	/**
+	 * @param _pricePublicKey - Ignored.
+	 * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+	 */
 	public async getOraclePriceData(
 		_pricePublicKey: PublicKey
 	): Promise<OraclePriceData> {
 		return Promise.resolve(QUOTE_ORACLE_PRICE_DATA);
 	}
 
+	/**
+	 * @param _buffer - Ignored.
+	 * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+	 */
 	public getOraclePriceDataFromBuffer(_buffer: Buffer): OraclePriceData {
 		return QUOTE_ORACLE_PRICE_DATA;
 	}

package/src/oracles/strictOraclePrice.ts

@@ -1,18 +1,39 @@
 import { BN } from '../isomorphic/anchor';
 
+/**
+ * Pairs a live oracle price with its 5-minute TWAP so margin/value calculations can pick whichever
+ * is more conservative — mirroring the on-chain "strict" price used for collateral valuation, which
+ * exists so a transient price spike/dip can't be used to over-value collateral or under-value a
+ * liability. All values are PRICE_PRECISION (1e6).
+ */
 export class StrictOraclePrice {
 	current: BN;
 	twap?: BN;
 
+	/**
+	 * @param current - Live oracle price, PRICE_PRECISION (1e6).
+	 * @param twap - 5-minute oracle TWAP, PRICE_PRECISION (1e6). If omitted, `max()`/`min()` both
+	 * fall back to `current`.
+	 */
 	constructor(current: BN, twap?: BN) {
 		this.current = current;
 		this.twap = twap;
 	}
 
+	/**
+	 * The higher of `current` and `twap` — use when a higher price is the conservative choice
+	 * (e.g. valuing a liability/borrow, where undervaluing it would overstate free collateral).
+	 * @returns The larger of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+	 */
 	public max(): BN {
 		return this.twap ? BN.max(this.twap, this.current) : this.current;
 	}
 
+	/**
+	 * The lower of `current` and `twap` — use when a lower price is the conservative choice (e.g.
+	 * valuing a deposit/asset, where overvaluing it would overstate free collateral).
+	 * @returns The smaller of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+	 */
 	public min(): BN {
 		return this.twap ? BN.min(this.twap, this.current) : this.current;
 	}