@elmntl/jlpd-sdk 0.1.11 → 0.13.4

package/dist/jlpd-strategy/jlp-data.d.ts

@@ -0,0 +1,166 @@
+import { PublicKey } from "@solana/web3.js";
+import type { SolanaConnection } from "../common/connection";
+export type CustodyName = "SOL" | "ETH" | "WBTC" | "USDC" | "USDT";
+export interface JlpCustody {
+    name: CustodyName;
+    aumUsd: number;
+    weightBps: number;
+    priceUsd: number;
+}
+export interface JlpData {
+    timestamp: string;
+    totalAumUsd: number;
+    custodies: JlpCustody[];
+}
+/** Jupiter Perps Pool fee parameters (from on-chain Pool account) */
+export interface JlpPoolFees {
+    addRemoveLiquidityBps: number;
+    swapBps: number;
+    taxBps: number;
+    stableSwapBps: number;
+    stableSwapTaxBps: number;
+}
+/** Per-custody info including target weight and current weight */
+export interface JlpCustodyInfo {
+    mint: PublicKey;
+    name: CustodyName;
+    targetRatioBps: number;
+    currentRatioBps: number;
+    aumUsd: number;
+    isStable: boolean;
+}
+/** Full pool details: fees, custody weights, AUM, JLP price */
+export interface JlpPoolDetails {
+    fees: JlpPoolFees | null;
+    custodies: JlpCustodyInfo[];
+    poolAumUsd: number;
+    jlpPrice: number;
+    jlpSupply: number;
+}
+/**
+ * Reset the price memo. Intended for unit tests that mock global fetch with
+ * scenario-specific prices — module-level cache pollutes across tests when
+ * TTL has not expired, leading to assertion failures that depend on test
+ * ordering.
+ *
+ * Not part of the public surface for application code; cache TTL handles
+ * production. Exported under `__test__*` namespace convention so consumers
+ * tree-shake it out and never accidentally rely on cache invalidation.
+ */
+export declare function __test__resetPricesCache(): void;
+/**
+ * Fetch full JLP pool details: fee parameters, per-custody target/current
+ * weights, pool AUM, and JLP price.
+ *
+ * Reads the Pool account for fees and aumUsd, Custody accounts for per-asset
+ * data including target weights, and the JLP mint for total supply.
+ */
+export declare function fetchJlpPoolDetails(connection: SolanaConnection): Promise<JlpPoolDetails>;
+/**
+ * Estimate the addLiquidity fee for depositing into a specific JLP custody.
+ *
+ * Implements the Jupiter Perps fee formula:
+ * - If deposit moves custody weight TOWARD target: rebate (fee < baseFee)
+ * - If deposit moves custody weight AWAY from target: tax (fee > baseFee)
+ *
+ * Formula:
+ *   initDiff = |currentRatio - targetRatio|
+ *   finalDiff = |newRatio - targetRatio|
+ *   avgDiff = (initDiff + finalDiff) / 2
+ *   if improving: fee = max(baseFee - taxBps * avgDiff / 10000, 0)
+ *   if worsening: fee = baseFee + taxBps * avgDiff / 10000
+ */
+export declare function computeAddLiquidityFee(args: {
+    custodyAumUsd: number;
+    poolAumUsd: number;
+    targetRatioBps: number;
+    depositUsd: number;
+    fees: JlpPoolFees;
+    isStable: boolean;
+}): {
+    feeBps: number;
+    isDiscount: boolean;
+};
+export declare function fetchJlpCustodyData(connection: SolanaConnection): Promise<JlpData>;
+/** Public symbol used by the effective-weights API.
+ *
+ * Note: JLP custody is internally named "WBTC" but represents BTC exposure
+ * for sensitivity purposes — surfaced as `'BTC'` here per spec. */
+export type EffectiveWeightSymbol = "BTC" | "ETH" | "SOL" | "USDC" | "USDT";
+export interface AssetEffectiveWeight {
+    mint: PublicKey;
+    symbol: EffectiveWeightSymbol;
+    /** Effective USD contribution, normalized to 8 decimals. */
+    effUsd: bigint;
+    /** Share of total effective USD, in basis points (0–10000). */
+    effShareBps: number;
+    /** True if `(owned − locked) < 0`. Spot term clamped to 0 in `effUsd`. */
+    spotClamped: boolean;
+}
+export interface JlpEffectiveWeights {
+    assets: AssetEffectiveWeight[];
+    /** Sum of all `effUsd` values, 8 decimals. */
+    totalEffUsd: bigint;
+    /** Total pool aumUsd (including `guaranteed_usd`), 8 decimals — context only. */
+    totalAumUsd: bigint;
+}
+/** Inputs needed to compute effective USD for one custody.
+ *
+ * Decoupled from on-chain fetching so unit tests can drive the math directly. */
+export interface EffectiveWeightInput {
+    owned: bigint;
+    locked: bigint;
+    /** Raw debt u128 (DEBT_MULTIPLIER-scaled by 1e9 internally, then by 10^decimals). */
+    debt: bigint;
+    /** Raw borrow-lend interests accrued u128 (same scale as `debt`). */
+    borrowLendInterestsAccrued: bigint;
+    shortSizeUsd: bigint;
+    avgShortPriceUsd: bigint;
+    guaranteedUsd: bigint;
+    decimals: number;
+    /** Price scaled to 8 decimals (float price × 10^8, as bigint). */
+    priceScaled8: bigint;
+}
+export interface EffectiveWeightOutput {
+    /** (owned + netDebt − locked) × price, normalized to 8-decimal USD. Clamped to 0 if negative. */
+    spotEffUsd: bigint;
+    /** shortSize × price / avgShortPrice, normalized to 8-decimal USD. 0 if no shorts. */
+    shortEffUsd: bigint;
+    /** spotEffUsd + shortEffUsd. */
+    effUsd: bigint;
+    /** True if (owned + netDebt − locked) < 0 — spot term was clamped. */
+    spotClamped: boolean;
+    /** netDebt tokens applied to spot term (already converted to token-base units). */
+    netDebtTokens: bigint;
+}
+/** 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 ✓
+ */
+export declare function computeEffectiveUsd(input: EffectiveWeightInput): EffectiveWeightOutput;
+/**
+ * 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.
+ */
+export declare function fetchJlpEffectiveWeights(connection: SolanaConnection): Promise<JlpEffectiveWeights>;