@elemental-stv-core/sdk 0.8.0 → 0.9.1

package/dist/jlpd-strategy/jlp-data.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchJlpPoolDetails = fetchJlpPoolDetails;
 exports.computeAddLiquidityFee = computeAddLiquidityFee;
 exports.fetchJlpCustodyData = fetchJlpCustodyData;
+exports.computeEffectiveUsd = computeEffectiveUsd;
+exports.fetchJlpEffectiveWeights = fetchJlpEffectiveWeights;
 const web3_js_1 = require("@solana/web3.js");
 const constants_1 = require("./constants");
 const CUSTODIES = [
@@ -403,3 +405,170 @@ async function fetchJlpCustodyData(connection) {
         custodies: results,
     };
 }
+/** Map JLP custody internal name to public symbol used by effective-weights API. */
+function toEffSymbol(name) {
+    return name === "WBTC" ? "BTC" : name;
+}
+/** Convert a float USD price to an 8-decimal-scaled bigint.
+ *
+ * Uses 12-decimal intermediate to preserve sub-1¢ precision before truncation. */
+function priceToScaled8(priceFloat) {
+    if (!isFinite(priceFloat) || priceFloat <= 0)
+        return 0n;
+    // Round to 12 decimals first to avoid float artifacts, then scale to 8.
+    const scaled12 = BigInt(Math.round(priceFloat * 1e12));
+    return scaled12 / 10000n; // 12 → 8 decimals
+}
+/** Compute effective USD (price-sensitivity-weighted) for a single custody.
+ *
+ * Formula (in 8-decimal USD):
+ *   netDebtTokens = max(debt − borrowLendInterestsAccrued, 0) / DEBT_MULTIPLIER
+ *   spot          = (owned + netDebtTokens − locked) × price_8dec / 10^decimals
+ *   short         = shortSize_6dec × price_8dec / avgShortPrice_6dec  (zeroed if either operand is 0)
+ *   effUsd        = max(spot, 0) + short
+ *
+ * Algebra for unit normalization:
+ *   - owned/locked/netDebt is in 10^decimals base units; price is 10^8 USD.
+ *     spot = (owned + netDebt − locked) × price_8dec / 10^decimals → 10^8 USD ✓
+ *   - debt is stored as u128 scaled by DEBT_MULTIPLIER (1e9) on top of 10^decimals.
+ *     netDebtTokens = (debt − borrowLendInterestsAccrued) / DEBT_MULTIPLIER
+ *     (integer division — small rounding under one base unit, acceptable).
+ *   - shortSize and avgShortPrice are both 10^6; ratio is dimensionless.
+ *     short = shortSize × price_8dec / avgShortPrice → 10^8 USD ✓
+ */
+function computeEffectiveUsd(input) {
+    const { owned, locked, debt, borrowLendInterestsAccrued, shortSizeUsd, avgShortPriceUsd, decimals, priceScaled8, } = input;
+    const tokScale = 10n ** BigInt(decimals);
+    // Net debt tokens: (debt − interestsAccrued) / DEBT_MULTIPLIER, clamped to 0.
+    // Matches `calculateDebtTokens` in `calculateCustodyAum` to keep both code paths
+    // consistent. DEBT_MULTIPLIER is 1e9, scaled before token decimals.
+    const DEBT_MULTIPLIER_BIG = 1000000000n; // 1e9, matches DEBT_MULTIPLIER constant
+    let netDebtTokens = 0n;
+    if (debt > borrowLendInterestsAccrued) {
+        netDebtTokens = (debt - borrowLendInterestsAccrued) / DEBT_MULTIPLIER_BIG;
+    }
+    // Spot term: (owned + netDebt − locked) × price / 10^decimals
+    // Use signed bigint subtraction; clamp to 0 if (owned + netDebt) < locked.
+    const netTokens = owned + netDebtTokens - locked; // bigint — can go negative
+    let spotEffUsd;
+    let spotClamped = false;
+    if (netTokens <= 0n) {
+        spotEffUsd = 0n;
+        if (netTokens < 0n)
+            spotClamped = true;
+    }
+    else {
+        spotEffUsd = (netTokens * priceScaled8) / tokScale;
+    }
+    // Short term: only contributes when both shortSize and avgShortPrice > 0.
+    // Numerator stays in u128 range comfortably (shortSize_6dec × price_8dec).
+    let shortEffUsd = 0n;
+    if (shortSizeUsd > 0n && avgShortPriceUsd > 0n && priceScaled8 > 0n) {
+        shortEffUsd = (shortSizeUsd * priceScaled8) / avgShortPriceUsd;
+    }
+    return {
+        spotEffUsd,
+        shortEffUsd,
+        effUsd: spotEffUsd + shortEffUsd,
+        spotClamped,
+        netDebtTokens,
+    };
+}
+/** Compute basis-point shares for each effective USD value, summing to 10000.
+ *
+ * Uses largest-remainder allocation to guarantee the bps sum equals exactly 10000
+ * even with rounding. (Naive `round(eff_i / total × 10000)` per-asset can drift
+ * by up to `n` bps cumulatively.) Returns 0s for all assets if total is 0.
+ */
+function computeBpsShares(effs) {
+    const total = effs.reduce((s, e) => s + e, 0n);
+    if (total === 0n)
+        return effs.map(() => 0);
+    // Floor allocation
+    const exact = effs.map((e) => Number((e * 10000n) / total));
+    const allocated = exact.reduce((s, b) => s + b, 0);
+    let remaining = 10000 - allocated;
+    if (remaining <= 0)
+        return exact;
+    // Distribute remaining bps to the assets with largest fractional remainders.
+    // Compute remainder = (e × 10000) mod total, ranked descending.
+    const remainders = effs.map((e, i) => ({
+        i,
+        rem: (e * 10000n) % total,
+    }));
+    remainders.sort((a, b) => (a.rem === b.rem ? 0 : a.rem > b.rem ? -1 : 1));
+    const result = exact.slice();
+    for (let k = 0; k < remainders.length && remaining > 0; k++) {
+        result[remainders[k].i]++;
+        remaining--;
+    }
+    return result;
+}
+/**
+ * Fetch JLP pool effective-weight composition.
+ *
+ * Returns price-sensitivity-weighted shares per asset, dropping `guaranteed_usd`
+ * from the per-asset weight calculation. Suitable for rebalance planners that
+ * want to track the pool's true delta-1 composition rather than reported aumUsd.
+ *
+ * Reuses the same on-chain custody parser and Jupiter Price API source as
+ * `fetchJlpCustodyData` to keep numbers consistent across callers.
+ *
+ * @returns assets in fixed order: BTC, ETH, SOL, USDC, USDT.
+ */
+async function fetchJlpEffectiveWeights(connection) {
+    const [custodies, pricesByMint] = await Promise.all([
+        fetchAllCustodies(connection),
+        fetchPrices(),
+    ]);
+    // Resolve price per custody (stables fall back to $1.00 when API is missing them).
+    const priceFloat = {};
+    for (const cfg of CUSTODIES) {
+        const p = pricesByMint[cfg.mintAddress];
+        if (p === undefined || p === null) {
+            if (cfg.isStable) {
+                priceFloat[cfg.name] = 1;
+            }
+            else {
+                throw new Error(`Missing price for non-stable asset ${cfg.name} (mint: ${cfg.mintAddress})`);
+            }
+        }
+        else {
+            priceFloat[cfg.name] = p;
+        }
+    }
+    // Compute effective USD per custody.
+    const computed = custodies.map((raw) => {
+        const effInput = {
+            owned: raw.owned,
+            locked: raw.locked,
+            debt: raw.debt,
+            borrowLendInterestsAccrued: raw.borrowLendInterestsAccrued,
+            shortSizeUsd: raw.globalShortSizes,
+            avgShortPriceUsd: raw.globalShortAveragePrices,
+            guaranteedUsd: raw.guaranteedUsd,
+            decimals: raw.cfg.decimals,
+            priceScaled8: priceToScaled8(priceFloat[raw.cfg.name]),
+        };
+        return { raw, out: computeEffectiveUsd(effInput) };
+    });
+    const effs = computed.map((c) => c.out.effUsd);
+    const bpsShares = computeBpsShares(effs);
+    const assets = computed.map((c, i) => ({
+        mint: new web3_js_1.PublicKey(c.raw.cfg.mintAddress),
+        symbol: toEffSymbol(c.raw.cfg.name),
+        effUsd: c.out.effUsd,
+        effShareBps: bpsShares[i],
+        spotClamped: c.out.spotClamped,
+    }));
+    const totalEffUsd = effs.reduce((s, e) => s + e, 0n);
+    // Total pool aumUsd in 8-decimal USD = aumUsd from `calculateCustodyAum` (float)
+    // re-aggregated. We reuse the existing path but normalize to bigint 8-decimals.
+    // Each calculateCustodyAum return is a float USD; multiply by 1e8 and round.
+    const totalAumFloat = custodies.reduce((sum, raw) => {
+        const a = calculateCustodyAum(raw, priceFloat[raw.cfg.name] ?? 1);
+        return sum + a.aumUsd;
+    }, 0);
+    const totalAumUsd = BigInt(Math.round(totalAumFloat * 1e8));
+    return { assets, totalEffUsd, totalAumUsd };
+}

package/dist/p-stv-core/index.d.ts

@@ -8,3 +8,4 @@ export * from "./remaining-accounts";
 export * from "./send-tx";
 export * from "./sol-wrap";
 export * from "./prices";
+export * from "./lut";

package/dist/p-stv-core/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./remaining-accounts"), exports);
 __exportStar(require("./send-tx"), exports);
 __exportStar(require("./sol-wrap"), exports);
 __exportStar(require("./prices"), exports);
+__exportStar(require("./lut"), exports);

package/dist/p-stv-core/lut.d.ts

@@ -0,0 +1,41 @@
+/**
+ * p-STV Core Address Lookup Table helpers.
+ *
+ * Packages the STATIC (per-program, not per-tx) p-stv-core accounts into a LUT
+ * so versioned transactions can compress them into a single 1-byte index.
+ *
+ * Usage:
+ *   // Owner flow (one-time):
+ *   const [createIx, lutAddress] = AddressLookupTableProgram.createLookupTable({...});
+ *   const extendIxs = buildPstvCoreLutExtendIxs(payer, lutAddress);
+ *   // send createIx + extendIxs
+ *
+ *   // Consumer flow (every tx):
+ *   const lutAccount = await resolvePstvCoreLut(connection, lutAddress);
+ *   const msg = new TransactionMessage({...}).compileToV0Message([lutAccount]);
+ *
+ * NOTE: Only program IDs, the GlobalConfig PDA, and token/ATA/compute-budget
+ * program IDs. Per-vault PDAs (stv, evMint, vaultAta, withdrawRequest,
+ * managerRole) and strategy/lend state live in separate LUTs.
+ */
+import { AddressLookupTableAccount, Connection, PublicKey, TransactionInstruction } from "@solana/web3.js";
+/**
+ * Static p-stv-core accounts for the shared LUT. Order is deterministic so
+ * callers can cross-check against an on-chain LUT.
+ */
+export declare function getPstvCoreLutAddresses(programId?: PublicKey): PublicKey[];
+/**
+ * Build `extendLookupTable` ixs pushing every static p-stv-core account
+ * into `lutAddress`. Chunks at `MAX_ADDRS_PER_EXTEND` for safety.
+ *
+ * @param payer    Wallet funding + authority of the LUT.
+ * @param lutAddress LUT to extend (must be created via
+ *                   `AddressLookupTableProgram.createLookupTable` first).
+ * @param programId Override for p-stv-core program ID (defaults to mainnet).
+ */
+export declare function buildPstvCoreLutExtendIxs(payer: PublicKey, lutAddress: PublicKey, programId?: PublicKey): TransactionInstruction[];
+/**
+ * Fetch an `AddressLookupTableAccount` by address for use in
+ * `TransactionMessage.compileToV0Message([lutAccount])`.
+ */
+export declare function resolvePstvCoreLut(connection: Pick<Connection, "getAddressLookupTable">, lutAddress: PublicKey): Promise<AddressLookupTableAccount>;

package/dist/p-stv-core/lut.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * p-STV Core Address Lookup Table helpers.
+ *
+ * Packages the STATIC (per-program, not per-tx) p-stv-core accounts into a LUT
+ * so versioned transactions can compress them into a single 1-byte index.
+ *
+ * Usage:
+ *   // Owner flow (one-time):
+ *   const [createIx, lutAddress] = AddressLookupTableProgram.createLookupTable({...});
+ *   const extendIxs = buildPstvCoreLutExtendIxs(payer, lutAddress);
+ *   // send createIx + extendIxs
+ *
+ *   // Consumer flow (every tx):
+ *   const lutAccount = await resolvePstvCoreLut(connection, lutAddress);
+ *   const msg = new TransactionMessage({...}).compileToV0Message([lutAccount]);
+ *
+ * NOTE: Only program IDs, the GlobalConfig PDA, and token/ATA/compute-budget
+ * program IDs. Per-vault PDAs (stv, evMint, vaultAta, withdrawRequest,
+ * managerRole) and strategy/lend state live in separate LUTs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPstvCoreLutAddresses = getPstvCoreLutAddresses;
+exports.buildPstvCoreLutExtendIxs = buildPstvCoreLutExtendIxs;
+exports.resolvePstvCoreLut = resolvePstvCoreLut;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const constants_1 = require("./constants");
+const pda_1 = require("./pda");
+/** Max addresses per `extendLookupTable` ix (Solana runtime limit). */
+const MAX_ADDRS_PER_EXTEND = 20;
+/**
+ * Static p-stv-core accounts for the shared LUT. Order is deterministic so
+ * callers can cross-check against an on-chain LUT.
+ */
+function getPstvCoreLutAddresses(programId = constants_1.PROGRAM_ID) {
+    const [configPda] = (0, pda_1.findConfigPda)(programId);
+    return [
+        programId,
+        web3_js_1.SystemProgram.programId,
+        spl_token_1.TOKEN_PROGRAM_ID,
+        spl_token_1.TOKEN_2022_PROGRAM_ID,
+        spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
+        web3_js_1.ComputeBudgetProgram.programId,
+        configPda,
+    ];
+}
+/**
+ * Build `extendLookupTable` ixs pushing every static p-stv-core account
+ * into `lutAddress`. Chunks at `MAX_ADDRS_PER_EXTEND` for safety.
+ *
+ * @param payer    Wallet funding + authority of the LUT.
+ * @param lutAddress LUT to extend (must be created via
+ *                   `AddressLookupTableProgram.createLookupTable` first).
+ * @param programId Override for p-stv-core program ID (defaults to mainnet).
+ */
+function buildPstvCoreLutExtendIxs(payer, lutAddress, programId = constants_1.PROGRAM_ID) {
+    const addresses = getPstvCoreLutAddresses(programId);
+    const ixs = [];
+    for (let i = 0; i < addresses.length; i += MAX_ADDRS_PER_EXTEND) {
+        const chunk = addresses.slice(i, i + MAX_ADDRS_PER_EXTEND);
+        ixs.push(web3_js_1.AddressLookupTableProgram.extendLookupTable({
+            payer,
+            authority: payer,
+            lookupTable: lutAddress,
+            addresses: chunk,
+        }));
+    }
+    return ixs;
+}
+/**
+ * Fetch an `AddressLookupTableAccount` by address for use in
+ * `TransactionMessage.compileToV0Message([lutAccount])`.
+ */
+async function resolvePstvCoreLut(connection, lutAddress) {
+    const { value } = await connection.getAddressLookupTable(lutAddress);
+    if (!value) {
+        throw new Error(`p-stv-core LUT not found at ${lutAddress.toBase58()} — create it first with buildPstvCoreLutExtendIxs`);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elemental-stv-core/sdk",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "TypeScript SDK for Elemental Vaults — p-STV Core, Elemental Lend, JLPD Strategy",
   "license": "Apache-2.0",
   "keywords": [
@@ -46,6 +46,7 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "TS_NODE_TRANSPILE_ONLY=true mocha --require ts-node/register --extensions ts \"src/**/__tests__/**/*.test.ts\"",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {
@@ -55,6 +56,11 @@
     "@solana/spl-token": "^0.4.0",
     "@solana/web3.js": "^1.95.0",
     "@types/bn.js": "^5.2.0",
+    "@types/chai": "^4.3.20",
+    "@types/mocha": "^10.0.10",
+    "chai": "^4.5.0",
+    "mocha": "^10.8.2",
+    "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
   },
   "peerDependencies": {