@percolatorct/sdk 0.5.1 → 1.0.0-beta.1

package/dist/solana/rpc-pool.d.ts

@@ -0,0 +1,347 @@
+import { Connection, type Commitment, type ConnectionConfig } from "@solana/web3.js";
+/**
+ * Configuration for exponential-backoff retry on RPC calls.
+ *
+ * @example
+ * ```ts
+ * const retryConfig: RetryConfig = {
+ *   maxRetries: 3,
+ *   baseDelayMs: 500,
+ *   maxDelayMs: 10_000,
+ *   retryableStatusCodes: [429, 502, 503],
+ * };
+ * ```
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts after the initial request fails.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in ms for exponential backoff.
+     * Delay for attempt N is: `min(baseDelayMs * 2^N, maxDelayMs) + jitter`.
+     * @default 500
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum delay in ms (backoff cap).
+     * @default 10_000
+     */
+    maxDelayMs?: number;
+    /**
+     * Jitter factor (0–1). Applied as random `[0, jitterFactor * delay]` addition.
+     * @default 0.25
+     */
+    jitterFactor?: number;
+    /**
+     * HTTP status codes considered retryable.
+     * Errors matching these codes (or containing their string representation)
+     * will be retried.
+     * @default [429, 502, 503, 504]
+     */
+    retryableStatusCodes?: number[];
+}
+/**
+ * Configuration for a single RPC endpoint in the pool.
+ *
+ * @example
+ * ```ts
+ * const endpoint: RpcEndpointConfig = {
+ *   url: "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
+ *   weight: 10,
+ *   label: "helius-primary",
+ * };
+ * ```
+ */
+export interface RpcEndpointConfig {
+    /** RPC endpoint URL. */
+    url: string;
+    /**
+     * Relative weight for round-robin selection.
+     * Higher weight = more requests routed here.
+     * @default 1
+     */
+    weight?: number;
+    /**
+     * Human-readable label for logging / diagnostics.
+     * @default url hostname
+     */
+    label?: string;
+    /**
+     * Extra `ConnectionConfig` options (commitment, confirmTransactionInitialTimeout, etc.)
+     * merged into the Solana `Connection` constructor for this endpoint.
+     */
+    connectionConfig?: ConnectionConfig;
+}
+/**
+ * Strategy for selecting the next RPC endpoint from the pool.
+ *
+ * - `"round-robin"` — weighted round-robin across healthy endpoints.
+ * - `"failover"`    — use the first healthy endpoint; only advance on failure.
+ */
+export type SelectionStrategy = "round-robin" | "failover";
+/**
+ * Full configuration for the RPC connection pool.
+ *
+ * @example
+ * ```ts
+ * 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",
+ *   retry: { maxRetries: 3, baseDelayMs: 500 },
+ *   requestTimeoutMs: 30_000,
+ * });
+ *
+ * // Use like a Connection — same surface
+ * const slot = await pool.call(conn => conn.getSlot());
+ * ```
+ */
+export interface RpcPoolConfig {
+    /**
+     * One or more RPC endpoints. At least one is required.
+     * If a bare `string[]` is passed, each string is treated as `{ url: string }`.
+     */
+    endpoints: (RpcEndpointConfig | string)[];
+    /**
+     * How to pick the next endpoint.
+     * @default "failover"
+     */
+    strategy?: SelectionStrategy;
+    /**
+     * Retry config applied to every `call()`.
+     * Set to `false` to disable retries entirely.
+     * @default { maxRetries: 3, baseDelayMs: 500 }
+     */
+    retry?: RetryConfig | false;
+    /**
+     * Per-request timeout in ms.  Applies an `AbortSignal` timeout to `Connection`
+     * calls where supported, and is used as a deadline for the health probe.
+     * @default 30_000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Default Solana commitment level for connections.
+     * @default "confirmed"
+     */
+    commitment?: Commitment;
+    /**
+     * If true, `console.warn` diagnostic messages on retries, failovers, etc.
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Result of an RPC health probe.
+ *
+ * @example
+ * ```ts
+ * import { checkRpcHealth } from "@percolator/sdk";
+ *
+ * const health = await checkRpcHealth("https://api.mainnet-beta.solana.com");
+ * console.log(`Slot: ${health.slot}, Latency: ${health.latencyMs}ms`);
+ * if (!health.healthy) console.warn(`Unhealthy: ${health.error}`);
+ * ```
+ */
+export interface RpcHealthResult {
+    /** The endpoint that was probed. */
+    endpoint: string;
+    /** Whether the probe succeeded (getSlot returned without error). */
+    healthy: boolean;
+    /** Round-trip latency in milliseconds (0 if unhealthy). */
+    latencyMs: number;
+    /** Current slot height (0 if unhealthy). */
+    slot: number;
+    /** Error message if the probe failed. */
+    error?: string;
+}
+/**
+ * Probe an RPC endpoint's health by calling `getSlot()` and measuring latency.
+ *
+ * @param endpoint  - RPC URL to probe
+ * @param timeoutMs - Timeout in ms for the probe request (default: 5000)
+ * @returns Health result with latency and slot height
+ *
+ * @example
+ * ```ts
+ * import { checkRpcHealth } from "@percolator/sdk";
+ *
+ * const result = await checkRpcHealth("https://api.mainnet-beta.solana.com", 3000);
+ * if (result.healthy) {
+ *   console.log(`Slot ${result.slot} — ${result.latencyMs}ms`);
+ * } else {
+ *   console.error(`RPC down: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function checkRpcHealth(endpoint: string, timeoutMs?: number): Promise<RpcHealthResult>;
+/** Resolved defaults for RetryConfig. */
+interface ResolvedRetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterFactor: number;
+    retryableStatusCodes: number[];
+}
+declare function resolveRetryConfig(cfg?: RetryConfig | false): ResolvedRetryConfig | null;
+declare function normalizeEndpoint(ep: RpcEndpointConfig | string): RpcEndpointConfig;
+declare function endpointLabel(ep: RpcEndpointConfig): string;
+declare function isRetryable(err: unknown, codes: number[]): boolean;
+declare function computeDelay(attempt: number, config: ResolvedRetryConfig): number;
+/**
+ * RPC connection pool with retry, failover, and round-robin support.
+ *
+ * Wraps one or more Solana RPC endpoints behind a single `call()` interface
+ * that automatically retries transient errors and fails over to alternate
+ * endpoints when one goes down.
+ *
+ * @example
+ * ```ts
+ * 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",
+ *   retry: { maxRetries: 3 },
+ *   requestTimeoutMs: 30_000,
+ * });
+ *
+ * // Execute any Connection method through the pool
+ * const slot = await pool.call(conn => conn.getSlot());
+ *
+ * // Or get a raw connection for one-off use
+ * const conn = pool.getConnection();
+ *
+ * // Health check all endpoints
+ * const results = await pool.healthCheck();
+ * ```
+ */
+export declare class RpcPool {
+    private readonly endpoints;
+    private readonly strategy;
+    private readonly retryConfig;
+    private readonly requestTimeoutMs;
+    private readonly verbose;
+    /** Round-robin index tracker. */
+    private rrIndex;
+    /** Consecutive failure threshold before marking an endpoint unhealthy. */
+    private static readonly UNHEALTHY_THRESHOLD;
+    /** Minimum endpoints before auto-recovery is attempted. */
+    private static readonly MIN_HEALTHY;
+    constructor(config: RpcPoolConfig);
+    /**
+     * Execute a function against a pooled connection with automatic retry
+     * and failover.
+     *
+     * @param fn - Async function that receives a `Connection` and returns a result.
+     * @returns The result of `fn`.
+     * @throws The last error if all retries and failovers are exhausted.
+     *
+     * @example
+     * ```ts
+     * const balance = await pool.call(c => c.getBalance(pubkey));
+     * const markets = await pool.call(c => discoverMarkets(c, programId, opts));
+     * ```
+     */
+    call<T>(fn: (connection: Connection) => Promise<T>): Promise<T>;
+    /**
+     * Get a raw `Connection` from the current preferred endpoint.
+     * Useful when you need to pass a Connection to external code.
+     *
+     * NOTE: This bypasses retry and failover logic. Prefer `call()`.
+     *
+     * @returns Solana Connection from the current preferred endpoint.
+     *
+     * @example
+     * ```ts
+     * const conn = pool.getConnection();
+     * const balance = await conn.getBalance(pubkey);
+     * ```
+     */
+    getConnection(): Connection;
+    /**
+     * Run a health check against all endpoints in the pool.
+     *
+     * @param timeoutMs - Per-endpoint probe timeout (default: 5000)
+     * @returns Array of health results, one per endpoint.
+     *
+     * @example
+     * ```ts
+     * const results = await pool.healthCheck();
+     * for (const r of results) {
+     *   console.log(`${r.endpoint}: ${r.healthy ? 'UP' : 'DOWN'} (${r.latencyMs}ms, slot ${r.slot})`);
+     * }
+     * ```
+     */
+    healthCheck(timeoutMs?: number): Promise<RpcHealthResult[]>;
+    /**
+     * Get the number of endpoints in the pool.
+     */
+    get size(): number;
+    /**
+     * Get the number of currently healthy endpoints.
+     */
+    get healthyCount(): number;
+    /**
+     * Get endpoint labels and their current status.
+     *
+     * @returns Array of `{ label, url, healthy, failures, lastLatencyMs }`.
+     */
+    status(): Array<{
+        label: string;
+        url: string;
+        healthy: boolean;
+        failures: number;
+        lastLatencyMs: number;
+    }>;
+    /**
+     * Select the next endpoint based on strategy.
+     * Returns -1 if no endpoint is available.
+     */
+    private selectEndpoint;
+    /**
+     * If all endpoints are unhealthy, reset them so we at least try again.
+     */
+    private maybeRecoverEndpoints;
+}
+/**
+ * Execute an async function with exponential-backoff retry.
+ *
+ * Use this when you already have a `Connection` and just want retry logic
+ * without a full pool.
+ *
+ * @param fn     - Async function to execute
+ * @param config - Retry configuration (default: 3 retries, 500ms base delay)
+ * @returns Result of `fn`
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```ts
+ * 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 },
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/** @internal — exposed for unit tests only */
+export declare const _internal: {
+    readonly isRetryable: typeof isRetryable;
+    readonly computeDelay: typeof computeDelay;
+    readonly resolveRetryConfig: typeof resolveRetryConfig;
+    readonly normalizeEndpoint: typeof normalizeEndpoint;
+    readonly endpointLabel: typeof endpointLabel;
+};
+export {};

package/dist/solana/slab.d.ts

@@ -85,8 +85,10 @@ export declare const SLAB_TIERS_V1M: Record<string, {
     description: string;
 }>;
 /**
- * V1M2 slab tier sizes — mainnet program with 312-byte accounts.
- * Same engine layout as V1M but larger accounts. Sizes match V_ADL exactly.
+ * V1M2 slab tier sizes — mainnet program rebuilt from main@4861c56 with 312-byte accounts.
+ * ENGINE_OFF=616, BITMAP_OFF=1008 (empirically verified from CCTegYZ...).
+ * Engine struct is layout-identical to V_ADL; differs only in engineOff (616 vs 624).
+ * Sizes are unique from V_ADL after the bitmap correction: medium=323312 vs V_ADL=323320.
  */
 export declare const SLAB_TIERS_V1M2: Record<string, {
     maxAccounts: number;
@@ -96,9 +98,9 @@ export declare const SLAB_TIERS_V1M2: Record<string, {
 }>;
 /**
  * V_ADL slab tier sizes — PERC-8270/8271 ADL-upgraded program.
- * ENGINE_OFF=624, BITMAP_OFF=1006, ACCOUNT_SIZE=312, postBitmap=18.
+ * ENGINE_OFF=624, BITMAP_OFF=1008, 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.
+ * BPF SLAB_LEN verified by cargo build-sbf in PERC-8271: large (4096) = 1288320 bytes.
  */
 export declare const SLAB_TIERS_V_ADL: Record<string, {
     maxAccounts: number;
@@ -106,10 +108,32 @@ export declare const SLAB_TIERS_V_ADL: Record<string, {
     label: string;
     description: string;
 }>;
+/**
+ * V_SETDEXPOOL slab tier sizes — PERC-SetDexPool security fix.
+ * ENGINE_OFF=632, BITMAP_OFF=1008, ACCOUNT_SIZE=312, CONFIG_LEN=528.
+ * e.g. large (4096 accts) = 1288336 bytes.
+ */
+export declare const SLAB_TIERS_V_SETDEXPOOL: Record<string, {
+    maxAccounts: number;
+    dataSize: number;
+    label: string;
+    description: string;
+}>;
+/**
+ * V12_1 slab tier sizes — percolator-core v12.1 merge.
+ * ENGINE_OFF=648, BITMAP_OFF=1016, ACCOUNT_SIZE=320.
+ * Verified by cargo build-sbf compile-time assertions.
+ */
+export declare const SLAB_TIERS_V12_1: 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.
+ * Checks 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).
@@ -189,6 +213,14 @@ export interface MarketConfig {
     cumulativeVolumeE6: bigint;
     /** PERC-622: Slots elapsed from market creation to Phase 2 entry (u24) */
     phase2DeltaSlots: number;
+    /**
+     * PERC-SetDexPool: Admin-pinned DEX pool pubkey for HYPERP markets.
+     * Null when reading old slabs (pre-SetDexPool configLen < 528) or when
+     * SetDexPool has never been called (all-zero pubkey).
+     * Non-null means the program will reject any UpdateHyperpMark that passes
+     * a different pool account.
+     */
+    dexPool: PublicKey | null;
 }
 export interface InsuranceFund {
     balance: bigint;

package/dist/solana/static-markets.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Static market registry — bundled list of known Percolator slab addresses.
+ *
+ * This is the tier-3 fallback for `discoverMarkets()`: when both
+ * `getProgramAccounts` (tier 1) and the REST API (tier 2) are unavailable,
+ * the SDK falls back to this bundled list to bootstrap market discovery.
+ *
+ * The addresses are fetched on-chain via `getMarketsByAddress`
+ * (`getMultipleAccounts`), so all data is still verified on-chain.  The static
+ * list only provides the *address directory* — no cached market data is used.
+ *
+ * ## Maintenance
+ *
+ * Update this list when new markets are deployed or old ones are retired.
+ * Run `scripts/update-static-markets.ts` to regenerate from a permissive RPC
+ * or the REST API.
+ *
+ * @module
+ */
+import type { Network } from "../config/program-ids.js";
+/**
+ * A single entry in the static market registry.
+ *
+ * Only the slab address (base58) is required.  Optional metadata fields
+ * (`symbol`, `name`) are provided for debugging/logging purposes only —
+ * they are **not** used for on-chain data and may become stale.
+ */
+export interface StaticMarketEntry {
+    /** Base58-encoded slab account address. */
+    slabAddress: string;
+    /** Optional human-readable symbol (e.g. "SOL-PERP"). */
+    symbol?: string;
+    /** Optional descriptive name. */
+    name?: string;
+}
+/**
+ * Get the bundled static market list for a given network.
+ *
+ * Returns the built-in list merged with any entries added via
+ * {@link registerStaticMarkets}.  Duplicates (by `slabAddress`) are removed
+ * automatically — user-registered entries take precedence.
+ *
+ * @param network - Target network (`"mainnet"` or `"devnet"`)
+ * @returns Array of static market entries (may be empty if no markets are known)
+ *
+ * @example
+ * ```ts
+ * import { getStaticMarkets } from "@percolator/sdk";
+ *
+ * const markets = getStaticMarkets("mainnet");
+ * console.log(`${markets.length} known mainnet slab addresses`);
+ * ```
+ */
+export declare function getStaticMarkets(network: Network): StaticMarketEntry[];
+/**
+ * Register additional static market entries at runtime.
+ *
+ * Use this to inject known slab addresses before calling `discoverMarkets()`
+ * so that tier-3 fallback has addresses to work with — especially useful
+ * right after mainnet launch when the bundled list may be empty.
+ *
+ * Entries are deduplicated by `slabAddress` — calling this multiple times
+ * with the same address is safe.
+ *
+ * @param network - Target network
+ * @param entries - One or more static market entries to register
+ *
+ * @example
+ * ```ts
+ * import { registerStaticMarkets } from "@percolator/sdk";
+ *
+ * registerStaticMarkets("mainnet", [
+ *   { slabAddress: "ABC123...", symbol: "SOL-PERP" },
+ *   { slabAddress: "DEF456...", symbol: "ETH-PERP" },
+ * ]);
+ * ```
+ */
+export declare function registerStaticMarkets(network: Network, entries: StaticMarketEntry[]): void;
+/**
+ * Clear all user-registered static market entries for a network.
+ *
+ * Useful in tests or when resetting state.
+ *
+ * @param network - Target network to clear (omit to clear all networks)
+ */
+export declare function clearStaticMarkets(network?: Network): void;

package/dist/validation.d.ts

@@ -9,14 +9,34 @@ 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;
 /**
@@ -32,7 +52,12 @@ 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).
+ * 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.
  */
 export declare function validateBps(value: string, field: string): number;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percolatorct/sdk",
-  "version": "0.5.1",
+  "version": "1.0.0-beta.1",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -10,10 +10,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js",
-      "default": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -22,7 +22,8 @@
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly --declaration --outDir dist",
     "test": "tsx test/abi.test.ts && tsx test/slab.test.ts && tsx test/validation.test.ts && tsx test/dex-oracle.test.ts && tsx test/trading.test.ts && tsx test/warmup-leverage-cap.test.ts && tsx test/dynamic-fees.test.ts && tsx test/oracle.test.ts && vitest run",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "verify-layout": "tsx scripts/verify-layout.ts"
   },
   "dependencies": {
     "@solana/spl-token": "^0.4.14",