my_solana_bot/README.md

# 🎯 Pump.fun Sniper Bot

Pump.fun 新币狙击交易机器人 — 基于 Bonding Curve 数学模型的自动化交易系统。

## ⚠️ 风险警告

> **本项目仅供学习和研究使用。链上交易存在极高风险，99%+ 的 Pump.fun 代币归零。
> 永远不要投入你无法承受全部损失的资金。**

---

## 一、系统架构

| Layer | 模块 | 职责 |
|-------|------|------|
| 1 | 事件检测 (detection/) | Yellowstone gRPC / RPC 轮询 → 新币创建 / 进度更新 / 毕业 |
| 2 | 决策引擎 (decision/) | Rug 过滤 → 信号评分 → 仓位计算 → GO/NO-GO |
| 3 | 交易执行 (execution/) | 交易构建 → 模拟预检 → 多中继提交 (RPC + Jito) |
| 4 | 仓位管理 (position/) | 止盈(分批) → 止损 → 时间止损 → 毕业处理 |
| 5 | 风控 (risk/) | 熔断器 → 日亏损限制 → 连续失败保护 |
| 6 | 监控 (monitoring/) | Prometheus 指标 → 日志 → 告警 |

---

## 二、环境要求

### 2.1 系统要求

| 组件 | 最低要求 | 推荐 |
|------|---------|------|
| OS | Linux (Ubuntu 22.04+) / Windows 11 | Linux 裸金属 |
| CPU | 4 核 | 8 核+ (低延迟) |
| RAM | 8 GB | 16 GB+ |
| 磁盘 | 20 GB SSD | NVMe SSD |
| 网络 | 100 Mbps | 1 Gbps+ (共置) |

### 2.2 软件要求

| 软件 | 版本 | 安装方式 |
|------|------|---------|
| **Rust** | 1.75+ | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
| **Solana CLI** | 1.18+ | `sh -c "$(curl -sSfL https://release.solana.com/stable/install)"` |
| **Git** | 2.0+ | 系统包管理器 |

### 2.3 Rust 工具链安装

```bash
# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 验证
rustc --version   # >= 1.75
cargo --version

# 安装 Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
solana --version
```

## 三、安装步骤

### 3.1 克隆项目

```bash
cd pumpfun-sniper-bot
```

### 3.2 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 填入真实配置
```

### 3.3 配置 TOML

```bash
# 编辑 config/mainnet.toml
# 关键配置项:
# - detection.yellowstone_grpc_url: 你的 gRPC 端点
# - execution.rpc_url: 你的 RPC 端点
# - execution.jito_block_engine_url: Jito 端点
# - position.max_position_sol: 单次最大仓位
# - risk.daily_loss_limit_sol: 日亏损限制
```

### 3.4 创建钱包

```bash
# 创建钱包目录
mkdir -p wallets

# 生成钱包 (建议 3-5 个轮换)
solana-keygen new -o wallets/wallet_0.json
solana-keygen new -o wallets/wallet_1.json
solana-keygen new -o wallets/wallet_2.json

# 查看地址
solana-keygen pubkey wallets/wallet_0.json

# 转入 SOL (仅使用你能承受损失的资金!)
solana transfer <wallet_address> 1.0 --url mainnet-beta
```

### 3.5 编译

```bash
# 开发编译
cargo build

# 生产编译 (优化)
cargo build --release

# 运行测试
cargo test

# 运行基准测试
cargo bench
```

### 3.6 运行

```bash
# 开发模式 (dry_run = true, 不实际交易)
cargo run -- config/mainnet.toml

# 生产模式 (修改 config 中 dry_run = false)
./target/release/sniper config/mainnet.toml
```

## 四、SDK 安装 (后期)

当前项目使用内置实现，不依赖外部 SDK。当你准备好后，可以安装以下 SDK 获得更好的性能：

### 4.1 sol-trade-sdk (交易构建)

```bash
# Cargo.toml 中取消注释:
sol-trade-sdk = "2.0"
```

安装后替换 `src/execution/tx_builder.rs` 中的手动指令构建为：

```rust
use sol_trade_sdk::protocols::pumpfun::{self, PumpFunBuyParams};

let params = PumpFunBuyParams {
    bonding_curve: bonding_curve_pubkey,
    user: wallet.pubkey(),
    mint: mint_pubkey,
    sol_amount: lamports,
    slippage_bps,
};
let buy_ix = pumpfun::build_buy(&params)?;
```

### 4.2 solana-streamer-sdk (事件流)

```bash
# Cargo.toml 中取消注释:
solana-streamer-sdk = { version = "2.0", features = ["sdk-parse-zero-copy"] }
```

安装后替换 `src/detection/streamer.rs` 中的 RPC 轮询为 gRPC 流：

```rust
use solana_streamer_sdk::prelude::*;

let streamer = SolanaStreamer::builder()
    .grpc_endpoint(&config.yellowstone_grpc_url)
    .x_token(config.yellowstone_x_token.as_deref())
    .subscribe_program(PUMP_FUN_PROGRAM_ID)
    .order_mode(OrderMode::Unordered)
    .build()?;
```

## 五、配置说明

### 5.1 关键参数

| 参数 | 默认值 | 说明 | 建议 |
|------|-------|------|------|
| bot.mode | "sniper" | 运行模式 | 新手用 "sniper" |
| bot.dry_run | true | 模拟模式 | 首次必须 true |
| position.max_position_sol | 0.1 | 单次最大仓位 | 总资金的 1-2% |
| position.stop_loss_pct | 0.3 | 止损比例 | 30% |
| risk.daily_loss_limit_sol | 1.0 | 日亏损限制 | 总资金的 5% |
| risk.max_consecutive_failures | 5 | 熔断阈值 | 5 次 |
| decision.min_score_threshold | 60.0 | 最低评分 | 60-70 |
| decision.slippage_bps | 1000 | 滑点 (10%) | 新币需要高滑点 |

### 5.2 推荐 RPC 服务

| 服务 | 用途 | 价格 |
|------|------|------|
| Helius | RPC + gRPC | $49-$499/月 |
| QuickNode | RPC | $49-$299/月 |
| Triton | Yellowstone gRPC | 联系销售 |
| Jito | Block Engine | 免费 (tip 另算) |

## 六、项目结构

```
pumpfun-sniper-bot/
├── Cargo.toml                    # 项目配置
├── .env.example                  # 环境变量模板
├── README.md                     # 本文档
├── config/
│   └── mainnet.toml              # 主网配置
├── wallets/                      # 钱包文件 (不要提交到 git!)
│   ├── wallet_0.json
│   ├── wallet_1.json
│   └── wallet_2.json
├── scripts/                      # 辅助脚本
├── src/
│   ├── main.rs                   # 主入口 + 事件循环
│   ├── config.rs                 # 配置加载
│   ├── error.rs                  # 统一错误类型
│   ├── bonding_curve/            # Bonding Curve 数学模型
│   │   ├── mod.rs
│   │   ├── math.rs               # 核心公式 (含测试)
│   │   ├── account.rs            # 链上账户解析 (含测试)
│   │   └── simulator.rs          # 交易模拟器 (含测试)
│   ├── detection/                # 事件检测
│   │   ├── mod.rs
│   │   ├── streamer.rs           # gRPC / RPC 事件流
│   │   └── bonding_curve_monitor.rs  # 曲线状态监控
│   ├── decision/                 # 决策引擎
│   │   ├── mod.rs
│   │   ├── rug_filter.rs         # Rug Pull 过滤
│   │   ├── scorer.rs             # 信号评分
│   │   └── position_sizer.rs     # 仓位计算
│   ├── execution/                # 交易执行
│   │   ├── mod.rs
│   │   ├── tx_builder.rs         # 交易构建
│   │   ├── submitter.rs          # 多中继提交
│   │   └── jito.rs               # Jito Bundle
│   ├── position/                 # 仓位管理
│   │   ├── mod.rs
│   │   ├── manager.rs            # 仓位管理器
│   │   └── exit_strategy.rs      # 退出策略
│   ├── risk/                     # 风控
│   │   ├── mod.rs
│   │   └── circuit_breaker.rs    # 熔断器
│   └── monitoring/               # 监控
│       ├── mod.rs
│       └── metrics.rs            # Prometheus 指标
└── tests/                        # 集成测试
```

## 七、开发路线图

| 阶段 | 状态 | 内容 |
|------|------|------|
| Phase 1: 数学模型 | ✅ | Bonding Curve 公式 + 账户解析 + 模拟器 |
| Phase 2: 事件检测 | ✅ | RPC 轮询 (gRPC 待 SDK 安装) |
| Phase 3: 决策引擎 | ✅ | Rug 过滤 + 评分 + 仓位计算 |
| Phase 4: 交易执行 | ✅ | 交易构建 + 多中继 + Jito |
| Phase 5: 仓位管理 | ✅ | 止盈止损 + 退出策略 |
| Phase 6: 风控 | ✅ | 熔断器 + 日亏损限制 |
| Phase 7: 监控 | ✅ | Prometheus + 日志 |
| Phase 8: SDK 集成 | ⏳ | 安装 sol-trade-sdk + solana-streamer-sdk |
| Phase 9: 优化 | ⏳ | 预构建模板 + PDA 缓存 + 延迟优化 |
| Phase 10: 实盘 | ⏳ | Devnet 测试 → Mainnet 小资金 |

## 八、安全注意事项

- 永远不要将 `wallets/` 目录提交到 Git
- 永远不要在代码中硬编码私钥
- 永远先在 devnet 测试 2 周以上
- 永远先使用 `dry_run = true` 验证逻辑
- 永远设置日亏损限制和熔断器
- 定期检查钱包余额和交易记录

```gitignore
# .gitignore 必须包含:
wallets/
.env
*.json  # 钱包文件
```

## 九、常见问题

**Q:** 编译报错 solana-sdk 版本冲突？
**A:** 确保 solana-sdk 和 solana-client 版本一致 (都是 3.x)。

**Q:** 如何获取 Yellowstone gRPC 端点？
**A:** 推荐使用 Triton 或 Helius 的 gRPC 服务。

**Q:** Jito tip 应该设多少？
**A:** 起步 10,000 lamports (0.00001 SOL)，根据网络拥堵动态调整。

**Q:** 为什么 dry_run 模式下交易不发送？
**A:** 这是安全设计。确认策略逻辑正确后，将 bot.dry_run 改为 false。

## 十、许可证

MIT License - 仅供学习研究，使用风险自担。

---

## 19. `.gitignore`

```gitignore
# 钱包 (绝对不能提交!)
wallets/
*.json
!Cargo.lock

# 环境变量
.env

# 编译产物
target/

# IDE
.idea/
.vscode/
*.swp
*.swo

# 日志
logs/
*.log

# OS
.DS_Store
Thumbs.db
```

## 总结

- 安装 Rust 工具链：rustup + cargo
- 编译验证：cargo build 确认无编译错误
- 运行测试：cargo test 确认数学模型正确
- 配置环境：复制 .env.example → .env，填入你的 RPC/gRPC 端点
- Dry Run：cargo run -- config/mainnet.toml（默认 dry_run=true）
- 后期安装 sol-trade-sdk 和 solana-streamer-sdk 后，只需替换 tx_builder.rs 和 streamer.rs 中标记了 TODO 的部分即可。架构不需要改动。