# 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