# 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资产通证化打造的高性能原生区块链基础设施*