19 KiB

Raw Permalink Blame History

nac-constitution-macros 模块深度分析报告

模块名称: nac-constitution-macros
版本: 0.1.0
分析日期: 2026-02-18
分析人员: NAC开发团队

📋 模块概览

功能定位: NAC宪法过程宏库 - 为NAC宪法约束提供编译时代码生成
英文全称: NAC Constitution Procedural Macros
代码行数: 470行
完成度: 50%
测试覆盖: 20% (1个基础测试)
编译状态: ✅ 通过

🏗️ 架构设计

核心功能

nac-constitution-macros是NAC公链的过程宏库，提供三个核心宏：

#[constitutional]: 属性宏，为函数添加宪法约束检查
#[clause_param]: 属性宏，为常量添加宪法条款元数据
constitutional_fn!: 函数宏，生成带宪法检查的函数

技术特点

编译时代码生成: 使用Rust过程宏在编译时生成代码
零运行时开销: 检查逻辑在编译时注入
声明式约束: 通过宏参数声明宪法约束
日志集成: 自动生成日志记录代码

目录结构

nac-constitution-macros/
├── Cargo.toml
└── src/
    ├── lib.rs (297行) - 主要宏实现
    ├── constitutional.rs (119行) - #[constitutional]实现（备用）
    └── clause_param.rs (54行) - #[clause_param]实现（备用）

📦 依赖关系

[dependencies]
syn = { version = "2.0", features = ["full"] }  # Rust语法解析
quote = "1.0"                                   # 代码生成
proc-macro2 = "1.0"                             # 过程宏基础设施

依赖分析:

syn: 解析Rust语法树（AST）
quote: 生成Rust代码（quote!宏）
proc-macro2: 过程宏的基础类型和工具

🔍 核心功能详解

1. #[constitutional] 属性宏

1.1 功能说明

#[constitutional]是一个属性宏，用于标记需要宪法约束验证的函数。

语法:

#[constitutional(clause = "条款ID", check = "检查表达式", obligation = "义务类型")]
fn function_name(args) -> Result<T, E> {
    // 函数实现
}

参数:

clause: 宪法条款ID（可选）
check: 前置条件检查表达式（可选）
obligation: 义务类型（可选）

1.2 实现原理

#[proc_macro_attribute]
pub fn constitutional(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as ConstitutionalArgs);
    let input = parse_macro_input!(item as ItemFn);

    let fn_vis = &input.vis;
    let fn_sig = &input.sig;
    let fn_block = &input.block;
    let fn_name = &input.sig.ident;

    // 生成宪法条款检查代码
    let clause_check = if let Some(clause_id) = args.clause {
        quote! {
            log::debug!("Constitutional check: clause={}", #clause_id);
        }
    } else {
        quote! {}
    };

    // 生成前置条件检查代码
    let precondition_check = if let Some(check_expr) = args.check {
        quote! {
            log::debug!("Precondition check: {}", #check_expr);
        }
    } else {
        quote! {}
    };

    // 生成义务记录代码
    let obligation_record = if let Some(obligation_type) = args.obligation {
        quote! {
            log::info!("Obligation recorded: type={}, function={}", #obligation_type, stringify!(#fn_name));
        }
    } else {
        quote! {}
    };

    // 生成最终代码
    let expanded = quote! {
        #fn_vis #fn_sig {
            #clause_check
            #precondition_check
            #obligation_record
            log::trace!("Invoking constitutional function: {}", stringify!(#fn_name));
            #fn_block
        }
    };

    TokenStream::from(expanded)
}

代码生成流程:

解析属性参数（clause、check、obligation）
解析函数定义（签名、可见性、函数体）
根据参数生成检查代码
将检查代码注入函数开头
保留原始函数体

1.3 使用示例

输入代码:

#[constitutional(clause = "XTZH_GOLD_COVERAGE", check = "coverage >= 1.25")]
fn mint_xtzh(amount: u64, coverage: f64) -> Result<(), Error> {
    // 铸造XTZH稳定币
    Ok(())
}

生成代码:

fn mint_xtzh(amount: u64, coverage: f64) -> Result<(), Error> {
    // 宪法条款检查
    log::debug!("Constitutional check: clause={}", "XTZH_GOLD_COVERAGE");
    
    // 前置条件检查
    log::debug!("Precondition check: {}", "coverage >= 1.25");
    
    // 记录函数调用
    log::trace!("Invoking constitutional function: {}", "mint_xtzh");
    
    // 原始函数体
    {
        // 铸造XTZH稳定币
        Ok(())
    }
}

1.4 问题分析

问题1: 只记录日志，没有实际验证

当前实现只是记录日志，并不真正验证宪法约束。

应该实现:

let precondition_check = if let Some(check_expr) = args.check {
    quote! {
        // 解析并评估检查表达式
        if !(#check_expr) {
            return Err(ConstitutionalError::ConstraintViolation {
                clause: #clause_id,
                check: #check_expr,
            }.into());
        }
    }
} else {
    quote! {}
};

问题2: check参数是字符串，无法编译时验证

当前实现将check表达式作为字符串传递，无法在编译时验证语法。

应该改进:

使用syn::Expr解析表达式
在编译时验证表达式语法
生成类型安全的检查代码

2. #[clause_param] 属性宏

2.1 功能说明

#[clause_param]是一个属性宏，用于标记宪法参数常量。

语法:

#[clause_param(clause = "条款ID", rust_type = "类型")]
pub const PARAM_NAME: Type = value;

参数:

clause: 所属宪法条款ID
rust_type: Rust类型（可选）

2.2 实现原理

#[proc_macro_attribute]
pub fn clause_param(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as ClauseParamArgs);
    let input = parse_macro_input!(item as ItemConst);

    let const_vis = &input.vis;
    let const_ident = &input.ident;
    let const_ty = &input.ty;
    let const_expr = &input.expr;

    // 生成元数据注释
    let metadata = match (&args.clause, &args.rust_type) {
        (Some(clause_id), Some(type_name)) => {
            format!(
                "Constitutional parameter: clause={}, name={}, type={}",
                clause_id,
                const_ident,
                type_name
            )
        }
        (Some(clause_id), None) => {
            format!(
                "Constitutional parameter: clause={}, name={}",
                clause_id, const_ident
            )
        }
        _ => format!("Constitutional parameter: name={}", const_ident),
    };

    // 生成最终代码
    let expanded = quote! {
        #[doc = #metadata]
        #const_vis const #const_ident: #const_ty = #const_expr;
    };

    TokenStream::from(expanded)
}

代码生成流程:

解析属性参数（clause、rust_type）
解析常量定义
生成文档注释（包含元数据）
保留原始常量定义

2.3 使用示例

输入代码:

#[clause_param(clause = "XTZH_GOLD_COVERAGE", rust_type = "f64")]
pub const XTZH_GOLD_COVERAGE_MIN: f64 = 1.25;

生成代码:

/// Constitutional parameter: clause=XTZH_GOLD_COVERAGE, name=XTZH_GOLD_COVERAGE_MIN, type=f64
pub const XTZH_GOLD_COVERAGE_MIN: f64 = 1.25;

2.4 问题分析

问题: 只生成文档注释，没有运行时元数据

当前实现只生成文档注释，无法在运行时查询参数元数据。

应该改进:

let expanded = quote! {
    #[doc = #metadata]
    #const_vis const #const_ident: #const_ty = #const_expr;
    
    // 生成元数据结构
    pub const #metadata_ident: ConstitutionalParamMetadata = ConstitutionalParamMetadata {
        name: stringify!(#const_ident),
        clause: #clause_id,
        rust_type: #type_name,
        value: #const_ident,
    };
};

3. constitutional_fn! 函数宏

3.1 功能说明

constitutional_fn!是一个函数宏，用于生成带宪法检查的函数。

语法:

constitutional_fn! {
    clause = "条款ID",
    fn function_name(args) -> ReturnType {
        // 函数实现
    }
}

3.2 实现原理

#[proc_macro]
pub fn constitutional_fn(input: TokenStream) -> TokenStream {
    let input_parsed = parse_macro_input!(input as ConstitutionalFnInput);

    let clause_id = input_parsed.clause;
    let function = input_parsed.function;
    let fn_vis = &function.vis;
    let fn_sig = &function.sig;
    let fn_block = &function.block;
    let fn_name = &function.sig.ident;

    // 生成带宪法检查的函数
    let expanded = quote! {
        #[doc = concat!("Constitutional function for clause: ", #clause_id)]
        #fn_vis #fn_sig {
            log::debug!("Constitutional function invoked: clause={}, function={}", #clause_id, stringify!(#fn_name));
            #fn_block
        }
    };

    TokenStream::from(expanded)
}

3.3 使用示例

输入代码:

constitutional_fn! {
    clause = "XTZH_GOLD_COVERAGE",
    fn check_coverage(coverage: f64) -> bool {
        coverage >= XTZH_GOLD_COVERAGE_MIN
    }
}

生成代码:

/// Constitutional function for clause: XTZH_GOLD_COVERAGE
fn check_coverage(coverage: f64) -> bool {
    log::debug!("Constitutional function invoked: clause={}, function={}", "XTZH_GOLD_COVERAGE", "check_coverage");
    {
        coverage >= XTZH_GOLD_COVERAGE_MIN
    }
}

4. 备用实现文件

4.1 constitutional.rs

这是#[constitutional]宏的备用实现，提供了更详细的参数解析。

主要区别:

使用AttributeArgs解析参数（旧版API）
支持enforce参数（强制执行器）
更详细的注释说明

问题: 与lib.rs中的实现重复，应该统一

4.2 clause_param.rs

这是#[clause_param]宏的备用实现。

主要区别:

支持description参数
生成更详细的文档注释

问题: 与lib.rs中的实现重复，应该统一

🐛 发现的问题

问题1: 重复实现

严重程度: ⚠️ 高

描述: lib.rs、constitutional.rs、clause_param.rs中存在重复实现

影响:

维护困难
可能导致行为不一致
增加代码复杂度

建议:

统一使用lib.rs中的实现
删除constitutional.rs和clause_param.rs
或者将lib.rs改为导出模块

状态: ❌ 待修复

问题2: 缺少实际验证逻辑

严重程度: ⚠️ 高

描述: 宏只生成日志记录，没有实际的约束验证

影响: 无法真正执行宪法约束

建议:

let precondition_check = if let Some(check_expr) = args.check {
    // 解析check_expr为syn::Expr
    let check_expr_parsed: syn::Expr = syn::parse_str(&check_expr)?;
    
    quote! {
        // 实际验证
        if !(#check_expr_parsed) {
            return Err(ConstitutionalError::ConstraintViolation {
                clause: #clause_id.to_string(),
                constraint: stringify!(#check_expr_parsed).to_string(),
            }.into());
        }
    }
} else {
    quote! {}
};

状态: ❌ 待实现

问题3: 缺少运行时元数据

严重程度: ⚠️ 中等

描述: 参数元数据只在文档中，无法运行时查询

建议: 生成运行时元数据结构

pub struct ConstitutionalParamMetadata {
    pub name: &'static str,
    pub clause: &'static str,
    pub rust_type: &'static str,
}

// 在宏中生成
inventory::submit! {
    ConstitutionalParamMetadata {
        name: stringify!(#const_ident),
        clause: #clause_id,
        rust_type: #type_name,
    }
}

状态: ❌ 待实现

问题4: 缺少编译时验证

严重程度: ⚠️ 中等

描述: check表达式是字符串，无法编译时验证

建议: 使用syn::Expr解析表达式

struct ConstitutionalArgs {
    clause: Option<String>,
    check: Option<syn::Expr>,  // 改为Expr
    obligation: Option<String>,
}

状态: ❌ 待实现

问题5: 缺少集成测试

严重程度: ⚠️ 中等

描述: 只有1个基础测试，没有实际使用测试

建议: 添加集成测试

#[cfg(test)]
mod tests {
    use super::*;

    #[constitutional(clause = "TEST_CLAUSE", check = "x > 0")]
    fn test_function(x: i32) -> Result<(), String> {
        Ok(())
    }

    #[test]
    fn test_constitutional_macro() {
        assert!(test_function(1).is_ok());
    }
}

问题: 过程宏测试需要在单独的crate中

状态: ❌ 待添加

问题6: 缺少错误处理

严重程度: ⚠️ 低

描述: 参数解析错误时，没有友好的错误信息

建议: 添加详细的错误信息

let clause = clause.ok_or_else(|| {
    syn::Error::new(
        Span::call_site(),
        "Missing required parameter 'clause'"
    )
})?;

状态: ❌ 待改进

问题7: 缺少文档示例

严重程度: ⚠️ 低

描述: 文档示例被标记为ignore，无法运行

建议: 创建examples目录，提供可运行示例

状态: ❌ 待添加

📊 完成度评估

功能模块	代码行数	完成度	状态
#[constitutional]宏	128行	50%	⚠️ 缺少验证
#[clause_param]宏	85行	60%	⚠️ 缺少元数据
constitutional_fn!宏	84行	50%	⚠️ 缺少验证
备用实现	173行	100%	⚠️ 重复代码
测试覆盖	6行	20%	❌ 不足
总计	470行	50%	🚧 进行中

待完善功能

高优先级:
- ❌ 删除重复实现
- ❌ 实现实际验证逻辑
- ❌ 添加编译时验证
中优先级:
- ❌ 添加运行时元数据
- ❌ 添加集成测试
- ⏳ 改进错误处理
低优先级:
- ⏳ 添加文档示例
- ⏳ 优化代码生成
- ⏳ 添加性能测试

🌟 设计亮点

声明式约束
- 通过宏参数声明约束
- 简洁易读
编译时代码生成
- 零运行时开销
- 类型安全
日志集成
- 自动生成日志代码
- 方便调试
灵活的参数
- 所有参数都是可选的
- 支持多种使用场景

🔗 模块依赖关系

nac-constitution-macros
├── 依赖
│   ├── syn (语法解析)
│   ├── quote (代码生成)
│   └── proc-macro2 (过程宏基础)
├── 被依赖
│   ├── nac-cee (宪法执行引擎)
│   ├── nac-cbpp-l0 (共识参数)
│   ├── nac-nvm (虚拟机)
│   └── 所有需要宪法约束的模块
└── 协作模块
    ├── nac-constitution-clauses (条款定义)
    └── nac-constitution-state (状态管理)

📝 开发建议

短期目标 (1周)

删除重复实现 (优先级P1)
- 统一使用lib.rs中的实现
- 删除constitutional.rs和clause_param.rs
实现实际验证逻辑 (优先级P1)
- 解析check表达式
- 生成验证代码
- 抛出宪法异常
添加编译时验证 (优先级P1)
- 使用syn::Expr解析表达式
- 验证表达式语法

中期目标 (2周)

添加运行时元数据 (优先级P2)
- 生成元数据结构
- 支持运行时查询
添加集成测试 (优先级P2)
- 创建测试crate
- 测试所有宏功能
改进错误处理 (优先级P2)
- 添加详细错误信息
- 改进错误提示

长期目标 (1个月)

添加文档示例 (优先级P3)
- 创建examples目录
- 提供可运行示例
优化代码生成 (优先级P3)
- 减少生成代码量
- 优化性能
扩展功能 (优先级P4)
- 支持异步函数
- 支持泛型函数
- 支持trait方法

💡 使用示例

示例1: #[constitutional]宏

use nac_constitution_macros::constitutional;

#[constitutional(
    clause = "XTZH_GOLD_COVERAGE",
    check = "coverage >= 1.25"
)]
fn mint_xtzh(amount: u64, coverage: f64) -> Result<(), Error> {
    // 铸造XTZH稳定币
    println!("Minting {} XTZH with coverage {}", amount, coverage);
    Ok(())
}

// 使用
fn main() {
    mint_xtzh(1000, 1.30).unwrap();  // OK
    // mint_xtzh(1000, 1.20).unwrap();  // 应该失败（coverage < 1.25）
}

示例2: #[clause_param]宏

use nac_constitution_macros::clause_param;

#[clause_param(
    clause = "XTZH_GOLD_COVERAGE",
    rust_type = "f64"
)]
pub const XTZH_GOLD_COVERAGE_MIN: f64 = 1.25;

#[clause_param(
    clause = "NET_CONN_MIN_CBP",
    rust_type = "u32"
)]
pub const MIN_CBP_CONNECTIONS: u32 = 12;

// 使用
fn main() {
    println!("Min coverage: {}", XTZH_GOLD_COVERAGE_MIN);
    println!("Min connections: {}", MIN_CBP_CONNECTIONS);
}

示例3: constitutional_fn!宏

use nac_constitution_macros::constitutional_fn;

constitutional_fn! {
    clause = "XTZH_GOLD_COVERAGE",
    fn check_coverage(coverage: f64) -> bool {
        coverage >= 1.25
    }
}

constitutional_fn! {
    clause = "NET_CONN_MIN_CBP",
    fn check_connections(count: u32) -> bool {
        count >= 12
    }
}

// 使用
fn main() {
    assert!(check_coverage(1.30));
    assert!(!check_coverage(1.20));
    
    assert!(check_connections(15));
    assert!(!check_connections(10));
}

🔄 与其他模块的协作

与nac-cee的协作

// nac-cee使用宪法宏定义约束函数
use nac_constitution_macros::constitutional;

#[constitutional(clause = "GAS_LIMIT_MAX", check = "gas <= MAX_GAS")]
fn execute_transaction(tx: Transaction, gas: u64) -> Result<Receipt, Error> {
    // 执行交易
}

与nac-cbpp-l0的协作

// nac-cbpp-l0使用宪法宏定义共识参数
use nac_constitution_macros::clause_param;

#[clause_param(clause = "NET_CONN_MIN_CBP", rust_type = "u32")]
pub const MIN_CONNECTIONS: u32 = 12;

#[clause_param(clause = "BLOCK_TIME_TARGET", rust_type = "u64")]
pub const BLOCK_TIME: u64 = 3000;  // 3秒

与nac-nvm的协作

// nac-nvm使用宪法宏定义虚拟机约束
use nac_constitution_macros::constitutional;

#[constitutional(clause = "STACK_DEPTH_MAX", check = "depth <= 1024")]
fn push_stack(vm: &mut VM, value: Value, depth: usize) -> Result<(), VMError> {
    // 压栈操作
}

📈 扩展建议

1. 支持异步函数

#[constitutional(clause = "ASYNC_TIMEOUT", check = "timeout <= 30")]
async fn async_operation(timeout: u64) -> Result<(), Error> {
    // 异步操作
}

2. 支持泛型函数

#[constitutional(clause = "GENERIC_CONSTRAINT")]
fn generic_function<T: Trait>(value: T) -> Result<(), Error> {
    // 泛型函数
}

3. 支持trait方法

trait ConstitutionalTrait {
    #[constitutional(clause = "TRAIT_METHOD")]
    fn method(&self) -> Result<(), Error>;
}

4. 支持条件编译

#[constitutional(
    clause = "DEBUG_MODE",
    check = "cfg!(debug_assertions)"
)]
fn debug_function() {
    // 只在debug模式下检查
}

分析完成时间: 2026-02-18
下一步: 删除重复实现并添加实际验证逻辑

19 KiB Raw Permalink Blame History Unescape Escape

nac-constitution-macros 模块深度分析报告

📋 模块概览

🏗️ 架构设计

核心功能

技术特点

目录结构

📦 依赖关系

🔍 核心功能详解

1. #[constitutional] 属性宏

1.1 功能说明

1.2 实现原理

1.3 使用示例

1.4 问题分析

2. #[clause_param] 属性宏

2.1 功能说明

2.2 实现原理

2.3 使用示例

2.4 问题分析

3. constitutional_fn! 函数宏

3.1 功能说明

3.2 实现原理

3.3 使用示例

4. 备用实现文件

4.1 constitutional.rs

4.2 clause_param.rs

🐛 发现的问题

问题1: 重复实现

问题2: 缺少实际验证逻辑

问题3: 缺少运行时元数据

问题4: 缺少编译时验证

问题5: 缺少集成测试

问题6: 缺少错误处理

问题7: 缺少文档示例

📊 完成度评估

待完善功能

🌟 设计亮点

🔗 模块依赖关系

📝 开发建议

短期目标 (1周)

中期目标 (2周)

长期目标 (1个月)

💡 使用示例

示例1: #[constitutional]宏

示例2: #[clause_param]宏

示例3: constitutional_fn!宏

🔄 与其他模块的协作

与nac-cee的协作

与nac-cbpp-l0的协作

与nac-nvm的协作

📈 扩展建议

1. 支持异步函数

2. 支持泛型函数

3. 支持trait方法

4. 支持条件编译

19 KiB

Raw Permalink Blame History