NAC_Blockchain/protocol/nac-constitution-state

NAC宪法状态管理系统

NAC (New Asset Chain) 宪法状态管理系统是一个完整的宪法版本管理、升级验证、持久化和历史追踪解决方案。该系统为NAC公链提供了强大的宪法治理能力，确保宪法升级的安全性、可追溯性和透明度。

核心特性

NAC宪法状态管理系统提供了一套完整的宪法治理工具，包括版本管理、升级验证、状态持久化和历史审计等核心功能。系统采用模块化设计，各模块职责清晰，易于维护和扩展。

版本管理

系统支持完整的宪法版本生命周期管理。每个宪法版本包含版本号、宪法哈希、生效区块高度、条款数量、创建时间戳、创建者地址和版本描述等完整信息。版本管理器提供了版本添加、查询、排序和范围检索等功能，确保版本信息的完整性和可访问性。

版本比较功能支持按版本号进行排序和比较，生效性检查功能可以根据当前区块高度判断版本是否已生效。版本验证功能确保每个版本的条款数量和描述信息完整有效。

升级验证

升级验证器提供了多层次的安全验证机制。权限验证确保只有授权地址才能提议、执行或取消升级。升级条件验证包括版本号递增检查、生效高度验证、升级间隔验证和条款数量增量验证等多个维度。

系统支持配置最小升级间隔和最小条款增量，防止频繁升级或恶意升级。宪法哈希唯一性验证确保新版本确实包含了实质性的修改。所有验证规则都可以根据治理需求进行调整。

状态持久化

存储管理器提供了完整的状态持久化能力。状态快照包含当前版本、历史版本和待处理升级的完整信息。系统支持状态保存、加载、备份和恢复等操作，确保状态数据的安全性和可靠性。

状态序列化采用JSON格式，便于人工审查和调试。存储路径可配置，支持多环境部署。备份和恢复功能为系统提供了灾难恢复能力。

历史追踪

历史追踪器记录了所有宪法相关操作的完整审计日志。支持的操作类型包括版本创建、升级提议、升级执行、升级取消和版本回滚。每条历史记录包含操作类型、版本号、操作者地址、时间戳、区块高度和操作描述。

审计日志为每条记录分配唯一ID，支持按ID范围查询。历史查询功能支持多维度过滤，包括操作类型、版本号、操作者、时间范围和区块高度范围等。所有历史记录都持久化存储，确保审计追踪的完整性。

系统架构

系统采用模块化设计，主要包含以下核心模块：

lib.rs: 核心状态机实现，提供宪法状态管理的主要接口和逻辑。

version.rs: 版本管理模块，负责宪法版本的创建、查询和管理。

upgrade.rs: 升级验证模块，提供升级提议的多层次验证机制。

storage.rs: 持久化模块，负责状态的序列化、存储和恢复。

history.rs: 历史追踪模块，记录和查询所有宪法相关操作的审计日志。

error.rs: 错误类型定义，提供统一的错误处理机制。

使用示例

创建状态机

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();

提议升级

// 创建新版本
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();

执行升级

// 执行升级（当达到生效高度时）
let version = 2;
let current_height = 3000;
state_machine.execute_upgrade(version, current_height).unwrap();

查询历史

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();

状态同步

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个单元测试，覆盖所有核心功能。

运行测试：

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