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 + shadcn/ui (New York) + SWR
UI Components: shadcn/ui + Radix UI primitives
Theme: next-themes（class-based 明暗切换）
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)
Notifications: Discord Webhook
Package Manager: pnpm
Deployment: Docker (multi-stage, node:22-alpine, 不使用 lock 文件)

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     # 设置读写
│       ├── sync/route.ts         # Byreal API 仓位同步
│       └── wallet/balance/route.ts
├── lib/
│   ├── monitor/                  # 监控服务
│   │   ├── index.ts              # MonitorService (WebSocket + 轮询, singleton)
│   │   ├── parser.ts             # TX 解析 (判别符 + 日志 + 事件解码)
│   │   └── types.ts              # ParsedOperation
│   ├── copier/                   # 跟单引擎
│   │   ├── index.ts              # CopyEngine (四种操作调度, USDC+USDT 余额检查)
│   │   ├── price.ts              # Jupiter Price API 价格获取
│   │   ├── ratio.ts              # 金额缩放 (Decimal.js)
│   │   └── swap.ts               # Jupiter Ultra swap (含 USDC↔USDT 互换)
│   ├── 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 等
│   ├── byreal-sync.ts            # Byreal API 仓位同步 (PNL/APR/Fee/Bonus)
│   ├── pool-info.ts              # 池子信息缓存 (1 min TTL)
│   └── config.ts                 # 环境变量加载
├── components/
│   ├── ui/                       # shadcn/ui 组件 (Button, Table, Card, Badge, Input, Select, Switch, AlertDialog, Label, Tooltip)
│   ├── layout/                   # Sidebar & TopBar (含 ThemeToggle)
│   ├── providers.tsx             # ThemeProvider (next-themes, class-based, default dark)
│   └── theme-toggle.tsx          # Sun/Moon 明暗切换按钮
└── lib/utils.ts                  # cn() 工具函数 (clsx + tailwind-merge)

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 策略

开仓/加仓: 检查 USDC+USDT 总余额，不足则跳过；单币不足时自动从对方 ExactOut swap
关仓: ExactIn 模式，将收到的代币全部换回 USDC
稳定币 (USDC, USDT, USD1) 不触发外部 swap，但 USDC↔USDT 可互换

Byreal API 仓位同步

syncFromByrealApi() 从 api2.byreal.io 拉取所有 open 仓位 (status=0, pageSize=200)
通过 nftMintAddress 匹配 DB 中的 our_nft_mint
同步字段: pnl_usd, pnl_percent, apr, bonus_usd, earned_usd, liquidity_usd
APR = (earnedUsd / totalDeposit / ageDays) * 365 * 100
不在 API 响应中的活跃仓位自动标记为 closed
API 返回值为 string 类型，需 Number() 转换后再 .toFixed()

shadcn/ui 组件

使用 New York 风格、Zinc 基色、CSS 变量模式
全局 CSS 变量在 globals.css 中定义亮色 (:root) 和暗色 (.dark) 两套
Tailwind v4 使用 @custom-variant dark (&:is(.dark *)) 启用 dark 变体
Badge 扩展了 success 和 warning 变体

Key Constants

Byreal Program ID: REALQqNEomY6cQGZJUGwywTBD2UmDT32rZcNnfxQ5N2
USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT Mint: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
DB Path: data/copytrade.db
Byreal API: https://api2.byreal.io/byreal/api/dex/v2/position/list

Database Tables

watched_addresses — 监控目标 (address, label, enabled, 单独 multiplier/max_usd)
position_mappings — target_nft_mint(UNIQUE) ↔ our_nft_mint + 同步字段 (pnl_usd, pnl_percent, apr, bonus_usd, earned_usd, liquidity_usd)
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)
DISCORD_WEBHOOK_URL   # Discord 通知 Webhook URL (可选)

Conventions

Singleton 模式: MonitorService, CopyEngine, DB connection, RPC connection
所有链上操作在 src/lib/ server-side 代码中，前端仅通过 API routes 交互
SWR 用于前端数据刷新 (5s 间隔)
错误记录到 copy_history 表 + MonitorService.errorLog (最近 50 条)
Slippage: 减仓/关仓用 99%（宽松，移除自有流动性），开仓/加仓用 2%（保守）
Docker 部署不使用 pnpm-lock.yaml，避免公司内网 registry 问题
地址支持 per-address referrer mode（referer memo）
WebSocket 断线自动重连，超时后回退轮询

AGENTS.md 7.6 KB Link permanente Histórico Em bruto