# NAC钱包核心技术白皮书 - 实现要点

## 一、钱包架构

### 核心模块
1. **密钥管理模块** - 生成/存储/签名
2. **账户管理模块** - 地址派生、余额查询、历史记录
3. **交易构造模块** - 转账、合约调用、资产发行
4. **宪法收据模块** - 向CEE请求CR、验证CR
5. **资产解析模块** - GNACS解析、代币标准识别
6. **网络通信模块** - 与节点RPC交互、与CEE交互
7. **宪法沙箱模块** - 模拟交易合规性

### 底层依赖
- nac-primitives (Address, Hash, 编码转换)
- nac_serde (序列化)
- nac-toolbox (可选，用于一键上链)
- 密码学库 (Ed25519, BLS, Dilithium)

## 二、密钥管理与账户模型

### 2.1 密钥生成
支持三种签名算法：
1. **Ed25519** - 默认账户密钥，用于普通交易
2. **BLS** - 用于需要聚合签名的场景（如多签、跨链中继）
3. **Dilithium5** - 后量子备选，用于高安全需求账户

**助记词**: 遵循BIP39，生成种子。派生路径遵循NAC标准: `m/44'/626'/0'/0/index` (其中626是NAC的BIP44 coin type，需向SLIP注册)

### 2.2 结构化地址生成
公钥经SHA3-384哈希，取前26字节，加上版本、类型、KYC等级、区域等字段，拼接成32字节Address。钱包应提供从公钥到结构化地址的完整计算。

**地址字段**:
- version: 地址格式版本 (当前1)
- type: 账户类型 (个人/企业/合约/系统)
- kyc_level: KYC等级 (0-3)
- region: 司法管辖区代码 (ISO3166-1)
- pubkey_hash: 公钥哈希 (26字节)

### 2.3 密钥存储
1. **加密**: 使用AES-256-GCM加密私钥，密码派生自用户口令
2. **存储格式**: JSON文件 (类似Web3 Secret Storage)，包含加密私钥、地址、元数据（账户类型、KYC凭证哈希等）
3. **硬件钱包支持**: 计划支持Ledger、Trezor等硬件钱包，通过NAC App集成

## 三、交易构造与宪法收据

### 3.1 交易结构
NAC交易包含两部分：**交易体 + 宪法收据 (CR)**。CR必须在交易广播前获取。

```
message Transaction {
    bytes transaction_payload = 1; // 原始交易数据（类型、金额、目标等）
    ConstitutionalReceipt receipt = 2; // 宪法收据
}
```

### 3.2 交易构造流程
1. **用户输入**: 选择资产、输入接收地址、金额等
2. **交易体构造**: 钱包根据资产类型（XTZH、XIC、ACC-20代币）构造相应的交易体
3. **向CEE请求CR**:
   - 钱包将交易体（或交易哈希）及辅助信息（如资产GNACS、KYC凭证）发送给CEE节点
   - CEE验证交易符合宪法条款，返回CR
4. **签名**: 用户用私钥对交易体+CR的联合哈希签名（确保交易和CR绑定）
5. **广播**: 将完整交易（含签名）发送至NAC节点

### 3.3 宪法收据 (CR) 格式回顾
```
message ConstitutionalReceipt {
    bytes32 transaction_hash;
    bytes32 constitutional_hash;
    uint64 clause_mask;
    bytes32 execution_result_hash;
    uint64 timestamp;
    uint64 validity_window;
    repeated bytes signatures; // CEE节点签名
    bytes32 receipt_id;
}
```

钱包需验证CR的签名、宪法哈希是否匹配当前网络、是否在有效期内。

### 3.4 多CEE节点策略
钱包可配置多个CEE节点地址。请求CR时，可并行请求，取第一个有效响应，或等待多个签名（对于高价值交易）。若CEE节点无响应，可切换备用节点。

## 四、资产支持

### 4.1 原生代币
1. **XTZH**: 稳定币，用于支付、储备。单位: xtzh (精度1e6)。钱包需显示XTZH余额、汇率（与SDR/USD）
2. **XIC**: 治理币，用于支付交易费、质押。单位: xic (精度1e18)

### 4.2 ACC-20代币
1. 通过合约地址识别，从链上获取GNACS编码
2. 钱包解析GNACS，显示资产类型、风险等级、合规要求等信息
3. 支持发送ACC-20代币，调用合约的transfer方法

### 4.3 ACC-1400证券型代币
1. 支持分区余额（如普通股、员工股）
2. 发送时需指定分区ID
3. 钱包应展示不同分区的余额

### 4.4 GNACS解析
钱包内置GNACS解析器，将48位编码转换为人类可读信息：
1. 资产类型（如"不动产收益权"）
2. 风险权重（巴塞尔III）
3. 合规等级（完全合规/高风险等）
4. 实时状态（正常/冻结/注销）

## 五、与CEE交互协议

### 5.1 CEE节点发现
钱包可从链上系统合约（CEEList）获取当前活跃CEE节点列表（公钥、端点）。建议钱包缓存此列表，定期更新。

### 5.2 请求CR的API
```
POST /cee/v1/issue-receipt
Content-Type: application/json

{
    "transaction_hash": "0x...",
    "transaction_payload": "base64...", // 可选
    "auxiliary_data": {
        "kyc_proof": "...",
        "asset_gnacs": "..."
    }
}
```

响应:
```
{
    "receipt": { ... }, // CR对象
    "signature": "0x..." // CEE节点签名（已包含在CR中）
}
```

### 5.3 错误处理
CEE可能返回错误（如"KYC等级不足"、"资产已冻结"），钱包应解析错误信息并友好提示用户。

### 5.4 离线CR（高级）
对于特殊场景（如完全离线环境），CEE可提供预签名收据，但有效期较短。钱包需在有效期内广播交易。

## 六、离线与在线模式

### 6.1 在线模式
默认模式。钱包连接节点，实时查询余额、发送交易、获取CR。

### 6.2 离线模式
1. 用户可在离线环境构造交易，导出待签名文件
2. 将文件导入在线设备（或通过二维码）获取CR和广播
3. 离线钱包需存储宪法状态文件（定期更新），用于本地解析宪法条款、验证CR签名、估算费用等

### 6.3 宪法状态同步
钱包定期从节点同步最新的宪法状态文件（constitutional_state.json），用于本地解析宪法条款、验证CR签名、估算费用等。

## 七、宪法沙箱集成
钱包应集成宪法沙箱（nac sandbox），允许用户在发送真实交易前模拟交易结果。

1. 用户选择"测试模式"，钱包调用本地沙箱API，模拟交易执行，返回合规性结果、预估费用、CR等
2. 沙箱模式不消耗真实XIC，适合新手学习和复杂交易验证

## 八、与nac-toolbox及一键上链系统的联动
钱包将作为nac-toolbox的一部分，提供CLI和API，同时也有独立的图形界面版本（桌面/移动/Web）。所有钱包实现必须通过宪法法院的审计，确保不泄露私钥、不篡改交易。

1. **一键上链过程中**，需要用户签名资产发行交易，钱包负责签名并将交易提交
2. 钱包提供"资产发行"界面，引导用户完成信息填写（可复用一键上链前端部分逻辑）

## 九、安全与审计

### 9.1 私钥安全
1. 私钥永不离设备，不通过网络发送
2. 支持硬件钱包、生物识别等额外保护

### 9.2 交易验证
1. 钱包在签名前必须向用户展示完整的交易详情（包括接收地址、金额、资产类型、CR信息）
2. 高风险交易（如资产发行、大额转账）需二次确认

### 9.3 代码审计
1. 钱包代码必须开源，并接受宪法法院授权的第三方审计
2. 每次发布新版本，需提交审计报告，版本哈希上链存证

### 9.4 宪法免疫集成
钱包可集成宪政免疫系统客户端，定期检查自身代码哈希与链上合法版本是否一致，防止篡改。

## 十、路线图

| 阶段 | 时间 | 交付物 |
|------|------|--------|
| Phase 1 | 2026.02-03 | CLI钱包原型，支持XTZH/XIC转账、CR获取 |
| Phase 2 | 2026.03-04 | ACC-20/ACC-1400资产支持、GNACS解析 |
| Phase 3 | 2026.04-05 | 图形界面钱包（Web/桌面） |
| Phase 4 | 2026.05-06 | 移动端钱包（iOS/Android） |
| Phase 5 | 2026.06 | 硬件钱包支持、宪法沙箱集成 |
| Phase 6 | 2026.07 | 主网上线，通过宪法法院审计 |

## 十一、结论
NAC钱包是连接用户与宪法区块链的桥梁。它不仅管理密钥和资产，更确保每一笔交易在宪法框架内合规执行。通过深度集成CEE、GNACS、宪法状态等NAC原生特性，钱包成为NAC生态中不可或缺的"合规入口"。所有实现均遵循开源、可审计原则，与NAC"宪美中心化框架下的去中心化"理念一脉相承。

---

**制定人**: NAC钱包工作组
**最后更新**: 2026年2月14日
**文档状态**: 正式发布