Architecture
Frontend, Express backend, workers, and onchain registry.
Frontend (Vite) Backend (Express + workers)
index.html, src/js/ → backend/src/
├── api/ REST handlers
├── workers/ scheduler-driven engine
│ ├── fee-claimer
│ ├── desk-manager
│ ├── buyback-engine
│ ├── creator-buyback
│ ├── diem-engine
│ ├── desk-risk
│ └── profit-checker
├── services/
│ ├── clanker.ts
│ ├── registry.ts
│ ├── uniswap.ts USDC/WETH/token swaps (v3 + v4)
│ ├── venice.ts LLM desk agent (optional)
│ ├── agent.ts decideDeskEntry
│ ├── market-signal.ts Pyth momentum fallback
│ └── perp/avantis.ts
├── state.ts
└── config.ts
Contracts (Foundry) contracts/src/ProtocolRegistry.solLayer responsibilities
| Layer | Role |
|---|---|
| Frontend | Launch wizard, live dashboard, wallet connect, stats |
| API | Launch/register tokens, expose stats, buybacks, health |
| Workers | Autonomous fee claim, desk management, buybacks, risk |
| Services | Chain I/O — Clanker, Avantis, Uniswap, registry reads |
| Registry | Onchain list of enrolled tokens + (underlying, isLong, leverage) |
| State | In-memory queues and accumulators (reconcile on restart) |
Persistence model
| Data | Where |
|---|---|
| Enrolled tokens, pause status | ProtocolRegistry on Base |
| Open Avantis positions | Avantis TradingStorage onchain |
| Pending perp USDC, buyback queues, desk refs | In memory (state.ts) |
| Worker health | In memory (scheduler.ts) |
On restart, workers re-read registry + Avantis and reconcile desk references. Unclaimed in-memory allocations may be lost — design assumes frequent fee cycles, not long downtime.
Perp venue abstraction
PerpVenue (backend/src/services/perp/PerpVenue.ts) abstracts the venue. The live implementation is avantis.ts — tx-builder API, data API, Pyth prices, USDC collateral.
Swaps are Uniswap on Base (uniswap.ts, univ4.ts) — not 1inch aggregators. Do not wire GMX or Jupiter into workers; swap perp venues by implementing a new PerpVenue adapter.
Protocol wallet
A single hot wallet (PROTOCOL_PRIVATE_KEY) signs:
- Clanker fee claims
- Avantis open/increase/reduce/close (via unsigned txs from tx-builder)
- Uniswap / Universal Router swaps for buybacks
- Token burns to
0x…dEaD
All txs are observable on Basescan.
Repo layout
| Path | Purpose |
|---|---|
pumperp/ | App + contracts (main repo) |
pumperp-docs/ | This documentation site (Fumadocs) |
Docs track implementation, not the historical GMX plan in docs/clanker-base-fork-plan-v7.md.