@percolatorct/sdk 1.0.0-beta.8 → 2.0.0

package/README.md

@@ -2,7 +2,18 @@
 
 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.** `2.0.0`. v12.19 single-target. 792 tests passing. Do NOT use with real funds.
+
+## Target wrapper
+
+The SDK targets the percolator v12.19 wrapper (PR #271, branch `sync/v12.19-wrapper`, commit `d760fc4`).
+All encoders emit v12.19 wire format. The dual-target `target: 'v12.17' | 'v12.19'` parameter
+present in 2.0.0-rc.0 has been removed. PERC-628 shared-vault encoders
+(`InitSharedVault`, `AllocateMarket`, `QueueWithdrawalSV`, `ClaimEpochWithdrawal`,
+`AdvanceEpoch`) are unconditionally enabled.
+
+Slab parsers retain V12_1 / V12_15 / V12_17 layout descriptors for backward-compatible
+reads of older deployments. V12_19 layout descriptor is added for fresh v12.19 slabs.
 
 [![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 +445,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 +702,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/accounts.d.ts

@@ -17,7 +17,15 @@ export declare const ACCOUNTS_INIT_MARKET: readonly AccountSpec[];
  */
 export declare const ACCOUNTS_INIT_USER: readonly AccountSpec[];
 /**
- * InitLP: 5 accounts (clock/oracle removed in commit 410f947)
+ * InitLP: 6 accounts
+ * Program at percolator.rs:6607 calls expect_len(accounts, 6).
+ * The 6th account (accounts[5]) is the clock sysvar — used via Clock::from_account_info.
+ * [0] user         signer, writable (LP owner; pays fee)
+ * [1] slab         writable
+ * [2] userAta      writable (collateral source for fee)
+ * [3] vault        writable (collateral destination)
+ * [4] tokenProgram read-only
+ * [5] clock        read-only (SYSVAR_CLOCK_PUBKEY)
  */
 export declare const ACCOUNTS_INIT_LP: readonly AccountSpec[];
 /**
@@ -33,7 +41,9 @@ export declare const ACCOUNTS_WITHDRAW_COLLATERAL: readonly AccountSpec[];
  */
 export declare const ACCOUNTS_KEEPER_CRANK: readonly AccountSpec[];
 /**
- * TradeNoCpi: 4 accounts (PERC-199: clock sysvar removed — uses Clock::get() syscall)
+ * TradeNoCpi: 5 accounts.
+ * v12.19 wrapper at src/percolator.rs:8484 calls accounts::expect_len(5).
+ * Layout: [user(s+w), lp(s+w), slab(w), clock, oracle].
  */
 export declare const ACCOUNTS_TRADE_NOCPI: readonly AccountSpec[];
 /**
@@ -46,11 +56,13 @@ export declare const ACCOUNTS_LIQUIDATE_AT_ORACLE: readonly AccountSpec[];
  */
 export declare const ACCOUNTS_CLOSE_ACCOUNT: readonly AccountSpec[];
 /**
- * TopUpInsurance: 5 accounts
+ * TopUpInsurance: 6 accounts.
+ * v12.19 wrapper at src/percolator.rs:9256 calls accounts::expect_len(6).
+ * Layout: [user(s+w), slab(w), userAta(w), vault(w), tokenProgram, clock].
  */
 export declare const ACCOUNTS_TOPUP_INSURANCE: readonly AccountSpec[];
 /**
- * TradeCpi: 7 accounts (PERC-199: clock sysvar removed — uses Clock::get() syscall)
+ * TradeCpi: 8 accounts (deployed program expects clock sysvar at index 3)
  */
 export declare const ACCOUNTS_TRADE_CPI: readonly AccountSpec[];
 /**
@@ -62,11 +74,32 @@ export declare const ACCOUNTS_SET_RISK_THRESHOLD: readonly AccountSpec[];
  */
 export declare const ACCOUNTS_UPDATE_ADMIN: readonly AccountSpec[];
 /**
- * CloseSlab: 2 accounts
+ * AcceptAdmin: 2 accounts (tag 82)
+ * Second half of two-step admin transfer. The proposed new admin must sign to
+ * complete the transfer. Program at percolator.rs:7994 calls expect_len(accounts, 2).
+ * [0] pendingAdmin  signer, writable (must match config.pending_admin)
+ * [1] slab          writable
+ */
+export declare const ACCOUNTS_ACCEPT_ADMIN: readonly AccountSpec[];
+/**
+ * CloseSlab: 6 accounts
+ * Drains vault and recovers rent after market is fully resolved and all accounts closed.
+ * Program at percolator.rs:8033 calls expect_len(accounts, 6).
+ * [0] dest            signer, writable (receives rent + drained vault tokens)
+ * [1] slab            writable
+ * [2] vault           writable (token account — drained)
+ * [3] vaultAuthority  read-only (PDA that signs the drain transfer)
+ * [4] destAta         writable (dest's token ATA receiving drained tokens)
+ * [5] tokenProgram    read-only
  */
 export declare const ACCOUNTS_CLOSE_SLAB: readonly AccountSpec[];
 /**
- * UpdateConfig: 2 accounts
+ * UpdateConfig: 3 accounts (canonical) or 4 (with oracle).
+ * v12.19 wrapper at src/percolator.rs:9544 accepts either.
+ * 3-account form: [admin(s+w), slab(w), clock].
+ * 4-account form: [admin(s+w), slab(w), clock, oracle] (used when the wrapper
+ * needs to re-read price during config commit). Default to the 3-account form;
+ * callers that need oracle re-reads should append the oracle account themselves.
  */
 export declare const ACCOUNTS_UPDATE_CONFIG: readonly AccountSpec[];
 /**
@@ -74,23 +107,15 @@ export declare const ACCOUNTS_UPDATE_CONFIG: readonly AccountSpec[];
  */
 export declare const ACCOUNTS_SET_MAINTENANCE_FEE: readonly AccountSpec[];
 /**
- * SetOracleAuthority: 2 accounts
- * Sets the oracle price authority (admin only)
- */
-export declare const ACCOUNTS_SET_ORACLE_AUTHORITY: readonly AccountSpec[];
-/**
- * SetOraclePriceCap: 2 accounts
- * Set oracle price circuit breaker cap (admin only)
+ * SetOraclePriceCap: 3 accounts.
+ * v12.19 wrapper at src/percolator.rs:9654 calls accounts::expect_len(3).
+ * Layout: [admin(s+w), slab(w), clock].
  */
 export declare const ACCOUNTS_SET_ORACLE_PRICE_CAP: readonly AccountSpec[];
 /**
- * PushOraclePrice: 2 accounts
- * Push oracle price (oracle authority only)
- */
-export declare const ACCOUNTS_PUSH_ORACLE_PRICE: readonly AccountSpec[];
-/**
- * ResolveMarket: 2 accounts
- * Resolves a binary/premarket (admin only)
+ * ResolveMarket: 4 accounts.
+ * v12.19 wrapper at src/percolator.rs:9748 calls accounts::expect_len(4).
+ * Layout: [admin(s+w), slab(w), clock, oracle].
  */
 export declare const ACCOUNTS_RESOLVE_MARKET: readonly AccountSpec[];
 /**
@@ -98,6 +123,15 @@ export declare const ACCOUNTS_RESOLVE_MARKET: readonly AccountSpec[];
  * Withdraw insurance fund after market resolution (admin only)
  */
 export declare const ACCOUNTS_WITHDRAW_INSURANCE: readonly AccountSpec[];
+/**
+ * WithdrawInsuranceLimited (tag 23): 7 or 8 accounts.
+ * On live markets the 8th oracle account is REQUIRED (upstream 8ce8d54):
+ * the handler does a same-instruction accrue_market_to against the fresh
+ * oracle price to prevent withdrawals against overstated insurance.
+ * On resolved markets the oracle is frozen — 7 accounts suffice.
+ */
+export declare const ACCOUNTS_WITHDRAW_INSURANCE_LIMITED_RESOLVED: readonly AccountSpec[];
+export declare const ACCOUNTS_WITHDRAW_INSURANCE_LIMITED_LIVE: readonly AccountSpec[];
 /**
  * PauseMarket: 2 accounts
  */
@@ -106,6 +140,40 @@ export declare const ACCOUNTS_PAUSE_MARKET: readonly AccountSpec[];
  * UnpauseMarket: 2 accounts
  */
 export declare const ACCOUNTS_UNPAUSE_MARKET: readonly AccountSpec[];
+/**
+ * ReclaimEmptyAccount (tag 25): 2 accounts. Permissionless.
+ * Wrapper: src/percolator.rs:10470.
+ */
+export declare const ACCOUNTS_RECLAIM_EMPTY_ACCOUNT: readonly AccountSpec[];
+/**
+ * SettleAccount (tag 26): 3 accounts. Permissionless.
+ * Wrapper: src/percolator.rs:10503.
+ */
+export declare const ACCOUNTS_SETTLE_ACCOUNT: readonly AccountSpec[];
+/**
+ * DepositFeeCredits (tag 27): 6 accounts. Owner only.
+ * Wrapper: src/percolator.rs:10557. SPL transfer requires userAta + vault writable.
+ */
+export declare const ACCOUNTS_DEPOSIT_FEE_CREDITS: readonly AccountSpec[];
+/**
+ * ConvertReleasedPnl (tag 28): 4 accounts. Owner only.
+ * Wrapper: src/percolator.rs:10636.
+ */
+export declare const ACCOUNTS_CONVERT_RELEASED_PNL: readonly AccountSpec[];
+/**
+ * SetInsuranceWithdrawPolicy (tag 22): 2 accounts. Admin only.
+ * Wrapper: src/percolator.rs:9990.
+ */
+export declare const ACCOUNTS_SET_INSURANCE_WITHDRAW_POLICY: readonly AccountSpec[];
+/**
+ * UpdateAuthority (tag 83, v12.18.x 4-way split): 3 accounts.
+ * Wrapper: src/percolator.rs:6876.
+ *
+ * Both the current authority and the new authority must sign. For burn
+ * (`new_pubkey == default()`) the new account is still passed but does
+ * not need to sign per wrapper L7036 region.
+ */
+export declare const ACCOUNTS_UPDATE_AUTHORITY: readonly AccountSpec[];
 /**
  * Build AccountMeta array from spec and provided pubkeys.
  *
@@ -117,6 +185,21 @@ export declare const ACCOUNTS_UNPAUSE_MARKET: readonly AccountSpec[];
  * remember the positional order, and errors clearly on missing names.
  */
 export declare function buildAccountMetas(spec: readonly AccountSpec[], keys: PublicKey[] | Record<string, PublicKey>): AccountMeta[];
+/**
+ * CreateInsuranceMint: 9 accounts
+ * Creates SPL mint PDA for insurance LP tokens. Admin only, once per market.
+ */
+export declare const ACCOUNTS_CREATE_INSURANCE_MINT: readonly AccountSpec[];
+/**
+ * DepositInsuranceLP: 8 accounts
+ * Deposit collateral into insurance fund, receive LP tokens.
+ */
+export declare const ACCOUNTS_DEPOSIT_INSURANCE_LP: readonly AccountSpec[];
+/**
+ * WithdrawInsuranceLP: 8 accounts
+ * Burn LP tokens and withdraw proportional share of insurance fund.
+ */
+export declare const ACCOUNTS_WITHDRAW_INSURANCE_LP: readonly AccountSpec[];
 /**
  * LpVaultWithdraw: 10 accounts (tag 39, PERC-627 / GH#1926 / PERC-8287)
  *
@@ -172,6 +255,9 @@ export declare const ACCOUNTS_CANCEL_QUEUED_WITHDRAWAL: readonly AccountSpec[];
  * pass additional oracle accounts at accounts[4..].
  */
 export declare const ACCOUNTS_EXECUTE_ADL: readonly AccountSpec[];
+export declare const ACCOUNTS_RESOLVE_PERMISSIONLESS: readonly AccountSpec[];
+export declare const ACCOUNTS_FORCE_CLOSE_RESOLVED: readonly AccountSpec[];
+export declare const ACCOUNTS_ADMIN_FORCE_CLOSE: readonly AccountSpec[];
 /**
  * CloseStaleSlabs: 2 accounts (tag 51)
  * Admin closes a slab of an invalid/old layout and recovers rent SOL.
@@ -192,16 +278,25 @@ export declare const ACCOUNTS_AUDIT_CRANK: readonly AccountSpec[];
  * Permissionless — no signer required beyond fee payer.
  */
 export declare const ACCOUNTS_ADVANCE_ORACLE_PHASE: readonly AccountSpec[];
-/**
- * TopUpKeeperFund: 3 accounts
- * Permissionless — anyone can fund. Transfers lamports directly (no system program).
- */
-export declare const ACCOUNTS_TOPUP_KEEPER_FUND: readonly AccountSpec[];
+export declare const ACCOUNTS_UPDATE_HYPERP_MARK: readonly AccountSpec[];
+export declare const ACCOUNTS_CREATE_LP_VAULT: readonly AccountSpec[];
+export declare const ACCOUNTS_LP_VAULT_DEPOSIT: readonly AccountSpec[];
+export declare const ACCOUNTS_LP_VAULT_CRANK_FEES: readonly AccountSpec[];
+export declare const ACCOUNTS_CHALLENGE_SETTLEMENT: readonly AccountSpec[];
+export declare const ACCOUNTS_RESOLVE_DISPUTE: readonly AccountSpec[];
+export declare const ACCOUNTS_DEPOSIT_LP_COLLATERAL: readonly AccountSpec[];
+export declare const ACCOUNTS_WITHDRAW_LP_COLLATERAL: readonly AccountSpec[];
+export declare const ACCOUNTS_SET_OFFSET_PAIR: readonly AccountSpec[];
+export declare const ACCOUNTS_ATTEST_CROSS_MARGIN: readonly AccountSpec[];
 /**
  * SetOiImbalanceHardBlock: 2 accounts
  * Sets the OI imbalance hard-block threshold (admin only)
  */
 export declare const ACCOUNTS_SET_OI_IMBALANCE_HARD_BLOCK: readonly AccountSpec[];
+export declare const ACCOUNTS_SET_MAX_PNL_CAP: readonly AccountSpec[];
+export declare const ACCOUNTS_SET_OI_CAP_MULTIPLIER: readonly AccountSpec[];
+export declare const ACCOUNTS_SET_DISPUTE_PARAMS: readonly AccountSpec[];
+export declare const ACCOUNTS_SET_LP_COLLATERAL_PARAMS: readonly AccountSpec[];
 /**
  * MintPositionNft: 10 accounts
  * Creates a Token-2022 position NFT for an open position.
@@ -229,11 +324,20 @@ export declare const ACCOUNTS_SET_PENDING_SETTLEMENT: readonly AccountSpec[];
  * Protected by admin allowlist (GH#1475).
  */
 export declare const ACCOUNTS_CLEAR_PENDING_SETTLEMENT: readonly AccountSpec[];
+export declare const ACCOUNTS_TRANSFER_OWNERSHIP_CPI: readonly AccountSpec[];
 /**
  * SetWalletCap: 2 accounts
  * Sets the per-wallet position cap (admin only). capE6=0 disables.
  */
 export declare const ACCOUNTS_SET_WALLET_CAP: readonly AccountSpec[];
+export declare const ACCOUNTS_RESCUE_ORPHAN_VAULT: readonly AccountSpec[];
+export declare const ACCOUNTS_CLOSE_ORPHAN_SLAB: readonly AccountSpec[];
+/**
+ * SetDexPool: 3 accounts
+ * Admin pins the approved DEX pool address for a HYPERP market.
+ * After this call, UpdateHyperpMark rejects any pool that does not match.
+ */
+export declare const ACCOUNTS_SET_DEX_POOL: readonly AccountSpec[];
 /**
  * InitMatcherCtx: 5 accounts
  * Admin CPI-initializes the matcher context account for an LP slot.

package/dist/abi/errors.d.ts

@@ -19,27 +19,16 @@ export declare function getErrorName(code: number): string;
  * Get actionable hint for error code.
  */
 export declare function getErrorHint(code: number): string | undefined;
-/**
- * Check whether an error code is in the Anchor framework error range
- * (used by Lighthouse, not Percolator).
- */
-export declare function isAnchorErrorCode(code: number): boolean;
 /**
  * Parse error from transaction logs.
  * Looks for "Program ... failed: custom program error: 0x..."
  *
  * Hex capture is bounded (1–8 digits) so pathological logs cannot feed unbounded
  * strings into `parseInt` or produce precision-loss codes above u32.
- *
- * Distinguishes between:
- * - Percolator program errors (codes 0–65): returns Percolator error info
- * - Anchor/Lighthouse errors (codes 0x1770–0x1FFF): returns Lighthouse-specific
- *   name and hint so callers can handle wallet middleware failures
  */
 export declare function parseErrorFromLogs(logs: string[]): {
     code: number;
     name: string;
     hint?: string;
-    source?: "percolator" | "lighthouse" | "unknown";
 } | null;
 export {};

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";