@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/addresses/pda.js

@@ -26,34 +26,67 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLpPoolTokenTokenAccountPublicKey = exports.getConstituentCorrelationsPublicKey = exports.getAmmCachePublicKey = exports.getConstituentVaultPublicKey = exports.getConstituentPublicKey = exports.getConstituentTargetBasePublicKey = exports.getAmmConstituentMappingPublicKey = exports.getLpPoolTokenVaultPublicKey = exports.getLpPoolPublicKey = exports.getRevenueShareEscrowAccountPublicKey = exports.getRevenueShareAccountPublicKey = exports.getTokenProgramForSpotMarket = exports.getPythLazerOraclePublicKey = exports.getPrelaunchOraclePublicKey = exports.getReferrerNamePublicKeySync = exports.getVelocitySignerPublicKey = exports.getInsuranceFundStakeAccountPublicKey = exports.getInsuranceFundVaultPublicKey = exports.getSpotMarketVaultPublicKey = exports.getSpotMarketPublicKeySync = exports.getSpotMarketPublicKey = exports.getPerpMarketPublicKeySync = exports.getPerpMarketPublicKey = exports.getSignedMsgWsDelegatesAccountPublicKey = exports.getSignedMsgUserAccountPublicKey = exports.getUserStatsAccountPublicKey = exports.getUserAccountPublicKeySync = exports.getUserAccountPublicKey = exports.getUserAccountPublicKeyAndNonce = exports.getVelocityStateAccountPublicKey = exports.getVelocityStateAccountPublicKeyAndNonce = void 0;
 /**
  * PDA derivation helpers for all Velocity protocol accounts.
- * Covers: User, UserStats, PerpMarket, SpotMarket, InsuranceFundStake,
- * HighLeverageModeConfig, State, and vault PDAs.
+ * Covers: User, UserStats, PerpMarket, SpotMarket, InsuranceFundStake, State,
+ * LP pool (and its constituents/caches), revenue share, and vault PDAs.
  * All functions are pure (no RPC calls).
  */
 const web3_js_1 = require("@solana/web3.js");
 const anchor = __importStar(require("../isomorphic/anchor"));
 const spl_token_1 = require("@solana/spl-token");
 const types_1 = require("../types");
+/**
+ * Derives the singleton `State` account PDA (seed `"velocity_state"`), plus its bump nonce. There
+ * is exactly one `State` account per program deployment.
+ * @param programId - Deployed velocity program id.
+ * @returns Tuple of `[stateAccountPublicKey, bumpNonce]`.
+ */
 async function getVelocityStateAccountPublicKeyAndNonce(programId) {
-    return web3_js_1.PublicKey.findProgramAddress([Buffer.from(anchor.utils.bytes.utf8.encode('velocity_state'))], programId);
+    return Promise.resolve(web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(anchor.utils.bytes.utf8.encode('velocity_state'))], programId));
 }
 exports.getVelocityStateAccountPublicKeyAndNonce = getVelocityStateAccountPublicKeyAndNonce;
+/**
+ * Derives the singleton `State` account PDA (seed `"velocity_state"`).
+ * @param programId - Deployed velocity program id.
+ * @returns The `State` account's public key.
+ */
 async function getVelocityStateAccountPublicKey(programId) {
     return (await getVelocityStateAccountPublicKeyAndNonce(programId))[0];
 }
 exports.getVelocityStateAccountPublicKey = getVelocityStateAccountPublicKey;
+/**
+ * Derives a `User` (sub-account) PDA, plus its bump nonce, from seeds `["user", authority,
+ * subAccountId as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey that owns the sub-account.
+ * @param subAccountId - Sub-account index (u16); defaults to 0, the wallet's first/main sub-account.
+ * @returns Tuple of `[userAccountPublicKey, bumpNonce]`.
+ */
 async function getUserAccountPublicKeyAndNonce(programId, authority, subAccountId = 0) {
-    return web3_js_1.PublicKey.findProgramAddress([
+    return Promise.resolve(web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('user')),
         authority.toBuffer(),
         new anchor.BN(subAccountId).toArrayLike(Buffer, 'le', 2),
-    ], programId);
+    ], programId));
 }
 exports.getUserAccountPublicKeyAndNonce = getUserAccountPublicKeyAndNonce;
+/**
+ * Derives a `User` (sub-account) PDA from seeds `["user", authority, subAccountId as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey that owns the sub-account.
+ * @param subAccountId - Sub-account index (u16); defaults to 0, the wallet's first/main sub-account.
+ * @returns The `User` account's public key.
+ */
 async function getUserAccountPublicKey(programId, authority, subAccountId = 0) {
     return (await getUserAccountPublicKeyAndNonce(programId, authority, subAccountId))[0];
 }
 exports.getUserAccountPublicKey = getUserAccountPublicKey;
+/**
+ * Synchronous variant of `getUserAccountPublicKey` (no RPC/async round-trip; pure PDA math).
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey that owns the sub-account.
+ * @param subAccountId - Sub-account index (u16); defaults to 0.
+ * @returns The `User` account's public key.
+ */
 function getUserAccountPublicKeySync(programId, authority, subAccountId = 0) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('user')),
@@ -62,6 +95,13 @@ function getUserAccountPublicKeySync(programId, authority, subAccountId = 0) {
     ], programId)[0];
 }
 exports.getUserAccountPublicKeySync = getUserAccountPublicKeySync;
+/**
+ * Derives the `UserStats` PDA (one per authority, shared across all of that authority's
+ * sub-accounts) from seeds `["user_stats", authority]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey the stats account tracks.
+ * @returns The `UserStats` account's public key.
+ */
 function getUserStatsAccountPublicKey(programId, authority) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('user_stats')),
@@ -69,6 +109,13 @@ function getUserStatsAccountPublicKey(programId, authority) {
     ], programId)[0];
 }
 exports.getUserStatsAccountPublicKey = getUserStatsAccountPublicKey;
+/**
+ * Derives the `SignedMsgUserOrders` PDA (holds a user's pending swift/signed-message orders) from
+ * seeds `["SIGNED_MSG", authority]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey (the user's main authority, not the sub-account) that owns the account.
+ * @returns The `SignedMsgUserOrders` account's public key.
+ */
 function getSignedMsgUserAccountPublicKey(programId, authority) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('SIGNED_MSG')),
@@ -76,6 +123,13 @@ function getSignedMsgUserAccountPublicKey(programId, authority) {
     ], programId)[0];
 }
 exports.getSignedMsgUserAccountPublicKey = getSignedMsgUserAccountPublicKey;
+/**
+ * Derives the PDA that stores a user's approved signed-message (swift) websocket delegate keys,
+ * from seeds `["SIGNED_MSG_WS", authority]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey (the user's main authority) that owns the delegates account.
+ * @returns The delegates account's public key.
+ */
 function getSignedMsgWsDelegatesAccountPublicKey(programId, authority) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('SIGNED_MSG_WS')),
@@ -83,6 +137,12 @@ function getSignedMsgWsDelegatesAccountPublicKey(programId, authority) {
     ], programId)[0];
 }
 exports.getSignedMsgWsDelegatesAccountPublicKey = getSignedMsgWsDelegatesAccountPublicKey;
+/**
+ * Derives a `PerpMarket` PDA from seeds `["perp_market", marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Perp market index.
+ * @returns The `PerpMarket` account's public key.
+ */
 async function getPerpMarketPublicKey(programId, marketIndex) {
     return (await web3_js_1.PublicKey.findProgramAddress([
         Buffer.from(anchor.utils.bytes.utf8.encode('perp_market')),
@@ -90,6 +150,12 @@ async function getPerpMarketPublicKey(programId, marketIndex) {
     ], programId))[0];
 }
 exports.getPerpMarketPublicKey = getPerpMarketPublicKey;
+/**
+ * Synchronous variant of `getPerpMarketPublicKey`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Perp market index.
+ * @returns The `PerpMarket` account's public key.
+ */
 function getPerpMarketPublicKeySync(programId, marketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('perp_market')),
@@ -97,6 +163,12 @@ function getPerpMarketPublicKeySync(programId, marketIndex) {
     ], programId)[0];
 }
 exports.getPerpMarketPublicKeySync = getPerpMarketPublicKeySync;
+/**
+ * Derives a `SpotMarket` PDA from seeds `["spot_market", marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Spot market index.
+ * @returns The `SpotMarket` account's public key.
+ */
 async function getSpotMarketPublicKey(programId, marketIndex) {
     return (await web3_js_1.PublicKey.findProgramAddress([
         Buffer.from(anchor.utils.bytes.utf8.encode('spot_market')),
@@ -104,6 +176,12 @@ async function getSpotMarketPublicKey(programId, marketIndex) {
     ], programId))[0];
 }
 exports.getSpotMarketPublicKey = getSpotMarketPublicKey;
+/**
+ * Synchronous variant of `getSpotMarketPublicKey`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Spot market index.
+ * @returns The `SpotMarket` account's public key.
+ */
 function getSpotMarketPublicKeySync(programId, marketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('spot_market')),
@@ -111,6 +189,13 @@ function getSpotMarketPublicKeySync(programId, marketIndex) {
     ], programId)[0];
 }
 exports.getSpotMarketPublicKeySync = getSpotMarketPublicKeySync;
+/**
+ * Derives the token vault PDA (an SPL/Token-2022 token account owned by the `velocity_signer` PDA)
+ * that custodies a spot market's deposits, from seeds `["spot_market_vault", marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Spot market index.
+ * @returns The spot market vault token account's public key.
+ */
 async function getSpotMarketVaultPublicKey(programId, marketIndex) {
     return (await web3_js_1.PublicKey.findProgramAddress([
         Buffer.from(anchor.utils.bytes.utf8.encode('spot_market_vault')),
@@ -118,6 +203,13 @@ async function getSpotMarketVaultPublicKey(programId, marketIndex) {
     ], programId))[0];
 }
 exports.getSpotMarketVaultPublicKey = getSpotMarketVaultPublicKey;
+/**
+ * Derives the insurance fund's token vault PDA for a market, from seeds `["insurance_fund_vault",
+ * marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Spot market index whose insurance fund this vault backs.
+ * @returns The insurance fund vault token account's public key.
+ */
 async function getInsuranceFundVaultPublicKey(programId, marketIndex) {
     return (await web3_js_1.PublicKey.findProgramAddress([
         Buffer.from(anchor.utils.bytes.utf8.encode('insurance_fund_vault')),
@@ -125,6 +217,14 @@ async function getInsuranceFundVaultPublicKey(programId, marketIndex) {
     ], programId))[0];
 }
 exports.getInsuranceFundVaultPublicKey = getInsuranceFundVaultPublicKey;
+/**
+ * Derives an `InsuranceFundStake` PDA (an authority's staked share of one market's insurance fund)
+ * from seeds `["insurance_fund_stake", authority, marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey staking into the insurance fund.
+ * @param marketIndex - Spot market index whose insurance fund is being staked into.
+ * @returns The `InsuranceFundStake` account's public key.
+ */
 function getInsuranceFundStakeAccountPublicKey(programId, authority, marketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('insurance_fund_stake')),
@@ -133,10 +233,23 @@ function getInsuranceFundStakeAccountPublicKey(programId, authority, marketIndex
     ], programId)[0];
 }
 exports.getInsuranceFundStakeAccountPublicKey = getInsuranceFundStakeAccountPublicKey;
+/**
+ * Derives the singleton `velocity_signer` PDA — the program-derived authority that owns/signs for
+ * all program-controlled token vaults (spot market vaults, insurance fund vaults, etc.) via CPI.
+ * @param programId - Deployed velocity program id.
+ * @returns The velocity signer PDA's public key.
+ */
 function getVelocitySignerPublicKey(programId) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(anchor.utils.bytes.utf8.encode('velocity_signer'))], programId)[0];
 }
 exports.getVelocitySignerPublicKey = getVelocitySignerPublicKey;
+/**
+ * Derives the PDA that reserves a unique referrer name, from seeds `["referrer_name", nameBuffer]`.
+ * Used to enforce name uniqueness for referrers on-chain.
+ * @param programId - Deployed velocity program id.
+ * @param nameBuffer - The 32-byte encoded name (see `encodeName`) to reserve.
+ * @returns The referrer-name PDA's public key.
+ */
 function getReferrerNamePublicKeySync(programId, nameBuffer) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('referrer_name')),
@@ -144,6 +257,13 @@ function getReferrerNamePublicKeySync(programId, nameBuffer) {
     ], programId)[0];
 }
 exports.getReferrerNamePublicKeySync = getReferrerNamePublicKeySync;
+/**
+ * Derives the `PrelaunchOracle` PDA used as a placeholder/synthetic oracle for a not-yet-listed
+ * perp market, from seeds `["prelaunch_oracle", marketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Perp market index the prelaunch oracle backs.
+ * @returns The `PrelaunchOracle` account's public key.
+ */
 function getPrelaunchOraclePublicKey(programId, marketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('prelaunch_oracle')),
@@ -151,6 +271,13 @@ function getPrelaunchOraclePublicKey(programId, marketIndex) {
     ], programId)[0];
 }
 exports.getPrelaunchOraclePublicKey = getPrelaunchOraclePublicKey;
+/**
+ * Derives a Pyth Lazer oracle account PDA from seeds `["pyth_lazer", feedId as u32 LE]`. One
+ * account exists per Lazer feed id and is shared across all markets using that feed.
+ * @param progarmId - Deployed velocity program id (note: parameter name is misspelled but stable API).
+ * @param feedId - Pyth Lazer feed id (u32).
+ * @returns The Pyth Lazer oracle account's public key.
+ */
 function getPythLazerOraclePublicKey(progarmId, feedId) {
     const buffer = new ArrayBuffer(4);
     const view = new DataView(buffer);
@@ -162,6 +289,13 @@ function getPythLazerOraclePublicKey(progarmId, feedId) {
     ], progarmId)[0];
 }
 exports.getPythLazerOraclePublicKey = getPythLazerOraclePublicKey;
+/**
+ * Picks the correct SPL token program for a spot market's mint, based on its `tokenProgramFlag`.
+ * Needed because Velocity supports both classic SPL tokens and Token-2022 mints; passing the wrong
+ * token program id to an instruction's accounts will fail owner checks.
+ * @param spotMarketAccount - The spot market to inspect.
+ * @returns `TOKEN_2022_PROGRAM_ID` if `TokenProgramFlag.Token2022` is set, otherwise `TOKEN_PROGRAM_ID`.
+ */
 function getTokenProgramForSpotMarket(spotMarketAccount) {
     if ((spotMarketAccount.tokenProgramFlag & types_1.TokenProgramFlag.Token2022) > 0) {
         return spl_token_1.TOKEN_2022_PROGRAM_ID;
@@ -169,6 +303,13 @@ function getTokenProgramForSpotMarket(spotMarketAccount) {
     return spl_token_1.TOKEN_PROGRAM_ID;
 }
 exports.getTokenProgramForSpotMarket = getTokenProgramForSpotMarket;
+/**
+ * Derives a builder/referrer's `RevenueShare` PDA from seeds `["REV_SHARE", authority]`. Tracks
+ * fees a builder/referrer has accrued from orders that credited them.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey of the builder/referrer.
+ * @returns The `RevenueShare` account's public key.
+ */
 function getRevenueShareAccountPublicKey(programId, authority) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('REV_SHARE')),
@@ -176,6 +317,14 @@ function getRevenueShareAccountPublicKey(programId, authority) {
     ], programId)[0];
 }
 exports.getRevenueShareAccountPublicKey = getRevenueShareAccountPublicKey;
+/**
+ * Derives a user's `RevenueShareEscrow` PDA from seeds `["REV_ESCROW", authority]`. Holds the
+ * user's referrer link and approved builder-fee list; required as a remaining account whenever a
+ * placed order references a `builderIdx`/builder fee, or when a taker was referred.
+ * @param programId - Deployed velocity program id.
+ * @param authority - Wallet pubkey of the user (order placer), not the builder/referrer.
+ * @returns The `RevenueShareEscrow` account's public key.
+ */
 function getRevenueShareEscrowAccountPublicKey(programId, authority) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('REV_ESCROW')),
@@ -183,6 +332,12 @@ function getRevenueShareEscrowAccountPublicKey(programId, authority) {
     ], programId)[0];
 }
 exports.getRevenueShareEscrowAccountPublicKey = getRevenueShareEscrowAccountPublicKey;
+/**
+ * Derives an `LpPool` PDA from seeds `["lp_pool", lpPoolId as u8 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolId - Single-byte LP pool id.
+ * @returns The `LpPool` account's public key.
+ */
 function getLpPoolPublicKey(programId, lpPoolId) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('lp_pool')),
@@ -190,6 +345,13 @@ function getLpPoolPublicKey(programId, lpPoolId) {
     ], programId)[0];
 }
 exports.getLpPoolPublicKey = getLpPoolPublicKey;
+/**
+ * Derives the token vault PDA holding an `LpPool`'s minted LP token supply's backing, from seeds
+ * `["LP_POOL_TOKEN_VAULT", lpPool]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPool - The `LpPool` account's public key.
+ * @returns The LP pool token vault's public key.
+ */
 function getLpPoolTokenVaultPublicKey(programId, lpPool) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('LP_POOL_TOKEN_VAULT')),
@@ -197,6 +359,13 @@ function getLpPoolTokenVaultPublicKey(programId, lpPool) {
     ], programId)[0];
 }
 exports.getLpPoolTokenVaultPublicKey = getLpPoolTokenVaultPublicKey;
+/**
+ * Derives the `AmmConstituentMapping` PDA (maps LP-pool constituents to the perp AMMs they hedge)
+ * from seeds `["AMM_MAP", lpPoolPublicKey]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolPublicKey - The `LpPool` account's public key.
+ * @returns The `AmmConstituentMapping` account's public key.
+ */
 function getAmmConstituentMappingPublicKey(programId, lpPoolPublicKey) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('AMM_MAP')),
@@ -204,6 +373,13 @@ function getAmmConstituentMappingPublicKey(programId, lpPoolPublicKey) {
     ], programId)[0];
 }
 exports.getAmmConstituentMappingPublicKey = getAmmConstituentMappingPublicKey;
+/**
+ * Derives the `ConstituentTargetBase` PDA (target base-asset weights for an LP pool's
+ * constituents) from seeds `["constituent_target_base_seed", lpPoolPublicKey]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolPublicKey - The `LpPool` account's public key.
+ * @returns The `ConstituentTargetBase` account's public key.
+ */
 function getConstituentTargetBasePublicKey(programId, lpPoolPublicKey) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('constituent_target_base_seed')),
@@ -211,6 +387,14 @@ function getConstituentTargetBasePublicKey(programId, lpPoolPublicKey) {
     ], programId)[0];
 }
 exports.getConstituentTargetBasePublicKey = getConstituentTargetBasePublicKey;
+/**
+ * Derives a `Constituent` PDA (one per spot market backing an LP pool) from seeds `["CONSTITUENT",
+ * lpPoolPublicKey, spotMarketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolPublicKey - The `LpPool` account's public key.
+ * @param spotMarketIndex - Spot market index of this constituent.
+ * @returns The `Constituent` account's public key.
+ */
 function getConstituentPublicKey(programId, lpPoolPublicKey, spotMarketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('CONSTITUENT')),
@@ -219,6 +403,14 @@ function getConstituentPublicKey(programId, lpPoolPublicKey, spotMarketIndex) {
     ], programId)[0];
 }
 exports.getConstituentPublicKey = getConstituentPublicKey;
+/**
+ * Derives the token vault PDA that custodies a `Constituent`'s deposits, from seeds
+ * `["CONSTITUENT_VAULT", lpPoolPublicKey, spotMarketIndex as u16 LE]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolPublicKey - The `LpPool` account's public key.
+ * @param spotMarketIndex - Spot market index of the constituent this vault backs.
+ * @returns The constituent vault token account's public key.
+ */
 function getConstituentVaultPublicKey(programId, lpPoolPublicKey, spotMarketIndex) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('CONSTITUENT_VAULT')),
@@ -227,10 +419,23 @@ function getConstituentVaultPublicKey(programId, lpPoolPublicKey, spotMarketInde
     ], programId)[0];
 }
 exports.getConstituentVaultPublicKey = getConstituentVaultPublicKey;
+/**
+ * Derives the singleton `AmmCache` PDA (caches per-AMM data used by LP-pool hedging/settlement)
+ * from seed `"amm_cache_seed"`. One per program deployment.
+ * @param programId - Deployed velocity program id.
+ * @returns The `AmmCache` account's public key.
+ */
 function getAmmCachePublicKey(programId) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(anchor.utils.bytes.utf8.encode('amm_cache_seed'))], programId)[0];
 }
 exports.getAmmCachePublicKey = getAmmCachePublicKey;
+/**
+ * Derives the `ConstituentCorrelations` PDA (pairwise correlation data between an LP pool's
+ * constituents) from seeds `["constituent_correlations", lpPoolPublicKey]`.
+ * @param programId - Deployed velocity program id.
+ * @param lpPoolPublicKey - The `LpPool` account's public key.
+ * @returns The `ConstituentCorrelations` account's public key.
+ */
 function getConstituentCorrelationsPublicKey(programId, lpPoolPublicKey) {
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from(anchor.utils.bytes.utf8.encode('constituent_correlations')),
@@ -238,6 +443,13 @@ function getConstituentCorrelationsPublicKey(programId, lpPoolPublicKey) {
     ], programId)[0];
 }
 exports.getConstituentCorrelationsPublicKey = getConstituentCorrelationsPublicKey;
+/**
+ * Derives the associated token account for an LP pool's mint under a given owner (not a
+ * program-derived PDA — a standard SPL associated token account).
+ * @param lpPoolTokenMint - The LP pool's token mint.
+ * @param authority - Owner of the associated token account.
+ * @returns The associated token account's public key.
+ */
 async function getLpPoolTokenTokenAccountPublicKey(lpPoolTokenMint, authority) {
     return await (0, spl_token_1.getAssociatedTokenAddress)(lpPoolTokenMint, authority, true);
 }