@percolatorct/sdk 1.0.0-beta.15 → 1.0.0-beta.17

package/dist/math/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./trading.js";
+export * from "./warmup.js";

package/dist/math/trading.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Coin-margined perpetual trade math utilities.
+ *
+ * On-chain PnL formula:
+ *   mark_pnl = (oracle - entry) * abs_pos / oracle   (longs)
+ *   mark_pnl = (entry - oracle) * abs_pos / oracle   (shorts)
+ *
+ * All prices are in e6 format (1 USD = 1_000_000).
+ * All token amounts are in native units (e.g. lamports).
+ */
+/**
+ * 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;
+/**
+ * Dynamic fee tier configuration.
+ */
+export interface FeeTierConfig {
+    /** Base trading fee (Tier 1) in bps */
+    baseBps: bigint;
+    /** Tier 2 fee in bps (0 = disabled) */
+    tier2Bps: bigint;
+    /** Tier 3 fee in bps (0 = disabled) */
+    tier3Bps: bigint;
+    /** Notional threshold to enter Tier 2 (0 = tiered fees disabled) */
+    tier2Threshold: bigint;
+    /** Notional threshold to enter Tier 3 */
+    tier3Threshold: bigint;
+}
+/**
+ * Compute the effective fee rate in bps using the tiered fee schedule.
+ *
+ * Mirrors on-chain `compute_dynamic_fee_bps` logic:
+ * - notional < tier2Threshold → baseBps (Tier 1)
+ * - notional < tier3Threshold → tier2Bps (Tier 2)
+ * - notional >= tier3Threshold → tier3Bps (Tier 3)
+ *
+ * If tier2Threshold == 0, tiered fees are disabled (flat baseBps).
+ */
+export declare function computeDynamicFeeBps(notional: bigint, config: FeeTierConfig): bigint;
+/**
+ * Compute the dynamic trading fee for a given notional and tier config.
+ *
+ * Uses ceiling division to match on-chain behavior (prevents fee evasion
+ * via micro-trades).
+ */
+export declare function computeDynamicTradingFee(notional: bigint, config: FeeTierConfig): bigint;
+/**
+ * Fee split configuration.
+ */
+export interface FeeSplitConfig {
+    /** LP vault share in bps (0–10_000) */
+    lpBps: bigint;
+    /** Protocol treasury share in bps */
+    protocolBps: bigint;
+    /** Market creator share in bps */
+    creatorBps: bigint;
+}
+/**
+ * Compute fee split for a total fee amount.
+ *
+ * Returns [lpShare, protocolShare, creatorShare].
+ * If all split params are 0, 100% goes to LP (legacy behavior).
+ * Creator gets the rounding remainder to ensure total is preserved.
+ */
+export declare function computeFeeSplit(totalFee: bigint, config: FeeSplitConfig): [bigint, bigint, bigint];
+/**
+ * Compute PnL as a percentage of capital.
+ *
+ * Uses BigInt scaling to avoid precision loss from Number(bigint) conversion.
+ * Number(bigint) silently truncates values above 2^53, which can produce
+ * incorrect percentages for large positions (e.g., tokens with 9 decimals
+ * where capital > ~9M tokens in native units exceeds MAX_SAFE_INTEGER).
+ */
+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.
+ *
+ * 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

@@ -0,0 +1,105 @@
+/**
+ * Warmup leverage cap utilities.
+ *
+ * During the market warmup period, capital is released linearly over
+ * `warmupPeriodSlots` slots, which constrains the effective leverage
+ * and maximum position size available to traders.
+ */
+/**
+ * Compute unlocked capital during the warmup period.
+ *
+ * Capital is released linearly over `warmupPeriodSlots` slots starting from
+ * `warmupStartedAtSlot`. Before warmup starts (startSlot === 0) or if the
+ * warmup period is 0, all capital is considered unlocked.
+ *
+ * @param totalCapital    - Total deposited capital (native units).
+ * @param currentSlot     - The current on-chain slot.
+ * @param warmupStartSlot - Slot at which warmup started (0 = not started).
+ * @param warmupPeriodSlots - Total slots in the warmup period.
+ * @returns The amount of capital currently unlocked.
+ */
+export declare function computeWarmupUnlockedCapital(totalCapital: bigint, currentSlot: bigint, warmupStartSlot: bigint, warmupPeriodSlots: bigint): bigint;
+/**
+ * Compute the effective maximum leverage during the warmup period.
+ *
+ * During warmup, only unlocked capital can be used as margin. The effective
+ * leverage relative to *total* capital is therefore capped at:
+ *
+ *   effectiveMaxLeverage = maxLeverage × (unlockedCapital / totalCapital)
+ *
+ * This returns a floored integer value (leverage is always a whole number
+ * in the UI), with a minimum of 1x if any capital is unlocked.
+ *
+ * @param initialMarginBps   - Initial margin requirement in basis points.
+ * @param totalCapital       - Total deposited capital (native units).
+ * @param currentSlot        - The current on-chain slot.
+ * @param warmupStartSlot    - Slot at which warmup started (0 = not started).
+ * @param warmupPeriodSlots  - Total slots in the warmup period.
+ * @returns The effective maximum leverage (integer, ≥ 1).
+ */
+export declare function computeWarmupLeverageCap(initialMarginBps: bigint, totalCapital: bigint, currentSlot: bigint, warmupStartSlot: bigint, warmupPeriodSlots: bigint): number;
+/**
+ * Compute the maximum position size allowed during warmup.
+ *
+ * This is the unlocked capital multiplied by the base max leverage.
+ * Unlike `computeWarmupLeverageCap` (which gives effective leverage
+ * relative to total capital), this gives the absolute notional cap.
+ *
+ * @param initialMarginBps   - Initial margin requirement in basis points.
+ * @param totalCapital       - Total deposited capital (native units).
+ * @param currentSlot        - The current on-chain slot.
+ * @param warmupStartSlot    - Slot at which warmup started (0 = not started).
+ * @param warmupPeriodSlots  - Total slots in the warmup period.
+ * @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/oracle/price-router.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Smart Price Router — automatic oracle selection for any token.
+ *
+ * Given a token mint, discovers all available price sources (DexScreener, Pyth, Jupiter),
+ * ranks them by liquidity/reliability, and returns the best oracle config.
+ */
+export type PriceSourceType = "pyth" | "dex" | "jupiter";
+export interface PriceSource {
+    type: PriceSourceType;
+    /** Pool address (dex), Pyth feed ID (pyth), or mint (jupiter) */
+    address: string;
+    /** DEX id for dex sources */
+    dexId?: string;
+    /** Pair label e.g. "SOL / USDC" */
+    pairLabel?: string;
+    /** USD liquidity depth — higher is better */
+    liquidity: number;
+    /** Latest spot price in USD */
+    price: number;
+    /** Confidence score 0-100 (composite of liquidity, staleness, reliability) */
+    confidence: number;
+}
+export interface PriceRouterResult {
+    mint: string;
+    bestSource: PriceSource | null;
+    allSources: PriceSource[];
+    /** ISO timestamp of resolution */
+    resolvedAt: string;
+}
+/** Options for {@link resolvePrice}. */
+export interface ResolvePriceOptions {
+    timeoutMs?: number;
+}
+export declare const PYTH_SOLANA_FEEDS: Record<string, {
+    symbol: string;
+    mint: string;
+}>;
+export declare function resolvePrice(mint: string, signal?: AbortSignal, options?: ResolvePriceOptions): Promise<PriceRouterResult>;

package/dist/runtime/index.d.ts

@@ -0,0 +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;

package/dist/runtime/tx.d.ts

@@ -0,0 +1,31 @@
+import { Connection, PublicKey, TransactionInstruction, Keypair, Commitment, AccountMeta } from "@solana/web3.js";
+export interface BuildIxParams {
+    programId: PublicKey;
+    keys: AccountMeta[];
+    data: Uint8Array | Buffer;
+}
+/**
+ * Build a transaction instruction.
+ */
+export declare function buildIx(params: BuildIxParams): TransactionInstruction;
+export interface TxResult {
+    signature: string;
+    slot: number;
+    err: string | null;
+    hint?: string;
+    logs: string[];
+    unitsConsumed?: number;
+}
+export interface SimulateOrSendParams {
+    connection: Connection;
+    ix: TransactionInstruction;
+    signers: Keypair[];
+    simulate: boolean;
+    commitment?: Commitment;
+    computeUnitLimit?: number;
+}
+export declare function simulateOrSend(params: SimulateOrSendParams): Promise<TxResult>;
+/**
+ * Format transaction result for output.
+ */
+export declare function formatResult(result: TxResult, jsonMode: boolean): string;