// Charter Standard Library - XTZH 汇率模块
// Issue #61: XTZH 汇率系统原生支持
// 版本: 1.0 | NVM 指令: 0xF0-0xF7

/// XTZH 汇率快照（系统状态树持久化）
/// 内存布局与 NVM 系统状态树记录完全一致，无装箱开销
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
}

/// 宪法收据 —— 仅用于系统级交易，普通合约不可构造
@system
public struct ConstitutionalReceipt {
    @builtin
    internal raw: bytes
}

/// 汇率更新事件
public event XTZHRateUpdated {
    epoch: uint64,
    rate_sdr: uint64,
    rate_usd: uint64,
    updater: address
}

/// 汇率偏离告警事件
public event XTZHRateDeviation {
    epoch: uint64,
    deviation_bps: uint64,
    direction: string
}

/// xtzh 命名空间 —— 汇率查询标准库
module xtzh {
    /// 获取当前 XTZH/SDR 汇率（定点数 1e6）
    /// 编译器映射：NVM 指令 XTZH_RATE (0xF0)
    @builtin(0xF0)
    pub fn get_rate() -> XTZHRate;

    /// 获取指定纪元的历史汇率
    /// 编译器映射：NVM 指令 XTZH_RATE_HIST (0xF1)
    @builtin(0xF1)
    pub fn get_rate_at(epoch: uint64) -> XTZHRate;

    /// 将 XTZH 金额转换为 SDR（定点数运算，无溢出）
    /// 编译器映射：NVM 指令 XTZH_CONVERT (0xF2)
    @builtin(0xF2)
    pub fn to_sdr(xtzh_amount: uint64, rate: XTZHRate) -> uint64;

    /// 将 SDR 金额转换为 XTZH
    /// 编译器映射：NVM 指令 XTZH_CONVERT_INV (0xF3)
    @builtin(0xF3)
    pub fn from_sdr(sdr_amount: uint64, rate: XTZHRate) -> uint64;

    /// 验证汇率收据（宪法级验证）
    /// 编译器映射：NVM 指令 XTZH_VERIFY (0xF4)
    @builtin(0xF4)
    pub fn verify_rate_receipt(receipt: ConstitutionalReceipt) -> bool;

    /// 获取 SDR 篮子权重（IMF 标准）
    /// 返回：[USD, EUR, CNY, JPY, GBP] 权重，定点数 1e6
    /// 编译器映射：NVM 指令 SDR_BASKET (0xF5)
    @builtin(0xF5)
    pub fn sdr_basket_weights() -> [uint64; 5];

    /// 计算黄金覆盖率（储备/流通市值，定点数 1e4）
    /// 编译器映射：NVM 指令 GOLD_COVERAGE (0xF6)
    @builtin(0xF6)
    pub fn gold_coverage_ratio() -> uint64;

    /// 触发紧急汇率冻结（需宪法法院 7/9 签署）
    /// 编译器映射：NVM 指令 XTZH_FREEZE (0xF7)
    @system
    @builtin(0xF7)
    pub fn emergency_freeze(cr: ConstitutionalReceipt) -> bool;
}