@percolatorct/sdk 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/math/trading.d.ts

@@ -10,68 +10,20 @@
  */
 /**
  * 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;
 /**
@@ -137,86 +89,19 @@ 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.
  *
- * 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)
- * ```
+ * @throws Error if initialMarginBps is zero (infinite leverage is undefined)
  */
 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,53 +53,3 @@ 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/lighthouse.d.ts

@@ -55,7 +55,7 @@ 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>;
+export declare const LIGHTHOUSE_ERROR_CODES: Set<6400 | 6000 | 6001 | 6002 | 6003 | 6016 | 6032 | 6033 | 6034 | 6035 | 6036 | 6037 | 6038 | 6039 | 6040 | 6041 | 6042 | 6043>;
 /**
  * Check if a TransactionInstruction is from the Lighthouse program.
  *

package/dist/solana/oracle.d.ts

@@ -16,19 +16,11 @@ declare const CHAINLINK_MIN_SIZE = 224;
 declare const MAX_DECIMALS = 18;
 /** Offset of decimals field in Chainlink aggregator account */
 declare const CHAINLINK_DECIMALS_OFFSET = 138;
-/** Offset of updated_at timestamp (i64 LE, Unix seconds) in Chainlink aggregator */
-declare const CHAINLINK_TIMESTAMP_OFFSET = 168;
 /** Offset of latest answer in Chainlink aggregator account */
 declare const CHAINLINK_ANSWER_OFFSET = 216;
 export interface OraclePrice {
     price: bigint;
     decimals: number;
-    /** Unix timestamp (seconds) of the last oracle update, if available. */
-    updatedAt?: number;
-}
-export interface ParseChainlinkOptions {
-    /** Maximum allowed staleness in seconds. If the oracle update is older, an error is thrown. */
-    maxStalenessSeconds?: number;
 }
 /**
  * Parse price data from a Chainlink aggregator account buffer.
@@ -42,11 +34,11 @@ export interface ParseChainlinkOptions {
  * @returns Parsed oracle price with decimals
  * @throws if the buffer is invalid or contains unreasonable data
  */
-export declare function parseChainlinkPrice(data: Uint8Array, options?: ParseChainlinkOptions): OraclePrice;
+export declare function parseChainlinkPrice(data: Uint8Array): OraclePrice;
 /**
  * Validate that a buffer looks like a valid Chainlink aggregator account.
  * Returns true if the buffer passes all validation checks, false otherwise.
  * Use this for non-throwing validation.
  */
 export declare function isValidChainlinkOracle(data: Uint8Array): boolean;
-export { CHAINLINK_MIN_SIZE, CHAINLINK_DECIMALS_OFFSET, CHAINLINK_TIMESTAMP_OFFSET, CHAINLINK_ANSWER_OFFSET, MAX_DECIMALS };
+export { CHAINLINK_MIN_SIZE, CHAINLINK_DECIMALS_OFFSET, CHAINLINK_ANSWER_OFFSET, MAX_DECIMALS };

package/dist/solana/pda.d.ts

@@ -14,11 +14,6 @@ export declare function deriveInsuranceLpMint(programId: PublicKey, slab: Public
  * Seeds: ["lp", slab_key, lp_idx as u16 LE]
  */
 export declare function deriveLpPda(programId: PublicKey, slab: PublicKey, lpIdx: number): [PublicKey, number];
-/**
- * Derive keeper fund PDA.
- * Seeds: ["keeper_fund", slab_key]
- */
-export declare function deriveKeeperFund(programId: PublicKey, slab: PublicKey): [PublicKey, number];
 /** PumpSwap AMM program ID. */
 export declare const PUMPSWAP_PROGRAM_ID: PublicKey;
 /** Raydium CLMM (Concentrated Liquidity) program ID. */

package/dist/solana/slab.d.ts

@@ -130,10 +130,22 @@ export declare const SLAB_TIERS_V12_1: Record<string, {
     label: string;
     description: string;
 }>;
+/**
+ * V12_15 slab tier sizes — percolator v12.15 (engine+prog sync).
+ * ENGINE_OFF=624, BITMAP_OFF=862 (relative), ACCOUNT_SIZE=4400, postBitmap=18.
+ * MAX_ACCOUNTS default changed from 4096 to 2048. Verified SLAB_LEN=1,128,448 for small (256).
+ * Account layout completely redesigned with reserve cohort arrays.
+ */
+export declare const SLAB_TIERS_V12_15: Record<string, {
+    maxAccounts: number;
+    dataSize: number;
+    label: string;
+    description: string;
+}>;
 /**
  * Detect the slab layout version from the raw account data length.
  * Returns the full SlabLayout descriptor, or null if the size is unrecognised.
- * Checks V12_1, V_SETDEXPOOL, V1M2, V_ADL, V1M, V0, V1D, V1D-legacy, V1, and V1-legacy sizes.
+ * Checks V12_15, V12_1_EP, V12_1, V_SETDEXPOOL, V1M2, V_ADL, V1M, V0, V1D, V1D-legacy, V1, and V1-legacy sizes.
  *
  * When `data` is provided and the size matches V1D, the version field at offset 8 is read
  * to disambiguate V2 slabs (which produce identical sizes to V1D with postBitmap=2).
@@ -181,10 +193,10 @@ export interface MarketConfig {
     fundingInvScaleNotionalE6: bigint;
     fundingMaxPremiumBps: bigint;
     fundingMaxBpsPerSlot: bigint;
-    fundingPremiumWeightBps: bigint;
-    fundingSettlementIntervalSlots: bigint;
-    fundingPremiumDampeningE6: bigint;
-    fundingPremiumMaxBpsPerSlot: bigint;
+    /** @deprecated Removed in V12_1 — always 0 */ fundingPremiumWeightBps: bigint;
+    /** @deprecated Removed in V12_1 — always 0 */ fundingSettlementIntervalSlots: bigint;
+    /** @deprecated Removed in V12_1 — always 0 */ fundingPremiumDampeningE6: bigint;
+    /** @deprecated Removed in V12_1 — always 0 */ fundingPremiumMaxBpsPerSlot: bigint;
     threshFloor: bigint;
     threshRiskBps: bigint;
     threshUpdateIntervalSlots: bigint;
@@ -229,6 +241,10 @@ export interface InsuranceFund {
     isolationBps: number;
 }
 export interface RiskParams {
+    /**
+     * @deprecated Split into hMin/hMax in v12.15 RiskParams. On V12_15 slabs this field returns
+     * hMin for backwards compatibility. On pre-v12.15 slabs hMin/hMax both mirror this value.
+     */
     warmupPeriodSlots: bigint;
     maintenanceMarginBps: bigint;
     initialMarginBps: bigint;
@@ -242,6 +258,18 @@ export interface RiskParams {
     liquidationFeeCap: bigint;
     liquidationBufferBps: bigint;
     minLiquidationAbs: bigint;
+    /** Minimum initial deposit to open an account (V12_1+ only) */
+    minInitialDeposit: bigint;
+    /** Minimum nonzero maintenance margin requirement (V12_1+ only) */
+    minNonzeroMmReq: bigint;
+    /** Minimum nonzero initial margin requirement (V12_1+ only) */
+    minNonzeroImReq: bigint;
+    /** Insurance fund floor (V12_1+ only) */
+    insuranceFloor: bigint;
+    /** Minimum horizon slots (v12.15+). Replaces warmupPeriodSlots. 0n on pre-v12.15 slabs. */
+    hMin: bigint;
+    /** Maximum horizon slots (v12.15+). 0n on pre-v12.15 slabs. */
+    hMax: bigint;
 }
 export interface EngineState {
     vault: bigint;
@@ -249,7 +277,20 @@ export interface EngineState {
     currentSlot: bigint;
     fundingIndexQpbE6: bigint;
     lastFundingSlot: bigint;
+    /**
+     * Funding rate per slot. On pre-v12.15 slabs: i64 in BPS units.
+     * On v12.15+ slabs: i128 in e9 units (field renamed `funding_rate_e9` on-chain).
+     */
     fundingRateBpsPerSlotLast: bigint;
+    /**
+     * Funding rate in e9 units (i128). v12.15+ only.
+     * 0n on pre-v12.15 slabs.
+     */
+    fundingRateE9: bigint;
+    /**
+     * Market mode. v12.15+ only. 0 = Live, 1 = Resolved. null on pre-v12.15 slabs.
+     */
+    marketMode: 0 | 1 | null;
     lastCrankSlot: bigint;
     maxCrankStalenessSlots: bigint;
     totalOpenInterest: bigint;
@@ -257,6 +298,10 @@ export interface EngineState {
     shortOi: bigint;
     cTot: bigint;
     pnlPosTot: bigint;
+    /**
+     * Matured (settled) positive PnL total (u128). v12.15+ only. 0n on pre-v12.15 slabs.
+     */
+    pnlMaturedPosTot: bigint;
     liqCursor: number;
     gcCursor: number;
     lastSweepStartSlot: bigint;
@@ -280,22 +325,45 @@ export declare enum AccountKind {
     User = 0,
     LP = 1
 }
+/** Parsed reserve cohort (64 bytes on-chain). Raw bytes; structure is program-internal. */
+export type ReserveCohortBytes = Uint8Array;
 export interface Account {
     kind: AccountKind;
     accountId: bigint;
     capital: bigint;
     pnl: bigint;
     reservedPnl: bigint;
+    /** @deprecated Removed in v12.15. Always 0n on V12_15 slabs. */
     warmupStartedAtSlot: bigint;
+    /** @deprecated Removed in v12.15. Always 0n on V12_15 slabs. */
     warmupSlopePerStep: bigint;
     positionSize: bigint;
+    /** Entry price in e6 units. Present in V12_15 (offset 120) and V_ADL/V12_1_EP. -1 signals absent. */
     entryPrice: bigint;
     fundingIndex: bigint;
     matcherProgram: PublicKey;
     matcherContext: PublicKey;
     owner: PublicKey;
     feeCredits: bigint;
+    /** @deprecated Removed in v12.15. Always 0n on V12_15 slabs. */
     lastFeeSlot: bigint;
+    /** Total fees earned over account lifetime (u128). Present from v12.15. 0n on older layouts. */
+    feesEarnedTotal: bigint;
+    /**
+     * Reserve cohorts array (v12.15+). Up to 62 cohorts of 64 bytes each.
+     * `null` on pre-v12.15 slabs. Parse the raw bytes according to the on-chain ReserveCohort struct.
+     */
+    exactReserveCohorts: ReserveCohortBytes[] | null;
+    /** Number of active reserve cohorts (0-62). null on pre-v12.15 slabs. */
+    exactCohortCount: number | null;
+    /** Overflow (oldest) cohort raw bytes. null on pre-v12.15 slabs or when not present. */
+    overflowOlder: ReserveCohortBytes | null;
+    /** True if overflowOlder contains valid data. null on pre-v12.15 slabs. */
+    overflowOlderPresent: boolean | null;
+    /** Overflow (newest) cohort raw bytes. null on pre-v12.15 slabs or when not present. */
+    overflowNewest: ReserveCohortBytes | null;
+    /** True if overflowNewest contains valid data. null on pre-v12.15 slabs. */
+    overflowNewestPresent: boolean | null;
 }
 export declare function fetchSlab(connection: Connection, slabPubkey: PublicKey): Promise<Uint8Array>;
 export declare const RAMP_START_BPS = 1000n;

package/dist/solana/stake.d.ts

@@ -4,13 +4,13 @@
  *
  * Program: percolator-stake (dcccrypto/percolator-stake)
  * Deployed devnet:  6aJb1F9CDCVWCNYFwj8aQsVb696YnW6J1FznteHq4Q6k
- * Deployed mainnet: (pending deployment — DevOps must set STAKE_PROGRAM_ID env var or deploy and update STAKE_PROGRAM_IDS.mainnet)
+ * Deployed mainnet: DC5fovFQD5SZYsetwvEqd4Wi4PFY1Yfnc669VMe6oa7F
  */
 import { PublicKey } from '@solana/web3.js';
 /** Known stake program addresses per network. Mainnet is empty until deployed. */
 export declare const STAKE_PROGRAM_IDS: {
     readonly devnet: "6aJb1F9CDCVWCNYFwj8aQsVb696YnW6J1FznteHq4Q6k";
-    readonly mainnet: "";
+    readonly mainnet: "DC5fovFQD5SZYsetwvEqd4Wi4PFY1Yfnc669VMe6oa7F";
 };
 /**
  * Resolve the stake program ID for the given network.

package/dist/validation.d.ts

@@ -9,34 +9,14 @@ export declare class ValidationError extends Error {
 }
 /**
  * Validate a public key string.
- *
- * @param value - Base58-encoded public key string.
- * @param field - Field name for error messages.
- * @returns Parsed `PublicKey` instance.
- * @throws {@link ValidationError} if the string is not a valid base58 public key.
- *
- * @example
- * ```ts
- * const key = validatePublicKey("11111111111111111111111111111111", "slab");
- * ```
  */
 export declare function validatePublicKey(value: string, field: string): PublicKey;
 /**
  * Validate a non-negative integer index (u16 range for accounts).
- *
- * @param value - Decimal string representing the index.
- * @param field - Field name for error messages.
- * @returns Parsed integer in `[0, 65535]`.
- * @throws {@link ValidationError} if the value is not a valid u16 integer.
  */
 export declare function validateIndex(value: string, field: string): number;
 /**
  * Validate a non-negative amount (u64 range).
- *
- * @param value - Decimal string representing the amount.
- * @param field - Field name for error messages.
- * @returns Parsed `bigint` in `[0, 2^64 - 1]`.
- * @throws {@link ValidationError} if the value is negative or exceeds u64 max.
  */
 export declare function validateAmount(value: string, field: string): bigint;
 /**
@@ -52,12 +32,7 @@ export declare function validateI64(value: string, field: string): bigint;
  */
 export declare function validateI128(value: string, field: string): bigint;
 /**
- * Validate a basis points value (0–10000).
- *
- * @param value - Decimal string representing basis points.
- * @param field - Field name for error messages.
- * @returns Parsed integer in `[0, 10000]`.
- * @throws {@link ValidationError} if the value exceeds 10000.
+ * Validate a basis points value (0-10000).
  */
 export declare function validateBps(value: string, field: string): number;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percolatorct/sdk",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.21",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -31,6 +31,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.17.10",
+    "dotenv": "^17.4.1",
     "tsup": "^8.3.5",
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",