# 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 (开发中)