# NAC (New Asset Chain) 完整开发包

**版本**: v1.0.0  
**日期**: 2026-02-07  
**描述**: NAC区块链完整开发包 - 包含所有核心组件的干净源代码

---

## 📦 包含组件

### 1. **NAC_UDM** - NAC统一定义模块
**路径**: `nac-udm/`  
**语言**: Rust  
**代码量**: 15,739行（79个文件）

NAC区块链的核心类型定义和协议实现，包含完整的三层架构：

#### L0 原生层（Native Layer）- 95行
- `gids/` - 全局身份系统 (Global Identity System)
- `ma_rcm/` - 多资产注册管理 (Multi-Asset Registry & Compliance Manager)
- `aa_pe/` - 资产权限引擎 (Asset Authorization & Permission Engine)
- `ftan/` - 碎片化资产网络 (Fragmented Token Asset Network)
- `uca/` - 统一宪政账户 (Unified Constitutional Account)

#### L1 协议层（Protocol Layer）- 11,596行
- **ACC协议族** (745行)
  - `acc20.rs` - ACC-20基础资产协议
  - `acc721.rs` - ACC-721 NFT协议
  - `acc1155.rs` - ACC-1155多资产协议
  - `acc_rwa.rs` - RWA资产协议
  - `acc_xtzh.rs` - XTZH稳定币协议
  - `acc_collateral.rs` - 抵押品管理
  - `acc_compliance.rs` - 合规管理
  - `acc_custody.rs` - 托管服务
  - `acc_governance.rs` - 治理协议
  - `acc_insurance.rs` - 保险协议
  - `acc_redemption.rs` - 赎回协议
  - `acc_reserve.rs` - 储备金管理
  - `acc_valuation.rs` - 估值协议

- **CBPP共识** (宪政区块生产协议)
  - `constitutional_receipt.rs` - 宪法收据（核心！）
  - `fluid_block.rs` - 流体区块模型
  - `open_production_network.rs` - 开放生产网络
  - `gossip_protocol.rs` - 收据验证Gossip协议
  - `execution_engine.rs` - 执行引擎
  - `nrpc.rs` - NAC Lens协议

- **GNACS编码系统**
  - `category.rs` - 资产分类
  - `code.rs` - GNACS编码
  - `compliance.rs` - 合规等级
  - `jurisdiction.rs` - 司法辖区
  - `risk.rs` - 风险等级

- **NVM虚拟机接口**
  - `opcode.rs` - RWA专用操作码
  - `instruction.rs` - 指令集
  - `executor.rs` - 执行器
  - `gas.rs` - Gas模型

- **碎片化协议**
  - `amm.rs` - 自动做市商
  - `cross_chain.rs` - 跨链桥接
  - `factory.rs` - 工厂合约
  - `layered.rs` - 分层碎片化

- **分片系统**
  - `cross_shard_transaction.rs` - 跨分片交易
  - `shard_governance.rs` - 分片治理
  - `parallel_chain_manager.rs` - 并行链管理
  - `shard_load_balancer.rs` - 分片负载均衡

#### L2 治理层（Governance Layer - 宪法层）- 73行
- `constitutional/` - 宪法框架
- `clauses/` - 条款系统
- `rules/` - 规则引擎
- `ccrn/` - 宪政共识规则网络
- `penalties/` - 惩罚机制

#### L2 网络层（Network Layer）- 730行
- **CSNP协议** (宪政结构化网络协议)
  - `cross_chain_sync.rs` - 跨链同步

**编译**:
```bash
cd nac-udm
cargo build --release
cargo test
```

---

### 2. **Charter编译器** - Charter语言编译器
**路径**: `charter-compiler/`  
**语言**: Rust  
**代码量**: 2,647行

Charter是NAC的原生智能合约语言，专为RWA资产设计。

**组件**:
- `lexer.rs` (369行) - 词法分析器
- `parser.rs` (1,101行) - 语法分析器
- `semantic.rs` (470行) - 语义分析器
- `codegen.rs` (488行) - 代码生成器
- `optimizer.rs` (25行) - 优化器
- `charter.pest` - PEG语法定义

**编译**:
```bash
cd charter-compiler
cargo build --release
cargo test
```

**使用**:
```bash
./target/release/charter-compiler examples/shanghai_office.charter
```

---

### 3. **NVM_v2** - NAC虚拟机
**路径**: `nvm_v2/`  
**语言**: Rust  
**描述**: NAC原生虚拟机，支持RWA专用操作码

**核心模块**:
- L0层实现
- L1层实现
- 执行引擎
- 状态管理
- Gas计量

**编译**:
```bash
cd nvm_v2
cargo build --release
cargo test
```

---

## 📚 文档

**路径**: `docs/`

- `CHARTER_LANGUAGE_SPECIFICATION.md` - Charter语言完整规范
  - 语法定义
  - 类型系统
  - 标准库设计（asset/sovereignty/acc/defi/governance/utils）
  - RWA专用特性

---

## 💡 示例

**路径**: `examples/`

- `shanghai_office.charter` - 上海办公室股权资产示例

---

## 🏗️ 核心设计哲学

### "宪法即共识" - CBPP的核心理念

> "宪法治下，节点产生区块，参与即是共识，交易扩张区块的大小和高度。"

### 宪法收据（Constitutional Receipt）

任何试图改变链状态的操作必须先获得宪法收据（CR）：

```rust
pub struct ConstitutionalReceipt {
    pub receipt_id: Hash,
    pub transaction_hash: Hash,
    pub constitutional_hash: Hash,        // 宪法哈希
    pub execution_result_hash: Hash,      // AI校验结果
    pub timestamp: Timestamp,
    pub validity_window: u64,
    pub issuer_pubkey: Vec<u8>,           // CEE实例签发
    pub signature: Signature,
    pub validation_results: Vec<ValidationResult>,
}
```

**验证类型**:
- KYC验证
- AML反洗钱
- 资产估值
- 合规审查
- 司法辖区验证
- 宪法条款验证
- 智能合约验证

---

## 📐 NAC类型系统规范

NAC作为原生公链，拥有独立的类型系统，与以太坊有本质区别：

| 类型 | NAC | 以太坊 | 区别 |
|------|-----|--------|------|
| **Address** | 32字节 (256位) | 20字节 (160位) | ✅ **不同** |
| **Hash** | 48字节 (SHA3-384) | 32字节 (Keccak256) | ✅ **不同** |
| **编码** | 支持8组二进制字符串转换 | 仅十六进制 | ✅ **不同** |

📖 **详细文档**:
- [NAC类型系统完整规范](./docs/NAC_TYPE_SYSTEM.md)
- [类型系统快速参考](./docs/TYPE_SYSTEM_QUICK_REF.md)

⚠️ **重要**: 开发NAC应用时，请严格遵循NAC类型系统规范，不要假设与以太坊的兼容性。

---

## 🔑 核心特性

### NAC不是任何公链的继承或衍生

NAC是完全自主开发的RWA原生公链，包括：

- ❌ **不是** 以太坊/ERC的衍生
- ❌ **不使用** EVM虚拟机
- ❌ **不使用** Solidity语言
- ❌ **不使用** PoW/PoS/DPoS/BFT共识
- ❌ **不使用** JSON-RPC协议

- ✅ **使用** NVM虚拟机（NAC Virtual Machine）
- ✅ **使用** Charter语言（NAC原生智能合约语言）
- ✅ **使用** CBPP共识（Constitutional Block Production Protocol）
- ✅ **使用** NAC Lens协议（NAC RPC Protocol 3.0）
- ✅ **使用** CSNP网络（Constitutional State Network Protocol）
- ✅ **使用** ACC-20协议（Asset Certificate Contract）
- ✅ **使用** GNACS编码（Global NAC Asset Classification System）
- ✅ **使用** SHA3-384哈希（不是SHA256/Keccak256）

### 代币体系

- **XIC** - 治理代币（Governance Token）
- **XTZH** - 资产代币/稳定币（Asset Token/Stablecoin）

---

## 🛠️ 开发环境要求

### 必需工具

- **Rust** 1.70+ (推荐使用rustup安装)
- **Cargo** (Rust包管理器)
- **Git** (版本控制)

### 安装Rust

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

### 验证安装

```bash
rustc --version
cargo --version
```

---

## 📖 快速开始

### 1. 编译所有组件

```bash
# 编译NAC_UDM
cd nac-udm
cargo build --release
cargo test

# 编译Charter编译器
cd ../charter-compiler
cargo build --release
cargo test

# 编译NVM_v2
cd ../nvm_v2
cargo build --release
cargo test
```

### 2. 运行Charter示例

```bash
cd charter-compiler
cargo run --release -- ../examples/shanghai_office.charter
```

### 3. 运行测试

```bash
# 运行所有测试
cd nac-udm && cargo test
cd ../charter-compiler && cargo test
cd ../nvm_v2 && cargo test
```

---

## 📁 完整目录结构

**总模块数**: 48个  
**最后更新**: 2026-02-17

```
NAC_Clean_Dev/
├── README.md
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【核心基础设施】(6个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-udm/                           # NAC统一定义模块
├── nvm_v2/                            # NAC虚拟机 V2.0
├── charter-compiler/                  # Charter语言编译器
├── charter-std/                       # Charter标准库（英文）
├── charter-std-zh/                    # Charter标准库（中文）
├── cnnl-compiler/                     # CNNL编译器（宪法自然语言）
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【L0层 - 基础设施层】(2个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-cbpp-l0/                       # CBPP共识协议 L0层
├── nac-csnp-l0/                       # CSNP网络协议 L0层
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【L1层 - 协议层】(6个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-cbpp-l1/                       # CBPP共识协议 L1层
├── nac-csnp-l1/                       # CSNP网络协议 L1层
├── nac-acc-1410/                      # ACC-1410协议实现
├── nac-ftan/                          # FTAN（碎片化交易聚合网络）
├── nac-uca/                           # UCA（统一宪法架构）
├── nac-ma-rcm/                        # MA-RCM（多资产风险合规管理）
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【治理与合规】(5个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-constitution-clauses/          # 宪法条款系统
├── nac-constitution-state/            # 宪法状态管理
├── nac-constitution-macros/           # 宪法宏系统
├── cargo-constitution/                # Cargo宪法扩展
├── nac-cee/                           # CEE（宪法执行引擎）
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【AI系统】(1个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── xtzh-ai/                           # XTZH AI估值与合规系统
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【跨链桥接】(3个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-bridge-contracts/              # 跨链桥合约
├── nac-bridge-ethereum/               # 以太坊桥接
├── nac-cross-chain-bridge/            # 通用跨链桥
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【RPC与API】(3个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-lens/                          # NAC Lens 1.0
├── nac-lens/                         # NAC Lens
├── nac-api-server/                    # API服务器
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【钱包系统】(4个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-wallet-core/                   # 钱包核心库
├── nac-wallet-cli/                    # 钱包命令行工具
├── nac-vision-wallet/                 # Vision图形钱包
├── nac-vision-cli/                    # Vision命令行工具
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【开发工具】(7个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-cli/                           # NAC命令行工具
├── nac-cli-backup/                    # NAC CLI备份
├── nac-sdk/                           # NAC开发SDK
├── nac-serde/                         # NAC序列化库
├── tools/                             # 开发工具集
├── vscode-charter/                    # VSCode Charter扩展
├── cnnl-vscode-extension/             # VSCode CNNL扩展
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【部署与监控】(3个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-deploy/                        # 部署工具
├── nac-contract-deployer/             # 合约部署器
├── nac-monitor/                       # 监控系统
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【应用层】(2个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-rwa-exchange/                  # RWA交易所
├── nac-webdev-init/                   # Web开发初始化工具
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【测试与集成】(2个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── nac-test/                          # 测试框架
├── nac-integration-tests/             # 集成测试
│
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 【文档与示例】(3个模块)
├── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
├── docs/                              # 项目文档
├── examples/                          # 示例代码
├── memory/                            # 内存管理相关
│
└── ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
└── 【二进制文件】(1个模块)
    └── nac_binaries/                  # 编译后的二进制文件
```

---

## 🔧 故障排除

### 编译错误

如果遇到编译错误，请确保：

1. Rust版本 >= 1.70
2. 所有依赖已安装
3. 网络连接正常（下载crates.io依赖）

```bash
rustup update
cargo clean
cargo build
```

### 测试失败

```bash
# 查看详细测试输出
cargo test -- --nocapture

# 运行单个测试
cargo test test_name -- --nocapture
```

---

## 📞 联系方式

**项目**: NewAssetChain (NAC)  
**团队**: NewAssetChain Team  
**邮箱**: dev@newassetchain.io  
**仓库**: https://github.com/newassetchain/nac-udm

---

## 📄 许可证

MIT License

---

## ⚠️ 重要说明

### Charter标准库状态

**当前状态**: Charter标准库的.ch源文件尚未实现

**已有资源**:
- ✅ Charter编译器（完整）
- ✅ Charter语言规范（完整）
- ✅ Charter语法定义（charter.pest）
- ✅ 示例文件（shanghai_office.charter）
- ❌ 标准库源代码（.ch文件）

**标准库设计**（见CHARTER_LANGUAGE_SPECIFICATION.md）:
- `asset/` - 资产管理模块
- `sovereignty/` - 主权验证模块
- `acc/` - ACC协议模块
- `defi/` - DeFi功能模块
- `governance/` - 治理模块
- `utils/` - 工具函数模块

**下一步**: 根据语言规范实现Charter标准库的.ch源文件

---

## 🎯 开发路线图

- [x] L0原生层实现
- [x] L1协议层实现
- [x] L2治理层实现
- [x] L2网络层（CSNP）实现
- [x] Charter编译器实现
- [x] NVM_v2虚拟机实现
- [ ] Charter标准库实现
- [ ] 测试网部署
- [ ] 主网上线

---

**最后更新**: 2026-02-07  
**版本**: v1.0.0