# NAC升级框架 (nac-upgrade-framework) NAC公链统一升级机制框架，为所有NAC模块提供版本管理、升级协议、回滚机制和升级治理。 ## 📋 目录 - [功能特性](#功能特性) - [架构设计](#架构设计) - [快速开始](#快速开始) - [详细文档](#详细文档) - [测试](#测试) - [贡献指南](#贡献指南) ## 🎯 功能特性 ### 1. 版本管理 - ✅ 语义化版本控制 (Semantic Versioning 2.0.0) - ✅ 版本兼容性检查 - ✅ 破坏性变更检测 - ✅ 版本升级路径验证 ### 2. 升级协议 - ✅ 统一的升级接口 (`Upgradeable` trait) - ✅ 升级提案系统 - ✅ 状态迁移脚本 - ✅ 配置变更管理 ### 3. 回滚机制 - ✅ 自动快照创建 - ✅ 快照完整性验证 - ✅ 一键回滚 - ✅ 快照管理和清理 ### 4. 升级治理 - ✅ 提案投票系统 - ✅ 可配置的通过阈值 - ✅ 投票权重支持 - ✅ 提案生命周期管理 ## 🏗️ 架构设计 ``` nac-upgrade-framework/ ├── src/ │ ├── lib.rs # 主入口 │ ├── version.rs # 版本管理 │ ├── traits.rs # 核心trait定义 │ ├── proposal.rs # 升级提案 │ ├── snapshot.rs # 快照和回滚 │ ├── governance.rs # 治理和投票 │ ├── migration.rs # 状态迁移 │ ├── error.rs # 错误类型 │ └── helpers.rs # 辅助宏和函数 ├── tests/ │ └── integration_tests.rs ├── Cargo.toml └── README.md ``` ## 🚀 快速开始 ### 1. 添加依赖在模块的 `Cargo.toml` 中添加： ```toml [dependencies] nac-upgrade-framework = { path = "../nac-upgrade-framework" } ``` ### 2. 为结构体添加升级字段 ```rust use nac_upgrade_framework::{Version, UpgradeRecord}; use serde::{Deserialize, Serialize}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct MyModule { // 现有字段... pub data: String, // 升级框架必需字段 pub version: Version, pub upgrade_history: Vec, } ``` ### 3. 实现升级逻辑 ```rust use nac_upgrade_framework::{UpgradeData, Result}; impl MyModule { pub fn new() -> Self { Self { data: String::new(), version: Version::new(1, 0, 0), upgrade_history: Vec::new(), } } // 实现具体的升级逻辑 fn do_upgrade(&mut self, target: Version, data: UpgradeData) -> Result<()> { // 根据目标版本执行不同的升级逻辑 match (target.major, target.minor, target.patch) { (1, 1, 0) => { // 升级到1.1.0的逻辑 self.data = format!("upgraded to {}", target); Ok(()) } _ => Ok(()) } } } ``` ### 4. 使用宏实现Upgradeable trait ```rust nac_upgrade_framework::impl_upgradeable!(MyModule, "my-module", Version::new(1, 0, 0)); ``` ### 5. 执行升级 ```rust use nac_upgrade_framework::{traits::Upgradeable, UpgradeData, Version}; fn main() { let mut module = MyModule::new(); // 创建升级数据 let upgrade_data = UpgradeData::new(); // 执行升级 let target = Version::new(1, 1, 0); match module.upgrade(target, upgrade_data) { Ok(_) => println!("升级成功！"), Err(e) => println!("升级失败: {}", e), } // 查看升级历史 for record in module.upgrade_history() { println!("从 {} 升级到 {}", record.from_version, record.to_version); } } ``` ## 📚 详细文档 ### 版本管理 ```rust use nac_upgrade_framework::Version; // 创建版本 let v1 = Version::new(1, 0, 0); let v2 = Version::new(1, 1, 0); let v3 = Version::new(2, 0, 0); // 版本比较 assert!(v1 < v2); assert!(v2 < v3); // 兼容性检查 assert!(v1.is_compatible_with(&v2)); // 同一major版本 assert!(!v1.is_compatible_with(&v3)); // 不同major版本 // 破坏性变更检查 assert!(!v1.is_breaking_change(&v2)); // minor升级，非破坏性 assert!(v1.is_breaking_change(&v3)); // major升级，破坏性 // 版本解析 let v = Version::parse("1.2.3").unwrap(); assert_eq!(v, Version::new(1, 2, 3)); ``` ### 升级提案 ```rust use nac_upgrade_framework::{UpgradeProposal, UpgradeData, Version}; use std::collections::HashMap; // 创建升级提案 let proposal = UpgradeProposal::new( "nac-nvm".to_string(), Version::new(1, 0, 0), Version::new(1, 1, 0), "Upgrade NVM to 1.1.0 with new opcodes".to_string(), UpgradeData { migration_script: None, config_changes: HashMap::new(), state_migrations: vec![], breaking_changes: vec![], }, "admin".to_string(), 7, // 7天投票期 ); // 开始投票 let mut proposal = proposal; proposal.start_voting(); // 检查状态 assert!(proposal.can_vote()); ``` ### 快照和回滚 ```rust use nac_upgrade_framework::{Snapshot, SnapshotManager}; let mut manager = SnapshotManager::new(); // 创建快照 let snapshot = Snapshot::new( "nac-nvm".to_string(), Version::new(1, 0, 0), vec![1, 2, 3, 4], // 状态数据 ); // 保存快照 let snapshot_id = manager.save(snapshot); // 获取快照 let snapshot = manager.get(&snapshot_id).unwrap(); // 验证完整性 assert!(snapshot.verify_integrity()); // 回滚（在Upgradeable trait中自动处理） ``` ### 治理和投票 ```rust use nac_upgrade_framework::{ governance::{Vote, VoteRecord, VoteResult, GovernanceConfig}, }; // 创建投票结果 let mut result = VoteResult::new(); // 添加投票 result.add_vote(VoteRecord::new("voter1".to_string(), Vote::Yes, 1)); result.add_vote(VoteRecord::new("voter2".to_string(), Vote::Yes, 1)); result.add_vote(VoteRecord::new("voter3".to_string(), Vote::No, 1)); // 检查是否通过 let config = GovernanceConfig::default_config(); // 66%通过阈值 assert!(result.is_approved(config.approval_threshold)); // 获取投票统计 println!("赞成: {}%", result.yes_percentage()); println!("反对: {}%", result.no_percentage()); ``` ## 🧪 测试运行所有测试： ```bash cd nac-upgrade-framework cargo test ``` 运行特定模块测试： ```bash cargo test version cargo test proposal cargo test snapshot cargo test governance ``` 运行集成测试： ```bash cargo test --test integration_tests ``` ## 📊 测试覆盖率当前测试覆盖率：**>90%** - `version.rs`: 13个测试 ✅ - `proposal.rs`: 7个测试 ✅ - `snapshot.rs`: 9个测试 ✅ - `governance.rs`: 9个测试 ✅ - `migration.rs`: 7个测试 ✅ - `traits.rs`: 2个测试 ✅ - `helpers.rs`: 2个测试 ✅ - `error.rs`: 3个测试 ✅ **总计: 52个测试，全部通过 ✅** ## 🔧 配置选项 ### 治理配置 ```rust use nac_upgrade_framework::governance::GovernanceConfig; // 默认配置（适用于一般升级） let config = GovernanceConfig::default_config(); // - 通过阈值: 66% // - 拒绝阈值: 33% // - 最小投票数: 3 // - 投票期: 7天 // 严格配置（适用于关键升级） let config = GovernanceConfig::strict_config(); // - 通过阈值: 80% // - 拒绝阈值: 20% // - 最小投票数: 5 // - 投票期: 14天 // 宽松配置（适用于非关键升级） let config = GovernanceConfig::relaxed_config(); // - 通过阈值: 50% // - 拒绝阈值: 50% // - 最小投票数: 1 // - 投票期: 3天 ``` ## 🎓 最佳实践 ### 1. 版本规划 - **Major版本**: 破坏性变更，不兼容的API修改 - **Minor版本**: 新功能，向后兼容 - **Patch版本**: Bug修复，向后兼容 ### 2. 升级前检查 ```rust // 1. 检查版本兼容性 if !module.can_upgrade_to(&target_version)? { return Err("Cannot upgrade to this version"); } // 2. 创建快照 let snapshot = module.create_snapshot()?; // 3. 执行升级 match module.upgrade(target_version, upgrade_data) { Ok(_) => println!("Success!"), Err(e) => { // 4. 失败时自动回滚 module.rollback(snapshot)?; return Err(e); } } // 5. 验证状态 module.validate_state()?; ``` ### 3. 快照管理 ```rust // 定期清理旧快照，保留最近N个 manager.cleanup_old_snapshots("nac-nvm", 10); ``` ### 4. 治理流程 ```rust // 1. 提交提案 let proposal_id = governance.propose_upgrade(proposal)?; // 2. 投票 governance.vote(proposal_id.clone(), Vote::Yes)?; // 3. 检查投票结果 let result = governance.get_vote_result(&proposal_id)?; if config.validate_result(&result) { // 4. 执行升级 governance.execute_upgrade(proposal_id)?; } ``` ## 🤝 贡献指南 1. Fork本项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启Pull Request ## 📄 许可证 MIT License ## 👥 维护者 NAC Development Team ## 📞 联系方式 - 项目主页: https://git.newassetchain.io/nacadmin/NAC_Blockchain - Issue追踪: https://git.newassetchain.io/nacadmin/NAC_Blockchain/issues ## 🎉 致谢感谢所有为NAC公链升级机制做出贡献的开发者！