@percolatorct/sdk 0.3.0

package/dist/solana/stake.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @module stake
+ * Percolator Insurance LP Staking program — instruction encoders, PDA derivation, and account specs.
+ *
+ * Program: percolator-stake (dcccrypto/percolator-stake)
+ * Deployed devnet:  6aJb1F9CDCVWCNYFwj8aQsVb696YnW6J1FznteHq4Q6k
+ * Deployed mainnet: (pending deployment — DevOps must set STAKE_PROGRAM_ID env var or deploy and update STAKE_PROGRAM_IDS.mainnet)
+ */
+import { PublicKey } from '@solana/web3.js';
+/** Known stake program addresses per network. Mainnet is empty until deployed. */
+export declare const STAKE_PROGRAM_IDS: {
+    readonly devnet: "6aJb1F9CDCVWCNYFwj8aQsVb696YnW6J1FznteHq4Q6k";
+    readonly mainnet: "";
+};
+/**
+ * Resolve the stake program ID for the given network.
+ *
+ * Priority:
+ *  1. STAKE_PROGRAM_ID env var (explicit override — DevOps sets this for mainnet until constant is filled)
+ *  2. Network-specific constant from STAKE_PROGRAM_IDS
+ *
+ * Throws a clear error on mainnet when no address is available so callers
+ * surface the gap instead of silently hitting the devnet program.
+ */
+export declare function getStakeProgramId(network?: 'devnet' | 'mainnet'): PublicKey;
+/**
+ * Default export — resolves for the current runtime network.
+ * Use getStakeProgramId() with an explicit network argument where possible.
+ *
+ * @deprecated Direct use of STAKE_PROGRAM_ID is being phased out in favour of
+ *   getStakeProgramId() so mainnet callers get a clear error rather than silently
+ *   resolving to the devnet address.
+ */
+export declare const STAKE_PROGRAM_ID: PublicKey;
+export declare const STAKE_IX: {
+    readonly InitPool: 0;
+    readonly Deposit: 1;
+    readonly Withdraw: 2;
+    readonly FlushToInsurance: 3;
+    readonly UpdateConfig: 4;
+    readonly TransferAdmin: 5;
+    readonly AdminSetOracleAuthority: 6;
+    readonly AdminSetRiskThreshold: 7;
+    readonly AdminSetMaintenanceFee: 8;
+    readonly AdminResolveMarket: 9;
+    readonly AdminWithdrawInsurance: 10;
+    readonly AdminSetInsurancePolicy: 11;
+    /** PERC-272: Accrue trading fees to LP vault */
+    readonly AccrueFees: 12;
+    /** PERC-272: Init pool in trading LP mode */
+    readonly InitTradingPool: 13;
+    /** PERC-313: Set HWM config (enable + floor bps) */
+    readonly AdminSetHwmConfig: 14;
+    /** PERC-303: Enable/configure senior-junior LP tranches */
+    readonly AdminSetTrancheConfig: 15;
+    /** PERC-303: Deposit into junior (first-loss) tranche */
+    readonly DepositJunior: 16;
+};
+/** Derive the stake pool PDA for a given slab (market). */
+export declare function deriveStakePool(slab: PublicKey, programId?: PublicKey): [PublicKey, number];
+/** Derive the vault authority PDA (signs CPI, owns LP mint + vault). */
+export declare function deriveStakeVaultAuth(pool: PublicKey, programId?: PublicKey): [PublicKey, number];
+/** Derive the per-user deposit PDA (tracks cooldown, deposit time). */
+export declare function deriveDepositPda(pool: PublicKey, user: PublicKey, programId?: PublicKey): [PublicKey, number];
+/** Tag 0: InitPool — create stake pool for a slab. */
+export declare function encodeStakeInitPool(cooldownSlots: bigint | number, depositCap: bigint | number): Uint8Array;
+/** Tag 1: Deposit — deposit collateral, receive LP tokens. */
+export declare function encodeStakeDeposit(amount: bigint | number): Uint8Array;
+/** Tag 2: Withdraw — burn LP tokens, receive collateral (subject to cooldown). */
+export declare function encodeStakeWithdraw(lpAmount: bigint | number): Uint8Array;
+/** Tag 3: FlushToInsurance — move collateral from stake vault to wrapper insurance. */
+export declare function encodeStakeFlushToInsurance(amount: bigint | number): Uint8Array;
+/** Tag 4: UpdateConfig — update cooldown and/or deposit cap. */
+export declare function encodeStakeUpdateConfig(newCooldownSlots?: bigint | number, newDepositCap?: bigint | number): Uint8Array;
+/** Tag 5: TransferAdmin — transfer wrapper admin to pool PDA. */
+export declare function encodeStakeTransferAdmin(): Uint8Array;
+/** Tag 6: AdminSetOracleAuthority — forward to wrapper via CPI. */
+export declare function encodeStakeAdminSetOracleAuthority(newAuthority: PublicKey): Uint8Array;
+/** Tag 7: AdminSetRiskThreshold — forward to wrapper via CPI. */
+export declare function encodeStakeAdminSetRiskThreshold(newThreshold: bigint | number): Uint8Array;
+/** Tag 8: AdminSetMaintenanceFee — forward to wrapper via CPI. */
+export declare function encodeStakeAdminSetMaintenanceFee(newFee: bigint | number): Uint8Array;
+/** Tag 9: AdminResolveMarket — forward to wrapper via CPI. */
+export declare function encodeStakeAdminResolveMarket(): Uint8Array;
+/** Tag 10: AdminWithdrawInsurance — withdraw insurance after market resolution. */
+export declare function encodeStakeAdminWithdrawInsurance(amount: bigint | number): Uint8Array;
+/** Tag 12: AccrueFees — permissionless: accrue trading fees to LP vault. */
+export declare function encodeStakeAccrueFees(): Uint8Array;
+/** Tag 13: InitTradingPool — create pool in trading LP mode (pool_mode = 1). */
+export declare function encodeStakeInitTradingPool(cooldownSlots: bigint | number, depositCap: bigint | number): Uint8Array;
+/** Tag 14 (PERC-313): AdminSetHwmConfig — enable HWM protection and set floor BPS. */
+export declare function encodeStakeAdminSetHwmConfig(enabled: boolean, hwmFloorBps: number): Uint8Array;
+/** Tag 15 (PERC-303): AdminSetTrancheConfig — enable senior/junior LP tranches. */
+export declare function encodeStakeAdminSetTrancheConfig(juniorFeeMultBps: number): Uint8Array;
+/** Tag 16 (PERC-303): DepositJunior — deposit into first-loss junior tranche. */
+export declare function encodeStakeDepositJunior(amount: bigint | number): Uint8Array;
+/** Tag 11: AdminSetInsurancePolicy — set withdrawal policy on wrapper. */
+export declare function encodeStakeAdminSetInsurancePolicy(authority: PublicKey, minWithdrawBase: bigint | number, maxWithdrawBps: number, cooldownSlots: bigint | number): Uint8Array;
+/**
+ * Decoded StakePool state (352 bytes on-chain).
+ * Includes PERC-272 (fee yield), PERC-313 (HWM), and PERC-303 (tranches).
+ */
+export interface StakePoolState {
+    isInitialized: boolean;
+    bump: number;
+    vaultAuthorityBump: number;
+    adminTransferred: boolean;
+    slab: PublicKey;
+    admin: PublicKey;
+    collateralMint: PublicKey;
+    lpMint: PublicKey;
+    vault: PublicKey;
+    totalDeposited: bigint;
+    totalLpSupply: bigint;
+    cooldownSlots: bigint;
+    depositCap: bigint;
+    totalFlushed: bigint;
+    totalReturned: bigint;
+    totalWithdrawn: bigint;
+    percolatorProgram: PublicKey;
+    totalFeesEarned: bigint;
+    lastFeeAccrualSlot: bigint;
+    lastVaultSnapshot: bigint;
+    poolMode: number;
+    hwmEnabled: boolean;
+    epochHighWaterTvl: bigint;
+    hwmFloorBps: number;
+    trancheEnabled: boolean;
+    juniorBalance: bigint;
+    juniorTotalLp: bigint;
+    juniorFeeMultBps: number;
+}
+/** Size of StakePool on-chain (bytes). */
+export declare const STAKE_POOL_SIZE = 352;
+/**
+ * Decode a StakePool account from raw data buffer. * Uses DataView for all u64/u16 reads — browser-safe.
+ */
+export declare function decodeStakePool(data: Uint8Array): StakePoolState;
+export interface StakeAccounts {
+    /** InitPool accounts */
+    initPool: {
+        admin: PublicKey;
+        slab: PublicKey;
+        pool: PublicKey;
+        lpMint: PublicKey;
+        vault: PublicKey;
+        vaultAuth: PublicKey;
+        collateralMint: PublicKey;
+        percolatorProgram: PublicKey;
+    };
+    /** Deposit accounts */
+    deposit: {
+        user: PublicKey;
+        pool: PublicKey;
+        userCollateralAta: PublicKey;
+        vault: PublicKey;
+        lpMint: PublicKey;
+        userLpAta: PublicKey;
+        vaultAuth: PublicKey;
+        depositPda: PublicKey;
+    };
+    /** Withdraw accounts */
+    withdraw: {
+        user: PublicKey;
+        pool: PublicKey;
+        userLpAta: PublicKey;
+        lpMint: PublicKey;
+        vault: PublicKey;
+        userCollateralAta: PublicKey;
+        vaultAuth: PublicKey;
+        depositPda: PublicKey;
+    };
+    /** FlushToInsurance accounts (CPI from stake → percolator) */
+    flushToInsurance: {
+        caller: PublicKey;
+        pool: PublicKey;
+        vault: PublicKey;
+        vaultAuth: PublicKey;
+        slab: PublicKey;
+        wrapperVault: PublicKey;
+        percolatorProgram: PublicKey;
+    };
+}
+/**
+ * Build account keys for InitPool instruction.
+ * Returns array of {pubkey, isSigner, isWritable} in the order the program expects.
+ */
+export declare function initPoolAccounts(a: StakeAccounts['initPool']): {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+}[];
+/**
+ * Build account keys for Deposit instruction.
+ */
+export declare function depositAccounts(a: StakeAccounts['deposit']): {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+}[];
+/**
+ * Build account keys for Withdraw instruction.
+ */
+export declare function withdrawAccounts(a: StakeAccounts['withdraw']): {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+}[];
+/**
+ * Build account keys for FlushToInsurance instruction.
+ */
+export declare function flushToInsuranceAccounts(a: StakeAccounts['flushToInsurance']): {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+}[];

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,45 @@
+/**
+ * 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.
+ */
+export declare function validatePublicKey(value: string, field: string): PublicKey;
+/**
+ * Validate a non-negative integer index (u16 range for accounts).
+ */
+export declare function validateIndex(value: string, field: string): number;
+/**
+ * Validate a non-negative amount (u64 range).
+ */
+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).
+ */
+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

@@ -0,0 +1,45 @@
+{
+  "name": "@percolatorct/sdk",
+  "version": "0.3.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "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"
+  },
+  "dependencies": {
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.95.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.10",
+    "tsup": "^8.3.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dcccrypto/percolator-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}