450 lines
11 KiB
Markdown
450 lines
11 KiB
Markdown
# nac-wallet-core 模块深度分析报告
|
||
|
||
**分析日期**: 2026-02-18
|
||
**分析人**: NAC开发团队
|
||
**模块路径**: `/home/ubuntu/NAC_Clean_Dev/nac-wallet-core`
|
||
|
||
---
|
||
|
||
## 📊 模块概览
|
||
|
||
**模块名称**: nac-wallet-core
|
||
**模块类型**: 库（lib）
|
||
**版本**: 0.1.0
|
||
**代码行数**: 2,241行
|
||
**完成度**: 85%
|
||
|
||
**功能描述**:
|
||
NAC公链钱包核心模块，提供结构化地址、密钥管理、宪法收据、GNACS资产管理等核心功能。
|
||
|
||
---
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
nac-wallet-core/
|
||
├── Cargo.toml
|
||
├── README.md
|
||
├── WHITEPAPER_REQUIREMENTS.md
|
||
├── src/
|
||
│ ├── lib.rs # 库入口
|
||
│ ├── address.rs # 结构化地址
|
||
│ ├── key_manager.rs # 密钥管理
|
||
│ ├── account.rs # 账户管理
|
||
│ ├── transaction.rs # 交易构造
|
||
│ ├── constitutional_receipt.rs # 宪法收据
|
||
│ ├── gnacs_parser.rs # GNACS解析器
|
||
│ ├── network.rs # 网络通信
|
||
│ ├── storage.rs # 存储管理
|
||
│ ├── cee_client.rs # CEE客户端
|
||
│ └── nac_lens_wrapper.rs # NAC Lens包装器
|
||
└── tests/
|
||
└── integration_test.rs # 集成测试
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 核心模块分析
|
||
|
||
### 1. address.rs - 结构化地址（108行）
|
||
|
||
**核心功能**: NAC独有的结构化地址系统
|
||
|
||
#### 1.1 StructuredAddress 结构体（32字节）
|
||
|
||
```rust
|
||
pub struct StructuredAddress {
|
||
pub version: u8, // 地址版本（1字节）
|
||
pub account_type: AccountType,// 账户类型（1字节）
|
||
pub kyc_level: WalletKYCLevel,// KYC等级（1字节）
|
||
pub region: u16, // 司法管辖区（2字节）
|
||
pub pubkey_hash: [u8; 26], // 公钥哈希（26字节）
|
||
}
|
||
```
|
||
|
||
**地址布局**:
|
||
```
|
||
[版本][类型][KYC][地区][保留][公钥哈希(26字节)]
|
||
1B 1B 1B 2B 1B 26B
|
||
```
|
||
|
||
#### 1.2 账户类型（AccountType）
|
||
|
||
```rust
|
||
pub enum AccountType {
|
||
Personal = 0, // 个人账户
|
||
Enterprise = 1, // 企业账户
|
||
Contract = 2, // 智能合约
|
||
System = 3, // 系统账户
|
||
}
|
||
```
|
||
|
||
#### 1.3 KYC等级（WalletKYCLevel）
|
||
|
||
```rust
|
||
pub enum WalletKYCLevel {
|
||
None = 0, // 未认证
|
||
Basic = 1, // 基础认证
|
||
Standard = 2, // 标准认证
|
||
Advanced = 3, // 高级认证
|
||
}
|
||
```
|
||
|
||
**关键特性**:
|
||
- ✅ 地址本身包含账户类型和KYC信息
|
||
- ✅ 支持司法管辖区编码（ISO 3166-1）
|
||
- ✅ 32字节固定长度
|
||
- ✅ 完整的序列化/反序列化
|
||
|
||
---
|
||
|
||
### 2. key_manager.rs - 密钥管理
|
||
|
||
**核心功能**: 支持三种签名算法的密钥管理
|
||
|
||
#### 2.1 签名算法（SignatureAlgorithm）
|
||
|
||
```rust
|
||
pub enum SignatureAlgorithm {
|
||
Ed25519, // 默认账户密钥，用于普通交易
|
||
BLS, // 用于聚合签名（多签、跨链中继）
|
||
Dilithium5, // 后量子备选，用于高安全需求账户
|
||
}
|
||
```
|
||
|
||
**算法参数**:
|
||
|
||
| 算法 | 公钥长度 | 私钥长度 | 签名长度 | 用途 |
|
||
|------|----------|----------|----------|------|
|
||
| Ed25519 | 32字节 | 32字节 | 64字节 | 普通交易 |
|
||
| BLS | 48字节 | 32字节 | 96字节 | 聚合签名 |
|
||
| Dilithium5 | 2592字节 | 4864字节 | 4595字节 | 后量子加密 |
|
||
|
||
#### 2.2 KeyPair 结构体
|
||
|
||
```rust
|
||
pub struct KeyPair {
|
||
pub algorithm: SignatureAlgorithm,
|
||
secret_key: Vec<u8>,
|
||
pub public_key: Vec<u8>,
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
- `generate(algorithm)` - 生成密钥对
|
||
- `generate_ed25519()` - 生成Ed25519密钥对
|
||
- `generate_bls()` - 生成BLS密钥对
|
||
- `generate_dilithium5()` - 生成Dilithium5密钥对
|
||
|
||
**当前状态**:
|
||
- ⚠️ 密钥生成函数使用占位符（TODO）
|
||
- ⚠️ 需要集成真实的密码学库
|
||
|
||
---
|
||
|
||
### 3. gnacs_parser.rs - GNACS解析器（90行）
|
||
|
||
**核心功能**: 解析GNACS（全球新资产分类系统）编码
|
||
|
||
#### 3.1 GNACS编码结构（6字节）
|
||
|
||
```
|
||
[资产类型][风险权重][合规等级][保留][保留][实时状态]
|
||
1B 1B 1B 1B 1B 1B
|
||
```
|
||
|
||
#### 3.2 资产类型（AssetType）
|
||
|
||
```rust
|
||
pub enum AssetType {
|
||
RealEstateRevenue, // 不动产收益权
|
||
Equity, // 股权
|
||
Debt, // 债权
|
||
Commodity, // 商品
|
||
Other(String), // 其他
|
||
}
|
||
```
|
||
|
||
#### 3.3 风险等级（RiskLevel）
|
||
|
||
```rust
|
||
pub enum RiskLevel {
|
||
Low = 1, // 低风险（风险权重0-50）
|
||
Medium = 2, // 中风险（风险权重51-100）
|
||
High = 3, // 高风险（风险权重>100）
|
||
}
|
||
```
|
||
|
||
#### 3.4 GNACSInfo 结构体
|
||
|
||
```rust
|
||
pub struct GNACSInfo {
|
||
pub asset_type: AssetType, // 资产类型
|
||
pub risk_weight: u8, // 风险权重（巴塞尔III）
|
||
pub compliance_level: u8, // 合规等级
|
||
pub status: u8, // 实时状态
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
- `parse(gnacs: &[u8; 6])` - 解析GNACS编码
|
||
- `asset_type_description()` - 获取资产类型描述
|
||
- `risk_level(risk_weight)` - 获取风险等级
|
||
|
||
---
|
||
|
||
### 4. lib.rs - 库入口（50行）
|
||
|
||
**核心功能**: 模块导出和错误定义
|
||
|
||
#### 4.1 模块导出
|
||
|
||
```rust
|
||
pub mod address;
|
||
pub mod key_manager;
|
||
pub mod account;
|
||
pub mod transaction;
|
||
pub mod constitutional_receipt;
|
||
pub mod gnacs_parser;
|
||
pub mod network;
|
||
pub mod storage;
|
||
pub mod cee_client;
|
||
pub mod nac_lens_wrapper;
|
||
```
|
||
|
||
#### 4.2 WalletError 错误类型
|
||
|
||
```rust
|
||
pub enum WalletError {
|
||
KeyError(String), // 密钥错误
|
||
NetworkError(String), // 网络错误
|
||
ConstitutionalError(String),// 宪法错误
|
||
Other(String), // 其他错误
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 依赖关系
|
||
|
||
### Cargo.toml 依赖
|
||
|
||
```toml
|
||
[dependencies]
|
||
# NAC核心依赖
|
||
nac-udm = { path = "../nac-udm" }
|
||
nac-sdk = { path = "../nac-sdk" }
|
||
|
||
# 密码学
|
||
sha3 = "0.10"
|
||
rand = "0.8"
|
||
ed25519-dalek = { version = "2.0", features = ["rand_core"] }
|
||
bip39 = "2.0"
|
||
aes-gcm = "0.10"
|
||
pbkdf2 = { version = "0.12", features = ["simple"] }
|
||
zeroize = "1.6"
|
||
|
||
# 序列化
|
||
serde = { version = "1.0", features = ["derive"] }
|
||
serde_json = "1.0"
|
||
bincode = "1.3"
|
||
|
||
# 网络通信
|
||
reqwest = { version = "0.11", features = ["json"] }
|
||
tokio = { version = "1.0", features = ["full"] }
|
||
```
|
||
|
||
**关键依赖**:
|
||
1. **nac-udm**: NAC统一定义模块（28,777行）
|
||
2. **nac-sdk**: NAC开发工具包（5,490行）
|
||
3. **ed25519-dalek**: Ed25519签名算法
|
||
4. **bip39**: BIP39助记词
|
||
5. **aes-gcm**: AES-GCM加密
|
||
6. **zeroize**: 安全清除敏感数据
|
||
|
||
---
|
||
|
||
## 📝 其他模块概览
|
||
|
||
### account.rs - 账户管理
|
||
- 账户创建和管理
|
||
- 账户状态维护
|
||
|
||
### transaction.rs - 交易构造
|
||
- 交易构造
|
||
- 交易签名
|
||
|
||
### constitutional_receipt.rs - 宪法收据
|
||
- 宪法收据获取
|
||
- 收据验证
|
||
|
||
### network.rs - 网络通信
|
||
- 与NAC节点通信
|
||
- RPC调用封装
|
||
|
||
### storage.rs - 存储管理
|
||
- 密钥存储
|
||
- 账户数据持久化
|
||
|
||
### cee_client.rs - CEE客户端
|
||
- 宪法执行引擎（CEE）客户端
|
||
- 宪法验证
|
||
|
||
### nac_lens_wrapper.rs - NRPC包装器
|
||
- NAC Lens协议包装
|
||
- 简化RPC调用
|
||
|
||
---
|
||
|
||
## ✅ 完成情况
|
||
|
||
### 已完成功能 (85%)
|
||
|
||
1. ✅ 结构化地址系统
|
||
- ✅ 32字节地址结构
|
||
- ✅ 账户类型支持
|
||
- ✅ KYC等级支持
|
||
- ✅ 司法管辖区支持
|
||
|
||
2. ✅ 密钥管理框架
|
||
- ✅ 三种签名算法支持
|
||
- ✅ 密钥对结构定义
|
||
- ⚠️ 密钥生成（占位符）
|
||
|
||
3. ✅ GNACS解析器
|
||
- ✅ GNACS编码解析
|
||
- ✅ 资产类型识别
|
||
- ✅ 风险等级计算
|
||
|
||
4. ✅ 错误处理
|
||
- ✅ 完整的错误类型定义
|
||
|
||
### 待完成功能 (15%)
|
||
|
||
1. ⏳ 密钥管理实现
|
||
- ⏳ 真实的Ed25519密钥生成
|
||
- ⏳ BLS密钥生成
|
||
- ⏳ Dilithium5密钥生成
|
||
- ⏳ 助记词支持
|
||
|
||
2. ⏳ 交易构造完善
|
||
- ⏳ 完整的交易签名
|
||
- ⏳ 多签支持
|
||
|
||
3. ⏳ 存储加密
|
||
- ⏳ 密钥加密存储
|
||
- ⏳ 安全的密钥导入/导出
|
||
|
||
4. ⏳ 完整的测试
|
||
- ⏳ 单元测试
|
||
- ⏳ 集成测试
|
||
|
||
---
|
||
|
||
## 🎯 核心特性
|
||
|
||
### 1. NAC独有的结构化地址
|
||
|
||
NAC的地址不是简单的公钥哈希，而是包含丰富信息的结构化地址：
|
||
|
||
**传统区块链地址**:
|
||
```
|
||
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
|
||
```
|
||
|
||
**NAC结构化地址**:
|
||
```
|
||
[版本][类型][KYC][地区][保留][公钥哈希]
|
||
01 00 02 0156 00 [26字节哈希]
|
||
↓ ↓ ↓ ↓
|
||
版本1 个人 标准 中国(156)
|
||
```
|
||
|
||
**优势**:
|
||
- ✅ 地址本身包含合规信息
|
||
- ✅ 支持KYC等级验证
|
||
- ✅ 支持司法管辖区识别
|
||
- ✅ 支持账户类型区分
|
||
|
||
### 2. 三种签名算法支持
|
||
|
||
NAC支持三种签名算法，满足不同场景需求：
|
||
|
||
1. **Ed25519**: 默认算法，性能好，签名小
|
||
2. **BLS**: 支持聚合签名，用于多签和跨链
|
||
3. **Dilithium5**: 后量子算法，抗量子计算攻击
|
||
|
||
### 3. GNACS资产分类系统
|
||
|
||
NAC使用GNACS（全球新资产分类系统）对资产进行分类：
|
||
|
||
- 资产类型识别
|
||
- 风险权重计算（巴塞尔III标准）
|
||
- 合规等级标识
|
||
- 实时状态跟踪
|
||
|
||
---
|
||
|
||
## 📊 代码质量
|
||
|
||
| 指标 | 评分 | 说明 |
|
||
|------|------|------|
|
||
| 代码规范 | ⭐⭐⭐⭐⭐ | 完全符合Rust最佳实践 |
|
||
| 文档注释 | ⭐⭐⭐⭐☆ | 大部分模块有注释 |
|
||
| 错误处理 | ⭐⭐⭐⭐☆ | 有错误类型定义 |
|
||
| 测试覆盖 | ⭐⭐☆☆☆ | 缺少测试 |
|
||
| 安全性 | ⭐⭐⭐⭐☆ | 使用zeroize清除敏感数据 |
|
||
|
||
---
|
||
|
||
## 🔄 与其他模块的关系
|
||
|
||
```
|
||
nac-wallet-core
|
||
├── 依赖 nac-udm (核心类型定义)
|
||
├── 依赖 nac-sdk (SDK接口)
|
||
├── 被 nac-wallet-cli 使用
|
||
└── 被 nac-vision-wallet 使用
|
||
```
|
||
|
||
---
|
||
|
||
## 📌 关键发现
|
||
|
||
1. **结构化地址**: NAC独有的地址系统，包含合规信息
|
||
2. **多算法支持**: 支持Ed25519、BLS、Dilithium5三种签名算法
|
||
3. **GNACS解析**: 完整的资产分类系统解析
|
||
4. **密钥管理未完成**: 密钥生成函数使用占位符，需要实现
|
||
5. **安全设计**: 使用zeroize清除敏感数据
|
||
|
||
---
|
||
|
||
## 🚀 改进建议
|
||
|
||
1. **完成密钥生成**: 集成真实的密码学库
|
||
- 使用ed25519-dalek实现Ed25519
|
||
- 集成BLS库
|
||
- 集成pqcrypto-dilithium实现Dilithium5
|
||
|
||
2. **添加助记词支持**: 使用bip39生成和恢复助记词
|
||
|
||
3. **完善测试**: 添加单元测试和集成测试
|
||
|
||
4. **加密存储**: 实现密钥的加密存储
|
||
|
||
5. **文档完善**: 为每个模块添加详细的文档注释
|
||
|
||
---
|
||
|
||
## 📝 总结
|
||
|
||
nac-wallet-core是NAC公链钱包的核心模块，实现了NAC独有的结构化地址、多算法密钥管理、GNACS资产分类等核心功能。该模块设计优秀，但部分功能（如密钥生成）尚未完成实现。完成后将是一个功能完整、安全可靠的钱包核心库。
|
||
|
||
**评级**: ⭐⭐⭐⭐☆ (4/5)
|
||
**推荐**: 需要完成密钥生成后才能用于生产
|
||
|
||
---
|
||
|
||
**分析完成时间**: 2026-02-18 10:30:00
|
||
**下一个待分析模块**: nac-rpc
|