@percolatortool/sdk 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @percolatortool/sdk
+
+TypeScript types and instruction builders for building **Percolator wrapper** programs and frontends.
+
+## Install
+
+```bash
+npm install @percolatortool/sdk
+# or from repo
+npm install ./path/to/percolator-tools/sdk
+```
+
+## Use
+
+```ts
+import {
+  buildDepositInstructionData,
+  buildWithdrawInstructionData,
+  buildExecuteTradeInstructionData,
+  buildKeeperCrankInstructionData,
+  type DepositArgs,
+  type KeeperCrankArgs,
+} from '@percolatortool/sdk';
+
+// Deposit
+const depositData = buildDepositInstructionData({
+  accountIndex: 0,
+  amount: BigInt(1_000_000),
+  nowSlot: 12345,
+});
+
+// Keeper crank (permissionless)
+const crankData = buildKeeperCrankInstructionData({
+  callerIndex: 0,
+  nowSlot: 12345,
+  oraclePrice: 1_000_000,
+  fundingRateBpsPerSlot: 1,
+  allowPanic: false,
+});
+```
+
+Then pass `depositData` / `crankData` as the `data` for a `TransactionInstruction` to your wrapper program ID.
+
+## Note
+
+Instruction **layout** (discriminators, field order) is defined by your **wrapper** program. This SDK uses a minimal layout; if your wrapper uses Anchor or a different layout, adapt the builders or use this as reference.

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Percolator SDK — types and instruction builders for wrapper programs.
+ * Engine does not move tokens; wrapper must do SPL transfers and call engine.
+ *
+ * @see https://github.com/aeyakovenko/percolator
+ */
+export type U128 = {
+    lo: bigint;
+    hi: bigint;
+} | bigint;
+export type I128 = {
+    lo: bigint;
+    hi: bigint;
+} | bigint;
+export interface RiskEngineState {
+    vault: bigint;
+    insuranceBalance: bigint;
+    cTot: bigint;
+    pnlPosTot: bigint;
+    totalOpenInterest: bigint;
+    currentSlot: number;
+    lastCrankSlot: number;
+    fundingIndexQpbE6: bigint;
+    lastFundingSlot: number;
+    fundingRateBpsPerSlotLast: number;
+    lifetimeLiquidations: number;
+    numUsedAccounts: number;
+}
+export interface AccountSummary {
+    accountIndex: number;
+    accountId: number;
+    kind: 'user' | 'lp';
+    capital: bigint;
+    pnl: bigint;
+    positionSize: bigint;
+    entryPrice: number;
+    owner: string;
+}
+export interface DepositArgs {
+    accountIndex: number;
+    amount: bigint;
+    nowSlot: number;
+}
+export interface WithdrawArgs {
+    accountIndex: number;
+    amount: bigint;
+    nowSlot: number;
+    oraclePrice: number;
+}
+export interface ExecuteTradeArgs {
+    lpIndex: number;
+    userIndex: number;
+    nowSlot: number;
+    oraclePrice: number;
+    size: bigint;
+}
+export interface KeeperCrankArgs {
+    callerIndex: number;
+    nowSlot: number;
+    oraclePrice: number;
+    fundingRateBpsPerSlot: number;
+    allowPanic: boolean;
+}
+export declare const INSTRUCTION_NAMES: {
+    readonly deposit: 0;
+    readonly withdraw: 1;
+    readonly executeTrade: 2;
+    readonly keeperCrank: 3;
+    readonly addUser: 4;
+    readonly addLp: 5;
+};
+/**
+ * Build deposit instruction data.
+ * Wrapper must: transfer tokens to vault, then call engine.deposit(idx, amount, now_slot).
+ */
+export declare function buildDepositInstructionData(args: DepositArgs): Buffer;
+/**
+ * Build withdraw instruction data.
+ * Wrapper must: call engine.withdraw(...); if Ok, transfer tokens out of vault.
+ */
+export declare function buildWithdrawInstructionData(args: WithdrawArgs): Buffer;
+/**
+ * Build execute_trade instruction data.
+ * Wrapper must validate signers and oracle, then call engine.execute_trade(...).
+ */
+export declare function buildExecuteTradeInstructionData(args: ExecuteTradeArgs): Buffer;
+/**
+ * Build keeper_crank instruction data.
+ * Permissionless; anyone can call. Wrapper forwards to engine.keeper_crank(...).
+ */
+export declare function buildKeeperCrankInstructionData(args: KeeperCrankArgs): Buffer;

package/dist/index.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Percolator SDK — types and instruction builders for wrapper programs.
+ * Engine does not move tokens; wrapper must do SPL transfers and call engine.
+ *
+ * @see https://github.com/aeyakovenko/percolator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUCTION_NAMES = void 0;
+exports.buildDepositInstructionData = buildDepositInstructionData;
+exports.buildWithdrawInstructionData = buildWithdrawInstructionData;
+exports.buildExecuteTradeInstructionData = buildExecuteTradeInstructionData;
+exports.buildKeeperCrankInstructionData = buildKeeperCrankInstructionData;
+// -----------------------------------------------------------------------------
+// Instruction discriminators (wrapper-specific; replace with your program's)
+// -----------------------------------------------------------------------------
+exports.INSTRUCTION_NAMES = {
+    deposit: 0x00,
+    withdraw: 0x01,
+    executeTrade: 0x02,
+    keeperCrank: 0x03,
+    addUser: 0x04,
+    addLp: 0x05,
+};
+// -----------------------------------------------------------------------------
+// Instruction builders (serialize args for CPI; layout is wrapper-defined)
+// -----------------------------------------------------------------------------
+function encodeU64(n) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(BigInt(n));
+    return b;
+}
+function encodeU128(n) {
+    const b = Buffer.alloc(16);
+    b.writeBigUInt64LE(n & BigInt('0xffffffffffffffff'), 0);
+    b.writeBigUInt64LE(n >> BigInt(64), 8);
+    return b;
+}
+function encodeI128(n) {
+    const b = Buffer.alloc(16);
+    const lo = n & BigInt('0xffffffffffffffff');
+    const hi = n >> BigInt(64);
+    b.writeBigUInt64LE(lo >= 0 ? lo : lo + BigInt(1) << BigInt(64), 0);
+    b.writeBigInt64LE(hi, 8);
+    return b;
+}
+/**
+ * Build deposit instruction data.
+ * Wrapper must: transfer tokens to vault, then call engine.deposit(idx, amount, now_slot).
+ */
+function buildDepositInstructionData(args) {
+    const parts = [
+        Buffer.from([exports.INSTRUCTION_NAMES.deposit]),
+        encodeU64(args.accountIndex),
+        encodeU128(args.amount),
+        encodeU64(args.nowSlot),
+    ];
+    return Buffer.concat(parts);
+}
+/**
+ * Build withdraw instruction data.
+ * Wrapper must: call engine.withdraw(...); if Ok, transfer tokens out of vault.
+ */
+function buildWithdrawInstructionData(args) {
+    const parts = [
+        Buffer.from([exports.INSTRUCTION_NAMES.withdraw]),
+        encodeU64(args.accountIndex),
+        encodeU128(args.amount),
+        encodeU64(args.nowSlot),
+        encodeU64(args.oraclePrice),
+    ];
+    return Buffer.concat(parts);
+}
+/**
+ * Build execute_trade instruction data.
+ * Wrapper must validate signers and oracle, then call engine.execute_trade(...).
+ */
+function buildExecuteTradeInstructionData(args) {
+    const size = BigInt(args.size);
+    const parts = [
+        Buffer.from([exports.INSTRUCTION_NAMES.executeTrade]),
+        encodeU64(args.lpIndex),
+        encodeU64(args.userIndex),
+        encodeU64(args.nowSlot),
+        encodeU64(args.oraclePrice),
+        encodeI128(size),
+    ];
+    return Buffer.concat(parts);
+}
+/**
+ * Build keeper_crank instruction data.
+ * Permissionless; anyone can call. Wrapper forwards to engine.keeper_crank(...).
+ */
+function buildKeeperCrankInstructionData(args) {
+    const parts = [
+        Buffer.from([exports.INSTRUCTION_NAMES.keeperCrank]),
+        encodeU64(args.callerIndex),
+        encodeU64(args.nowSlot),
+        encodeU64(args.oraclePrice),
+        encodeI128(BigInt(args.fundingRateBpsPerSlot)),
+        Buffer.from([args.allowPanic ? 1 : 0]),
+    ];
+    return Buffer.concat(parts);
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@percolatortool/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Percolator wrapper builders",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.87.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,169 @@
+/**
+ * Percolator SDK — types and instruction builders for wrapper programs.
+ * Engine does not move tokens; wrapper must do SPL transfers and call engine.
+ *
+ * @see https://github.com/aeyakovenko/percolator
+ */
+
+// -----------------------------------------------------------------------------
+// Types (align with engine state where useful for builders)
+// -----------------------------------------------------------------------------
+
+export type U128 = { lo: bigint; hi: bigint } | bigint;
+export type I128 = { lo: bigint; hi: bigint } | bigint;
+
+export interface RiskEngineState {
+  vault: bigint;
+  insuranceBalance: bigint;
+  cTot: bigint;
+  pnlPosTot: bigint;
+  totalOpenInterest: bigint;
+  currentSlot: number;
+  lastCrankSlot: number;
+  fundingIndexQpbE6: bigint;
+  lastFundingSlot: number;
+  fundingRateBpsPerSlotLast: number;
+  lifetimeLiquidations: number;
+  numUsedAccounts: number;
+}
+
+export interface AccountSummary {
+  accountIndex: number;
+  accountId: number;
+  kind: 'user' | 'lp';
+  capital: bigint;
+  pnl: bigint;
+  positionSize: bigint;
+  entryPrice: number;
+  owner: string;
+}
+
+export interface DepositArgs {
+  accountIndex: number;
+  amount: bigint;
+  nowSlot: number;
+}
+
+export interface WithdrawArgs {
+  accountIndex: number;
+  amount: bigint;
+  nowSlot: number;
+  oraclePrice: number;
+}
+
+export interface ExecuteTradeArgs {
+  lpIndex: number;
+  userIndex: number;
+  nowSlot: number;
+  oraclePrice: number;
+  size: bigint;
+}
+
+export interface KeeperCrankArgs {
+  callerIndex: number;
+  nowSlot: number;
+  oraclePrice: number;
+  fundingRateBpsPerSlot: number;
+  allowPanic: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// Instruction discriminators (wrapper-specific; replace with your program's)
+// -----------------------------------------------------------------------------
+
+export const INSTRUCTION_NAMES = {
+  deposit: 0x00,
+  withdraw: 0x01,
+  executeTrade: 0x02,
+  keeperCrank: 0x03,
+  addUser: 0x04,
+  addLp: 0x05,
+} as const;
+
+// -----------------------------------------------------------------------------
+// Instruction builders (serialize args for CPI; layout is wrapper-defined)
+// -----------------------------------------------------------------------------
+
+function encodeU64(n: number): Buffer {
+  const b = Buffer.alloc(8);
+  b.writeBigUInt64LE(BigInt(n));
+  return b;
+}
+
+function encodeU128(n: bigint): Buffer {
+  const b = Buffer.alloc(16);
+  b.writeBigUInt64LE(n & BigInt('0xffffffffffffffff'), 0);
+  b.writeBigUInt64LE(n >> BigInt(64), 8);
+  return b;
+}
+
+function encodeI128(n: bigint): Buffer {
+  const b = Buffer.alloc(16);
+  const lo = n & BigInt('0xffffffffffffffff');
+  const hi = n >> BigInt(64);
+  b.writeBigUInt64LE(lo >= 0 ? lo : lo + BigInt(1) << BigInt(64), 0);
+  b.writeBigInt64LE(hi, 8);
+  return b;
+}
+
+/**
+ * Build deposit instruction data.
+ * Wrapper must: transfer tokens to vault, then call engine.deposit(idx, amount, now_slot).
+ */
+export function buildDepositInstructionData(args: DepositArgs): Buffer {
+  const parts = [
+    Buffer.from([INSTRUCTION_NAMES.deposit]),
+    encodeU64(args.accountIndex),
+    encodeU128(args.amount),
+    encodeU64(args.nowSlot),
+  ];
+  return Buffer.concat(parts);
+}
+
+/**
+ * Build withdraw instruction data.
+ * Wrapper must: call engine.withdraw(...); if Ok, transfer tokens out of vault.
+ */
+export function buildWithdrawInstructionData(args: WithdrawArgs): Buffer {
+  const parts = [
+    Buffer.from([INSTRUCTION_NAMES.withdraw]),
+    encodeU64(args.accountIndex),
+    encodeU128(args.amount),
+    encodeU64(args.nowSlot),
+    encodeU64(args.oraclePrice),
+  ];
+  return Buffer.concat(parts);
+}
+
+/**
+ * Build execute_trade instruction data.
+ * Wrapper must validate signers and oracle, then call engine.execute_trade(...).
+ */
+export function buildExecuteTradeInstructionData(args: ExecuteTradeArgs): Buffer {
+  const size = BigInt(args.size);
+  const parts = [
+    Buffer.from([INSTRUCTION_NAMES.executeTrade]),
+    encodeU64(args.lpIndex),
+    encodeU64(args.userIndex),
+    encodeU64(args.nowSlot),
+    encodeU64(args.oraclePrice),
+    encodeI128(size),
+  ];
+  return Buffer.concat(parts);
+}
+
+/**
+ * Build keeper_crank instruction data.
+ * Permissionless; anyone can call. Wrapper forwards to engine.keeper_crank(...).
+ */
+export function buildKeeperCrankInstructionData(args: KeeperCrankArgs): Buffer {
+  const parts = [
+    Buffer.from([INSTRUCTION_NAMES.keeperCrank]),
+    encodeU64(args.callerIndex),
+    encodeU64(args.nowSlot),
+    encodeU64(args.oraclePrice),
+    encodeI128(BigInt(args.fundingRateBpsPerSlot)),
+    Buffer.from([args.allowPanic ? 1 : 0]),
+  ];
+  return Buffer.concat(parts);
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}