介绍
# Kaspa Wallet Skill
适用于 Kaspa 区块链的简单自托管钱包。
## 概述
``` ┌─────────────────────────────────────────────────────────┐ │ KASPA WALLET │ ├─────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ Balance │ │ Send │ │ Payment URIs │ │ │ │ Check │ │ KAS │ │ Generator │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ │ │ │ │ │ └────────────────┴───────────────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ Kaspa Python SDK │ │ │ │ (wRPC Client) │ │ │ └─────────────────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Mainnet │ │ Testnet │ │ Custom │ │ │ │ wRPC │ │ wRPC │ │ RPC │ │ │ └─────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────┘ ```
## 功能
| 功能 | 描述 | |---------|-------------| | **发送 KAS** | 向任何 Kaspa 地址转账 KAS | | **余额查询** | 查询任意地址的余额 | | **支付 URI** | 生成 `kaspa:` 支付请求 URI | | **费率估算** | 获取当前网络费率等级 | | **网络信息** | 检查节点同步状态和区块 | | **钱包生成** | 生成新的助记词 |
## 快速开始
### 安装
```bash python3 install.py ```
**要求：** Python 3.8+ 及 pip。支持 macOS、Linux、Windows。
**安装故障排除：** - 如果 pip 失败：手动运行 `pip install kaspa`，或尝试 `KASPA_PYTHON=python3.12 python3 install.py` - 如果缺少 venv：`sudo apt install python3-venv` (Ubuntu/Debian) - 重新安装：`rm -rf .venv && python3 install.py`
### CLI 使用方法
```bash # Check balance ./kaswallet.sh balance ./kaswallet.sh balance kaspa:qrc8y...
# Send payment ./kaswallet.sh send kaspa:qrc8y... 0.5 ./kaswallet.sh send kaspa:qrc8y... max
# Generate payment URI ./kaswallet.sh uri kaspa:q... 1.5 "coffee payment"
# Network info ./kaswallet.sh info
# Fee estimates ./kaswallet.sh fees
# Generate new wallet ./kaswallet.sh generate-mnemonic ```
### 支付 URI 格式
## 架构
``` kaspa-wallet/ ├── SKILL.md ├── README.md ├── install.py # Auto-installer with venv ├── kaswallet.sh # CLI wrapper script ├── requirements.txt └── scripts/ └── kaswallet.py # Main wallet logic ```
## 配置
```bash # Environment variables (one required) export KASPA_PRIVATE_KEY="64-character-hex-string" # OR export KASPA_MNEMONIC="your twelve or twenty four word seed phrase"
# Optional export KASPA_NETWORK="mainnet" # mainnet (default), testnet-10 export KASPA_RPC_URL="wss://..." # Custom RPC endpoint export KASPA_RPC_CONNECT_TIMEOUT_MS="30000" # Connection timeout (default: 15000) ```
## 核心功能
### 查询余额
```bash ./kaswallet.sh balance # Your wallet balance ./kaswallet.sh balance kaspa:qrc8y... # Any address balance ```
**输出：** ```json {"address": "kaspa:q...", "balance": "1.5", "sompi": "150000000", "network": "mainnet"} ```
### 发送 KAS
```bash ./kaswallet.sh send <address> <amount> # Send specific amount ./kaswallet.sh send <address> max # Send entire balance ./kaswallet.sh send <address> <amount> priority # Priority fee tier ```
**输出（成功）：** ```json {"status": "sent", "txid": "abc123...", "from": "kaspa:q...", "to": "kaspa:q...", "amount": "0.5", "fee": "0.0002"} ```
**输出（错误）：** ```json {"error": "Storage mass exceeds maximum", "errorCode": "STORAGE_MASS_EXCEEDED", "hint": "...", "action": "consolidate_utxos"} ```
### 网络信息
```bash ./kaswallet.sh info ```
**输出：** ```json {"network": "mainnet", "url": "wss://...", "blocks": 12345678, "synced": true, "version": "1.0.0"} ```
### 费率估算
```bash ./kaswallet.sh fees ```
**输出：** ```json {"network": "mainnet", "low": {"feerate": 1.0, "estimatedSeconds": 60}, "economic": {...}, "priority": {...}} ```
### 生成新钱包
```bash ./kaswallet.sh generate-mnemonic ```
**输出：** ```json {"mnemonic": "word1 word2 word3 ... word24"} ```
### 支付 URI
```bash ./kaswallet.sh uri # Your address ./kaswallet.sh uri kaspa:q... 1.5 "payment" # With amount and message ```
## 错误处理
| 错误 | 原因 | 解决方案 | |-------|-------|----------| | `STORAGE_MASS_EXCEEDED` | 金额对于当前 UTXO 来说太小 | 先向自己发送 `max` 以合并 | | `NO_UTXOS` | 没有可用的输出 | 等待确认或向钱包充值 | | `INSUFFICIENT_FUNDS` | 余额过低 | 检查余额，减少金额 | | `RPC_TIMEOUT` | 网络缓慢 | 重试或增加超时时间 | | `NO_CREDENTIALS` | 缺少钱包密钥 | 设置 KASPA_PRIVATE_KEY 或 KASPA_MNEMONIC | | `SDK_NOT_INSTALLED` | 缺少 Kaspa SDK | 运行 `python3 install.py` |
## 支付流程
``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Sender │ │ Kaspa Wallet│ │ Recipient │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ 1. Initiate │ │ │──────────────────▶│ │ │ │ │ │ │ 2. Execute │ │ │ KAS Transfer │ │ │─────────────────▶│ │ │ │ │ │ 3. Confirm │ │ │◀──────────────────│ │ 4. Success │ │ │◀──────────────────│ │ │ │ │ ```
## 常见工作流程
### 合并 UTXO（修复存储质量错误）
当发送失败并提示 `STORAGE_MASS_EXCEEDED` 时：
```bash # 1. Get your address ./kaswallet.sh balance # Returns: {"address": "kaspa:qYOUR_ADDRESS...", ...}
# 2. Send max to yourself (consolidates UTXOs) ./kaswallet.sh send kaspa:qYOUR_ADDRESS... max
# 3. Now send the original amount (will work) ./kaswallet.sh send kaspa:qRECIPIENT... 0.5 ```
### 检查交易状态
发送后，使用 `txid` 在区块浏览器上验证： - 主网：`https://explorer.kaspa.org/txs/{txid}` - 测试网：`https://explorer-tn10.kaspa.org/txs/{txid}`
### 切换网络
```bash # Testnet export KASPA_NETWORK="testnet-10" ./kaswallet.sh info
# Back to mainnet export KASPA_NETWORK="mainnet" ./kaswallet.sh info ```
## 单位
- **KAS**：人类可读单位（例如 1.5 KAS） - **sompi**：最小单位，1 KAS = 100,000,000 sompi
所有命令输入均接受 KAS。输出在相关时会同时包含 KAS 和 sompi。
## 安全注意事项
- **私钥**：切勿在日志或错误消息中暴露 - **助记词**：仅通过环境变量传递 - **无磁盘存储**：钱包不存储凭据 - **新建连接**：每个命令建立新的 RPC 连接 - **地址格式**：验证 Kaspa 地址（`kaspa:q...` 格式）
## 与传统钱包的比较
| 功能 | 传统钱包 | Kaspa Wallet CLI | |---------|-------------------|------------------| | 设置 | GUI 安装 | `python3 install.py` | | 界面 | 桌面应用 | CLI + JSON 输出 | | 自动化 | 有限 | 完全（JSON 解析） | | 托管 | 各不相同 | 自托管 | | Agent 友好 | 否 | 是 |
## 路线图
- [ ] 地址二维码生成 - [ ] 支付链接 - [ ] 交易历史 - [ ] 多地址支持 - [ ] 批量支付 - [ ] Telegram 机器人集成
## 资源
- [Kaspa 文档](https://docs.kaspa.org/) - [Kaspa 浏览器](https://explorer.kaspa.org/) - [kaspa-py SDK](https://github.com/aspect-build/kaspa-py)