AGENTS.md — Byreal CLMM Copy Trade

Solana 链上 Byreal DEX CLMM 跟单系统。监控目标钱包的集中流动性操作，自动复制 Open / Add / Decrease / Close，支持可配置倍率和金额上限。

Tech Stack

Frontend: Next.js 16 + React 19 + Tailwind CSS 4 + SWR
Backend: Next.js API Routes (server-side only)
Database: SQLite (better-sqlite3, WAL mode)
Blockchain: Solana Web3.js + Anchor 0.31
CLMM SDK: 本地 TypeScript SDK，编译为 CommonJS 后通过 require() 导入
Swap: Jupiter Ultra API (ExactIn / ExactOut)
Package Manager: pnpm

Project Structure

src/
├── app/                          # Next.js App Router
│   ├── page.tsx                  # Dashboard
│   ├── addresses/page.tsx        # 监控地址管理
│   ├── positions/page.tsx        # 仓位映射
│   ├── history/page.tsx          # 操作历史
│   ├── settings/page.tsx         # 全局设置
│   └── api/
│       ├── monitor/{start,stop,status}/  # 监控控制
│       ├── addresses/route.ts    # 地址 CRUD
│       ├── positions/route.ts    # 仓位查询 & 手动关仓
│       ├── history/route.ts      # 历史记录
│       ├── settings/route.ts     # 设置读写
│       └── wallet/balance/route.ts
├── lib/
│   ├── monitor/                  # 监控服务
│   │   ├── index.ts              # MonitorService (WebSocket + 轮询, singleton)
│   │   ├── parser.ts             # TX 解析 (判别符 + 日志 + 事件解码)
│   │   └── types.ts              # ParsedOperation
│   ├── copier/                   # 跟单引擎
│   │   ├── index.ts              # CopyEngine (四种操作调度)
│   │   ├── price.ts              # Jupiter Price API 价格获取
│   │   ├── ratio.ts              # 金额缩放 (Decimal.js)
│   │   └── swap.ts               # Jupiter Ultra swap
│   ├── db/
│   │   ├── index.ts              # SQLite singleton (WAL mode)
│   │   ├── schema.ts             # 4 表 DDL + 自动迁移
│   │   └── queries.ts            # 20+ SQL helpers
│   ├── solana/
│   │   ├── connection.ts         # RPC singleton
│   │   └── wallet.ts             # Keypair & signerCallback
│   ├── clmm-sdk/                 # Byreal CLMM SDK (独立编译)
│   │   ├── src/index.ts          # re-export all
│   │   ├── src/constants.ts      # Program IDs, tick sizes
│   │   ├── src/client/           # Chain class (链上操作)
│   │   ├── src/instructions/     # TX 构建 & 底层布局
│   │   └── src/utils/            # TickMath, SqrtPrice 等
│   ├── pool-info.ts              # 池子信息缓存 (1 min TTL)
│   └── config.ts                 # 环境变量加载
└── components/layout/            # Sidebar & TopBar

Build Process

pnpm install                      # 安装根依赖
pnpm build:sdk                    # tsc 编译 clmm-sdk → dist/
pnpm build                        # build:sdk + next build

重要: clmm-sdk 是独立编译的 CommonJS 包。根 tsconfig.json 通过 exclude 排除了它。copier/index.ts 通过 require('../clmm-sdk/dist/index.js') 导入，而不是 ES import。修改 SDK 源码后必须重新运行 pnpm build:sdk。

Architecture Decisions

SDK 通过 require() 导入

clmm-sdk 编译为 CommonJS ("module": "commonjs")，通过动态 require() 加载，避免 Turbopack 尝试打包 SDK 内部依赖。next.config.ts 中 serverExternalPackages: ['better-sqlite3'] 确保 native 模块不被打包。

双模式监控

WebSocket 订阅 Byreal program logs（confirmed 级别）+ 轮询（5s 间隔）。WebSocket 断线自动回退到轮询。签名去重使用 120s TTL 防止内存泄漏。

仓位映射

通过 position_mappings 表建立 target_nft_mint → our_nft_mint 的映射关系，跨越四种操作类型追踪仓位对应关系。

Swap 策略

开仓/加仓: ExactOut 模式，补齐余额缺口 (额外 2% buffer)
关仓: ExactIn 模式，将收到的代币全部换回 USDC
稳定币 (USDC, USDT, USD1) 不触发 swap

Key Constants

Byreal Program ID: REALQqNEomY6cQGZJUGwywTBD2UmDT32rZcNnfxQ5N2
USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
DB Path: data/copytrade.db

Database Tables

watched_addresses — 监控目标 (address, label, enabled, 单独 multiplier/max_usd)
position_mappings — target_nft_mint(UNIQUE) ↔ our_nft_mint
copy_history — 操作日志 (status: pending/executing/success/failed/skipped)
settings — 全局 key-value 配置

Environment Variables

SOL_ENDPOINT          # RPC endpoint (默认 mainnet-beta)
SOL_SECRET_KEY        # Base58 私钥
JUPITER_API_KEY       # Jupiter API Key
COPY_MULTIPLIER       # 跟单倍率 (默认 1.0)
COPY_MAX_USD          # 单次上限 (默认 1000)
COPY_SLIPPAGE         # 滑点 (默认 0.02)
MONITOR_POLL_INTERVAL # 轮询间隔 ms (默认 5000)

Conventions

Singleton 模式: MonitorService, CopyEngine, DB connection, RPC connection
所有链上操作在 src/lib/ server-side 代码中，前端仅通过 API routes 交互
SWR 用于前端数据刷新 (5s 间隔)
错误记录到 copy_history 表 + MonitorService.errorLog (最近 50 条)
Slippage: 减仓/关仓用 99%（宽松，移除自有流动性），开仓/加仓用 2%（保守）

AGENTS.md 5.5 KB Historik Rå