feat: 添加 MiniSwap CLI 工具及相关文档
- 新增 CLI 工具，支持通过命令行与 MiniSwapAMM 合约交互 - 创建 CLI 使用指南文档，详细说明命令和操作流程 - 更新合约地址，确保与新部署的合约匹配 - 添加快速网络连接测试脚本，验证合约连接和网络状态 - 实现完整测试场景脚本，模拟用户操作和流动性管理
This commit is contained in:
190
CLI-USAGE.md
Normal file
190
CLI-USAGE.md
Normal file
@ -0,0 +1,190 @@
|
||||
# MiniSwap CLI 工具使用指南
|
||||
|
||||
这个 CLI 工具让你可以通过命令行操作和测试 MiniSwapAMM 合约的所有功能，无需前端界面。
|
||||
|
||||
## 前置条件
|
||||
|
||||
1. 确保已经部署了合约：
|
||||
```bash
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
2. 确保本地网络正在运行：
|
||||
```bash
|
||||
npm run node
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 方法1: 交互式 CLI 工具
|
||||
|
||||
启动交互式命令行界面：
|
||||
```bash
|
||||
npm run cli
|
||||
```
|
||||
|
||||
这将启动一个交互式界面，你可以输入命令来操作合约。
|
||||
|
||||
### 方法2: 测试网络连接
|
||||
|
||||
如果遇到连接问题，可以先运行连接测试：
|
||||
```bash
|
||||
npm run test-connection
|
||||
```
|
||||
|
||||
这会测试网络连接和合约加载是否正常。
|
||||
|
||||
### 方法3: 运行完整测试场景
|
||||
|
||||
运行预设的完整测试场景：
|
||||
```bash
|
||||
npm run test-scenario
|
||||
```
|
||||
|
||||
这会自动执行一系列操作，演示 AMM 的所有功能。
|
||||
|
||||
## CLI 命令详解
|
||||
|
||||
### 基本信息查询
|
||||
|
||||
- `accounts` - 显示所有可用账户
|
||||
- `switch <index>` - 切换到指定账户（例如：`switch 1`）
|
||||
- `balances` - 查看当前账户的所有代币余额
|
||||
- `reserves` - 查看 AMM 池的储备量和价格信息
|
||||
|
||||
### 代币操作
|
||||
|
||||
- `mint [amount]` - 铸造测试代币（默认 1000 个）
|
||||
- 例如：`mint 500` 铸造 500 个代币
|
||||
- `approve [amount]` - 授权代币给 AMM 合约（默认 10000 个）
|
||||
- 例如：`approve 5000` 授权 5000 个代币
|
||||
|
||||
### 流动性操作
|
||||
|
||||
- `add <amountA> <amountB> [slippage]` - 添加流动性
|
||||
- 例如：`add 1000 2000 1` 添加 1000 TKA + 2000 TKB，允许 1% 滑点
|
||||
- `remove <liquidity> [slippage]` - 移除流动性
|
||||
- 例如：`remove 500 1` 移除 500 个 LP 代币，允许 1% 滑点
|
||||
|
||||
### 代币交换
|
||||
|
||||
- `swapAB <amount> [slippage]` - 将 TokenA 交换为 TokenB
|
||||
- 例如：`swapAB 100 1` 用 100 TKA 交换 TKB，允许 1% 滑点
|
||||
- `swapBA <amount> [slippage]` - 将 TokenB 交换为 TokenA
|
||||
- 例如：`swapBA 50 1` 用 50 TKB 交换 TKA，允许 1% 滑点
|
||||
|
||||
### 价格计算
|
||||
|
||||
- `calc <amount> <direction>` - 计算交换价格
|
||||
- `calc 100 a2b` - 计算 100 TKA 能换多少 TKB
|
||||
- `calc 50 b2a` - 计算 50 TKB 能换多少 TKA
|
||||
|
||||
### 其他命令
|
||||
|
||||
- `help` - 显示帮助信息
|
||||
- `exit` - 退出程序
|
||||
|
||||
## 使用示例
|
||||
|
||||
以下是一个完整的操作流程示例：
|
||||
|
||||
```bash
|
||||
# 启动 CLI
|
||||
npm run cli
|
||||
|
||||
# 查看当前账户余额
|
||||
> balances
|
||||
|
||||
# 铸造一些测试代币
|
||||
> mint 5000
|
||||
|
||||
# 授权代币给 AMM 合约
|
||||
> approve 10000
|
||||
|
||||
# 添加初始流动性（1000 TKA + 2000 TKB）
|
||||
> add 1000 2000
|
||||
|
||||
# 查看池子状态
|
||||
> reserves
|
||||
|
||||
# 切换到另一个账户
|
||||
> switch 1
|
||||
|
||||
# 为新账户铸造代币
|
||||
> mint 3000
|
||||
> approve 5000
|
||||
|
||||
# 进行代币交换
|
||||
> swapAB 100 1
|
||||
|
||||
# 查看交换后的余额
|
||||
> balances
|
||||
> reserves
|
||||
|
||||
# 计算交换价格
|
||||
> calc 50 a2b
|
||||
|
||||
# 退出
|
||||
> exit
|
||||
```
|
||||
|
||||
## 滑点保护
|
||||
|
||||
所有涉及交换和流动性操作的命令都支持滑点保护参数：
|
||||
- 滑点参数以百分比形式输入（例如：1 表示 1%）
|
||||
- 如果不指定，默认使用 1% 的滑点保护
|
||||
- 滑点保护可以防止因价格变动导致的不利交易
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **网络连接**：确保本地 Hardhat 网络正在运行
|
||||
2. **代币授权**：在添加流动性或交换代币前，必须先授权代币给 AMM 合约
|
||||
3. **账户管理**：可以使用 `switch` 命令在不同账户间切换，模拟多用户操作
|
||||
4. **交易确认**：每个交易都会等待区块确认，可能需要几秒钟
|
||||
5. **错误处理**：如果操作失败，CLI 会显示详细的错误信息
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见错误及解决方法
|
||||
|
||||
1. **"could not decode result data" 错误**
|
||||
- 原因：CLI 工具连接的网络与合约部署的网络不一致
|
||||
- 解决：确保先运行 `npm run node`，然后运行 `npm run deploy`，最后运行 `npm run cli`
|
||||
|
||||
2. **"合约地址文件不存在" 错误**
|
||||
- 解决：运行 `npm run deploy` 重新部署合约
|
||||
|
||||
3. **"网络连接失败" 错误**
|
||||
- 解决：确保本地网络正在运行 `npm run node`
|
||||
|
||||
4. **"合约验证失败" 错误**
|
||||
- 原因：合约可能没有正确部署或网络不匹配
|
||||
- 解决：重新部署合约 `npm run deploy`
|
||||
|
||||
5. **其他问题**
|
||||
- **代币不足**：使用 `mint` 命令铸造更多代币
|
||||
- **未授权代币**：使用 `approve` 命令授权代币
|
||||
- **滑点过大**：增加滑点保护参数或减少交换数量
|
||||
|
||||
### 完整重置流程
|
||||
|
||||
如果遇到无法解决的问题，可以完全重置：
|
||||
|
||||
```bash
|
||||
# 1. 停止当前网络 (Ctrl+C)
|
||||
# 2. 重新启动网络
|
||||
npm run node
|
||||
|
||||
# 3. 重新部署合约（新终端）
|
||||
npm run deploy
|
||||
|
||||
# 4. 启动 CLI
|
||||
npm run cli
|
||||
```
|
||||
|
||||
## 高级功能
|
||||
|
||||
- **批量测试**：使用 `npm run test-scenario` 运行完整的测试场景
|
||||
- **多账户操作**：使用 `switch` 命令模拟多用户环境
|
||||
- **价格影响分析**：通过连续小额交换观察价格变化
|
||||
- **流动性管理**：添加和移除流动性来观察对价格的影响
|
||||
Reference in New Issue
Block a user