# 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开发团队