224 lines
4.7 KiB
Markdown
224 lines
4.7 KiB
Markdown
# NAC宪法执行引擎 (CEE)
|
||
|
||
Constitutional Execution Engine for NAC Blockchain
|
||
|
||
## 概述
|
||
|
||
宪法执行引擎（Constitutional Execution Engine, CEE）是NAC公链宪法系统的核心组件，负责执行宪法规则、验证交易和区块的合宪性，并生成执行收据。
|
||
|
||
## 核心功能
|
||
|
||
### 1. 规则引擎
|
||
|
||
- **规则解析器** (`RuleParser`): 解析宪法条款为可执行规则
|
||
- **规则执行器** (`RuleExecutor`): 执行规则并返回结果
|
||
- **规则缓存** (`RuleCache`): LRU缓存提高性能
|
||
|
||
### 2. 验证系统
|
||
|
||
- **交易验证器** (`TransactionValidator`): 验证交易合宪性
|
||
- **区块验证器** (`BlockValidator`): 验证区块合宪性
|
||
- **状态验证器** (`StateValidator`): 验证状态变更合宪性
|
||
- **升级验证器** (`UpgradeValidator`): 验证升级提案合宪性
|
||
|
||
### 3. 收据系统
|
||
|
||
- **收据生成器** (`ReceiptGenerator`): 生成执行收据
|
||
- **收据存储** (`ReceiptStorage`): 存储和查询收据
|
||
|
||
### 4. 集成模块
|
||
|
||
- 与 `nac-constitution-state` 集成
|
||
- 与 `nac-constitution-clauses` 集成
|
||
- 与 `nac-constitution-macros` 集成
|
||
- 与 CBPP 共识引擎集成
|
||
|
||
## 使用示例
|
||
|
||
### 验证交易
|
||
|
||
```rust
|
||
use nac_cee::{ConstitutionalExecutionEngine, Transaction, Rule};
|
||
|
||
let mut engine = ConstitutionalExecutionEngine::new();
|
||
|
||
let tx = Transaction {
|
||
hash: Hash::zero(),
|
||
from: Address::new([1u8; 32]),
|
||
to: Address::new([2u8; 32]),
|
||
amount: 1000,
|
||
nonce: 1,
|
||
timestamp: 1000000,
|
||
data: vec![],
|
||
};
|
||
|
||
let rules = vec![]; // 加载宪法规则
|
||
let receipt = engine.validate_transaction(&tx, &rules)?;
|
||
|
||
if receipt.validation_result.passed {
|
||
println!("交易验证通过");
|
||
} else {
|
||
println!("交易验证失败: {:?}", receipt.validation_result.violated_clauses);
|
||
}
|
||
```
|
||
|
||
### 验证区块
|
||
|
||
```rust
|
||
use nac_cee::{ConstitutionalExecutionEngine, Block};
|
||
|
||
let mut engine = ConstitutionalExecutionEngine::new();
|
||
|
||
let block = Block {
|
||
hash: Hash::zero(),
|
||
parent_hash: Hash::zero(),
|
||
number: 1,
|
||
timestamp: 1000000,
|
||
proposer: Address::zero(),
|
||
transactions: vec![],
|
||
state_root: Hash::zero(),
|
||
};
|
||
|
||
let rules = vec![]; // 加载宪法规则
|
||
let receipt = engine.validate_block(&block, &rules)?;
|
||
```
|
||
|
||
### 创建和执行规则
|
||
|
||
```rust
|
||
use nac_cee::{Rule, RuleType, Condition, Operator, Value, Action, RuleExecutor};
|
||
use std::collections::HashMap;
|
||
|
||
// 创建规则
|
||
let mut rule = Rule::new(
|
||
1,
|
||
100,
|
||
RuleType::Transaction,
|
||
"金额限制规则".to_string(),
|
||
"限制单笔交易金额不超过10000".to_string(),
|
||
);
|
||
|
||
rule.add_condition(Condition::new(
|
||
"amount".to_string(),
|
||
Operator::LessThanOrEqual,
|
||
Value::UnsignedInteger(10000),
|
||
));
|
||
|
||
rule.add_action(Action::Allow);
|
||
|
||
// 执行规则
|
||
let mut executor = RuleExecutor::new();
|
||
let mut context = HashMap::new();
|
||
context.insert("amount".to_string(), Value::UnsignedInteger(5000));
|
||
|
||
let result = executor.execute(&rule, &context)?;
|
||
println!("规则执行结果: {:?}", result);
|
||
```
|
||
|
||
### 使用规则缓存
|
||
|
||
```rust
|
||
use nac_cee::{RuleCache, Rule};
|
||
|
||
let mut cache = RuleCache::new(1000, 3600); // 最大1000条，TTL 1小时
|
||
|
||
// 插入规则
|
||
cache.insert(rule);
|
||
|
||
// 获取规则
|
||
if let Some(cached_rule) = cache.get(rule_id) {
|
||
println!("缓存命中");
|
||
}
|
||
|
||
// 查看缓存统计
|
||
let stats = cache.stats();
|
||
println!("缓存命中率: {:.2}%", stats.hit_rate * 100.0);
|
||
```
|
||
|
||
## 架构设计
|
||
|
||
详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
||
|
||
## 性能指标
|
||
|
||
- 单笔交易验证延迟: < 10ms
|
||
- 批量验证TPS: > 1000
|
||
- 规则缓存命中率: > 90%
|
||
- 并行验证支持: 是
|
||
|
||
## 配置
|
||
|
||
```toml
|
||
[cee]
|
||
rule_cache_size = 1000
|
||
rule_cache_ttl = 3600
|
||
max_parallel_validations = 8
|
||
batch_size = 100
|
||
execution_timeout = 1000
|
||
max_recursion_depth = 100
|
||
max_memory_usage = 104857600
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行所有测试：
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
运行特定模块测试：
|
||
|
||
```bash
|
||
cargo test engine::
|
||
cargo test validator::
|
||
cargo test receipt::
|
||
```
|
||
|
||
## 测试覆盖率
|
||
|
||
- **规则引擎**: 38个测试
|
||
- **验证系统**: 20个测试
|
||
- **收据系统**: 8个测试
|
||
- **主引擎**: 3个测试
|
||
- **总计**: 64个测试，100%通过
|
||
|
||
## 依赖
|
||
|
||
- `nac-udm`: NAC统一数据模型
|
||
- `serde`: 序列化/反序列化
|
||
- `serde_json`: JSON支持
|
||
- `thiserror`: 错误处理
|
||
|
||
## 错误处理
|
||
|
||
```rust
|
||
pub enum CeeError {
|
||
ClauseNotFound(u64),
|
||
ValidationFailed(String),
|
||
RuleParseError(String),
|
||
ExecutionError(String),
|
||
StorageError(String),
|
||
IntegrationError(String),
|
||
}
|
||
```
|
||
|
||
## 安全考虑
|
||
|
||
- 规则执行超时保护（1秒）
|
||
- 递归深度限制（100层）
|
||
- 内存使用限制（100MB）
|
||
- 权限控制和签名验证
|
||
- 收据不可篡改
|
||
|
||
## 未来扩展
|
||
|
||
- 智能合约集成
|
||
- 跨链验证支持
|
||
- AI辅助验证
|
||
- 性能优化
|
||
|
||
## 许可证
|
||
|
||
Copyright © 2024 NAC Foundation
|