@percolatorct/sdk 1.0.0-beta.23 → 1.0.0-beta.25

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.
 
-> **⚠️ 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.
+> **EXPERIMENTAL — NOT AUDITED.** `1.0.0-beta.25`. 742 tests passing. Do NOT use with real funds.
 
 [![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)
@@ -434,8 +434,10 @@ const markets = await discoverMarkets(connection);
 
 | Program | Network | Address |
 |---------|---------|---------|
-| Percolator | Mainnet | `GM8zjJ8LTBMv9xEsverh6H6wLyevgMHEJXcEzyY3rY24` |
+| Percolator | Mainnet | `ESa89R5Es3rJ5mnwGybVRG1GrNt9etP11Z5V2QWD4edv` |
 | Matcher | Mainnet | `DHP6DtwXP1yJsz8YzfoeigRFPB979gzmumkmCxDLSkUX` |
+| Stake | Mainnet | `DC5fovFQD5SZYsetwvEqd4Wi4PFY1Yfnc669VMe6oa7F` |
+| NFT | Mainnet | `FqhKJT9gtScjrmfUuRMjeg7cXNpif1fqsy5Jh65tJmTS` |
 | Percolator | Devnet | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` |
 | Matcher | Devnet | `GTRgyTDfrMvBubALAqtHuQwT8tbGyXid7svXZKtWfC9k` |
 
@@ -689,19 +691,26 @@ const markets = await getMarketsByAddress(
 ```bash
 pnpm install              # Install dependencies
 pnpm build                # Build with tsup (outputs to dist/)
-pnpm test                 # Run test suite (vitest)
+pnpm test                 # Run all 742 tests (vitest)
 pnpm lint                 # Type-check (tsc --noEmit)
+pnpm verify-layout        # Verify ABI byte offsets against on-chain layout
 ```
 
 ### Testing
 
-Tests cover ABI encoding roundtrips, PDA derivation, slab parsing, validation, and trading math:
+Tests cover ABI encoding roundtrips, PDA derivation, slab parsing, validation, and trading math. 742 tests, 0 failures.
 
 ```bash
 pnpm test                 # Run all tests
 pnpm test -- --watch      # Watch mode
 ```
 
+### v12.17 Layout Support
+
+The SDK supports the v12.17 slab layout natively via `detectSlabLayout()`. The layout detection function inspects account size to select the correct field offsets for header, config, and per-account data.
+
+A key fix in this version corrects the SBF byte offsets for `d1`/`d2` delta fields that were misaligned in earlier SDK versions. The `parseAllAccounts()` function applies the correct offsets for both devnet (legacy layout) and mainnet (v12.17 layout) slabs automatically.
+
 ### Publishing
 
 ```bash

package/dist/abi/index.d.ts

@@ -2,3 +2,4 @@ export * from "./encode.js";
 export * from "./instructions.js";
 export * from "./accounts.js";
 export * from "./errors.js";
+export * from "./nft.js";

package/dist/abi/instructions.d.ts

@@ -204,12 +204,41 @@ export interface WithdrawCollateralArgs {
 }
 export declare function encodeWithdrawCollateral(args: WithdrawCollateralArgs): Uint8Array;
 /**
- * KeeperCrank instruction data (4 bytes)
- * Funding rate is computed on-chain from LP inventory.
+ * Liquidation policy for KeeperCrank candidates (v12.17 two-phase crank).
+ *
+ * On-chain wire tags:
+ *   0x00 = FullClose — liquidate the entire position
+ *   0x01 = ExactPartial(u128) — reduce position by exactly `quantity` units
+ *   0xFF = TouchOnly — accrue fees / sweep dust, do NOT liquidate
+ */
+export declare const LiquidationPolicyTag: {
+    readonly FullClose: 0;
+    readonly ExactPartial: 1;
+    readonly TouchOnly: 255;
+};
+export type KeeperCrankCandidate = {
+    policy: typeof LiquidationPolicyTag.FullClose;
+    idx: number;
+} | {
+    policy: typeof LiquidationPolicyTag.ExactPartial;
+    idx: number;
+    quantity: bigint | string;
+} | {
+    policy: typeof LiquidationPolicyTag.TouchOnly;
+    idx: number;
+};
+/**
+ * KeeperCrank instruction data (v12.17 two-phase crank).
+ *
+ * Wire format: tag(1) + caller_idx(u16) + format_version=1(u8) +
+ *   candidates: [ idx(u16) + policy_tag(u8) [+ quantity(u128) if ExactPartial] ]*
+ *
+ * Empty candidates list = simple crank (accrue funding, sweep dust).
+ * With candidates = targeted liquidation/touch pass.
  */
 export interface KeeperCrankArgs {
     callerIdx: number;
-    allowPanic: boolean;
+    candidates?: KeeperCrankCandidate[];
 }
 export declare function encodeKeeperCrank(args: KeeperCrankArgs): Uint8Array;
 /**
@@ -243,21 +272,24 @@ export interface TopUpInsuranceArgs {
 }
 export declare function encodeTopUpInsurance(args: TopUpInsuranceArgs): Uint8Array;
 /**
- * TradeCpi instruction data (21 bytes)
+ * TradeCpi instruction data (29 bytes)
+ *
+ * v12.17: limit_price_e6 is now REQUIRED (slippage protection).
+ * Set to 0 to accept any price (no slippage protection).
+ * For buys: tx reverts if execution price > limitPriceE6.
+ * For sells: tx reverts if execution price < limitPriceE6.
  */
 export interface TradeCpiArgs {
     lpIdx: number;
     userIdx: number;
     size: bigint | string;
+    /** Limit price in e6 units. 0 = no limit (accept any price). */
+    limitPriceE6: bigint | string;
 }
 export declare function encodeTradeCpi(args: TradeCpiArgs): Uint8Array;
 /**
- * TradeCpiV2 instruction data (22 bytes) — PERC-154 optimized trade CPI.
- *
- * Same as TradeCpi but includes a caller-provided PDA bump byte.
- * Uses create_program_address instead of find_program_address,
- * saving ~1500 CU per trade. The bump should be obtained once via
- * deriveLpPda() and cached for the lifetime of the market.
+ * @deprecated Tag 35 removed in v12.17. Use TradeCpi (tag 10) with limitPriceE6 instead.
+ * TradeCpi now handles PDA bump internally. Sending tag 35 will fail with InvalidInstructionData.
  */
 export interface TradeCpiV2Args {
     lpIdx: number;
@@ -265,13 +297,24 @@ export interface TradeCpiV2Args {
     size: bigint | string;
     bump: number;
 }
+/** @deprecated Tag 35 removed in v12.17. Use encodeTradeCpi with limitPriceE6 instead. */
 export declare function encodeTradeCpiV2(args: TradeCpiV2Args): Uint8Array;
 /**
- * SetRiskThreshold instruction data (17 bytes)
+ * @deprecated Tag 36 removed in v12.17. Will fail on-chain with InvalidInstructionData.
+ */
+export interface UnresolveMarketArgs {
+    confirmation: bigint | string;
+}
+/** @deprecated Tag 36 removed in v12.17. Will fail on-chain. */
+export declare function encodeUnresolveMarket(args: UnresolveMarketArgs): Uint8Array;
+/**
+ * @deprecated Tag 11 removed in v12.17. Insurance floor is now set at InitMarket.
+ * Sending this instruction will fail with InvalidInstructionData.
  */
 export interface SetRiskThresholdArgs {
     newThreshold: bigint | string;
 }
+/** @deprecated Tag 11 removed in v12.17. Will fail on-chain. */
 export declare function encodeSetRiskThreshold(args: SetRiskThresholdArgs): Uint8Array;
 /**
  * UpdateAdmin instruction data (33 bytes)
@@ -285,31 +328,27 @@ export declare function encodeUpdateAdmin(args: UpdateAdminArgs): Uint8Array;
  */
 export declare function encodeCloseSlab(): Uint8Array;
 /**
- * UpdateConfig instruction data
- * Updates funding and threshold parameters at runtime (admin only)
+ * UpdateConfig instruction data (33 bytes)
+ *
+ * v12.17: Only 4 funding parameters. Threshold/insurance parameters are set
+ * at InitMarket and updated via dedicated instructions (SetRiskThreshold removed).
+ * fundingInvScaleNotionalE6 removed (now computed on-chain from LP state).
  */
 export interface UpdateConfigArgs {
     fundingHorizonSlots: bigint | string;
     fundingKBps: bigint | string;
-    fundingInvScaleNotionalE6: bigint | string;
     fundingMaxPremiumBps: bigint | string;
     fundingMaxBpsPerSlot: bigint | string;
-    threshFloor: bigint | string;
-    threshRiskBps: bigint | string;
-    threshUpdateIntervalSlots: bigint | string;
-    threshStepBps: bigint | string;
-    threshAlphaBps: bigint | string;
-    threshMin: bigint | string;
-    threshMax: bigint | string;
-    threshMinStep: bigint | string;
 }
 export declare function encodeUpdateConfig(args: UpdateConfigArgs): Uint8Array;
 /**
- * SetMaintenanceFee instruction data (17 bytes)
+ * @deprecated Tag 15 removed in v12.17. Maintenance fee is set at InitMarket only.
+ * Sending this instruction will fail with InvalidInstructionData.
  */
 export interface SetMaintenanceFeeArgs {
     newFee: bigint | string;
 }
+/** @deprecated Tag 15 removed in v12.17. Will fail on-chain. */
 export declare function encodeSetMaintenanceFee(args: SetMaintenanceFeeArgs): Uint8Array;
 /**
  * SetOracleAuthority instruction data (33 bytes)
@@ -378,18 +417,16 @@ export interface AdminForceCloseArgs {
 }
 export declare function encodeAdminForceClose(args: AdminForceCloseArgs): Uint8Array;
 /**
- * UpdateRiskParams instruction data (17 or 25 bytes)
- * Update initial and maintenance margin BPS (admin only).
- *
- * R2-S13: The Rust program uses `data.len() >= 25` to detect the optional
- * tradingFeeBps field, so variable-length encoding is safe. When tradingFeeBps
- * is omitted, the data is 17 bytes (tag + 2×u64). When included, 25 bytes.
+ * @deprecated Tag 22 is now SetInsuranceWithdrawPolicy in v12.17.
+ * This encoder sends the WRONG wire format (u64+u64 instead of pubkey+u64+u16+u64).
+ * Use encodeSetInsuranceWithdrawPolicy instead.
  */
 export interface UpdateRiskParamsArgs {
     initialMarginBps: bigint | string;
     maintenanceMarginBps: bigint | string;
     tradingFeeBps?: bigint | string;
 }
+/** @deprecated Use encodeSetInsuranceWithdrawPolicy (tag 22). This sends wrong wire format. */
 export declare function encodeUpdateRiskParams(args: UpdateRiskParamsArgs): Uint8Array;
 /**
  * On-chain confirmation code for RenounceAdmin (must match program constant).
@@ -401,11 +438,9 @@ export declare const RENOUNCE_ADMIN_CONFIRMATION = 5928230587143701317n;
  */
 export declare const UNRESOLVE_CONFIRMATION = 16045690984503054900n;
 /**
- * RenounceAdmin instruction data (9 bytes)
- * Irreversibly set admin to all zeros. After this, all admin-only instructions fail.
- *
- * Requires the confirmation code 0x52454E4F554E4345 ("RENOUNCE" as u64 LE)
- * to prevent accidental invocation.
+ * @deprecated Tag 23 is now WithdrawInsuranceLimited in v12.17.
+ * This encoder sends the confirmation code as a withdrawal amount — DANGEROUS.
+ * Use encodeWithdrawInsuranceLimited instead.
  */
 export declare function encodeRenounceAdmin(): Uint8Array;
 /**
@@ -464,29 +499,15 @@ export declare function encodePauseMarket(): Uint8Array;
  */
 export declare function encodeUnpauseMarket(): Uint8Array;
 /**
- * SetPythOracle (Tag 32) — switch a market to Pyth-pinned mode.
- *
- * After this instruction:
- * - oracle_authority is cleared → PushOraclePrice is disabled
- * - index_feed_id is set to feed_id → validated on every price read
- * - max_staleness_secs and conf_filter_bps are updated
- * - All price reads go directly to read_pyth_price_e6() with on-chain
- *   staleness + confidence + feed-ID validation (no silent fallback)
- *
- * Instruction data: tag(1) + feed_id(32) + max_staleness_secs(8) + conf_filter_bps(2) = 43 bytes
- *
- * Accounts:
- *   0. [signer, writable] Admin
- *   1. [writable]         Slab
+ * @deprecated Tag 32 removed in v12.17. Pyth oracle is configured at InitMarket via indexFeedId.
+ * Sending this instruction will fail with InvalidInstructionData.
  */
 export interface SetPythOracleArgs {
-    /** 32-byte Pyth feed ID. All zeros is invalid (reserved for Hyperp mode). */
     feedId: Uint8Array;
-    /** Maximum age of Pyth price in seconds before OracleStale is returned. Must be > 0. */
     maxStalenessSecs: bigint;
-    /** Max confidence/price ratio in bps (0 = no confidence check). */
     confFilterBps: number;
 }
+/** @deprecated Tag 32 removed in v12.17. Pyth is configured at InitMarket. */
 export declare function encodeSetPythOracle(args: SetPythOracleArgs): Uint8Array;
 /**
  * Derive the expected Pyth PriceUpdateV2 account address for a given feed ID.
@@ -498,18 +519,8 @@ export declare function encodeSetPythOracle(args: SetPythOracleArgs): Uint8Array
 export declare const PYTH_RECEIVER_PROGRAM_ID = "rec5EKMGg6MxZYaMdyBfgwp4d5rB9T1VQH5pJv5LtFJ";
 export declare function derivePythPriceUpdateAccount(feedId: Uint8Array, shardId?: number): Promise<string>;
 /**
- * UpdateMarkPrice (Tag 33) — permissionless EMA mark price crank.
- *
- * Reads the current oracle price on-chain, applies 8-hour EMA smoothing
- * with circuit breaker, and writes result to authority_price_e6.
- *
- * Instruction data: 1 byte (tag only — all params read from on-chain state)
- *
- * Accounts:
- *   0. [writable] Slab
- *   1. []         Oracle account (Pyth PriceUpdateV2 / Chainlink / DEX AMM)
- *   2. []         Clock sysvar (SysvarC1ock11111111111111111111111111111111)
- *   3..N []       Remaining accounts (PumpSwap vaults, etc. if needed)
+ * @deprecated Tag 33 removed in v12.17. Use UpdateHyperpMark (tag 34) for DEX-oracle markets.
+ * Sending this instruction will fail with InvalidInstructionData.
  */
 export declare function encodeUpdateMarkPrice(): Uint8Array;
 /**

package/dist/abi/nft.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Standalone percolator-nft program SDK module.
+ *
+ * This covers the NFT program at `PERCOLATOR_NFT_PROGRAM_ID` which is
+ * separate from the main Percolator program. It handles:
+ *   - MintPositionNft (tag 0)
+ *   - BurnPositionNft (tag 1)
+ *   - SettleFunding   (tag 2)
+ *   - GetPositionValue (tag 3)
+ *   - ExecuteTransferHook (tag 4, SPL interface — not called directly)
+ *   - EmergencyBurn   (tag 5)
+ *
+ * PDA seeds (matches percolator-nft/src/state.rs):
+ *   PositionNft state : ["position_nft",      slab, user_idx_u16_LE]
+ *   PositionNft mint  : ["position_nft_mint", slab, user_idx_u16_LE]
+ *   Mint authority    : ["mint_authority"]
+ */
+import { PublicKey } from "@solana/web3.js";
+/** The standalone percolator-nft program (TransferHook + mint authority). */
+export declare const NFT_PROGRAM_ID: PublicKey;
+export declare function getNftProgramId(): PublicKey;
+export declare const NFT_IX_TAG: {
+    readonly MintPositionNft: 0;
+    readonly BurnPositionNft: 1;
+    readonly SettleFunding: 2;
+    readonly GetPositionValue: 3;
+    readonly ExecuteTransferHook: 4;
+    readonly EmergencyBurn: 5;
+};
+/** Encode MintPositionNft (tag 0). Data: tag(1) + user_idx(2). */
+export declare function encodeNftMint(userIdx: number): Uint8Array;
+/** Encode BurnPositionNft (tag 1). Data: tag(1). */
+export declare function encodeNftBurn(): Uint8Array;
+/** Encode SettleFunding (tag 2). Data: tag(1). */
+export declare function encodeNftSettleFunding(): Uint8Array;
+/** Encode EmergencyBurn (tag 5). Data: tag(1). */
+export declare function encodeNftEmergencyBurn(): Uint8Array;
+type AccountMeta = "s" | "w" | "sw" | "r";
+/**
+ * Account metas for MintPositionNft (tag 0).
+ *
+ *   0. [signer, writable]  payer / position owner
+ *   1. [writable]          PositionNft PDA (created)
+ *   2. [writable, signer]  NFT mint (Token-2022, fresh keypair)
+ *   3. [writable]          Owner's NFT ATA (created)
+ *   4. []                  Slab account
+ *   5. []                  Mint authority PDA
+ *   6. []                  Token-2022 program
+ *   7. []                  Associated token account program
+ *   8. []                  System program
+ *   9. [writable]          ExtraAccountMetaList PDA
+ */
+export declare const ACCOUNTS_NFT_MINT: AccountMeta[];
+/**
+ * Account metas for BurnPositionNft (tag 1).
+ *
+ *   0. [signer]    NFT holder
+ *   1. [writable]  PositionNft PDA (closed)
+ *   2. [writable]  NFT mint (supply → 0)
+ *   3. [writable]  Holder's NFT ATA (closed)
+ *   4. []          Slab account
+ *   5. []          Mint authority PDA
+ *   6. []          Token-2022 program
+ */
+export declare const ACCOUNTS_NFT_BURN: AccountMeta[];
+/**
+ * Account metas for EmergencyBurn (tag 5).
+ *
+ *   0. [signer]    NFT holder
+ *   1. [writable]  PositionNft PDA (closed)
+ *   2. [writable]  NFT mint
+ *   3. [writable]  Holder's NFT ATA
+ *   4. []          Slab account
+ *   5. []          Mint authority PDA
+ *   6. []          Token-2022 program
+ */
+export declare const ACCOUNTS_NFT_EMERGENCY_BURN: AccountMeta[];
+/**
+ * Derive the PositionNft state PDA.
+ * Seeds: ["position_nft", slab, user_idx_u16_LE]
+ */
+export declare function deriveNftPda(slab: PublicKey, userIdx: number, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the PositionNft mint PDA.
+ * Seeds: ["position_nft_mint", slab, user_idx_u16_LE]
+ */
+export declare function deriveNftMint(slab: PublicKey, userIdx: number, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the program-wide mint authority PDA.
+ * Seeds: ["mint_authority"]
+ */
+export declare function deriveMintAuthority(programId?: PublicKey): [PublicKey, number];
+/**
+ * On-chain PositionNft state (208 bytes, matches percolator-nft/src/state.rs).
+ *
+ *   [0..8]     magic             u64
+ *   [8]        version           u8
+ *   [9]        bump              u8
+ *   [10..16]   _pad0
+ *   [16..48]   slab              [u8; 32]
+ *   [48..50]   user_idx          u16 LE
+ *   [50..56]   _pad1
+ *   [56..88]   nft_mint          [u8; 32]
+ *   [88..96]   entry_price_e6    u64
+ *   [96..104]  position_size     u64
+ *   [104]      is_long           u8
+ *   [105..112] _pad2
+ *   [112..128] position_basis_q  i128
+ *   [128..144] last_funding_index_e18  i128
+ *   [144..152] minted_at         i64
+ *   [152..160] account_id        u64
+ *   [160..208] _reserved
+ */
+export declare const POSITION_NFT_STATE_LEN = 208;
+export interface PositionNftState {
+    version: number;
+    bump: number;
+    slab: PublicKey;
+    userIdx: number;
+    nftMint: PublicKey;
+    entryPriceE6: bigint;
+    positionSize: bigint;
+    isLong: boolean;
+    positionBasisQ: bigint;
+    lastFundingIndexE18: bigint;
+    mintedAt: bigint;
+    accountId: bigint;
+}
+/**
+ * Parse a PositionNft account from raw bytes.
+ * @throws if data is shorter than POSITION_NFT_STATE_LEN (208 bytes).
+ */
+export declare function parsePositionNftAccount(data: Uint8Array): PositionNftState;
+export {};

package/dist/config/program-ids.d.ts

@@ -18,7 +18,7 @@ export declare const PROGRAM_IDS: {
     };
     readonly mainnet: {
         readonly percolator: "ESa89R5Es3rJ5mnwGybVRG1GrNt9etP11Z5V2QWD4edv";
-        readonly matcher: "DHP6DtwXP1yJsz8YzfoeigRFPB979gzmumkmCxDLSkUX";
+        readonly matcher: "GDK8wx38kpiSVSfGTVNiSdptX3Z5R4kQyqh6Q3QX6wmi";
     };
 };
 export type Network = "devnet" | "mainnet";