@percolatorct/sdk 0.3.1 → 0.5.0

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.
 
-> **⚠️ DISCLAIMER: FOR EDUCATIONAL PURPOSES ONLY** — This code has NOT been audited. Do NOT use in production or with real funds.
+> **⚠️ 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.
 
 [![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)
@@ -382,6 +382,67 @@ if (errors.length > 0) {
 
 ---
 
+## Mainnet vs Devnet
+
+By default the SDK targets **devnet** (safety default — PERC-697). The `NETWORK` environment
+variable and the `network` parameter to `getProgramId()` / `discoverMarkets()` control which
+program IDs and RPC endpoints are used. Production deployments always set `NETWORK=mainnet`
+explicitly via Railway env vars.
+
+```typescript
+import { getProgramId, discoverMarkets } from "@percolator/sdk";
+
+// Devnet (default — safe fallback)
+const programId = getProgramId("devnet");
+
+// Mainnet — set env or pass explicitly
+// NETWORK=mainnet
+const mainnetProgramId = getProgramId("mainnet");
+
+// Market discovery — uses network from NETWORK env by default
+const markets = await discoverMarkets(connection);
+```
+
+### Program Addresses
+
+| Program | Network | Address |
+|---------|---------|---------|
+| Percolator | Mainnet | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` |
+| Matcher | Mainnet | see `getMatcherProgramId("mainnet")` |
+| Percolator | Devnet | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` |
+
+> Use `PROGRAM_ID` / `MATCHER_PROGRAM_ID` env vars to override for local test validators.
+
+---
+
+## RPC Concurrency
+
+`discoverMarkets()` fires one `getProgramAccounts` request per known slab tier size.
+There are ~15 known tier sizes. To avoid hitting rate limits on public or free-tier endpoints,
+the SDK caps parallel in-flight requests at **6** by default.
+
+For production use a [Helius](https://helius.dev) paid-tier key. On the free tier,
+pass `sequential: true` to serialize requests with exponential backoff:
+
+```typescript
+import { discoverMarkets } from "@percolator/sdk";
+
+// Helius paid tier — parallel (default, fast)
+const markets = await discoverMarkets(connection, { maxParallelTiers: 6 });
+
+// Free-tier or public RPC — sequential with 429 backoff
+const marketsSafe = await discoverMarkets(connection, { sequential: true });
+
+// Custom concurrency
+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.
+
+---
+
 ## Architecture
 
 ```

package/dist/index.js

@@ -1457,39 +1457,51 @@ var V_ADL_ACCT_MATCHER_CONTEXT_OFF = 160;
 var V_ADL_ACCT_OWNER_OFF = 192;
 var V_ADL_ACCT_FEE_CREDITS_OFF = 224;
 var V_ADL_ACCT_LAST_FEE_SLOT_OFF = 240;
-var V1M_ENGINE_OFF = 632;
-var V1M_CONFIG_LEN = 528;
+var V1M_ENGINE_OFF = 640;
+var V1M_CONFIG_LEN = 536;
 var V1M_ACCOUNT_SIZE = 248;
-var V1M_ENGINE_PARAMS_OFF = 80;
+var V1M2_ENGINE_OFF = 616;
+var V1M2_CONFIG_LEN = 512;
+var V1M_ENGINE_PARAMS_OFF = 72;
 var V1M_PARAMS_SIZE = 336;
-var V1M_ENGINE_CURRENT_SLOT_OFF = 416;
-var V1M_ENGINE_FUNDING_INDEX_OFF = 424;
-var V1M_ENGINE_LAST_FUNDING_SLOT_OFF = 440;
-var V1M_ENGINE_FUNDING_RATE_BPS_OFF = 448;
-var V1M_ENGINE_MARK_PRICE_OFF = 456;
-var V1M_ENGINE_LAST_CRANK_SLOT_OFF = 480;
-var V1M_ENGINE_MAX_CRANK_STALENESS_OFF = 488;
-var V1M_ENGINE_TOTAL_OI_OFF = 496;
-var V1M_ENGINE_LONG_OI_OFF = 512;
-var V1M_ENGINE_SHORT_OI_OFF = 528;
-var V1M_ENGINE_C_TOT_OFF = 544;
-var V1M_ENGINE_PNL_POS_TOT_OFF = 560;
-var V1M_ENGINE_LIQ_CURSOR_OFF = 576;
-var V1M_ENGINE_GC_CURSOR_OFF = 578;
-var V1M_ENGINE_LAST_SWEEP_START_OFF = 584;
-var V1M_ENGINE_LAST_SWEEP_COMPLETE_OFF = 592;
-var V1M_ENGINE_CRANK_CURSOR_OFF = 600;
-var V1M_ENGINE_SWEEP_START_IDX_OFF = 602;
-var V1M_ENGINE_LIFETIME_LIQUIDATIONS_OFF = 608;
-var V1M_ENGINE_LIFETIME_FORCE_CLOSES_OFF = 616;
-var V1M_ENGINE_NET_LP_POS_OFF = 624;
+var V1M_ENGINE_CURRENT_SLOT_OFF = 408;
+var V1M_ENGINE_FUNDING_INDEX_OFF = 416;
+var V1M_ENGINE_LAST_FUNDING_SLOT_OFF = 432;
+var V1M_ENGINE_FUNDING_RATE_BPS_OFF = 440;
+var V1M_ENGINE_MARK_PRICE_OFF = 448;
+var V1M_ENGINE_LAST_CRANK_SLOT_OFF = 472;
+var V1M_ENGINE_MAX_CRANK_STALENESS_OFF = 480;
+var V1M_ENGINE_TOTAL_OI_OFF = 488;
+var V1M_ENGINE_LONG_OI_OFF = 504;
+var V1M_ENGINE_SHORT_OI_OFF = 520;
+var V1M_ENGINE_C_TOT_OFF = 536;
+var V1M_ENGINE_PNL_POS_TOT_OFF = 552;
+var V1M_ENGINE_LIQ_CURSOR_OFF = 568;
+var V1M_ENGINE_GC_CURSOR_OFF = 570;
+var V1M_ENGINE_LAST_SWEEP_START_OFF = 576;
+var V1M_ENGINE_LAST_SWEEP_COMPLETE_OFF = 584;
+var V1M_ENGINE_CRANK_CURSOR_OFF = 592;
+var V1M_ENGINE_SWEEP_START_IDX_OFF = 594;
+var V1M_ENGINE_LIFETIME_LIQUIDATIONS_OFF = 600;
+var V1M_ENGINE_LIFETIME_FORCE_CLOSES_OFF = 608;
+var V1M_ENGINE_NET_LP_POS_OFF = 616;
 var V1M_ENGINE_LP_SUM_ABS_OFF = 632;
 var V1M_ENGINE_LP_MAX_ABS_OFF = 648;
 var V1M_ENGINE_LP_MAX_ABS_SWEEP_OFF = 664;
 var V1M_ENGINE_EMERGENCY_OI_MODE_OFF = 680;
 var V1M_ENGINE_EMERGENCY_START_SLOT_OFF = 688;
 var V1M_ENGINE_LAST_BREAKER_SLOT_OFF = 696;
-var V1M_ENGINE_BITMAP_OFF = 728;
+var V1M_ENGINE_BITMAP_OFF = 720;
+var V1M2_ACCOUNT_SIZE = 312;
+var V1M2_ENGINE_BITMAP_OFF = 990;
+var V1M2_ENGINE_CURRENT_SLOT_OFF = 408;
+var V1M2_ENGINE_FUNDING_INDEX_OFF = 416;
+var V1M2_ENGINE_LAST_FUNDING_SLOT_OFF = 432;
+var V1M2_ENGINE_FUNDING_RATE_BPS_OFF = 440;
+var V1M2_ENGINE_MARK_PRICE_OFF = 480;
+var V1M2_ENGINE_LAST_CRANK_SLOT_OFF = 504;
+var V1M2_ENGINE_MAX_CRANK_STALENESS_OFF = 512;
+var V1M2_RUNTIME_SHIFT = 32;
 var ENGINE_OFF = V1_ENGINE_OFF;
 var ENGINE_MARK_PRICE_OFF = V1_ENGINE_MARK_PRICE_OFF;
 function computeSlabSize(engineOff, bitmapOff, accountSize, maxAccounts, postBitmap = 18) {
@@ -1528,6 +1540,11 @@ for (const [label, n] of [["Micro", 64], ["Small", 256], ["Medium", 1024], ["Lar
   const size = computeSlabSize(V1M_ENGINE_OFF, V1M_ENGINE_BITMAP_OFF, V1M_ACCOUNT_SIZE, n, 18);
   SLAB_TIERS_V1M[label.toLowerCase()] = { maxAccounts: n, dataSize: size, label, description: `${n} slots (V1M mainnet)` };
 }
+var SLAB_TIERS_V1M2 = {};
+for (const [label, n] of [["Micro", 64], ["Small", 256], ["Medium", 1024], ["Large", 4096]]) {
+  const size = computeSlabSize(V1M2_ENGINE_OFF, V1M2_ENGINE_BITMAP_OFF, V1M2_ACCOUNT_SIZE, n, 18);
+  SLAB_TIERS_V1M2[label.toLowerCase()] = { maxAccounts: n, dataSize: size, label, description: `${n} slots (V1M2 mainnet upgraded)` };
+}
 var SLAB_TIERS_V_ADL = {};
 for (const [label, n] of [["Micro", 64], ["Small", 256], ["Medium", 1024], ["Large", 4096]]) {
   const size = computeSlabSize(V_ADL_ENGINE_OFF, V_ADL_ENGINE_BITMAP_OFF, V_ADL_ACCOUNT_SIZE, n, 18);
@@ -1785,6 +1802,69 @@ function buildLayoutV1M(maxAccounts) {
     engineInsuranceIsolationBpsOff: 64
   };
 }
+function buildLayoutV1M2(maxAccounts) {
+  const engineOff = V1M2_ENGINE_OFF;
+  const bitmapOff = V1M2_ENGINE_BITMAP_OFF;
+  const accountSize = V1M2_ACCOUNT_SIZE;
+  const bitmapWords = Math.ceil(maxAccounts / 64);
+  const bitmapBytes = bitmapWords * 8;
+  const postBitmap = 18;
+  const nextFreeBytes = maxAccounts * 2;
+  const preAccountsLen = bitmapOff + bitmapBytes + postBitmap + nextFreeBytes;
+  const accountsOffRel = Math.ceil(preAccountsLen / 8) * 8;
+  return {
+    version: 1,
+    headerLen: V1_HEADER_LEN,
+    configOffset: V1_HEADER_LEN,
+    configLen: V1M2_CONFIG_LEN,
+    reservedOff: V1_RESERVED_OFF,
+    engineOff,
+    accountSize,
+    maxAccounts,
+    bitmapWords,
+    accountsOff: engineOff + accountsOffRel,
+    engineInsuranceOff: 16,
+    engineParamsOff: V1M_ENGINE_PARAMS_OFF,
+    // 72 — same as V1M
+    paramsSize: V1M_PARAMS_SIZE,
+    // 336 — same as V1M
+    // Runtime fields: same as V1M up to fundingRateBps, then +32 shift
+    engineCurrentSlotOff: V1M2_ENGINE_CURRENT_SLOT_OFF,
+    engineFundingIndexOff: V1M2_ENGINE_FUNDING_INDEX_OFF,
+    engineLastFundingSlotOff: V1M2_ENGINE_LAST_FUNDING_SLOT_OFF,
+    engineFundingRateBpsOff: V1M2_ENGINE_FUNDING_RATE_BPS_OFF,
+    engineMarkPriceOff: V1M2_ENGINE_MARK_PRICE_OFF,
+    engineLastCrankSlotOff: V1M2_ENGINE_LAST_CRANK_SLOT_OFF,
+    engineMaxCrankStalenessOff: V1M2_ENGINE_MAX_CRANK_STALENESS_OFF,
+    // Fields after maxCrankStaleness: apply same +32 shift from V1M
+    engineTotalOiOff: V1M_ENGINE_TOTAL_OI_OFF + V1M2_RUNTIME_SHIFT,
+    engineLongOiOff: V1M_ENGINE_LONG_OI_OFF + V1M2_RUNTIME_SHIFT,
+    engineShortOiOff: V1M_ENGINE_SHORT_OI_OFF + V1M2_RUNTIME_SHIFT,
+    engineCTotOff: V1M_ENGINE_C_TOT_OFF + V1M2_RUNTIME_SHIFT,
+    enginePnlPosTotOff: V1M_ENGINE_PNL_POS_TOT_OFF + V1M2_RUNTIME_SHIFT,
+    engineLiqCursorOff: V1M_ENGINE_LIQ_CURSOR_OFF + V1M2_RUNTIME_SHIFT,
+    engineGcCursorOff: V1M_ENGINE_GC_CURSOR_OFF + V1M2_RUNTIME_SHIFT,
+    engineLastSweepStartOff: V1M_ENGINE_LAST_SWEEP_START_OFF + V1M2_RUNTIME_SHIFT,
+    engineLastSweepCompleteOff: V1M_ENGINE_LAST_SWEEP_COMPLETE_OFF + V1M2_RUNTIME_SHIFT,
+    engineCrankCursorOff: V1M_ENGINE_CRANK_CURSOR_OFF + V1M2_RUNTIME_SHIFT,
+    engineSweepStartIdxOff: V1M_ENGINE_SWEEP_START_IDX_OFF + V1M2_RUNTIME_SHIFT,
+    engineLifetimeLiquidationsOff: V1M_ENGINE_LIFETIME_LIQUIDATIONS_OFF + V1M2_RUNTIME_SHIFT,
+    engineLifetimeForceClosesOff: V1M_ENGINE_LIFETIME_FORCE_CLOSES_OFF + V1M2_RUNTIME_SHIFT,
+    engineNetLpPosOff: V1M_ENGINE_NET_LP_POS_OFF + V1M2_RUNTIME_SHIFT,
+    engineLpSumAbsOff: V1M_ENGINE_LP_SUM_ABS_OFF + V1M2_RUNTIME_SHIFT,
+    engineLpMaxAbsOff: V1M_ENGINE_LP_MAX_ABS_OFF + V1M2_RUNTIME_SHIFT,
+    engineLpMaxAbsSweepOff: V1M_ENGINE_LP_MAX_ABS_SWEEP_OFF + V1M2_RUNTIME_SHIFT,
+    engineEmergencyOiModeOff: V1M_ENGINE_EMERGENCY_OI_MODE_OFF + V1M2_RUNTIME_SHIFT,
+    engineEmergencyStartSlotOff: V1M_ENGINE_EMERGENCY_START_SLOT_OFF + V1M2_RUNTIME_SHIFT,
+    engineLastBreakerSlotOff: V1M_ENGINE_LAST_BREAKER_SLOT_OFF + V1M2_RUNTIME_SHIFT,
+    engineBitmapOff: V1M2_ENGINE_BITMAP_OFF,
+    postBitmap: 18,
+    acctOwnerOff: ACCT_OWNER_OFF,
+    hasInsuranceIsolation: true,
+    engineInsuranceIsolatedOff: 48,
+    engineInsuranceIsolationBpsOff: 64
+  };
+}
 function buildLayoutVADL(maxAccounts) {
   const engineOff = V_ADL_ENGINE_OFF;
   const bitmapOff = V_ADL_ENGINE_BITMAP_OFF;
@@ -1880,7 +1960,15 @@ function buildLayoutVADL(maxAccounts) {
 }
 function detectSlabLayout(dataLen, data) {
   const vadln = V_ADL_SIZES.get(dataLen);
-  if (vadln !== void 0) return buildLayoutVADL(vadln);
+  if (vadln !== void 0) {
+    if (data && data.length >= 752) {
+      const maxAcctsV1M2 = readU64LE(data, V1M2_ENGINE_OFF + V1M_ENGINE_PARAMS_OFF + 32);
+      if (maxAcctsV1M2 === BigInt(vadln)) {
+        return buildLayoutV1M2(vadln);
+      }
+    }
+    return buildLayoutVADL(vadln);
+  }
   const v1mn = V1M_SIZES.get(dataLen);
   if (v1mn !== void 0) return buildLayoutV1M(v1mn);
   const v0n = V0_SIZES.get(dataLen);
@@ -1961,7 +2049,7 @@ function computeEffectiveOiCapBps(config, currentSlot) {
   return result < target ? result : target;
 }
 function readNonce(data) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) {
     throw new Error(`readNonce: unrecognized slab data length ${data.length}`);
   }
@@ -1970,7 +2058,7 @@ function readNonce(data) {
   return readU64LE(data, roff);
 }
 function readLastThrUpdateSlot(data) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) {
     throw new Error(`readLastThrUpdateSlot: unrecognized slab data length ${data.length}`);
   }
@@ -1990,7 +2078,7 @@ function parseHeader(data) {
   const bump = readU8(data, 12);
   const flags = readU8(data, 13);
   const admin = new PublicKey3(data.subarray(16, 48));
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   const roff = layout ? layout.reservedOff : V0_RESERVED_OFF;
   const nonce = readU64LE(data, roff);
   const lastThrUpdateSlot = readU64LE(data, roff + 8);
@@ -2007,7 +2095,7 @@ function parseHeader(data) {
   };
 }
 function parseConfig(data, layoutHint) {
-  const layout = layoutHint !== void 0 ? layoutHint : detectSlabLayout(data.length);
+  const layout = layoutHint !== void 0 ? layoutHint : detectSlabLayout(data.length, data);
   const configOff = layout ? layout.configOffset : V0_HEADER_LEN;
   const configLen = layout ? layout.configLen : V0_CONFIG_LEN;
   const minLen = configOff + Math.min(configLen, 120);
@@ -2159,7 +2247,7 @@ function parseConfig(data, layoutHint) {
   };
 }
 function parseParams(data, layoutHint) {
-  const layout = layoutHint !== void 0 ? layoutHint : detectSlabLayout(data.length);
+  const layout = layoutHint !== void 0 ? layoutHint : detectSlabLayout(data.length, data);
   const engineOff = layout ? layout.engineOff : V0_ENGINE_OFF;
   const paramsOff = layout ? layout.engineParamsOff : V0_ENGINE_PARAMS_OFF;
   const paramsSize = layout ? layout.paramsSize : V0_PARAMS_SIZE;
@@ -2195,7 +2283,7 @@ function parseParams(data, layoutHint) {
   return result;
 }
 function parseEngine(data) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) {
     throw new Error(`Unrecognized slab data length: ${data.length}. Cannot determine layout version.`);
   }
@@ -2249,7 +2337,7 @@ function parseEngine(data) {
   };
 }
 function parseUsedIndices(data) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) throw new Error(`Unrecognized slab data length: ${data.length}`);
   const base = layout.engineOff + layout.engineBitmapOff;
   if (data.length < base + layout.bitmapWords * 8) {
@@ -2268,7 +2356,7 @@ function parseUsedIndices(data) {
   return used;
 }
 function isAccountUsed(data, idx) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) return false;
   if (!Number.isInteger(idx) || idx < 0 || idx >= layout.maxAccounts) return false;
   const base = layout.engineOff + layout.engineBitmapOff;
@@ -2285,7 +2373,7 @@ function maxAccountIndex(dataLen) {
   return Math.floor(accountsEnd / layout.accountSize);
 }
 function parseAccount(data, idx) {
-  const layout = detectSlabLayout(data.length);
+  const layout = detectSlabLayout(data.length, data);
   if (!layout) throw new Error(`Unrecognized slab data length: ${data.length}`);
   const maxIdx = maxAccountIndex(data.length);
   if (!Number.isInteger(idx) || idx < 0 || idx >= maxIdx) {
@@ -4409,6 +4497,7 @@ export {
   SLAB_TIERS_V1D,
   SLAB_TIERS_V1D_LEGACY,
   SLAB_TIERS_V1M,
+  SLAB_TIERS_V1M2,
   SLAB_TIERS_V2,
   SLAB_TIERS_V_ADL,
   SLAB_TIERS_V_ADL_DISCOVERY,