# NAC公链命名规范文档

**版本**: v1.0  
**日期**: 2026-02-14  
**状态**: 正式发布  

---

## 📋 目录

1. [概述](#概述)
2. [架构层级命名](#架构层级命名)
3. [协议命名规范](#协议命名规范)
4. [代码命名规范](#代码命名规范)
5. [文档命名规范](#文档命名规范)
6. [常见错误和修正](#常见错误和修正)

---

## 概述

本文档定义了NAC公链项目中所有命名的统一规范，包括架构层级、协议名称、代码模块、文档等。

**核心原则**：
- **一致性**：同一概念在不同场景下使用统一的命名
- **清晰性**：命名应清晰表达其含义和用途
- **规范性**：遵循Rust语言和区块链行业的命名惯例

---

## 架构层级命名

### NAC 5层架构

| 层级 | 英文名称 | 中文名称 | 代码模块名 | 文档引用 |
|------|----------|----------|------------|----------|
| L5 | Application Layer | 应用层 | `l5_application` | L5应用层 |
| L4 | AI Layer | AI层 | `l4_ai` | L4 AI层 |
| L3 | Storage Layer | 存储层 | `l3_storage` | L3存储层 |
| L2 | Constitutional Governance Layer | 宪法规则层 | `l2_governance` | L2宪法规则层 |
| L1 | Protocol Layer | 协议层 | `l1_protocol` | L1协议层 |
| L0 | Foundation Layer | 基础设施层 | `l0_native` | L0基础设施层 |

**规则**：
- 代码模块名：使用小写+下划线（snake_case）
- 文档引用：使用大写层级编号+空格+层名称

**示例**：
```rust
// ✅ 正确
pub mod l0_native;
pub mod l1_protocol;

// ❌ 错误
pub mod L0Native;
pub mod L1Protocol;
```

---

## 协议命名规范

### 核心协议

| 协议全称 | 缩写 | 代码模块名 | 文档引用 | UID命名空间 |
|----------|------|------------|----------|-------------|
| Constitutional Block Production Protocol | CBPP | `cbpp` | CBPP | `nac.cbpp` |
| Constitutional Structured Network Protocol | CSNP | `csnp` | CSNP | `nac.csnp` |
| NAC Virtual Machine | NVM | `nvm` | NVM | `nac.nvm` |
| Asset Certificate Contract Protocol | ACC | `acc` | ACC | `nac.acc` |
| Global NAC Asset Classification System | GNACS | `gnacs` | GNACS | `nac.gnacs` |
| XTZH Stability Mechanism | XTZH | `xtzh` | XTZH | `nac.xtzh` |

**规则**：
1. **文档中**：使用大写缩写（CBPP、CSNP、NVM等）
2. **代码模块名**：使用小写（cbpp、csnp、nvm等）
3. **UID命名空间**：使用小写（nac.cbpp、nac.csnp等）

**示例**：
```rust
// ✅ 正确
pub mod cbpp;
pub use nac_udm::l1_protocol::cbpp::ConstitutionalReceipt;

// UID: nac.cbpp.ConstitutionalReceipt.v1

// ❌ 错误
pub mod CBPP;
pub use nac_udm::l1_protocol::CBPP::ConstitutionalReceipt;
```

**文档示例**：
```markdown
✅ 正确：
NAC公链使用CBPP共识协议，结合CSNP网络协议，在NVM虚拟机上运行ACC-20协议。

❌ 错误：
NAC公链使用cbpp共识协议，结合csnp网络协议，在nvm虚拟机上运行acc-20协议。
```

---

## 代码命名规范

### Rust命名规范

| 类型 | 命名规范 | 示例 |
|------|----------|------|
| 模块名 | snake_case | `l1_protocol`, `state_database` |
| 结构体 | PascalCase | `GNACSCode`, `StateDatabase` |
| 枚举 | PascalCase | `StateKey`, `ArchitectureLayer` |
| 函数 | snake_case | `get_state`, `set_value` |
| 常量 | SCREAMING_SNAKE_CASE | `MAX_SIZE`, `DEFAULT_TIMEOUT` |
| 变量 | snake_case | `gnacs_code`, `state_value` |

**示例**：
```rust
// ✅ 正确
pub struct GNACSCode([u8; 6]);

pub fn get_gnacs_code() -> GNACSCode {
    GNACSCode([0u8; 6])
}

const MAX_GNACS_LENGTH: usize = 6;

// ❌ 错误
pub struct gnacs_code([u8; 6]);

pub fn GetGNACSCode() -> gnacs_code {
    gnacs_code([0u8; 6])
}

const max_gnacs_length: usize = 6;
```

### GNACS编码命名

| 概念 | 类型 | 长度 | 代码名称 | 文档引用 |
|------|------|------|----------|----------|
| NAC核心GNACS编码 | 二进制 | 48位（6字节） | `GNACSCode` | GNACS编码 |
| 资产分类编码 | 字符串 | 30位 | `AssetClassificationCode` | 资产分类编码 |

**规则**：
- **NAC核心GNACS编码**：48位二进制，使用`GNACSCode`结构体
- **资产分类编码**：30位字符串，使用`AssetClassificationCode`结构体
- 两者不可混淆

**示例**：
```rust
// ✅ 正确
pub struct GNACSCode([u8; 6]); // 48位 = 6字节

pub struct AssetClassificationCode {
    pub code: String, // 30位字符串
}

// ❌ 错误
pub struct GNACSCode {
    pub code: String, // 30位字符串 - 这是错误的！
}
```

---

## 文档命名规范

### 文档标题

| 类型 | 命名规范 | 示例 |
|------|----------|------|
| 技术文档 | 大写缩写 | CBPP技术白皮书、NVM虚拟机规范 |
| 协议文档 | 大写缩写 | ACC-20协议、GNACS编码规范 |
| 报告文档 | 大写缩写 | NAC架构改造报告、XTZH AI整合方案 |

### 文件命名

| 类型 | 命名规范 | 示例 |
|------|----------|------|
| Markdown文档 | SCREAMING_SNAKE_CASE | `NAC_NAMING_CONVENTIONS.md` |
| Rust源文件 | snake_case | `state_database.rs` |
| 配置文件 | snake_case | `cargo.toml` |

---

## 常见错误和修正

### 错误1: GNACS编码位数不一致

❌ **错误**：
```rust
let gnacs = GNACSCode::new([0u8; 48]); // 48字节，不是48位
```

✅ **正确**：
```rust
let gnacs = GNACSCode::new([0u8; 6]); // 48位 = 6字节
```

### 错误2: 协议名称大小写混用

❌ **错误**：
```markdown
NAC公链使用cbpp共识协议和nvm虚拟机。
```

✅ **正确**：
```markdown
NAC公链使用CBPP共识协议和NVM虚拟机。
```

### 错误3: 模块名使用大写

❌ **错误**：
```rust
pub mod CBPP;
pub mod NVM;
```

✅ **正确**：
```rust
pub mod cbpp;
pub mod nvm;
```

### 错误4: GNACS编码命名冲突

❌ **错误**：
```rust
// nvm_v2中的30位编码也叫GNACSCode
pub struct GNACSCode {
    pub code: String, // 30位字符串
}
```

✅ **正确**：
```rust
// 重命名为AssetClassificationCode
pub struct AssetClassificationCode {
    pub code: String, // 30位字符串
}
```

---

## 验收标准

### 代码命名
- ✅ 所有模块名使用snake_case
- ✅ 所有结构体使用PascalCase
- ✅ 所有函数使用snake_case
- ✅ 所有常量使用SCREAMING_SNAKE_CASE

### 文档命名
- ✅ 协议名称使用大写缩写（CBPP、NVM、GNACS等）
- ✅ 架构层级使用统一格式（L0基础设施层、L1协议层等）
- ✅ 文件名使用SCREAMING_SNAKE_CASE

### GNACS编码
- ✅ NAC核心GNACS编码统一为48位二进制（6字节）
- ✅ 资产分类编码独立为30位字符串
- ✅ 两者命名清晰，不混淆

---

## 参考资料

1. [Rust命名规范](https://rust-lang.github.io/api-guidelines/naming.html)
2. [NAC公链技术架构白皮书](../NAC公链技术架构白皮书（最终整合版）.docx)
3. [NAC定义问题修正日志](../../NAC_Definition_Fix_Log_20260214.md)

---

## 版本历史

- **v1.0** (2026-02-14): 初始版本，定义NAC公链命名规范