406 lines
9.0 KiB
Markdown
406 lines
9.0 KiB
Markdown
# 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<UpgradeRecord>,
|
||
}
|
||
```
|
||
|
||
### 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公链升级机制做出贡献的开发者！
|