# charms_runner

**Repository Path**: openour/charms_runner

## Basic Information

- **Project Name**: charms_runner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-18
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Charms GPU 挖矿部署指南

## 🚀 快速开始 (选择你的方案)

| 你的情况 | 推荐方案 | 命令 |
|----------|----------|------|
| 🆕 **新手，新机器** | 一键安装 | `./quick-setup.sh` |
| 📦 **已有 xinrun 目录** | 直接启动 | `./install.sh` 然后 `./run.sh server` |
| 🔍 **先检查兼容性** | 环境检查 | `./check-env.sh` |

> 📖 更多详情请看: [QUICKSTART.md](QUICKSTART.md) | [脚本说明](FILES.md)

## ✨ 新特性 - 本地化部署

现在 xinrun 目录包含了完整的安装包，**无需从网络下载**！优势：

- ✅ **离线安装**: 不依赖网络连接
- ✅ **自动安装 Bitcoin Core**: 自动检测、安装和配置
- ✅ **自动生成配置**: 安全的 RPC 配置和钱包设置
- ✅ **一键启动**: `./quick-setup.sh` 完成所有设置

## 概述

本部署包包含了 Charms GPU 挖矿程序的完整运行环境，支持 NVIDIA CUDA GPU 加速的零知识证明计算。

**预编译包信息:**
- 下载地址: http://oss.fishline.top/charms-gpu-package-20250918-105625.tar.gz
- 包大小: ~200MB (包含完整的 GPU 加速支持)
- 编译时间: 2025年9月18日
- 源码版本: 最新 main 分支
- 特性: prover (GPU acceleration enabled)

## 系统要求

### 硬件要求
- **GPU**: NVIDIA RTX 4090 或其他支持 CUDA 的显卡
- **VRAM**: 最低 24GB
- **RAM**: 建议 32GB 以上
- **存储**: 至少 50GB 可用空间

### 软件要求
- **操作系统**: Ubuntu 20.04+ 或其他 Linux 发行版
- **NVIDIA 驱动**: 535+ 版本
- **CUDA**: 11.8+ 或 12.x
- **网络**: 稳定的互联网连接

## 快速开始

### 1. 下载预编译包

**方案一：预编译包（推荐）**
```bash
# 1. 检查环境兼容性
wget -O - https://gitee.com/openour/charms_runner/raw/master/check-env.sh | bash

# 2. 一键安装（自动检查并安装依赖）
wget -O - https://gitee.com/openour/charms_runner/raw/master/install.sh | bash

# 3. 或手动下载
wget http://oss.fishline.top/charms-gpu-package-20250918-105625.tar.gz
tar -xzf charms-gpu-package-20250918-105625.tar.gz
cd charms-package-*
```

**方案二：源码编译（高级用户）**
```bash
# 如果需要从源码编译（需要较长时间和完整编译环境）
git clone https://github.com/CharmsDev/charms.git
cd charms
./xinrun/build.sh
```

**重要：跨机器部署说明**
- 打包机器和运行机器可能不同
- 运行脚本会自动检查环境并安装缺失依赖
- 支持 Ubuntu/Debian 系统的自动依赖安装
- 其他系统需要手动安装依赖

### 2. 验证部署包

```bash
# 检查包内容
ls -la
cat VERSION

# 检查系统状态
./scripts/run.sh status
```

### 3. 准备 Bitcoin 环境和资金

**重要：Charms 运行需要 Bitcoin 作为 Gas（手续费），请确保有足够的 BTC！**

```bash
# 检查 Bitcoin Core 是否运行
bitcoin-cli getblockchaininfo

# 如果没有运行，启动 Bitcoin Core
bitcoind -daemon

# 创建或加载钱包
bitcoin-cli createwallet "charms-wallet"
bitcoin-cli loadwallet "charms-wallet"

# 获取地址并充值
NEW_ADDRESS=$(bitcoin-cli getnewaddress)
echo "请向此地址充值 BTC: $NEW_ADDRESS"

# 检查余额（需要至少 0.001 BTC 用于手续费）
bitcoin-cli getbalance
```

**资金要求：**
- **测试网**: 至少 50,000 sats (0.0005 BTC)
- **主网**: 建议至少 0.01 BTC 用于手续费和操作
- **建议**: 准备多个 UTXO，包括小额（>=10,000 sats）和大额

### 4. 启动服务器

```bash
./scripts/run.sh server
```

### 5. 创建第一个应用

```bash
./scripts/run.sh app new my-first-token
cd my-first-token
ls -la
```

## 目录结构

```
charms-package-*/
├── bin/
│   └── charms              # 主程序可执行文件
├── scripts/
│   ├── run.sh             # 运行脚本
│   └── env.sh             # 环境配置
├── docs/
│   └── README.md          # 本文档
└── VERSION                # 版本信息
```

## 脚本文件说明

### 🎯 **用户必需文件**

| 文件 | 用途 | 使用场景 |
|------|------|----------|
| **`install.sh`** | 一键安装脚本 | 新机器部署，自动下载+安装+配置 |
| **`run.sh`** | 程序运行脚本 | 已有预编译包，启动和管理 Charms |
| **`check-env.sh`** | 环境检查脚本 | 部署前检查机器兼容性 |

### 🔧 **开发和维护文件**

| 文件 | 用途 | 使用场景 |
|------|------|----------|
| **`build.sh`** | 源码编译脚本 | 从源码构建预编译包 |
| **`wallet-backup.sh`** | 钱包备份脚本 | 钱包数据备份和恢复 |
| **`fix-libclang.sh`** | libclang 修复脚本 | 编译问题排查和修复 |
| **`debug-libclang.sh`** | libclang 诊断脚本 | 编译环境诊断 |

### 📚 **文档文件**

| 文件 | 内容 |
|------|------|
| **`README.md`** | 完整部署指南 |
| **`QUICKSTART.md`** | 快速启动指南 |
| **`WALLET_GUIDE.md`** | 钱包配置和安全指南 |

## 选择使用方案

### 🚀 **场景一：新手快速开始**
```bash
# 只需要一个命令
wget -O - https://gitee.com/openour/charms_runner/raw/master/install.sh | bash
```
**说明**: `install.sh` 会自动下载预编译包、检查环境、安装依赖、配置系统

### 📦 **场景二：已有预编译包**
```bash
# 下载后直接使用
tar -xzf charms-gpu-package-*.tar.gz
cd charms-package-*/
./scripts/run.sh server
```
**说明**: `run.sh` 用于启动和管理已有的预编译包

### 🔍 **场景三：环境诊断**
```bash
# 检查机器是否兼容
wget -O - https://gitee.com/openour/charms_runner/raw/master/check-env.sh | bash
```
**说明**: `check-env.sh` 检查 GPU、CUDA、Bitcoin Core 等环境

### 🛠️ **场景四：从源码构建**
```bash
# 开发者或需要自定义构建
git clone https://github.com/CharmsDev/charms.git
cd charms
./xinrun/build.sh
```
**说明**: `build.sh` 从源码编译生成预编译包

## 脚本关系图

```
用户场景：
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  新机器部署     │    │  已有预编译包   │    │  环境检查       │
│  install.sh     │    │  run.sh         │    │  check-env.sh   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  预编译包       │
                    │  (主程序)       │
                    └─────────────────┘
                                 │
    开发场景：                    │
┌─────────────────┐              │
│  源码构建       │──────────────┘
│  build.sh       │
└─────────────────┘

维护工具：
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  钱包备份       │    │  编译问题修复   │    │  编译环境诊断   │
│  wallet-backup  │    │  fix-libclang   │    │  debug-libclang │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 文件依赖说明

- **`install.sh`** → 下载预编译包 → 调用 `run.sh`
- **`run.sh`** → 检查环境 → 启动 `bin/charms`
- **`build.sh`** → 编译源码 → 生成预编译包（包含 `run.sh`）
- **其他脚本** → 独立工具，按需使用

## 网络配置说明

### 支持的网络类型

Charms 项目支持多种 Bitcoin 网络环境：

| 网络类型 | 配置参数 | 用途 | 资金要求 |
|---------|----------|------|----------|
| **Bitcoin 主网** | `mainnet=1` | 生产环境，真实挖矿 | 建议 0.01+ BTC |
| **Bitcoin 测试网4** | `testnet=1` | 开发测试，学习使用 | 最少 0.0005 BTC |
| **回归测试网** | `regtest=1` | 本地开发调试 | 无需真实资金 |

### 网络切换配置

在 `bitcoin.conf` 中设置网络类型：

```bash
# === 测试网配置 (推荐新手) ===
server=1
testnet=1              # 使用测试网4
txindex=1
addresstype=bech32m
changetype=bech32m

# === 主网配置 (生产环境) ===
# server=1
# mainnet=1            # 使用主网
# txindex=1
# addresstype=bech32m
# changetype=bech32m
```

### 获取测试币

**测试网水龙头**:
- 访问 https://mempool.space/testnet4/faucet
- 获取至少 50000 sats (0.0005 test BTC)
- 建议获取多个 UTXO 以备后续使用

**主网资金**:
- 需要购买真实 BTC
- 确保有足够余额支付 Gas 费用
- 建议保持 0.01+ BTC 余额

### 安全提醒

⚠️ **重要**:
- 新手务必先在测试网熟悉操作流程
- 确认所有功能正常后再切换到主网
- 主网操作涉及真实资金，请谨慎操作
- 定期备份钱包数据 (使用 `wallet-backup.sh`)

## 经济模型和费用结构

### Gas 费用说明

Charms 使用 **Bitcoin 作为 Gas**，涉及多种费用：

#### 1. Bitcoin 网络费用
- **交易费**: 按 sats/vB 计算，默认 2.0 sats/vB
- **UTXO 管理**: 需要 funding UTXO 支付交易费用
- **网络拥堵**: 费用随网络状况波动

#### 2. Charms 协议费用
- **基础费用**: 每笔操作的固定费用
- **计算费用**: 按计算周期收费（sats/mega-cycle）
- **证明费用**: GPU 零知识证明的成本

#### 3. 费用计算公式
```
总费用 = Bitcoin交易费 + Charms基础费 + (计算周期 × 费率 / 1000000)
```

### 资金管理策略

#### 推荐配置
```bash
# 测试网络
最小余额: 50,000 sats (0.0005 BTC)
推荐余额: 500,000 sats (0.005 BTC)

# 主网络
最小余额: 1,000,000 sats (0.01 BTC)
推荐余额: 10,000,000 sats (0.1 BTC)
```

#### UTXO 管理
- **多个 UTXO**: 避免单点故障
- **大小搭配**: 大额用于主要操作，小额用于测试
- **余额监控**: 定期检查，及时补充

## 详细使用说明

### 环境变量配置

运行脚本会自动设置以下环境变量：

```bash
SP1_PROVER=cuda              # 主证明器使用 CUDA
APP_SP1_PROVER=cuda          # 应用证明器使用 CUDA
SPELL_SP1_PROVER=network     # Spell 证明器使用网络模式
SP1_GPU_SERVICE_URL=http://localhost:3000/twirp/
RUST_LOG=info                # 日志级别
```

### 运行模式

#### 1. 服务器模式

```bash
# 默认启动 (127.0.0.1:17784)
./scripts/run.sh server

# 自定义地址和端口
./scripts/run.sh server --ip 0.0.0.0 --port 8080
```

#### 2. 应用管理

```bash
# 创建新应用
./scripts/run.sh app new my-token

# 其他应用命令
./scripts/run.sh app --help
```

#### 3. Spell 操作

```bash
# 检查 spell 文件
./scripts/run.sh spell check --spell spell.yaml

# 生成证明 (使用 GPU 加速)
./scripts/run.sh spell prove --spell spell.yaml

# 验证 spell
./scripts/run.sh spell verify --spell spell.yaml
```

#### 4. 钱包操作

```bash
# 列出钱包
./scripts/run.sh wallet list

# 创建新钱包
./scripts/run.sh wallet create --name my-wallet
```

### 监控和状态检查

#### 系统状态查看

```bash
./scripts/run.sh status
```

显示内容包括：
- GPU 使用情况和温度
- 进程状态和内存使用
- Bitcoin Core 连接状态
- 钱包余额和 UTXO 数量
- 环境变量配置
- 版本信息

#### 运行状态监控

```bash
# GPU 实时监控
./scripts/run.sh monitor

# Bitcoin 钱包状态
bitcoin-cli getwalletinfo
bitcoin-cli listunspent

# Charms 钱包内容
./scripts/run.sh wallet list

# 服务器健康检查
curl -s http://localhost:17784/health || echo "服务器未响应"

# 日志监控
tail -f server.log  # 如果使用后台运行
```

#### 性能指标

**关键监控指标：**
- **GPU 利用率**: 应在证明期间达到 >80%
- **内存使用**: GPU 内存 <90%，系统内存 <80%
- **Bitcoin 同步**: 区块高度应与网络一致
- **钱包余额**: 保持充足的 BTC 余额
- **网络延迟**: 与 Bitcoin 节点的连接延迟 <100ms

**告警阈值：**
```bash
# GPU 温度过高
nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader,nounits | awk '$1 > 85 {print "GPU 温度过高: " $1 "°C"}'

# 余额不足
BALANCE=$(bitcoin-cli getbalance)
awk "BEGIN {if ($BALANCE < 0.001) print \"BTC 余额不足: $BALANCE\"}"

# 磁盘空间
df -h | awk '$5 > 90 {print "磁盘空间不足: " $0}'
```

### 性能优化建议

#### 1. GPU 设置

```bash
# 设置 GPU 功率限制 (可选)
sudo nvidia-smi -pl 450  # 设置为 450W

# 检查 GPU 状态
nvidia-smi
```

#### 2. 系统优化

```bash
# 增加文件描述符限制
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# 禁用交换分区 (可选，如果内存充足)
sudo swapoff -a
```

#### 3. 网络优化

```bash
# 调整网络缓冲区
echo 'net.core.rmem_max = 134217728' | sudo tee -a /etc/sysctl.conf
echo 'net.core.wmem_max = 134217728' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

## 故障排除

### 常见问题

#### 1. 资金相关问题

**症状**: `insufficient funds` 或交易失败

**解决方案**:
```bash
# 检查 Bitcoin 余额
bitcoin-cli getbalance

# 检查可用 UTXO
bitcoin-cli listunspent

# 如果余额不足，需要充值
NEW_ADDRESS=$(bitcoin-cli getnewaddress)
echo "充值地址: $NEW_ADDRESS"

# 检查 funding UTXO 是否有效
bitcoin-cli gettxout <txid> <vout>
```

#### 2. 费用设置问题

**症状**: 交易费用过高或过低

**解决方案**:
```bash
# 检查当前网络费率
bitcoin-cli estimatesmartfee 6

# 调整费率参数
./scripts/run.sh spell prove --spell spell.yaml --fee-rate 3.0

# 检查 mempool 状态
curl -s https://mempool.space/api/v1/fees/recommended
```

#### 3. CUDA 相关错误

**症状**: `CUDA driver version is insufficient`

**解决方案**:
```bash
# 检查驱动版本
nvidia-smi

# 重新安装驱动
apt purge nvidia-*
apt install nvidia-driver-535
reboot
```

#### 4. Bitcoin Core 连接问题

**症状**: `Could not connect to the server`

**解决方案**:
```bash
# 检查 Bitcoin Core 状态
ps aux | grep bitcoind

# 启动 Bitcoin Core
bitcoind -daemon

# 检查配置文件
cat ~/.bitcoin/bitcoin.conf

# 检查网络连接
bitcoin-cli getnetworkinfo
```

#### 5. 内存不足

**症状**: `out of memory` 或程序崩溃

**解决方案**:
```bash
# 检查可用内存
free -h

# 关闭不必要的程序
# 或增加交换分区
fallocate -l 8G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
```

#### 6. 权限问题

**症状**: `Permission denied`

**解决方案**:
```bash
# 设置可执行权限
chmod +x scripts/run.sh
chmod +x bin/charms

# 检查文件所有者
ls -la bin/charms
```

### 日志分析

#### 启用详细日志

```bash
export RUST_LOG=debug
./scripts/run.sh server
```

#### 查看系统日志

```bash
# 查看 GPU 相关日志
dmesg | grep -i nvidia

# 查看系统资源使用
top
htop
iotop
```

## 生产环境部署

### 1. 服务管理

创建 systemd 服务文件：

```bash
sudo tee /etc/systemd/system/charms.service << EOF
[Unit]
Description=Charms GPU Mining Service
After=network.target

[Service]
Type=simple
User=charms
Group=charms
WorkingDirectory=/opt/charms
ExecStart=/opt/charms/scripts/run.sh server --ip 0.0.0.0
Restart=always
RestartSec=5
Environment=SP1_PROVER=cuda
Environment=APP_SP1_PROVER=cuda
Environment=SPELL_SP1_PROVER=network
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target
EOF

# 启用服务
sudo systemctl enable charms
sudo systemctl start charms
```

### 2. 监控设置

```bash
# 使用 screen 或 tmux 运行长期任务
screen -S charms-server
./scripts/run.sh server
# Ctrl+A, D 分离会话

# 重新连接
screen -r charms-server
```

### 3. 自动化脚本

```bash
# 创建启动脚本
cat > start_mining.sh << 'EOF'
#!/bin/bash
cd /opt/charms
source scripts/env.sh
nohup ./scripts/run.sh server > server.log 2>&1 &
echo $! > server.pid
echo "Charms 服务器已启动，PID: $(cat server.pid)"
EOF

chmod +x start_mining.sh
```

## 安全注意事项

1. **网络安全**
   - 不要将服务器暴露到公网，除非必要
   - 使用防火墙限制访问
   - 定期更新系统和驱动

2. **数据安全**
   - 定期备份钱包文件
   - 使用强密码
   - 加密存储敏感信息

3. **系统安全**
   - 使用非 root 用户运行程序
   - 监控系统资源使用
   - 定期检查日志

## 支持和联系

- **官方网站**: https://charms.dev
- **文档**: https://docs.charms.dev
- **GitHub**: https://github.com/CharmsDev/charms

## 版本历史

请查看 `VERSION` 文件了解当前部署包的详细信息。

---

© 2025 Charms Inc. 保留所有权利。