1046 lines
28 KiB
Markdown
1046 lines
28 KiB
Markdown
# NAC统一定义模块（UDM）开发说明文档
|
||
|
||
**版本**: v0.1.0
|
||
**作者**: NAC公链开发小组
|
||
**日期**: 2025-02-07
|
||
**状态**: 开发中
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#项目概述)
|
||
2. [架构设计](#架构设计)
|
||
3. [核心组件](#核心组件)
|
||
4. [已实现模块](#已实现模块)
|
||
5. [开发指南](#开发指南)
|
||
6. [测试指南](#测试指南)
|
||
7. [多语言支持](#多语言支持)
|
||
8. [路线图](#路线图)
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
NAC统一定义模块（Unified Definition Module, UDM）是NAC原生公链的**单一真理来源（Single Source of Truth）**，统一管理整个NAC生态系统中的所有类型定义、函数签名、常量和版本信息。
|
||
|
||
### 设计哲学
|
||
|
||
**"定义即真理，规则即共识"**
|
||
|
||
UDM采用元定义系统（Meta-Definition System），实现了"定义如何定义"的自举机制，确保所有定义在整个NAC生态中保持一致性和可追溯性。
|
||
|
||
### 核心特性
|
||
|
||
- **语言无关**: 支持Rust、Go、Charter三种语言的自动绑定生成
|
||
- **版本管理**: 基于语义化版本（SemVer 2.0.0）的定义版本控制
|
||
- **分层架构**: 完全遵循NAC的3层架构（L2/L1/L0）
|
||
- **类型安全**: 强类型系统，编译时检查
|
||
- **可追溯性**: 每个定义都有唯一的UID和完整的元数据
|
||
|
||
### 技术栈
|
||
|
||
- **实现语言**: Rust 1.70+
|
||
- **序列化**: serde + serde_json
|
||
- **哈希算法**: SHA-256
|
||
- **测试框架**: Rust内置测试框架
|
||
|
||
---
|
||
|
||
## 架构设计
|
||
|
||
### 3层架构
|
||
|
||
NAC采用清晰的3层架构设计，UDM完全遵循这一架构：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ L2: 宪法治理层 (Constitutional Governance Layer) │
|
||
│ - 宪法收据、宪法条款、网络规则、CCRN授权 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ L1: 多链协议层 (Multi-Chain Protocol Layer) │
|
||
│ - CBPP共识、GNACS分类、ACC协议族、NVM虚拟机 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ L0: CSNP结构化网络层 (CSNP Structured Network Layer) │
|
||
│ - GIDS、MA-RCM、AA-PE、FTAN、UCA │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
nac-udm/
|
||
├── Cargo.toml # Rust项目配置
|
||
├── README.md # 项目说明
|
||
├── CHANGELOG.md # 版本变更日志
|
||
├── DEVELOPMENT_GUIDE.md # 本文档
|
||
├── API_SPECIFICATION.md # API规范文档（待生成）
|
||
│
|
||
├── src/
|
||
│ ├── lib.rs # 模块入口
|
||
│ │
|
||
│ ├── registry/ # 核心注册表系统
|
||
│ │ ├── mod.rs
|
||
│ │ ├── uid.rs # 统一标识符
|
||
│ │ ├── version.rs # 版本管理
|
||
│ │ ├── definition.rs # 定义抽象
|
||
│ │ ├── registry.rs # 定义注册表
|
||
│ │ └── language.rs # 多语言支持
|
||
│ │
|
||
│ ├── primitives/ # 基础原语类型
|
||
│ │ ├── mod.rs
|
||
│ │ ├── address.rs # 地址类型（20字节）
|
||
│ │ ├── hash.rs # 哈希类型（32字节）
|
||
│ │ ├── timestamp.rs # 时间戳类型
|
||
│ │ └── signature.rs # 签名类型
|
||
│ │
|
||
│ ├── l2_governance/ # L2: 宪法治理层
|
||
│ │ ├── mod.rs
|
||
│ │ ├── constitutional/ # 宪法收据、CEE
|
||
│ │ ├── clauses/ # 宪法条款库
|
||
│ │ ├── rules/ # 网络规则定义
|
||
│ │ ├── ccrn/ # 跨链中继节点授权
|
||
│ │ └── penalties/ # 惩罚条款
|
||
│ │
|
||
│ ├── l1_protocol/ # L1: 多链协议层
|
||
│ │ ├── mod.rs
|
||
│ │ ├── cbpp/ # 宪政区块生产协议
|
||
│ │ │ ├── mod.rs
|
||
│ │ │ ├── constitutional_receipt.rs
|
||
│ │ │ ├── fluid_block.rs
|
||
│ │ │ ├── open_production_network.rs
|
||
│ │ │ └── gossip_protocol.rs
|
||
│ │ ├── gnacs/ # 全球资产分类系统
|
||
│ │ │ ├── mod.rs
|
||
│ │ │ ├── code.rs
|
||
│ │ │ ├── category.rs
|
||
│ │ │ ├── jurisdiction.rs
|
||
│ │ │ ├── compliance.rs
|
||
│ │ │ └── risk.rs
|
||
│ │ ├── acc/ # ACC协议族（待实现）
|
||
│ │ └── nvm/ # NVM 2.0虚拟机（待实现）
|
||
│ │
|
||
│ ├── l0_native/ # L0: CSNP网络层
|
||
│ │ ├── mod.rs
|
||
│ │ ├── gids/ # 全域身份目录服务
|
||
│ │ ├── ma_rcm/ # 多链自适应连接管理器
|
||
│ │ ├── aa_pe/ # 资产感知传播引擎
|
||
│ │ ├── ftan/ # 碎片化交易聚合网络
|
||
│ │ └── uca/ # 统一跨链审计器
|
||
│ │
|
||
│ └── utils/ # 工具函数
|
||
│ └── mod.rs
|
||
│
|
||
├── tests/ # 集成测试
|
||
├── docs/ # 文档
|
||
└── tools/ # 工具脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 核心组件
|
||
|
||
### 1. 统一标识符（UID）
|
||
|
||
UID是UDM的核心标识系统，为每个定义分配唯一的分层命名空间标识符。
|
||
|
||
**格式**: `nac.<layer>.<module>.<definition>`
|
||
|
||
**示例**:
|
||
- `nac.primitives.Address.v1` - 地址类型
|
||
- `nac.cbpp.ConstitutionalReceipt.v1` - 宪法收据
|
||
- `nac.gnacs.GNACSCode.v1` - GNACS编码
|
||
|
||
**特性**:
|
||
- 分层命名空间（Layer、Module、Definition）
|
||
- 父子关系查询
|
||
- 层级过滤
|
||
- 字符串解析和验证
|
||
|
||
### 2. 版本管理（Version）
|
||
|
||
基于语义化版本（SemVer 2.0.0）的版本管理系统。
|
||
|
||
**格式**: `major.minor.patch[-prerelease][+build]`
|
||
|
||
**示例**:
|
||
- `1.0.0` - 稳定版本
|
||
- `2.1.3` - 功能更新
|
||
- `3.0.0-alpha.1` - 预发布版本
|
||
- `1.2.3+20250207` - 带构建元数据
|
||
|
||
**特性**:
|
||
- 版本比较（>, <, ==）
|
||
- 兼容性检查
|
||
- 版本递增（bump_major, bump_minor, bump_patch）
|
||
- 预发布和构建元数据支持
|
||
|
||
### 3. 定义抽象（Definition）
|
||
|
||
元定义系统的核心，定义"什么是定义"。
|
||
|
||
**字段**:
|
||
- `uid`: UID - 唯一标识符
|
||
- `version`: Version - 版本号
|
||
- `name`: String - 定义名称
|
||
- `description`: String - 定义描述
|
||
- `definition_type`: DefinitionType - 定义类型
|
||
- `tags`: Vec<String> - 标签
|
||
- `deprecated`: bool - 是否弃用
|
||
- `dependencies`: Vec<UID> - 依赖关系
|
||
- `language_bindings`: HashMap<Language, LanguageBinding> - 多语言绑定
|
||
|
||
**定义类型**:
|
||
- `Type` - 类型定义（struct、enum）
|
||
- `Function` - 函数定义
|
||
- `Constant` - 常量定义
|
||
- `Protocol` - 协议定义
|
||
- `Module` - 模块定义
|
||
|
||
### 4. 定义注册表（DefinitionRegistry）
|
||
|
||
线程安全的定义管理系统。
|
||
|
||
**特性**:
|
||
- 多版本支持（同一定义可以有多个版本）
|
||
- 标签索引（快速按标签查询）
|
||
- 类型索引（快速按类型查询）
|
||
- 依赖追踪（查询定义的所有依赖）
|
||
- 线程安全（使用RwLock）
|
||
|
||
**API**:
|
||
```rust
|
||
// 注册定义
|
||
registry.register(definition)?;
|
||
|
||
// 查询定义
|
||
let def = registry.get(&uid)?;
|
||
|
||
// 按标签查询
|
||
let defs = registry.find_by_tag("cbpp");
|
||
|
||
// 按类型查询
|
||
let types = registry.find_by_type(DefinitionType::Type);
|
||
|
||
// 获取所有版本
|
||
let versions = registry.get_all_versions(&uid);
|
||
```
|
||
|
||
### 5. 多语言支持（Language）
|
||
|
||
支持Rust、Go、Charter三种语言的自动绑定生成。
|
||
|
||
**语言类型**:
|
||
- `Rust` - Rust语言
|
||
- `Go` - Go语言
|
||
- `Charter` - NAC智能合约语言
|
||
|
||
**语言绑定**:
|
||
```rust
|
||
pub struct LanguageBinding {
|
||
pub language: Language,
|
||
pub code: String, // 生成的代码
|
||
pub imports: Vec<String>, // 导入依赖
|
||
pub type_mappings: HashMap<String, String>, // 类型映射
|
||
}
|
||
```
|
||
|
||
**基础类型映射表**:
|
||
|
||
| NAC类型 | Rust | Go | Charter |
|
||
|---------|------|----|----|
|
||
| u8 | u8 | uint8 | u8 |
|
||
| u64 | u64 | uint64 | u64 |
|
||
| u128 | u128 | *big.Int | u128 |
|
||
| u256 | U256 | *big.Int | u256 |
|
||
| address | Address | [20]byte | address |
|
||
| hash | Hash | [32]byte | hash |
|
||
| bytes | Vec<u8> | []byte | bytes |
|
||
| string | String | string | string |
|
||
|
||
---
|
||
|
||
## 已实现模块
|
||
|
||
### 基础原语类型（Primitives）
|
||
|
||
#### Address（地址类型）
|
||
|
||
**UID**: `nac.primitives.Address.v1`
|
||
|
||
20字节地址类型，用于标识账户、合约等实体。
|
||
|
||
**字段**:
|
||
- `bytes: [u8; 20]` - 20字节数组
|
||
|
||
**方法**:
|
||
- `new(bytes: [u8; 20]) -> Self` - 创建新地址
|
||
- `from_slice(slice: &[u8]) -> Result<Self, String>` - 从切片创建
|
||
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
|
||
- `as_bytes(&self) -> &[u8; 20]` - 获取字节数组
|
||
- `to_hex(&self) -> String` - 转换为十六进制字符串
|
||
- `zero() -> Self` - 零地址
|
||
- `is_zero(&self) -> bool` - 检查是否为零地址
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::primitives::Address;
|
||
|
||
// 创建地址
|
||
let addr = Address::new([1u8; 20]);
|
||
|
||
// 从十六进制创建
|
||
let addr = Address::from_hex("0x1234567890abcdef1234567890abcdef12345678")?;
|
||
|
||
// 转换为十六进制
|
||
let hex = addr.to_hex();
|
||
```
|
||
|
||
#### Hash（哈希类型）
|
||
|
||
**UID**: `nac.primitives.Hash.v1`
|
||
|
||
32字节哈希类型，使用SHA-256算法。
|
||
|
||
**字段**:
|
||
- `bytes: [u8; 32]` - 32字节数组
|
||
|
||
**方法**:
|
||
- `new(bytes: [u8; 32]) -> Self` - 创建新哈希
|
||
- `from_slice(slice: &[u8]) -> Result<Self, String>` - 从切片创建
|
||
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
|
||
- `sha256(data: &[u8]) -> Self` - 计算SHA-256哈希
|
||
- `as_bytes(&self) -> &[u8; 32]` - 获取字节数组
|
||
- `to_hex(&self) -> String` - 转换为十六进制字符串
|
||
- `zero() -> Self` - 零哈希
|
||
- `is_zero(&self) -> bool` - 检查是否为零哈希
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::primitives::Hash;
|
||
|
||
// 计算哈希
|
||
let hash = Hash::sha256(b"hello world");
|
||
|
||
// 从十六进制创建
|
||
let hash = Hash::from_hex("a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e")?;
|
||
```
|
||
|
||
#### Timestamp（时间戳类型）
|
||
|
||
**UID**: `nac.primitives.Timestamp.v1`
|
||
|
||
Unix时间戳类型（秒级精度）。
|
||
|
||
**字段**:
|
||
- `secs: u64` - Unix时间戳（秒）
|
||
|
||
**方法**:
|
||
- `now() -> Self` - 当前时间
|
||
- `from_secs(secs: u64) -> Self` - 从秒数创建
|
||
- `as_secs(&self) -> u64` - 获取秒数
|
||
- `is_expired(&self, duration: u64) -> bool` - 检查是否过期
|
||
- `add_secs(&self, secs: u64) -> Self` - 增加秒数
|
||
- `sub_secs(&self, secs: u64) -> Self` - 减少秒数
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::primitives::Timestamp;
|
||
|
||
// 当前时间
|
||
let now = Timestamp::now();
|
||
|
||
// 1小时后
|
||
let future = now.add_secs(3600);
|
||
|
||
// 检查是否过期
|
||
if now.is_expired(3600) {
|
||
println!("已过期");
|
||
}
|
||
```
|
||
|
||
#### Signature（签名类型）
|
||
|
||
**UID**: `nac.primitives.Signature.v1`
|
||
|
||
数字签名类型（可变长度）。
|
||
|
||
**字段**:
|
||
- `bytes: Vec<u8>` - 签名字节
|
||
|
||
**方法**:
|
||
- `new(bytes: Vec<u8>) -> Self` - 创建新签名
|
||
- `from_slice(slice: &[u8]) -> Self` - 从切片创建
|
||
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
|
||
- `as_bytes(&self) -> &[u8]` - 获取字节切片
|
||
- `to_hex(&self) -> String` - 转换为十六进制字符串
|
||
- `is_empty(&self) -> bool` - 检查是否为空
|
||
- `len(&self) -> usize` - 获取长度
|
||
- `empty() -> Self` - 空签名
|
||
|
||
### CBPP（宪政区块生产协议）
|
||
|
||
#### ConstitutionalReceipt（宪法收据）
|
||
|
||
**UID**: `nac.cbpp.ConstitutionalReceipt.v1`
|
||
|
||
宪法收据是CBPP的核心组件，任何试图改变链状态的操作必须先获得CR。
|
||
|
||
**字段**:
|
||
- `receipt_id: Hash` - 收据ID
|
||
- `transaction_hash: Hash` - 交易哈希
|
||
- `constitutional_hash: Hash` - 宪法哈希
|
||
- `execution_result_hash: Hash` - 执行结果哈希
|
||
- `timestamp: Timestamp` - 签发时间戳
|
||
- `validity_window: u64` - 有效期窗口（秒）
|
||
- `issuer_pubkey: Vec<u8>` - 签发者公钥（CEE实例）
|
||
- `signature: Signature` - 签名
|
||
- `validation_results: Vec<ValidationResult>` - 验证结果列表
|
||
|
||
**验证类型**:
|
||
- `KYC` - KYC验证
|
||
- `AML` - 反洗钱
|
||
- `AssetValuation` - 资产估值
|
||
- `ComplianceCheck` - 合规审查
|
||
- `JurisdictionCheck` - 司法辖区验证
|
||
- `ConstitutionalClause` - 宪法条款验证
|
||
- `SmartContractValidation` - 智能合约验证
|
||
- `Other(String)` - 其他
|
||
|
||
**方法**:
|
||
- `new(...) -> Self` - 创建新收据
|
||
- `add_validation_result(&mut self, result: ValidationResult)` - 添加验证结果
|
||
- `sign(&mut self, signature: Signature)` - 签名收据
|
||
- `verify(&self, current_time: Timestamp, valid_constitutional_hash: &Hash) -> bool` - 验证收据
|
||
- `is_expired(&self, current_time: Timestamp) -> bool` - 检查是否过期
|
||
- `get_weight(&self) -> u64` - 获取权重
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::l1_protocol::cbpp::*;
|
||
|
||
// 创建宪法收据
|
||
let mut cr = ConstitutionalReceipt::new(
|
||
tx_hash,
|
||
const_hash,
|
||
exec_hash,
|
||
issuer_key,
|
||
3600, // 1小时有效期
|
||
);
|
||
|
||
// 添加验证结果
|
||
cr.add_validation_result(ValidationResult::new(
|
||
ValidationType::KYC,
|
||
true,
|
||
b"KYC passed",
|
||
));
|
||
|
||
// 签名
|
||
cr.sign(signature);
|
||
|
||
// 验证
|
||
if cr.verify(Timestamp::now(), &const_hash) {
|
||
println!("收据有效");
|
||
}
|
||
```
|
||
|
||
#### FluidBlock（流体区块）
|
||
|
||
**UID**: `nac.cbpp.FluidBlock.v1`
|
||
|
||
流体区块使用三维坐标系统：(Epoch, Round, Branch)，支持DAG结构。
|
||
|
||
**字段**:
|
||
- `coordinates: BlockCoordinates` - 三维坐标
|
||
- `hash: Hash` - 区块哈希
|
||
- `parent_hashes: Vec<Hash>` - 父区块哈希列表
|
||
- `constitutional_hash: Hash` - 宪法哈希
|
||
- `timestamp: Timestamp` - 时间戳
|
||
- `transactions: Vec<TransactionWithReceipt>` - 交易列表
|
||
- `producer_pubkey: Vec<u8>` - 区块生产者公钥
|
||
- `signature: Signature` - 区块签名
|
||
- `size: u64` - 区块大小（字节）
|
||
- `weight: u64` - 区块权重
|
||
|
||
**三维坐标**:
|
||
- `epoch: u64` - 纪元
|
||
- `round: u64` - 轮次
|
||
- `branch: u32` - 分支
|
||
|
||
**方法**:
|
||
- `new(...) -> Self` - 创建新区块
|
||
- `sign(&mut self, signature: Signature)` - 签名区块
|
||
- `verify(&self, current_time: Timestamp, valid_constitutional_hash: &Hash) -> bool` - 验证区块
|
||
- `should_produce_block(last_block_time: Timestamp, pending_tx_count: usize, config: &BlockConfig) -> bool` - 检查是否应该出块
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::l1_protocol::cbpp::*;
|
||
|
||
// 创建区块坐标
|
||
let coords = BlockCoordinates::new(1, 100, 0);
|
||
|
||
// 创建流体区块
|
||
let mut block = FluidBlock::new(
|
||
coords,
|
||
parent_hashes,
|
||
const_hash,
|
||
producer_key,
|
||
transactions,
|
||
);
|
||
|
||
// 签名区块
|
||
block.sign(signature);
|
||
|
||
// 验证区块
|
||
if block.verify(Timestamp::now(), &const_hash) {
|
||
println!("区块有效");
|
||
}
|
||
```
|
||
|
||
#### OpenProductionNetwork（开放生产网络）
|
||
|
||
**UID**: `nac.cbpp.OpenProductionNetwork.v1`
|
||
|
||
OPN管理区块生产者节点，任何满足条件的节点都可以加入。
|
||
|
||
**字段**:
|
||
- `producers: Vec<BlockProducer>` - 所有区块生产者
|
||
- `min_stake: u128` - 最低质押要求
|
||
- `min_reputation: f64` - 最低信誉要求
|
||
|
||
**区块生产者**:
|
||
- `pubkey: Vec<u8>` - 节点公钥
|
||
- `stake: u128` - 质押金额
|
||
- `reputation: f64` - 信誉分数
|
||
- `joined_at: Timestamp` - 加入时间
|
||
- `last_active: Timestamp` - 最后活跃时间
|
||
- `blocks_produced: u64` - 生产的区块数
|
||
- `blocks_validated: u64` - 验证的区块数
|
||
|
||
**方法**:
|
||
- `new(min_stake: u128, min_reputation: f64) -> Self` - 创建OPN
|
||
- `add_producer(&mut self, producer: BlockProducer) -> Result<(), String>` - 添加生产者
|
||
- `remove_producer(&mut self, pubkey: &[u8]) -> Result<(), String>` - 移除生产者
|
||
- `active_producer_count(&self, timeout_secs: u64) -> usize` - 获取活跃生产者数量
|
||
|
||
#### GossipProtocol（Gossip协议）
|
||
|
||
**UID**: `nac.cbpp.GossipProtocol.v1`
|
||
|
||
RVGP负责在网络中传播和验证宪法收据。
|
||
|
||
**消息类型**:
|
||
- `NewReceipt` - 新收据广播
|
||
- `ReceiptValidation` - 收据验证结果
|
||
- `NewBlock` - 区块广播
|
||
- `BlockValidation` - 区块验证结果
|
||
|
||
**方法**:
|
||
- `GossipMessage::new(...) -> Self` - 创建Gossip消息
|
||
- `verify(&self) -> bool` - 验证消息
|
||
- `GossipNode::new(pubkey: Vec<u8>) -> Self` - 创建Gossip节点
|
||
- `add_peer(&mut self, peer_pubkey: Vec<u8>)` - 添加对等节点
|
||
- `has_received(&self, message_hash: &Hash) -> bool` - 检查消息是否已接收
|
||
- `broadcast(&self, message: &GossipMessage) -> Vec<Vec<u8>>` - 广播消息
|
||
|
||
### GNACS（全球资产分类系统）
|
||
|
||
#### GNACSCode（48位编码）
|
||
|
||
**UID**: `nac.gnacs.GNACSCode.v1`
|
||
|
||
48位GNACS编码，为每个资产分配唯一的"数字基因"。
|
||
|
||
**编码结构**:
|
||
```
|
||
┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
|
||
│ 8 bits │ 8 bits │ 8 bits │ 8 bits │ 8 bits │ 8 bits │
|
||
│ Category │ SubCat │ Juris │ Comp │ Risk │ Checksum │
|
||
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
|
||
```
|
||
|
||
**方法**:
|
||
- `new(...) -> Self` - 创建新编码
|
||
- `from_bytes(bytes: [u8; 6]) -> Result<Self, String>` - 从字节数组创建
|
||
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制创建
|
||
- `to_hex(&self) -> String` - 转换为十六进制
|
||
- `category(&self) -> AssetCategory` - 获取资产大类
|
||
- `jurisdiction(&self) -> Jurisdiction` - 获取司法辖区
|
||
- `compliance_level(&self) -> ComplianceLevel` - 获取合规级别
|
||
- `risk_level(&self) -> RiskLevel` - 获取风险等级
|
||
- `verify_checksum(&self) -> bool` - 验证校验和
|
||
- `format_readable(&self) -> String` - 格式化为人类可读字符串
|
||
|
||
**示例**:
|
||
```rust
|
||
use nac_udm::l1_protocol::gnacs::*;
|
||
|
||
// 创建GNACS编码
|
||
let code = GNACSCode::new(
|
||
AssetCategory::Equity,
|
||
1,
|
||
Jurisdiction::US,
|
||
ComplianceLevel::High,
|
||
RiskLevel::Medium,
|
||
);
|
||
|
||
// 转换为十六进制
|
||
let hex = code.to_hex();
|
||
|
||
// 格式化输出
|
||
println!("{}", code); // GNACS-0101-0102-0305
|
||
```
|
||
|
||
#### AssetCategory（资产分类）
|
||
|
||
**UID**: `nac.gnacs.AssetCategory.v1`
|
||
|
||
11种资产大类：
|
||
|
||
- `Equity` (0x01) - 股权资产
|
||
- `Debt` (0x02) - 债权资产
|
||
- `Physical` (0x03) - 实物资产
|
||
- `IntellectualProperty` (0x04) - 知识产权
|
||
- `Derivatives` (0x05) - 金融衍生品
|
||
- `Digital` (0x06) - 数字资产
|
||
- `Commodities` (0x07) - 大宗商品
|
||
- `RealEstate` (0x08) - 房地产
|
||
- `ArtCollectibles` (0x09) - 艺术品与收藏品
|
||
- `CarbonCredits` (0x0A) - 碳信用
|
||
- `Other` (0xFF) - 其他
|
||
|
||
**方法**:
|
||
- `from_u8(value: u8) -> Self` - 从u8转换
|
||
- `name(&self) -> &'static str` - 获取分类名称
|
||
- `description(&self) -> &'static str` - 获取分类描述
|
||
- `all() -> Vec<Self>` - 获取所有分类
|
||
|
||
#### Jurisdiction（司法辖区）
|
||
|
||
**UID**: `nac.gnacs.Jurisdiction.v1`
|
||
|
||
17个司法辖区：
|
||
|
||
- `US` (0x01) - 美国
|
||
- `CN` (0x02) - 中国
|
||
- `EU` (0x03) - 欧盟
|
||
- `UK` (0x04) - 英国
|
||
- `JP` (0x05) - 日本
|
||
- `SG` (0x06) - 新加坡
|
||
- `HK` (0x07) - 香港
|
||
- `CH` (0x08) - 瑞士
|
||
- `AE` (0x09) - 阿联酋
|
||
- `KY` (0x0A) - 开曼群岛
|
||
- `VG` (0x0B) - 英属维尔京群岛
|
||
- `LU` (0x0C) - 卢森堡
|
||
- `AU` (0x0D) - 澳大利亚
|
||
- `CA` (0x0E) - 加拿大
|
||
- `KR` (0x0F) - 韩国
|
||
- `Global` (0xFE) - 全球/跨境
|
||
- `Other` (0xFF) - 其他
|
||
|
||
**方法**:
|
||
- `from_u8(value: u8) -> Self` - 从u8转换
|
||
- `iso_code(&self) -> &'static str` - 获取ISO代码
|
||
- `full_name(&self) -> &'static str` - 获取全称
|
||
- `all() -> Vec<Self>` - 获取所有司法辖区
|
||
|
||
#### ComplianceLevel（合规级别）
|
||
|
||
**UID**: `nac.gnacs.ComplianceLevel.v1`
|
||
|
||
6个合规等级：
|
||
|
||
- `VeryHigh` (0x01) - 极高（100分）
|
||
- `High` (0x02) - 高（80分）
|
||
- `Medium` (0x03) - 中（60分）
|
||
- `Low` (0x04) - 低（40分）
|
||
- `VeryLow` (0x05) - 极低（20分）
|
||
- `Unknown` (0xFF) - 未知（0分）
|
||
|
||
**方法**:
|
||
- `from_u8(value: u8) -> Self` - 从u8转换
|
||
- `name(&self) -> &'static str` - 获取级别名称
|
||
- `description(&self) -> &'static str` - 获取级别描述
|
||
- `score(&self) -> u8` - 获取数值分数（0-100）
|
||
|
||
#### RiskLevel（风险等级）
|
||
|
||
**UID**: `nac.gnacs.RiskLevel.v1`
|
||
|
||
6个风险等级：
|
||
|
||
- `VeryLow` (0x01) - 极低（20分）
|
||
- `Low` (0x02) - 低（40分）
|
||
- `Medium` (0x03) - 中（60分）
|
||
- `High` (0x04) - 高（80分）
|
||
- `VeryHigh` (0x05) - 极高（100分）
|
||
- `Unknown` (0xFF) - 未知（0分）
|
||
|
||
**方法**:
|
||
- `from_u8(value: u8) -> Self` - 从u8转换
|
||
- `name(&self) -> &'static str` - 获取级别名称
|
||
- `description(&self) -> &'static str` - 获取级别描述
|
||
- `score(&self) -> u8` - 获取数值分数（0-100）
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 环境准备
|
||
|
||
**系统要求**:
|
||
- Rust 1.70+
|
||
- Cargo
|
||
- Git
|
||
|
||
**安装Rust**:
|
||
```bash
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
```
|
||
|
||
### 编译项目
|
||
|
||
```bash
|
||
# 克隆项目
|
||
cd /home/ubuntu/nac-workspace/nac-udm
|
||
|
||
# 检查编译
|
||
cargo check
|
||
|
||
# 编译
|
||
cargo build
|
||
|
||
# 编译发布版本
|
||
cargo build --release
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行特定模块的测试
|
||
cargo test primitives
|
||
|
||
# 运行特定测试
|
||
cargo test test_address_creation
|
||
|
||
# 显示测试输出
|
||
cargo test -- --nocapture
|
||
```
|
||
|
||
### 添加新定义
|
||
|
||
#### 步骤1: 创建定义文件
|
||
|
||
在相应的层级目录下创建新的定义文件，例如：
|
||
|
||
```rust
|
||
// src/l1_protocol/acc/acc20.rs
|
||
|
||
use crate::primitives::{Address, Hash};
|
||
use serde::{Deserialize, Serialize};
|
||
|
||
/// ACC-20 可替代代币标准
|
||
///
|
||
/// UID: nac.acc.ACC20.v1
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct ACC20Token {
|
||
/// 代币名称
|
||
pub name: String,
|
||
|
||
/// 代币符号
|
||
pub symbol: String,
|
||
|
||
/// 小数位数
|
||
pub decimals: u8,
|
||
|
||
/// 总供应量
|
||
pub total_supply: u128,
|
||
|
||
/// 合约地址
|
||
pub contract_address: Address,
|
||
}
|
||
|
||
impl ACC20Token {
|
||
/// 创建新的ACC-20代币
|
||
pub fn new(name: String, symbol: String, decimals: u8, total_supply: u128) -> Self {
|
||
Self {
|
||
name,
|
||
symbol,
|
||
decimals,
|
||
total_supply,
|
||
contract_address: Address::zero(),
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 步骤2: 更新模块导出
|
||
|
||
在`mod.rs`中导出新定义：
|
||
|
||
```rust
|
||
// src/l1_protocol/acc/mod.rs
|
||
|
||
pub mod acc20;
|
||
|
||
pub use acc20::*;
|
||
```
|
||
|
||
#### 步骤3: 添加测试
|
||
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
#[test]
|
||
fn test_acc20_creation() {
|
||
let token = ACC20Token::new(
|
||
"Test Token".to_string(),
|
||
"TEST".to_string(),
|
||
18,
|
||
1_000_000_000,
|
||
);
|
||
|
||
assert_eq!(token.name, "Test Token");
|
||
assert_eq!(token.symbol, "TEST");
|
||
assert_eq!(token.decimals, 18);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 步骤4: 注册到UDM
|
||
|
||
```rust
|
||
use nac_udm::registry::*;
|
||
|
||
// 创建定义
|
||
let definition = Definition::builder()
|
||
.uid(UID::parse("nac.acc.ACC20.v1")?)
|
||
.version(Version::new(1, 0, 0))
|
||
.name("ACC20Token")
|
||
.description("ACC-20 fungible token standard")
|
||
.definition_type(DefinitionType::Type)
|
||
.add_tag("acc")
|
||
.add_tag("token")
|
||
.build();
|
||
|
||
// 注册到注册表
|
||
let registry = DefinitionRegistry::new();
|
||
registry.register(definition)?;
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
**命名规范**:
|
||
- 类型名称：PascalCase（如`ConstitutionalReceipt`）
|
||
- 函数名称：snake_case（如`add_validation_result`）
|
||
- 常量名称：SCREAMING_SNAKE_CASE（如`MAX_BLOCK_SIZE`）
|
||
- 模块名称：snake_case（如`constitutional_receipt`）
|
||
|
||
**文档规范**:
|
||
- 所有公开类型和函数必须有文档注释
|
||
- 使用`///!`注释模块
|
||
- 使用`///`注释类型和函数
|
||
- 包含示例代码
|
||
|
||
**测试规范**:
|
||
- 每个公开函数至少一个测试
|
||
- 测试函数命名：`test_<function_name>_<scenario>`
|
||
- 使用`assert_eq!`、`assert!`等宏进行断言
|
||
|
||
---
|
||
|
||
## 测试指南
|
||
|
||
### 单元测试
|
||
|
||
每个模块都应该包含单元测试：
|
||
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
#[test]
|
||
fn test_example() {
|
||
// 测试代码
|
||
assert_eq!(1 + 1, 2);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 集成测试
|
||
|
||
在`tests/`目录下创建集成测试：
|
||
|
||
```rust
|
||
// tests/integration_test.rs
|
||
|
||
use nac_udm::prelude::*;
|
||
|
||
#[test]
|
||
fn test_full_workflow() {
|
||
// 完整的工作流测试
|
||
}
|
||
```
|
||
|
||
### 测试覆盖率
|
||
|
||
```bash
|
||
# 安装tarpaulin
|
||
cargo install cargo-tarpaulin
|
||
|
||
# 运行覆盖率测试
|
||
cargo tarpaulin --out Html
|
||
```
|
||
|
||
---
|
||
|
||
## 多语言支持
|
||
|
||
### Rust绑定
|
||
|
||
Rust是UDM的原生实现语言，直接使用即可：
|
||
|
||
```rust
|
||
use nac_udm::prelude::*;
|
||
|
||
let addr = Address::new([1u8; 20]);
|
||
```
|
||
|
||
### Go绑定（待实现）
|
||
|
||
计划使用代码生成工具自动生成Go绑定：
|
||
|
||
```go
|
||
package nac
|
||
|
||
type Address [20]byte
|
||
|
||
func NewAddress(bytes [20]byte) Address {
|
||
return Address(bytes)
|
||
}
|
||
```
|
||
|
||
### Charter绑定（待实现）
|
||
|
||
计划为Charter智能合约语言生成绑定：
|
||
|
||
```charter
|
||
struct Address {
|
||
bytes: [u8; 20]
|
||
}
|
||
|
||
impl Address {
|
||
fn new(bytes: [u8; 20]) -> Self {
|
||
Self { bytes }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 路线图
|
||
|
||
### 已完成（v0.1.0）
|
||
|
||
- ✅ 核心注册表系统（UID、Version、Definition、Registry、Language）
|
||
- ✅ 基础原语类型（Address、Hash、Timestamp、Signature）
|
||
- ✅ CBPP完整模块（ConstitutionalReceipt、FluidBlock、OPN、Gossip）
|
||
- ✅ GNACS完整模块（GNACSCode、AssetCategory、Jurisdiction、ComplianceLevel、RiskLevel）
|
||
|
||
### 进行中（v0.2.0）
|
||
|
||
- ⏳ ACC协议族（13个协议）
|
||
- ACC-20（可替代代币）
|
||
- ACC-721（不可替代代币）
|
||
- ACC-1155（多代币标准）
|
||
- ACC-RWA（RWA资产）
|
||
- ACC-Compliance（合规）
|
||
- ACC-Valuation（估值）
|
||
- ACC-Custody（托管）
|
||
- ACC-Collateral（抵押）
|
||
- ACC-Redemption（赎回）
|
||
- ACC-Insurance（保险）
|
||
- ACC-Governance（治理）
|
||
- ACC-XTZH（稳定币）
|
||
- ACC-Reserve（储备）
|
||
|
||
- ⏳ NVM 2.0虚拟机
|
||
- 225个基础操作码
|
||
- 125个RWA专属指令
|
||
- Gas计量模型
|
||
|
||
### 计划中（v0.3.0）
|
||
|
||
- ⏳ L2宪法治理层
|
||
- 宪法条款库
|
||
- 网络规则定义
|
||
- CCRN授权管理
|
||
- 惩罚条款
|
||
|
||
- ⏳ L0 CSNP网络层
|
||
- GIDS（全域身份目录服务）
|
||
- MA-RCM（多链自适应连接管理器）
|
||
- AA-PE（资产感知传播引擎）
|
||
- FTAN（碎片化交易聚合网络）
|
||
- UCA（统一跨链审计器）
|
||
|
||
### 未来（v1.0.0）
|
||
|
||
- ⏳ 多语言绑定生成
|
||
- Go绑定生成器
|
||
- Charter绑定生成器
|
||
- 类型映射优化
|
||
|
||
- ⏳ 工具链完善
|
||
- 定义验证器
|
||
- 定义迁移工具
|
||
- 代码生成器
|
||
|
||
- ⏳ 文档完善
|
||
- API规范文档
|
||
- 使用示例
|
||
- 最佳实践
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 参考资料
|
||
|
||
- NAC原生公链完全去以太坊化架构设计
|
||
- CSNP V2.0技术白皮书
|
||
- 宪政区块生产协议（CBPP）技术白皮书
|
||
- 资产加密DNA管理系统技术白皮书
|
||
|
||
### 贡献指南
|
||
|
||
欢迎贡献代码、文档和测试！请遵循以下流程：
|
||
|
||
1. Fork项目
|
||
2. 创建特性分支（`git checkout -b feature/amazing-feature`）
|
||
3. 提交更改（`git commit -m 'Add amazing feature'`）
|
||
4. 推送到分支（`git push origin feature/amazing feature`）
|
||
5. 创建Pull Request
|
||
|
||
### 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
**文档版本**: v0.1.0
|
||
**最后更新**: 2025-02-07
|
||
**维护者**: NAC公链开发小组
|