Skip to main content
Repository: purpletrade/percolator-cli · License: Apache 2.0 · Language: TypeScript · Runtime: Node.js / tsx

​
What It Does

percolator-cli is a comprehensive command-line tool for interacting with the Percolator protocol on Solana. It supports all protocol operations: account management, trading, keeper cranking, LP setup, market analysis, and stress testing.

​
Installation

pnpm install
pnpm build

​
Configuration

Create ~/.config/percolator-cli.json: 
{
  "rpcUrl": "https://api.devnet.solana.com",
  "programId": "2SSnp35m7FQ7cRLNKGdW5UzjYFF6RBUNq7d3m5mqNByp",
  "walletPath": "~/.config/solana/id.json"
}
Or use flags: --rpc, --program, --wallet, --json, --simulate.

​
Commands

​
User Operations

# Initialize user account
percolator-cli init-user --slab <pubkey>

# Deposit / withdraw collateral
percolator-cli deposit --slab <pubkey> --user-idx <n> --amount <lamports>
percolator-cli withdraw --slab <pubkey> --user-idx <n> --amount <lamports>

# Trade via matcher CPI
percolator-cli trade-cpi --slab <pubkey> --user-idx <n> --lp-idx <n> \
  --size <i128> --matcher-program <pubkey> --matcher-ctx <pubkey> --oracle <pubkey>

# Trade without matcher (testing)
percolator-cli trade-nocpi --slab <pubkey> --user-idx <n> --lp-idx <n> \
  --size <i128> --oracle <pubkey>

# Close account
percolator-cli close-account --slab <pubkey> --idx <n>

​
Keeper Operations

# Run keeper crank (permissionless)
percolator-cli keeper-crank --slab <pubkey> --oracle <pubkey>

# Check best LP prices before trading
percolator-cli best-price --slab <pubkey> --oracle <pubkey>
Risk-increasing trades require a recent keeper crank — within the last 200 slots (~80 seconds). Run the crank before trading or use the crank bot for continuous operation.

​
LP Operations

# Initialize LP account
percolator-cli init-lp --slab <pubkey>

# Deposit collateral to LP
percolator-cli deposit --slab <pubkey> --user-idx <lp-idx> --amount <lamports>

​
Admin Operations

# Rotate admin
percolator-cli update-admin --slab <pubkey> --new-admin <pubkey>

# Set risk threshold
percolator-cli set-risk-threshold --slab <pubkey> --threshold-bps <n>

# Oracle authority (push custom prices)
percolator-cli set-oracle-authority --slab <pubkey> --authority <pubkey>
percolator-cli push-oracle-price --slab <pubkey> --price <usd>

# Update market configuration
percolator-cli update-config --slab <pubkey> --funding-horizon-slots <n> ...

​
Market Analysis

# View slab state
percolator-cli slab:get --slab <pubkey>
percolator-cli slab:header --slab <pubkey>
percolator-cli slab:config --slab <pubkey>

# Dump full market state to JSON
npx tsx scripts/dump-state.ts
npx tsx scripts/dump-market.ts

# Check liquidation risk / funding / parameters
npx tsx scripts/check-liquidation.ts
npx tsx scripts/check-funding.ts
npx tsx scripts/check-params.ts

# Find user account by owner
npx tsx scripts/find-user.ts <slab> <owner>

​
Bots & Scripts

​
Keeper Bot

Continuous crank every 5 seconds: 
npx tsx scripts/crank-bot.ts

​
Random Traders

Simulates 5 traders with momentum bias, routing to the best LP by price: 
npx tsx scripts/random-traders.ts

​
LP Setup

Create a vAMM-configured LP with matcher context + deposit: 
npx tsx scripts/add-vamm-lp.ts

​
Market Setup

Full devnet market with funded LP and insurance: 
npx tsx scripts/setup-devnet-market.ts

​
Stress Testing & Security

The CLI includes comprehensive stress tests and penetration testing scripts:
ScriptWhat it tests
stress-haircut-system.tsConservation, insurance fund, undercollateralization
stress-worst-case.tsGap risk, insurance exhaustion, socialized losses
oracle-authority-stress.tsPrice manipulation scenarios
pentest-oracle.tsFlash crash, price edges, timestamp attacks, funding manipulation
test-price-profit.tsPrice-profit relationship validation
test-threshold-increase.tsAuto-threshold adjustment verification
test-lp-profit-realize.tsLP profit realization and withdrawal
test-profit-withdrawal.tsProfit withdrawal limit enforcement

​
Testing

# Unit tests
pnpm test

# Devnet integration
./test-vectors.sh

# Live trading test (with PnL validation)
npx tsx tests/t21-live-trading.ts 3             # 3 minutes
npx tsx tests/t21-live-trading.ts 3 --inverted  # inverted market

​
Original Source

Forked from aeyakovenko/percolator-cli.

View Repository

Full CLI source, scripts, bots, and stress tests