9.0 KiB

Raw Permalink Blame History

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 中添加：

[dependencies]
nac-upgrade-framework = { path = "../nac-upgrade-framework" }

2. 为结构体添加升级字段

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<UpgradeRecord>,
}

3. 实现升级逻辑

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

nac_upgrade_framework::impl_upgradeable!(MyModule, "my-module", Version::new(1, 0, 0));

5. 执行升级

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

📚 详细文档

版本管理

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

升级提案

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

快照和回滚

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中自动处理）

治理和投票

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

🧪 测试

运行所有测试：

cd nac-upgrade-framework
cargo test

运行特定模块测试：

cargo test version
cargo test proposal
cargo test snapshot
cargo test governance

运行集成测试：

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个测试，全部通过 ✅

🔧 配置选项

治理配置

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. 升级前检查

// 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. 快照管理

// 定期清理旧快照，保留最近N个
manager.cleanup_old_snapshots("nac-nvm", 10);

4. 治理流程

// 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)?;
}

🤝 贡献指南

Fork本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启Pull Request

📄 许可证

MIT License

👥 维护者

NAC Development Team

📞 联系方式

项目主页: https://git.newassetchain.io/nacadmin/NAC_Blockchain
Issue追踪: https://git.newassetchain.io/nacadmin/NAC_Blockchain/issues

🎉 致谢

感谢所有为NAC公链升级机制做出贡献的开发者！

9.0 KiB Raw Permalink Blame History Unescape Escape

NAC升级框架 (nac-upgrade-framework)

📋 目录

🎯 功能特性

1. 版本管理

2. 升级协议

3. 回滚机制

4. 升级治理

🏗️ 架构设计

🚀 快速开始

1. 添加依赖

2. 为结构体添加升级字段

3. 实现升级逻辑

4. 使用宏实现Upgradeable trait

5. 执行升级

📚 详细文档

版本管理

升级提案

快照和回滚

治理和投票

🧪 测试

📊 测试覆盖率

🔧 配置选项

治理配置

🎓 最佳实践

1. 版本规划

2. 升级前检查

3. 快照管理

4. 治理流程

🤝 贡献指南

📄 许可证

👥 维护者

📞 联系方式

🎉 致谢

9.0 KiB

Raw Permalink Blame History