@elmntl/jlpd-sdk 0.2.0 → 0.13.4

package/dist/p-stv-core/remaining-accounts.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * Remaining accounts builders for p-STV Core instructions.
+ *
+ * These functions build the complete `remainingAccounts` arrays needed for
+ * deposit, claim_withdraw, and process_epoch instructions, pulling all the
+ * lend + protocol AUM + strategy pair + auto-route/unroute account building
+ * logic out of the frontend and into the SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDepositContext = buildDepositContext;
+exports.buildClaimWithdrawContext = buildClaimWithdrawContext;
+exports.buildDepositToStrategyContext = buildDepositToStrategyContext;
+exports.buildProcessEpochContext = buildProcessEpochContext;
+const web3_js_1 = require("@solana/web3.js");
+const pda_1 = require("../elemental-lend/pda");
+const accounts_1 = require("../elemental-lend/accounts");
+const jupiter_lend_1 = require("../elemental-lend/jupiter-lend");
+const kamino_vault_1 = require("../elemental-lend/kamino-vault");
+const ata_1 = require("../common/ata");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_PUBKEY = web3_js_1.PublicKey.default;
+const SPL_TOKEN_PROGRAM = new web3_js_1.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+/** Resolve the effective token program from a VaultInfo. Falls back to SPL Token. */
+function resolveTokenProgram(vault) {
+    return vault.tokenProgram ?? SPL_TOKEN_PROGRAM;
+}
+const STRATEGY_STATE_SEED = Buffer.from("strategy_state");
+const POSITION_SEED = Buffer.from("position");
+function isDefault(pubkey) {
+    return pubkey.equals(DEFAULT_PUBKEY);
+}
+/**
+ * Build the 4 fixed lend accounts for value-movement paths (deposit, claim_withdraw,
+ * deposit_to_strategy, withdraw_from_strategy):
+ *   [lendProgram(ro), lendStrategyState(w), lendPosition(w), lendBaseAta(w)]
+ *
+ * All three data accounts are writable on these paths because sweep/unsweep CPIs
+ * (lend.rs:341-344) write all three.
+ *
+ * `tokenProgram` MUST match the base-mint's token program. The on-chain
+ * check_lend_base_ata (lend.rs:61) derives the expected ATA using
+ * [strategy_state, token_program, base_mint] and rejects a mismatch.
+ */
+function buildFixedLendAccounts(lendProgram, baseMint, stvAddress, tokenProgram) {
+    const [lendStrategyState] = (0, pda_1.findStrategyStatePda)(baseMint, lendProgram);
+    const [lendPosition] = (0, pda_1.findStvPositionPda)(stvAddress, lendProgram);
+    const lendBaseAta = (0, ata_1.findAta)(baseMint, lendStrategyState, tokenProgram);
+    return {
+        lendStrategyState,
+        accounts: [
+            { pubkey: lendProgram, isSigner: false, isWritable: false },
+            { pubkey: lendStrategyState, isSigner: false, isWritable: true },
+            { pubkey: lendPosition, isSigner: false, isWritable: true },
+            { pubkey: lendBaseAta, isSigner: false, isWritable: true },
+        ],
+    };
+}
+/**
+ * Build the 4 fixed lend accounts for the process_epoch (NAV-refresh) path:
+ *   [lendProgram(ro), lendStrategyState(w), lendPosition(ro), lendBaseAta(ro)]
+ *
+ * `update_lend_aum` (lend.rs:264-311) only writes `lend_strategy_state`; it passes
+ * `lend_base_ata` and protocol accounts as readonly, and never touches `lend_stv_position`
+ * in the CPI at all. Marking `lend_stv_position` and `lend_base_ata` writable here would
+ * consume extra write-lock slots and can cause AccountNotWritable failures on read-only
+ * accounts. Do NOT use for deposit/claim/sweep paths — use `buildFixedLendAccounts`.
+ */
+function buildFixedLendAccountsForEpoch(lendProgram, baseMint, stvAddress, tokenProgram) {
+    const [lendStrategyState] = (0, pda_1.findStrategyStatePda)(baseMint, lendProgram);
+    const [lendPosition] = (0, pda_1.findStvPositionPda)(stvAddress, lendProgram);
+    const lendBaseAta = (0, ata_1.findAta)(baseMint, lendStrategyState, tokenProgram);
+    return {
+        lendStrategyState,
+        accounts: [
+            { pubkey: lendProgram, isSigner: false, isWritable: false },
+            { pubkey: lendStrategyState, isSigner: false, isWritable: true },
+            { pubkey: lendPosition, isSigner: false, isWritable: false },
+            { pubkey: lendBaseAta, isSigner: false, isWritable: false },
+        ],
+    };
+}
+/**
+ * Build strategy pair accounts for deposit/claim paths: [strategy_state(w), stv_position(w)].
+ *
+ * Both writable: deposit and claim_withdraw CPIs mutate strategy_state (update_aum)
+ * and stv_position (deposit/withdraw shares). Do NOT use for process_epoch's lockPps
+ * call — that path only reads positions, never mutates them.
+ */
+function buildStrategyPairAccounts(vault) {
+    if (isDefault(vault.strategy))
+        return [];
+    const [stratState] = web3_js_1.PublicKey.findProgramAddressSync([STRATEGY_STATE_SEED, vault.baseMint.toBuffer()], vault.strategy);
+    const [stratPos] = web3_js_1.PublicKey.findProgramAddressSync([POSITION_SEED, vault.address.toBuffer()], vault.strategy);
+    return [
+        { pubkey: stratState, isSigner: false, isWritable: true },
+        { pubkey: stratPos, isSigner: false, isWritable: true },
+    ];
+}
+/**
+ * Build strategy pair accounts for process_epoch lockPps (NAV-only read):
+ * [strategy_state(w), stv_position(ro)].
+ *
+ * process_epoch calls `update_strategy_and_read_position` (strategy.rs:190) which
+ * issues a CPI `update_aum` with `strategy_state_info` as WRITABLE
+ * (`InstructionAccount::writable`, strategy.rs:230). The CPI passes only
+ * [strategy_state, stv_account] — `stv_position` is read locally after the CPI but
+ * is NOT passed to the CPI, so it can stay readonly.
+ *
+ * Marking `strategy_state` writable is required: a CPI cannot upgrade a readonly
+ * account to writable, so a readonly `strategy_state` here will cause the transaction
+ * to fail with AccountNotWritable.
+ *
+ * Do NOT use for deposit, claim_withdraw, or deposit_to_strategy paths — use
+ * `buildStrategyPairAccounts` for those (both writable).
+ */
+function buildStrategyPairAccountsForEpoch(vault) {
+    if (isDefault(vault.strategy))
+        return [];
+    const [stratState] = web3_js_1.PublicKey.findProgramAddressSync([STRATEGY_STATE_SEED, vault.baseMint.toBuffer()], vault.strategy);
+    const [stratPos] = web3_js_1.PublicKey.findProgramAddressSync([POSITION_SEED, vault.address.toBuffer()], vault.strategy);
+    return [
+        { pubkey: stratState, isSigner: false, isWritable: true },
+        { pubkey: stratPos, isSigner: false, isWritable: false },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Context Builders
+// ---------------------------------------------------------------------------
+/**
+ * Build the complete remaining_accounts for a deposit instruction.
+ *
+ * Layout: [4 lend, N protocol_aum, M*2+P strategy_pairs, K auto_route]
+ *
+ * - If lend is active, derives lend PDAs and fetches protocol AUM accounts
+ * - Builds strategy pair accounts for each active strategy
+ * - If USDC + Jupiter Lend registered, appends auto-route accounts
+ * - Checks for stale kVaults (returned in preInstructions once invest ix is available)
+ */
+async function buildDepositContext(connection, vault, payer) {
+    const remainingAccounts = [];
+    const preInstructions = [];
+    let protocolAumCount = 0;
+    const tokenProgram = resolveTokenProgram(vault);
+    // 1. Lend accounts (if active)
+    if (!isDefault(vault.lendProgram)) {
+        const { accounts: lendAccounts, lendStrategyState } = buildFixedLendAccounts(vault.lendProgram, vault.baseMint, vault.address, tokenProgram);
+        remainingAccounts.push(...lendAccounts);
+        // Single fetch of LendStrategyState — used for both protocol AUM
+        // accounts and kVault staleness check.
+        const lendState = await (0, accounts_1.fetchLendStrategyState)(connection, vault.baseMint, vault.lendProgram).catch(() => null);
+        if (lendState) {
+            // Protocol AUM accounts — ALL registered protocols must be present.
+            // buildProtocolAccountsForAum derives canonical ATAs even for uninitialized
+            // positions; the on-chain handler values those as zero (update_aum.rs:291).
+            const protocolAccounts = await (0, accounts_1.buildProtocolAccountsForAum)(connection, lendState, lendStrategyState, tokenProgram);
+            protocolAumCount = protocolAccounts.length;
+            remainingAccounts.push(...protocolAccounts);
+            // Check kVault staleness — prepend invest ix if stale
+            try {
+                const protocolKeys = lendState.protocols
+                    .filter((p) => !isDefault(p));
+                // Need a payer for the invest ix — will be set by the caller
+                const investIxs = payer ? await (0, kamino_vault_1.buildKaminoInvestIxsIfStale)(connection, payer, vault.baseMint, protocolKeys) : [];
+                preInstructions.push(...investIxs);
+            }
+            catch {
+                // Skip if staleness check fails
+            }
+        }
+    }
+    // 2. Strategy pair accounts (2 per strategy: state + position)
+    const strategyAccounts = buildStrategyPairAccounts(vault);
+    remainingAccounts.push(...strategyAccounts);
+    // 3. Auto-route to Jupiter Lend (for any asset with a configured pool)
+    let autoRouteCount = 0;
+    const jupPool = jupiter_lend_1.JUP_LEND_POOLS[vault.baseMint.toBase58()];
+    if (!isDefault(vault.lendProgram) && jupPool) {
+        try {
+            const [lendSS] = (0, pda_1.findStrategyStatePda)(vault.baseMint, vault.lendProgram);
+            const strategyBaseAta = (0, ata_1.findAta)(vault.baseMint, lendSS, tokenProgram);
+            const strategyFtokenAta = (0, ata_1.findAta)(jupPool.fTokenMint, lendSS, tokenProgram);
+            const autoRouteAccounts = (0, jupiter_lend_1.buildJupLendAutoRouteAccounts)(jupPool, lendSS, strategyBaseAta, strategyFtokenAta);
+            autoRouteCount = autoRouteAccounts.length;
+            for (const acc of autoRouteAccounts) {
+                remainingAccounts.push({ ...acc, isSigner: false });
+            }
+        }
+        catch {
+            // Skip auto-route if account resolution fails
+        }
+    }
+    // 4. Strategy program (after auto-route, for CPI resolution)
+    // Must be in the transaction but NOT counted as auto-route or strategy pairs.
+    if (!isDefault(vault.strategy)) {
+        remainingAccounts.push({ pubkey: vault.strategy, isSigner: false, isWritable: false });
+    }
+    return { remainingAccounts, protocolAumCount, autoRouteCount, preInstructions };
+}
+/**
+ * Build the complete remaining_accounts for a claim_withdraw instruction.
+ *
+ * Layout: [4 lend, K auto_unroute]
+ *
+ * - If lend is active, derives lend PDAs
+ * - If USDC + Jupiter Lend, appends auto-unroute accounts
+ */
+async function buildClaimWithdrawContext(connection, vault) {
+    const remainingAccounts = [];
+    const preInstructions = [];
+    let autoUnrouteCount = 0;
+    let protocolAumCount = 0;
+    const tokenProgram = resolveTokenProgram(vault);
+    if (!isDefault(vault.lendProgram)) {
+        const { accounts: lendAccounts, lendStrategyState } = buildFixedLendAccounts(vault.lendProgram, vault.baseMint, vault.address, tokenProgram);
+        remainingAccounts.push(...lendAccounts);
+        // Protocol-AUM accounts (between fixed lend and auto-unroute) — feed the
+        // pre-unsweep update_aum refresh. The on-chain lend update_aum rejects an
+        // incomplete tail, so these MUST cover the strategy's full protocol set.
+        // Canonical ATAs are derived even for uninitialized positions (valued as zero).
+        const lendState = await (0, accounts_1.fetchLendStrategyState)(connection, vault.baseMint, vault.lendProgram).catch(() => null);
+        if (lendState) {
+            const protocolAccounts = await (0, accounts_1.buildProtocolAccountsForAum)(connection, lendState, lendStrategyState, tokenProgram);
+            protocolAumCount = protocolAccounts.length;
+            remainingAccounts.push(...protocolAccounts);
+        }
+        // Auto-unroute from Jupiter Lend (for any asset with a configured pool)
+        const jupPoolForUnroute = jupiter_lend_1.JUP_LEND_POOLS[vault.baseMint.toBase58()];
+        if (jupPoolForUnroute) {
+            try {
+                const lendBaseAta = (0, ata_1.findAta)(vault.baseMint, lendStrategyState, tokenProgram);
+                const strategyFtokenAta = (0, ata_1.findAta)(jupPoolForUnroute.fTokenMint, lendStrategyState, tokenProgram);
+                const autoUnrouteAccounts = (0, jupiter_lend_1.buildJupLendAutoUnrouteAccounts)(jupPoolForUnroute, lendStrategyState, strategyFtokenAta, lendBaseAta);
+                autoUnrouteCount = autoUnrouteAccounts.length;
+                remainingAccounts.push(...autoUnrouteAccounts.map(a => ({ ...a, isSigner: false })));
+            }
+            catch {
+                // Skip auto-unroute if resolution fails
+            }
+        }
+    }
+    return { remainingAccounts, autoUnrouteCount, protocolAumCount, preInstructions };
+}
+/**
+ * Build the complete remaining_accounts for a deposit_to_strategy instruction.
+ *
+ * Layout: [4 fixed lend, N protocol_aum, K auto_unroute]
+ *
+ * - Fixed lend accounts (if lend is active)
+ * - Protocol AUM accounts: required by the on-chain handler to refresh lend
+ *   valuation via update_lend_aum before the reserved_base liquidity lock check
+ * - Auto-unroute accounts: forwarded to the lend withdraw CPI for unsweep
+ *
+ * The `connection` parameter is required to fetch LendStrategyState and
+ * resolve protocol AUM accounts.
+ */
+async function buildDepositToStrategyContext(connection, vault) {
+    const remainingAccounts = [];
+    let protocolAumCount = 0;
+    let autoUnrouteCount = 0;
+    const tokenProgram = resolveTokenProgram(vault);
+    if (!isDefault(vault.lendProgram)) {
+        const { accounts: lendAccounts, lendStrategyState } = buildFixedLendAccounts(vault.lendProgram, vault.baseMint, vault.address, tokenProgram);
+        remainingAccounts.push(...lendAccounts);
+        // Fetch LendStrategyState once — used for protocol AUM resolution.
+        // ALL registered protocols must be present; derive canonical ATAs even for
+        // uninitialized positions (the on-chain handler values them as zero).
+        const lendState = await (0, accounts_1.fetchLendStrategyState)(connection, vault.baseMint, vault.lendProgram).catch(() => null);
+        if (lendState) {
+            const protocolAccounts = await (0, accounts_1.buildProtocolAccountsForAum)(connection, lendState, lendStrategyState, tokenProgram);
+            protocolAumCount = protocolAccounts.length;
+            remainingAccounts.push(...protocolAccounts);
+        }
+        // Auto-unroute from Jupiter Lend (for any asset with a configured pool)
+        const jupPoolForUnroute = jupiter_lend_1.JUP_LEND_POOLS[vault.baseMint.toBase58()];
+        if (jupPoolForUnroute) {
+            try {
+                const lendBaseAta = (0, ata_1.findAta)(vault.baseMint, lendStrategyState, tokenProgram);
+                const strategyFtokenAta = (0, ata_1.findAta)(jupPoolForUnroute.fTokenMint, lendStrategyState, tokenProgram);
+                const autoUnrouteAccounts = (0, jupiter_lend_1.buildJupLendAutoUnrouteAccounts)(jupPoolForUnroute, lendStrategyState, strategyFtokenAta, lendBaseAta);
+                autoUnrouteCount = autoUnrouteAccounts.length;
+                remainingAccounts.push(...autoUnrouteAccounts.map(a => ({ ...a, isSigner: false })));
+            }
+            catch {
+                // Skip auto-unroute if resolution fails
+            }
+        }
+    }
+    return { remainingAccounts, protocolAumCount, autoUnrouteCount, preInstructions: [] };
+}
+/**
+ * Build the complete remaining_accounts for a process_epoch instruction.
+ *
+ * @param phase - 'lockPps': needs lend + protocol AUM + strategy pairs for NAV.
+ *                'advance': empty remaining_accounts.
+ */
+async function buildProcessEpochContext(connection, vault, phase) {
+    if (phase === "advance") {
+        return { remainingAccounts: [], protocolAumCount: 0, preInstructions: [] };
+    }
+    // lockPps: lend + protocol AUM (for NAV update_aum refresh) + strategy pairs.
+    // No auto-route — process_epoch does not sweep to Jupiter Lend.
+    const tokenProgram = resolveTokenProgram(vault);
+    const remainingAccounts = [];
+    const preInstructions = [];
+    let protocolAumCount = 0;
+    if (!isDefault(vault.lendProgram)) {
+        // Use epoch-specific fixed lend accounts: lend_strategy_state writable,
+        // lend_stv_position and lend_base_ata readonly (update_lend_aum does not write them).
+        const { accounts: lendAccounts, lendStrategyState } = buildFixedLendAccountsForEpoch(vault.lendProgram, vault.baseMint, vault.address, tokenProgram);
+        remainingAccounts.push(...lendAccounts);
+        // ALL registered protocols must be present; derive canonical ATAs even for
+        // uninitialized positions (the on-chain handler values them as zero).
+        const lendState = await (0, accounts_1.fetchLendStrategyState)(connection, vault.baseMint, vault.lendProgram);
+        const protocolAccounts = await (0, accounts_1.buildProtocolAccountsForAum)(connection, lendState, lendStrategyState, tokenProgram);
+        protocolAumCount = protocolAccounts.length;
+        remainingAccounts.push(...protocolAccounts);
+    }
+    // Strategy pairs for process_epoch: strategy_state WRITABLE (update_aum CPI writes it),
+    // stv_position readonly (only read locally after CPI, not passed into the CPI itself).
+    const strategyAccounts = buildStrategyPairAccountsForEpoch(vault);
+    remainingAccounts.push(...strategyAccounts);
+    return { remainingAccounts, protocolAumCount, preInstructions };
+}

package/dist/p-stv-core/send-tx.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Smart transaction builder and sender.
+ *
+ * Features:
+ * - Simulates to get exact compute units, adds 5% buffer
+ * - Fetches priority fee from Helius (medium tier)
+ * - Pre-checks size to decide legacy vs versioned tx with LUT (no double-sign)
+ * - Uses lastValidBlockHeight for reliable confirmation
+ * - Parallel fetches where possible
+ */
+import { AddressLookupTableAccount, Connection, PublicKey, Transaction, TransactionInstruction, VersionedTransaction } from "@solana/web3.js";
+/**
+ * Default LUTs for Elemental Vaults.
+ * These are fetched in parallel and merged for every versioned transaction.
+ *
+ * After creating new LUTs with `scripts/create-luts.ts --create`,
+ * replace these placeholder addresses with the real ones.
+ */
+export declare const DEFAULT_LUT_ADDRESSES: {
+    /** Elemental Lend (Kamino + Jupiter Lend + protocol infra) */
+    lend: PublicKey;
+    /** p-STV Core (vaults, evMints, vault ATAs, config) */
+    stv: PublicKey;
+    /** JLPD Strategy (config, strategy states, positions, JLP, oracles) */
+    jlpd: PublicKey;
+};
+/**
+ * Wallet signing callback. Accepts either a legacy `Transaction` or a
+ * `VersionedTransaction` and returns the same type, fully signed.
+ *
+ * Generic over `T` so callers don't lose the input type when chaining.
+ */
+export type SignTransactionFn = <T extends Transaction | VersionedTransaction>(tx: T) => Promise<T>;
+/**
+ * Minimal structural type accepted by `sendSmartTx` / `simulateSmartTx`.
+ * Using a structural subset of `Connection` lets callers pass any web3.js
+ * version without nominal type mismatches.
+ */
+export type SmartTxConnection = Pick<Connection, "getLatestBlockhash" | "getAddressLookupTable" | "simulateTransaction" | "sendRawTransaction" | "confirmTransaction">;
+export interface SmartTxOptions {
+    /** Single LUT address (deprecated — use additionalLuts or DEFAULT_LUT_ADDRESSES) */
+    lutAddress?: PublicKey;
+    /** Additional pre-fetched ALTs to merge (e.g. Jupiter ALTs) */
+    additionalLuts?: AddressLookupTableAccount[];
+    /** Skip priority fee fetch (use 0) */
+    noPriorityFee?: boolean;
+    /** Custom compute unit limit (skips simulation) */
+    computeUnits?: number;
+    /** Force legacy transaction (no ALTs). Use when CPI programs appear as regular accounts. */
+    forceLegacy?: boolean;
+    /**
+     * RPC URL — required to enable the Helius `getPriorityFeeEstimate` shortcut.
+     * If omitted, the SDK falls back to a flat `FALLBACK_PRIORITY_FEE` and skips
+     * the Helius call entirely. Avoid reaching into `connection._rpcEndpoint`.
+     */
+    rpcUrl?: string;
+}
+/**
+ * Build, simulate, and send a transaction with optimal compute budget.
+ *
+ * 1. Fetches blockhash + LUT + priority fee in parallel
+ * 2. Pre-checks serialized size to choose legacy vs versioned
+ * 3. Simulates to get exact CU, adds 10% buffer
+ * 4. Prepends ComputeBudget instructions
+ * 5. Signs and sends with lastValidBlockHeight confirmation
+ */
+export declare function sendSmartTx(connection: SmartTxConnection, instructions: TransactionInstruction[], payer: PublicKey, signTransaction: SignTransactionFn, optionsOrLut?: PublicKey | SmartTxOptions): Promise<string>;
+/**
+ * Simulate a transaction without signing. Returns true if simulation succeeds.
+ * Use this to gate combined-tx attempts before asking the wallet to sign.
+ */
+export declare function simulateSmartTx(connection: SmartTxConnection, instructions: TransactionInstruction[], payer: PublicKey, optionsOrLut?: PublicKey | SmartTxOptions): Promise<boolean>;