@elmntl/jlpd-sdk 0.1.11 → 0.13.4

package/dist/jlpd-strategy/fluid-view.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Jupiter Lend (Fluid Vaults + Fluid Earn) read-only valuation helpers — TS mirror of
+ * `jlpd-strategy/programs/jlpd-strategy/src/utils/jup_lend_view.rs` (program
+ * `GXqt4ZH2UUBsLWwMNJiZMXza3q7xEGChfW8XjVRjLxr5`, mainnet).
+ *
+ * Pure decode + math, ALL-bigint (matching Rust's u128/i128 exactly — truncating division
+ * for the hop-rate math, ceil-division for debt). Answers the same question the on-chain
+ * `hedge_borrow`/`hedge_withdraw_collateral` guard answers: what LTV does a position imply,
+ * valued on the SAME Fluid oracle chain the vault itself liquidates on (never this program's
+ * own JLP NAV mark, `computeLiveJlpPriceUsd` — see `live-jlp-price.ts` — which is a DIFFERENT
+ * feed that can diverge from Fluid's exactly when liquidation risk is highest).
+ *
+ * Ported/derived from `github.com/Instadapp/fluid-solana-programs` the same way `oracle.rs`
+ * itself was ported (fixed-byte-offset decode, no new on-chain-format dependency). Every
+ * offset below is cross-checked against `jup_lend_view.rs`'s own named constants.
+ */
+import { PublicKey } from "@solana/web3.js";
+import type { SolanaConnection } from "../common/connection";
+import type { HedgePositionSlot } from "./hedge-state";
+export declare const JUP_LEND_EARN_MIN_SANE_RATE = 1000000000000n;
+export declare const JUP_LEND_EARN_MAX_SANE_RATE: bigint;
+/** `ratio_x48` at tick 0 (`1 << 48`). */
+export declare const FLUID_ZERO_TICK_SCALED_RATIO: bigint;
+/** `ratio_x48 = 1.0015^tick * 2^48`. */
+export declare function getRatioAtTick(tick: number): bigint;
+/** Minimal identity of a fetched on-chain account, as returned by `connection.getAccountInfo`. */
+export interface RawAccount {
+    pubkey: PublicKey;
+    owner: PublicKey;
+    data: Buffer;
+}
+/** Decoded essentials of a Fluid `Position` (Jupiter Lend Borrow position NFT account). */
+export interface FluidPosition {
+    vaultId: number;
+    isSupplyOnly: boolean;
+    tick: number;
+    /** Tick GENERATION this position was placed at. Liquidation-current iff the canonical Tick has
+     *  `!isLiquidated && totalIds === tickId` (see `requireFluidPositionLiquidationCurrent`). */
+    tickId: number;
+    /** Raw collateral (`Position.supply_amount`), Fluid's normalized 9-decimal basis. */
+    collateralRaw: bigint;
+    /** Raw dust debt (`Position.dust_debt_amount`), same basis. */
+    dustDebtRaw: bigint;
+}
+/**
+ * Decode + validate a Fluid `Position` account. `expected` pins it to the caller's canonical
+ * pubkey (e.g. one `HedgePositionSlot.borrowPosition`) — mirrors `decode_fluid_position`.
+ */
+export declare function decodeFluidPosition(account: RawAccount, expected: PublicKey): FluidPosition;
+/** Decoded essentials of a Fluid `Tick` account. */
+export interface FluidTick {
+    vaultId: number;
+    tick: number;
+    isLiquidated: boolean;
+    /** Generation counter — increments when the tick is FULLY liquidated. */
+    totalIds: number;
+}
+/**
+ * Canonical Tick PDA `[b"tick", vault_id_le2, (tick − MIN_TICK)_i32_le4]` under the Fluid vault
+ * program — byte-identical to the on-chain `derive_fluid_tick_pda` (golden-vector tested).
+ */
+export declare function deriveFluidTickPda(vaultId: number, tick: number): PublicKey;
+/**
+ * The Tick account settle_yield's per-slot triple must carry for `position`: the canonical
+ * `Tick(vaultId, position.tick)` for an ACTIVE debt position, or the `Tick(vaultId, MIN_TICK)`
+ * cold placeholder for a supply-only one (key-pinned by the program; the placeholder may not
+ * exist on chain — contents are ignored, only the key matters).
+ */
+export declare function settleTickPdaForPosition(position: FluidPosition): PublicKey;
+/**
+ * Decode + fully validate a Fluid `Tick` against `expected` (the canonical PDA) — mirrors the
+ * on-chain `decode_fluid_tick`: key equality, Fluid ownership, discriminator, min length, and a
+ * CANONICAL `is_liquidated` byte (any value other than 0/1 rejects).
+ */
+export declare function decodeFluidTick(account: RawAccount, expected: PublicKey): FluidTick;
+/**
+ * Mirror of the on-chain liquidation-staleness gate (`require_fluid_position_liquidation_current`):
+ * throws unless `position`'s stored bytes are proven liquidation-current by its canonical Tick.
+ * For a supply-only position only the placeholder KEY is checked (`tickAccount` may be null —
+ * the placeholder need not exist). For an active position the Tick must decode cleanly and pass
+ * `!isLiquidated && totalIds === tickId` (strict generation equality — `<` is not a valid Fluid
+ * transition and also rejects).
+ */
+export declare function requireFluidPositionLiquidationCurrent(position: FluidPosition, tickAccount: RawAccount | null): void;
+/** Decoded exchange prices of a Fluid `VaultState`. */
+export interface FluidVaultExchangePrices {
+    vaultId: number;
+    supplyExPrice: bigint;
+    borrowExPrice: bigint;
+    /** Unix seconds. Only ENFORCED as a freshness bound by `requireFluidVaultStateFresh`. */
+    lastUpdateTimestamp: bigint;
+}
+/**
+ * Decode + validate a Fluid `VaultState` account. `expected` pins it to the caller's canonical
+ * pubkey (e.g. one `HedgePositionSlot.vaultState`) — mirrors `decode_fluid_vault_state`.
+ */
+export declare function decodeFluidVaultState(account: RawAccount, expected: PublicKey): FluidVaultExchangePrices;
+/**
+ * Require a Fluid `VaultState`'s `lastUpdateTimestamp` to be within
+ * `FLUID_VAULT_STATE_MAX_STALENESS_SECS` (24h) of `nowUnixSec` — mirrors
+ * `require_fluid_vault_state_fresh` — the check every risk-limit valuation applies:
+ * `settle_yield`'s NAV fold, the `hedge_supply_collateral` pledge cap, and the per-op LTV
+ * guards on `hedge_borrow`/`hedge_withdraw_collateral` (Fluid's `operate` CPI does not
+ * refresh `last_update_timestamp`, so a post-`operate` read is not automatically fresh).
+ */
+export declare function requireFluidVaultStateFresh(vaultState: Pick<FluidVaultExchangePrices, "lastUpdateTimestamp">, nowUnixSec: bigint): void;
+/** Decoded essentials of a Fluid `VaultConfig`. */
+export interface FluidVaultConfigInfo {
+    vaultId: number;
+    oracle: PublicKey;
+}
+/**
+ * Decode + validate a Fluid `VaultConfig` account. `expected` pins it to the caller's canonical
+ * pubkey (e.g. one `HedgePositionSlot.vaultConfig`) — mirrors the account-loading half of
+ * `read_fluid_price_1e15`.
+ */
+export declare function decodeFluidVaultConfig(account: RawAccount, expected: PublicKey): FluidVaultConfigInfo;
+/**
+ * Bind a Fluid position's, vault state's, and vault config's `vaultId` together in one call —
+ * mirrors `require_fluid_vault_id_bind`.
+ */
+export declare function requireFluidVaultIdBind(positionVaultId: number, vaultStateVaultId: number, vaultConfigVaultId: number): void;
+/**
+ * Collateral (always JLP, 6 decimals) held by `position`, interest-adjusted and FLOORED —
+ * mirrors `collateral_jlp_normal` exactly.
+ */
+export declare function collateralJlpNormal(position: FluidPosition, vaultState: FluidVaultExchangePrices): bigint;
+/**
+ * TRUE debt owed by `position` in `mintDecimals`-decimal native units of the debt mint,
+ * interest-adjusted and CEILED at both conversion stages.
+ *
+ * Fluid stores a position as (tick, collateral, dust): `operate` rounds the debt/col ratio UP one
+ * tick (1.0015 steps) and books the excess as `dust_debt`, so the true owed amount is
+ * `tick_implied − dust` (Fluid's own `get_net_debt_raw` = `debt_raw.safe_sub(dust_debt_raw)`,
+ * structs.rs). Adding dust — the sign this function shipped with — overstates debt by 2×dust,
+ * a random ≤~30bps of total debt that re-rolls on every operate.
+ */
+export declare function debtNativeCeil(position: FluidPosition, vaultState: FluidVaultExchangePrices, mintDecimals: number): bigint;
+/**
+ * The DEPLOYED jlpd-strategy program's debt view (`jup_lend_view.rs::debt_native_ceil`), which
+ * ADDS dust — overstating true debt by 2×dust. Wrong as economics, but the program's own LTV /
+ * repay guards are enforced against THIS number until the program-side sign fix ships, so any
+ * caller sizing an operation the PROGRAM must accept has to use this view, not the true one.
+ */
+export declare function debtNativeCeilProgramView(position: FluidPosition, vaultState: FluidVaultExchangePrices, mintDecimals: number): bigint;
+/**
+ * `ltvBps = ceil(debtNative * 10_000 / colInDebtNative)`, mirrors `position_ltv_bps` exactly —
+ * `debtNative == 0` short-circuits to 0; a non-zero debt against zero-valued collateral
+ * saturates to `0xFFFF` (u16::MAX), matching the on-chain guard's "maximally unsafe" reading.
+ */
+export declare function positionLtvBps(debtNative: bigint, debtDecimals: number, collateralJlpNative: bigint, price1e15: bigint): number;
+/** One decoded `Sources` element: which account to read, whether to invert, and its type tag. */
+export interface OracleSourceMeta {
+    sourcePk: PublicKey;
+    invert: boolean;
+    sourceType: number;
+}
+/**
+ * Peek a Fluid oracle config account's own declared hop count (1 or 2) — mirrors
+ * `read_oracle_hop_count` (sizes how many feed accounts to fetch before decoding any price).
+ */
+export declare function readOracleHopCount(account: RawAccount, expected: PublicKey): number;
+/**
+ * Read one Fluid vault's pair-native price (1e15 precision — collateral, always JLP, valued in
+ * that vault's OWN debt mint), off the SAME oracle chain Fluid itself liquidates on. Pure
+ * orchestrator over already-fetched accounts — mirrors `read_fluid_price_1e15` exactly.
+ * See `readFluidPrice1e15` for the async fetch-and-compute convenience wrapper.
+ */
+export declare function readFluidPrice1e15FromAccounts(args: {
+    vaultConfig: RawAccount;
+    expectedVaultConfig: PublicKey;
+    positionVaultId: number;
+    vaultStateVaultId: number;
+    oracleCfg: RawAccount;
+    expectedOracle: PublicKey;
+    feedAccounts: RawAccount[];
+    nowUnixSec: bigint;
+    currentSlot: bigint;
+}): bigint;
+/**
+ * Fetch + decode one `HedgePositionSlot`'s pair-native oracle price (1e15), then read that
+ * slot's Position/VaultState and compute its LTV — the async convenience wrapper matching
+ * `hedge_borrow`'s / `hedge_withdraw_collateral`'s guard basis exactly. `debtDecimals` must be
+ * the debt mint's own `Mint.decimals` (fetch separately; not re-derived here).
+ */
+export declare function fetchFluidSlotLtv(connection: SolanaConnection, slot: HedgePositionSlot, debtDecimals: number): Promise<{
+    ltvBps: number;
+    debtNative: bigint;
+    collateralJlpNative: bigint;
+    price1e15: bigint;
+    position: FluidPosition;
+    vaultState: FluidVaultExchangePrices;
+}>;
+/**
+ * Read the Jupiter Lend Earn `lending` account's stored exchange rate (1e12 precision) for one
+ * fToken — mirrors `earn_exchange_rate` exactly (uses the STORED rate directly, no forward
+ * accrual; `lending`'s identity must be pinned by the caller).
+ */
+export declare function earnExchangeRate(account: RawAccount): bigint;