277 lines
6.8 KiB
Markdown
277 lines
6.8 KiB
Markdown
# 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公链命名规范
|