@voltr/vault-sdk 1.0.21 → 2.0.0

package/src/extensions/lpEconomics.ts

@@ -0,0 +1,225 @@
+import type { Address } from "@solana/kit";
+
+import {
+  fetchVault,
+  findVaultLpMintPda,
+  VOLTR_VAULT_PROGRAM_ADDRESS,
+  type FeeConfiguration,
+  type Vault,
+} from "../generated";
+import {
+  calculateAssetsForWithdrawAmount,
+  calculateLpForDepositAmount,
+  calculateLpForWithdrawAmount,
+  calculateUnrealisedLpFees,
+  getTotalLpSupplyInclFees,
+} from "./math";
+import type { ExtensionsRpc } from "./rpc";
+
+/**
+ * Total management fee in BPS — sum of manager + admin + protocol, matching
+ * the program's `Vault::get_total_fee_configuration_management_fee`.
+ */
+export function getTotalManagementFeeBps(
+  feeConfiguration: FeeConfiguration,
+): number {
+  return (
+    feeConfiguration.managerManagementFee +
+    feeConfiguration.adminManagementFee +
+    feeConfiguration.protocolManagementFee
+  );
+}
+
+async function vaultLpMintAddress(vault: Address): Promise<Address> {
+  const [address] = await findVaultLpMintPda(
+    { vault },
+    { programAddress: VOLTR_VAULT_PROGRAM_ADDRESS },
+  );
+  return address;
+}
+
+async function fetchTokenSupply(
+  rpc: ExtensionsRpc,
+  mint: Address,
+): Promise<{ amount: bigint; decimals: number }> {
+  const { value } = await rpc.getTokenSupply(mint).send();
+  return { amount: BigInt(value.amount), decimals: value.decimals };
+}
+
+async function loadVaultAndLpSupply(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<{ data: Vault; lpSupply: bigint; lpDecimals: number }> {
+  const account = await fetchVault(rpc, vault);
+  const lpMint = await vaultLpMintAddress(vault);
+  const { amount, decimals } = await fetchTokenSupply(rpc, lpMint);
+  return { data: account.data, lpSupply: amount, lpDecimals: decimals };
+}
+
+/**
+ * Returns the on-chain "asset per LP" ratio used by mint/burn math: total
+ * asset value divided by `total_lp_supply_incl_fees + unrealised management
+ * fee LP`. Mirrors what the deposit/withdraw handlers see after they call
+ * `handle_management_fee`. Returns 0 when there is no LP at all.
+ */
+export async function getCurrentAssetPerLpForVault(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<number> {
+  const { data, lpSupply } = await loadVaultAndLpSupply(rpc, vault);
+
+  const totalLpSupplyInclFees = getTotalLpSupplyInclFees({
+    lpSupply,
+    vaultAccumulatedLpAdminFees: data.feeState.accumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees: data.feeState.accumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees: data.feeState.accumulatedLpProtocolFees,
+    vaultDeadWeight: data.deadWeight,
+  });
+
+  const unrealisedLpFees = calculateUnrealisedLpFees(
+    totalLpSupplyInclFees,
+    data.asset.totalValue,
+    data.feeUpdate.lastManagementFeeUpdateTs,
+    BigInt(getTotalManagementFeeBps(data.feeConfiguration)),
+  );
+
+  const totalLpSupply = totalLpSupplyInclFees + unrealisedLpFees;
+  if (totalLpSupply === 0n) return 0;
+
+  return Number(data.asset.totalValue) / Number(totalLpSupply);
+}
+
+export type VaultLpSupplyBreakdown = {
+  circulating: bigint;
+  unharvestedFees: bigint;
+  deadWeight: bigint;
+  unrealisedFees: bigint;
+  total: bigint;
+};
+
+export async function getVaultLpSupplyBreakdown(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<VaultLpSupplyBreakdown> {
+  const { data, lpSupply } = await loadVaultAndLpSupply(rpc, vault);
+
+  const unharvestedFees =
+    data.feeState.accumulatedLpAdminFees +
+    data.feeState.accumulatedLpManagerFees +
+    data.feeState.accumulatedLpProtocolFees;
+  const deadWeight = data.deadWeight;
+
+  const currentTotalLp = lpSupply + unharvestedFees + deadWeight;
+
+  const unrealisedFees = calculateUnrealisedLpFees(
+    currentTotalLp,
+    data.asset.totalValue,
+    data.feeUpdate.lastManagementFeeUpdateTs,
+    BigInt(getTotalManagementFeeBps(data.feeConfiguration)),
+  );
+
+  return {
+    circulating: lpSupply,
+    unharvestedFees,
+    deadWeight,
+    unrealisedFees,
+    total: currentTotalLp + unrealisedFees,
+  };
+}
+
+export async function calculateAssetsForWithdraw(
+  rpc: ExtensionsRpc,
+  vault: Address,
+  lpAmount: bigint,
+): Promise<bigint> {
+  const { data, lpSupply } = await loadVaultAndLpSupply(rpc, vault);
+
+  return calculateAssetsForWithdrawAmount({
+    vaultTotalValue: data.asset.totalValue,
+    vaultLastUpdatedLockedProfit:
+      data.lockedProfitState.lastUpdatedLockedProfit,
+    vaultLastReport: data.lockedProfitState.lastReport,
+    vaultLockedProfitDegradationDuration:
+      data.vaultConfiguration.lockedProfitDegradationDuration,
+    vaultAccumulatedLpAdminFees: data.feeState.accumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees: data.feeState.accumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees: data.feeState.accumulatedLpProtocolFees,
+    vaultDeadWeight: data.deadWeight,
+    vaultRedemptionFeeBps: data.feeConfiguration.redemptionFee,
+    vaultManagementFeeBps: getTotalManagementFeeBps(data.feeConfiguration),
+    vaultLastManagementFeeUpdateTs: data.feeUpdate.lastManagementFeeUpdateTs,
+    lpSupply,
+    lpAmount,
+  });
+}
+
+export async function calculateLpForWithdraw(
+  rpc: ExtensionsRpc,
+  vault: Address,
+  assetAmount: bigint,
+): Promise<bigint> {
+  const { data, lpSupply } = await loadVaultAndLpSupply(rpc, vault);
+
+  return calculateLpForWithdrawAmount({
+    vaultTotalValue: data.asset.totalValue,
+    vaultLastUpdatedLockedProfit:
+      data.lockedProfitState.lastUpdatedLockedProfit,
+    vaultLastReport: data.lockedProfitState.lastReport,
+    vaultLockedProfitDegradationDuration:
+      data.vaultConfiguration.lockedProfitDegradationDuration,
+    vaultAccumulatedLpAdminFees: data.feeState.accumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees: data.feeState.accumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees: data.feeState.accumulatedLpProtocolFees,
+    vaultDeadWeight: data.deadWeight,
+    vaultRedemptionFeeBps: data.feeConfiguration.redemptionFee,
+    vaultManagementFeeBps: getTotalManagementFeeBps(data.feeConfiguration),
+    vaultLastManagementFeeUpdateTs: data.feeUpdate.lastManagementFeeUpdateTs,
+    lpSupply,
+    assetAmount,
+  });
+}
+
+export async function calculateLpForDeposit(
+  rpc: ExtensionsRpc,
+  vault: Address,
+  assetAmount: bigint,
+): Promise<bigint> {
+  const { data, lpSupply, lpDecimals } = await loadVaultAndLpSupply(rpc, vault);
+
+  // Asset decimals are only required when the LP pool is empty (1:1 mint).
+  // Avoid an extra RPC round-trip in the common case.
+  let assetDecimals = 0;
+  const lpSupplyInclAccumulatedFees = getTotalLpSupplyInclFees({
+    lpSupply,
+    vaultAccumulatedLpAdminFees: data.feeState.accumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees: data.feeState.accumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees: data.feeState.accumulatedLpProtocolFees,
+    vaultDeadWeight: data.deadWeight,
+  });
+  const unrealisedLpFees = calculateUnrealisedLpFees(
+    lpSupplyInclAccumulatedFees,
+    data.asset.totalValue,
+    data.feeUpdate.lastManagementFeeUpdateTs,
+    BigInt(getTotalManagementFeeBps(data.feeConfiguration)),
+  );
+  const lpSupplyInclFees = lpSupplyInclAccumulatedFees + unrealisedLpFees;
+  if (lpSupplyInclFees === 0n) {
+    const { decimals } = await fetchTokenSupply(rpc, data.asset.mint);
+    assetDecimals = decimals;
+  }
+
+  return calculateLpForDepositAmount({
+    vaultTotalValue: data.asset.totalValue,
+    vaultAccumulatedLpAdminFees: data.feeState.accumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees: data.feeState.accumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees: data.feeState.accumulatedLpProtocolFees,
+    vaultDeadWeight: data.deadWeight,
+    vaultIssuanceFeeBps: data.feeConfiguration.issuanceFee,
+    vaultManagementFeeBps: getTotalManagementFeeBps(data.feeConfiguration),
+    vaultLastManagementFeeUpdateTs: data.feeUpdate.lastManagementFeeUpdateTs,
+    lpSupply,
+    assetAmount,
+    assetDecimals,
+    lpDecimals,
+  });
+}

package/src/extensions/math.ts

@@ -0,0 +1,338 @@
+export const MAX_FEE_BPS = 10_000n;
+export const SECONDS_PER_YEAR = BigInt(365 * 24 * 60 * 60);
+/**
+ * Matches `DEAD_WEIGHT` in the program. The first deposit ever made into a
+ * vault donates this many LP units permanently to the vault to prevent
+ * inflation/donation attacks; subsequent deposits are unaffected.
+ */
+export const DEAD_WEIGHT_LP = 1_000n;
+
+export function maxBigInt(a: bigint, b: bigint): bigint {
+  return a > b ? a : b;
+}
+
+export function minBigInt(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}
+
+/** Ceiling division for positive bigints. */
+export function ceilDivBigInt(a: bigint, b: bigint): bigint {
+  return (a + b - 1n) / b;
+}
+
+export function nowSeconds(): bigint {
+  return BigInt(Math.floor(Date.now() / 1000));
+}
+
+/**
+ * Mirrors the program-side locked-profit decay: the locked profit drops
+ * linearly over `lockedProfitDegradationDuration` and is zero once that
+ * window has elapsed. Note: the legacy JS SDK measured elapsed time from
+ * `lastUpdatedLockedProfit` (an amount, not a timestamp), which produced
+ * incorrect values; this port follows the program, which uses `lastReport`.
+ */
+export function calculateLockedProfit(
+  lastUpdatedLockedProfit: bigint,
+  lockedProfitDegradationDuration: bigint,
+  currentTimeSec: bigint,
+  lastReport: bigint,
+): bigint {
+  if (lockedProfitDegradationDuration === 0n) return 0n;
+
+  const duration = currentTimeSec - lastReport;
+  if (duration <= 0n) return lastUpdatedLockedProfit;
+  if (duration >= lockedProfitDegradationDuration) return 0n;
+
+  return (
+    (lastUpdatedLockedProfit *
+      (lockedProfitDegradationDuration - duration)) /
+    lockedProfitDegradationDuration
+  );
+}
+
+/**
+ * Estimates the LP that would be minted to cover management fees accrued
+ * since `lastManagementFeeUpdateTs`. Returns 0n when the inputs make the
+ * fee calculation undefined (no time elapsed, no assets, etc.).
+ *
+ * Both rounding steps are ceiling divisions, matching the program's
+ * `calc_management_fee_amount_in_asset` and `calc_fee_lp_to_mint` — flooring
+ * the asset fee first would understate the LP that should be minted whenever
+ * the accrued fee isn't an exact multiple of the denominator.
+ */
+export function calculateUnrealisedLpFees(
+  currentTotalLp: bigint,
+  assetTotalValue: bigint,
+  lastManagementFeeUpdateTs: bigint,
+  managementFeeBps: bigint,
+  currentTimeSec: bigint = nowSeconds(),
+): bigint {
+  if (
+    lastManagementFeeUpdateTs === 0n ||
+    assetTotalValue === 0n ||
+    managementFeeBps === 0n
+  ) {
+    return 0n;
+  }
+
+  const timeElapsed = maxBigInt(0n, currentTimeSec - lastManagementFeeUpdateTs);
+  if (timeElapsed === 0n) return 0n;
+
+  const feeAmountInAsset = ceilDivBigInt(
+    assetTotalValue * timeElapsed * managementFeeBps,
+    MAX_FEE_BPS * SECONDS_PER_YEAR,
+  );
+
+  // Matches the program's `handle_management_fee`: when accrued fees would
+  // meet or exceed the vault's asset value, the on-chain instruction reverts
+  // with FeeExceedsTotalAssetValue. Quoting 0 here would silently mask a
+  // state where every deposit/withdraw transaction is going to fail.
+  if (feeAmountInAsset >= assetTotalValue) {
+    throw new Error(
+      "Accrued management fees exceed vault total asset value (program would revert with FeeExceedsTotalAssetValue)",
+    );
+  }
+
+  const lpDenominator = assetTotalValue - feeAmountInAsset;
+  return ceilDivBigInt(feeAmountInAsset * currentTotalLp, lpDenominator);
+}
+
+/**
+ * Total LP supply the program treats as outstanding for accounting:
+ * circulating LP + accumulated (but unharvested) fee LP + dead weight LP.
+ * Matches `Vault::get_total_lp_supply_incl_fees` in the program.
+ */
+export function getTotalLpSupplyInclFees(args: {
+  lpSupply: bigint;
+  vaultAccumulatedLpAdminFees: bigint;
+  vaultAccumulatedLpManagerFees: bigint;
+  vaultAccumulatedLpProtocolFees: bigint;
+  vaultDeadWeight: bigint;
+}): bigint {
+  return (
+    args.lpSupply +
+    args.vaultAccumulatedLpAdminFees +
+    args.vaultAccumulatedLpManagerFees +
+    args.vaultAccumulatedLpProtocolFees +
+    args.vaultDeadWeight
+  );
+}
+
+export type AssetsForWithdrawInputs = {
+  vaultTotalValue: bigint;
+  vaultLastUpdatedLockedProfit: bigint;
+  vaultLastReport: bigint;
+  vaultLockedProfitDegradationDuration: bigint;
+  vaultAccumulatedLpAdminFees: bigint;
+  vaultAccumulatedLpManagerFees: bigint;
+  vaultAccumulatedLpProtocolFees: bigint;
+  vaultDeadWeight: bigint;
+  vaultRedemptionFeeBps: number;
+  vaultManagementFeeBps: number;
+  vaultLastManagementFeeUpdateTs: bigint;
+  lpSupply: bigint;
+  lpAmount: bigint;
+  currentTimeSec?: bigint;
+};
+
+export function calculateAssetsForWithdrawAmount(
+  inputs: AssetsForWithdrawInputs,
+): bigint {
+  const {
+    vaultTotalValue,
+    vaultLastUpdatedLockedProfit,
+    vaultLastReport,
+    vaultLockedProfitDegradationDuration,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+    vaultRedemptionFeeBps,
+    vaultManagementFeeBps,
+    vaultLastManagementFeeUpdateTs,
+    lpSupply,
+    lpAmount,
+    currentTimeSec = nowSeconds(),
+  } = inputs;
+
+  if (lpSupply <= 0n) throw new Error("Invalid LP supply");
+  if (vaultTotalValue <= 0n) throw new Error("Invalid total assets");
+
+  const lockedProfit = calculateLockedProfit(
+    vaultLastUpdatedLockedProfit,
+    vaultLockedProfitDegradationDuration,
+    currentTimeSec,
+    vaultLastReport,
+  );
+  const totalUnlockedValue = vaultTotalValue - lockedProfit;
+
+  const lpSupplyInclAccumulatedFees = getTotalLpSupplyInclFees({
+    lpSupply,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+  });
+  const unrealisedLpFees = calculateUnrealisedLpFees(
+    lpSupplyInclAccumulatedFees,
+    vaultTotalValue,
+    vaultLastManagementFeeUpdateTs,
+    BigInt(vaultManagementFeeBps),
+    currentTimeSec,
+  );
+  const lpSupplyInclFees = lpSupplyInclAccumulatedFees + unrealisedLpFees;
+
+  // The program floors asset_to_redeem (favours the vault on the redeem side).
+  const numerator =
+    lpAmount * totalUnlockedValue * BigInt(10_000 - vaultRedemptionFeeBps);
+  const denominator = lpSupplyInclFees * 10_000n;
+
+  return numerator / denominator;
+}
+
+export type LpForWithdrawInputs = Omit<AssetsForWithdrawInputs, "lpAmount"> & {
+  assetAmount: bigint;
+};
+
+/**
+ * Computes the LP that must be burned to redeem at least `assetAmount`,
+ * matching `calc_withdraw_lp_to_burn` in the program (which rounds up so
+ * the burn always covers the requested asset amount). Flooring here would
+ * underquote the burn and either revert or short-redeem.
+ */
+export function calculateLpForWithdrawAmount(
+  inputs: LpForWithdrawInputs,
+): bigint {
+  const {
+    vaultTotalValue,
+    vaultLastUpdatedLockedProfit,
+    vaultLastReport,
+    vaultLockedProfitDegradationDuration,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+    vaultRedemptionFeeBps,
+    vaultManagementFeeBps,
+    vaultLastManagementFeeUpdateTs,
+    lpSupply,
+    assetAmount,
+    currentTimeSec = nowSeconds(),
+  } = inputs;
+
+  if (lpSupply <= 0n) throw new Error("Invalid LP supply");
+  if (vaultTotalValue <= 0n) throw new Error("Invalid total assets");
+
+  const lockedProfit = calculateLockedProfit(
+    vaultLastUpdatedLockedProfit,
+    vaultLockedProfitDegradationDuration,
+    currentTimeSec,
+    vaultLastReport,
+  );
+  const totalUnlockedValue = vaultTotalValue - lockedProfit;
+
+  const lpSupplyInclAccumulatedFees = getTotalLpSupplyInclFees({
+    lpSupply,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+  });
+  const unrealisedLpFees = calculateUnrealisedLpFees(
+    lpSupplyInclAccumulatedFees,
+    vaultTotalValue,
+    vaultLastManagementFeeUpdateTs,
+    BigInt(vaultManagementFeeBps),
+    currentTimeSec,
+  );
+  const lpSupplyInclFees = lpSupplyInclAccumulatedFees + unrealisedLpFees;
+
+  const numerator = assetAmount * lpSupplyInclFees * 10_000n;
+  const denominator =
+    totalUnlockedValue * BigInt(10_000 - vaultRedemptionFeeBps);
+
+  return ceilDivBigInt(numerator, denominator);
+}
+
+export type LpForDepositInputs = {
+  vaultTotalValue: bigint;
+  vaultAccumulatedLpAdminFees: bigint;
+  vaultAccumulatedLpManagerFees: bigint;
+  vaultAccumulatedLpProtocolFees: bigint;
+  vaultDeadWeight: bigint;
+  vaultIssuanceFeeBps: number;
+  vaultManagementFeeBps: number;
+  vaultLastManagementFeeUpdateTs: bigint;
+  lpSupply: bigint;
+  assetAmount: bigint;
+  /** Required when the pool is empty so the 1:1 mint can scale precision correctly. */
+  assetDecimals: number;
+  /** Required when the pool is empty so the 1:1 mint can scale precision correctly. */
+  lpDecimals: number;
+  currentTimeSec?: bigint;
+};
+
+export function calculateLpForDepositAmount(inputs: LpForDepositInputs): bigint {
+  const {
+    vaultTotalValue,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+    vaultIssuanceFeeBps,
+    vaultManagementFeeBps,
+    vaultLastManagementFeeUpdateTs,
+    lpSupply,
+    assetAmount,
+    assetDecimals,
+    lpDecimals,
+    currentTimeSec = nowSeconds(),
+  } = inputs;
+
+  const lpSupplyInclAccumulatedFees = getTotalLpSupplyInclFees({
+    lpSupply,
+    vaultAccumulatedLpAdminFees,
+    vaultAccumulatedLpManagerFees,
+    vaultAccumulatedLpProtocolFees,
+    vaultDeadWeight,
+  });
+  const unrealisedLpFees = calculateUnrealisedLpFees(
+    lpSupplyInclAccumulatedFees,
+    vaultTotalValue,
+    vaultLastManagementFeeUpdateTs,
+    BigInt(vaultManagementFeeBps),
+    currentTimeSec,
+  );
+  const lpSupplyInclFees = lpSupplyInclAccumulatedFees + unrealisedLpFees;
+
+  let lpToMintBeforeDeadWeight: bigint;
+  if (lpSupplyInclFees === 0n) {
+    lpToMintBeforeDeadWeight =
+      (assetAmount * 10n ** BigInt(lpDecimals)) / 10n ** BigInt(assetDecimals);
+  } else {
+    // The program floors mint quantity (favours existing holders on the
+    // mint side), so we mirror that here.
+    const numerator =
+      assetAmount * lpSupplyInclFees * BigInt(10_000 - vaultIssuanceFeeBps);
+    const totalAssetPostDeposit = vaultTotalValue + assetAmount;
+    const denominator =
+      totalAssetPostDeposit * 10_000n -
+      assetAmount * BigInt(10_000 - vaultIssuanceFeeBps);
+    lpToMintBeforeDeadWeight = numerator / denominator;
+  }
+
+  // First-ever deposit pays DEAD_WEIGHT_LP into the vault permanently. The
+  // program rejects deposits that don't clear that floor, so we surface the
+  // same condition here rather than silently quoting a value the user can't
+  // actually receive.
+  if (vaultDeadWeight === 0n) {
+    if (lpToMintBeforeDeadWeight < DEAD_WEIGHT_LP) {
+      throw new Error(
+        `First deposit must mint at least ${DEAD_WEIGHT_LP} LP (would mint ${lpToMintBeforeDeadWeight})`,
+      );
+    }
+    return lpToMintBeforeDeadWeight - DEAD_WEIGHT_LP;
+  }
+
+  return lpToMintBeforeDeadWeight;
+}

package/src/extensions/metadataPda.ts

@@ -0,0 +1,47 @@
+import {
+  getAddressEncoder,
+  getBytesEncoder,
+  getProgramDerivedAddress,
+  type Address,
+  type ProgramDerivedAddress,
+} from "@solana/kit";
+
+import { findVaultLpMintPda, VOLTR_VAULT_PROGRAM_ADDRESS } from "../generated";
+
+/**
+ * Metaplex Token Metadata program ID. Codama can't derive PDAs that depend on
+ * an external program, so we keep this helper hand-written.
+ */
+export const METAPLEX_METADATA_PROGRAM_ADDRESS =
+  "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s" as Address<"metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s">;
+
+const METADATA_SEED = new Uint8Array([
+  109, 101, 116, 97, 100, 97, 116, 97,
+]); // "metadata"
+
+/**
+ * Derives the LP metadata PDA owned by the Metaplex Token Metadata program for
+ * a given Voltr vault. Mirrors the legacy SDK's `findLpMetadataAccount(vault)`
+ * convenience: caller supplies the vault, we compute the LP mint PDA and then
+ * the metadata PDA off of it.
+ */
+export async function findLpMetadataPda(
+  seeds: { vault: Address },
+  config: { voltrProgramAddress?: Address } = {},
+): Promise<ProgramDerivedAddress> {
+  const [lpMint] = await findVaultLpMintPda(
+    { vault: seeds.vault },
+    {
+      programAddress:
+        config.voltrProgramAddress ?? VOLTR_VAULT_PROGRAM_ADDRESS,
+    },
+  );
+  return await getProgramDerivedAddress({
+    programAddress: METAPLEX_METADATA_PROGRAM_ADDRESS,
+    seeds: [
+      getBytesEncoder().encode(METADATA_SEED),
+      getAddressEncoder().encode(METAPLEX_METADATA_PROGRAM_ADDRESS),
+      getAddressEncoder().encode(lpMint),
+    ],
+  });
+}

package/src/extensions/position.ts

@@ -0,0 +1,54 @@
+import type { Address } from "@solana/kit";
+
+import { fetchVault } from "../generated";
+import { fetchAllStrategyInitReceiptAccountsOfVault } from "./batchFetchers";
+import { convertDecimalBitsToNumber } from "./decimal";
+import type { ExtensionsRpc } from "./rpc";
+
+export type StrategyPositionInfo = {
+  strategyId: Address;
+  /** Position value in raw asset base units. */
+  amount: bigint;
+};
+
+export type VaultPositionAndTotalValues = {
+  /** Total value of the vault in raw asset base units. */
+  totalValue: bigint;
+  strategies: StrategyPositionInfo[];
+};
+
+export async function getPositionAndTotalValuesForVault(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<VaultPositionAndTotalValues> {
+  const [vaultAccount, strategyAccounts] = await Promise.all([
+    fetchVault(rpc, vault),
+    fetchAllStrategyInitReceiptAccountsOfVault(rpc, vault),
+  ]);
+
+  return {
+    totalValue: vaultAccount.data.asset.totalValue,
+    strategies: strategyAccounts.map((account) => ({
+      strategyId: account.data.strategy,
+      amount: account.data.positionValue,
+    })),
+  };
+}
+
+export type HighWaterMarkInfo = {
+  highestAssetPerLp: number;
+  lastUpdatedTs: bigint;
+};
+
+export async function getHighWaterMarkForVault(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<HighWaterMarkInfo> {
+  const account = await fetchVault(rpc, vault);
+  return {
+    highestAssetPerLp: convertDecimalBitsToNumber(
+      account.data.highWaterMark.highestAssetPerLpDecimalBits,
+    ),
+    lastUpdatedTs: account.data.highWaterMark.lastUpdatedTs,
+  };
+}

package/src/extensions/rpc.ts

@@ -0,0 +1,17 @@
+import type {
+  GetAccountInfoApi,
+  GetMultipleAccountsApi,
+  GetProgramAccountsApi,
+  GetTokenSupplyApi,
+  Rpc,
+} from "@solana/kit";
+
+export type GetAccountInfoRpc = Rpc<GetAccountInfoApi>;
+export type GetMultipleAccountsRpc = Rpc<GetMultipleAccountsApi>;
+export type GetProgramAccountsRpc = Rpc<GetProgramAccountsApi>;
+export type GetTokenSupplyRpc = Rpc<GetTokenSupplyApi>;
+
+/** Combined RPC interface used by the higher-level extension helpers. */
+export type ExtensionsRpc = Rpc<
+  GetAccountInfoApi & GetTokenSupplyApi & GetProgramAccountsApi
+>;