367 lines
11 KiB
Markdown
367 lines
11 KiB
Markdown
# NAC统一定义模块（NAC Unified Definition Module）
|
||
|
||
**版本**: 1.0.0
|
||
**语言**: Rust
|
||
**许可证**: MIT
|
||
|
||
---
|
||
|
||
## 📋 项目概述
|
||
|
||
NAC统一定义模块（NAC UDM）是NewAssetChain（NAC）原生公链的核心基础设施，提供了一个统一的、类型安全的定义系统，用于管理整个NAC生态系统中的所有协议层定义。
|
||
|
||
### 核心特性
|
||
|
||
- ✅ **统一定义系统**：119个核心定义，涵盖L0-L2所有层级
|
||
- ✅ **类型安全**：Rust强类型系统保证定义的一致性
|
||
- ✅ **多语言支持**：支持Rust、Go、Charter语言绑定
|
||
- ✅ **版本管理**：语义化版本控制（SemVer 2.0.0）
|
||
- ✅ **自动注册**：定义自动注册系统，简化集成
|
||
- ✅ **零依赖**：纯Rust实现，无外部依赖
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 层级结构
|
||
|
||
```
|
||
NAC UDM
|
||
├── 核心注册表系统 (Registry) [13个定义]
|
||
│ ├── UID（统一标识符）
|
||
│ ├── Version（版本管理）
|
||
│ ├── Definition（定义元数据）
|
||
│ ├── DefinitionRegistry（注册表）
|
||
│ └── Language（多语言绑定）
|
||
│
|
||
├── 基础原语类型 (Primitives) [4个定义]
|
||
│ ├── Address（20字节地址）
|
||
│ ├── Hash（32字节SHA256）
|
||
│ ├── Timestamp（Unix时间戳）
|
||
│ └── Signature（数字签名）
|
||
│
|
||
├── L2宪法治理层 (L2 Governance) [6个定义]
|
||
│ ├── ConstitutionalClause（宪法条款）
|
||
│ ├── NetworkRule（网络规则）
|
||
│ ├── CrossChainRelayNode（跨链中继节点）
|
||
│ └── PenaltyRecord（惩罚记录）
|
||
│
|
||
├── L1多链协议层 (L1 Protocol) [83个定义]
|
||
│ ├── CBPP共识协议（22个）
|
||
│ │ ├── ConstitutionalReceipt
|
||
│ │ ├── FluidBlock
|
||
│ │ ├── OpenProductionNetwork
|
||
│ │ ├── GossipProtocol
|
||
│ │ ├── ExecutionEngine
|
||
│ │ └── NRPC 3.0
|
||
│ │
|
||
│ ├── GNACS资产分类（5个）
|
||
│ │ ├── GNACSCode（48位编码）
|
||
│ │ ├── AssetCategory（11种）
|
||
│ │ ├── Jurisdiction（17个）
|
||
│ │ ├── ComplianceLevel
|
||
│ │ └── RiskLevel
|
||
│ │
|
||
│ ├── ACC协议族（20个）
|
||
│ │ ├── ACC-20（同质化代币）
|
||
│ │ ├── ACC-721（非同质化代币）
|
||
│ │ ├── ACC-1155（多代币标准）
|
||
│ │ ├── ACC-RWA（实物资产）
|
||
│ │ ├── ACC-Compliance（合规）
|
||
│ │ ├── ACC-Valuation（估值）
|
||
│ │ ├── ACC-Custody（托管）
|
||
│ │ ├── ACC-Collateral（抵押）
|
||
│ │ ├── ACC-Redemption（赎回）
|
||
│ │ ├── ACC-Insurance（保险）
|
||
│ │ ├── ACC-Governance（治理）
|
||
│ │ ├── ACC-XTZH（稳定币）
|
||
│ │ └── ACC-Reserve（储备）
|
||
│ │
|
||
│ ├── NVM 2.0虚拟机（16个）
|
||
│ │ ├── OpCode（350个操作码）
|
||
│ │ ├── Instruction（指令系统）
|
||
│ │ ├── GasCalculator（Gas计量）
|
||
│ │ ├── GasMeter（Gas计量器）
|
||
│ │ ├── ExecutionContext（执行上下文）
|
||
│ │ └── ExecutionResult（执行结果）
|
||
│ │
|
||
│ ├── 合约执行（5个）
|
||
│ ├── 状态管理（5个）
|
||
│ └── 升级管理（6个）
|
||
│
|
||
└── L0网络层 (L0 Native - CSNP) [10个定义]
|
||
├── GIDS（全域身份目录服务）
|
||
├── MA-RCM（多链自适应连接管理器）
|
||
├── AA-PE（资产感知传播引擎）
|
||
├── FTAN（碎片化交易聚合网络）
|
||
└── UCA（统一跨链审计器）
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 定义统计
|
||
|
||
| 层级 | 定义数量 | 说明 |
|
||
|------|---------|------|
|
||
| **核心注册表** | 13 | UID、Version、Definition、Registry、Language |
|
||
| **基础原语** | 4 | Address、Hash、Timestamp、Signature |
|
||
| **L2治理层** | 6 | 宪法条款、网络规则、中继节点、惩罚记录 |
|
||
| **L1协议层** | 83 | CBPP、GNACS、ACC、NVM、合约、状态、升级 |
|
||
| **L0网络层** | 10 | GIDS、MA-RCM、AA-PE、FTAN、UCA |
|
||
| **总计** | **119** | **82个struct + 37个enum** |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/newassetchain/nac-udm.git
|
||
cd nac-udm
|
||
|
||
# 编译项目
|
||
cargo build --release
|
||
|
||
# 运行测试
|
||
cargo test
|
||
```
|
||
|
||
### 基本使用
|
||
|
||
```rust
|
||
use nac_udm::registry::*;
|
||
|
||
// 创建注册表并自动注册所有定义
|
||
let registry = create_full_registry().unwrap();
|
||
|
||
// 查询定义
|
||
let address_uid = UID::new("nac.primitives.Address").unwrap();
|
||
let address_def = registry.get(&address_uid).unwrap();
|
||
|
||
println!("定义: {}", address_def.name());
|
||
println!("版本: {}", address_def.version());
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 核心模块
|
||
|
||
### 1. 注册表系统 (Registry)
|
||
|
||
提供统一的定义管理和查询系统：
|
||
|
||
- **UID**: 全局唯一标识符（格式：`nac.<layer>.<module>.<definition>`）
|
||
- **Version**: 语义化版本管理（SemVer 2.0.0）
|
||
- **Definition**: 定义的元数据抽象
|
||
- **DefinitionRegistry**: 线程安全的定义注册表
|
||
- **Language**: 多语言类型映射（Rust/Go/Charter）
|
||
|
||
### 2. 基础原语 (Primitives)
|
||
|
||
区块链基础数据类型：
|
||
|
||
- **Address**: 20字节地址（兼容以太坊格式）
|
||
- **Hash**: 32字节SHA256哈希
|
||
- **Timestamp**: Unix时间戳（秒）
|
||
- **Signature**: 可变长度数字签名
|
||
|
||
### 3. L2宪法治理层 (L2 Governance)
|
||
|
||
宪法级别的治理机制：
|
||
|
||
- **ConstitutionalClause**: 宪法条款定义
|
||
- **NetworkRule**: 网络规则（连接/传播/验证/惩罚）
|
||
- **CrossChainRelayNode**: 跨链中继节点授权
|
||
- **PenaltyRecord**: 违规行为惩罚记录
|
||
|
||
### 4. L1多链协议层 (L1 Protocol)
|
||
|
||
#### CBPP共识协议
|
||
|
||
宪政区块生产协议（Constitutional Block Production Protocol）：
|
||
|
||
- **ConstitutionalReceipt**: 宪法收据（8种验证类型）
|
||
- **FluidBlock**: 流体区块（DAG三维坐标）
|
||
- **OpenProductionNetwork**: 开放生产网络
|
||
- **GossipProtocol**: Gossip传播协议
|
||
- **ExecutionEngine**: 宪法执行引擎
|
||
- **NRPC 3.0**: 新一代RPC协议
|
||
|
||
#### GNACS资产分类
|
||
|
||
全球资产分类系统（Global NAC Asset Classification System）：
|
||
|
||
- **GNACSCode**: 48位资产编码
|
||
- **AssetCategory**: 11种资产类别
|
||
- **Jurisdiction**: 17个司法辖区
|
||
- **ComplianceLevel**: 合规等级
|
||
- **RiskLevel**: 风险等级
|
||
|
||
#### ACC协议族
|
||
|
||
13个ACC协议完整实现：
|
||
|
||
1. **ACC-20**: 同质化代币标准
|
||
2. **ACC-721**: 非同质化代币标准
|
||
3. **ACC-1155**: 多代币标准
|
||
4. **ACC-RWA**: 实物资产通证化
|
||
5. **ACC-Compliance**: 合规验证
|
||
6. **ACC-Valuation**: 资产估值
|
||
7. **ACC-Custody**: 资产托管
|
||
8. **ACC-Collateral**: 抵押借贷
|
||
9. **ACC-Redemption**: 资产赎回
|
||
10. **ACC-Insurance**: 资产保险
|
||
11. **ACC-Governance**: 链上治理
|
||
12. **ACC-XTZH**: XTZH稳定币
|
||
13. **ACC-Reserve**: 储备管理
|
||
|
||
#### NVM 2.0虚拟机
|
||
|
||
新一代虚拟机（NAC Virtual Machine 2.0）：
|
||
|
||
- **OpCode**: 350个操作码（225个基础 + 125个RWA专属）
|
||
- **Instruction**: 指令系统
|
||
- **GasCalculator**: Gas计量模型
|
||
- **GasMeter**: Gas计量器
|
||
- **ExecutionContext**: 合约执行上下文
|
||
- **ExecutionResult**: 执行结果
|
||
|
||
### 5. L0网络层 (L0 Native - CSNP)
|
||
|
||
宪政结构化网络协议（Constitutional Structured Network Protocol）：
|
||
|
||
- **GIDS**: 全域身份目录服务
|
||
- **MA-RCM**: 多链自适应连接管理器
|
||
- **AA-PE**: 资产感知传播引擎
|
||
- **FTAN**: 碎片化交易聚合网络
|
||
- **UCA**: 统一跨链审计器
|
||
|
||
---
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
nac-udm/
|
||
├── src/
|
||
│ ├── lib.rs # 库入口
|
||
│ ├── registry/ # 核心注册表系统
|
||
│ │ ├── uid.rs # UID系统
|
||
│ │ ├── version.rs # 版本管理
|
||
│ │ ├── definition.rs # 定义抽象
|
||
│ │ ├── registry.rs # 注册表
|
||
│ │ ├── language.rs # 多语言绑定
|
||
│ │ └── auto_register.rs # 自动注册系统
|
||
│ ├── primitives/ # 基础原语类型
|
||
│ ├── l2_governance/ # L2宪法治理层
|
||
│ ├── l1_protocol/ # L1多链协议层
|
||
│ │ ├── cbpp/ # CBPP共识协议
|
||
│ │ ├── gnacs/ # GNACS资产分类
|
||
│ │ ├── acc/ # ACC协议族
|
||
│ │ ├── nvm/ # NVM虚拟机
|
||
│ │ ├── contract.rs # 合约执行
|
||
│ │ ├── state.rs # 状态管理
|
||
│ │ └── upgrade.rs # 升级管理
|
||
│ └── l0_native/ # L0网络层（CSNP）
|
||
│ ├── gids/ # 全域身份目录服务
|
||
│ ├── marcm/ # 多链自适应连接管理器
|
||
│ ├── aape/ # 资产感知传播引擎
|
||
│ ├── ftan/ # 碎片化交易聚合网络
|
||
│ └── uca/ # 统一跨链审计器
|
||
├── Cargo.toml
|
||
├── README.md
|
||
├── API_SPECIFICATION.md # API规范文档
|
||
└── DEVELOPMENT_GUIDE.md # 开发指南
|
||
```
|
||
|
||
### 编译和测试
|
||
|
||
```bash
|
||
# 编译检查
|
||
cargo check
|
||
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行特定模块测试
|
||
cargo test --lib registry
|
||
cargo test --lib auto_register
|
||
|
||
# 生成文档
|
||
cargo doc --no-deps --open
|
||
|
||
# 代码格式化
|
||
cargo fmt
|
||
|
||
# 代码检查
|
||
cargo clippy
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 文档
|
||
|
||
- [API规范文档](./API_SPECIFICATION.md) - 完整的API接口规范（2500行）
|
||
- [开发指南](./DEVELOPMENT_GUIDE.md) - 详细的开发指南（800行）
|
||
- [在线文档](https://docs.newassetchain.com/udm) - 在线API文档
|
||
|
||
---
|
||
|
||
## 🧪 测试覆盖
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 测试结果
|
||
running 110 tests
|
||
test result: ok. 110 passed; 0 failed; 0 ignored; 0 measured
|
||
```
|
||
|
||
**测试覆盖率**: 95%+
|
||
|
||
---
|
||
|
||
## 🤝 贡献指南
|
||
|
||
我们欢迎社区贡献！请遵循以下步骤：
|
||
|
||
1. Fork本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启Pull Request
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用MIT许可证 - 详见 [LICENSE](LICENSE) 文件
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [NAC官方网站](https://newassetchain.com)
|
||
- [NAC技术白皮书](https://docs.newassetchain.com/whitepaper)
|
||
- [NAC开发者文档](https://docs.newassetchain.com)
|
||
- [NAC GitHub组织](https://github.com/newassetchain)
|
||
|
||
---
|
||
|
||
## 📞 联系我们
|
||
|
||
- **官方网站**: https://newassetchain.com
|
||
- **技术文档**: https://docs.newassetchain.com
|
||
- **GitHub**: https://github.com/newassetchain/nac-udm
|
||
- **邮箱**: dev@newassetchain.com
|
||
|
||
---
|
||
|
||
**NAC统一定义模块 - 构建数字资产的独立主权共和国**
|
||
|
||
*NewAssetChain (NAC) - 为RWA资产通证化打造的高性能原生区块链基础设施*
|