14 KiB

Raw Permalink Blame History

charter-compiler 模块深度分析报告

分析日期: 2026-02-18
模块版本: 0.1.0
分析状态: ✅ 完成

一、模块概述

模块名称: charter-compiler
功能定位: Charter语言编译器 - 将Charter智能合约源代码编译为NVM字节码
开发语言: Rust (Edition 2021)
模块类型: 二进制(bin)

Charter编译器是NAC公链的核心工具链之一，负责将高级智能合约语言Charter编译成可在NVM虚拟机上执行的字节码。它采用经典的编译器架构：词法分析 → 语法分析 → 语义分析 → 代码生成 → 优化。

二、目录结构

charter-compiler/
├── Cargo.toml          # 项目配置
├── Cargo.lock          # 依赖锁定
├── README.md           # 模块说明
├── charter.pest        # Pest语法文件（备用）
├── examples/           # 示例代码
│   └── shanghai_office.charter
└── src/                # 源代码
    ├── main.rs         # 主入口（194行）
    ├── lexer/          # 词法分析器
    │   └── mod.rs      # (400行)
    ├── parser/         # 语法分析器
    │   ├── ast.rs      # AST定义（278行）
    │   ├── mod.rs      # 解析器实现（944行）
    │   └── parser_fix.patch
    ├── semantic/       # 语义分析器
    │   └── mod.rs      # (648行)
    ├── codegen/        # 代码生成器
    │   └── mod.rs      # (590行)
    └── optimizer/      # 优化器
        └── mod.rs      # (192行)

代码统计:

总行数: 3246行
Rust文件数: 7个
模块数: 5个（lexer, parser, semantic, codegen, optimizer）

三、核心组件详细分析

3.1 main.rs - 编译器主入口

文件大小: 194行
核心功能: 命令行界面和编译流程控制

支持的命令

1. compile - 编译Charter源代码

charter compile -i contract.charter -o contract.nvm -O 2

-i, --input: 输入文件路径
-o, --output: 输出文件路径（可选，默认为.nvm扩展名）
-O, --optimization: 优化级别0-3（默认2）
-d, --debug: 生成调试信息

2. check - 语法检查

charter check -i contract.charter

仅进行词法、语法、语义分析
不生成字节码

3. ast - 显示抽象语法树

charter ast -i contract.charter

用于调试和理解编译器行为

4. version - 显示版本信息

charter version

显示编译器版本、NAC UDM版本、NVM目标版本

编译流程

源代码 → 词法分析 → 语法分析 → 语义分析 → 代码生成 → 优化 → 字节码

读取源代码: 从文件读取Charter代码
词法分析: lexer::tokenize() - 转换为Token流
语法分析: parser::parse() - 构建AST
语义分析: semantic::analyze() - 类型检查、作用域分析
代码生成: codegen::generate() - 生成NVM字节码
优化: optimizer::optimize() - 字节码优化（可选）
输出: 写入.nvm文件

3.2 lexer/mod.rs - 词法分析器

文件大小: 400行
核心功能: 将源代码字符串转换为Token流

使用的技术

Logos库: 高性能词法分析器生成器

使用宏定义Token
自动生成词法分析代码
支持正则表达式匹配

Token分类（共100+种）

1. 关键字 (20+个):

基础: asset, contract, fn, let, mut, const
控制流: if, else, for, in, while, return
模块: module, import, as
NAC特有: gnacs, sovereignty, require, requires, ensures
合规: require_cr, verify_cr

2. 修饰符 (7个):

pub, public, private, internal
payable, view, pure

3. 基础类型 (20+个):

无符号整数: uint8/u8, uint16/u16, ..., uint256/u256
有符号整数: int8/i8, int16/i16, ..., int256/i256
其他: bool, string, bytes, address, hash, timestamp

4. NAC专有类型 (11个):

身份: DID
资产: GNACSCode, AssetInstance
合规: ConstitutionalReceipt
标准: ACC20, ACC721, ACC1155, ACCRWA
主权: A0, C0, C1, C2, D0, D1, D2

5. 字面量:

整数: [0-9]+
十六进制: 0x[0-9a-fA-F]+
字符串: "..."
DID: did:nac:main:user:0x1234
布尔: true, false

6. 运算符 (20+个):

算术: +, -, *, /, %
比较: ==, !=, <, >, <=, >=
逻辑: &&, ||, !
赋值: =

7. 分隔符 (11个):

(, ), {, }, [, ]
,, ;, :, ., ->

注释支持

单行注释: //
文档注释: ///
多行注释: /* ... */

测试覆盖

4个单元测试：

test_tokenize_keywords - 关键字识别
test_tokenize_nac_types - NAC类型识别
test_tokenize_literals - 字面量识别
test_tokenize_did - DID格式识别

3.3 parser/ - 语法分析器

文件总大小: 1222行（ast.rs 278行 + mod.rs 944行）
核心功能: 将Token流转换为抽象语法树（AST）

3.3.1 ast.rs - AST定义

核心数据结构:

Program - 程序根节点

pub struct Program {
    pub items: Vec<TopLevelItem>,
}

TopLevelItem - 顶层项

pub enum TopLevelItem {
    Module(ModuleDeclaration),      // 模块声明
    Import(ImportStatement),         // 导入语句
    Asset(AssetDefinition),          // 资产定义
    Contract(ContractDefinition),    // 合约定义
    Function(FunctionDeclaration),   // 函数声明
}

AssetDefinition - 资产定义（NAC特色）

pub struct AssetDefinition {
    pub name: String,
    pub gnacs_code: GNACSCode,           // GNACS编码
    pub sovereignty: Option<SovereigntyType>,  // 主权类型
    pub fields: Vec<FieldDeclaration>,
    pub methods: Vec<MethodDeclaration>,
}

ContractDefinition - 合约定义

pub struct ContractDefinition {
    pub name: String,
    pub fields: Vec<FieldDeclaration>,
    pub methods: Vec<MethodDeclaration>,
}

MethodDeclaration - 方法声明（支持契约式编程）

pub struct MethodDeclaration {
    pub modifiers: Vec<MethodModifier>,
    pub name: String,
    pub parameters: Vec<Parameter>,
    pub return_type: Option<TypeAnnotation>,
    pub requires: Vec<Expression>,  // 前置条件
    pub ensures: Vec<Expression>,   // 后置条件
    pub body: Block,
}

TypeAnnotation - 类型注解

支持所有基础类型（uint8-uint256, int8-int256, bool, string等）
支持NAC类型（DID, GNACSCode, ConstitutionalReceipt等）
支持数组: Array(Box<TypeAnnotation>, Option<usize>)
支持动态数组: Vec(Box<TypeAnnotation>)
支持引用: Reference(Box<TypeAnnotation>)

Statement - 语句类型

pub enum Statement {
    Let(LetStatement),           // 变量声明
    Assign(AssignStatement),     // 赋值
    If(IfStatement),             // 条件语句
    For(ForStatement),           // 循环
    While(WhileStatement),       // While循环
    Return(ReturnStatement),     // 返回
    Emit(EmitStatement),         // 事件发射
    RequireCR(Expression),       // 要求宪政收据
    VerifyCR(Expression),        // 验证宪政收据
    Expression(Expression),      // 表达式语句
}

Expression - 表达式类型

字面量: Integer, HexNumber, String, Boolean, GNACSCode, DID
标识符: Identifier
运算: Binary, Unary
调用: FunctionCall
访问: MemberAccess, ArrayAccess
条件: If表达式

3.3.2 mod.rs - 解析器实现

文件大小: 944行
核心功能: 递归下降解析器

Parser结构:

pub struct Parser {
    tokens: Vec<Token>,
    current: usize,
}

核心方法:

parse_program() - 解析整个程序
parse_top_level_item() - 解析顶层项
parse_asset_definition() - 解析资产定义
parse_contract_definition() - 解析合约定义
parse_method() - 解析方法
parse_statement() - 解析语句
parse_expression() - 解析表达式
parse_type_annotation() - 解析类型注解

错误处理:

pub enum ParseError {
    UnexpectedToken { expected: String, actual: String },
    UnexpectedEOF,
    InvalidTypeAnnotation,
    InvalidExpression,
    MissingGNACSDeclaration,
    InvalidGNACSCode(String),
}

3.4 semantic/mod.rs - 语义分析器

文件大小: 648行
核心功能: 类型检查、作用域分析、语义验证

主要功能

1. 类型检查:

变量类型一致性检查
函数参数类型匹配
返回值类型验证
表达式类型推导

2. 作用域分析:

变量声明和使用检查
函数可见性验证
模块导入验证

3. NAC特定验证:

GNACS编码格式验证
主权类型合法性检查
宪政收据验证
DID格式验证

4. 契约式编程验证:

requires前置条件检查
ensures后置条件检查
不变量验证

3.5 codegen/mod.rs - 代码生成器

文件大小: 590行
核心功能: 将AST转换为NVM字节码

代码生成流程

AST → 中间表示 → NVM字节码

主要任务:

遍历AST
为每个节点生成对应的NVM指令
处理变量分配（栈/内存）
生成跳转标签和地址
生成函数调用序列
处理NAC特定操作码

生成的字节码格式:

使用nac-nvm定义的Opcode
支持所有27种NVM指令
生成可执行的.nvm文件

3.6 optimizer/mod.rs - 优化器

文件大小: 192行
核心功能: 字节码优化

优化级别

Level 0: 无优化
Level 1: 基础优化

常量折叠
死代码消除

Level 2: 标准优化（默认）

Level 1的所有优化
公共子表达式消除
跳转优化

Level 3: 激进优化

Level 2的所有优化
内联展开
循环优化

四、依赖分析

核心依赖

nac-udm (本地依赖):

NAC统一定义模块
提供GNACSCode, SovereigntyType等类型
确保与NAC生态系统的类型一致性

logos (0.13):

高性能词法分析器生成器
用于Token定义和词法分析

pest (2.7):

PEG解析器生成器
作为备用解析方案（charter.pest文件）

serde (1.0):

序列化/反序列化
用于AST的持久化

thiserror (2.0):

错误类型派生宏
简化错误处理

anyhow (1.0):

错误处理库
提供Result类型

clap (4.5):

命令行参数解析
支持derive宏

tracing (0.1):

结构化日志
用于编译过程追踪

hex (0.4):

十六进制编码/解码
用于字节码处理

sha3 (0.10):

SHA3哈希
用于合约地址生成

开发依赖

tempfile (3.8):

临时文件管理
用于测试

criterion (0.5):

性能基准测试
用于优化器性能测试

五、与其他模块的关系

上游依赖

nac-udm: 统一定义模块，提供类型系统
charter-std: Charter标准库（编译时链接）

下游使用

nac-nvm: 执行编译后的字节码
nac-contract-deployer: 部署编译后的合约
nac-cli: 命令行工具中集成编译器

输入输出

输入: .charter源文件
输出: .nvm字节码文件

六、示例代码

shanghai_office.charter

// 示例：上海办公室资产合约
asset ShangHaiOffice {
    gnacs "1.1.1.1.1.1.1.1";
    sovereignty C1;
    
    address: string;
    area: uint64;
    value: uint256;
}

七、优缺点分析

优点

✅ 完整的编译器架构（词法→语法→语义→代码生成→优化）
✅ 支持NAC特有功能（GNACS、主权类型、宪政收据）
✅ 支持契约式编程（requires/ensures）
✅ 良好的错误处理
✅ 多级优化支持
✅ 命令行工具完善
✅ 代码结构清晰，模块化设计

缺点

⚠️ 缺少测试覆盖（仅词法分析器有4个测试）
⚠️ 缺少完整的示例代码
⚠️ README文档不完整（功能说明为"待补充"）
⚠️ 缺少性能基准测试
⚠️ 缺少IDE集成（语法高亮、自动补全）

八、待完成工作

⏳ 补充完整的单元测试和集成测试
⏳ 完善README文档
⏳ 添加更多示例代码
⏳ 实现性能基准测试
⏳ 开发VSCode扩展（语法高亮、自动补全）
⏳ 添加调试信息生成
⏳ 实现增量编译
⏳ 添加编译缓存

九、使用示例

编译合约

# 编译Charter合约
charter compile -i contract.charter -o contract.nvm -O 2

# 仅检查语法
charter check -i contract.charter

# 查看AST
charter ast -i contract.charter

# 查看版本
charter version

编程示例

contract SimpleToken {
    name: string;
    total_supply: uint256;
    balances: mapping<address, uint256>;
    
    pub fn transfer(to: address, amount: uint256) 
        requires balance[msg.sender] >= amount
        ensures balance[to] == old(balance[to]) + amount
    {
        balances[msg.sender] -= amount;
        balances[to] += amount;
        emit Transfer(msg.sender, to, amount);
    }
}

十、总结

charter-compiler是一个设计良好、功能完整的智能合约编译器。它成功地将Charter高级语言编译为NVM字节码，支持NAC公链的所有特色功能（GNACS、主权类型、宪政收据等）。代码结构清晰，采用经典的编译器架构，易于维护和扩展。

主要不足在于测试覆盖不够完整，文档需要补充。建议优先完善测试和文档，然后添加IDE集成和调试支持。

完成度: 85%
生产就绪: ⚠️ 需要补充测试
建议: 补充测试后可用于生产环境

分析完成时间: 2026-02-18 23:00
下一个模块: charter-std（Charter标准库）

14 KiB Raw Permalink Blame History Unescape Escape