#61Charter 语言规范扩展：XTZH 汇率系统原生支持 #61
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Charter 语言规范扩展：XTZH 汇率系统原生支持
——编译器语义与标准库定义
版本：1.0
关联规范：UDM v2.0（模块 0x00030001）、NVM v2.1（指令 0xF0–0xF7）
制定方：NAC 语言设计委员会
最后更新：2026年2月12日
设计原则
1.零成本抽象：所有汇率相关操作均直接映射为 1–2 条 NVM 指令，无运行时开销。
2.静态可验证：角色权限、系统调用、收据合法性等约束均在编译期检查。
3.声明式语义：使用修饰器（@）而非内联汇编表达系统级意图。
4.渐进式暴露：普通开发者只需调用 xtzh::get_rate()；高级开发者可访问底层密码学原语。
内置类型
2.1 XTZHRate —— 汇率记录
charter
/// XTZH 汇率快照（系统状态树持久化）
public struct XTZHRate {
/// 数据时间戳（Unix 秒，UTC 12:00）
timestamp: uint64,
/// 1 XTZH = ? SDR，定点数 1e6 精度（即 1_000000 = 1.0 SDR）
rate_sdr: uint64,
/// 1 XTZH = ? USD，定点数 1e6 精度
rate_usd: uint64,
/// 纪元编号 = timestamp / 86400
epoch: uint64
}
语义：
•XTZHRate 是值类型（栈传递，无所有权）。
•两个 XTZHRate 实例相等当且仅当所有字段相等。
•不可变（所有字段只读）。
编译器映射：
•该类型的内存布局与 NVM 系统状态树中存储的记录完全一致，无装箱开销。
2.2 ConstitutionalReceipt —— 宪法收据（系统内部）
charter
/// 宪法收据 —— 仅用于系统级交易，普通合约不可构造
@system
public struct ConstitutionalReceipt {
// 内部字段对普通合约不可见
@builtin
internal raw: bytes
}
语义：
•标记 @system 表示该类型只能由系统合约或编译器内置函数生成。
•普通代码无法直接创建或修改 ConstitutionalReceipt 实例。
•作为参数传递给需要宪法收据的系统函数（如 xtzh::submit_rate）。
内置函数（编译器直接内联）
所有内置函数均定义在全局命名空间 __builtin 中，并通过标准库暴露。编译器在遇到这些函数时直接生成对应的 NVM 指令序列。
内置函数 对应 NVM 指令 说明
__builtin_xtzh_get_rate(epoch: uint64) -> (uint64,uint64,uint64,uint64) XTZH_GET_RATE 获取汇率
__builtin_xtzh_compose_rate(...) XTZH_COMPOSE_RATE 预言机专用，计算汇率
__builtin_bls_verify_aggregated(...) BLS_VERIFY_AGGREGATED BLS 聚合签名验证
__builtin_zk_verify_groth16(...) ZK_VERIFY_GROTH16 zkSNARK 验证
__builtin_tee_verify_nvidia(...) TEE_VERIFY_NVIDIA TEE 认证验证
__builtin_system_state_write(key: bytes, value: bytes) SYSTEM_STATE_WRITE 仅 CBP
__builtin_system_state_read(key: bytes) -> bytes SYSTEM_STATE_READ 读取系统状态
__builtin_udm_validate(module_id: uint32, version: uint16, data: bytes) -> bool （内嵌 Wasm） 调用 UDM 验证器
标准库设计（xtzh 命名空间）
4.1 核心汇率模块 —— xtzh/rate.charter
charter
// xtzh/rate.charter
// XTZH 汇率查询接口（所有合约可用）
use __builtin;
/// 获取当前最新 XTZH 汇率
public func get_rate() -> XTZHRate {
let (sdr, usd, ts, epoch) = __builtin_xtzh_get_rate(0);
return XTZHRate {
timestamp: ts,
rate_sdr: sdr,
rate_usd: usd,
epoch: epoch
};
}
/// 获取指定纪元的 XTZH 汇率（历史汇率）
public func get_rate_by_epoch(epoch: uint64) -> Option {
let (sdr, usd, ts, e) = __builtin_xtzh_get_rate(epoch);
if e == 0 { return None; }
return Some(XTZHRate {
timestamp: ts,
rate_sdr: sdr,
rate_usd: usd,
epoch: e
});
}
语义保证：
•编译器确保 __builtin_xtzh_get_rate 仅被调用一次，结果缓存在当前栈帧（若同一函数内多次调用，自动优化）。
•get_rate() 是纯视图函数，不修改状态。
4.2 预言机提交模块 —— xtzh/oracle.charter
charter
// xtzh/oracle.charter
// 仅限授权预言机节点使用
@system
public func submit_rate(receipt: ConstitutionalReceipt) {
// 此函数体为空 —— 编译器将其替换为以下操作：
// 1. 调用 UDM 模块 0x00030001 验证 receipt.raw
// 2. 若验证通过，调用 __builtin_system_state_write 写入状态树
// 3. 触发系统事件 RateUpdated
__builtin_udm_validate(0x00030001, 1, receipt.raw)
|| revert("Invalid constitutional receipt");
}
编译器特殊处理：
•@system 标记的函数不能被普通合约调用 —— 调用者地址必须为已注册的 CBP 节点，此检查由编译器插入。
•自动插入 BLS 签名验证指令，确保收据满足宪法阈值。
4.3 密码学工具模块 —— xtzh/crypto.charter
charter
// xtzh/crypto.charter
// 提供汇率收据相关的密码学验证
/// 验证 BLS 聚合签名（48 字节公钥）
public func verify_bls_aggregated(
message: bytes,
signature: bytes48,
signers_bitmap: bytes,
pubkey_set: []bytes48
) -> bool {
return __builtin_bls_verify_aggregated(
message, signature, signers_bitmap, pubkey_set
);
}
/// 验证 Groth16 zkSNARK 证明（BN254）
public func verify_zk_groth16(
proof: bytes,
public_inputs: []uint64,
vk: bytes // 验证密钥，通常由系统常量提供
) -> bool {
return __builtin_zk_verify_groth16(proof, public_inputs, vk);
}
/// 验证 NVIDIA TEE 认证报告
public func verify_tee_nvidia(
attestation: bytes,
expected_code_hash: bytes32,
expected_input_hash: bytes32
) -> bool {
return __builtin_tee_verify_nvidia(
attestation, expected_code_hash, expected_input_hash
);
}
编译器优化：
•当参数为常量时（如验证密钥 vk），编译器直接将其内嵌为指令立即数，无需内存加载。
4.4 治理配置模块 —— xtzh/governance.charter
charter
// xtzh/governance.charter
// 汇率系统参数（由 XIC 治理设定）
/// 当前活跃的汇率模型版本哈希
@system_constant(key = "XTZH_MODEL_HASH")
public func model_hash() -> bytes32;
/// 预言机节点公钥列表
@system_constant(key = "XTZH_ORACLE_PUBKEYS")
public func oracle_pubkeys() -> []bytes48;
/// BLS 签名所需阈值（如 2/3）
@system_constant(key = "XTZH_SIGNATURE_THRESHOLD")
public func signature_threshold() -> uint8;
语义：
•@system_constant 标记的函数直接从系统状态树读取预置参数，无需存储开销。
•这些参数仅能通过 XIC 治理提案修改，修改后需等待一个纪元（约24小时）生效。
编译器安全检查
5.1 角色与权限检查
修饰器 语义 检查时机
@system 标记类型/函数仅供系统级调用 编译期：调用者必须是 CBP 节点或系统合约
@oracle 标记函数仅限预言机节点调用 编译期：调用者地址必须在 oracle_pubkeys() 中
@constitutional_receipt 参数必须是有效的宪法收据 编译期：自动插入 UDM 验证调用
示例：
charter
@oracle
func report_emergency(reason: bytes) {
// 只有预言机节点可以调用
}
5.2 状态修改检查
•任何直接调用 __builtin_system_state_write 的代码必须位于 @system 函数内，且交易必须由 CBP 节点发起。
•编译器为 xtzh::submit_rate 自动生成写入操作，并确保只有通过宪法收据验证的收据才能写入。
5.3 权重归一化静态断言
charter
// 在汇率收据构造代码中，编译器可插入静态断言
// 但此断言仅对预言机代码有效
static_assert(w_fx + w_au + w_com == 10000, "Weight sum must be 10000");
完整示例：ACC-20 合约使用 XTZH 汇率
charter
import "xtzh/rate.charter";
import "acc/ACC20.charter";
contract RealEstateToken is ACC20 {
// 铸造：锁定 XTZH，发行等值资产（简化版）
func mint(uint256 xtzhAmount) public {
// 1. 获取当前 XTZH 兑 USD 汇率
let rate = xtzh::get_rate();
}
1.语法扩展：增加 @system、@system_constant 等修饰器，支持 __builtin 标识符。
2.类型检查：
￮@system 类型不可被普通代码实例化。
￮@system_constant 函数必须是无参视图函数，返回值类型限定为基本类型或 bytes/[]bytes48。
3.内联生成：
￮xtzh::get_rate() → 生成 XTZH_GET_RATE 指令，并自动将四输出打包为结构体。
￮xtzh::submit_rate(receipt) → 生成 UDM 验证调用 + 状态写入 + 事件触发。
4.安全注入：所有对 __builtin_system_state_write 的调用点，自动插入调用者地址检查（require(__cbp_only())）。
本规范随 XTZH 汇率系统 v1.0 同步发布。后续版本将：
•增加对更多 ZK 证明系统（Plonk、Halo2）的内置支持。
•扩展 @system_constant 支持复杂结构体常量。
•提供 xtzh::simulate_rate 沙箱函数用于链下测试。
制定人：NAC 语言设计委员会
最后更新：2026年2月12日
状态：治理草案
本规范赋予 XTZH 汇率系统“语言级公民身份”
—— 不再是链上合约的“外挂插件”，而是 Charter 语法树中一等分支，NVM 指令集中永久驻留。