1127 lines
27 KiB
Markdown
1127 lines
27 KiB
Markdown
# nac-cbpp 模块深度分析报告
|
||
|
||
**模块名称**: nac-cbpp
|
||
**版本**: 1.0.0
|
||
**分析日期**: 2026-02-18
|
||
**分析人员**: NAC开发团队
|
||
|
||
---
|
||
|
||
## 📋 模块概览
|
||
|
||
**功能定位**: 宪政区块生产协议（CBPP）- NAC公链核心共识机制
|
||
**英文全称**: Constitutional Block Production Protocol
|
||
**代码行数**: 766行
|
||
**完成度**: 65%
|
||
**测试覆盖**: 100% (15个测试全部通过)
|
||
**编译状态**: ✅ 通过
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 核心理念
|
||
|
||
CBPP是NAC公链的核心共识机制，结合了**DPoS（委托权益证明）**和**BFT（拜占庭容错）**的优点，实现了高性能、高安全性和宪法治理的统一。
|
||
|
||
### 技术特点
|
||
|
||
1. **两阶段投票**: Prevote（预投票）→ Precommit（预提交）
|
||
2. **2/3+多数机制**: 需要超过2/3的投票权才能达成共识
|
||
3. **轮次机制**: 支持多轮共识，确保活性
|
||
4. **锁定机制**: 防止双签和分叉
|
||
5. **验证者集合**: 动态管理验证者和投票权
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
nac-cbpp/
|
||
├── Cargo.toml
|
||
├── README.md
|
||
└── src/
|
||
├── lib.rs (24行) - 模块导出
|
||
├── block.rs (215行) - 区块结构
|
||
├── validator.rs (161行) - 验证者管理
|
||
├── vote.rs (122行) - 投票机制
|
||
└── consensus.rs (244行) - 共识引擎
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 依赖关系
|
||
|
||
```toml
|
||
[dependencies]
|
||
tokio = { version = "1.0", features = ["full"] } # 异步运行时
|
||
serde = { version = "1.0", features = ["derive"] } # 序列化
|
||
serde_json = "1.0" # JSON序列化
|
||
sha3 = "0.10" # SHA3哈希
|
||
hex = "0.4" # 十六进制编码
|
||
chrono = { version = "0.4", features = ["serde"] } # 时间处理
|
||
anyhow = "1.0" # 错误处理
|
||
thiserror = "1.0" # 错误定义
|
||
rand = "0.8" # 随机数
|
||
```
|
||
|
||
**关键依赖**:
|
||
- **sha3**: NAC公链统一使用SHA3-384哈希算法
|
||
- **tokio**: 异步共识引擎的基础
|
||
- **chrono**: 区块时间戳和投票时间戳
|
||
|
||
---
|
||
|
||
## 🔍 核心功能详解
|
||
|
||
### 1. 区块结构 (block.rs - 215行)
|
||
|
||
#### 1.1 区块头 (BlockHeader)
|
||
|
||
```rust
|
||
pub struct BlockHeader {
|
||
pub version: u32, // 区块版本
|
||
pub height: u64, // 区块高度
|
||
pub timestamp: DateTime<Utc>, // 时间戳
|
||
pub prev_hash: String, // 前一区块哈希
|
||
pub merkle_root: String, // Merkle根
|
||
pub state_root: String, // 状态根
|
||
pub validator: String, // 验证者地址
|
||
pub signature: String, // 验证者签名
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 说明 | 用途 |
|
||
|------|------|------|------|
|
||
| `version` | u32 | 区块版本 | 协议升级兼容性 |
|
||
| `height` | u64 | 区块高度 | 区块链长度标识 |
|
||
| `timestamp` | DateTime<Utc> | UTC时间戳 | 时间排序和验证 |
|
||
| `prev_hash` | String | 前一区块哈希 | 链式结构 |
|
||
| `merkle_root` | String | 交易Merkle根 | 交易完整性验证 |
|
||
| `state_root` | String | 状态树根 | 状态完整性验证 |
|
||
| `validator` | String | 出块验证者 | 责任追溯 |
|
||
| `signature` | String | 验证者签名 | 身份验证 |
|
||
|
||
**哈希计算**:
|
||
```rust
|
||
pub fn hash(&self) -> String {
|
||
let data = format!(
|
||
"{}{}{}{}{}{}{}",
|
||
self.version,
|
||
self.height,
|
||
self.timestamp.timestamp(),
|
||
self.prev_hash,
|
||
self.merkle_root,
|
||
self.state_root,
|
||
self.validator
|
||
);
|
||
|
||
let hash = Sha3_384::digest(data.as_bytes());
|
||
hex::encode(hash) // 96个十六进制字符（48字节）
|
||
}
|
||
```
|
||
|
||
**设计亮点**:
|
||
- 使用SHA3-384（而非SHA256），符合NAC技术规范
|
||
- 签名不参与哈希计算（标准做法）
|
||
- 时间戳使用UTC避免时区问题
|
||
|
||
---
|
||
|
||
#### 1.2 交易结构 (Transaction)
|
||
|
||
```rust
|
||
pub struct Transaction {
|
||
pub from: String, // 发送方地址
|
||
pub to: String, // 接收方地址
|
||
pub amount: u64, // 转账金额
|
||
pub nonce: u64, // 交易序号
|
||
pub signature: String, // 交易签名
|
||
}
|
||
```
|
||
|
||
**交易哈希**:
|
||
```rust
|
||
pub fn hash(&self) -> String {
|
||
let data = format!(
|
||
"{}{}{}{}",
|
||
self.from, self.to, self.amount, self.nonce
|
||
);
|
||
let hash = Sha3_384::digest(data.as_bytes());
|
||
hex::encode(hash)
|
||
}
|
||
```
|
||
|
||
**问题**: 当前交易结构过于简化，缺少：
|
||
- Gas费用字段
|
||
- 合约调用数据
|
||
- 交易类型（转账/合约调用/合约部署）
|
||
- 时间戳
|
||
|
||
---
|
||
|
||
#### 1.3 区块体 (BlockBody)
|
||
|
||
```rust
|
||
pub struct BlockBody {
|
||
pub transactions: Vec<Transaction>,
|
||
}
|
||
```
|
||
|
||
**Merkle树计算**:
|
||
```rust
|
||
pub fn calculate_merkle_root(&self) -> String {
|
||
if self.transactions.is_empty() {
|
||
return String::from("0000...0000"); // 空区块
|
||
}
|
||
|
||
// 1. 计算所有交易哈希
|
||
let mut hashes: Vec<String> = self.transactions
|
||
.iter()
|
||
.map(|tx| tx.hash())
|
||
.collect();
|
||
|
||
// 2. 两两组合，递归计算
|
||
while hashes.len() > 1 {
|
||
let mut new_hashes = Vec::new();
|
||
|
||
for chunk in hashes.chunks(2) {
|
||
let combined = if chunk.len() == 2 {
|
||
format!("{}{}", chunk[0], chunk[1])
|
||
} else {
|
||
// 奇数个节点，复制最后一个
|
||
format!("{}{}", chunk[0], chunk[0])
|
||
};
|
||
|
||
let hash = Sha3_384::digest(combined.as_bytes());
|
||
new_hashes.push(hex::encode(hash));
|
||
}
|
||
|
||
hashes = new_hashes;
|
||
}
|
||
|
||
hashes[0].clone()
|
||
}
|
||
```
|
||
|
||
**算法分析**:
|
||
- **时间复杂度**: O(n)，其中n是交易数量
|
||
- **空间复杂度**: O(n)
|
||
- **特殊处理**: 奇数个节点时复制最后一个（标准Merkle树做法）
|
||
|
||
---
|
||
|
||
#### 1.4 完整区块 (Block)
|
||
|
||
```rust
|
||
pub struct Block {
|
||
pub header: BlockHeader,
|
||
pub body: BlockBody,
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
|
||
| 方法 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `new` | 创建新区块 | height, prev_hash, validator | Self |
|
||
| `add_transaction` | 添加交易 | tx | - |
|
||
| `finalize` | 完成区块（计算Merkle根） | - | - |
|
||
| `hash` | 获取区块哈希 | - | String |
|
||
| `height` | 获取区块高度 | - | u64 |
|
||
|
||
**使用流程**:
|
||
```rust
|
||
// 1. 创建区块
|
||
let mut block = Block::new(1, "genesis".to_string(), "validator1".to_string());
|
||
|
||
// 2. 添加交易
|
||
block.add_transaction(Transaction::new(...));
|
||
block.add_transaction(Transaction::new(...));
|
||
|
||
// 3. 完成区块
|
||
block.finalize(); // 计算Merkle根
|
||
|
||
// 4. 获取哈希
|
||
let hash = block.hash();
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 验证者管理 (validator.rs - 161行)
|
||
|
||
#### 2.1 验证者信息 (Validator)
|
||
|
||
```rust
|
||
pub struct Validator {
|
||
pub address: String, // 验证者地址
|
||
pub voting_power: u64, // 投票权（等于质押量）
|
||
pub stake: u64, // 质押量
|
||
pub is_active: bool, // 是否激活
|
||
}
|
||
```
|
||
|
||
**设计说明**:
|
||
- `voting_power` = `stake`（简化实现）
|
||
- 实际应该根据声誉、表现等因素调整投票权
|
||
|
||
---
|
||
|
||
#### 2.2 验证者集合 (ValidatorSet)
|
||
|
||
```rust
|
||
pub struct ValidatorSet {
|
||
validators: HashMap<String, Validator>, // 验证者映射
|
||
total_voting_power: u64, // 总投票权
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
|
||
##### 添加验证者
|
||
```rust
|
||
pub fn add_validator(&mut self, validator: Validator) {
|
||
self.total_voting_power += validator.voting_power;
|
||
self.validators.insert(validator.address.clone(), validator);
|
||
}
|
||
```
|
||
|
||
##### 移除验证者
|
||
```rust
|
||
pub fn remove_validator(&mut self, address: &str) -> Option<Validator> {
|
||
if let Some(validator) = self.validators.remove(address) {
|
||
self.total_voting_power -= validator.voting_power;
|
||
Some(validator)
|
||
} else {
|
||
None
|
||
}
|
||
}
|
||
```
|
||
|
||
##### 更新质押
|
||
```rust
|
||
pub fn update_stake(&mut self, address: &str, new_stake: u64) -> bool {
|
||
if let Some(validator) = self.validators.get_mut(address) {
|
||
// 更新总投票权
|
||
self.total_voting_power = self.total_voting_power
|
||
.saturating_sub(validator.voting_power)
|
||
.saturating_add(new_stake);
|
||
|
||
// 更新验证者
|
||
validator.stake = new_stake;
|
||
validator.voting_power = new_stake;
|
||
true
|
||
} else {
|
||
false
|
||
}
|
||
}
|
||
```
|
||
|
||
**设计亮点**: 使用`saturating_sub`和`saturating_add`防止溢出
|
||
|
||
##### 检查法定人数
|
||
```rust
|
||
pub fn has_quorum(&self, voting_power: u64) -> bool {
|
||
voting_power * 3 > self.total_voting_power * 2
|
||
}
|
||
```
|
||
|
||
**公式**: `voting_power > 2/3 * total_voting_power`
|
||
|
||
**示例**:
|
||
- 总投票权: 3000
|
||
- 需要投票权: > 2000（即2001及以上）
|
||
|
||
---
|
||
|
||
### 3. 投票机制 (vote.rs - 122行)
|
||
|
||
#### 3.1 投票类型 (VoteType)
|
||
|
||
```rust
|
||
pub enum VoteType {
|
||
Prevote, // 预投票
|
||
Precommit, // 预提交
|
||
}
|
||
```
|
||
|
||
**两阶段投票**:
|
||
1. **Prevote（预投票）**: 验证者对提议的区块进行初步投票
|
||
2. **Precommit（预提交）**: 在Prevote达成多数后，验证者进行最终投票
|
||
|
||
**作用**: 防止分叉和双签
|
||
|
||
---
|
||
|
||
#### 3.2 投票 (Vote)
|
||
|
||
```rust
|
||
pub struct Vote {
|
||
pub vote_type: VoteType, // 投票类型
|
||
pub height: u64, // 投票高度
|
||
pub round: u32, // 投票轮次
|
||
pub block_hash: String, // 投票的区块哈希
|
||
pub validator: String, // 投票者地址
|
||
pub timestamp: DateTime<Utc>, // 投票时间
|
||
pub signature: String, // 投票签名
|
||
}
|
||
```
|
||
|
||
**便捷构造方法**:
|
||
```rust
|
||
// 创建预投票
|
||
Vote::prevote(height, round, block_hash, validator);
|
||
|
||
// 创建预提交
|
||
Vote::precommit(height, round, block_hash, validator);
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.3 投票集合 (VoteSet)
|
||
|
||
```rust
|
||
pub struct VoteSet {
|
||
votes: Vec<Vote>, // 投票列表
|
||
total_voting_power: u64, // 总投票权
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
|
||
| 方法 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `new` | 创建投票集合 | total_voting_power | Self |
|
||
| `add_vote` | 添加投票 | vote | - |
|
||
| `len` | 获取投票数量 | - | usize |
|
||
| `has_two_thirds_majority` | 检查是否达到2/3+多数 | voting_power | bool |
|
||
|
||
**问题**: 当前实现没有验证：
|
||
- 同一验证者是否重复投票
|
||
- 投票签名是否有效
|
||
- 投票是否针对同一区块
|
||
|
||
---
|
||
|
||
### 4. 共识引擎 (consensus.rs - 244行)
|
||
|
||
#### 4.1 共识状态 (ConsensusState)
|
||
|
||
```rust
|
||
pub enum ConsensusState {
|
||
NewHeight, // 新高度（初始状态）
|
||
Propose, // 提议阶段
|
||
Prevote, // 预投票阶段
|
||
Precommit, // 预提交阶段
|
||
Commit, // 提交阶段
|
||
}
|
||
```
|
||
|
||
**状态转换图**:
|
||
```
|
||
NewHeight → Propose → Prevote → Precommit → Commit
|
||
↑ ↓
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
#### 4.2 共识引擎 (ConsensusEngine)
|
||
|
||
```rust
|
||
pub struct ConsensusEngine {
|
||
state: ConsensusState, // 当前状态
|
||
height: u64, // 当前高度
|
||
round: u32, // 当前轮次
|
||
validator_set: ValidatorSet, // 验证者集合
|
||
prevotes: HashMap<String, VoteSet>, // 预投票集合（按区块哈希分组）
|
||
precommits: HashMap<String, VoteSet>, // 预提交集合（按区块哈希分组）
|
||
locked_block: Option<Block>, // 锁定的区块
|
||
locked_round: Option<u32>, // 锁定的轮次
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `state` | ConsensusState | 当前共识状态 |
|
||
| `height` | u64 | 当前区块高度 |
|
||
| `round` | u32 | 当前共识轮次（同一高度可能多轮） |
|
||
| `validator_set` | ValidatorSet | 当前验证者集合 |
|
||
| `prevotes` | HashMap<String, VoteSet> | 预投票集合（key=区块哈希） |
|
||
| `precommits` | HashMap<String, VoteSet> | 预提交集合（key=区块哈希） |
|
||
| `locked_block` | Option<Block> | 锁定的区块（防止切换） |
|
||
| `locked_round` | Option<u32> | 锁定的轮次 |
|
||
|
||
---
|
||
|
||
#### 4.3 核心流程
|
||
|
||
##### 开始新高度
|
||
```rust
|
||
pub fn start_new_height(&mut self, height: u64) {
|
||
self.height = height;
|
||
self.round = 0;
|
||
self.state = ConsensusState::NewHeight;
|
||
self.prevotes.clear();
|
||
self.precommits.clear();
|
||
self.locked_block = None;
|
||
self.locked_round = None;
|
||
}
|
||
```
|
||
|
||
**作用**: 清空上一高度的所有状态，开始新一轮共识
|
||
|
||
---
|
||
|
||
##### 处理提议
|
||
```rust
|
||
pub fn handle_proposal(&mut self, block: Block) -> bool {
|
||
// 1. 检查状态
|
||
if self.state != ConsensusState::Propose {
|
||
return false;
|
||
}
|
||
|
||
// 2. 验证区块
|
||
if !self.validate_block(&block) {
|
||
return false;
|
||
}
|
||
|
||
// 3. 进入预投票阶段
|
||
self.state = ConsensusState::Prevote;
|
||
true
|
||
}
|
||
```
|
||
|
||
**问题**: `validate_block`是空实现，应该验证：
|
||
1. 区块签名
|
||
2. 交易有效性
|
||
3. 状态转换
|
||
4. Merkle根
|
||
|
||
---
|
||
|
||
##### 处理预投票
|
||
```rust
|
||
pub fn handle_prevote(&mut self, vote: Vote) -> bool {
|
||
// 1. 检查投票类型
|
||
if vote.vote_type != VoteType::Prevote {
|
||
return false;
|
||
}
|
||
|
||
// 2. 添加到对应区块的投票集合
|
||
let vote_set = self.prevotes
|
||
.entry(vote.block_hash.clone())
|
||
.or_insert_with(|| VoteSet::new(self.validator_set.total_voting_power()));
|
||
|
||
vote_set.add_vote(vote);
|
||
|
||
// 3. 检查是否达到2/3+多数
|
||
if self.check_prevote_majority() {
|
||
self.state = ConsensusState::Precommit;
|
||
return true;
|
||
}
|
||
|
||
false
|
||
}
|
||
```
|
||
|
||
**问题**: `check_prevote_majority`使用简化计算：
|
||
```rust
|
||
let voting_power = vote_set.len() as u64 * 1000; // 假设每个验证者1000投票权
|
||
```
|
||
|
||
**应该改为**:
|
||
```rust
|
||
// 根据实际验证者的投票权计算
|
||
let voting_power = votes.iter()
|
||
.map(|vote| validator_set.get_validator(&vote.validator).unwrap().voting_power)
|
||
.sum();
|
||
```
|
||
|
||
---
|
||
|
||
##### 处理预提交
|
||
```rust
|
||
pub fn handle_precommit(&mut self, vote: Vote) -> bool {
|
||
// 类似handle_prevote
|
||
// ...
|
||
|
||
if self.check_precommit_majority() {
|
||
self.state = ConsensusState::Commit;
|
||
return true;
|
||
}
|
||
|
||
false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
##### 提交区块
|
||
```rust
|
||
pub fn commit_block(&mut self) -> Option<Block> {
|
||
// 1. 检查状态
|
||
if self.state != ConsensusState::Commit {
|
||
return None;
|
||
}
|
||
|
||
// 2. 取出锁定的区块
|
||
let block = self.locked_block.take();
|
||
|
||
// 3. 进入新高度
|
||
self.start_new_height(self.height + 1);
|
||
|
||
block
|
||
}
|
||
```
|
||
|
||
**问题**: 没有实际保存区块到链上，只是返回区块对象
|
||
|
||
---
|
||
|
||
## 🧪 测试覆盖
|
||
|
||
### 测试统计
|
||
|
||
| 模块 | 测试数量 | 测试状态 |
|
||
|------|---------|---------|
|
||
| lib.rs | 1 | ✅ 通过 |
|
||
| block.rs | 4 | ✅ 通过 |
|
||
| validator.rs | 4 | ✅ 通过 |
|
||
| vote.rs | 3 | ✅ 通过 |
|
||
| consensus.rs | 3 | ✅ 通过 |
|
||
| **总计** | **15** | **✅ 全部通过** |
|
||
|
||
### 测试详情
|
||
|
||
#### block.rs 测试
|
||
```rust
|
||
#[test]
|
||
fn test_block_creation() // 区块创建
|
||
fn test_transaction_hash() // 交易哈希（验证SHA3-384输出96字符）
|
||
fn test_merkle_root() // Merkle根计算
|
||
fn test_block_finalize() // 区块完成
|
||
```
|
||
|
||
#### validator.rs 测试
|
||
```rust
|
||
#[test]
|
||
fn test_validator_creation() // 验证者创建
|
||
fn test_validator_set() // 验证者集合
|
||
fn test_quorum() // 法定人数（2/3+）
|
||
fn test_update_stake() // 更新质押
|
||
```
|
||
|
||
#### vote.rs 测试
|
||
```rust
|
||
#[test]
|
||
fn test_vote_creation() // 投票创建
|
||
fn test_vote_set() // 投票集合
|
||
fn test_two_thirds_majority() // 2/3+多数
|
||
```
|
||
|
||
#### consensus.rs 测试
|
||
```rust
|
||
#[test]
|
||
fn test_consensus_engine_creation() // 引擎创建
|
||
fn test_start_new_height() // 开始新高度
|
||
fn test_consensus_flow() // 共识流程
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 发现的问题
|
||
|
||
### 问题1: 交易结构过于简化
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 当前交易结构缺少关键字段
|
||
|
||
**缺失字段**:
|
||
- Gas费用（gas_price, gas_limit）
|
||
- 合约调用数据（data）
|
||
- 交易类型（transfer/contract_call/contract_deploy）
|
||
- 时间戳
|
||
|
||
**建议**:
|
||
```rust
|
||
pub struct Transaction {
|
||
pub from: String,
|
||
pub to: String,
|
||
pub amount: u64,
|
||
pub nonce: u64,
|
||
pub gas_price: u64, // 新增
|
||
pub gas_limit: u64, // 新增
|
||
pub data: Vec<u8>, // 新增
|
||
pub tx_type: TxType, // 新增
|
||
pub timestamp: u64, // 新增
|
||
pub signature: String,
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题2: 区块验证未实现
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: `validate_block`是空实现，直接返回true
|
||
|
||
**影响**:
|
||
- 无法验证区块签名
|
||
- 无法验证交易有效性
|
||
- 无法验证状态转换
|
||
|
||
**建议**:
|
||
```rust
|
||
fn validate_block(&self, block: &Block) -> bool {
|
||
// 1. 验证区块签名
|
||
if !self.verify_block_signature(block) {
|
||
return false;
|
||
}
|
||
|
||
// 2. 验证Merkle根
|
||
if block.header.merkle_root != block.body.calculate_merkle_root() {
|
||
return false;
|
||
}
|
||
|
||
// 3. 验证所有交易
|
||
for tx in &block.body.transactions {
|
||
if !self.validate_transaction(tx) {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 4. 验证状态转换
|
||
if !self.verify_state_transition(block) {
|
||
return false;
|
||
}
|
||
|
||
true
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题3: 投票权计算简化
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: `check_prevote_majority`和`check_precommit_majority`使用简化计算
|
||
|
||
**当前实现**:
|
||
```rust
|
||
let voting_power = vote_set.len() as u64 * 1000; // 假设每个验证者1000投票权
|
||
```
|
||
|
||
**问题**: 忽略了验证者的实际投票权差异
|
||
|
||
**建议**:
|
||
```rust
|
||
fn calculate_voting_power(&self, votes: &[Vote]) -> u64 {
|
||
votes.iter()
|
||
.filter_map(|vote| self.validator_set.get_validator(&vote.validator))
|
||
.map(|validator| validator.voting_power)
|
||
.sum()
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待修复
|
||
|
||
---
|
||
|
||
### 问题4: 缺少重复投票检测
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: `VoteSet`没有检测同一验证者是否重复投票
|
||
|
||
**影响**: 验证者可以多次投票，破坏2/3+机制
|
||
|
||
**建议**:
|
||
```rust
|
||
pub struct VoteSet {
|
||
votes: Vec<Vote>,
|
||
voted_validators: HashSet<String>, // 新增：已投票的验证者
|
||
total_voting_power: u64,
|
||
}
|
||
|
||
pub fn add_vote(&mut self, vote: Vote) -> Result<(), VoteError> {
|
||
// 检查是否重复投票
|
||
if self.voted_validators.contains(&vote.validator) {
|
||
return Err(VoteError::DuplicateVote);
|
||
}
|
||
|
||
self.voted_validators.insert(vote.validator.clone());
|
||
self.votes.push(vote);
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题5: 缺少超时机制
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 没有超时机制，如果某个阶段无法达成共识，系统会卡住
|
||
|
||
**影响**: 活性问题，系统可能停止出块
|
||
|
||
**建议**:
|
||
```rust
|
||
pub struct ConsensusEngine {
|
||
// ...
|
||
propose_timeout: Duration,
|
||
prevote_timeout: Duration,
|
||
precommit_timeout: Duration,
|
||
}
|
||
|
||
pub async fn run_consensus(&mut self) {
|
||
loop {
|
||
match self.state {
|
||
ConsensusState::Propose => {
|
||
tokio::select! {
|
||
_ = tokio::time::sleep(self.propose_timeout) => {
|
||
// 超时，进入下一轮
|
||
self.round += 1;
|
||
self.enter_propose();
|
||
}
|
||
// 处理提议
|
||
}
|
||
}
|
||
// 其他状态类似
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题6: 缺少轮次切换机制
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: 定义了`round`字段，但没有实现轮次切换逻辑
|
||
|
||
**影响**: 如果第0轮无法达成共识，无法进入第1轮
|
||
|
||
**建议**:
|
||
```rust
|
||
pub fn start_new_round(&mut self, round: u32) {
|
||
self.round = round;
|
||
self.state = ConsensusState::Propose;
|
||
self.prevotes.clear();
|
||
self.precommits.clear();
|
||
// locked_block和locked_round保持不变
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题7: 缺少提议者选择算法
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 没有实现提议者选择算法
|
||
|
||
**建议**:
|
||
```rust
|
||
pub fn select_proposer(&self) -> Option<&Validator> {
|
||
// 方案1: 轮流出块（Round-Robin）
|
||
let index = (self.height + self.round as u64) as usize % self.validator_set.len();
|
||
self.validator_set.get_active_validators().get(index).copied()
|
||
|
||
// 方案2: 加权随机（根据投票权）
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题8: 缺少签名验证
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 区块签名和投票签名都是空字符串，没有实际签名和验证
|
||
|
||
**影响**: 无法防止伪造区块和投票
|
||
|
||
**建议**:
|
||
```rust
|
||
// 集成密码学库
|
||
use ed25519_dalek::{Keypair, Signature, Signer, Verifier};
|
||
|
||
impl BlockHeader {
|
||
pub fn sign(&mut self, keypair: &Keypair) {
|
||
let message = self.hash();
|
||
let signature = keypair.sign(message.as_bytes());
|
||
self.signature = hex::encode(signature.to_bytes());
|
||
}
|
||
|
||
pub fn verify_signature(&self, public_key: &PublicKey) -> bool {
|
||
let message = self.hash();
|
||
let signature = Signature::from_bytes(&hex::decode(&self.signature).unwrap()).unwrap();
|
||
public_key.verify(message.as_bytes(), &signature).is_ok()
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题9: 缺少状态根计算
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: `state_root`字段是空字符串，没有实际计算
|
||
|
||
**影响**: 无法验证状态转换的正确性
|
||
|
||
**建议**: 集成Merkle Patricia Trie或其他状态树实现
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题10: 缺少网络层
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 只有共识逻辑，没有网络通信
|
||
|
||
**影响**: 无法在分布式环境中运行
|
||
|
||
**建议**: 集成nac-csnp网络协议
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
## 📊 完成度评估
|
||
|
||
| 功能模块 | 代码行数 | 完成度 | 状态 |
|
||
|---------|---------|--------|------|
|
||
| 区块结构 | 215行 | 70% | ⚠️ 缺少字段和验证 |
|
||
| 验证者管理 | 161行 | 90% | ✅ 基本完成 |
|
||
| 投票机制 | 122行 | 70% | ⚠️ 缺少重复检测 |
|
||
| 共识引擎 | 244行 | 50% | ⚠️ 缺少关键功能 |
|
||
| 模块导出 | 24行 | 100% | ✅ 完成 |
|
||
| **总计** | **766行** | **65%** | **🚧 进行中** |
|
||
|
||
### 待完善功能
|
||
|
||
1. **高优先级**:
|
||
- ❌ 实现区块验证逻辑
|
||
- ❌ 实现签名和验证
|
||
- ❌ 实现提议者选择算法
|
||
- ❌ 实现超时机制
|
||
- ❌ 集成网络层
|
||
|
||
2. **中优先级**:
|
||
- ❌ 完善交易结构
|
||
- ❌ 修复投票权计算
|
||
- ❌ 实现重复投票检测
|
||
- ❌ 实现轮次切换
|
||
- ❌ 实现状态根计算
|
||
|
||
3. **低优先级**:
|
||
- ⏳ 添加更多测试
|
||
- ⏳ 性能优化
|
||
- ⏳ 添加监控指标
|
||
|
||
---
|
||
|
||
## 🌟 设计亮点
|
||
|
||
1. **两阶段投票机制**
|
||
- Prevote + Precommit确保安全性
|
||
- 2/3+多数机制防止分叉
|
||
|
||
2. **清晰的状态机**
|
||
- NewHeight → Propose → Prevote → Precommit → Commit
|
||
- 状态转换逻辑清晰
|
||
|
||
3. **完整的测试覆盖**
|
||
- 15个测试全部通过
|
||
- 覆盖核心功能
|
||
|
||
4. **SHA3-384哈希**
|
||
- 符合NAC技术规范
|
||
- 96字符输出（48字节）
|
||
|
||
5. **Merkle树实现**
|
||
- 标准算法
|
||
- 支持奇数个节点
|
||
|
||
---
|
||
|
||
## 🔗 模块依赖关系
|
||
|
||
```
|
||
nac-cbpp
|
||
├── 依赖
|
||
│ ├── tokio (异步运行时)
|
||
│ ├── sha3 (哈希算法)
|
||
│ └── chrono (时间处理)
|
||
├── 被依赖
|
||
│ ├── nac-api-server (API接口)
|
||
│ └── nac-cli (命令行工具)
|
||
└── 协作模块
|
||
├── nac-cbpp-l0 (L0层)
|
||
├── nac-cbpp-l1 (L1层)
|
||
├── nac-csnp (网络协议)
|
||
└── nac-udm (数据模型)
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发建议
|
||
|
||
### 短期目标 (1-2周)
|
||
|
||
1. **实现区块验证** (优先级P1)
|
||
- 签名验证
|
||
- Merkle根验证
|
||
- 交易验证
|
||
|
||
2. **实现提议者选择** (优先级P1)
|
||
- Round-Robin算法
|
||
- 或加权随机算法
|
||
|
||
3. **实现超时机制** (优先级P1)
|
||
- Propose超时
|
||
- Prevote超时
|
||
- Precommit超时
|
||
|
||
### 中期目标 (2-4周)
|
||
|
||
4. **完善交易结构** (优先级P2)
|
||
- 添加Gas字段
|
||
- 添加合约调用数据
|
||
- 添加交易类型
|
||
|
||
5. **集成网络层** (优先级P2)
|
||
- 使用nac-csnp
|
||
- 实现区块广播
|
||
- 实现投票广播
|
||
|
||
6. **实现签名系统** (优先级P2)
|
||
- 集成ed25519
|
||
- 区块签名
|
||
- 投票签名
|
||
|
||
### 长期目标 (1-2个月)
|
||
|
||
7. **实现状态树** (优先级P3)
|
||
- Merkle Patricia Trie
|
||
- 状态根计算
|
||
- 状态验证
|
||
|
||
8. **性能优化** (优先级P3)
|
||
- 并行验证交易
|
||
- 优化Merkle树计算
|
||
- 优化内存使用
|
||
|
||
9. **监控和指标** (优先级P4)
|
||
- 共识延迟
|
||
- 区块大小
|
||
- 验证者表现
|
||
|
||
---
|
||
|
||
## 💡 使用示例
|
||
|
||
```rust
|
||
use nac_cbpp::{ConsensusEngine, ValidatorSet, Validator, Block, Transaction, Vote};
|
||
|
||
#[tokio::main]
|
||
async fn main() {
|
||
// 1. 创建共识引擎
|
||
let mut engine = ConsensusEngine::new();
|
||
|
||
// 2. 设置验证者集合
|
||
let mut validator_set = ValidatorSet::new();
|
||
validator_set.add_validator(Validator::new("v1".to_string(), 1000));
|
||
validator_set.add_validator(Validator::new("v2".to_string(), 2000));
|
||
validator_set.add_validator(Validator::new("v3".to_string(), 3000));
|
||
engine.set_validator_set(validator_set);
|
||
|
||
// 3. 开始新高度
|
||
engine.start_new_height(1);
|
||
println!("状态: {:?}", engine.state()); // NewHeight
|
||
|
||
// 4. 进入提议阶段
|
||
engine.enter_propose();
|
||
println!("状态: {:?}", engine.state()); // Propose
|
||
|
||
// 5. 创建并处理提议
|
||
let mut block = Block::new(1, "genesis".to_string(), "v1".to_string());
|
||
block.add_transaction(Transaction::new(
|
||
"alice".to_string(),
|
||
"bob".to_string(),
|
||
100,
|
||
1
|
||
));
|
||
block.finalize();
|
||
|
||
engine.handle_proposal(block);
|
||
println!("状态: {:?}", engine.state()); // Prevote
|
||
|
||
// 6. 处理预投票
|
||
engine.handle_prevote(Vote::prevote(1, 0, "block_hash".to_string(), "v1".to_string()));
|
||
engine.handle_prevote(Vote::prevote(1, 0, "block_hash".to_string(), "v2".to_string()));
|
||
engine.handle_prevote(Vote::prevote(1, 0, "block_hash".to_string(), "v3".to_string()));
|
||
println!("状态: {:?}", engine.state()); // Precommit
|
||
|
||
// 7. 处理预提交
|
||
engine.handle_precommit(Vote::precommit(1, 0, "block_hash".to_string(), "v1".to_string()));
|
||
engine.handle_precommit(Vote::precommit(1, 0, "block_hash".to_string(), "v2".to_string()));
|
||
engine.handle_precommit(Vote::precommit(1, 0, "block_hash".to_string(), "v3".to_string()));
|
||
println!("状态: {:?}", engine.state()); // Commit
|
||
|
||
// 8. 提交区块
|
||
if let Some(committed_block) = engine.commit_block() {
|
||
println!("区块已提交: 高度={}", committed_block.height());
|
||
println!("状态: {:?}", engine.state()); // NewHeight (高度2)
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 与CBPP白皮书的对应关系
|
||
|
||
### 白皮书核心概念
|
||
|
||
| 白皮书概念 | 代码实现 | 位置 |
|
||
|-----------|---------|------|
|
||
| 两阶段投票 | Prevote + Precommit | vote.rs:7-11 |
|
||
| 2/3+多数 | `has_quorum()`, `has_two_thirds_majority()` | validator.rs:101, vote.rs:86 |
|
||
| 验证者集合 | `ValidatorSet` | validator.rs:27-104 |
|
||
| 区块提议 | `handle_proposal()` | consensus.rs:72-85 |
|
||
| 锁定机制 | `locked_block`, `locked_round` | consensus.rs:28-29 |
|
||
| 轮次机制 | `round` | consensus.rs:24 |
|
||
| 状态机 | `ConsensusState` | consensus.rs:10-17 |
|
||
|
||
---
|
||
|
||
**分析完成时间**: 2026-02-18
|
||
**下一步**: 实现缺失的核心功能（区块验证、签名、超时机制等）
|