@percolatorct/sdk 1.0.0-beta.15 → 1.0.0-beta.16

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/solana/token-program.d.ts

@@ -0,0 +1,19 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+/**
+ * Token2022 (Token Extensions) program ID.
+ */
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+/**
+ * Detect which token program owns a given mint account.
+ * Returns the owner program ID (TOKEN_PROGRAM_ID or TOKEN_2022_PROGRAM_ID).
+ * Throws if the mint account doesn't exist.
+ */
+export declare function detectTokenProgram(connection: Connection, mint: PublicKey): Promise<PublicKey>;
+/**
+ * Check if a given token program ID is Token2022.
+ */
+export declare function isToken2022(tokenProgramId: PublicKey): boolean;
+/**
+ * Check if a given token program ID is the standard SPL Token program.
+ */
+export declare function isStandardToken(tokenProgramId: PublicKey): boolean;

package/dist/validation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Input validation utilities for CLI commands.
+ * Provides descriptive error messages for invalid input.
+ */
+import { PublicKey } from "@solana/web3.js";
+export declare class ValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * 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;
+/**
+ * Validate a u128 value.
+ */
+export declare function validateU128(value: string, field: string): bigint;
+/**
+ * Validate an i64 value.
+ */
+export declare function validateI64(value: string, field: string): bigint;
+/**
+ * Validate an i128 value (trade sizes).
+ */
+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.
+ */
+export declare function validateBps(value: string, field: string): number;
+/**
+ * Validate a u64 value.
+ */
+export declare function validateU64(value: string, field: string): bigint;
+/**
+ * Validate a u16 value.
+ */
+export declare function validateU16(value: string, field: string): number;

package/package.json

@@ -1,24 +1,29 @@
 {
   "name": "@percolatorct/sdk",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.16",
   "license": "Apache-2.0",
   "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "main": "./dist/index.js",
   "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": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
-    "test": "tsx test/abi.test.ts && tsx test/pda.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"
+    "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",
+    "verify-layout": "tsx scripts/verify-layout.ts"
   },
   "dependencies": {
     "@solana/spl-token": "^0.4.14",
@@ -26,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",