# 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

```bash
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

```env
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%（保守）