diff --git a/docs_center/CONSTITUTION_LAYER_002_20260318.md b/docs_center/CONSTITUTION_LAYER_002_20260318.md new file mode 100644 index 0000000..a0ddbb0 --- /dev/null +++ b/docs_center/CONSTITUTION_LAYER_002_20260318.md @@ -0,0 +1,118 @@ +# 工单 #CONSTITUTION-LAYER-002:宪法层四项完善 + +**日期**:2026-03-18 +**状态**:✅ 100% 完成 +**Git 提交**:`a754adc` +**关联工单**:#CONSTITUTION-LAYER-001(宪法层初步补全)、#STORAGE-LAYER-001(L3存储层) + +--- + +## 一、工作内容概述 + +本次工单落地实施了宪法层的四项后续完善工作,严格遵循"尊重前期开发者工作成果"原则,采用追加扩展策略。 + +--- + +## 二、详细变更记录 + +### 2.1 条款文件拆分(A04-A43) + +**背景**:前期开发者将 A01-A43 全部写在 `amendments.cnnl` 中,不便于按章节管理和查阅。 + +**变更**:将 `amendments.cnnl` 按章节拆分为 6 个独立文件,`amendments.cnnl` 原文件保留不变(作为历史参考): + +| 新文件 | 条款范围 | 内容 | +|--------|---------|------| +| `infrastructure.cnnl` | A04-A08 | 基础架构条款(CBPP/CSNP/nac_lens/ACC-20/CNNL) | +| `asset_compliance.cnnl` | A09-A16 | 资产合规条款(GNACS/RWA/DID/CR/跨境/AI估值/冻结/销毁) | +| `governance.cnnl` | A17-A24 | 治理条款(XIC投票/修改程序/宪法法院/法官选举/透明度/紧急权力) | +| `xtzh_currency.cnnl` | A25-A32 | XTZH货币条款(黄金储备/SDR锚定/铸造/销毁/审计/保管/紧急/透明) | +| `jurisdiction.cnnl` | A33-A38 | 多辖区条款(隔离/双收据/动态加入/公平分配/协商委员会/插件验证) | +| `ai_compliance.cnnl` | A39-A43 | AI合规条款(合规检查/估值准确性/审计追踪/模型治理/人工监督) | + +> 注:A01-A03 已在上次工单(#CONSTITUTION-LAYER-001)中创建为 `core_principles.cnnl` + +### 2.2 constitution_hash 升级为 SHA3-384 Merkle 根 + +**背景**:`constitution_hash` 原为硬编码字符串,不能反映实际激活条款的状态。 + +**变更**:在 `nac-constitution-state/src/lib.rs` 末尾追加 `calculate_constitution_merkle_root()` 函数: +- 使用 **SHA3-384**(NAC 公链原生哈希算法,48字节/96位十六进制) +- 对所有激活条款 ID 字符串逐一计算叶节点哈希,再向上归并为 Merkle 根 +- 奇数个节点时复制最后一个节点(标准 Merkle 树处理方式) +- 输出格式:96 位十六进制字符串 + +### 2.3 L3 存储层对接(state_database_ext.rs v2) + +**背景**:`state_database_ext.rs` 的 `constitution_ref` 字段为普通字符串,无类型安全保障。 + +**变更**:将 `state_database_ext.rs` 升级为 v2,新增: + +| 新增内容 | 说明 | +|---------|------| +| `ConstitutionClauseId` 枚举 | A01-A56 完整 56 条条款的类型安全枚举 | +| `as_str()` / `from_str()` | 与 CNNL 文件中的 clause 名称双向转换 | +| `ConstitutionalStateValue::new()` | 类型安全的状态值构造函数 | +| `get_clause_id()` | 从 `constitution_ref` 字符串获取类型安全的枚举值 | +| `ConstitutionRefValidator` | 验证器,支持按章节分类验证(资产条款/治理条款) | +| 完整单元测试 | 5 个测试用例,覆盖枚举转换、验证、56条完整性 | + +> 原有的 `ConstitutionalStateValue`、`StateSnapshot`、`GNACSStateIndex` 结构体保持完全不变。 + +### 2.4 nac_lens 协议对接(constitution-service main.rs v2) + +**背景**:宪法服务的 `main.rs` 只有骨架,`mod nrpc` 为模拟实现。 + +**变更**:将 `main.rs` 升级为 v2,实现完整的 nac_lens 协议服务: + +| 新增内容 | 说明 | +|---------|------| +| `NacLensRequest` / `NacLensResponse` | nac_lens 协议请求/响应结构体 | +| `ConstitutionMethod` 枚举 | 8 个支持的方法 | +| `handle_request()` | 完整的请求路由和处理逻辑 | +| TCP 监听 | 实际 TCP 服务器,监听 `0.0.0.0:22050` | +| 创世宪法初始化 | A01-A08 基础架构条款默认激活 | + +**支持的 nac_lens 方法**: + +| 方法名 | 功能 | +|--------|------| +| `constitution_verify_clause` | 验证条款是否激活 | +| `constitution_get_hash` | 获取当前宪法 SHA3-384 Merkle 根 | +| `constitution_list_active` | 获取激活条款列表 | +| `constitution_issue_cr` | 签发宪法收据(CR) | +| `constitution_verify_cr` | 验证宪法收据 | +| `constitution_get_clause` | 获取条款详情 | +| `constitution_propose_amendment` | 提交修改提案 | +| `constitution_status` | 获取服务状态 | + +--- + +## 三、同步状态 + +| 服务器 | 状态 | 同步文件数 | +|--------|------|-----------| +| 备份服务器 (103.96.148.7) | ✅ Git 提交 `a754adc`,已推送 Gitea | 10 files, +1065 lines | +| 服务器A (103.43.191.50) | ✅ 同步完成 | 10/10 | +| 服务器B (103.43.188.43) | ✅ 同步完成 | 10/10 | + +--- + +## 四、五大治理哲学对应关系 + +| 哲学原则 | 本次实现 | +|---------|---------| +| **约法即是治法** | `ConstitutionRefValidator` 强制验证每条状态变更必须引用合法条款 | +| **宪法即是规则** | `ConstitutionClauseId` 枚举是代码层面的"宪法规则表",编译时强制检查 | +| **参与即是共识** | SHA3-384 Merkle 根确保每个节点对激活条款集合有一致的密码学共识 | +| **节点产生区块** | 宪法服务通过 nac_lens 协议为 CBPP 节点提供条款验证服务 | +| **交易决定区块大小** | CR 签发与交易绑定,交易携带的条款引用决定了宪法验证的范围 | + +--- + +## 五、后续工作建议 + +1. **nac-nac_lens crate 完整实现**:当前 `nac-nac_lens/src/lib.rs` 只有 `add()` 函数,需要实现完整的 nac_lens 协议(帧格式、连接管理、多路复用) +2. **RocksDB 持久化**:宪法服务状态目前为内存存储,需要对接 L3 存储层的 `state_database.rs` +3. **条款激活流程**:A09-A56 的激活需要通过 A18_AmendmentProcess 治理流程,目前仅 A01-A08 默认激活 +4. **CBPP 完整对接**:`constitution_validator.rs` 中的 mock 实现需要替换为真实的 nac_lens 调用