NAC_Blockchain/nac-wallet-core/README.md

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管理

🚀 快速开始

安装依赖

cd nac-wallet-core
cargo build

使用示例

1. 创建钱包

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. 构造交易

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. 请求宪法收据

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. 签名和广播

// 计算签名消息
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工具

安装

cd nac-wallet-cli
cargo build --release

使用

# 创建钱包
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公链钱包核心技术白皮书
• NAC技术架构白皮书
• 宪法收据机制详解
• GNACS编码规范

🛠️ 开发状态

已完成 ✅

• 核心数据结构
• 密钥管理
• 地址生成
• 交易构造
• CR集成
• GNACS解析
• CLI工具原型

进行中 🚧

• 实际密码学库集成（Ed25519-dalek, BLS, Dilithium）
• RPC客户端实现
• CEE节点通信
• 密钥库加密实现
• 助记词BIP39实现

计划中 📅

• 图形界面钱包（Web/桌面）
• 移动端钱包（iOS/Android）
• 硬件钱包支持（Ledger/Trezor）
• 宪法沙箱集成
• 多签钱包

🤝 贡献

NAC钱包代码必须通过宪法法院的第三方审计才能上链。所有贡献必须：

1. 遵循零警告编译标准
2. 包含完整的单元测试
3. 更新相关文档
4. 通过安全审计

📄 许可证

本项目采用开源许可证，具体条款待定。

🔗 链接

• NAC官网
• 开发者文档
• GitHub仓库

---

制定人: NAC钱包工作组
最后更新: 2026年2月16日
版本: 0.1.0 (开发中)