// contribute

Agent Contribution Guide

Use your AI agent to improve Percolator Launch. Fork, build, submit PRs.

View on GitHub Full Contributing Guide

How It Works

Fork the repository

Clone dcccrypto/percolator-launch to your own GitHub

Point your agent at the code

Give it the architecture context and a specific task

Agent builds on a feature branch

TypeScript must compile clean. Follow the design system.

Submit a PR

Main branch is protected. All changes go through review.

Architecture Context

Copy this into your agent's context window before starting any task:

Percolator Launch — Solana perpetual futures DEX launcher

Stack:
├── app/              Next.js 14 + TypeScript + Tailwind (frontend)
├── packages/server/  Hono backend on Railway (API + crank + oracle)
├── packages/core/    Shared Solana instruction encoding/parsing
├── program/          Solana BPF program (Rust)
├── percolator/       Risk engine crate (Rust)
└── tests/            On-chain TypeScript tests

Design: "Solana Terminal" — #0A0A0F bg, #9945FF purple, #14F195 green
        Monospace fonts, no emojis, terminal/HUD aesthetic

Key concepts:
- Slab = market account (positions, config, engine state)
- Crank = background funding/liquidation processor
- Admin Oracle = devnet manual price push
- Coin-margined = deposit same token you trade
- vAMM = automatic liquidity via matcher program

What To Work On

Easy

Bug Fixes

Fix console errors, null rendering, missing loading states, TypeScript issues, mobile layout

Easy

UI Polish

Better skeletons, animations, accessibility, responsive design, performance

Medium

Backend Features

Trade history indexing, market stats, WebSocket reliability, monitoring dashboards

Hard

Solana Program

Gas optimization, new instructions, security hardening. Requires Rust + BPF toolchain.

Ready-Made Prompts

Bug Hunt

Read the codebase. For each page in app/app/, check:
1. Does data load and display correctly?
2. Are there null/undefined paths that render nothing?
3. Are BigInt values rendered safely?
4. Do error boundaries catch crashes?
5. Are loading and empty states shown?

Report: file, line, severity, description, fix.

Feature Build

Implement [your feature] in percolator-launch.

Rules:
- Branch: agent/[name]/[feature]
- TypeScript clean: npx tsc --noEmit -p app/tsconfig.json
- Use CSS variables from globals.css, not hardcoded colors
- No emojis in UI. Follow Solana Terminal design.
- Write a clear PR description.

Security Audit

Audit [file] line by line for:
1. Exposed secrets or missing auth
2. Logic errors (wrong math, race conditions)
3. Missing error handling
4. Type safety issues (any casts, null checks)
5. Performance problems

Severity + line number + fix for each finding.

PR Guidelines

Branch naming:agent/[name]/[type]/[description]
Small PRs:One feature or fix per PR, not a kitchen sink
Clear description:What changed, why, how to test
TypeScript clean:npx tsc --noEmit must pass with 0 errors
No breaking changes:Don't modify existing API signatures
No secrets:Use environment variables, never hardcode keys

Quick Start

# Fork and clone
gh repo fork dcccrypto/percolator-launch --clone
cd percolator-launch

# Install
pnpm install
cd app && pnpm install && cd ..

# Environment
cp app/.env.example app/.env.local

# Run locally
cd app && pnpm dev

# TypeScript check
npx tsc --noEmit -p app/tsconfig.json

# Run tests (needs devnet SOL)
npx tsx tests/t1-market-boot.ts

Back to Percolator Launch