@percolatorct/sdk 0.5.0 → 1.0.0-beta.1

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for building clients, bots, and UIs on top of the [Percolator](https://github.com/dcccrypto/percolator) perpetual futures protocol on Solana.
 
-> **⚠️ RELEASE CANDIDATE** — `1.0.0-rc.1`. Security audit (0x-SquidSol) complete. Pending final mainnet program verification before `1.0.0` stable. Use at your own risk.
+> **⚠️ BETA** — `1.0.0-beta.1`. Security audit (0x-SquidSol) complete. All 709 tests passing. Pending Helius API key + mainnet market deployment before `1.0.0` stable.
 
 [![npm](https://img.shields.io/npm/v/@percolator/sdk?color=14F195)](https://www.npmjs.com/package/@percolator/sdk)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -27,10 +27,13 @@ npm install @percolator/sdk
 import {
   getProgramId,
   deriveVaultAuthority,
-  buildInitUserIxData,
-  buildDepositCollateralIxData,
-  buildTradeNoCpiIxData,
-  parseSlab,
+  encodeInitUser,
+  encodeDepositCollateral,
+  encodeTradeNoCpi,
+  parseHeader,
+  parseConfig,
+  parseAllAccounts,
+  detectSlabLayout,
   computeMarkPnl,
   computeLiqPrice,
   simulateOrSend,
@@ -43,8 +46,12 @@ const programId = getProgramId("devnet");
 const [vaultAuth, bump] = deriveVaultAuthority(programId, slabPubkey);
 
 // Read and parse on-chain slab account
-const slabData = await connection.getAccountInfo(slabPubkey);
-const { header, config, accounts } = parseSlab(slabData.data);
+const slabInfo = await connection.getAccountInfo(slabPubkey);
+const slabData = new Uint8Array(slabInfo!.data);
+const header = parseHeader(slabData);
+const layout = detectSlabLayout(slabData.length);
+const config = parseConfig(slabData, layout!);
+const accounts = parseAllAccounts(slabData);
 
 // Compute PnL for a position
 const pnl = computeMarkPnl(positionSize, entryPrice, oraclePrice);
@@ -153,9 +160,18 @@ See [`examples/admin-instructions.ts`](examples/admin-instructions.ts) for full
 Parse the on-chain slab account into typed TypeScript objects:
 
 ```typescript
-import { parseSlab, parseSlabHeader, parseMarketConfig } from "@percolator/sdk";
+import {
+  parseHeader,
+  parseConfig,
+  parseAllAccounts,
+  detectSlabLayout,
+} from "@percolator/sdk";
 
-const { header, config, accounts } = parseSlab(accountData);
+const slabData = new Uint8Array(accountInfo.data);
+const header = parseHeader(slabData);
+const layout = detectSlabLayout(slabData.length)!;
+const config = parseConfig(slabData, layout);
+const accounts = parseAllAccounts(slabData);
 
 // header.magic, header.version, header.admin, header.nonce
 // header.resolved, header.paused
@@ -165,7 +181,8 @@ const { header, config, accounts } = parseSlab(accountData);
 // config.fundingHorizonSlots, config.fundingKBps
 // config.threshFloor, config.threshRiskBps
 
-// accounts[i].owner, accounts[i].capital, accounts[i].pnl, accounts[i].positionSize
+// accounts[i].account.owner, accounts[i].account.capital,
+// accounts[i].account.pnl, accounts[i].account.positionSize
 ```
 
 ### PDA Derivation
@@ -312,7 +329,7 @@ const event = parseAdlEvent(tx?.meta?.logMessages ?? []);
 import { fetchAdlRankings } from "@percolator/sdk";
 
 const result = await fetchAdlRankings(
-  "https://api.percolatorlaunch.com",
+  "https://percolatorlaunch.com/api",
   slabAddress,
 );
 // result.slabAddress              — slab public key (base58)
@@ -338,8 +355,8 @@ const result = await fetchAdlRankings(
 
 | Code | Name | Description |
 |------|------|-------------|
-| 61 | `EngineSideBlocked` | ADL blocked — dominant side already at cap |
-| 62 | `EngineCorruptState` | Slab state corrupt — contact support |
+| 61 | `EngineSideBlocked` | Trade blocked — this side is in DrainOnly or ResetPending mode |
+| 62 | `EngineCorruptState` | Slab state corrupt — critical internal error, please report |
 | 63 | `InsuranceFundNotDepleted` | ADL not triggered yet (insurance fund healthy) |
 | 64 | `NoAdlCandidates` | No eligible positions to deleverage |
 | 65 | `BankruptPositionAlreadyClosed` | Target position already closed |
@@ -372,12 +389,22 @@ const result = await simulateOrSend({
 Validate parameters before submitting transactions:
 
 ```typescript
-import { validateRiskParams, validateTradeParams } from "@percolator/sdk";
+import {
+  validatePublicKey,
+  validateAmount,
+  validateBps,
+  validateI128,
+  validateIndex,
+} from "@percolator/sdk";
 
-const errors = validateRiskParams(params);
-if (errors.length > 0) {
-  console.error("Invalid risk params:", errors);
-}
+// Validates a public key string (throws ValidationError on invalid input)
+const slabKey = validatePublicKey(slabAddress, "slab");
+
+// Validates a u64 amount (throws ValidationError if negative or > u64 max)
+const amount = validateAmount("1000000000", "depositAmount");
+
+// Validates basis points (0-10000)
+const feeBps = validateBps("50", "tradingFee");
 ```
 
 ---
@@ -407,14 +434,82 @@ const markets = await discoverMarkets(connection);
 
 | Program | Network | Address |
 |---------|---------|---------|
-| Percolator | Mainnet | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` |
-| Matcher | Mainnet | see `getMatcherProgramId("mainnet")` |
+| Percolator | Mainnet | `GM8zjJ8LTBMv9xEsverh6H6wLyevgMHEJXcEzyY3rY24` |
+| Matcher | Mainnet | `DHP6DtwXP1yJsz8YzfoeigRFPB979gzmumkmCxDLSkUX` |
 | Percolator | Devnet | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` |
+| Matcher | Devnet | `GTRgyTDfrMvBubALAqtHuQwT8tbGyXid7svXZKtWfC9k` |
 
 > Use `PROGRAM_ID` / `MATCHER_PROGRAM_ID` env vars to override for local test validators.
 
 ---
 
+## RPC Connection Pool, Retry, and Health Probes
+
+The SDK provides a production-grade RPC connection pool with automatic retry,
+failover, and health probing. Use `RpcPool` for mainnet reliability.
+
+### RpcPool — Multi-endpoint with failover/round-robin
+
+```typescript
+import { RpcPool } from "@percolator/sdk";
+
+const pool = new RpcPool({
+  endpoints: [
+    { url: "https://mainnet.helius-rpc.com/?api-key=KEY", weight: 10, label: "helius" },
+    { url: "https://api.mainnet-beta.solana.com", weight: 1, label: "public" },
+  ],
+  strategy: "failover",   // or "round-robin"
+  retry: {
+    maxRetries: 3,         // default: 3
+    baseDelayMs: 500,      // default: 500 (exponential backoff)
+    maxDelayMs: 10_000,    // default: 10s cap
+    jitterFactor: 0.25,    // default: 0.25 (avoid thundering herd)
+  },
+  requestTimeoutMs: 30_000, // default: 30s per request
+  commitment: "confirmed",  // default: confirmed
+});
+
+// Execute any async call through the pool — auto-retry + failover
+const slot = await pool.call(conn => conn.getSlot());
+const balance = await pool.call(conn => conn.getBalance(pubkey));
+
+// Use with discoverMarkets
+const markets = await pool.call(conn =>
+  discoverMarkets(conn, programId, { apiBaseUrl: "https://percolatorlaunch.com/api" })
+);
+
+// Pool status & diagnostics
+console.log(pool.status()); // [{ label, url, healthy, failures, lastLatencyMs }]
+console.log(`${pool.healthyCount}/${pool.size} endpoints healthy`);
+```
+
+### Standalone retry wrapper
+
+```typescript
+import { withRetry } from "@percolator/sdk";
+import { Connection } from "@solana/web3.js";
+
+const conn = new Connection("https://api.mainnet-beta.solana.com");
+const slot = await withRetry(
+  () => conn.getSlot(),
+  { maxRetries: 3, baseDelayMs: 1000 },
+);
+```
+
+### RPC health probes
+
+```typescript
+import { checkRpcHealth } from "@percolator/sdk";
+
+const health = await checkRpcHealth("https://api.mainnet-beta.solana.com", 5000);
+console.log(`${health.endpoint}: ${health.healthy ? "UP" : "DOWN"} — ${health.latencyMs}ms, slot ${health.slot}`);
+
+// Or check all pool endpoints at once
+const results = await pool.healthCheck();
+```
+
+---
+
 ## RPC Concurrency
 
 `discoverMarkets()` fires one `getProgramAccounts` request per known slab tier size.
@@ -438,8 +533,113 @@ const marketsCustom = await discoverMarkets(connection, { maxParallelTiers: 3 })
 ```
 
 > **Note:** Public mainnet-beta RPC (`api.mainnet-beta.solana.com`) rejects
-> `getProgramAccounts` calls entirely. A Helius or QuickNode endpoint is required for
-> `discoverMarkets()` in production.
+> `getProgramAccounts` calls entirely. Use the **API fallback** (below) or a
+> Helius/QuickNode endpoint.
+
+## Market Discovery — 3-Tier Fallback Chain
+
+Public mainnet RPCs reject `getProgramAccounts`, which blocks `discoverMarkets()`.
+The SDK provides a resilient 3-tier fallback chain that works on any RPC endpoint:
+
+| Tier | Method | Requires |
+|------|--------|----------|
+| 1 | `getProgramAccounts` (RPC) | Helius/premium RPC key |
+| 2 | REST API (`GET /markets`) | Percolator API online |
+| 3 | Static bundle (bundled addresses) | Nothing — works offline |
+
+All tiers verify data on-chain via `getMultipleAccounts` (works on all RPCs).
+
+### Recommended: Full 3-tier fallback
+
+Pass both `apiBaseUrl` and `network` to enable all three tiers:
+
+```typescript
+import { discoverMarkets, getProgramId } from "@percolator/sdk";
+import { Connection } from "@solana/web3.js";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const markets = await discoverMarkets(connection, getProgramId("mainnet"), {
+  apiBaseUrl: "https://percolatorlaunch.com/api",
+  network: "mainnet",  // enables tier-3 static fallback
+});
+```
+
+### API-only discovery via `discoverMarketsViaApi()`
+
+Skip `getProgramAccounts` entirely — query the REST API for slab addresses,
+then fetch full on-chain data:
+
+```typescript
+import { discoverMarketsViaApi, getProgramId } from "@percolator/sdk";
+import { Connection } from "@solana/web3.js";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const programId = getProgramId("mainnet");
+const markets = await discoverMarketsViaApi(
+  connection,
+  programId,
+  "https://percolatorlaunch.com/api",
+);
+```
+
+### Static-only discovery via `discoverMarketsViaStaticBundle()`
+
+Use the bundled address list directly (no network calls except `getMultipleAccounts`):
+
+```typescript
+import {
+  discoverMarketsViaStaticBundle,
+  getStaticMarkets,
+  getProgramId,
+} from "@percolator/sdk";
+import { Connection } from "@solana/web3.js";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const entries = getStaticMarkets("mainnet");
+const markets = await discoverMarketsViaStaticBundle(
+  connection,
+  getProgramId("mainnet"),
+  entries,
+);
+```
+
+### Extending the static registry at runtime
+
+The static bundle can be augmented before calling `discoverMarkets()`:
+
+```typescript
+import { registerStaticMarkets, discoverMarkets, getProgramId } from "@percolator/sdk";
+import { Connection } from "@solana/web3.js";
+
+// Register known slab addresses before discovery
+registerStaticMarkets("mainnet", [
+  { slabAddress: "ABC123...", symbol: "SOL-PERP" },
+  { slabAddress: "DEF456...", symbol: "ETH-PERP" },
+]);
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const markets = await discoverMarkets(connection, getProgramId("mainnet"), {
+  apiBaseUrl: "https://percolatorlaunch.com/api",
+  network: "mainnet",
+});
+```
+
+### Known addresses via `getMarketsByAddress()`
+
+If you already know your market slab addresses (e.g. from an indexer or
+hardcoded list), fetch them directly:
+
+```typescript
+import { getMarketsByAddress, getProgramId } from "@percolator/sdk";
+import { Connection, PublicKey } from "@solana/web3.js";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const markets = await getMarketsByAddress(
+  connection,
+  getProgramId("mainnet"),
+  [new PublicKey("..."), new PublicKey("...")],
+);
+```
 
 ---
 
@@ -448,7 +648,7 @@ const marketsCustom = await discoverMarkets(connection, { maxParallelTiers: 3 })
 ```
 @percolator/sdk
 ├── abi/                 # Binary encoding/decoding matching on-chain layout
-│   ├── instructions.ts  # Instruction data builders (all 28+ instructions)
+│   ├── instructions.ts  # Instruction data builders (all 72 instructions)
 │   ├── accounts.ts      # Account struct deserialization
 │   ├── encode.ts        # Low-level binary encoding (u8/u16/u32/u64/i128/pubkey)
 │   ├── errors.ts        # On-chain error code → human-readable parsing
@@ -457,6 +657,7 @@ const marketsCustom = await discoverMarkets(connection, { maxParallelTiers: 3 })
 │   ├── slab.ts          # Slab account parser (header + config + accounts)
 │   ├── pda.ts           # PDA derivation (vault, LP, insurance mint)
 │   ├── discovery.ts     # Market discovery (find all Percolator markets)
+│   ├── rpc-pool.ts      # RPC connection pool, retry, failover, health probes
 │   ├── dex-oracle.ts    # DEX oracle price integration
 │   ├── token-program.ts # SPL Token helpers
 │   ├── ata.ts           # Associated Token Account helpers

package/dist/abi/accounts.d.ts

@@ -249,6 +249,13 @@ export declare const ACCOUNTS_CLEAR_PENDING_SETTLEMENT: readonly AccountSpec[];
  * Sets the per-wallet position cap (admin only). capE6=0 disables.
  */
 export declare const ACCOUNTS_SET_WALLET_CAP: readonly AccountSpec[];
+/**
+ * InitMatcherCtx: 5 accounts
+ * Admin CPI-initializes the matcher context account for an LP slot.
+ * The LP PDA signs via invoke_signed in the program — it must be included in
+ * the transaction's account list even though it carries 0 lamports.
+ */
+export declare const ACCOUNTS_INIT_MATCHER_CTX: readonly AccountSpec[];
 export declare const WELL_KNOWN: {
     readonly tokenProgram: PublicKey;
     readonly clock: PublicKey;

package/dist/abi/errors.d.ts

@@ -19,16 +19,27 @@ export declare function getErrorName(code: number): string;
  * Get actionable hint for error code.
  */
 export declare function getErrorHint(code: number): string | undefined;
+/**
+ * Check whether an error code is in the Anchor framework error range
+ * (used by Lighthouse, not Percolator).
+ */
+export declare function isAnchorErrorCode(code: number): boolean;
 /**
  * Parse error from transaction logs.
  * Looks for "Program ... failed: custom program error: 0x..."
  *
  * Hex capture is bounded (1–8 digits) so pathological logs cannot feed unbounded
  * strings into `parseInt` or produce precision-loss codes above u32.
+ *
+ * Distinguishes between:
+ * - Percolator program errors (codes 0–65): returns Percolator error info
+ * - Anchor/Lighthouse errors (codes 0x1770–0x1FFF): returns Lighthouse-specific
+ *   name and hint so callers can handle wallet middleware failures
  */
 export declare function parseErrorFromLogs(logs: string[]): {
     code: number;
     name: string;
     hint?: string;
+    source?: "percolator" | "lighthouse" | "unknown";
 } | null;
 export {};

package/dist/abi/instructions.d.ts

@@ -1,4 +1,9 @@
 import { PublicKey } from "@solana/web3.js";
+/**
+ * Oracle price constraints.
+ * Maximum oracle price that can be pushed to the on-chain oracle authority.
+ */
+export declare const MAX_ORACLE_PRICE = 1000000000000n;
 /**
  * Instruction tags - exact match to Rust ix::Instruction::decode
  */
@@ -106,6 +111,14 @@ export declare const IX_TAG: {
     readonly SetWalletCap: 70;
     /** PERC-8110: Set OI imbalance hard-block threshold (admin only). */
     readonly SetOiImbalanceHardBlock: 71;
+    /** PERC-8270: Rescue orphan vault — recover tokens from a closed market's vault (admin). */
+    readonly RescueOrphanVault: 72;
+    /** PERC-8270: Close orphan slab — reclaim rent from a slab whose market closed unexpectedly (admin). */
+    readonly CloseOrphanSlab: 73;
+    /** PERC-SetDexPool: Pin admin-approved DEX pool address for a HYPERP market (admin). */
+    readonly SetDexPool: 74;
+    /** CPI to the matcher program to initialize a matcher context account for an LP slot. Admin-only. */
+    readonly InitMatcherCtx: 75;
 };
 /**
  * InitMarket instruction data (256 bytes total)
@@ -297,6 +310,17 @@ export interface PushOraclePriceArgs {
     priceE6: bigint | string;
     timestamp: bigint | string;
 }
+/**
+ * Encode PushOraclePrice instruction data with validation.
+ *
+ * Validates oracle price constraints:
+ * - Price cannot be zero (division by zero in on-chain engine)
+ * - Price cannot exceed MAX_ORACLE_PRICE (prevents overflow in price math)
+ *
+ * @param args - PushOraclePrice arguments
+ * @returns Encoded instruction data (17 bytes)
+ * @throws Error if price is 0 or exceeds MAX_ORACLE_PRICE
+ */
 export declare function encodePushOraclePrice(args: PushOraclePriceArgs): Uint8Array;
 /**
  * SetOraclePriceCap instruction data (9 bytes)
@@ -988,3 +1012,47 @@ export interface SetWalletCapArgs {
     capE6: bigint | string;
 }
 export declare function encodeSetWalletCap(args: SetWalletCapArgs): Uint8Array;
+/**
+ * InitMatcherCtx (Tag 75) — admin initializes the matcher context account for an LP slot.
+ *
+ * The matcher program (DHP6DtwXP1yJsz8YzfoeigRFPB979gzmumkmCxDLSkUX) requires its context
+ * account to be initialized before TradeCpi can work. Only the percolator program can sign
+ * as the LP PDA via invoke_signed, so this instruction acts as the trusted initializer.
+ *
+ * Instruction data layout: tag(1) + lp_idx(2) + kind(1) + trading_fee_bps(4) +
+ *   base_spread_bps(4) + max_total_bps(4) + impact_k_bps(4) +
+ *   liquidity_notional_e6(16) + max_fill_abs(16) + max_inventory_abs(16) +
+ *   fee_to_insurance_bps(2) + skew_spread_mult_bps(2) = 72 bytes
+ *
+ * Accounts:
+ *   0. [signer]   admin
+ *   1. []         slab (program-owned; used to verify admin + LP slot)
+ *   2. [writable] matcherCtx (must match LP's stored matcher_context)
+ *   3. []         matcherProg (executable; must match LP's stored matcher_program)
+ *   4. []         lpPda (PDA ["lp", slab, lp_idx]; required by CPI as signer)
+ */
+export interface InitMatcherCtxArgs {
+    /** LP account index in the engine (0-based). */
+    lpIdx: number;
+    /** Matcher kind: 0=Passive, 1=vAMM. */
+    kind: number;
+    /** Base trading fee in bps (e.g. 30 = 0.30%). */
+    tradingFeeBps: number;
+    /** Base spread in bps. */
+    baseSpreadBps: number;
+    /** Max total spread in bps. */
+    maxTotalBps: number;
+    /** vAMM impact constant in bps (0 for passive matchers). */
+    impactKBps: number;
+    /** Liquidity notional in e6 units (0 for passive matchers). */
+    liquidityNotionalE6: bigint | string;
+    /** Max single fill size in absolute units (u128::MAX = no limit). */
+    maxFillAbs: bigint | string;
+    /** Max inventory size in absolute units (u128::MAX = no limit). */
+    maxInventoryAbs: bigint | string;
+    /** Fraction of fees routed to insurance fund in bps. */
+    feeToInsuranceBps: number;
+    /** Skew spread multiplier in bps (0 = disabled). */
+    skewSpreadMultBps: number;
+}
+export declare function encodeInitMatcherCtx(args: InitMatcherCtxArgs): Uint8Array;