@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/memcmp.js

@@ -7,6 +7,11 @@ exports.getConstituentLpPoolFilter = exports.getConstituentFilter = exports.getR
 const bs58_1 = __importDefault(require("bs58"));
 const anchor29_1 = require("./isomorphic/anchor29");
 const userName_1 = require("./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.
+ */
 function getUserFilter() {
     return {
         memcmp: {
@@ -37,6 +42,12 @@ 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.
+ */
 function getNonIdleUserFilter() {
     return {
         memcmp: {
@@ -46,6 +57,12 @@ function getNonIdleUserFilter() {
     };
 }
 exports.getNonIdleUserFilter = getNonIdleUserFilter;
+/**
+ * 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.
+ */
 function getUserWithOrderFilter() {
     return {
         memcmp: {
@@ -55,6 +72,11 @@ function getUserWithOrderFilter() {
     };
 }
 exports.getUserWithOrderFilter = getUserWithOrderFilter;
+/**
+ * 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.
+ */
 function getUserWithoutOrderFilter() {
     return {
         memcmp: {
@@ -64,6 +86,11 @@ function getUserWithoutOrderFilter() {
     };
 }
 exports.getUserWithoutOrderFilter = getUserWithoutOrderFilter;
+/**
+ * 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.
+ */
 function getUserWithAuctionFilter() {
     return {
         memcmp: {
@@ -73,6 +100,13 @@ function getUserWithAuctionFilter() {
     };
 }
 exports.getUserWithAuctionFilter = getUserWithAuctionFilter;
+/**
+ * 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.
+ */
 function getUserWithName(name) {
     return {
         memcmp: {
@@ -82,6 +116,12 @@ function getUserWithName(name) {
     };
 }
 exports.getUserWithName = getUserWithName;
+/**
+ * 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.
+ */
 function getUsersWithPoolId(poolId) {
     return {
         memcmp: {
@@ -91,6 +131,11 @@ function getUsersWithPoolId(poolId) {
     };
 }
 exports.getUsersWithPoolId = getUsersWithPoolId;
+/**
+ * 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.
+ */
 function getUserStatsFilter() {
     return {
         memcmp: {
@@ -100,24 +145,53 @@ function getUserStatsFilter() {
     };
 }
 exports.getUserStatsFilter = getUserStatsFilter;
+/*
+ * 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.
+ */
 function getUserStatsIsReferredFilter() {
     return {
         memcmp: {
-            offset: 188,
+            offset: USER_STATS_REFERRER_STATUS_OFFSET,
             bytes: bs58_1.default.encode(Buffer.from(Uint8Array.from([2]))),
         },
     };
 }
 exports.getUserStatsIsReferredFilter = getUserStatsIsReferredFilter;
+/**
+ * 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.
+ */
 function getUserStatsIsReferredOrReferrerFilter() {
     return {
         memcmp: {
-            offset: 188,
+            offset: USER_STATS_REFERRER_STATUS_OFFSET,
             bytes: bs58_1.default.encode(Buffer.from(Uint8Array.from([3]))),
         },
     };
 }
 exports.getUserStatsIsReferredOrReferrerFilter = getUserStatsIsReferredOrReferrerFilter;
+/**
+ * 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.
+ */
 function getSignedMsgUserOrdersFilter() {
     return {
         memcmp: {
@@ -127,6 +201,11 @@ function getSignedMsgUserOrdersFilter() {
     };
 }
 exports.getSignedMsgUserOrdersFilter = getSignedMsgUserOrdersFilter;
+/**
+ * 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.
+ */
 function getPerpMarketAccountsFilter() {
     return {
         memcmp: {
@@ -136,6 +215,11 @@ function getPerpMarketAccountsFilter() {
     };
 }
 exports.getPerpMarketAccountsFilter = getPerpMarketAccountsFilter;
+/**
+ * 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.
+ */
 function getSpotMarketAccountsFilter() {
     return {
         memcmp: {
@@ -145,6 +229,12 @@ function getSpotMarketAccountsFilter() {
     };
 }
 exports.getSpotMarketAccountsFilter = getSpotMarketAccountsFilter;
+/**
+ * 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.
+ */
 function getRevenueShareEscrowFilter() {
     return {
         memcmp: {
@@ -154,6 +244,11 @@ function getRevenueShareEscrowFilter() {
     };
 }
 exports.getRevenueShareEscrowFilter = getRevenueShareEscrowFilter;
+/**
+ * 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.
+ */
 function getConstituentFilter() {
     return {
         memcmp: {
@@ -163,6 +258,12 @@ function getConstituentFilter() {
     };
 }
 exports.getConstituentFilter = getConstituentFilter;
+/**
+ * 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.
+ */
 function getConstituentLpPoolFilter(lpPoolPublicKey) {
     return {
         memcmp: {

package/lib/browser/oracles/oracleClientCache.d.ts

@@ -2,8 +2,24 @@ import { OracleClient } from './types';
 import { OracleSource } from '../types';
 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 declare class OracleClientCache {
     cache: Map<string, OracleClient>;
     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.
+     */
     get(oracleSource: OracleSource, connection: Connection, program: VelocityProgram): OracleClient | undefined;
 }

package/lib/browser/oracles/oracleClientCache.js

@@ -2,10 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OracleClientCache = void 0;
 const oracleClient_1 = require("../factory/oracleClient");
+/**
+ * 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.
+ */
 class OracleClientCache {
     constructor() {
         this.cache = new Map();
     }
+    /**
+     * 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.
+     */
     get(oracleSource, connection, program) {
         const key = Object.keys(oracleSource)[0];
         if (this.cache.has(key)) {

package/lib/browser/oracles/oracleId.d.ts

@@ -1,8 +1,39 @@
 import { PublicKey } from '@solana/web3.js';
 import { OracleSource } 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 declare function getOracleSourceNum(source: OracleSource): number;
+/**
+ * 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 declare function getOracleSourceFromNum(sourceNum: number): OracleSource;
+/**
+ * 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 declare function getOracleId(publicKey: PublicKey, source: OracleSource): string;
+/**
+ * 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 declare function getPublicKeyAndSourceFromOracleId(oracleId: string): {
     publicKey: PublicKey;
     source: OracleSource;

package/lib/browser/oracles/oracleId.js

@@ -3,6 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPublicKeyAndSourceFromOracleId = exports.getOracleId = exports.getOracleSourceFromNum = exports.getOracleSourceNum = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const types_1 = require("../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.
+ */
 function getOracleSourceNum(source) {
     if ('pyth' in source)
         return types_1.OracleSourceNum.PYTH;
@@ -16,8 +24,8 @@ function getOracleSourceNum(source) {
         return types_1.OracleSourceNum.PYTH_1K_PULL;
     if ('pyth1MPull' in source)
         return types_1.OracleSourceNum.PYTH_1M_PULL;
-    if ('switchboard' in source)
-        return types_1.OracleSourceNum.SWITCHBOARD;
+    if ('deprecatedSwitchboard' in source)
+        return types_1.OracleSourceNum.DEPRECATED_SWITCHBOARD;
     if ('quoteAsset' in source)
         return types_1.OracleSourceNum.QUOTE_ASSET;
     if ('pythStableCoin' in source)
@@ -26,8 +34,8 @@ function getOracleSourceNum(source) {
         return types_1.OracleSourceNum.PYTH_STABLE_COIN_PULL;
     if ('prelaunch' in source)
         return types_1.OracleSourceNum.PRELAUNCH;
-    if ('switchboardOnDemand' in source)
-        return types_1.OracleSourceNum.SWITCHBOARD_ON_DEMAND;
+    if ('deprecatedSwitchboardOnDemand' in source)
+        return types_1.OracleSourceNum.DEPRECATED_SWITCHBOARD_ON_DEMAND;
     if ('pythLazer' in source)
         return types_1.OracleSourceNum.PYTH_LAZER;
     if ('pythLazer1K' in source)
@@ -39,6 +47,13 @@ function getOracleSourceNum(source) {
     throw new Error('Invalid oracle source');
 }
 exports.getOracleSourceNum = getOracleSourceNum;
+/**
+ * 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.
+ */
 function getOracleSourceFromNum(sourceNum) {
     if (sourceNum === types_1.OracleSourceNum.PYTH)
         return 'pyth';
@@ -52,8 +67,8 @@ function getOracleSourceFromNum(sourceNum) {
         return 'pyth1KPull';
     if (sourceNum === types_1.OracleSourceNum.PYTH_1M_PULL)
         return 'pyth1MPull';
-    if (sourceNum === types_1.OracleSourceNum.SWITCHBOARD)
-        return 'switchboard';
+    if (sourceNum === types_1.OracleSourceNum.DEPRECATED_SWITCHBOARD)
+        return 'deprecatedSwitchboard';
     if (sourceNum === types_1.OracleSourceNum.QUOTE_ASSET)
         return 'quoteAsset';
     if (sourceNum === types_1.OracleSourceNum.PYTH_STABLE_COIN)
@@ -62,8 +77,8 @@ function getOracleSourceFromNum(sourceNum) {
         return 'pythStableCoinPull';
     if (sourceNum === types_1.OracleSourceNum.PRELAUNCH)
         return 'prelaunch';
-    if (sourceNum === types_1.OracleSourceNum.SWITCHBOARD_ON_DEMAND)
-        return 'switchboardOnDemand';
+    if (sourceNum === types_1.OracleSourceNum.DEPRECATED_SWITCHBOARD_ON_DEMAND)
+        return 'deprecatedSwitchboardOnDemand';
     if (sourceNum === types_1.OracleSourceNum.PYTH_LAZER)
         return 'pythLazer';
     if (sourceNum === types_1.OracleSourceNum.PYTH_LAZER_1K)
@@ -75,10 +90,26 @@ function getOracleSourceFromNum(sourceNum) {
     throw new Error('Invalid oracle source');
 }
 exports.getOracleSourceFromNum = getOracleSourceFromNum;
+/**
+ * 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>"`.
+ */
 function getOracleId(publicKey, source) {
     return `${publicKey.toBase58()}-${getOracleSourceNum(source)}`;
 }
 exports.getOracleId = getOracleId;
+/**
+ * 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.
+ */
 function getPublicKeyAndSourceFromOracleId(oracleId) {
     const [publicKey, source] = oracleId.split('-');
     return {

package/lib/browser/oracles/prelaunchOracleClient.d.ts

@@ -3,10 +3,30 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { OracleClient, OraclePriceData } from './types';
 import { VelocityProgram } from '../config';
+/**
+ * `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 declare class PrelaunchOracleClient implements OracleClient {
     private connection;
     private program;
     constructor(connection: Connection, program: VelocityProgram);
+    /**
+     * 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.
+     */
     getOraclePriceData(pricePublicKey: PublicKey): Promise<OraclePriceData>;
+    /**
+     * 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).
+     */
     getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData;
 }

package/lib/browser/oracles/prelaunchOracleClient.js

@@ -2,15 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrelaunchOracleClient = void 0;
 const utils_1 = require("./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.
+ */
 class PrelaunchOracleClient {
     constructor(connection, program) {
         this.connection = connection;
         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.
+     */
     async getOraclePriceData(pricePublicKey) {
         const data = await (0, utils_1.getOracleAccountDataOrThrow)(this.connection, pricePublicKey, 'Prelaunch oracle');
         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).
+     */
     getOraclePriceDataFromBuffer(buffer) {
         const prelaunchOracle = this.program.account.prelaunchOracle.coder.accounts.decodeUnchecked('prelaunchOracle', buffer);
         return {

package/lib/browser/oracles/pythClient.d.ts

@@ -3,11 +3,42 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { OracleClient, OraclePriceData } from './types';
 import { BN } from '../isomorphic/anchor';
+/**
+ * `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 declare class PythClient implements OracleClient {
     private connection;
     private multiple;
     private stableCoin;
+    /**
+     * @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`.
+     */
     constructor(connection: Connection, multiple?: BN, stableCoin?: boolean);
+    /**
+     * 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.
+     */
     getOraclePriceData(pricePublicKey: PublicKey): Promise<OraclePriceData>;
+    /**
+     * 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`.
+     */
     getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData;
 }

package/lib/browser/oracles/pythClient.js

@@ -5,16 +5,47 @@ const client_1 = require("@pythnetwork/client");
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
 const utils_1 = require("./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`.
+ */
 class PythClient {
+    /**
+     * @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`.
+     */
     constructor(connection, multiple = numericConstants_1.ONE, stableCoin = false) {
         this.connection = connection;
         this.multiple = multiple;
         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.
+     */
     async getOraclePriceData(pricePublicKey) {
         const data = await (0, utils_1.getOracleAccountDataOrThrow)(this.connection, pricePublicKey, 'Pyth oracle');
         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`.
+     */
     getOraclePriceDataFromBuffer(buffer) {
         var _a;
         const priceData = (0, client_1.parsePriceData)(buffer);
@@ -48,7 +79,7 @@ function convertPythPrice(price, exponent, multiple) {
 }
 const fiveBPS = new anchor_1.BN(500);
 function getStableCoinPrice(price, confidence) {
-    if (price.sub(numericConstants_1.QUOTE_PRECISION).abs().lt(anchor_1.BN.min(confidence, fiveBPS))) {
+    if (price.sub(numericConstants_1.QUOTE_PRECISION).abs().lte(anchor_1.BN.min(confidence, fiveBPS))) {
         return numericConstants_1.QUOTE_PRECISION;
     }
     else {

package/lib/browser/oracles/pythLazerClient.d.ts

@@ -3,13 +3,47 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { OracleClient, OraclePriceData } from './types';
 import { BN } from '../isomorphic/anchor';
+/**
+ * `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 declare class PythLazerClient implements OracleClient {
     private connection;
     private multiple;
     private stableCoin;
     private program;
     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`.
+     */
     constructor(connection: Connection, multiple?: BN, stableCoin?: boolean);
+    /**
+     * 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.
+     */
     getOraclePriceData(pricePublicKey: PublicKey): Promise<OraclePriceData>;
+    /**
+     * 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`).
+     */
     getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData;
 }