268 lines
5.9 KiB
Markdown
268 lines
5.9 KiB
Markdown
# NAC公链钱包核心模块
|
||
|
||
NAC钱包是NAC生态中用户与区块链交互的核心工具，它不仅管理密钥和资产，更确保每一笔交易在宪法框架内合规执行。
|
||
|
||
## 📦 模块概览
|
||
|
||
### 核心模块
|
||
|
||
1. **密钥管理模块** (`key_manager.rs`)
|
||
- 支持三种签名算法：Ed25519、BLS、Dilithium5
|
||
- BIP39助记词生成与恢复
|
||
- BIP44路径派生 (`m/44'/626'/0'/0/index`)
|
||
- 安全的密钥存储和导出
|
||
|
||
2. **地址模块** (`address.rs`)
|
||
- 32字节结构化地址
|
||
- 包含：版本 + 账户类型 + KYC等级 + 区域 + 公钥哈希
|
||
- 支持4种账户类型：个人、企业、合约、系统
|
||
- 支持4级KYC：无认证、基础、标准、高级
|
||
|
||
3. **交易模块** (`transaction.rs`)
|
||
- 完整的交易构造流程
|
||
- 支持多种交易类型：XTZH/XIC转账、ACC-20/ACC-1400代币转账
|
||
- Builder模式构造交易
|
||
- CR（宪法收据）集成
|
||
- 交易签名和验证
|
||
|
||
4. **宪法收据模块** (`constitutional_receipt.rs`)
|
||
- CR生成和验证
|
||
- CEE节点交互
|
||
- 签名管理
|
||
- 有效期检查
|
||
|
||
5. **GNACS解析器** (`gnacs_parser.rs`)
|
||
- 48位GNACS编码解析
|
||
- 资产类型识别
|
||
- 风险等级评估
|
||
- 合规等级判断
|
||
|
||
6. **网络通信模块** (`network.rs`)
|
||
- RPC客户端
|
||
- CEE节点通信
|
||
- 余额查询
|
||
- 交易广播
|
||
|
||
7. **存储模块** (`storage.rs`)
|
||
- 密钥库文件加密存储
|
||
- AES-256-GCM加密
|
||
- PBKDF2密钥派生
|
||
- JSON格式存储
|
||
|
||
8. **账户管理模块** (`account.rs`)
|
||
- 账户信息管理
|
||
- 余额追踪
|
||
- Nonce管理
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
cd nac-wallet-core
|
||
cargo build
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
#### 1. 创建钱包
|
||
|
||
```rust
|
||
use nac_wallet_core::*;
|
||
|
||
// 生成密钥对
|
||
let keypair = KeyPair::generate(SignatureAlgorithm::Ed25519)?;
|
||
|
||
// 计算公钥哈希
|
||
let pubkey_hash = keypair.public_key_hash();
|
||
|
||
// 创建结构化地址
|
||
let address = StructuredAddress::new(
|
||
AccountType::Personal,
|
||
WalletKYCLevel::Standard,
|
||
156, // 中国
|
||
pubkey_hash,
|
||
);
|
||
```
|
||
|
||
#### 2. 构造交易
|
||
|
||
```rust
|
||
use nac_wallet_core::transaction::*;
|
||
|
||
// 使用Builder模式构造交易
|
||
let tx = TransactionBuilder::new(TransactionType::XTZHTransfer)
|
||
.from(from_address)
|
||
.to(to_address)
|
||
.amount(1000000) // 1 XTZH
|
||
.nonce(1)
|
||
.build()?;
|
||
```
|
||
|
||
#### 3. 请求宪法收据
|
||
|
||
```rust
|
||
use nac_wallet_core::constitutional_receipt::*;
|
||
|
||
// 创建CEE请求
|
||
let request = CEERequest::new(tx.payload.hash());
|
||
|
||
// 发送到CEE节点
|
||
let receipt = network_client.request_cr(request).await?;
|
||
|
||
// 附加到交易
|
||
tx.attach_receipt(receipt);
|
||
```
|
||
|
||
#### 4. 签名和广播
|
||
|
||
```rust
|
||
// 计算签名消息
|
||
let message = tx.signing_message();
|
||
|
||
// 签名
|
||
let signature = keypair.sign(&message)?;
|
||
tx.sign(signature);
|
||
|
||
// 验证交易
|
||
tx.verify()?;
|
||
|
||
// 广播
|
||
let tx_hash = network_client.broadcast_transaction(&tx.to_bytes()?).await?;
|
||
```
|
||
|
||
## 🔧 CLI工具
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
cd nac-wallet-cli
|
||
cargo build --release
|
||
```
|
||
|
||
### 使用
|
||
|
||
```bash
|
||
# 创建钱包
|
||
nac-wallet-cli create --account-type personal --kyc-level 2 --region 156
|
||
|
||
# 查询余额
|
||
nac-wallet-cli balance <address>
|
||
|
||
# 发送交易
|
||
nac-wallet-cli send <to_address> <amount> --asset xtzh
|
||
|
||
# 查看钱包信息
|
||
nac-wallet-cli info <address>
|
||
```
|
||
|
||
## 📋 技术规范
|
||
|
||
### 签名算法
|
||
|
||
| 算法 | 用途 | 公钥长度 | 私钥长度 | 签名长度 |
|
||
|------|------|----------|----------|----------|
|
||
| Ed25519 | 默认账户密钥 | 32字节 | 32字节 | 64字节 |
|
||
| BLS | 聚合签名 | 48字节 | 32字节 | 96字节 |
|
||
| Dilithium5 | 后量子 | 2592字节 | 4864字节 | 4595字节 |
|
||
|
||
### 地址结构
|
||
|
||
```
|
||
字节 0: 版本 (1)
|
||
字节 1: 账户类型 (0=个人, 1=企业, 2=合约, 3=系统)
|
||
字节 2: KYC等级 (0-3)
|
||
字节 3-4: 区域代码 (ISO 3166-1)
|
||
字节 5: 保留
|
||
字节 6-31: 公钥哈希 (SHA3-384的前26字节)
|
||
```
|
||
|
||
### 交易类型
|
||
|
||
- `0x00`: XTZH转账
|
||
- `0x01`: XIC转账
|
||
- `0x02`: ACC-20代币转账
|
||
- `0x03`: ACC-1400证券型代币转账
|
||
- `0x04`: 合约部署
|
||
- `0x05`: 合约调用
|
||
- `0x06`: 资产发行
|
||
|
||
### Gas费用
|
||
|
||
| 交易类型 | 默认Gas限制 |
|
||
|---------|-------------|
|
||
| XTZH/XIC转账 | 21,000 |
|
||
| ACC-20转账 | 50,000 |
|
||
| ACC-1400转账 | 80,000 |
|
||
| 合约调用 | 100,000 |
|
||
| 资产发行 | 150,000 |
|
||
| 合约部署 | 200,000 |
|
||
|
||
## 🔒 安全特性
|
||
|
||
1. **私钥永不离设备** - 所有签名操作在本地完成
|
||
2. **AES-256-GCM加密** - 密钥库文件使用军事级加密
|
||
3. **PBKDF2密钥派生** - 100,000次迭代，防止暴力破解
|
||
4. **CR强制验证** - 所有交易必须获得宪法收据
|
||
5. **零警告编译** - 主网级代码质量标准
|
||
|
||
## 📚 相关文档
|
||
|
||
- [NAC公链钱包核心技术白皮书](./WHITEPAPER_REQUIREMENTS.md)
|
||
- [NAC技术架构白皮书](../docs/)
|
||
- [宪法收据机制详解](../docs/constitutional-receipt.md)
|
||
- [GNACS编码规范](../docs/gnacs-standard.md)
|
||
|
||
## 🛠️ 开发状态
|
||
|
||
### 已完成 ✅
|
||
|
||
- [x] 核心数据结构
|
||
- [x] 密钥管理
|
||
- [x] 地址生成
|
||
- [x] 交易构造
|
||
- [x] CR集成
|
||
- [x] GNACS解析
|
||
- [x] CLI工具原型
|
||
|
||
### 进行中 🚧
|
||
|
||
- [ ] 实际密码学库集成（Ed25519-dalek, BLS, Dilithium）
|
||
- [ ] RPC客户端实现
|
||
- [ ] CEE节点通信
|
||
- [ ] 密钥库加密实现
|
||
- [ ] 助记词BIP39实现
|
||
|
||
### 计划中 📅
|
||
|
||
- [ ] 图形界面钱包（Web/桌面）
|
||
- [ ] 移动端钱包（iOS/Android）
|
||
- [ ] 硬件钱包支持（Ledger/Trezor）
|
||
- [ ] 宪法沙箱集成
|
||
- [ ] 多签钱包
|
||
|
||
## 🤝 贡献
|
||
|
||
NAC钱包代码必须通过宪法法院的第三方审计才能上链。所有贡献必须：
|
||
|
||
1. 遵循零警告编译标准
|
||
2. 包含完整的单元测试
|
||
3. 更新相关文档
|
||
4. 通过安全审计
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用开源许可证，具体条款待定。
|
||
|
||
## 🔗 链接
|
||
|
||
- [NAC官网](https://nac.chain)
|
||
- [开发者文档](https://docs.nac.chain)
|
||
- [GitHub仓库](https://github.com/nac-chain/nac-wallet)
|
||
|
||
---
|
||
|
||
**制定人**: NAC钱包工作组
|
||
**最后更新**: 2026年2月16日
|
||
**版本**: 0.1.0 (开发中)
|