@voltr/vault-sdk 1.1.0 → 2.1.0

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
+>;

package/src/extensions/withdrawals.ts

@@ -0,0 +1,113 @@
+import type { Account, Address } from "@solana/kit";
+
+import {
+  fetchRequestWithdrawVaultReceipt,
+  fetchVault,
+  findRequestWithdrawVaultReceiptPda,
+  findVaultLpMintPda,
+  VOLTR_VAULT_PROGRAM_ADDRESS,
+  type RequestWithdrawVaultReceipt,
+  type Vault,
+} from "../generated";
+import { fetchAllRequestWithdrawVaultReceiptsOfVault } from "./batchFetchers";
+import { convertDecimalBitsToNumber } from "./decimal";
+import { getTotalManagementFeeBps } from "./lpEconomics";
+import { calculateAssetsForWithdrawAmount } from "./math";
+import type { ExtensionsRpc } from "./rpc";
+
+export type PendingWithdrawal = {
+  user: Address;
+  amountAssetToWithdrawEffective: number;
+  amountAssetToWithdrawAtRequest: number;
+  amountAssetToWithdrawAtPresent: number;
+  amountLpEscrowed: bigint;
+  withdrawableFromTs: bigint;
+};
+
+function processWithdrawalReceipt(
+  receipt: RequestWithdrawVaultReceipt,
+  vault: Vault,
+  lpSupply: bigint,
+): PendingWithdrawal {
+  const amountAssetToWithdrawAtRequest = convertDecimalBitsToNumber(
+    receipt.amountAssetToWithdrawDecimalBits,
+  );
+
+  const amountAssetToWithdrawAtPresent = Number(
+    calculateAssetsForWithdrawAmount({
+      vaultTotalValue: vault.asset.totalValue,
+      vaultLastUpdatedLockedProfit:
+        vault.lockedProfitState.lastUpdatedLockedProfit,
+      vaultLastReport: vault.lockedProfitState.lastReport,
+      vaultLockedProfitDegradationDuration:
+        vault.vaultConfiguration.lockedProfitDegradationDuration,
+      vaultAccumulatedLpAdminFees: vault.feeState.accumulatedLpAdminFees,
+      vaultAccumulatedLpManagerFees: vault.feeState.accumulatedLpManagerFees,
+      vaultAccumulatedLpProtocolFees: vault.feeState.accumulatedLpProtocolFees,
+      vaultDeadWeight: vault.deadWeight,
+      vaultRedemptionFeeBps: vault.feeConfiguration.redemptionFee,
+      vaultManagementFeeBps: getTotalManagementFeeBps(vault.feeConfiguration),
+      vaultLastManagementFeeUpdateTs: vault.feeUpdate.lastManagementFeeUpdateTs,
+      lpSupply,
+      lpAmount: receipt.amountLpEscrowed,
+    }),
+  );
+
+  return {
+    user: receipt.user,
+    amountAssetToWithdrawEffective: Math.min(
+      amountAssetToWithdrawAtPresent,
+      amountAssetToWithdrawAtRequest,
+    ),
+    amountAssetToWithdrawAtRequest,
+    amountAssetToWithdrawAtPresent,
+    amountLpEscrowed: receipt.amountLpEscrowed,
+    withdrawableFromTs: receipt.withdrawableFromTs,
+  };
+}
+
+async function fetchVaultWithLpSupply(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<{ data: Vault; lpSupply: bigint }> {
+  const account = await fetchVault(rpc, vault);
+  const [lpMint] = await findVaultLpMintPda(
+    { vault },
+    { programAddress: VOLTR_VAULT_PROGRAM_ADDRESS },
+  );
+  const supplyResp = await rpc.getTokenSupply(lpMint).send();
+  return {
+    data: account.data,
+    lpSupply: BigInt(supplyResp.value.amount),
+  };
+}
+
+export async function getPendingWithdrawalForUser(
+  rpc: ExtensionsRpc,
+  vault: Address,
+  user: Address,
+): Promise<PendingWithdrawal> {
+  const { data, lpSupply } = await fetchVaultWithLpSupply(rpc, vault);
+  const [receiptAddress] = await findRequestWithdrawVaultReceiptPda(
+    { vault, userTransferAuthority: user },
+    { programAddress: VOLTR_VAULT_PROGRAM_ADDRESS },
+  );
+  const receipt = await fetchRequestWithdrawVaultReceipt(rpc, receiptAddress);
+  return processWithdrawalReceipt(receipt.data, data, lpSupply);
+}
+
+export async function getAllPendingWithdrawalsForVault(
+  rpc: ExtensionsRpc,
+  vault: Address,
+): Promise<PendingWithdrawal[]> {
+  const [{ data, lpSupply }, receipts] = await Promise.all([
+    fetchVaultWithLpSupply(rpc, vault),
+    fetchAllRequestWithdrawVaultReceiptsOfVault(rpc, vault),
+  ]);
+
+  return receipts.map((account: Account<RequestWithdrawVaultReceipt>) =>
+    processWithdrawalReceipt(account.data, data, lpSupply),
+  );
+}
+
+export { processWithdrawalReceipt };