@percolatorct/sdk 0.5.0 → 1.0.0-beta.1

package/dist/math/trading.d.ts

@@ -10,20 +10,68 @@
  */
 /**
  * Compute mark-to-market PnL for an open position.
+ *
+ * @param positionSize - Signed position size (positive = long, negative = short).
+ * @param entryPrice   - Entry price in e6 format (1 USD = 1_000_000).
+ * @param oraclePrice  - Current oracle price in e6 format.
+ * @returns PnL in native token units (positive = profit, negative = loss).
+ *
+ * @example
+ * ```ts
+ * // Long 10 SOL at $100, oracle now $110 → profit
+ * const pnl = computeMarkPnl(10_000_000n, 100_000_000n, 110_000_000n);
+ * ```
  */
 export declare function computeMarkPnl(positionSize: bigint, entryPrice: bigint, oraclePrice: bigint): bigint;
 /**
  * Compute liquidation price given entry, capital, position and maintenance margin.
  * Uses pure BigInt arithmetic for precision (no Number() truncation).
+ *
+ * @param entryPrice          - Entry price in e6 format.
+ * @param capital             - Account capital in native token units.
+ * @param positionSize        - Signed position size (positive = long, negative = short).
+ * @param maintenanceMarginBps - Maintenance margin requirement in basis points (e.g. 500n = 5%).
+ * @returns Liquidation price in e6 format. Returns 0n for longs that can't be liquidated,
+ *          or max u64 for shorts with ≥100% maintenance margin.
+ *
+ * @example
+ * ```ts
+ * // Long 1 SOL at $100, $10 capital, 5% maintenance margin
+ * const liqPrice = computeLiqPrice(100_000_000n, 10_000_000n, 1_000_000n, 500n);
+ * ```
  */
 export declare function computeLiqPrice(entryPrice: bigint, capital: bigint, positionSize: bigint, maintenanceMarginBps: bigint): bigint;
 /**
  * Compute estimated liquidation price BEFORE opening a trade.
  * Accounts for trading fees reducing effective capital.
+ *
+ * @param oracleE6   - Current oracle price in e6 format (used as entry estimate).
+ * @param margin     - Deposit margin in native token units.
+ * @param posSize    - Intended position size (absolute value used internally).
+ * @param maintBps   - Maintenance margin in basis points.
+ * @param feeBps     - Trading fee in basis points.
+ * @param direction  - Trade direction: `"long"` or `"short"`.
+ * @returns Estimated liquidation price in e6 format.
+ *
+ * @example
+ * ```ts
+ * const liq = computePreTradeLiqPrice(
+ *   100_000_000n, 10_000_000n, 1_000_000n, 500n, 30n, "long"
+ * );
+ * ```
  */
 export declare function computePreTradeLiqPrice(oracleE6: bigint, margin: bigint, posSize: bigint, maintBps: bigint, feeBps: bigint, direction: "long" | "short"): bigint;
 /**
  * Compute trading fee from notional value and fee rate in bps.
+ *
+ * @param notional      - Trade notional value in native token units.
+ * @param tradingFeeBps - Fee rate in basis points (e.g. 30n = 0.30%).
+ * @returns Fee amount in native token units.
+ *
+ * @example
+ * ```ts
+ * const fee = computeTradingFee(1_000_000_000n, 30n); // 0.30% of 1 SOL
+ * ```
  */
 export declare function computeTradingFee(notional: bigint, tradingFeeBps: bigint): bigint;
 /**
@@ -89,19 +137,86 @@ export declare function computeFeeSplit(totalFee: bigint, config: FeeSplitConfig
 export declare function computePnlPercent(pnlTokens: bigint, capital: bigint): number;
 /**
  * Estimate entry price including fee impact (slippage approximation).
+ *
+ * @param oracleE6      - Current oracle price in e6 format.
+ * @param tradingFeeBps - Trading fee in basis points.
+ * @param direction     - Trade direction: `"long"` or `"short"`.
+ * @returns Estimated entry price in e6 format (higher for longs, lower for shorts).
+ *
+ * @example
+ * ```ts
+ * const entry = computeEstimatedEntryPrice(100_000_000n, 30n, "long");
+ * // → 100_030_000n (oracle + 0.30% fee impact)
+ * ```
  */
 export declare function computeEstimatedEntryPrice(oracleE6: bigint, tradingFeeBps: bigint, direction: "long" | "short"): bigint;
 /**
  * Convert per-slot funding rate (bps) to annualized percentage.
+ *
+ * @param fundingRateBpsPerSlot - Funding rate per slot in basis points (i64 from engine state).
+ * @returns Annualized funding rate as a percentage (e.g. 12.5 = 12.5% APR).
+ * @throws Error if the value exceeds Number.MAX_SAFE_INTEGER.
+ *
+ * @example
+ * ```ts
+ * const apr = computeFundingRateAnnualized(1n); // ~78.84% APR
+ * ```
  */
 export declare function computeFundingRateAnnualized(fundingRateBpsPerSlot: bigint): number;
 /**
  * Compute margin required for a given notional and initial margin bps.
+ *
+ * @param notional         - Trade notional value in native token units.
+ * @param initialMarginBps - Initial margin requirement in basis points (e.g. 1000n = 10%).
+ * @returns Required margin in native token units.
+ *
+ * @example
+ * ```ts
+ * const margin = computeRequiredMargin(10_000_000_000n, 1000n); // 10% of notional
+ * // → 1_000_000_000n
+ * ```
  */
 export declare function computeRequiredMargin(notional: bigint, initialMarginBps: bigint): bigint;
 /**
  * Compute maximum leverage from initial margin bps.
  *
- * @throws Error if initialMarginBps is zero (infinite leverage is undefined)
+ * Formula: leverage = 10000 / initialMarginBps
+ * Uses scaled arithmetic to preserve precision for fractional leverage values.
+ *
+ * @param initialMarginBps - Initial margin requirement in basis points (e.g. 500n = 5% → 20x).
+ * @returns Maximum leverage as a number (e.g. 20 for 500 bps, 3.003 for 3333 bps).
+ * @throws Error if initialMarginBps is zero (infinite leverage is undefined).
+ *
+ * @example
+ * ```ts
+ * const maxLev = computeMaxLeverage(500n); // → 20
+ * const maxLev2 = computeMaxLeverage(1000n); // → 10
+ * const maxLev3 = computeMaxLeverage(3333n); // → 3.003 (not truncated to 3)
+ * ```
  */
 export declare function computeMaxLeverage(initialMarginBps: bigint): number;
+/**
+ * Compute the maximum amount that can be withdrawn from a position.
+ *
+ * The withdrawable amount is the capital plus any matured (unreserved) PnL.
+ * Reserved PnL is still locked and cannot be withdrawn until the warmup period elapses.
+ *
+ * Formula: max_withdrawable = capital + max(0, pnl - reserved_pnl)
+ *
+ * @param capital - Capital allocated to the position (in native token units)
+ * @param pnl - Mark-to-market PnL (in native token units, can be negative)
+ * @param reservedPnl - PnL that is still locked during warmup (always non-negative)
+ * @returns The maximum amount in native units that can be withdrawn without closing the position
+ *
+ * @example
+ * ```ts
+ * // Position: 10 SOL capital, +2 SOL mark PnL, 0.5 SOL reserved
+ * const max = computeMaxWithdrawable(
+ *   10_000_000_000n,  // 10 SOL in lamports
+ *   2_000_000_000n,   // +2 SOL in lamports
+ *   500_000_000n      // 0.5 SOL reserved in lamports
+ * );
+ * // Returns: 11_500_000_000n (10 + (2 - 0.5) = 11.5 SOL in lamports)
+ * ```
+ */
+export declare function computeMaxWithdrawable(capital: bigint, pnl: bigint, reservedPnl: bigint): bigint;

package/dist/math/warmup.d.ts

@@ -53,3 +53,53 @@ export declare function computeWarmupLeverageCap(initialMarginBps: bigint, total
  * @returns Maximum position size in native units.
  */
 export declare function computeWarmupMaxPositionSize(initialMarginBps: bigint, totalCapital: bigint, currentSlot: bigint, warmupStartSlot: bigint, warmupPeriodSlots: bigint): bigint;
+/**
+ * Warmup progress information for a position.
+ */
+export interface WarmupProgress {
+    /** PnL available for withdrawal right now (not locked by warmup). */
+    maturedPnl: bigint;
+    /** PnL still locked until warmup completes. */
+    reservedPnl: bigint;
+    /** Progress toward full warmup as a basis point (0–10,000). */
+    progressBps: bigint;
+    /** Slots remaining until full warmup (0 if fully matured). */
+    slotsRemaining: bigint;
+}
+/**
+ * Compute PnL warmup progress for a position.
+ *
+ * During the warmup period, a position's unrealized PnL is linearly released.
+ * The portion available for withdrawal grows over time. This utility shows:
+ * - How much PnL is currently available (matured)
+ * - How much is still locked (reserved)
+ * - Progress toward full maturation (as %)
+ * - Slots remaining
+ *
+ * Users can display a progress bar or "unlocks in X slots" message to give
+ * transparency into when their PnL becomes withdrawable.
+ *
+ * @param currentSlot        - Current on-chain slot (from engine state).
+ * @param warmupStartedAtSlot - Slot when this position's warmup started.
+ * @param warmupPeriodSlots  - Total warmup duration in slots (from market config).
+ * @param pnl                - Total realized + unrealized PnL (from account).
+ * @param reservedPnl        - PnL locked during warmup (from account).
+ * @returns WarmupProgress with matured/reserved PnL, progress %, and slots remaining.
+ *
+ * @example
+ * ```ts
+ * const progress = computeWarmupProgress(
+ *   10000n,      // current slot
+ *   9000n,       // warmup started at slot 9000
+ *   2000n,       // warmup period = 2000 slots
+ *   1000000000n, // pnl = 1 SOL
+ *   600000000n   // reserved = 0.6 SOL (60% still locked)
+ * );
+ * // Returns:
+ * // maturedPnl: 400000000n    (0.4 SOL available)
+ * // reservedPnl: 600000000n   (0.6 SOL locked)
+ * // progressBps: 5000n        (50% complete)
+ * // slotsRemaining: 1000n     (1000 slots until fully mature)
+ * ```
+ */
+export declare function computeWarmupProgress(currentSlot: bigint, warmupStartedAtSlot: bigint, warmupPeriodSlots: bigint, pnl: bigint, reservedPnl: bigint): WarmupProgress;

package/dist/runtime/index.d.ts

@@ -1 +1,2 @@
 export * from "./tx.js";
+export * from "./lighthouse.js";

package/dist/runtime/lighthouse.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @module lighthouse
+ * Lighthouse v2 (Blowfish / Phantom wallet middleware) detection and mitigation.
+ *
+ * Lighthouse (program L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95) is an Anchor-based
+ * wallet guard injected by Phantom and other Solana wallets via the Blowfish transaction
+ * scanning service. It adds assertion instructions to transactions that verify account
+ * state expectations (e.g., "this account should be empty" or "this account should have
+ * X lamports").
+ *
+ * **Problem:** Lighthouse doesn't understand Percolator's slab accounts. When a slab
+ * (e.g., ESa89R5 with 323,312 bytes) is passed as a TradeCpi account, Lighthouse injects
+ * an assertion like `StateInvalidAddress` that expects `data_len == 0` (uninitialised).
+ * The slab IS initialised, so the assertion fails with error 0x1900 (Anchor ConstraintAddress
+ * = 6400 decimal). This causes the transaction to revert even though the Percolator program
+ * logic is correct.
+ *
+ * **Solution:** The SDK provides utilities to:
+ * 1. Detect Lighthouse instructions in a transaction
+ * 2. Strip them before sending
+ * 3. Classify 0x1900 errors as Lighthouse (not Percolator) errors
+ * 4. Provide clear, actionable error messages for end users
+ *
+ * @example
+ * ```ts
+ * import { isLighthouseError, stripLighthouseInstructions, LIGHTHOUSE_PROGRAM_ID } from "@percolator/sdk";
+ *
+ * // Before sending: strip injected Lighthouse IXs
+ * const cleanIxs = stripLighthouseInstructions(instructions);
+ *
+ * // After error: classify and give user-friendly message
+ * if (isLighthouseError(error)) {
+ *   console.warn("Wallet middleware blocked the transaction");
+ * }
+ * ```
+ */
+import { PublicKey, TransactionInstruction, Transaction } from "@solana/web3.js";
+/**
+ * Lighthouse v2 program ID (Blowfish/Phantom wallet guard).
+ *
+ * This is an immutable Anchor program deployed at slot 294,179,293.
+ * Wallets like Phantom inject instructions from this program into user
+ * transactions to enforce Blowfish security assertions.
+ */
+export declare const LIGHTHOUSE_PROGRAM_ID: PublicKey;
+/** Base58 string form for fast comparison without PublicKey instantiation. */
+export declare const LIGHTHOUSE_PROGRAM_ID_STR = "L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95";
+/**
+ * Anchor error code for ConstraintAddress (0x1900 = 6400 decimal).
+ * This is NOT a Percolator error — it comes from Lighthouse's Anchor framework
+ * when an account constraint check fails.
+ */
+export declare const LIGHTHOUSE_CONSTRAINT_ADDRESS = 6400;
+/**
+ * Known Lighthouse/Anchor error codes that may appear in transaction logs.
+ * All are in the Anchor error range (0x1770–0x1900+).
+ */
+export declare const LIGHTHOUSE_ERROR_CODES: Set<6000 | 6032 | 6036 | 6038 | 6400 | 6001 | 6002 | 6003 | 6016 | 6033 | 6034 | 6035 | 6037 | 6039 | 6040 | 6041 | 6042 | 6043>;
+/**
+ * Check if a TransactionInstruction is from the Lighthouse program.
+ *
+ * @param ix - A Solana transaction instruction.
+ * @returns `true` if the instruction's programId is Lighthouse.
+ *
+ * @example
+ * ```ts
+ * const hasLighthouse = instructions.some(isLighthouseInstruction);
+ * ```
+ */
+export declare function isLighthouseInstruction(ix: TransactionInstruction): boolean;
+/**
+ * Check if an error message or error object indicates a Lighthouse assertion failure.
+ *
+ * Detects:
+ * - `custom program error: 0x1900` (Anchor ConstraintAddress from Lighthouse)
+ * - References to the Lighthouse program ID in error text
+ * - `"Custom": 6400` in JSON-encoded InstructionError
+ * - Any Anchor error code in the LIGHTHOUSE_ERROR_CODES range when the
+ *   failing program is Lighthouse (identified by program ID in logs)
+ *
+ * @param error - An Error object, error message string, or transaction logs array.
+ * @returns `true` if the error appears to originate from Lighthouse, not Percolator.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sendTransaction(tx);
+ * } catch (e) {
+ *   if (isLighthouseError(e)) {
+ *     // Retry with skipPreflight or notify user about wallet middleware
+ *   }
+ * }
+ * ```
+ */
+export declare function isLighthouseError(error: unknown): boolean;
+/**
+ * Check if transaction logs contain evidence of a Lighthouse failure.
+ *
+ * More precise than `isLighthouseError` on a string — examines the program
+ * invocation chain to confirm the error originates from Lighthouse, not from
+ * a Percolator instruction that happens to return a similar code.
+ *
+ * @param logs - Array of transaction log lines from `getTransaction()`.
+ * @returns `true` if logs show a Lighthouse program failure.
+ */
+export declare function isLighthouseFailureInLogs(logs: string[]): boolean;
+/**
+ * Remove all Lighthouse assertion instructions from an instruction array.
+ *
+ * Call this before building a Transaction to prevent Lighthouse assertion
+ * failures. Safe to call even if no Lighthouse instructions are present.
+ *
+ * @param instructions - Array of transaction instructions.
+ * @returns Filtered array with Lighthouse instructions removed.
+ *
+ * @example
+ * ```ts
+ * import { stripLighthouseInstructions } from "@percolator/sdk";
+ *
+ * const instructions = [crankIx, tradeIx]; // May have Lighthouse IXs mixed in
+ * const clean = stripLighthouseInstructions(instructions);
+ * const tx = new Transaction().add(...clean);
+ * ```
+ */
+export declare function stripLighthouseInstructions(instructions: TransactionInstruction[], percolatorProgramId?: PublicKey): TransactionInstruction[];
+/**
+ * Strip Lighthouse instructions from an already-built Transaction.
+ *
+ * Creates a new Transaction with the same recentBlockhash and feePayer
+ * but without any Lighthouse instructions. The returned transaction is
+ * unsigned and must be re-signed.
+ *
+ * @param transaction - A Transaction (signed or unsigned).
+ * @returns A new Transaction without Lighthouse instructions, or the same
+ *          transaction if no Lighthouse instructions were found.
+ *
+ * @example
+ * ```ts
+ * const signed = await wallet.signTransaction(tx);
+ * if (hasLighthouseInstructions(signed)) {
+ *   const clean = stripLighthouseFromTransaction(signed);
+ *   const reSigned = await wallet.signTransaction(clean);
+ *   await connection.sendRawTransaction(reSigned.serialize());
+ * }
+ * ```
+ */
+export declare function stripLighthouseFromTransaction(transaction: Transaction, percolatorProgramId?: PublicKey): Transaction;
+/**
+ * Count Lighthouse instructions in an instruction array or transaction.
+ *
+ * @param ixsOrTx - Array of instructions or a Transaction.
+ * @returns Number of Lighthouse instructions found.
+ */
+export declare function countLighthouseInstructions(ixsOrTx: TransactionInstruction[] | Transaction): number;
+/**
+ * User-friendly error message for Lighthouse assertion failures.
+ *
+ * Suitable for display in UI toast/modal when `isLighthouseError()` returns true.
+ */
+export declare const LIGHTHOUSE_USER_MESSAGE: string;
+/**
+ * Classify an error and return an appropriate user-facing message.
+ *
+ * If the error is from Lighthouse, returns the Lighthouse-specific message.
+ * Otherwise returns `null` (callers should use their own error display).
+ *
+ * @param error - An Error, string, or logs array.
+ * @returns User-facing message string, or `null` if not a Lighthouse error.
+ */
+export declare function classifyLighthouseError(error: unknown): string | null;