@percolatorct/sdk 0.3.0

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,107 @@
+/**
+ * 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.
+ */
+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).
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+export declare function computeEstimatedEntryPrice(oracleE6: bigint, tradingFeeBps: bigint, direction: "long" | "short"): bigint;
+/**
+ * Convert per-slot funding rate (bps) to annualized percentage.
+ */
+export declare function computeFundingRateAnnualized(fundingRateBpsPerSlot: bigint): number;
+/**
+ * Compute margin required for a given notional and initial margin bps.
+ */
+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)
+ */
+export declare function computeMaxLeverage(initialMarginBps: bigint): number;

package/dist/math/warmup.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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;

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 @@
+export * from "./tx.js";

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;

package/dist/solana/adl.d.ts

@@ -0,0 +1,305 @@
+/**
+ * @module adl
+ * Percolator ADL (Auto-Deleveraging) client utilities.
+ *
+ * PERC-8278 / PERC-8312 / PERC-305: ADL is triggered when `pnl_pos_tot > max_pnl_cap`
+ * on a market (PnL cap exceeded) AND the insurance fund is fully depleted (balance == 0).
+ * The most profitable positions on the dominant side are deleveraged first.
+ *
+ * **Note on caller permissions:** `ExecuteAdl` (tag 50) requires the caller to be the
+ * market admin/keeper key (`header.admin`). It is NOT permissionless despite the
+ * instruction being structurally available to any signer.
+ *
+ * API surface:
+ *  - fetchAdlRankedPositions() — fetch slab + rank all open positions by PnL%
+ *  - rankAdlPositions()        — pure (no-RPC) variant for already-fetched slab bytes
+ *  - isAdlTriggered()          — check if slab's pnl_pos_tot exceeds max_pnl_cap
+ *  - buildAdlInstruction()     — build a single ExecuteAdl TransactionInstruction
+ *  - buildAdlTransaction()     — fetch + rank + pick top target + return instruction
+ *  - parseAdlEvent()           — decode AdlEvent from transaction log lines
+ *  - fetchAdlRankings()        — call /api/adl/rankings HTTP endpoint
+ *  - AdlRankedPosition         — position record with adl_rank and computed pnlPct
+ *  - AdlRankingResult          — full ranking with trigger status
+ *  - AdlEvent                  — decoded on-chain AdlEvent log entry (tag 0xAD1E_0001)
+ *  - AdlApiRanking             — single ranked position from /api/adl/rankings
+ *  - AdlApiResult              — full result from /api/adl/rankings
+ *  - AdlSide                   — "long" | "short"
+ */
+import { Connection, PublicKey, TransactionInstruction } from "@solana/web3.js";
+/** Position side derived from positionSize sign. */
+export type AdlSide = "long" | "short";
+/**
+ * A ranked open position for ADL purposes.
+ * Positions are ranked descending by `pnlPct` — rank 0 is the most profitable
+ * and will be deleveraged first.
+ */
+export interface AdlRankedPosition {
+    /** Account index in the slab (used as `targetIdx` in ExecuteAdl). */
+    idx: number;
+    /** Owner public key. */
+    owner: PublicKey;
+    /** Raw position size (i128 — negative = short, positive = long). */
+    positionSize: bigint;
+    /** Realised + mark-to-market PnL in lamports (i128 from slab). */
+    pnl: bigint;
+    /** Capital at entry in lamports (u128). */
+    capital: bigint;
+    /**
+     * PnL as a fraction of capital, expressed as basis points (scaled × 10_000).
+     * pnlPct = pnl * 10_000 / capital.
+     * Higher = more profitable = deleveraged first.
+     */
+    pnlPct: bigint;
+    /** Long or short. */
+    side: AdlSide;
+    /**
+     * ADL rank among positions on the same side (0 = highest PnL%, deleveraged first).
+     * `-1` if position size is zero (inactive).
+     */
+    adlRank: number;
+}
+/**
+ * Result of `fetchAdlRankedPositions`.
+ */
+export interface AdlRankingResult {
+    /** All open (non-zero) user positions, sorted descending by PnLPct, ranked. */
+    ranked: AdlRankedPosition[];
+    /**
+     * Longs ranked separately (adlRank within this subset).
+     * Rank 0 = most profitable long = first to be deleveraged on a net-long market.
+     */
+    longs: AdlRankedPosition[];
+    /**
+     * Shorts ranked separately (adlRank within this subset).
+     * Rank 0 = most profitable short (most negative pnlPct magnitude — i.e., highest
+     * unrealised gain for the short-side holder).
+     */
+    shorts: AdlRankedPosition[];
+    /** Whether ADL is currently triggered (pnlPosTot > maxPnlCap). */
+    isTriggered: boolean;
+    /** pnl_pos_tot from engine state. */
+    pnlPosTot: bigint;
+    /** max_pnl_cap from market config. */
+    maxPnlCap: bigint;
+}
+/**
+ * Check whether ADL is currently triggered on a slab.
+ *
+ * ADL triggers when pnl_pos_tot > max_pnl_cap (max_pnl_cap must be > 0).
+ *
+ * @param slabData - Raw slab account bytes.
+ * @returns true if ADL is triggered.
+ *
+ * @example
+ * ```ts
+ * const data = await fetchSlab(connection, slabKey);
+ * if (isAdlTriggered(data)) {
+ *   const ranking = await fetchAdlRankedPositions(connection, slabKey);
+ * }
+ * ```
+ */
+export declare function isAdlTriggered(slabData: Uint8Array): boolean;
+/**
+ * Fetch a slab and rank all open user positions by PnL% for ADL targeting.
+ *
+ * Positions are ranked separately per side:
+ * - Longs: rank 0 = highest positive PnL% (most profitable long)
+ * - Shorts: rank 0 = highest negative PnL% by abs value (most profitable short)
+ *
+ * Rank ordering matches the on-chain ADL engine in percolator-prog (PERC-8273):
+ * the position at rank 0 of the dominant side is deleveraged first.
+ *
+ * @param connection - Solana connection.
+ * @param slab       - Slab (market) public key.
+ * @returns AdlRankingResult with ranked longs, ranked shorts, and trigger status.
+ *
+ * @example
+ * ```ts
+ * const { ranked, longs, isTriggered } = await fetchAdlRankedPositions(connection, slabKey);
+ * if (isTriggered && longs.length > 0) {
+ *   const target = longs[0]; // highest PnL long
+ *   const ix = buildAdlInstruction(caller, slabKey, oracleKey, programId, target.idx);
+ * }
+ * ```
+ */
+export declare function fetchAdlRankedPositions(connection: Connection, slab: PublicKey): Promise<AdlRankingResult>;
+/**
+ * Pure (no-RPC) variant — rank positions from already-fetched slab bytes.
+ * Useful when you already have the slab data (e.g., from a subscription).
+ */
+export declare function rankAdlPositions(slabData: Uint8Array): AdlRankingResult;
+/**
+ * Build a single `ExecuteAdl` TransactionInstruction (tag 50, PERC-305).
+ *
+ * Does NOT fetch the slab or check trigger status — use `fetchAdlRankedPositions`
+ * first to determine the correct `targetIdx`.
+ *
+ * **Caller requirement:** The on-chain handler requires the caller to be the market
+ * admin/keeper authority (`header.admin`). Passing any other signer will result in
+ * `EngineUnauthorized`.
+ *
+ * @param caller     - Signer — must be the market keeper/admin authority.
+ * @param slab       - Slab (market) public key.
+ * @param oracle     - Primary oracle public key for this market.
+ * @param programId  - Percolator program ID.
+ * @param targetIdx  - Account index to deleverage (from `AdlRankedPosition.idx`).
+ * @param backupOracles - Optional additional oracle accounts (non-Hyperp markets).
+ *
+ * @example
+ * ```ts
+ * import { fetchAdlRankedPositions, buildAdlInstruction } from "@percolator/sdk";
+ *
+ * const { longs, isTriggered } = await fetchAdlRankedPositions(connection, slabKey);
+ * if (isTriggered && longs.length > 0) {
+ *   const ix = buildAdlInstruction(
+ *     caller.publicKey, slabKey, oracleKey, PROGRAM_ID, longs[0].idx
+ *   );
+ *   await sendAndConfirmTransaction(connection, new Transaction().add(ix), [caller]);
+ * }
+ * ```
+ */
+export declare function buildAdlInstruction(caller: PublicKey, slab: PublicKey, oracle: PublicKey, programId: PublicKey, targetIdx: number, backupOracles?: PublicKey[]): TransactionInstruction;
+/**
+ * Convenience builder: fetch slab, rank positions, pick the highest-ranked
+ * target on the given side, and return a ready-to-send `TransactionInstruction`.
+ *
+ * Returns `null` when ADL is not triggered or no eligible positions exist.
+ *
+ * @param connection    - Solana connection.
+ * @param caller        - Signer — must be the market keeper/admin authority.
+ * @param slab          - Slab (market) public key.
+ * @param oracle        - Primary oracle public key.
+ * @param programId     - Percolator program ID.
+ * @param preferSide    - Optional: target "long" or "short" side only.
+ *                        If omitted, picks the overall top-ranked position.
+ * @param backupOracles - Optional extra oracle accounts.
+ *
+ * @example
+ * ```ts
+ * const ix = await buildAdlTransaction(
+ *   connection, caller.publicKey, slabKey, oracleKey, PROGRAM_ID
+ * );
+ * if (ix) {
+ *   await sendAndConfirmTransaction(connection, new Transaction().add(ix), [caller]);
+ * }
+ * ```
+ */
+export declare function buildAdlTransaction(connection: Connection, caller: PublicKey, slab: PublicKey, oracle: PublicKey, programId: PublicKey, preferSide?: AdlSide, backupOracles?: PublicKey[]): Promise<TransactionInstruction | null>;
+/**
+ * Decoded on-chain AdlEvent emitted by the `ExecuteAdl` instruction handler.
+ *
+ * The on-chain handler emits via `sol_log_64(0xAD1E_0001, target_idx, price, closed_lo, closed_hi)`.
+ * `sol_log_64` prints 5 decimal u64 values separated by spaces on a single "Program log:" line.
+ *
+ * Fields:
+ * - `tag`       — always `0xAD1E_0001` (2970353665n)
+ * - `targetIdx` — slab account index that was deleveraged
+ * - `price`     — oracle price used (in market price units, e.g. e6)
+ * - `closedAbs` — absolute size of the position closed (i128, reassembled from lo+hi u64 parts)
+ *
+ * @example
+ * ```ts
+ * const logs = tx.meta?.logMessages ?? [];
+ * const event = parseAdlEvent(logs);
+ * if (event) {
+ *   console.log("ADL closed position", event.targetIdx, "size", event.closedAbs);
+ * }
+ * ```
+ */
+export interface AdlEvent {
+    /** Tag discriminator — always 0xAD1E_0001n (2970353665). */
+    tag: bigint;
+    /** Slab account index that was deleveraged. */
+    targetIdx: number;
+    /** Oracle price used for the deleverage (market-native units, e.g. lamports/e6). */
+    price: bigint;
+    /**
+     * Absolute position size closed (reassembled from lo+hi u64).
+     * This is the i128 absolute value — always non-negative.
+     */
+    closedAbs: bigint;
+}
+/**
+ * Parse the AdlEvent from a transaction's log messages.
+ *
+ * Searches for a "Program log: <a> <b> <c> <d> <e>" line where the first
+ * decimal value equals `0xAD1E_0001` (2970353665). Returns `null` if not found.
+ *
+ * @param logs - Array of log message strings (from `tx.meta.logMessages`).
+ * @returns Decoded `AdlEvent` or `null` if the log is not present.
+ *
+ * @example
+ * ```ts
+ * const event = parseAdlEvent(tx.meta?.logMessages ?? []);
+ * if (event) {
+ *   console.log(`ADL: idx=${event.targetIdx} price=${event.price} closed=${event.closedAbs}`);
+ * }
+ * ```
+ */
+export declare function parseAdlEvent(logs: string[]): AdlEvent | null;
+/**
+ * A single ranked position as returned by the /api/adl/rankings endpoint.
+ */
+export interface AdlApiRanking {
+    /** 1-based rank (1 = highest PnL%, first to be deleveraged). */
+    rank: number;
+    /** Slab account index. Pass as `targetIdx` to `buildAdlInstruction`. */
+    idx: number;
+    /** Absolute PnL (lamports) as a decimal string. */
+    pnlAbs: string;
+    /** Capital at entry (lamports) as a decimal string. */
+    capital: string;
+    /** PnL as millionths of capital (pnl * 1_000_000 / capital). */
+    pnlPctMillionths: string;
+}
+/**
+ * Full result from the /api/adl/rankings endpoint.
+ */
+export interface AdlApiResult {
+    slabAddress: string;
+    /** pnl_pos_tot from slab engine state (decimal string). */
+    pnlPosTot: string;
+    /** max_pnl_cap from market config (decimal string, "0" if unconfigured). */
+    maxPnlCap: string;
+    /** Insurance fund balance (decimal string). */
+    insuranceFundBalance: string;
+    /** Insurance fund lifetime fee revenue (decimal string). */
+    insuranceFundFeeRevenue: string;
+    /** Insurance utilization in basis points (0–10000). */
+    insuranceUtilizationBps: number;
+    /** true if pnlPosTot > maxPnlCap. */
+    capExceeded: boolean;
+    /** true if insurance fund is fully depleted (balance == 0). */
+    insuranceDepleted: boolean;
+    /** true if utilization BPS exceeds the configured ADL threshold. */
+    utilizationTriggered: boolean;
+    /** true if ADL is needed (capExceeded or utilizationTriggered). */
+    adlNeeded: boolean;
+    /** Excess PnL above cap (decimal string). */
+    excess: string;
+    /** Ranked positions (empty if adlNeeded=false). */
+    rankings: AdlApiRanking[];
+}
+/**
+ * Fetch ADL rankings from the Percolator API.
+ *
+ * Calls `GET <apiBase>/api/adl/rankings?slab=<address>` and returns the
+ * parsed result. Use this from the frontend or keeper to determine ADL
+ * trigger status and pick the target index.
+ *
+ * @param apiBase  - Base URL of the Percolator API (e.g. `https://api.percolator.io`).
+ * @param slab     - Slab (market) public key or base58 address string.
+ * @param fetchFn  - Optional custom fetch implementation (defaults to global `fetch`).
+ * @returns Parsed `AdlApiResult`.
+ * @throws On HTTP error or JSON parse failure.
+ *
+ * @example
+ * ```ts
+ * const result = await fetchAdlRankings("https://api.percolator.io", slabKey);
+ * if (result.adlNeeded && result.rankings.length > 0) {
+ *   const target = result.rankings[0]; // rank 1 = highest PnL%
+ *   const ix = buildAdlInstruction(caller, slabKey, oracleKey, PROGRAM_ID, target.idx);
+ * }
+ * ```
+ */
+export declare function fetchAdlRankings(apiBase: string, slab: PublicKey | string, fetchFn?: typeof fetch): Promise<AdlApiResult>;

package/dist/solana/ata.d.ts

@@ -0,0 +1,18 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { Account } from "@solana/spl-token";
+/**
+ * Get the associated token address for an owner and mint.
+ * Supports both standard SPL Token and Token2022 via optional tokenProgramId.
+ */
+export declare function getAta(owner: PublicKey, mint: PublicKey, allowOwnerOffCurve?: boolean, tokenProgramId?: PublicKey): Promise<PublicKey>;
+/**
+ * Synchronous version of getAta.
+ * Supports both standard SPL Token and Token2022 via optional tokenProgramId.
+ */
+export declare function getAtaSync(owner: PublicKey, mint: PublicKey, allowOwnerOffCurve?: boolean, tokenProgramId?: PublicKey): PublicKey;
+/**
+ * Fetch token account info.
+ * Supports both standard SPL Token and Token2022 via optional tokenProgramId.
+ * Throws if account doesn't exist.
+ */
+export declare function fetchTokenAccount(connection: Connection, address: PublicKey, tokenProgramId?: PublicKey): Promise<Account>;

package/dist/solana/dex-oracle.d.ts

@@ -0,0 +1,49 @@
+import { PublicKey } from "@solana/web3.js";
+export type DexType = "pumpswap" | "raydium-clmm" | "meteora-dlmm";
+export interface DexPoolInfo {
+    dexType: DexType;
+    poolAddress: PublicKey;
+    baseMint: PublicKey;
+    quoteMint: PublicKey;
+    baseVault?: PublicKey;
+    quoteVault?: PublicKey;
+}
+/**
+ * Detect DEX type from the program that owns the pool account.
+ *
+ * @param ownerProgramId - The program ID that owns the pool account
+ * @returns The detected DEX type, or `null` if the owner is not a supported DEX program
+ *
+ * Supported DEX programs:
+ * - PumpSwap (constant-product AMM)
+ * - Raydium CLMM (concentrated liquidity)
+ * - Meteora DLMM (discretized liquidity)
+ */
+export declare function detectDexType(ownerProgramId: PublicKey): DexType | null;
+/**
+ * Parse a DEX pool account into a {@link DexPoolInfo} struct.
+ *
+ * @param dexType - The type of DEX (pumpswap, raydium-clmm, or meteora-dlmm)
+ * @param poolAddress - The on-chain address of the pool account
+ * @param data - Raw account data bytes
+ * @returns Parsed pool info including mints and (for PumpSwap) vault addresses
+ * @throws Error if data is too short for the given DEX type
+ */
+export declare function parseDexPool(dexType: DexType, poolAddress: PublicKey, data: Uint8Array): DexPoolInfo;
+/**
+ * Compute the spot price from a DEX pool in e6 format (i.e., 1.0 = 1_000_000).
+ *
+ * **SECURITY NOTE:** DEX spot prices have no staleness or confidence checks and are
+ * vulnerable to flash-loan manipulation within a single transaction. For high-value
+ * markets, prefer Pyth or Chainlink oracles.
+ *
+ * @param dexType - The type of DEX
+ * @param data - Raw pool account data
+ * @param vaultData - For PumpSwap only: base and quote vault account data
+ * @returns Price in e6 format (quote per base token)
+ * @throws Error if data is too short or computation fails
+ */
+export declare function computeDexSpotPriceE6(dexType: DexType, data: Uint8Array, vaultData?: {
+    base: Uint8Array;
+    quote: Uint8Array;
+}): bigint;