11 KiB

Raw Blame History

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字节）

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）

pub enum AccountType {
    Personal = 0,      // 个人账户
    Enterprise = 1,    // 企业账户
    Contract = 2,      // 智能合约
    System = 3,        // 系统账户
}

1.3 KYC等级（WalletKYCLevel）

pub enum WalletKYCLevel {
    None = 0,          // 未认证
    Basic = 1,         // 基础认证
    Standard = 2,      // 标准认证
    Advanced = 3,      // 高级认证
}

关键特性:

✅ 地址本身包含账户类型和KYC信息
✅ 支持司法管辖区编码（ISO 3166-1）
✅ 32字节固定长度
✅ 完整的序列化/反序列化

2. key_manager.rs - 密钥管理

核心功能: 支持三种签名算法的密钥管理

2.1 签名算法（SignatureAlgorithm）

pub enum SignatureAlgorithm {
    Ed25519,       // 默认账户密钥，用于普通交易
    BLS,           // 用于聚合签名（多签、跨链中继）
    Dilithium5,    // 后量子备选，用于高安全需求账户
}

算法参数:

算法	公钥长度	私钥长度	签名长度	用途
Ed25519	32字节	32字节	64字节	普通交易
BLS	48字节	32字节	96字节	聚合签名
Dilithium5	2592字节	4864字节	4595字节	后量子加密

2.2 KeyPair 结构体

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）

pub enum AssetType {
    RealEstateRevenue,  // 不动产收益权
    Equity,             // 股权
    Debt,               // 债权
    Commodity,          // 商品
    Other(String),      // 其他
}

3.3 风险等级（RiskLevel）

pub enum RiskLevel {
    Low = 1,       // 低风险（风险权重0-50）
    Medium = 2,    // 中风险（风险权重51-100）
    High = 3,      // 高风险（风险权重>100）
}

3.4 GNACSInfo 结构体

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 模块导出

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 错误类型

pub enum WalletError {
    KeyError(String),           // 密钥错误
    NetworkError(String),       // 网络错误
    ConstitutionalError(String),// 宪法错误
    Other(String),              // 其他错误
}

🔗 依赖关系

Cargo.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"] }

关键依赖:

nac-udm: NAC统一定义模块（28,777行）
nac-sdk: NAC开发工具包（5,490行）
ed25519-dalek: Ed25519签名算法
bip39: BIP39助记词
aes-gcm: AES-GCM加密
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%)

✅ 结构化地址系统
- ✅ 32字节地址结构
- ✅ 账户类型支持
- ✅ KYC等级支持
- ✅ 司法管辖区支持
✅ 密钥管理框架
- ✅ 三种签名算法支持
- ✅ 密钥对结构定义
- ⚠️ 密钥生成（占位符）
✅ GNACS解析器
- ✅ GNACS编码解析
- ✅ 资产类型识别
- ✅ 风险等级计算
✅ 错误处理
- ✅ 完整的错误类型定义

待完成功能 (15%)

⏳ 密钥管理实现
- ⏳ 真实的Ed25519密钥生成
- ⏳ BLS密钥生成
- ⏳ Dilithium5密钥生成
- ⏳ 助记词支持
⏳ 交易构造完善
- ⏳ 完整的交易签名
- ⏳ 多签支持
⏳ 存储加密
- ⏳ 密钥加密存储
- ⏳ 安全的密钥导入/导出
⏳ 完整的测试
- ⏳ 单元测试
- ⏳ 集成测试

🎯 核心特性

1. NAC独有的结构化地址

NAC的地址不是简单的公钥哈希，而是包含丰富信息的结构化地址：

传统区块链地址:

0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

NAC结构化地址:

[版本][类型][KYC][地区][保留][公钥哈希]
  01    00    02   0156   00   [26字节哈希]
  ↓     ↓     ↓     ↓
版本1  个人  标准  中国(156)

优势:

✅ 地址本身包含合规信息
✅ 支持KYC等级验证
✅ 支持司法管辖区识别
✅ 支持账户类型区分

2. 三种签名算法支持

NAC支持三种签名算法，满足不同场景需求：

Ed25519: 默认算法，性能好，签名小
BLS: 支持聚合签名，用于多签和跨链
Dilithium5: 后量子算法，抗量子计算攻击

3. GNACS资产分类系统

NAC使用GNACS（全球新资产分类系统）对资产进行分类：

资产类型识别
风险权重计算（巴塞尔III标准）
合规等级标识
实时状态跟踪

📊 代码质量

指标	评分	说明
代码规范	⭐⭐⭐⭐⭐	完全符合Rust最佳实践
文档注释	⭐⭐⭐⭐☆	大部分模块有注释
错误处理	⭐⭐⭐⭐☆	有错误类型定义
测试覆盖	⭐⭐☆☆☆	缺少测试
安全性	⭐⭐⭐⭐☆	使用zeroize清除敏感数据

🔄 与其他模块的关系

nac-wallet-core
  ├── 依赖 nac-udm (核心类型定义)
  ├── 依赖 nac-sdk (SDK接口)
  ├── 被 nac-wallet-cli 使用
  └── 被 nac-vision-wallet 使用

📌 关键发现

结构化地址: NAC独有的地址系统，包含合规信息
多算法支持: 支持Ed25519、BLS、Dilithium5三种签名算法
GNACS解析: 完整的资产分类系统解析
密钥管理未完成: 密钥生成函数使用占位符，需要实现
安全设计: 使用zeroize清除敏感数据

🚀 改进建议

完成密钥生成: 集成真实的密码学库
- 使用ed25519-dalek实现Ed25519
- 集成BLS库
- 集成pqcrypto-dilithium实现Dilithium5
添加助记词支持: 使用bip39生成和恢复助记词
完善测试: 添加单元测试和集成测试
加密存储: 实现密钥的加密存储
文档完善: 为每个模块添加详细的文档注释

📝 总结

nac-wallet-core是NAC公链钱包的核心模块，实现了NAC独有的结构化地址、多算法密钥管理、GNACS资产分类等核心功能。该模块设计优秀，但部分功能（如密钥生成）尚未完成实现。完成后将是一个功能完整、安全可靠的钱包核心库。

评级: ⭐⭐⭐⭐☆ (4/5)
推荐: 需要完成密钥生成后才能用于生产

分析完成时间: 2026-02-18 10:30:00
下一个待分析模块: nac-rpc

11 KiB Raw Blame History Unescape Escape