@elmntl/jlpd-sdk 0.2.0 → 0.13.4

package/dist/jlpd-strategy/fluid-view.js

@@ -0,0 +1,799 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLUID_ZERO_TICK_SCALED_RATIO = exports.JUP_LEND_EARN_MAX_SANE_RATE = exports.JUP_LEND_EARN_MIN_SANE_RATE = void 0;
+exports.getRatioAtTick = getRatioAtTick;
+exports.decodeFluidPosition = decodeFluidPosition;
+exports.deriveFluidTickPda = deriveFluidTickPda;
+exports.settleTickPdaForPosition = settleTickPdaForPosition;
+exports.decodeFluidTick = decodeFluidTick;
+exports.requireFluidPositionLiquidationCurrent = requireFluidPositionLiquidationCurrent;
+exports.decodeFluidVaultState = decodeFluidVaultState;
+exports.requireFluidVaultStateFresh = requireFluidVaultStateFresh;
+exports.decodeFluidVaultConfig = decodeFluidVaultConfig;
+exports.requireFluidVaultIdBind = requireFluidVaultIdBind;
+exports.collateralJlpNormal = collateralJlpNormal;
+exports.debtNativeCeil = debtNativeCeil;
+exports.debtNativeCeilProgramView = debtNativeCeilProgramView;
+exports.positionLtvBps = positionLtvBps;
+exports.readOracleHopCount = readOracleHopCount;
+exports.readFluidPrice1e15FromAccounts = readFluidPrice1e15FromAccounts;
+exports.fetchFluidSlotLtv = fetchFluidSlotLtv;
+exports.earnExchangeRate = earnExchangeRate;
+const web3_js_1 = require("@solana/web3.js");
+const constants_1 = require("./constants");
+// ============================================================================
+// Discriminators (sha256("account:<Type>")[..8], except Chainlink's own scheme)
+// ============================================================================
+const VAULT_CONFIG_DISCRIMINATOR = Buffer.from([99, 86, 43, 216, 184, 102, 119, 77]);
+const VAULT_STATE_DISCRIMINATOR = Buffer.from([228, 196, 82, 165, 98, 210, 235, 152]);
+const POSITION_DISCRIMINATOR = Buffer.from([170, 188, 143, 228, 122, 64, 247, 208]);
+const ORACLE_CONFIG_DISCRIMINATOR = Buffer.from([139, 194, 131, 179, 140, 179, 229, 244]);
+/** Chainlink's own discriminator (`data_feeds_store_v1::TRANSMISSIONS_DISCRIMINATOR`) — NOT sha256("account:X"). */
+const CHAINLINK_TRANSMISSIONS_DISCRIMINATOR = Buffer.from([96, 179, 69, 66, 128, 129, 73, 117]);
+/** `sha256("account:PriceUpdateV2")[..8]` — `pyth-solana-receiver-sdk` 1.0.1's own Anchor discriminator. */
+const PYTH_PRICE_UPDATE_DISCRIMINATOR = Buffer.from([0x22, 0xf1, 0x23, 0x63, 0x9d, 0x7e, 0xf4, 0xcd]);
+// ============================================================================
+// Byte offsets — mirror jup_lend_view.rs's own named offset constants exactly.
+// VaultConfig/VaultState/Position are zero-copy `#[repr(C, packed)]`: 8-byte disc then every
+// field packed in declaration order, no padding.
+// ============================================================================
+const VAULT_CONFIG_OFFSET_VAULT_ID = 8;
+const VAULT_CONFIG_OFFSET_ORACLE = 26;
+const VAULT_CONFIG_MIN_LEN = 219;
+const VAULT_STATE_OFFSET_VAULT_ID = 8;
+const VAULT_STATE_OFFSET_SUPPLY_EX_PRICE = 99;
+const VAULT_STATE_OFFSET_BORROW_EX_PRICE = 107;
+const VAULT_STATE_OFFSET_LAST_UPDATE_TIMESTAMP = 119;
+const VAULT_STATE_MIN_LEN = 127;
+/** Fluid's liquidity-layer floor: exchange prices init at exactly 1e12 and only ever increase. */
+const VAULT_STATE_MIN_EX_PRICE = 1000000000000n; // 1e12
+/** `settle_yield`'s NAV-fold staleness bound (24h) — see `jup_lend_view.rs`'s doc comment. */
+const FLUID_VAULT_STATE_MAX_STALENESS_SECS = 86400n;
+const POSITION_OFFSET_VAULT_ID = 8;
+const POSITION_OFFSET_IS_SUPPLY_ONLY = 46;
+const POSITION_OFFSET_TICK = 47;
+/** `Position.tick_id` u32 — the tick GENERATION this position was placed at (between `tick` @47
+ *  and `supply_amount` @55). Mirrors `jup_lend_view.rs::POSITION_OFFSET_TICK_ID`. */
+const POSITION_OFFSET_TICK_ID = 51;
+const POSITION_OFFSET_COLLATERAL = 55;
+const POSITION_OFFSET_DUST_DEBT = 63;
+const POSITION_MIN_LEN = 71;
+// --- Fluid `Tick` account (mirrors jup_lend_view.rs's TICK_* constants) ---
+const TICK_DISCRIMINATOR = Buffer.from([176, 94, 67, 247, 133, 173, 7, 115]);
+const TICK_OFFSET_VAULT_ID = 8; // u16
+const TICK_OFFSET_TICK = 10; // i32
+const TICK_OFFSET_IS_LIQUIDATED = 14; // u8 (canonical 0/1)
+const TICK_OFFSET_TOTAL_IDS = 15; // u32
+const TICK_MIN_LEN = 40;
+const TICK_SEED = Buffer.from("tick");
+const ORACLE_CFG_OFFSET_SOURCES_LEN = 10;
+const ORACLE_CFG_OFFSET_SOURCES = 14;
+const ORACLE_SOURCE_STRIDE = 66;
+const ORACLE_SOURCE_OFF_PUBKEY = 0;
+const ORACLE_SOURCE_OFF_INVERT = 32;
+const ORACLE_SOURCE_OFF_TYPE = 65;
+const ORACLE_SOURCE_TYPE_PYTH = 0;
+const ORACLE_SOURCE_TYPE_CHAINLINK = 4;
+const CHAINLINK_OFFSET_DECIMALS = 138;
+const CHAINLINK_OFFSET_LATEST_ROUND_ID = 143;
+const CHAINLINK_OFFSET_LIVE_LENGTH = 148;
+const CHAINLINK_OFFSET_SLOT = 200;
+const CHAINLINK_OFFSET_ANSWER = 216;
+const CHAINLINK_MIN_LEN = CHAINLINK_OFFSET_ANSWER + 16; // 232
+const CHAINLINK_MAX_STALENESS_SECS = 7200n;
+const AVG_SLOT_TIME_MS = 400n;
+const ORACLE_RATE_OUTPUT_DECIMALS = 15;
+const PYTH_OFFSET_VERIFICATION_LEVEL = 40;
+const PYTH_VERIFICATION_LEVEL_FULL = 1;
+const PYTH_OFFSET_PRICE = 73;
+const PYTH_OFFSET_CONF = 81;
+const PYTH_OFFSET_EXPONENT = 89;
+const PYTH_OFFSET_PUBLISH_TIME = 93;
+const PYTH_MIN_LEN = PYTH_OFFSET_PUBLISH_TIME + 8; // 101
+const PYTH_CONFIDENCE_SCALE_FACTOR_LIQUIDATE = 25n;
+const PYTH_MAX_STALENESS_SECS = 7200n;
+const PYTH_MAX_ABS_EXPONENT = 15;
+/** Jup-Lend Earn `lending` account — `tokenExchangePrice: u64` at 1e12 precision. */
+const LENDING_OFFSET_EXCHANGE_RATE = 115;
+const LENDING_MIN_LEN = LENDING_OFFSET_EXCHANGE_RATE + 8;
+const LENDING_DISCRIMINATOR = Buffer.from([135, 199, 82, 16, 249, 131, 182, 241]);
+exports.JUP_LEND_EARN_MIN_SANE_RATE = 1000000000000n; // 1e12
+exports.JUP_LEND_EARN_MAX_SANE_RATE = 1000n * 1000000000000n;
+// ============================================================================
+// Precision constants
+// ============================================================================
+const EXCHANGE_PRICES_PRECISION = 1000000000000n; // 1e12
+const FLUID_MAX_TOKEN_DECIMALS = 9;
+const TOKEN_DECIMALS_JLP = 6;
+/** `10^(RATE_OUTPUT_DECIMALS)`; JLP's 6-dec collapses `collateral_value_in_debt_native`'s stage 1 to `/1e15`. */
+const JLP_PRICE_1E15_PRECISION = 1000000000000000n;
+/** Oracle chain's own accumulator base + per-hop combine divisor. */
+const ORACLE_RATE_SCALE = 1000000000000000n; // 1e15
+/** `10^(RATE_OUTPUT_DECIMALS * 2)` — invert numerator: `rate = 1e30 / rate`. */
+const ORACLE_INVERT_NUMERATOR = 1000000000000000000000000000000n; // 1e30
+/** Defense-in-depth clamp — applies ONLY to a single-hop (direct USD) oracle chain. */
+const MIN_JLP_PRICE_1E15 = 500000000000000n; // $0.50
+const MAX_JLP_PRICE_1E15 = 50000000000000000n; // $50.00
+// ============================================================================
+// Fluid tick math — faithful port of `library::math::tick::TickMath::get_ratio_at_tick`
+// (fluid-solana-programs crates/library/src/math/tick.rs:9-117). Same FACTOR table, same
+// bit-by-bit accumulation, same positive-tick reciprocal + round-up correction.
+// ============================================================================
+const FLUID_MIN_TICK = -16383;
+const FLUID_MAX_TICK = 16383;
+/** "No active tick" sentinel — i32::MIN. */
+const FLUID_COLD_TICK = -2147483648;
+/** `ratio_x48` at tick 0 (`1 << 48`). */
+exports.FLUID_ZERO_TICK_SCALED_RATIO = 1n << 48n;
+const U128_MAX = (1n << 128n) - 1n;
+// FACTOR00..FACTOR14 = 2^64 / 1.0015^(2^i) — tick.rs:24-38, verbatim.
+const FACTOR00 = 0x10000000000000000n;
+const FACTOR01 = 0xff9dd7de423466c2n;
+const FACTOR02 = 0xff3bd55f4488ad27n;
+const FACTOR03 = 0xfe78410fd6498b74n;
+const FACTOR04 = 0xfcf2d9987c9be179n;
+const FACTOR05 = 0xf9ef02c4529258b0n;
+const FACTOR06 = 0xf402d288133a85a1n;
+const FACTOR07 = 0xe895615b5beb6386n;
+const FACTOR08 = 0xd34f17a00ffa00a8n;
+const FACTOR09 = 0xae6b7961714e2055n;
+const FACTOR10 = 0x76d6461f27082d75n;
+const FACTOR11 = 0x372a3bfe0745d8b7n;
+const FACTOR12 = 0x0be32cbee4897976n;
+const FACTOR13 = 0x008d4f70c9ff4925n;
+const FACTOR14 = 0x00004e009ae55194n;
+function mulShift64(n0, n1) {
+    return (n0 * n1) >> 64n;
+}
+/** `ratio_x48 = 1.0015^tick * 2^48`. */
+function getRatioAtTick(tick) {
+    if (!Number.isInteger(tick) || tick < FLUID_MIN_TICK || tick > FLUID_MAX_TICK) {
+        throw new Error(`getRatioAtTick: tick ${tick} out of bounds [${FLUID_MIN_TICK}, ${FLUID_MAX_TICK}]`);
+    }
+    const absTick = Math.abs(tick);
+    let factor = FACTOR00;
+    if (absTick & 0x1)
+        factor = FACTOR01;
+    if (absTick & 0x2)
+        factor = mulShift64(factor, FACTOR02);
+    if (absTick & 0x4)
+        factor = mulShift64(factor, FACTOR03);
+    if (absTick & 0x8)
+        factor = mulShift64(factor, FACTOR04);
+    if (absTick & 0x10)
+        factor = mulShift64(factor, FACTOR05);
+    if (absTick & 0x20)
+        factor = mulShift64(factor, FACTOR06);
+    if (absTick & 0x40)
+        factor = mulShift64(factor, FACTOR07);
+    if (absTick & 0x80)
+        factor = mulShift64(factor, FACTOR08);
+    if (absTick & 0x100)
+        factor = mulShift64(factor, FACTOR09);
+    if (absTick & 0x200)
+        factor = mulShift64(factor, FACTOR10);
+    if (absTick & 0x400)
+        factor = mulShift64(factor, FACTOR11);
+    if (absTick & 0x800)
+        factor = mulShift64(factor, FACTOR12);
+    if (absTick & 0x1000)
+        factor = mulShift64(factor, FACTOR13);
+    if (absTick & 0x2000)
+        factor = mulShift64(factor, FACTOR14);
+    let precision = 0n;
+    if (tick >= 0) {
+        if (factor === 0n)
+            throw new Error("getRatioAtTick: math overflow (factor == 0)");
+        factor = U128_MAX / factor;
+        if (factor % 0x10000n !== 0n)
+            precision = 1n;
+    }
+    return (factor >> 16n) + precision;
+}
+/**
+ * Raw (pre-interest) debt implied by `tick` + `collateralRaw`, per Fluid's
+ * `Position::get_position_info`: when `tick > COLD_TICK`,
+ * `debt_raw = ((collateral_raw + 1) * ratio_x48 >> 48) + 1`; `tick == COLD_TICK` ⇒ 0.
+ */
+function tickImpliedDebtRaw(tick, collateralRaw) {
+    if (tick <= FLUID_COLD_TICK)
+        return 0n;
+    const collateralForDebtCalc = collateralRaw + 1n;
+    const ratioX48 = getRatioAtTick(tick);
+    const scaled = ratioX48 * collateralForDebtCalc;
+    return (scaled >> 48n) + 1n;
+}
+function ceilDiv(numerator, denominator) {
+    if (denominator === 0n)
+        throw new Error("ceilDiv: division by zero");
+    const quotient = numerator / denominator;
+    const remainder = numerator % denominator;
+    return remainder === 0n ? quotient : quotient + 1n;
+}
+/** `raw * exPrice / 1e12`, FLOORED. */
+function normalAmountFloor(raw, exPrice) {
+    return (raw * exPrice) / EXCHANGE_PRICES_PRECISION;
+}
+/** As `normalAmountFloor`, but CEILED — used for debt. */
+function normalAmountCeil(raw, exPrice) {
+    return ceilDiv(raw * exPrice, EXCHANGE_PRICES_PRECISION);
+}
+/** Normalized-9-decimal amount -> native `decimals`, FLOORED. */
+function unscaleFloor(scaled, decimals) {
+    if (decimals > FLUID_MAX_TOKEN_DECIMALS)
+        throw new Error("unscaleFloor: unsupported token decimals");
+    const divisor = 10n ** BigInt(FLUID_MAX_TOKEN_DECIMALS - decimals);
+    return scaled / divisor;
+}
+/** As `unscaleFloor`, but CEILED — used for debt. */
+function unscaleCeil(scaled, decimals) {
+    if (decimals > FLUID_MAX_TOKEN_DECIMALS)
+        throw new Error("unscaleCeil: unsupported token decimals");
+    const divisor = 10n ** BigInt(FLUID_MAX_TOKEN_DECIMALS - decimals);
+    return ceilDiv(scaled, divisor);
+}
+/** The tick this position's tick-implied debt should be computed at (COLD_TICK when supply-only). */
+function effectiveTick(position) {
+    return position.isSupplyOnly ? FLUID_COLD_TICK : position.tick;
+}
+/**
+ * Decode + validate a Fluid `Position` account. `expected` pins it to the caller's canonical
+ * pubkey (e.g. one `HedgePositionSlot.borrowPosition`) — mirrors `decode_fluid_position`.
+ */
+function decodeFluidPosition(account, expected) {
+    if (!account.pubkey.equals(expected)) {
+        throw new Error("decodeFluidPosition: account pubkey does not match expected pin");
+    }
+    if (!account.owner.equals(constants_1.JUP_LEND_BORROW_PROGRAM_ID)) {
+        throw new Error("decodeFluidPosition: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < POSITION_MIN_LEN)
+        throw new Error("decodeFluidPosition: account data too short");
+    if (!data.subarray(0, 8).equals(POSITION_DISCRIMINATOR)) {
+        throw new Error("decodeFluidPosition: discriminator mismatch");
+    }
+    return {
+        vaultId: data.readUInt16LE(POSITION_OFFSET_VAULT_ID),
+        // Fluid's own `is_supply_only_position()` checks `== 1` exactly, not `!= 0`.
+        isSupplyOnly: data[POSITION_OFFSET_IS_SUPPLY_ONLY] === 1,
+        tick: data.readInt32LE(POSITION_OFFSET_TICK),
+        tickId: data.readUInt32LE(POSITION_OFFSET_TICK_ID),
+        collateralRaw: data.readBigUInt64LE(POSITION_OFFSET_COLLATERAL),
+        dustDebtRaw: data.readBigUInt64LE(POSITION_OFFSET_DUST_DEBT),
+    };
+}
+/**
+ * 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).
+ */
+function deriveFluidTickPda(vaultId, tick) {
+    if (!Number.isInteger(tick) || tick < FLUID_MIN_TICK || tick > FLUID_MAX_TICK) {
+        throw new Error(`deriveFluidTickPda: tick ${tick} out of bounds [${FLUID_MIN_TICK}, ${FLUID_MAX_TICK}]`);
+    }
+    if (!Number.isInteger(vaultId) || vaultId < 0 || vaultId > 0xffff) {
+        throw new Error(`deriveFluidTickPda: vaultId ${vaultId} out of u16 range`);
+    }
+    const vaultIdLe = Buffer.alloc(2);
+    vaultIdLe.writeUInt16LE(vaultId);
+    const normalizedLe = Buffer.alloc(4);
+    normalizedLe.writeInt32LE(tick - FLUID_MIN_TICK);
+    return web3_js_1.PublicKey.findProgramAddressSync([TICK_SEED, vaultIdLe, normalizedLe], constants_1.JUP_LEND_BORROW_PROGRAM_ID)[0];
+}
+/**
+ * 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).
+ */
+function settleTickPdaForPosition(position) {
+    return position.isSupplyOnly
+        ? deriveFluidTickPda(position.vaultId, FLUID_MIN_TICK)
+        : deriveFluidTickPda(position.vaultId, position.tick);
+}
+/**
+ * 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).
+ */
+function decodeFluidTick(account, expected) {
+    if (!account.pubkey.equals(expected)) {
+        throw new Error("decodeFluidTick: account pubkey does not match expected pin");
+    }
+    if (!account.owner.equals(constants_1.JUP_LEND_BORROW_PROGRAM_ID)) {
+        throw new Error("decodeFluidTick: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < TICK_MIN_LEN)
+        throw new Error("decodeFluidTick: account data too short");
+    if (!data.subarray(0, 8).equals(TICK_DISCRIMINATOR)) {
+        throw new Error("decodeFluidTick: discriminator mismatch");
+    }
+    const liqByte = data[TICK_OFFSET_IS_LIQUIDATED];
+    if (liqByte > 1)
+        throw new Error("decodeFluidTick: non-canonical is_liquidated byte");
+    return {
+        vaultId: data.readUInt16LE(TICK_OFFSET_VAULT_ID),
+        tick: data.readInt32LE(TICK_OFFSET_TICK),
+        isLiquidated: liqByte === 1,
+        totalIds: data.readUInt32LE(TICK_OFFSET_TOTAL_IDS),
+    };
+}
+/**
+ * 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).
+ */
+function requireFluidPositionLiquidationCurrent(position, tickAccount) {
+    if (position.isSupplyOnly) {
+        const placeholder = deriveFluidTickPda(position.vaultId, FLUID_MIN_TICK);
+        if (tickAccount && !tickAccount.pubkey.equals(placeholder)) {
+            throw new Error("requireFluidPositionLiquidationCurrent: wrong cold placeholder Tick key");
+        }
+        return;
+    }
+    if (!tickAccount) {
+        throw new Error("requireFluidPositionLiquidationCurrent: active position requires its Tick account");
+    }
+    const expected = deriveFluidTickPda(position.vaultId, position.tick);
+    const tick = decodeFluidTick(tickAccount, expected);
+    if (tick.vaultId !== position.vaultId || tick.tick !== position.tick) {
+        throw new Error("requireFluidPositionLiquidationCurrent: Tick vault_id/tick mismatch vs position");
+    }
+    if (tick.isLiquidated) {
+        throw new Error("requireFluidPositionLiquidationCurrent: tick is liquidated -- position is liquidation-stale");
+    }
+    if (tick.totalIds !== position.tickId) {
+        throw new Error(`requireFluidPositionLiquidationCurrent: tick generation ${tick.totalIds} != position tick_id ${position.tickId} -- position is liquidation-stale`);
+    }
+}
+/**
+ * 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`.
+ */
+function decodeFluidVaultState(account, expected) {
+    if (!account.pubkey.equals(expected)) {
+        throw new Error("decodeFluidVaultState: account pubkey does not match expected pin");
+    }
+    if (!account.owner.equals(constants_1.JUP_LEND_BORROW_PROGRAM_ID)) {
+        throw new Error("decodeFluidVaultState: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < VAULT_STATE_MIN_LEN)
+        throw new Error("decodeFluidVaultState: account data too short");
+    if (!data.subarray(0, 8).equals(VAULT_STATE_DISCRIMINATOR)) {
+        throw new Error("decodeFluidVaultState: discriminator mismatch");
+    }
+    const vaultId = data.readUInt16LE(VAULT_STATE_OFFSET_VAULT_ID);
+    const supplyExPrice = data.readBigUInt64LE(VAULT_STATE_OFFSET_SUPPLY_EX_PRICE);
+    const borrowExPrice = data.readBigUInt64LE(VAULT_STATE_OFFSET_BORROW_EX_PRICE);
+    const lastUpdateTimestamp = data.readBigUInt64LE(VAULT_STATE_OFFSET_LAST_UPDATE_TIMESTAMP);
+    if (supplyExPrice < VAULT_STATE_MIN_EX_PRICE || borrowExPrice < VAULT_STATE_MIN_EX_PRICE) {
+        throw new Error("decodeFluidVaultState: exchange price below the 1e12 sanity floor");
+    }
+    return { vaultId, supplyExPrice, borrowExPrice, lastUpdateTimestamp };
+}
+/**
+ * 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).
+ */
+function requireFluidVaultStateFresh(vaultState, nowUnixSec) {
+    const age = nowUnixSec - vaultState.lastUpdateTimestamp;
+    if (age < 0n)
+        throw new Error("requireFluidVaultStateFresh: negative age (clock skew?)");
+    if (age > FLUID_VAULT_STATE_MAX_STALENESS_SECS) {
+        throw new Error(`requireFluidVaultStateFresh: stale (${age}s > ${FLUID_VAULT_STATE_MAX_STALENESS_SECS}s)`);
+    }
+}
+/**
+ * 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`.
+ */
+function decodeFluidVaultConfig(account, expected) {
+    if (!account.pubkey.equals(expected)) {
+        throw new Error("decodeFluidVaultConfig: account pubkey does not match expected pin");
+    }
+    if (!account.owner.equals(constants_1.JUP_LEND_BORROW_PROGRAM_ID)) {
+        throw new Error("decodeFluidVaultConfig: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < VAULT_CONFIG_MIN_LEN)
+        throw new Error("decodeFluidVaultConfig: account data too short");
+    if (!data.subarray(0, 8).equals(VAULT_CONFIG_DISCRIMINATOR)) {
+        throw new Error("decodeFluidVaultConfig: discriminator mismatch");
+    }
+    const vaultId = data.readUInt16LE(VAULT_CONFIG_OFFSET_VAULT_ID);
+    const oracle = new web3_js_1.PublicKey(data.subarray(VAULT_CONFIG_OFFSET_ORACLE, VAULT_CONFIG_OFFSET_ORACLE + 32));
+    return { vaultId, oracle };
+}
+/**
+ * Bind a Fluid position's, vault state's, and vault config's `vaultId` together in one call —
+ * mirrors `require_fluid_vault_id_bind`.
+ */
+function requireFluidVaultIdBind(positionVaultId, vaultStateVaultId, vaultConfigVaultId) {
+    if (positionVaultId !== vaultStateVaultId || vaultStateVaultId !== vaultConfigVaultId) {
+        throw new Error(`requireFluidVaultIdBind: vault_id mismatch (position=${positionVaultId}, vaultState=${vaultStateVaultId}, vaultConfig=${vaultConfigVaultId})`);
+    }
+}
+// ============================================================================
+// Public valuation API — collateral / debt / LTV
+// ============================================================================
+/** `position.vaultId == vaultState.vaultId` — the 2-way bind `collateralJlpNormal`/`debtNativeCeil` require. */
+function requireVaultIdMatch(positionVaultId, vaultStateVaultId) {
+    if (positionVaultId !== vaultStateVaultId) {
+        throw new Error(`requireVaultIdMatch: vault_id mismatch (position=${positionVaultId}, vaultState=${vaultStateVaultId})`);
+    }
+}
+/**
+ * Collateral (always JLP, 6 decimals) held by `position`, interest-adjusted and FLOORED —
+ * mirrors `collateral_jlp_normal` exactly.
+ */
+function collateralJlpNormal(position, vaultState) {
+    requireVaultIdMatch(position.vaultId, vaultState.vaultId);
+    const scaled = normalAmountFloor(position.collateralRaw, vaultState.supplyExPrice);
+    return unscaleFloor(scaled, TOKEN_DECIMALS_JLP);
+}
+/**
+ * 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.
+ */
+function debtNativeCeil(position, vaultState, mintDecimals) {
+    requireVaultIdMatch(position.vaultId, vaultState.vaultId);
+    const tick = effectiveTick(position);
+    const tickDebtRaw = tickImpliedDebtRaw(tick, position.collateralRaw);
+    // Fluid semantics: dust ≥ registered debt ⇒ fully liquidated/absorbed — nothing owed.
+    const totalRaw = tickDebtRaw > position.dustDebtRaw ? tickDebtRaw - position.dustDebtRaw : 0n;
+    const scaled = normalAmountCeil(totalRaw, vaultState.borrowExPrice);
+    return unscaleCeil(scaled, mintDecimals);
+}
+/**
+ * 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.
+ */
+function debtNativeCeilProgramView(position, vaultState, mintDecimals) {
+    requireVaultIdMatch(position.vaultId, vaultState.vaultId);
+    const tick = effectiveTick(position);
+    const tickDebtRaw = tickImpliedDebtRaw(tick, position.collateralRaw);
+    const totalRaw = tickDebtRaw + position.dustDebtRaw;
+    const scaled = normalAmountCeil(totalRaw, vaultState.borrowExPrice);
+    return unscaleCeil(scaled, mintDecimals);
+}
+/**
+ * Value `collateralJlpNative` (JLP, 6-dec) in the debt mint's NATIVE units, using Fluid's own
+ * pair-native oracle price (`price1e15`) — mirrors `collateral_value_in_debt_native` exactly.
+ */
+function collateralValueInDebtNative(collateralJlpNative, debtDecimals, price1e15) {
+    const naive6dec = (collateralJlpNative * price1e15) / JLP_PRICE_1E15_PRECISION; // floor, stage 1
+    if (debtDecimals >= TOKEN_DECIMALS_JLP) {
+        const scale = 10n ** BigInt(debtDecimals - TOKEN_DECIMALS_JLP);
+        return naive6dec * scale;
+    }
+    const scale = 10n ** BigInt(TOKEN_DECIMALS_JLP - debtDecimals);
+    return naive6dec / scale; // floor, stage 2
+}
+/**
+ * `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.
+ */
+function positionLtvBps(debtNative, debtDecimals, collateralJlpNative, price1e15) {
+    if (debtNative === 0n)
+        return 0;
+    const colInDebtNative = collateralValueInDebtNative(collateralJlpNative, debtDecimals, price1e15);
+    if (colInDebtNative === 0n)
+        return 0xffff;
+    const numerator = debtNative * 10000n;
+    const ltv = ceilDiv(numerator, colInDebtNative);
+    return ltv > 0xffffn ? 0xffff : Number(ltv);
+}
+/**
+ * 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).
+ */
+function readOracleHopCount(account, expected) {
+    if (!account.pubkey.equals(expected)) {
+        throw new Error("readOracleHopCount: account pubkey does not match expected pin");
+    }
+    if (!account.owner.equals(constants_1.FLUID_ORACLE_PROGRAM_ID)) {
+        throw new Error("readOracleHopCount: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < ORACLE_CFG_OFFSET_SOURCES_LEN + 4) {
+        throw new Error("readOracleHopCount: account data too short");
+    }
+    if (!data.subarray(0, 8).equals(ORACLE_CONFIG_DISCRIMINATOR)) {
+        throw new Error("readOracleHopCount: discriminator mismatch");
+    }
+    const rawLen = data.readUInt32LE(ORACLE_CFG_OFFSET_SOURCES_LEN);
+    if (rawLen !== 1 && rawLen !== 2) {
+        throw new Error(`readOracleHopCount: unsupported hop count ${rawLen} (only 1 or 2 supported)`);
+    }
+    return rawLen;
+}
+function readOracleSourceMeta(data, index) {
+    const base = ORACLE_CFG_OFFSET_SOURCES + index * ORACLE_SOURCE_STRIDE;
+    if (data.length < base + ORACLE_SOURCE_STRIDE) {
+        throw new Error("readOracleSourceMeta: account data too short");
+    }
+    return {
+        sourcePk: new web3_js_1.PublicKey(data.subarray(base + ORACLE_SOURCE_OFF_PUBKEY, base + ORACLE_SOURCE_OFF_PUBKEY + 32)),
+        invert: data[base + ORACLE_SOURCE_OFF_INVERT] !== 0,
+        sourceType: data[base + ORACLE_SOURCE_OFF_TYPE],
+    };
+}
+/** Read a signed 128-bit little-endian integer (two's complement) out of `data` at `offset`. */
+function readI128LE(data, offset) {
+    let val = 0n;
+    for (let i = 0; i < 16; i++) {
+        val |= BigInt(data[offset + i]) << BigInt(8 * i);
+    }
+    if (val >= 1n << 127n)
+        val -= 1n << 128n;
+    return val;
+}
+/** Decode one Chainlink `Transmissions`/`Transmission` hop into `answer * 10^(15-decimals)`. */
+function decodeChainlinkHop(account, currentSlot) {
+    if (!account.owner.equals(constants_1.CHAINLINK_STORE_PROGRAM_ID)) {
+        throw new Error("decodeChainlinkHop: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < CHAINLINK_MIN_LEN)
+        throw new Error("decodeChainlinkHop: account data too short");
+    if (!data.subarray(0, 8).equals(CHAINLINK_TRANSMISSIONS_DISCRIMINATOR)) {
+        throw new Error("decodeChainlinkHop: discriminator mismatch");
+    }
+    const decimals = data[CHAINLINK_OFFSET_DECIMALS];
+    const latestRoundId = data.readUInt32LE(CHAINLINK_OFFSET_LATEST_ROUND_ID);
+    const liveLength = data.readUInt32LE(CHAINLINK_OFFSET_LIVE_LENGTH);
+    const feedSlot = data.readBigUInt64LE(CHAINLINK_OFFSET_SLOT);
+    const answer = readI128LE(data, CHAINLINK_OFFSET_ANSWER);
+    if (liveLength !== 1)
+        throw new Error("decodeChainlinkHop: unexpected live_length");
+    if (latestRoundId === 0)
+        throw new Error("decodeChainlinkHop: latest_round_id is zero");
+    if (answer <= 0n)
+        throw new Error("decodeChainlinkHop: answer is non-positive");
+    if (decimals > ORACLE_RATE_OUTPUT_DECIMALS)
+        throw new Error("decodeChainlinkHop: decimals out of range");
+    if (currentSlot < feedSlot)
+        throw new Error("decodeChainlinkHop: feed slot is in the future");
+    const slotsElapsed = currentSlot - feedSlot;
+    const elapsedS = (slotsElapsed * AVG_SLOT_TIME_MS) / 1000n;
+    if (elapsedS > CHAINLINK_MAX_STALENESS_SECS)
+        throw new Error("decodeChainlinkHop: feed stale");
+    const scale = 10n ** BigInt(ORACLE_RATE_OUTPUT_DECIMALS - decimals);
+    return answer * scale;
+}
+/** Decode one Pyth `PriceUpdateV2` hop into `price * 10^(15-|exponent|)`. */
+function decodePythHop(account, nowUnixSec) {
+    if (!account.owner.equals(constants_1.PYTH_RECEIVER_PROGRAM_ID)) {
+        throw new Error("decodePythHop: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < PYTH_MIN_LEN)
+        throw new Error("decodePythHop: account data too short");
+    if (!data.subarray(0, 8).equals(PYTH_PRICE_UPDATE_DISCRIMINATOR)) {
+        throw new Error("decodePythHop: discriminator mismatch");
+    }
+    const verificationLevel = data[PYTH_OFFSET_VERIFICATION_LEVEL];
+    const price = data.readBigInt64LE(PYTH_OFFSET_PRICE);
+    const conf = data.readBigUInt64LE(PYTH_OFFSET_CONF);
+    const exponent = data.readInt32LE(PYTH_OFFSET_EXPONENT);
+    const publishTime = data.readBigInt64LE(PYTH_OFFSET_PUBLISH_TIME);
+    if (verificationLevel !== PYTH_VERIFICATION_LEVEL_FULL) {
+        throw new Error("decodePythHop: verification level is not Full");
+    }
+    if (price <= 0n)
+        throw new Error("decodePythHop: price is non-positive");
+    if (exponent > 0 || exponent < -PYTH_MAX_ABS_EXPONENT) {
+        throw new Error("decodePythHop: exponent out of range");
+    }
+    if (conf * PYTH_CONFIDENCE_SCALE_FACTOR_LIQUIDATE > price) {
+        throw new Error("decodePythHop: confidence interval too wide");
+    }
+    if (nowUnixSec < publishTime)
+        throw new Error("decodePythHop: publish_time is in the future");
+    const elapsedS = nowUnixSec - publishTime;
+    if (elapsedS > PYTH_MAX_STALENESS_SECS)
+        throw new Error("decodePythHop: price stale");
+    const absExponent = -exponent;
+    const scale = 10n ** BigInt(ORACLE_RATE_OUTPUT_DECIMALS - absExponent);
+    return price * scale;
+}
+/**
+ * Decode hop `meta.sourcePk`'s feed (dispatching on `meta.sourceType`), apply this hop's own
+ * `invert`, and fold it into the running chained rate — mirrors `apply_hop` /
+ * `get_exchange_rate_for_hop` exactly: `rate = hop_value; if invert { rate = 1e30 / rate };
+ * running = running * rate / 1e15`.
+ */
+function applyHop(meta, feedAccount, nowUnixSec, currentSlot, runningRate) {
+    let r;
+    if (meta.sourceType === ORACLE_SOURCE_TYPE_PYTH) {
+        r = decodePythHop(feedAccount, nowUnixSec);
+    }
+    else if (meta.sourceType === ORACLE_SOURCE_TYPE_CHAINLINK) {
+        r = decodeChainlinkHop(feedAccount, currentSlot);
+    }
+    else {
+        throw new Error(`applyHop: unsupported oracle source type ${meta.sourceType}`);
+    }
+    if (r > 0n && meta.invert) {
+        r = ORACLE_INVERT_NUMERATOR / r;
+    }
+    const combined = (runningRate * r) / ORACLE_RATE_SCALE;
+    if (combined === 0n)
+        throw new Error("applyHop: combined rate is zero");
+    return combined;
+}
+/**
+ * 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.
+ */
+function readFluidPrice1e15FromAccounts(args) {
+    const { vaultConfig, expectedVaultConfig, positionVaultId, vaultStateVaultId, oracleCfg, expectedOracle, feedAccounts, nowUnixSec, currentSlot } = args;
+    const vaultConfigInfo = decodeFluidVaultConfig(vaultConfig, expectedVaultConfig);
+    requireFluidVaultIdBind(positionVaultId, vaultStateVaultId, vaultConfigInfo.vaultId);
+    if (!vaultConfigInfo.oracle.equals(expectedOracle)) {
+        throw new Error("readFluidPrice1e15FromAccounts: VaultConfig.oracle does not match the pinned oracle");
+    }
+    if (!oracleCfg.pubkey.equals(expectedOracle)) {
+        throw new Error("readFluidPrice1e15FromAccounts: oracle config pubkey does not match expected pin");
+    }
+    if (!oracleCfg.owner.equals(constants_1.FLUID_ORACLE_PROGRAM_ID)) {
+        throw new Error("readFluidPrice1e15FromAccounts: unexpected oracle config owner");
+    }
+    const oracleData = oracleCfg.data;
+    if (oracleData.length < ORACLE_CFG_OFFSET_SOURCES_LEN + 4) {
+        throw new Error("readFluidPrice1e15FromAccounts: oracle config data too short");
+    }
+    if (!oracleData.subarray(0, 8).equals(ORACLE_CONFIG_DISCRIMINATOR)) {
+        throw new Error("readFluidPrice1e15FromAccounts: oracle config discriminator mismatch");
+    }
+    const sourcesLen = oracleData.readUInt32LE(ORACLE_CFG_OFFSET_SOURCES_LEN);
+    if (sourcesLen !== 1 && sourcesLen !== 2) {
+        throw new Error(`readFluidPrice1e15FromAccounts: unsupported hop count ${sourcesLen}`);
+    }
+    if (feedAccounts.length !== sourcesLen) {
+        throw new Error(`readFluidPrice1e15FromAccounts: feed account count mismatch (got ${feedAccounts.length}, expected ${sourcesLen})`);
+    }
+    let rate = ORACLE_RATE_SCALE;
+    for (let i = 0; i < sourcesLen; i++) {
+        const meta = readOracleSourceMeta(oracleData, i);
+        if (!feedAccounts[i].pubkey.equals(meta.sourcePk)) {
+            throw new Error(`readFluidPrice1e15FromAccounts: feed account ${i} does not match the oracle config's declared source`);
+        }
+        rate = applyHop(meta, feedAccounts[i], nowUnixSec, currentSlot, rate);
+    }
+    if (sourcesLen === 1 && (rate < MIN_JLP_PRICE_1E15 || rate > MAX_JLP_PRICE_1E15)) {
+        throw new Error("readFluidPrice1e15FromAccounts: single-hop price outside [$0.50, $50] clamp");
+    }
+    return rate;
+}
+/**
+ * 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).
+ */
+async function fetchFluidSlotLtv(connection, slot, debtDecimals) {
+    const [positionInfo, vaultStateInfo, vaultConfigInfo] = await connection.getMultipleAccountsInfo([
+        slot.borrowPosition,
+        slot.vaultState,
+        slot.vaultConfig,
+    ]);
+    if (!positionInfo)
+        throw new Error("fetchFluidSlotLtv: Fluid position account not found");
+    if (!vaultStateInfo)
+        throw new Error("fetchFluidSlotLtv: Fluid vault_state account not found");
+    if (!vaultConfigInfo)
+        throw new Error("fetchFluidSlotLtv: Fluid vault_config account not found");
+    const position = decodeFluidPosition({ pubkey: slot.borrowPosition, owner: positionInfo.owner, data: positionInfo.data }, slot.borrowPosition);
+    const vaultState = decodeFluidVaultState({ pubkey: slot.vaultState, owner: vaultStateInfo.owner, data: vaultStateInfo.data }, slot.vaultState);
+    const oracleHopCountInfo = await connection.getAccountInfo(slot.fluidOracle);
+    if (!oracleHopCountInfo)
+        throw new Error("fetchFluidSlotLtv: Fluid oracle config account not found");
+    const oracleCfg = {
+        pubkey: slot.fluidOracle,
+        owner: oracleHopCountInfo.owner,
+        data: oracleHopCountInfo.data,
+    };
+    const hopCount = readOracleHopCount(oracleCfg, slot.fluidOracle);
+    const oracleData = oracleCfg.data;
+    const feedPubkeys = [];
+    for (let i = 0; i < hopCount; i++) {
+        feedPubkeys.push(readOracleSourceMeta(oracleData, i).sourcePk);
+    }
+    const [slotNumber, feedInfos] = await Promise.all([
+        connection.getSlot(),
+        connection.getMultipleAccountsInfo(feedPubkeys),
+    ]);
+    const blockTime = await connection.getBlockTime(slotNumber);
+    if (blockTime == null)
+        throw new Error("fetchFluidSlotLtv: could not resolve current block time");
+    const feedAccounts = feedPubkeys.map((pk, i) => {
+        const info = feedInfos[i];
+        if (!info)
+            throw new Error(`fetchFluidSlotLtv: oracle feed account ${pk.toBase58()} not found`);
+        return { pubkey: pk, owner: info.owner, data: info.data };
+    });
+    const price1e15 = readFluidPrice1e15FromAccounts({
+        vaultConfig: {
+            pubkey: slot.vaultConfig,
+            owner: vaultConfigInfo.owner,
+            data: vaultConfigInfo.data,
+        },
+        expectedVaultConfig: slot.vaultConfig,
+        positionVaultId: position.vaultId,
+        vaultStateVaultId: vaultState.vaultId,
+        oracleCfg,
+        expectedOracle: slot.fluidOracle,
+        feedAccounts,
+        nowUnixSec: BigInt(blockTime),
+        currentSlot: BigInt(slotNumber),
+    });
+    // PROGRAM view (dust ADDED) deliberately: this LTV feeds operation sizing, and the deployed
+    // program enforces its own guards against the +dust reading until the sign fix ships — sizing
+    // from the true (lower) debt could build an op the program rejects.
+    const debtNative = debtNativeCeilProgramView(position, vaultState, debtDecimals);
+    const collateralJlpNative = collateralJlpNormal(position, vaultState);
+    const ltvBps = positionLtvBps(debtNative, debtDecimals, collateralJlpNative, price1e15);
+    return { ltvBps, debtNative, collateralJlpNative, price1e15, position, vaultState };
+}
+// ============================================================================
+// Jup-Lend Earn — live fToken exchange rate
+// ============================================================================
+/**
+ * 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).
+ */
+function earnExchangeRate(account) {
+    if (!account.owner.equals(constants_1.JUP_LEND_EARN_PROGRAM_ID)) {
+        throw new Error("earnExchangeRate: unexpected owner");
+    }
+    const data = account.data;
+    if (data.length < LENDING_MIN_LEN)
+        throw new Error("earnExchangeRate: account data too short");
+    if (!data.subarray(0, 8).equals(LENDING_DISCRIMINATOR)) {
+        throw new Error("earnExchangeRate: discriminator mismatch");
+    }
+    const rate = data.readBigUInt64LE(LENDING_OFFSET_EXCHANGE_RATE);
+    if (rate < exports.JUP_LEND_EARN_MIN_SANE_RATE || rate > exports.JUP_LEND_EARN_MAX_SANE_RATE) {
+        throw new Error("earnExchangeRate: rate outside sane bounds");
+    }
+    return rate;
+}