252 lines
8.3 KiB
Markdown
252 lines
8.3 KiB
Markdown
# NAC宪法状态管理系统
|
||
|
||
NAC (New Asset Chain) 宪法状态管理系统是一个完整的宪法版本管理、升级验证、持久化和历史追踪解决方案。该系统为NAC公链提供了强大的宪法治理能力，确保宪法升级的安全性、可追溯性和透明度。
|
||
|
||
## 核心特性
|
||
|
||
NAC宪法状态管理系统提供了一套完整的宪法治理工具，包括版本管理、升级验证、状态持久化和历史审计等核心功能。系统采用模块化设计，各模块职责清晰，易于维护和扩展。
|
||
|
||
### 版本管理
|
||
|
||
系统支持完整的宪法版本生命周期管理。每个宪法版本包含版本号、宪法哈希、生效区块高度、条款数量、创建时间戳、创建者地址和版本描述等完整信息。版本管理器提供了版本添加、查询、排序和范围检索等功能，确保版本信息的完整性和可访问性。
|
||
|
||
版本比较功能支持按版本号进行排序和比较，生效性检查功能可以根据当前区块高度判断版本是否已生效。版本验证功能确保每个版本的条款数量和描述信息完整有效。
|
||
|
||
### 升级验证
|
||
|
||
升级验证器提供了多层次的安全验证机制。权限验证确保只有授权地址才能提议、执行或取消升级。升级条件验证包括版本号递增检查、生效高度验证、升级间隔验证和条款数量增量验证等多个维度。
|
||
|
||
系统支持配置最小升级间隔和最小条款增量，防止频繁升级或恶意升级。宪法哈希唯一性验证确保新版本确实包含了实质性的修改。所有验证规则都可以根据治理需求进行调整。
|
||
|
||
### 状态持久化
|
||
|
||
存储管理器提供了完整的状态持久化能力。状态快照包含当前版本、历史版本和待处理升级的完整信息。系统支持状态保存、加载、备份和恢复等操作，确保状态数据的安全性和可靠性。
|
||
|
||
状态序列化采用JSON格式，便于人工审查和调试。存储路径可配置，支持多环境部署。备份和恢复功能为系统提供了灾难恢复能力。
|
||
|
||
### 历史追踪
|
||
|
||
历史追踪器记录了所有宪法相关操作的完整审计日志。支持的操作类型包括版本创建、升级提议、升级执行、升级取消和版本回滚。每条历史记录包含操作类型、版本号、操作者地址、时间戳、区块高度和操作描述。
|
||
|
||
审计日志为每条记录分配唯一ID，支持按ID范围查询。历史查询功能支持多维度过滤，包括操作类型、版本号、操作者、时间范围和区块高度范围等。所有历史记录都持久化存储，确保审计追踪的完整性。
|
||
|
||
## 系统架构
|
||
|
||
系统采用模块化设计，主要包含以下核心模块：
|
||
|
||
**lib.rs**: 核心状态机实现，提供宪法状态管理的主要接口和逻辑。
|
||
|
||
**version.rs**: 版本管理模块，负责宪法版本的创建、查询和管理。
|
||
|
||
**upgrade.rs**: 升级验证模块，提供升级提议的多层次验证机制。
|
||
|
||
**storage.rs**: 持久化模块，负责状态的序列化、存储和恢复。
|
||
|
||
**history.rs**: 历史追踪模块，记录和查询所有宪法相关操作的审计日志。
|
||
|
||
**error.rs**: 错误类型定义，提供统一的错误处理机制。
|
||
|
||
## 使用示例
|
||
|
||
### 创建状态机
|
||
|
||
```rust
|
||
use nac_constitution_state::{ConstitutionStateMachine, ConstitutionVersion};
|
||
use nac_udm::primitives::{Hash, Address};
|
||
use std::path::PathBuf;
|
||
|
||
// 创建初始版本
|
||
let initial_version = ConstitutionVersion::new(
|
||
1, // 版本号
|
||
Hash::zero(), // 宪法哈希
|
||
1000, // 生效区块高度
|
||
10, // 条款数量
|
||
1234567890, // 创建时间戳
|
||
Address::zero(), // 创建者地址
|
||
"Initial version".to_string(), // 版本描述
|
||
);
|
||
|
||
// 创建状态机
|
||
let storage_path = PathBuf::from("/path/to/storage");
|
||
let mut state_machine = ConstitutionStateMachine::new(
|
||
initial_version,
|
||
storage_path
|
||
).unwrap();
|
||
```
|
||
|
||
### 提议升级
|
||
|
||
```rust
|
||
// 创建新版本
|
||
let new_version = ConstitutionVersion::new(
|
||
2, // 版本号
|
||
Hash::zero(), // 宪法哈希
|
||
3000, // 生效区块高度
|
||
15, // 条款数量
|
||
1234567900, // 创建时间戳
|
||
Address::zero(), // 创建者地址
|
||
"Version 2 upgrade".to_string(), // 版本描述
|
||
);
|
||
|
||
// 提议升级
|
||
let proposer = Address::zero();
|
||
state_machine.propose_upgrade(new_version, proposer).unwrap();
|
||
```
|
||
|
||
### 执行升级
|
||
|
||
```rust
|
||
// 执行升级（当达到生效高度时）
|
||
let version = 2;
|
||
let current_height = 3000;
|
||
state_machine.execute_upgrade(version, current_height).unwrap();
|
||
```
|
||
|
||
### 查询历史
|
||
|
||
```rust
|
||
use nac_constitution_state::{HistoryFilter, HistoryRecordType};
|
||
|
||
// 创建查询过滤器
|
||
let filter = HistoryFilter {
|
||
record_type: Some(HistoryRecordType::UpgradeExecuted),
|
||
version: Some(2),
|
||
..Default::default()
|
||
};
|
||
|
||
// 查询历史记录
|
||
let records = state_machine.query_history(filter).unwrap();
|
||
```
|
||
|
||
### 状态同步
|
||
|
||
```rust
|
||
use nac_constitution_state::StateSnapshot;
|
||
|
||
// 从远程节点获取状态快照
|
||
let remote_state = get_remote_state(); // 假设的函数
|
||
|
||
// 同步状态
|
||
state_machine.sync(remote_state).unwrap();
|
||
```
|
||
|
||
## API文档
|
||
|
||
### ConstitutionVersion
|
||
|
||
宪法版本结构体，包含完整的版本信息。
|
||
|
||
**字段**:
|
||
- `version: u64` - 版本号
|
||
- `constitution_hash: Hash` - 宪法哈希（48字节）
|
||
- `effective_from: u64` - 生效区块高度
|
||
- `clause_count: u64` - 条款数量
|
||
- `created_at: u64` - 创建时间戳
|
||
- `created_by: Address` - 创建者地址（32字节）
|
||
- `description: String` - 版本描述
|
||
|
||
**方法**:
|
||
- `new()` - 创建新版本
|
||
- `compare()` - 比较版本号
|
||
- `is_effective()` - 检查是否已生效
|
||
- `validate()` - 验证版本有效性
|
||
|
||
### ConstitutionStateMachine
|
||
|
||
宪法状态机，管理宪法版本和升级。
|
||
|
||
**方法**:
|
||
- `new()` - 创建新的状态机
|
||
- `load()` - 从存储加载状态机
|
||
- `save()` - 保存状态到存储
|
||
- `propose_upgrade()` - 提议升级
|
||
- `execute_upgrade()` - 执行升级
|
||
- `cancel_upgrade()` - 取消升级
|
||
- `rollback()` - 回滚到指定版本
|
||
- `get_current_version()` - 获取当前版本
|
||
- `get_history()` - 获取历史版本
|
||
- `get_version()` - 获取指定版本
|
||
- `get_pending_upgrades()` - 获取待处理的升级
|
||
- `query_history()` - 查询历史记录
|
||
- `get_audit_log()` - 获取审计日志
|
||
- `sync()` - 同步状态
|
||
|
||
### UpgradeValidator
|
||
|
||
升级验证器，验证升级提议的合法性。
|
||
|
||
**方法**:
|
||
- `new()` - 创建新的验证器
|
||
- `add_authorized_address()` - 添加授权地址
|
||
- `remove_authorized_address()` - 移除授权地址
|
||
- `is_authorized()` - 检查地址是否授权
|
||
- `validate_permission()` - 验证权限
|
||
- `validate_upgrade()` - 验证升级
|
||
- `set_min_upgrade_interval()` - 设置最小升级间隔
|
||
- `set_min_clause_increment()` - 设置最小条款增量
|
||
|
||
### HistoryTracker
|
||
|
||
历史追踪器，记录和查询审计日志。
|
||
|
||
**方法**:
|
||
- `new()` - 创建新的追踪器
|
||
- `load()` - 从存储加载追踪器
|
||
- `record_version()` - 记录版本创建
|
||
- `record_proposal()` - 记录升级提议
|
||
- `record_upgrade()` - 记录升级执行
|
||
- `record_cancellation()` - 记录升级取消
|
||
- `record_rollback()` - 记录版本回滚
|
||
- `query()` - 查询历史记录
|
||
- `get_audit_log()` - 获取审计日志
|
||
- `get_all_records()` - 获取所有记录
|
||
|
||
## 测试
|
||
|
||
系统包含22个单元测试，覆盖所有核心功能。
|
||
|
||
运行测试：
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
测试覆盖范围：
|
||
- 版本创建和验证（3个测试）
|
||
- 版本管理器功能（5个测试）
|
||
- 升级验证功能（5个测试）
|
||
- 存储功能（2个测试）
|
||
- 历史追踪功能（4个测试）
|
||
- 状态机核心功能（3个测试）
|
||
|
||
## 依赖
|
||
|
||
- `nac-udm`: NAC统一数据模型，提供Hash和Address等基础类型
|
||
- `serde`: 序列化和反序列化支持
|
||
- `serde_json`: JSON格式支持
|
||
|
||
## 版本历史
|
||
|
||
### v0.2.0 (2026-02-18)
|
||
|
||
- ✅ 完整实现版本管理功能
|
||
- ✅ 完整实现升级验证功能
|
||
- ✅ 完整实现持久化功能
|
||
- ✅ 完整实现历史追踪功能
|
||
- ✅ 添加22个单元测试
|
||
- ✅ 完善API文档
|
||
|
||
### v0.1.0
|
||
|
||
- 基础的ConstitutionVersion结构
|
||
- 简单的ConstitutionStateMachine
|
||
- 基本的upgrade方法
|
||
|
||
## 许可证
|
||
|
||
NAC公链项目专有
|
||
|
||
## 作者
|
||
|
||
NAC开发团队
|