185 lines
6.3 KiB
JSON
185 lines
6.3 KiB
JSON
{
|
||
"category": "architecture",
|
||
"title": "NAC架构核心原则",
|
||
"last_updated": "2026-02-07",
|
||
"principles": [
|
||
{
|
||
"principle_id": "ARCH_001",
|
||
"title": "四层架构体系",
|
||
"description": "NAC采用L0-L1-L2-L3四层架构，每层职责明确",
|
||
"layers": [
|
||
{
|
||
"layer": "L0",
|
||
"name": "Base Layer",
|
||
"chinese": "基础层",
|
||
"responsibility": "基础数据结构、哈希算法（Blake3）、密码学原语",
|
||
"key_components": [
|
||
"Blake3 Hash",
|
||
"Constitutional Layer（宪法层）",
|
||
"Basic Data Structures"
|
||
]
|
||
},
|
||
{
|
||
"layer": "L1",
|
||
"name": "Protocol Layer",
|
||
"chinese": "协议层",
|
||
"responsibility": "核心协议实现：NVM、CBPP、ACC-20、Fragmentation",
|
||
"key_components": [
|
||
"NVM (NAC Virtual Machine)",
|
||
"CBPP Consensus",
|
||
"ACC-20 Protocol",
|
||
"Fragmentation Protocol",
|
||
"Advanced Architecture"
|
||
]
|
||
},
|
||
{
|
||
"layer": "L2",
|
||
"name": "Constitutional Layer",
|
||
"chinese": "宪法层",
|
||
"responsibility": "不可变的宪法规则，治理机制，合规验证",
|
||
"key_components": [
|
||
"Constitutional Rules",
|
||
"Jurisdiction Management",
|
||
"Asset Categories",
|
||
"Governance System"
|
||
],
|
||
"immutability": "L2是不可变层，只能通过严格的治理流程修改"
|
||
},
|
||
{
|
||
"layer": "L3",
|
||
"name": "Application Layer",
|
||
"chinese": "应用层",
|
||
"responsibility": "DApps、Charter合约、用户应用",
|
||
"key_components": [
|
||
"Charter Contracts",
|
||
"DApps",
|
||
"User Applications"
|
||
]
|
||
}
|
||
],
|
||
"must_do": [
|
||
"严格遵守四层架构划分",
|
||
"L2宪法层规则必须通过治理流程修改",
|
||
"L1协议层实现必须符合L2宪法规则",
|
||
"所有代码必须明确标注所属层级"
|
||
],
|
||
"must_not_do": [
|
||
"不要混淆层级职责",
|
||
"不要绕过L2宪法层直接修改规则",
|
||
"不要在L1实现L3的应用逻辑"
|
||
]
|
||
},
|
||
{
|
||
"principle_id": "ARCH_002",
|
||
"title": "OpCode命名规范",
|
||
"description": "所有NVM OpCode必须使用UPPER_CASE命名",
|
||
"rationale": "符合区块链行业标准（EVM使用UPPER_CASE），提高代码可读性",
|
||
"examples": [
|
||
"PUSH1（不是Push1）",
|
||
"SSTORE（不是SStore）",
|
||
"JUMP_DEST（不是JumpDest）",
|
||
"CR_CREATE（不是CrCreate）"
|
||
],
|
||
"must_do": [
|
||
"所有OpCode使用UPPER_CASE",
|
||
"多单词OpCode使用下划线分隔",
|
||
"保持与EVM兼容的OpCode名称一致（如PUSH1, SSTORE）"
|
||
],
|
||
"must_not_do": [
|
||
"不要使用PascalCase（如Push1）",
|
||
"不要使用camelCase（如push1）",
|
||
"不要使用snake_case（如push_1）"
|
||
],
|
||
"related_decisions": ["D001"]
|
||
},
|
||
{
|
||
"principle_id": "ARCH_003",
|
||
"title": "Blake3哈希统一",
|
||
"description": "NAC使用Blake3作为唯一哈希算法，不使用SHA256或其他哈希",
|
||
"rationale": "Blake3性能优异，安全性高，统一哈希算法简化实现",
|
||
"must_do": [
|
||
"所有哈希计算使用Blake3",
|
||
"区块哈希使用Blake3",
|
||
"交易哈希使用Blake3",
|
||
"Merkle树使用Blake3"
|
||
],
|
||
"must_not_do": [
|
||
"不要使用SHA256",
|
||
"不要使用Keccak256",
|
||
"不要混用多种哈希算法"
|
||
]
|
||
},
|
||
{
|
||
"principle_id": "ARCH_004",
|
||
"title": "代码保留原则",
|
||
"description": "永远不要删除代码，所有接口都是为未来功能预留",
|
||
"rationale": "NAC是新开发的系统，很多接口和功能是为未来扩展预留的",
|
||
"must_do": [
|
||
"保留所有定义的接口和结构",
|
||
"保留所有OpCode定义（即使暂未实现）",
|
||
"保留所有模块和函数（即使暂未使用）"
|
||
],
|
||
"must_not_do": [
|
||
"不要删除'未使用'的代码",
|
||
"不要使用#[allow(unused)]隐藏问题",
|
||
"不要使用ignore/no_run隐藏测试问题"
|
||
],
|
||
"correct_approach": [
|
||
"遇到'未使用'警告时，添加proper imports",
|
||
"遇到测试失败时，修复问题而非忽略",
|
||
"遇到类型错误时，添加proper types"
|
||
]
|
||
},
|
||
{
|
||
"principle_id": "ARCH_005",
|
||
"title": "NAC原生设计原则",
|
||
"description": "NAC不是任何公链的继承、衍生或扩展，必须使用NAC原生方法",
|
||
"must_do": [
|
||
"使用Rust的类型系统（enum, struct）",
|
||
"使用强类型而非字符串表示",
|
||
"使用NAC原生术语和概念",
|
||
"使用NAC原生协议和算法"
|
||
],
|
||
"must_not_do": [
|
||
"不要使用JSON序列化（serde_json）表示复杂类型",
|
||
"不要模仿以太坊的实现方式",
|
||
"不要使用Cosmos的IBC协议",
|
||
"不要使用比特币的UTXO模型"
|
||
],
|
||
"common_mistakes": [
|
||
{
|
||
"mistake": "使用JSON字符串表示提案内容",
|
||
"correction": "使用Rust enum定义强类型的ProposalContent",
|
||
"example": "enum ProposalContent { CreateShard {...}, ModifyConfig {...} }"
|
||
},
|
||
{
|
||
"mistake": "使用serde_json序列化",
|
||
"correction": "使用Rust的类型系统和二进制序列化"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"principle_id": "ARCH_006",
|
||
"title": "测试驱动开发",
|
||
"description": "所有功能必须有完整的单元测试和集成测试",
|
||
"must_do": [
|
||
"每个模块必须有tests模块",
|
||
"每个公开函数必须有测试用例",
|
||
"测试必须覆盖正常流程和错误流程",
|
||
"所有测试必须通过（cargo test）"
|
||
],
|
||
"must_not_do": [
|
||
"不要提交未通过测试的代码",
|
||
"不要使用#[ignore]跳过测试",
|
||
"不要使用no_run隐藏doctest问题"
|
||
],
|
||
"test_requirements": [
|
||
"单元测试覆盖率 > 80%",
|
||
"所有公开API必须有doctest",
|
||
"集成测试覆盖核心流程",
|
||
"性能测试覆盖关键路径"
|
||
]
|
||
}
|
||
]
|
||
}
|