NAC_Blockchain/nac-cee/README.md

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 共识引擎集成

使用示例

验证交易

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

验证区块

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

创建和执行规则

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

使用规则缓存

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

性能指标

• 单笔交易验证延迟: < 10ms
• 批量验证TPS: > 1000
• 规则缓存命中率: > 90%
• 并行验证支持: 是

配置

[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

测试

运行所有测试：

cargo test

运行特定模块测试：

cargo test engine::
cargo test validator::
cargo test receipt::

测试覆盖率

• 规则引擎: 38个测试
• 验证系统: 20个测试
• 收据系统: 8个测试
• 主引擎: 3个测试
• 总计: 64个测试，100%通过

依赖

• nac-udm: NAC统一数据模型
• serde: 序列化/反序列化
• serde_json: JSON支持
• thiserror: 错误处理

错误处理

pub enum CeeError {
    ClauseNotFound(u64),
    ValidationFailed(String),
    RuleParseError(String),
    ExecutionError(String),
    StorageError(String),
    IntegrationError(String),
}

安全考虑

• 规则执行超时保护（1秒）
• 递归深度限制（100层）
• 内存使用限制（100MB）
• 权限控制和签名验证
• 收据不可篡改

未来扩展

• 智能合约集成
• 跨链验证支持
• AI辅助验证
• 性能优化

许可证

Copyright © 2024 NAC Foundation