forgex-cli 1.0.0

package/README.md

@@ -0,0 +1,479 @@
+# ForgeX CLI
+
+Solana 链上做市系统命令行工具。
+
+ForgeX CLI 提供完整的 Solana 链上做市操作能力，包括多钱包组管理、批量交易、专业做市工具（换手/刷量/价格机器人）、代币创建与查询、批量转账等功能。支持多 DEX 协议和 Jito MEV 保护。
+
+## 功能特性
+
+- **多钱包组管理** -- 创建/删除钱包组，批量生成钱包，靓号地址生成（自定义后缀/前缀），CSV/JSON 导入导出，AES 加密存储私钥
+- **批量交易** -- 多钱包同时买入/卖出，支持百分比卖出、全部卖出、狙击买入
+- **专业做市工具** -- 换手交易（Jito Bundle 零滑点）、刷量工具（5 种模式）、价格机器人（自动拉升/砸盘）
+- **多 DEX 支持** -- Pump.fun、PumpSwap、Raydium V4/CPMM、LaunchLab
+- **Jito MEV 保护** -- 交易捆绑发送，防止夹子攻击
+- **代币创建** -- 支持 Pump.fun / LaunchLab 发币，IPFS 元数据上传，开盘狙击
+- **链上查询** -- 余额、价格、K 线、交易记录、持仓监控
+- **外盘抢筹** -- Pump 外盘抢筹、Bonk 外盘抢筹
+- **批量转账** -- 收集（多对一）、分发（一对多）、多对多转账
+- **交易追踪** -- 自动追踪交易结果，持久化持仓和盈亏数据
+- **灵活输出** -- 支持 JSON / Table / Minimal 三种输出格式
+
+## 安装
+
+### 环境要求
+
+- Node.js >= 22.14.0
+- npm
+- solana-keygen（仅靓号生成功能需要，可选）
+
+### 安装步骤
+
+```bash
+cd cli
+npm install
+npm run build
+```
+
+安装完成后可通过以下方式运行：
+
+```bash
+# 开发模式（tsx 直接运行 TypeScript）
+npm run dev -- <command>
+
+# 编译后运行
+node dist/bin/forgex.js <command>
+
+# 全局链接后
+npm link
+forgex <command>
+```
+
+## 快速上手
+
+### 1. 初始化配置
+
+```bash
+# 创建默认配置文件 (~/.forgex/config.json)
+forgex config init
+
+# 设置 RPC 节点（推荐付费节点）
+forgex config set rpcUrl https://your-rpc-url.com
+
+# 设置 Codex API Key（代币信息和价格查询）
+forgex config set codexApiKey your-codex-api-key
+
+# 设置 API Token
+forgex config set apiToken your-api-token
+
+# 查看当前配置
+forgex config list
+```
+
+### 2. 创建钱包组并生成钱包
+
+```bash
+# 创建本地钱包组
+forgex wallet create-group --name "做市组A"
+
+# 生成 5 个新钱包（首次使用需设置加密密码）
+forgex wallet generate --group 1 --count 5
+
+# 查看钱包组详情
+forgex wallet group-info --id 1
+
+# 列出所有钱包组
+forgex wallet list-groups --format table
+```
+
+### 3. 分发 SOL 到钱包
+
+```bash
+# 从主钱包向钱包组每个钱包分发 0.1 SOL
+forgex transfer out --from <主钱包地址> --to-group 1 --value 0.1
+
+# 模拟分发（不实际执行，检查余额是否充足）
+forgex transfer out --from <主钱包地址> --to-group 1 --value 0.1 --dry-run
+```
+
+### 4. 执行交易
+
+```bash
+# 批量买入（每个钱包买入 0.01 SOL 的代币）
+forgex trade buy --group 1 --token <代币CA> --amount 0.01
+
+# 全部卖出
+forgex trade sell --group 1 --token <代币CA> --amount all
+
+# 卖出 50%
+forgex trade sell --group 1 --token <代币CA> --amount 50%
+
+# 狙击买入（指定每个钱包不同金额）
+forgex trade sniper --group 1 --token <代币CA> --amounts 0.1,0.2,0.15
+```
+
+### 5. 使用做市工具
+
+```bash
+# 刷量（1买1卖模式，执行 3 轮）
+forgex tools volume --group 1 --token <代币CA> --mode 1b1s --amount 0.01 --rounds 3
+
+# 换手交易（组A -> 组B）
+forgex tools turnover --from-group 1 --to-group 2 --token <代币CA>
+
+# 价格机器人（拉升到目标价格）
+forgex tools robot-price --group 1 --token <代币CA> --direction up --target-price 0.001
+```
+
+### 6. 收集 SOL
+
+```bash
+# 将钱包组所有钱包的 SOL 收集到一个地址
+forgex transfer in --to <目标地址> --from-group 1 --amount all
+```
+
+## 命令参考
+
+### 全局选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--format <format>` | 输出格式: `json` \| `table` \| `minimal` | `json` |
+| `--help` | 显示帮助信息 | - |
+| `--version` | 显示版本号 | - |
+
+所有交易类命令均支持 `--dry-run`（模拟执行）、`--priority-fee`（优先费 SOL）、`--slippage`（滑点 bps）。
+
+---
+
+### config -- 配置管理
+
+| 命令 | 说明 |
+|------|------|
+| `config init` | 初始化配置文件，支持 `--rpc-url`、`--api-token`、`--api-base-url`、`--network` |
+| `config set <key> <value>` | 设置配置项，支持点号路径（如 `feeConfig.trade_fee`） |
+| `config get [key]` | 查看配置项，不指定 key 显示全部（敏感信息脱敏） |
+| `config list` | 列出所有配置（敏感信息脱敏） |
+
+---
+
+### wallet -- 钱包组管理
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `wallet create-group` | `--name` (必填), `--type local\|monitor` | 创建钱包组 |
+| `wallet list-groups` | `--type` | 列出钱包组，可按类型过滤 |
+| `wallet group-info` | `--id` (必填), `--show-keys` | 查看详情，`--show-keys` 显示私钥明文 |
+| `wallet delete-group` | `--id` (必填), `--force` | 删除钱包组 |
+| `wallet generate` | `--group` (必填), `--count` | 批量生成新钱包（上限 100 个/组） |
+| `wallet add` | `--group` (必填), `--private-key` (必填) | 导入已有钱包 |
+| `wallet remove` | `--group` (必填), `--address` (必填) | 从组中移除钱包 |
+| `wallet import` | `--group` (必填), `--file` (必填) | 从 CSV 批量导入钱包 |
+| `wallet export` | `--group` (必填), `--file` (必填) | 导出钱包组为 CSV |
+| `wallet import-group` | `--file` (必填), `--password` | 从 JSON 导入钱包组 |
+| `wallet export-group` | `--file` (必填), `--encrypt`, `--password` | 导出所有钱包组为 JSON |
+| `wallet overview` | `--groups` (必填，逗号分隔), `--token` | 钱包组资产概览（总价值/盈亏/均价） |
+| `wallet grind` | `--suffix` (必填), `--prefix`, `--count`, `--threads` | 生成靓号地址（自定义后缀/前缀），需要本地安装 solana-keygen |
+| `wallet grind-list` | `--suffix` | 列出已生成的靓号地址，可按后缀过滤 |
+
+**靓号生成 (grind) 说明:**
+- 依赖本地 `solana-keygen` 工具，未安装时会提示安装方式
+- 后缀/前缀仅支持 Base58 字符（不含 0, O, I, l）
+- 生成的密钥文件保存在 `~/.forgex/vanity/` 目录
+- 后缀越长，生成时间越久（4 字符秒级，5+ 字符可能数分钟）
+
+---
+
+### trade -- 交易操作
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `trade buy` | `--group`, `--token`, `--amount`(SOL) | 批量买入，`--slippage` 默认 300bps |
+| `trade sell` | `--group`, `--token`, `--amount` | 批量卖出，amount 支持: 数量 / 百分比(`50%`) / `all` |
+| `trade batch` | `--group`, `--token`, `--type`, `--mode` | 批量交易，type: `buy\|sell\|buyWithSell`，mode: `1b1s\|1b2s\|1b3s\|2b1s\|3b1s` |
+| `trade sniper` | `--group`, `--token`, `--amounts` | 狙击买入，amounts 逗号分隔，数量须匹配钱包数 |
+
+---
+
+### tools -- 专业做市工具
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `tools turnover` | `--from-group`, `--to-group`, `--token` | 换手交易，使用 Jito Bundle 实现零滑点钱包间换手 |
+| `tools volume` | `--group`, `--token`, `--mode`, `--amount` | 刷量工具，支持 5 种模式，零损失提升交易量 |
+| `tools robot-price` | `--group`, `--token`, `--direction`, `--target-price` | 价格机器人，direction: `up`(拉升) / `down`(砸盘) |
+
+**换手 (turnover) 额外参数:**
+- `--amount`: 金额类型，固定数量 / 百分比(`50%`) / `all`(默认)
+- `--daemon`: 后台持续执行
+- `--rounds`: 轮数（0=无限）
+- `--interval`: 间隔毫秒
+
+**刷量 (volume) 额外参数:**
+- `--mode`: `1b1s`(1买1卖) / `1b2s` / `1b3s` / `2b1s` / `3b1s`
+- `--daemon`: 后台持续执行
+- `--rounds`: 轮数（0=无限）
+- `--interval`: 间隔毫秒
+
+**价格机器人 (robot-price) 额外参数:**
+- `--amount-type`: `fixed` / `random`
+- `--amount-max`: random 模式最大金额
+- `--max-cost`: 总消耗 SOL 上限
+- 默认持续运行直到达到目标价格或成本上限，Ctrl+C 停止
+
+---
+
+### transfer -- 转账操作
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `transfer in` | `--to`, `--from-group` | 批量收集（多对一），`--amount all\|fixed\|reserve` |
+| `transfer out` | `--from`, `--to-group`, `--value` | 批量分发（一对多），`--amount fixed\|random` |
+| `transfer many-to-many` | `--from-group`, `--to-group` | 多对多转账，按索引配对，`--amount all\|fixed\|reserve\|random` |
+
+---
+
+### token -- 代币操作
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `token create` | `--dex`, `--name`, `--symbol`, `--image` | 创建代币，dex: `pump` / `launchlab` |
+| `token info` | `--ca` | 查询代币信息（名称、符号、价格、交易对等） |
+| `token pool` | `--ca` | 查询代币池子信息 |
+
+**代币创建额外参数:**
+- `--description`, `--twitter`, `--website`, `--telegram`: 元数据
+- `--dev-wallet`: 开发者钱包组 ID，`--dev-buy`: 开发者买入金额
+- `--snipers`: 狙击者钱包组 ID，`--sniper-amounts`: 狙击金额
+- `--bundle-time`: `T0`(同区块) / `T1_T5`
+- `--use-suffix`: 使用自定义后缀地址
+
+---
+
+### query -- 查询操作
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `query balance` | `--address`, `--token`(可选) | 查询余额，不填 token 查 SOL |
+| `query price` | `--token` | 查询代币价格（SOL/USD） |
+| `query kline` | `--token`, `--interval`, `--count` | K 线数据，interval: `1m\|5m\|15m\|1h\|4h\|1d` |
+| `query transactions` | `--group`, `--token`(可选) | 查询交易记录，支持分页 `--page` `--page-size` |
+| `query monitor` | `--group`, `--token`(可选) | 持仓监控（余额/均价/已实现&未实现盈亏） |
+
+---
+
+### sniper -- 外盘抢筹
+
+| 命令 | 主要参数 | 说明 |
+|------|----------|------|
+| `sniper external` | `--launch-group`, `--sniper-group`, `--token`, `--amounts` | Pump.fun 外盘抢筹（Pump -> PumpSwap 迁移触发） |
+| `sniper bonk` | `--sniper-group`, `--token`, `--amounts` | Bonk 外盘抢筹（Raydium CPMM） |
+
+## 配置
+
+### 配置文件位置
+
+`~/.forgex/config.json`，通过 `forgex config init` 创建。
+
+### 配置项
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `rpcUrl` | Solana RPC 节点 URL | `https://api.mainnet-beta.solana.com` |
+| `apiToken` | API 认证 Token | `""` |
+| `apiBaseUrl` | API 基础 URL | `https://forgex.online/api` |
+| `codexApiKey` | Codex API Key（市场数据查询） | `""` |
+| `network` | 网络: `mainnet` / `devnet` / `testnet` | `mainnet` |
+| `defaultPriorityFee` | 默认优先费 (SOL) | `0.0001` |
+| `defaultSlippage` | 默认滑点 (bps) | `300` |
+| `outputFormat` | 默认输出格式 | `json` |
+| `solPrice` | SOL 美元价格（估值用） | `130` |
+| `feeConfig.*` | 手续费配置（嵌套对象） | 见源码 |
+
+### 环境变量
+
+以下环境变量会覆盖配置文件中的对应值（优先级最高）：
+
+| 环境变量 | 对应配置项 |
+|----------|-----------|
+| `FORGEX_API_TOKEN` | `apiToken` |
+| `FORGEX_RPC_URL` | `rpcUrl` |
+| `FORGEX_API_BASE_URL` | `apiBaseUrl` |
+| `FORGEX_CODEX_API_KEY` | `codexApiKey` |
+| `FORGEX_WALLET_PASSWORD` | 钱包加密密码（避免交互式输入，适合脚本自动化） |
+
+## 安全
+
+### 私钥加密
+
+所有钱包私钥使用 AES 加密存储。首次创建或导入钱包时，CLI 要求设置加密密码。之后每次涉及私钥的操作（交易、导出等）都需要验证密码。
+
+加密流程：
+1. 用户设置主密码
+2. 私钥通过 `CryptoJS.AES.encrypt(privateKey, password)` 加密后写入磁盘
+3. 使用时通过 `CryptoJS.AES.decrypt(encrypted, password)` 临时解密到内存
+4. 明文私钥仅在内存中使用，不持久化
+5. 旧版明文存储会自动检测并迁移到加密格式
+
+### 安全建议
+
+- 使用强密码保护钱包
+- 通过环境变量 `FORGEX_WALLET_PASSWORD` 设置密码适合脚本自动化场景
+- 定期使用 `wallet export-group --encrypt --password <pwd>` 加密备份钱包数据
+- 不要在公共环境或共享屏幕时使用 `wallet group-info --show-keys`
+- 所有交易命令支持 `--dry-run` 预检，建议大额操作前先模拟验证
+- 配置文件权限为 `600`（仅所有者可读写），目录权限为 `700`
+
+### 文件存储
+
+```
+~/.forgex/                     # 700 权限
+  config.json                  # 600 权限，全局配置
+  wallets/                     # 钱包加密数据
+    wallet-store.json          # 钱包组和加密私钥
+  vanity/                      # 靓号密钥文件 (solana-keygen grind 生成)
+    {address}.json             # Solana keypair JSON
+  data/                        # DataStore 本地数据
+    tokens/{CA}/               # 按代币组织
+      groups/{groupId}/        # 按钱包组组织
+        transactions.json      # 交易记录
+        holdings.json          # 持仓数据
+        balances.json          # 余额快照
+  logs/                        # 运行日志
+```
+
+## 架构
+
+```
+CLI 命令层 (commands/)
+    |
+    v
+DataSource (data-source.ts) ---- 统一数据源门面
+    |
+    +---> CodexAdapter    代币信息/价格/K线/池信息 (远程 API + 本地缓存)
+    +---> RpcAdapter      余额/账户信息/交易确认 (链上 RPC)
+    +---> JitoAdapter     Bundle 发送/状态查询 (Jito Block Engine)
+    +---> DataStore       交易记录/持仓/缓存 (本地文件 ~/.forgex/data/)
+    |
+    v
+TxTracker (tx-tracker/) ---- 交易追踪系统
+    +---> TxDetailAdapter   解析链上交易详情
+    +---> DataStore         持久化交易结果和持仓变化
+
+SdkAdapter (adapters/sdk-adapter.ts) ---- 交易执行
+    +---> sol-sdk           前端交易 SDK 适配
+```
+
+### 核心模块说明
+
+- **DataSource**: 命令层唯一的数据访问接口。路由请求到正确的适配器，支持缓存穿透（优先读本地，miss 或过期时从远程获取并写入本地）和容错降级（远程不可用时 fallback 到本地缓存）
+- **DataStore**: 基于文件系统的本地数据存储，按 `tokens/{CA}/groups/{groupId}/` 组织数据
+- **CodexAdapter**: 对接 Codex API 获取市场数据（代币信息、实时价格、K 线、交易对）
+- **RpcAdapter**: 对接 Solana RPC 节点进行链上查询（SOL/Token 余额、账户信息、交易确认）
+- **JitoAdapter**: 对接 Jito Block Engine 发送和查询 Bundle 交易
+- **TxTracker**: 交易完成后自动追踪链上结果，解析交易详情，更新持仓和盈亏数据
+- **SdkAdapter**: 封装前端 sol-sdk，提供买入/卖出/换手/刷量等交易构建和执行能力
+
+### 输出系统
+
+所有命令通过统一的 `output()` 函数输出数据，支持三种格式：
+
+- **json** (默认): 结构化 JSON，适合程序解析和 Agent 集成
+- **table**: cli-table3 表格，适合终端人工查看
+- **minimal**: 简洁文本，仅输出关键信息
+
+```bash
+forgex wallet list-groups --format json
+forgex wallet list-groups --format table
+forgex wallet list-groups --format minimal
+```
+
+## 开发
+
+### 开发环境
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式运行
+npm run dev -- config list
+npm run dev -- wallet list-groups --format table
+
+# 编译 TypeScript
+npm run build
+
+# 清除编译产物
+npm run clean
+```
+
+### 测试
+
+```bash
+# 运行全部测试
+npm test
+
+# 监听模式（文件变更自动重跑）
+npm run test:watch
+```
+
+测试框架使用 vitest，测试文件位于 `tests/` 目录，超时时间 30 秒。
+
+### 项目结构
+
+```
+cli/
+  bin/
+    forgex.ts                  CLI 入口（密码迁移检测 + 命令解析）
+  src/
+    index.ts                   程序主入口，注册 8 个命令组
+    config.ts                  配置管理（读写 ~/.forgex/config.json）
+    output.ts                  输出格式化（json/table/minimal）
+    wallet-store.ts            钱包加密存储（AES 加密/解密/迁移）
+    data-source.ts             统一数据源门面
+    commands/
+      config/index.ts          配置管理命令 (init/set/get/list)
+      wallet/index.ts          钱包组管理命令 (14 个子命令)
+      trade/index.ts           交易命令 (buy/sell/batch/sniper)
+      tools/index.ts           做市工具命令 (turnover/volume/robot-price)
+      transfer/index.ts        转账命令 (in/out/many-to-many)
+      token/index.ts           代币操作命令 (create/info/pool)
+      query/index.ts           查询命令 (balance/price/kline/transactions/monitor)
+      sniper/index.ts          外盘抢筹命令 (external/bonk)
+    adapters/
+      sdk-adapter.ts           前端 sol-sdk 适配层
+      codex-adapter.ts         Codex API 适配器
+      rpc-adapter.ts           Solana RPC 适配器
+      jito-adapter.ts          Jito Bundle 适配器
+      api.ts                   服务端 API 适配器
+    data-store/
+      index.ts                 本地文件存储实现
+      types.ts                 数据类型定义
+    tx-tracker/
+      index.ts                 交易追踪主逻辑
+      detail-adapter.ts        链上交易详情解析
+  tests/                       测试文件
+  vitest.config.ts             vitest 测试配置
+  package.json                 依赖和脚本
+  tsconfig.json                TypeScript 配置
+```
+
+### 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 语言 | TypeScript (ESM, type: module) |
+| CLI 框架 | Commander.js 13 |
+| 区块链 SDK | @solana/web3.js, @coral-xyz/anchor 0.31 |
+| 加密 | crypto-js (AES) |
+| 交互 | inquirer 12 |
+| 表格 | cli-table3 |
+| 进度条 | cli-progress |
+| 加载动画 | ora |
+| 颜色 | chalk 5 |
+| 大数 | bignumber.js, bn.js |
+| HTTP | axios |
+| 测试 | vitest 4 |
+
+## License
+
+MIT

package/dist/bin/forgex.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * ForgeX CLI 入口
+ *
+ * Solana 链上做市系统命令行工具
+ *
+ * 启动流程：
+ * 1. 检测钱包存储是否为旧格式（明文私钥），如果是则自动迁移到加密格式
+ * 2. 构建命令树并解析命令行参数
+ */
+export {};
+//# sourceMappingURL=forgex.d.ts.map

package/dist/bin/forgex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgex.d.ts","sourceRoot":"","sources":["../../bin/forgex.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}

package/dist/bin/forgex.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * ForgeX CLI 入口
+ *
+ * Solana 链上做市系统命令行工具
+ *
+ * 启动流程：
+ * 1. 检测钱包存储是否为旧格式（明文私钥），如果是则自动迁移到加密格式
+ * 2. 构建命令树并解析命令行参数
+ */
+import { createProgram } from '../src/index.js';
+import { migrateToEncryptedStore } from '../src/wallet-store.js';
+async function main() {
+    // 检测并迁移旧格式的钱包存储（明文私钥 → AES 加密）
+    await migrateToEncryptedStore();
+    const program = createProgram();
+    program.parse(process.argv);
+}
+main().catch((err) => {
+    console.error('启动失败:', err.message || err);
+    process.exit(1);
+});
+//# sourceMappingURL=forgex.js.map

package/dist/bin/forgex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgex.js","sourceRoot":"","sources":["../../bin/forgex.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,KAAK,UAAU,IAAI;IACjB,+BAA+B;IAC/B,MAAM,uBAAuB,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}