NAC_Blockchain/charter-std/docs/nvm_xtzh_opcodes.md

NVM XTZH 汇率指令集扩展

Issue #61: NVM v2.1 新增指令 0xF0-0xF7

指令列表

操作码	助记符	操作数	描述
0xF0	XTZH_RATE	-	从系统状态树读取当前 XTZHRate，压栈
0xF1	XTZH_RATE_HIST	epoch: u64	读取指定纪元历史汇率，压栈
0xF2	XTZH_CONVERT	amount: u64, rate_ptr: ptr	XTZH → SDR 定点数转换
0xF3	XTZH_CONVERT_INV	amount: u64, rate_ptr: ptr	SDR → XTZH 定点数转换
0xF4	XTZH_VERIFY	receipt_ptr: ptr	验证宪法收据，返回 bool
0xF5	SDR_BASKET	-	读取 SDR 篮子权重数组，压栈
0xF6	GOLD_COVERAGE	-	计算黄金覆盖率，压栈
0xF7	XTZH_FREEZE	receipt_ptr: ptr	紧急冻结（需系统权限）

安全约束

• 0xF7 (XTZH_FREEZE) 仅在 @system 修饰的函数中可用
• 0xF4 (XTZH_VERIFY) 在编译期静态检查 ConstitutionalReceipt 类型
• 0xF0-0xF6 在 @view 和 @pure 函数中均可调用
• 所有定点数运算使用 256 位中间精度，防止溢出

Charter 编译器映射规则

@builtin(0xF0) fn get_rate() -> XTZHRate
  → PUSH_SYSCALL 0xF0
  → POP_STRUCT XTZHRate (4 fields × 8 bytes = 32 bytes)

@builtin(0xF2) fn to_sdr(amount: u64, rate: XTZHRate) -> u64
  → PUSH amount
  → PUSH_STRUCT rate
  → SYSCALL 0xF2
  → POP u64

@system @builtin(0xF7) fn emergency_freeze(cr: CR) -> bool
  → CHECK_SYSCALL_PERMISSION SYSTEM
  → PUSH_STRUCT cr
  → SYSCALL 0xF7
  → POP bool

零成本抽象验证

所有 XTZH 汇率操作均直接映射为 1-2 条 NVM 指令，无运行时开销：

• get_rate() → 1 条指令（XTZH_RATE）
• to_sdr() → 3 条指令（PUSH + PUSH_STRUCT + SYSCALL）
• verify_rate_receipt() → 2 条指令（PUSH_STRUCT + XTZH_VERIFY）