NAC_Blockchain/docs/NAC_NAMING_CONVENTIONS.md

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）
• 文档引用：使用大写层级编号+空格+层名称

示例：

// ✅ 正确
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等）

示例：

// ✅ 正确
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;

文档示例：

✅ 正确：
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

示例：

// ✅ 正确
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结构体
• 两者不可混淆

示例：

// ✅ 正确
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编码位数不一致

❌ 错误：

let gnacs = GNACSCode::new([0u8; 48]); // 48字节，不是48位

✅ 正确：

let gnacs = GNACSCode::new([0u8; 6]); // 48位 = 6字节

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

❌ 错误：

NAC公链使用cbpp共识协议和nvm虚拟机。

✅ 正确：

NAC公链使用CBPP共识协议和NVM虚拟机。

错误3: 模块名使用大写

❌ 错误：

pub mod CBPP;
pub mod NVM;

✅ 正确：

pub mod cbpp;
pub mod nvm;

错误4: GNACS编码命名冲突

❌ 错误：

// nvm_v2中的30位编码也叫GNACSCode
pub struct GNACSCode {
    pub code: String, // 30位字符串
}

✅ 正确：

// 重命名为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命名规范
2. NAC公链技术架构白皮书
3. NAC定义问题修正日志

---

版本历史

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