@percolatorct/sdk 0.3.0

package/dist/solana/discovery.d.ts

@@ -0,0 +1,263 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { type SlabHeader, type MarketConfig, type EngineState, type RiskParams } from "./slab.js";
+/**
+ * A discovered Percolator market from on-chain program accounts.
+ */
+export interface DiscoveredMarket {
+    slabAddress: PublicKey;
+    /** The program that owns this slab account */
+    programId: PublicKey;
+    header: SlabHeader;
+    config: MarketConfig;
+    engine: EngineState;
+    params: RiskParams;
+}
+/**
+ * Slab tier definitions — V1 layout (all tiers upgraded as of 2026-03-13).
+ * IMPORTANT: dataSize must match the compiled program's SLAB_LEN for that MAX_ACCOUNTS.
+ * The on-chain program has a hardcoded SLAB_LEN — slab account data.len() must equal it exactly.
+ *
+ * Layout: HEADER(104) + CONFIG(536) + RiskEngine(variable by tier)
+ *   ENGINE_OFF = 640  (HEADER=104 + CONFIG=536, padded to 8-byte align on SBF)
+ *   RiskEngine = fixed(656) + bitmap(BW*8) + post_bitmap(18) + next_free(N*2) + pad + accounts(N*248)
+ *
+ * Values are empirically verified against on-chain initialized accounts (GH #1109):
+ *   small  = 65,352  (256-acct program, verified on-chain post-V1 upgrade)
+ *   medium = 257,448 (1024-acct program g9msRSV3, verified on-chain)
+ *   large  = 1,025,832 (4096-acct program FxfD37s1, pre-PERC-118, matches slabDataSizeV1(4096) formula)
+ *
+ * NOTE: small program (FwfBKZXb) redeployed with --features small,devnet (2026-03-13).
+ *       Large program FxfD37s1 is pre-PERC-118 — SLAB_LEN=1,025,832, matching formula.
+ *       See GH #1109, GH #1112.
+ *
+ * History: Small was V0 (62_808) until 2026-03-13 program upgrade. V0 values preserved
+ *          in SLAB_TIERS_V0 for discovery of legacy on-chain accounts.
+ */
+export declare const SLAB_TIERS: {
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 65352;
+        readonly label: "Small";
+        readonly description: "256 slots · ~0.45 SOL";
+    };
+    readonly medium: {
+        readonly maxAccounts: 1024;
+        readonly dataSize: 257448;
+        readonly label: "Medium";
+        readonly description: "1,024 slots · ~1.79 SOL";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 1025832;
+        readonly label: "Large";
+        readonly description: "4,096 slots · ~7.14 SOL";
+    };
+};
+/** @deprecated V0 slab sizes — kept for backward compatibility with old on-chain slabs */
+export declare const SLAB_TIERS_V0: {
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 62808;
+        readonly label: "Small";
+        readonly description: "256 slots · ~0.44 SOL";
+    };
+    readonly medium: {
+        readonly maxAccounts: 1024;
+        readonly dataSize: 248760;
+        readonly label: "Medium";
+        readonly description: "1,024 slots · ~1.73 SOL";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 992568;
+        readonly label: "Large";
+        readonly description: "4,096 slots · ~6.90 SOL";
+    };
+};
+/**
+ * V1D slab sizes — actually-deployed devnet V1 program (ENGINE_OFF=424, BITMAP_OFF=624).
+ * PR #1200 added V1D layout detection in slab.ts but discovery.ts ALL_TIERS was missing
+ * these sizes, causing V1D slabs to fall through to the memcmp fallback with wrong dataSize
+ * hints → detectSlabLayout returning null → parse failure (GH#1205).
+ *
+ * Sizes computed via computeSlabSize(ENGINE_OFF=424, BITMAP_OFF=624, ACCOUNT_SIZE=248, N, postBitmap=2):
+ *   The V1D deployed program uses postBitmap=2 (free_head u16 only — no num_used/pad/next_account_id).
+ *   This is 16 bytes smaller per tier than the SDK default (postBitmap=18). GH#1234.
+ *   micro  =  17,064  (64 slots)
+ *   small  =  65,088  (256 slots)
+ *   medium = 257,184  (1,024 slots)
+ *   large  = 1,025,568 (4,096 slots)
+ */
+export declare const SLAB_TIERS_V1D: {
+    readonly micro: {
+        readonly maxAccounts: 64;
+        readonly dataSize: 17064;
+        readonly label: "Micro";
+        readonly description: "64 slots (V1D devnet)";
+    };
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 65088;
+        readonly label: "Small";
+        readonly description: "256 slots (V1D devnet)";
+    };
+    readonly medium: {
+        readonly maxAccounts: 1024;
+        readonly dataSize: 257184;
+        readonly label: "Medium";
+        readonly description: "1,024 slots (V1D devnet)";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 1025568;
+        readonly label: "Large";
+        readonly description: "4,096 slots (V1D devnet)";
+    };
+};
+/**
+ * V1D legacy slab sizes — on-chain V1D slabs created before GH#1234 when the SDK assumed
+ * postBitmap=18. These are 16 bytes larger per tier than SLAB_TIERS_V1D.
+ * PR #1236 fixed postBitmap for new slabs (→2) but caused slab 6ZytbpV4 (65104 bytes,
+ * top active market ~$15k 24h vol) to be unrecognized → "Failed to load market". GH#1237.
+ *
+ * Sizes computed via computeSlabSize(ENGINE_OFF=424, BITMAP_OFF=624, ACCOUNT_SIZE=248, N, postBitmap=18):
+ *   micro  =  17,080  (64 slots)
+ *   small  =  65,104  (256 slots)  ← slab 6ZytbpV4 TEST/USD
+ *   medium = 257,200  (1,024 slots)
+ *   large  = 1,025,584 (4,096 slots)
+ */
+export declare const SLAB_TIERS_V1D_LEGACY: {
+    readonly micro: {
+        readonly maxAccounts: 64;
+        readonly dataSize: 17080;
+        readonly label: "Micro";
+        readonly description: "64 slots (V1D legacy, postBitmap=18)";
+    };
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 65104;
+        readonly label: "Small";
+        readonly description: "256 slots (V1D legacy, postBitmap=18)";
+    };
+    readonly medium: {
+        readonly maxAccounts: 1024;
+        readonly dataSize: 257200;
+        readonly label: "Medium";
+        readonly description: "1,024 slots (V1D legacy, postBitmap=18)";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 1025584;
+        readonly label: "Large";
+        readonly description: "4,096 slots (V1D legacy, postBitmap=18)";
+    };
+};
+/** @deprecated Alias — use SLAB_TIERS (already V1) */
+export declare const SLAB_TIERS_V1: {
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 65352;
+        readonly label: "Small";
+        readonly description: "256 slots · ~0.45 SOL";
+    };
+    readonly medium: {
+        readonly maxAccounts: 1024;
+        readonly dataSize: 257448;
+        readonly label: "Medium";
+        readonly description: "1,024 slots · ~1.79 SOL";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 1025832;
+        readonly label: "Large";
+        readonly description: "4,096 slots · ~7.14 SOL";
+    };
+};
+/**
+ * V_ADL slab tier sizes — PERC-8270/8271 ADL-upgraded program.
+ * ENGINE_OFF=624, BITMAP_OFF=1006, ACCOUNT_SIZE=312, postBitmap=18.
+ * New account layout adds ADL tracking fields (+64 bytes/account).
+ * BPF SLAB_LEN verified by cargo build-sbf in PERC-8271: large (4096) = 1288304 bytes.
+ */
+export declare const SLAB_TIERS_V_ADL_DISCOVERY: Record<string, {
+    maxAccounts: number;
+    dataSize: number;
+    label: string;
+    description: string;
+}>;
+export type SlabTierKey = keyof typeof SLAB_TIERS;
+/** Calculate slab data size for arbitrary account count.
+ *
+ * Layout (SBF, u128 align = 8):
+ *   HEADER(104) + CONFIG(536) → ENGINE_OFF = 640
+ *   RiskEngine fixed scalars: 656 bytes (PERC-299: +24 emergency OI, +32 long/short OI)
+ *   + bitmap: ceil(N/64)*8
+ *   + num_used_accounts(u16) + pad(6) + next_account_id(u64) + free_head(u16) = 18
+ *   + next_free: N*2
+ *   + pad to 8-byte alignment for Account array
+ *   + accounts: N*248
+ *
+ * Must match the on-chain program's SLAB_LEN exactly.
+ */
+export declare function slabDataSize(maxAccounts: number): number;
+/**
+ * Calculate slab data size for V1 layout (ENGINE_OFF=640).
+ *
+ * NOTE: This formula is accurate for small (256) and medium (1024) tiers but
+ * underestimates large (4096) by 16 bytes — likely due to a padding/alignment
+ * difference at high account counts or a post-PERC-118 struct addition in the
+ * deployed binary. Always prefer the hardcoded SLAB_TIERS values (empirically
+ * verified on-chain) over this formula for production use.
+ */
+export declare function slabDataSizeV1(maxAccounts: number): number;
+/**
+ * Validate that a slab data size matches one of the known tier sizes.
+ * Use this to catch tier↔program mismatches early (PERC-277).
+ *
+ * @param dataSize - The expected slab data size (from SLAB_TIERS[tier].dataSize)
+ * @param programSlabLen - The program's compiled SLAB_LEN (from on-chain error logs or program introspection)
+ * @returns true if sizes match, false if there's a mismatch
+ */
+export declare function validateSlabTierMatch(dataSize: number, programSlabLen: number): boolean;
+/** Options for `discoverMarkets`. */
+export interface DiscoverMarketsOptions {
+    /**
+     * Run tier queries sequentially with per-tier retry on HTTP 429 instead of
+     * firing all in parallel.  Reduces RPC rate-limit pressure at the cost of
+     * slightly slower discovery (~14 round-trips instead of 1 concurrent batch).
+     * Default: false (preserves original parallel behaviour).
+     *
+     * PERC-1650: keeper uses this flag to avoid 429 storms on its fallback RPC
+     * (Helius starter tier).  Pass `sequential: true` from CrankService.discover().
+     */
+    sequential?: boolean;
+    /**
+     * Delay in ms between sequential tier queries (only used when sequential=true).
+     * Default: 200 ms.
+     */
+    interTierDelayMs?: number;
+    /**
+     * Per-tier retry backoff delays on 429 (ms).  Jitter of up to +25% is applied.
+     * Only used when sequential=true.  Default: [1_000, 3_000, 9_000, 27_000].
+     */
+    rateLimitBackoffMs?: number[];
+    /**
+     * In parallel mode (the default), cap how many tier RPC requests are in-flight
+     * at once to avoid accidental RPC storms from client code.
+     *
+     * Default: 6
+     */
+    maxParallelTiers?: number;
+    /**
+     * Hard cap on how many tier dataSize queries are attempted.
+     * Default: all known tiers.
+     */
+    maxTierQueries?: number;
+}
+/**
+ * Discover all Percolator markets owned by the given program.
+ * Uses getProgramAccounts with dataSize filter + dataSlice to download only ~1400 bytes per slab.
+ *
+ * @param options.sequential - Run tier queries sequentially with 429 retry (PERC-1650).
+ */
+export declare function discoverMarkets(connection: Connection, programId: PublicKey, options?: DiscoverMarketsOptions): Promise<DiscoveredMarket[]>;

package/dist/solana/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./slab.js";
+export * from "./pda.js";
+export * from "./ata.js";
+export * from "./discovery.js";
+export * from "./dex-oracle.js";
+export * from "./oracle.js";
+export * from "./token-program.js";
+export * from "./stake.js";
+export * from "./adl.js";

package/dist/solana/oracle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Oracle account parsing utilities.
+ *
+ * Chainlink aggregator layout on Solana (from Toly's percolator-cli):
+ *   offset 138: decimals (u8)
+ *   offset 216: latest answer (i64 LE)
+ *
+ * Minimum account size: 224 bytes (offset 216 + 8 bytes for i64).
+ *
+ * These utilities validate oracle data BEFORE parsing to prevent silent
+ * propagation of stale or malformed Chainlink data as price.
+ */
+/** Minimum buffer size to read Chainlink price data */
+declare const CHAINLINK_MIN_SIZE = 224;
+/** Maximum reasonable decimals for a price feed */
+declare const MAX_DECIMALS = 18;
+/** Offset of decimals field in Chainlink aggregator account */
+declare const CHAINLINK_DECIMALS_OFFSET = 138;
+/** Offset of latest answer in Chainlink aggregator account */
+declare const CHAINLINK_ANSWER_OFFSET = 216;
+export interface OraclePrice {
+    price: bigint;
+    decimals: number;
+}
+/**
+ * Parse price data from a Chainlink aggregator account buffer.
+ *
+ * Validates:
+ * - Buffer is large enough to contain the required fields (≥ 224 bytes)
+ * - Decimals are in a reasonable range (0-18)
+ * - Price is positive (non-zero)
+ *
+ * @param data - Raw account data from Chainlink aggregator
+ * @returns Parsed oracle price with decimals
+ * @throws if the buffer is invalid or contains unreasonable data
+ */
+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_ANSWER_OFFSET, MAX_DECIMALS };

package/dist/solana/pda.d.ts

@@ -0,0 +1,54 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Derive vault authority PDA.
+ * Seeds: ["vault", slab_key]
+ */
+export declare function deriveVaultAuthority(programId: PublicKey, slab: PublicKey): [PublicKey, number];
+/**
+ * Derive insurance LP mint PDA.
+ * Seeds: ["ins_lp", slab_key]
+ */
+export declare function deriveInsuranceLpMint(programId: PublicKey, slab: PublicKey): [PublicKey, number];
+/**
+ * Derive LP PDA for TradeCpi.
+ * 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. */
+export declare const RAYDIUM_CLMM_PROGRAM_ID: PublicKey;
+/** Meteora DLMM (Dynamic Liquidity Market Maker) program ID. */
+export declare const METEORA_DLMM_PROGRAM_ID: PublicKey;
+/** Pyth Push Oracle program on mainnet. */
+export declare const PYTH_PUSH_ORACLE_PROGRAM_ID: PublicKey;
+/**
+ * Seed used to derive the creator lock PDA.
+ * Matches `creator_lock::CREATOR_LOCK_SEED` in percolator-prog.
+ */
+export declare const CREATOR_LOCK_SEED = "creator_lock";
+/**
+ * Derive the creator lock PDA for a given slab.
+ * Seeds: ["creator_lock", slab_key]
+ *
+ * This PDA is required as accounts[9] in every LpVaultWithdraw instruction
+ * since percolator-prog PR#170 (GH#1926 / PERC-8287).
+ * Non-creator withdrawers must pass this key; if no lock exists on-chain the
+ * enforcement is a no-op. The SDK must ALWAYS include it — passing it is mandatory.
+ *
+ * @param programId - The percolator program ID.
+ * @param slab      - The slab (market) public key.
+ * @returns [pda, bump]
+ *
+ * @example
+ * ```ts
+ * const [creatorLockPda] = deriveCreatorLockPda(PROGRAM_ID, slabKey);
+ * ```
+ */
+export declare function deriveCreatorLockPda(programId: PublicKey, slab: PublicKey): [PublicKey, number];
+export declare function derivePythPushOraclePDA(feedIdHex: string): [PublicKey, number];

package/dist/solana/slab.d.ts

@@ -0,0 +1,316 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+/**
+ * Full slab layout descriptor. Returned by detectSlabLayout().
+ * All engine field offsets are relative to engineOff.
+ */
+export interface SlabLayout {
+    version: 0 | 1 | 2;
+    headerLen: number;
+    configOffset: number;
+    configLen: number;
+    reservedOff: number;
+    engineOff: number;
+    accountSize: number;
+    maxAccounts: number;
+    bitmapWords: number;
+    accountsOff: number;
+    engineInsuranceOff: number;
+    engineParamsOff: number;
+    paramsSize: number;
+    engineCurrentSlotOff: number;
+    engineFundingIndexOff: number;
+    engineLastFundingSlotOff: number;
+    engineFundingRateBpsOff: number;
+    engineMarkPriceOff: number;
+    engineLastCrankSlotOff: number;
+    engineMaxCrankStalenessOff: number;
+    engineTotalOiOff: number;
+    engineLongOiOff: number;
+    engineShortOiOff: number;
+    engineCTotOff: number;
+    enginePnlPosTotOff: number;
+    engineLiqCursorOff: number;
+    engineGcCursorOff: number;
+    engineLastSweepStartOff: number;
+    engineLastSweepCompleteOff: number;
+    engineCrankCursorOff: number;
+    engineSweepStartIdxOff: number;
+    engineLifetimeLiquidationsOff: number;
+    engineLifetimeForceClosesOff: number;
+    engineNetLpPosOff: number;
+    engineLpSumAbsOff: number;
+    engineLpMaxAbsOff: number;
+    engineLpMaxAbsSweepOff: number;
+    engineEmergencyOiModeOff: number;
+    engineEmergencyStartSlotOff: number;
+    engineLastBreakerSlotOff: number;
+    engineBitmapOff: number;
+    postBitmap: number;
+    acctOwnerOff: number;
+    hasInsuranceIsolation: boolean;
+    engineInsuranceIsolatedOff: number;
+    engineInsuranceIsolationBpsOff: number;
+}
+export declare const ENGINE_OFF = 600;
+export declare const ENGINE_MARK_PRICE_OFF = 400;
+/**
+ * V2 slab tier sizes (small and large) for discovery.
+ * V2 uses ENGINE_OFF=600, BITMAP_OFF=432, ACCOUNT_SIZE=248, postBitmap=18.
+ * Sizes overlap with V1D (postBitmap=2) — disambiguation requires reading the version field.
+ */
+export declare const SLAB_TIERS_V2: {
+    readonly small: {
+        readonly maxAccounts: 256;
+        readonly dataSize: 65088;
+        readonly label: "Small";
+        readonly description: "256 slots (V2 BPF intermediate)";
+    };
+    readonly large: {
+        readonly maxAccounts: 4096;
+        readonly dataSize: 1025568;
+        readonly label: "Large";
+        readonly description: "4,096 slots (V2 BPF intermediate)";
+    };
+};
+/**
+ * V1M slab tier sizes — mainnet-deployed V1 program (ESa89R5).
+ * ENGINE_OFF=640, BITMAP_OFF=726, ACCOUNT_SIZE=248, postBitmap=18.
+ * Expanded RiskParams (336 bytes) and trade_twap runtime fields.
+ * Confirmed by on-chain probing of slab 8NY7rvQ (SOL/USDC Perpetual, 257512 bytes).
+ */
+export declare const SLAB_TIERS_V1M: Record<string, {
+    maxAccounts: number;
+    dataSize: number;
+    label: string;
+    description: string;
+}>;
+/**
+ * V_ADL slab tier sizes — PERC-8270/8271 ADL-upgraded program.
+ * ENGINE_OFF=624, BITMAP_OFF=1006, ACCOUNT_SIZE=312, postBitmap=18.
+ * New account layout adds ADL tracking fields (+64 bytes/account including alignment padding).
+ * BPF SLAB_LEN verified by cargo build-sbf in PERC-8271: large (4096) = 1288304 bytes.
+ */
+export declare const SLAB_TIERS_V_ADL: 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 V_ADL, V1M, V0, V1D, V1D-legacy, V1, and V1-legacy sizes in priority order.
+ *
+ * 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).
+ * V2 slabs have version===2 at offset 8 (u32 LE).
+ *
+ * @param dataLen - The slab account data length in bytes
+ * @param data    - Optional raw slab data for version-field disambiguation
+ */
+export declare function detectSlabLayout(dataLen: number, data?: Uint8Array): SlabLayout | null;
+/**
+ * Legacy detectLayout for backward compat.
+ * Returns { bitmapWords, accountsOff, maxAccounts } or null.
+ *
+ * GH#1238: previously recomputed accountsOff with hardcoded postBitmap=18, which gave a value
+ * 16 bytes too large for V1D slabs (which use postBitmap=2). Now delegates directly to the
+ * SlabLayout descriptor so each variant uses its own correct accountsOff.
+ */
+export declare function detectLayout(dataLen: number): {
+    bitmapWords: number;
+    accountsOff: number;
+    maxAccounts: number;
+} | null;
+export interface SlabHeader {
+    magic: bigint;
+    version: number;
+    bump: number;
+    flags: number;
+    resolved: boolean;
+    paused: boolean;
+    admin: PublicKey;
+    nonce: bigint;
+    lastThrUpdateSlot: bigint;
+}
+export interface MarketConfig {
+    collateralMint: PublicKey;
+    vaultPubkey: PublicKey;
+    indexFeedId: PublicKey;
+    maxStalenessSlots: bigint;
+    confFilterBps: number;
+    vaultAuthorityBump: number;
+    invert: number;
+    unitScale: number;
+    fundingHorizonSlots: bigint;
+    fundingKBps: bigint;
+    fundingInvScaleNotionalE6: bigint;
+    fundingMaxPremiumBps: bigint;
+    fundingMaxBpsPerSlot: bigint;
+    fundingPremiumWeightBps: bigint;
+    fundingSettlementIntervalSlots: bigint;
+    fundingPremiumDampeningE6: bigint;
+    fundingPremiumMaxBpsPerSlot: bigint;
+    threshFloor: bigint;
+    threshRiskBps: bigint;
+    threshUpdateIntervalSlots: bigint;
+    threshStepBps: bigint;
+    threshAlphaBps: bigint;
+    threshMin: bigint;
+    threshMax: bigint;
+    threshMinStep: bigint;
+    oracleAuthority: PublicKey;
+    authorityPriceE6: bigint;
+    authorityTimestamp: bigint;
+    oraclePriceCapE2bps: bigint;
+    lastEffectivePriceE6: bigint;
+    oiCapMultiplierBps: bigint;
+    maxPnlCap: bigint;
+    adaptiveFundingEnabled: boolean;
+    adaptiveScaleBps: number;
+    adaptiveMaxFundingBps: bigint;
+    marketCreatedSlot: bigint;
+    oiRampSlots: bigint;
+    resolvedSlot: bigint;
+    insuranceIsolationBps: number;
+    /** PERC-622: Oracle phase (0=Nascent, 1=Growing, 2=Mature) */
+    oraclePhase: number;
+    /** PERC-622: Cumulative trade volume in e6 format */
+    cumulativeVolumeE6: bigint;
+    /** PERC-622: Slots elapsed from market creation to Phase 2 entry (u24) */
+    phase2DeltaSlots: number;
+}
+export interface InsuranceFund {
+    balance: bigint;
+    feeRevenue: bigint;
+    isolatedBalance: bigint;
+    isolationBps: number;
+}
+export interface RiskParams {
+    warmupPeriodSlots: bigint;
+    maintenanceMarginBps: bigint;
+    initialMarginBps: bigint;
+    tradingFeeBps: bigint;
+    maxAccounts: bigint;
+    newAccountFee: bigint;
+    riskReductionThreshold: bigint;
+    maintenanceFeePerSlot: bigint;
+    maxCrankStalenessSlots: bigint;
+    liquidationFeeBps: bigint;
+    liquidationFeeCap: bigint;
+    liquidationBufferBps: bigint;
+    minLiquidationAbs: bigint;
+}
+export interface EngineState {
+    vault: bigint;
+    insuranceFund: InsuranceFund;
+    currentSlot: bigint;
+    fundingIndexQpbE6: bigint;
+    lastFundingSlot: bigint;
+    fundingRateBpsPerSlotLast: bigint;
+    lastCrankSlot: bigint;
+    maxCrankStalenessSlots: bigint;
+    totalOpenInterest: bigint;
+    longOi: bigint;
+    shortOi: bigint;
+    cTot: bigint;
+    pnlPosTot: bigint;
+    liqCursor: number;
+    gcCursor: number;
+    lastSweepStartSlot: bigint;
+    lastSweepCompleteSlot: bigint;
+    crankCursor: number;
+    sweepStartIdx: number;
+    lifetimeLiquidations: bigint;
+    lifetimeForceCloses: bigint;
+    netLpPos: bigint;
+    lpSumAbs: bigint;
+    lpMaxAbs: bigint;
+    lpMaxAbsSweep: bigint;
+    emergencyOiMode: boolean;
+    emergencyStartSlot: bigint;
+    lastBreakerSlot: bigint;
+    numUsedAccounts: number;
+    nextAccountId: bigint;
+    markPriceE6: bigint;
+}
+export declare enum AccountKind {
+    User = 0,
+    LP = 1
+}
+export interface Account {
+    kind: AccountKind;
+    accountId: bigint;
+    capital: bigint;
+    pnl: bigint;
+    reservedPnl: bigint;
+    warmupStartedAtSlot: bigint;
+    warmupSlopePerStep: bigint;
+    positionSize: bigint;
+    entryPrice: bigint;
+    fundingIndex: bigint;
+    matcherProgram: PublicKey;
+    matcherContext: PublicKey;
+    owner: PublicKey;
+    feeCredits: bigint;
+    lastFeeSlot: bigint;
+}
+export declare function fetchSlab(connection: Connection, slabPubkey: PublicKey): Promise<Uint8Array>;
+export declare const RAMP_START_BPS = 1000n;
+export declare const DEFAULT_OI_RAMP_SLOTS = 432000n;
+export declare function computeEffectiveOiCapBps(config: MarketConfig, currentSlot: bigint): bigint;
+export declare function readNonce(data: Uint8Array): bigint;
+export declare function readLastThrUpdateSlot(data: Uint8Array): bigint;
+/**
+ * Parse slab header (first 72 bytes — layout-independent).
+ */
+export declare function parseHeader(data: Uint8Array): SlabHeader;
+/**
+ * Parse market config. Layout-version aware.
+ * For V0 slabs, fields beyond the basic config are read if present in the data,
+ * otherwise defaults are returned.
+ *
+ * @param data - Slab data (may be a partial slice for discovery; pass layoutHint in that case)
+ * @param layoutHint - Pre-detected layout to use; if omitted, detected from data.length.
+ */
+export declare function parseConfig(data: Uint8Array, layoutHint?: SlabLayout | null): MarketConfig;
+/**
+ * Parse RiskParams from engine data. Layout-version aware.
+ * For V0 slabs, extended params (risk_threshold, maintenance_fee, etc.) are
+ * not present on-chain, so defaults (0) are returned.
+ *
+ * @param data - Slab data (may be a partial slice; pass layoutHint in that case)
+ * @param layoutHint - Pre-detected layout to use; if omitted, detected from data.length.
+ */
+export declare function parseParams(data: Uint8Array, layoutHint?: SlabLayout | null): RiskParams;
+/**
+ * Parse RiskEngine state (excluding accounts array). Layout-version aware.
+ */
+export declare function parseEngine(data: Uint8Array): EngineState;
+/**
+ * Read bitmap to get list of used account indices.
+ */
+/**
+ * Return all account indices whose bitmap bit is set (i.e. slot is in use).
+ * Uses the layout-aware bitmap offset so V1_LEGACY slabs (bitmap at rel+672) are handled correctly.
+ */
+export declare function parseUsedIndices(data: Uint8Array): number[];
+/**
+ * Check if a specific account index is used.
+ */
+export declare function isAccountUsed(data: Uint8Array, idx: number): boolean;
+/**
+ * Calculate the maximum valid account index for a given slab size.
+ */
+export declare function maxAccountIndex(dataLen: number): number;
+/**
+ * Parse a single account by index.
+ */
+export declare function parseAccount(data: Uint8Array, idx: number): Account;
+/**
+ * Parse all used accounts.
+ */
+export declare function parseAllAccounts(data: Uint8Array): {
+    idx: number;
+    account: Account;
+}[];