@elmntl/jlpd-sdk 0.1.0 → 1.0.9

package/README.md

@@ -108,6 +108,26 @@ console.log("Exchange rate:", rate.rate); // e.g., 1.05 means 5% yield
 console.log("Is fresh:", rate.isFresh);
 ```
 
+### Calculate APY
+
+Calculate annualized return based on PPS (price per share) growth over time.
+
+```typescript
+// You need a starting PPS and timestamp (e.g., from when user deposited)
+const startPps = new BN("1000000000"); // 1.0 (9 decimals)
+const startTime = 1706140800; // Unix timestamp when PPS was recorded
+
+// Calculate compound APY
+const apy = await client.calculateApy("SOL", startPps, startTime);
+console.log(`APY: ${(apy * 100).toFixed(2)}%`); // e.g., "APY: 12.50%"
+
+// Or calculate simple APY (non-compounded)
+const simpleApy = await client.calculateSimpleApy("SOL", startPps, startTime);
+console.log(`Simple APY: ${(simpleApy * 100).toFixed(2)}%`);
+```
+
+**Note:** Store the user's PPS and timestamp when they deposit to calculate their personal returns later.
+
 ---
 
 ## Manager Operations

package/dist/index.d.mts

@@ -233,6 +233,33 @@ declare class JlpdClient {
     fetchVault(): Promise<JLPVault | null>;
     fetchStv(baseMint: PublicKey): Promise<STV | null>;
     fetchExchangeRate(poolName: PoolName): Promise<ExchangeRateResult>;
+    /**
+     * Calculate APY based on PPS growth over time
+     *
+     * @param poolName Pool to calculate APY for
+     * @param startPps PPS at the start of the period (as BN with 9 decimals)
+     * @param startTime Unix timestamp (seconds) when startPps was recorded
+     * @returns APY as a decimal (e.g., 0.12 = 12% APY)
+     *
+     * @example
+     * ```typescript
+     * // Calculate APY from a week ago
+     * const startPps = new BN("1050000000"); // 1.05 (9 decimals)
+     * const startTime = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
+     * const apy = await client.calculateApy("SOL", startPps, startTime);
+     * console.log(`APY: ${(apy * 100).toFixed(2)}%`);
+     * ```
+     */
+    calculateApy(poolName: PoolName, startPps: BN, startTime: number): Promise<number>;
+    /**
+     * Calculate simple APY (non-compounded) based on PPS growth
+     *
+     * @param poolName Pool to calculate APY for
+     * @param startPps PPS at the start of the period
+     * @param startTime Unix timestamp when startPps was recorded
+     * @returns Simple APY as a decimal
+     */
+    calculateSimpleApy(poolName: PoolName, startPps: BN, startTime: number): Promise<number>;
     pool(poolNameOrMint: PoolName | PublicKey): PoolContext;
     swap(): SwapContext;
     admin(): AdminContext;

package/dist/index.d.ts

@@ -233,6 +233,33 @@ declare class JlpdClient {
     fetchVault(): Promise<JLPVault | null>;
     fetchStv(baseMint: PublicKey): Promise<STV | null>;
     fetchExchangeRate(poolName: PoolName): Promise<ExchangeRateResult>;
+    /**
+     * Calculate APY based on PPS growth over time
+     *
+     * @param poolName Pool to calculate APY for
+     * @param startPps PPS at the start of the period (as BN with 9 decimals)
+     * @param startTime Unix timestamp (seconds) when startPps was recorded
+     * @returns APY as a decimal (e.g., 0.12 = 12% APY)
+     *
+     * @example
+     * ```typescript
+     * // Calculate APY from a week ago
+     * const startPps = new BN("1050000000"); // 1.05 (9 decimals)
+     * const startTime = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
+     * const apy = await client.calculateApy("SOL", startPps, startTime);
+     * console.log(`APY: ${(apy * 100).toFixed(2)}%`);
+     * ```
+     */
+    calculateApy(poolName: PoolName, startPps: BN, startTime: number): Promise<number>;
+    /**
+     * Calculate simple APY (non-compounded) based on PPS growth
+     *
+     * @param poolName Pool to calculate APY for
+     * @param startPps PPS at the start of the period
+     * @param startTime Unix timestamp when startPps was recorded
+     * @returns Simple APY as a decimal
+     */
+    calculateSimpleApy(poolName: PoolName, startPps: BN, startTime: number): Promise<number>;
     pool(poolNameOrMint: PoolName | PublicKey): PoolContext;
     swap(): SwapContext;
     admin(): AdminContext;

package/dist/index.js

@@ -791,34 +791,34 @@ async function fetchJlpRate(jlpMint, fallbackPrice = 4.6, apiKey = DEFAULT_API_K
 // src/instructions/admin.ts
 var import_web38 = require("@solana/web3.js");
 var INIT_OR_UPDATE_VAULT_DISCRIMINATOR = Buffer.from([
-  91,
-  101,
-  110,
-  100,
-  105,
-  110,
-  103,
-  93
+  234,
+  24,
+  218,
+  120,
+  213,
+  149,
+  245,
+  213
 ]);
 var INITIALIZE_STV_DISCRIMINATOR = Buffer.from([
-  105,
-  110,
-  105,
-  116,
-  95,
-  115,
-  116,
-  118
+  136,
+  8,
+  178,
+  176,
+  57,
+  33,
+  1,
+  106
 ]);
 var UPDATE_STV_DISCRIMINATOR = Buffer.from([
-  117,
-  112,
-  100,
-  95,
-  115,
-  116,
-  118,
-  0
+  72,
+  173,
+  200,
+  203,
+  74,
+  83,
+  242,
+  43
 ]);
 function serializeOptionPubkey(value) {
   if (value === null) {
@@ -910,14 +910,14 @@ function createUpdateStvInstruction(params, accounts, programId = JLPD_PROGRAM_I
 // src/instructions/user.ts
 var import_web39 = require("@solana/web3.js");
 var DEPOSIT_DISCRIMINATOR = Buffer.from([
-  248,
+  242,
+  35,
   198,
-  158,
-  145,
+  137,
+  82,
   225,
-  117,
-  135,
-  200
+  242,
+  182
 ]);
 var WITHDRAW_DISCRIMINATOR = Buffer.from([
   183,
@@ -974,54 +974,54 @@ function createWithdrawInstruction(sharesToBurn, accounts, remainingAccounts = [
 // src/instructions/manager.ts
 var import_web310 = require("@solana/web3.js");
 var JUP_EARN_DISCRIMINATOR = Buffer.from([
-  161,
-  178,
-  195,
+  124,
+  60,
+  71,
+  122,
+  162,
   212,
-  229,
-  246,
-  7,
-  24
+  164,
+  191
 ]);
 var MOVE_STV_DISCRIMINATOR = Buffer.from([
-  41,
-  58,
-  75,
-  92,
-  109,
+  60,
+  104,
+  8,
   126,
-  143,
-  144
+  254,
+  244,
+  95,
+  221
 ]);
 var SWAP_JLX_JLX_DISCRIMINATOR = Buffer.from([
-  65,
-  82,
-  99,
-  116,
-  133,
-  150,
-  167,
-  184
+  24,
+  52,
+  70,
+  107,
+  160,
+  96,
+  155,
+  62
 ]);
 var SWAP_JLX_JLP_DISCRIMINATOR = Buffer.from([
-  201,
-  218,
-  235,
-  252,
-  13,
-  30,
-  47,
-  48
+  229,
+  185,
+  136,
+  170,
+  210,
+  189,
+  172,
+  241
 ]);
 var SETTLE_YIELD_DISCRIMINATOR = Buffer.from([
-  81,
-  98,
-  115,
-  132,
-  149,
-  166,
-  183,
-  200
+  64,
+  28,
+  44,
+  24,
+  43,
+  204,
+  58,
+  215
 ]);
 function serializeU8(value) {
   const buf = Buffer.alloc(1);
@@ -1155,14 +1155,14 @@ function createSettleYieldInstruction(params, accounts, remainingAccounts = [],
 // src/instructions/fees.ts
 var import_web311 = require("@solana/web3.js");
 var CLAIM_FEES_DISCRIMINATOR = Buffer.from([
-  209,
-  226,
-  243,
-  4,
-  21,
-  38,
-  55,
-  72
+  82,
+  251,
+  233,
+  156,
+  12,
+  52,
+  184,
+  202
 ]);
 function createClaimFeesInstruction(accounts, remainingAccounts = [], programId = JLPD_PROGRAM_ID) {
   const data = CLAIM_FEES_DISCRIMINATOR;
@@ -1267,6 +1267,78 @@ var JlpdClient = class _JlpdClient {
       isFresh: staleness < 300
     };
   }
+  /**
+   * Calculate APY based on PPS growth over time
+   *
+   * @param poolName Pool to calculate APY for
+   * @param startPps PPS at the start of the period (as BN with 9 decimals)
+   * @param startTime Unix timestamp (seconds) when startPps was recorded
+   * @returns APY as a decimal (e.g., 0.12 = 12% APY)
+   *
+   * @example
+   * ```typescript
+   * // Calculate APY from a week ago
+   * const startPps = new BN("1050000000"); // 1.05 (9 decimals)
+   * const startTime = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
+   * const apy = await client.calculateApy("SOL", startPps, startTime);
+   * console.log(`APY: ${(apy * 100).toFixed(2)}%`);
+   * ```
+   */
+  async calculateApy(poolName, startPps, startTime) {
+    const pool = getPoolByName(poolName);
+    if (!pool) throw new JlpdClientError(`Unknown pool: ${poolName}`);
+    const [stv, slot] = await Promise.all([
+      this.fetchStv(pool.mint),
+      this.connection.getSlot()
+    ]);
+    if (!stv) throw new JlpdClientError(`STV not found for pool: ${poolName}`);
+    const currentTime = await this.connection.getBlockTime(slot);
+    if (!currentTime) throw new JlpdClientError("Failed to get block time");
+    const currentPps = stv.pps;
+    const startPpsNum = Number(startPps.toString()) / PPS_DECIMALS;
+    const currentPpsNum = Number(currentPps.toString()) / PPS_DECIMALS;
+    const timeElapsed = currentTime - startTime;
+    if (timeElapsed <= 0) {
+      throw new JlpdClientError("Start time must be in the past");
+    }
+    const SECONDS_PER_YEAR2 = 365.25 * 24 * 60 * 60;
+    const ppsGrowthRatio = currentPpsNum / startPpsNum;
+    if (ppsGrowthRatio <= 0) {
+      return -1;
+    }
+    const annualizationFactor = SECONDS_PER_YEAR2 / timeElapsed;
+    const apy = Math.pow(ppsGrowthRatio, annualizationFactor) - 1;
+    return apy;
+  }
+  /**
+   * Calculate simple APY (non-compounded) based on PPS growth
+   *
+   * @param poolName Pool to calculate APY for
+   * @param startPps PPS at the start of the period
+   * @param startTime Unix timestamp when startPps was recorded
+   * @returns Simple APY as a decimal
+   */
+  async calculateSimpleApy(poolName, startPps, startTime) {
+    const pool = getPoolByName(poolName);
+    if (!pool) throw new JlpdClientError(`Unknown pool: ${poolName}`);
+    const [stv, slot] = await Promise.all([
+      this.fetchStv(pool.mint),
+      this.connection.getSlot()
+    ]);
+    if (!stv) throw new JlpdClientError(`STV not found for pool: ${poolName}`);
+    const currentTime = await this.connection.getBlockTime(slot);
+    if (!currentTime) throw new JlpdClientError("Failed to get block time");
+    const startPpsNum = Number(startPps.toString()) / PPS_DECIMALS;
+    const currentPpsNum = Number(stv.pps.toString()) / PPS_DECIMALS;
+    const timeElapsed = currentTime - startTime;
+    if (timeElapsed <= 0) {
+      throw new JlpdClientError("Start time must be in the past");
+    }
+    const SECONDS_PER_YEAR2 = 365.25 * 24 * 60 * 60;
+    const growthRate = (currentPpsNum - startPpsNum) / startPpsNum;
+    const simpleApy = growthRate * (SECONDS_PER_YEAR2 / timeElapsed);
+    return simpleApy;
+  }
   // Get pool context for pool-specific operations (cached)
   pool(poolNameOrMint) {
     const key = typeof poolNameOrMint === "string" ? poolNameOrMint : poolNameOrMint.toBase58();

package/dist/index.mjs

@@ -702,34 +702,34 @@ async function fetchJlpRate(jlpMint, fallbackPrice = 4.6, apiKey = DEFAULT_API_K
 // src/instructions/admin.ts
 import { TransactionInstruction } from "@solana/web3.js";
 var INIT_OR_UPDATE_VAULT_DISCRIMINATOR = Buffer.from([
-  91,
-  101,
-  110,
-  100,
-  105,
-  110,
-  103,
-  93
+  234,
+  24,
+  218,
+  120,
+  213,
+  149,
+  245,
+  213
 ]);
 var INITIALIZE_STV_DISCRIMINATOR = Buffer.from([
-  105,
-  110,
-  105,
-  116,
-  95,
-  115,
-  116,
-  118
+  136,
+  8,
+  178,
+  176,
+  57,
+  33,
+  1,
+  106
 ]);
 var UPDATE_STV_DISCRIMINATOR = Buffer.from([
-  117,
-  112,
-  100,
-  95,
-  115,
-  116,
-  118,
-  0
+  72,
+  173,
+  200,
+  203,
+  74,
+  83,
+  242,
+  43
 ]);
 function serializeOptionPubkey(value) {
   if (value === null) {
@@ -821,14 +821,14 @@ function createUpdateStvInstruction(params, accounts, programId = JLPD_PROGRAM_I
 // src/instructions/user.ts
 import { TransactionInstruction as TransactionInstruction2 } from "@solana/web3.js";
 var DEPOSIT_DISCRIMINATOR = Buffer.from([
-  248,
+  242,
+  35,
   198,
-  158,
-  145,
+  137,
+  82,
   225,
-  117,
-  135,
-  200
+  242,
+  182
 ]);
 var WITHDRAW_DISCRIMINATOR = Buffer.from([
   183,
@@ -885,54 +885,54 @@ function createWithdrawInstruction(sharesToBurn, accounts, remainingAccounts = [
 // src/instructions/manager.ts
 import { TransactionInstruction as TransactionInstruction3 } from "@solana/web3.js";
 var JUP_EARN_DISCRIMINATOR = Buffer.from([
-  161,
-  178,
-  195,
+  124,
+  60,
+  71,
+  122,
+  162,
   212,
-  229,
-  246,
-  7,
-  24
+  164,
+  191
 ]);
 var MOVE_STV_DISCRIMINATOR = Buffer.from([
-  41,
-  58,
-  75,
-  92,
-  109,
+  60,
+  104,
+  8,
   126,
-  143,
-  144
+  254,
+  244,
+  95,
+  221
 ]);
 var SWAP_JLX_JLX_DISCRIMINATOR = Buffer.from([
-  65,
-  82,
-  99,
-  116,
-  133,
-  150,
-  167,
-  184
+  24,
+  52,
+  70,
+  107,
+  160,
+  96,
+  155,
+  62
 ]);
 var SWAP_JLX_JLP_DISCRIMINATOR = Buffer.from([
-  201,
-  218,
-  235,
-  252,
-  13,
-  30,
-  47,
-  48
+  229,
+  185,
+  136,
+  170,
+  210,
+  189,
+  172,
+  241
 ]);
 var SETTLE_YIELD_DISCRIMINATOR = Buffer.from([
-  81,
-  98,
-  115,
-  132,
-  149,
-  166,
-  183,
-  200
+  64,
+  28,
+  44,
+  24,
+  43,
+  204,
+  58,
+  215
 ]);
 function serializeU8(value) {
   const buf = Buffer.alloc(1);
@@ -1066,14 +1066,14 @@ function createSettleYieldInstruction(params, accounts, remainingAccounts = [],
 // src/instructions/fees.ts
 import { TransactionInstruction as TransactionInstruction4 } from "@solana/web3.js";
 var CLAIM_FEES_DISCRIMINATOR = Buffer.from([
-  209,
-  226,
-  243,
-  4,
-  21,
-  38,
-  55,
-  72
+  82,
+  251,
+  233,
+  156,
+  12,
+  52,
+  184,
+  202
 ]);
 function createClaimFeesInstruction(accounts, remainingAccounts = [], programId = JLPD_PROGRAM_ID) {
   const data = CLAIM_FEES_DISCRIMINATOR;
@@ -1178,6 +1178,78 @@ var JlpdClient = class _JlpdClient {
       isFresh: staleness < 300
     };
   }
+  /**
+   * Calculate APY based on PPS growth over time
+   *
+   * @param poolName Pool to calculate APY for
+   * @param startPps PPS at the start of the period (as BN with 9 decimals)
+   * @param startTime Unix timestamp (seconds) when startPps was recorded
+   * @returns APY as a decimal (e.g., 0.12 = 12% APY)
+   *
+   * @example
+   * ```typescript
+   * // Calculate APY from a week ago
+   * const startPps = new BN("1050000000"); // 1.05 (9 decimals)
+   * const startTime = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
+   * const apy = await client.calculateApy("SOL", startPps, startTime);
+   * console.log(`APY: ${(apy * 100).toFixed(2)}%`);
+   * ```
+   */
+  async calculateApy(poolName, startPps, startTime) {
+    const pool = getPoolByName(poolName);
+    if (!pool) throw new JlpdClientError(`Unknown pool: ${poolName}`);
+    const [stv, slot] = await Promise.all([
+      this.fetchStv(pool.mint),
+      this.connection.getSlot()
+    ]);
+    if (!stv) throw new JlpdClientError(`STV not found for pool: ${poolName}`);
+    const currentTime = await this.connection.getBlockTime(slot);
+    if (!currentTime) throw new JlpdClientError("Failed to get block time");
+    const currentPps = stv.pps;
+    const startPpsNum = Number(startPps.toString()) / PPS_DECIMALS;
+    const currentPpsNum = Number(currentPps.toString()) / PPS_DECIMALS;
+    const timeElapsed = currentTime - startTime;
+    if (timeElapsed <= 0) {
+      throw new JlpdClientError("Start time must be in the past");
+    }
+    const SECONDS_PER_YEAR2 = 365.25 * 24 * 60 * 60;
+    const ppsGrowthRatio = currentPpsNum / startPpsNum;
+    if (ppsGrowthRatio <= 0) {
+      return -1;
+    }
+    const annualizationFactor = SECONDS_PER_YEAR2 / timeElapsed;
+    const apy = Math.pow(ppsGrowthRatio, annualizationFactor) - 1;
+    return apy;
+  }
+  /**
+   * Calculate simple APY (non-compounded) based on PPS growth
+   *
+   * @param poolName Pool to calculate APY for
+   * @param startPps PPS at the start of the period
+   * @param startTime Unix timestamp when startPps was recorded
+   * @returns Simple APY as a decimal
+   */
+  async calculateSimpleApy(poolName, startPps, startTime) {
+    const pool = getPoolByName(poolName);
+    if (!pool) throw new JlpdClientError(`Unknown pool: ${poolName}`);
+    const [stv, slot] = await Promise.all([
+      this.fetchStv(pool.mint),
+      this.connection.getSlot()
+    ]);
+    if (!stv) throw new JlpdClientError(`STV not found for pool: ${poolName}`);
+    const currentTime = await this.connection.getBlockTime(slot);
+    if (!currentTime) throw new JlpdClientError("Failed to get block time");
+    const startPpsNum = Number(startPps.toString()) / PPS_DECIMALS;
+    const currentPpsNum = Number(stv.pps.toString()) / PPS_DECIMALS;
+    const timeElapsed = currentTime - startTime;
+    if (timeElapsed <= 0) {
+      throw new JlpdClientError("Start time must be in the past");
+    }
+    const SECONDS_PER_YEAR2 = 365.25 * 24 * 60 * 60;
+    const growthRate = (currentPpsNum - startPpsNum) / startPpsNum;
+    const simpleApy = growthRate * (SECONDS_PER_YEAR2 / timeElapsed);
+    return simpleApy;
+  }
   // Get pool context for pool-specific operations (cached)
   pool(poolNameOrMint) {
     const key = typeof poolNameOrMint === "string" ? poolNameOrMint : poolNameOrMint.toBase58();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elmntl/jlpd-sdk",
-  "version": "0.1.0",
+  "version": "1.0.9",
   "description": "SDK for JLP.D (JLP Deconstructed) by Elemental",
   "main": "dist/index.js",
   "module": "dist/index.mjs",