# XTZH AI汇率定价模型系统

**版本**: 1.0.0  
**状态**: 开发中  
**架构层级**: L1 Protocol Layer（协议层）

---

## 概述

XTZH AI汇率定价模型是NAC公链的核心价值稳定机制，通过双层嵌套注意力机制实现基于50维宏观状态向量的汇率预测。系统采用可验证计算架构，确保链上汇率的可信性与透明性。

### 核心特性

- **双层嵌套注意力机制**: Transformer 4层8头 + 资产层权重注意力 + 商品内偏离注意力
- **50维宏观状态向量**: 覆盖全球增长、通胀压力、货币政策、风险不确定性、实体活动、商品市场
- **可验证计算**: 混合预言机网络（ZK + TEE + 乐观）三模冗余验证
- **高性能**: 模型推理 < 100ms，ZK证明生成 < 10秒
- **宪法约束**: 黄金层权重5%-20%，125%黄金永续合约信任锚

---

## 架构

```
xtzh-ai/
├── src/
│   ├── lib.rs                 # 模块入口
│   ├── data/                  # 数据工程层
│   │   ├── mod.rs
│   │   ├── features.rs        # 50维特征定义
│   │   ├── pipeline.rs        # 数据流水线
│   │   ├── sources.rs         # 数据源集成
│   │   └── preprocessing.rs   # 预处理与标准化
│   ├── model/                 # AI模型层
│   │   ├── mod.rs
│   │   ├── transformer.rs     # Transformer编码器
│   │   ├── attention.rs       # 双层注意力机制
│   │   ├── architecture.rs    # 模型架构定义
│   │   └── inference.rs       # 推理引擎
│   ├── training/              # 训练系统
│   │   ├── mod.rs
│   │   ├── trainer.rs         # 训练器
│   │   ├── loss.rs            # 多任务损失函数
│   │   ├── optimizer.rs       # 优化器配置
│   │   └── validation.rs      # 验证指标
│   ├── export/                # ONNX导出
│   │   ├── mod.rs
│   │   ├── onnx.rs            # ONNX导出
│   │   ├── quantization.rs    # INT8量化
│   │   └── optimization.rs    # 模型优化
│   └── oracle/                # 预言机集成
│       ├── mod.rs
│       ├── node.rs            # 预言机节点
│       ├── aggregator.rs      # 聚合器
│       ├── proof.rs           # 证明生成
│       └── api.rs             # gRPC API
├── tests/                     # 集成测试
├── benches/                   # 性能基准测试
├── examples/                  # 示例代码
├── docs/                      # 文档
└── Cargo.toml

```

---

## 模块说明

### 数据工程层（data/）

负责50维宏观状态向量的采集、清洗、对齐、标准化与存储。

**关键组件**：
- `features.rs`: 50维特征定义（G1-G10, I1-I8, M1-M6, R1-R8, A1-A10, C1-C8）
- `pipeline.rs`: Airflow + Rust数据流水线
- `sources.rs`: 数据源集成（BLS, IMF, LBMA, CBOE, ICE, FRED等）
- `preprocessing.rs`: 卡尔曼滤波插补、z-score标准化

**性能要求**：
- 更新频率：每日UTC 12:00快照
- 延迟：≤5分钟
- 历史回溯：2000年至今

### AI模型层（model/）

实现双层嵌套注意力机制的汇率预测模型。

**关键组件**：
- `transformer.rs`: 4层8头Transformer编码器（256维嵌入）
- `attention.rs`: 双层注意力（资产层权重 + 商品内偏离）
- `architecture.rs`: 模型架构定义（2.1M参数）
- `inference.rs`: 推理引擎（< 100ms）

**输出**：
- XTZH汇率（1 XTZH = ? SDR，定点数1e6）
- 动态权重（w_fx, w_au, w_com，基点）
- 商品偏离系数（18维，int8）

### 训练系统（training/）

模型训练、验证与评估。

**关键组件**：
- `trainer.rs`: 训练器（4 × H100，批次64，200轮）
- `loss.rs`: 多任务损失（汇率MSE + 权重交叉熵 + 宏观预测MSE）
- `optimizer.rs`: AdamW优化器（学习率3e-4 → 1e-6余弦退火）
- `validation.rs`: 验证指标（R² ≥ 0.65，波动率约束）

**数据划分**：
- 训练集：2000-2022（5,800天）
- 验证集：2023-2024（500天）
- 测试集1：2025（260天）
- 测试集2：2008金融危机+2020疫情

### ONNX导出（export/）

模型导出为ONNX格式，支持zkML编译与TEE部署。

**关键组件**：
- `onnx.rs`: ONNX导出（opset 17，静态计算图）
- `quantization.rs`: INT8量化（scale=0.023529）
- `optimization.rs`: 模型优化（onnx-simplifier）

**输出文件**：
- `xtzh_model_v1.0.int8.onnx`: INT8量化模型（ZK编译用）
- `xtzh_model_v1.0.fp16.onnx`: FP16模型（TEE部署用）

### 预言机集成（oracle/）

混合预言机网络，提供可验证的汇率数据。

**关键组件**：
- `node.rs`: 预言机节点（ZK/TEE/乐观）
- `aggregator.rs`: 聚合器（中位数，BLS签名）
- `proof.rs`: 证明生成（Groth16/TEE认证/Ed25519签名）
- `api.rs`: gRPC API（XTZHOracle服务）

**网络配置**：
- 3个ZK节点（Nexus zkMCP，证明 < 10秒）
- 2个TEE节点（NVIDIA H100 CC，推理 < 500ms）
- 2个乐观节点（Ed25519签名，推理 < 100ms）

---

## 开发原则

遵循NAC记忆系统（`../memory/`）中的核心原则：

- **ARCH_001**: 四层架构体系（本模块属于L1协议层）
- **ARCH_004**: 代码保留原则（永远不要删除代码）
- **ARCH_005**: NAC原生设计（不模仿任何其他公链）
- **ARCH_006**: 测试驱动开发（单元测试覆盖率 > 80%）

---

## 快速开始

### 构建

```bash
cd /home/ubuntu/NAC_Clean_Dev_NEW/NAC_Clean_Dev/xtzh-ai
cargo build --release
```

### 测试

```bash
# 运行所有测试
cargo test

# 运行特定模块测试
cargo test --package xtzh-ai --lib data::tests

# 运行基准测试
cargo bench
```

### 示例

```bash
# 运行数据流水线示例
cargo run --example data_pipeline

# 运行模型推理示例
cargo run --example model_inference

# 运行预言机节点示例
cargo run --example oracle_node
```

---

## 性能指标

| 指标 | 目标 | 当前状态 |
|------|------|---------|
| 宏观预测R² | ≥ 0.65 | 开发中 |
| 模型推理时间 | < 100ms | 开发中 |
| ZK证明生成时间 | < 10秒 | 开发中 |
| TEE推理时间 | < 500ms | 开发中 |
| 单元测试覆盖率 | > 80% | 开发中 |

---

## 文档

详细技术文档请参阅：

- [XTZH AI模型完整技术规范](/home/ubuntu/XTZH_AI_Model_Technical_Specification.md)
- [50维宏观状态向量定义](/home/ubuntu/upload/附件A：特征全集详细定义（50维宏观状态向量）.docx)
- [ONNX导出指南](/home/ubuntu/upload/附件B：模型架构ONNX导出指南.docx)
- [zkML编译器配置指南](/home/ubuntu/upload/附件C：NexuszkMCP编译器配置指南.docx)
- [预言机节点API规范](/home/ubuntu/upload/附件D：预言机节点API规范.docx)

---

## 许可证

MIT License

---

## 联系方式

NAC人工智能实验室  
Email: ai@nac.network  
GitHub: https://github.com/NAC/xtzh-ai