# 多智能体预言机系统 (Multi-Agent Oracle)

[![Crates.io](https://img.shields.io/crates/v/multi-agent-oracle.svg)](https://crates.io/crates/multi-agent-oracle)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于**因果指纹（Causal Fingerprinting）**的去中心化多智能体预言机网络。本系统不仅验证数据的准确性，更验证智能体的**逻辑一致性**，实现了"逻辑层面的去中心化"。

## 🚀 SDK 快速开始

### 安装

```bash
cargo add multi-agent-oracle
```

或在 `Cargo.toml` 中添加：

```toml
[dependencies]
multi-agent-oracle = "0.1.0"
```

### 基本使用

```rust
use multi_agent_oracle::sdk::{Oracle, SdkConfig, OracleQuery};
use std::time::Duration;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. 创建配置
    let config = SdkConfig::builder()
        .with_solana_rpc("https://api.devnet.solana.com")
        .with_agent_count(5)
        .with_consensus_threshold(0.67)
        .with_query_timeout(Duration::from_secs(30))
        .build();

    // 2. 创建预言机实例
    let oracle = Oracle::new(config)?;

    // 3. 初始化 Agents 和共识引擎
    oracle.init_default_agents().await?;
    oracle.init_consensus().await?;

    // 4. 发起查询
    let query = OracleQuery::new("query_001", "BTC price prediction")
        .with_data_type("crypto_price")
        .with_timeout(30);

    let result = oracle.query(query).await?;

    // 5. 获取共识结果
    let consensus = result.consensus_output()?;
    println!("共识值: {:.4}", consensus.consensus_value);
    println!("置信度: {:.2}%", consensus.confidence * 100.0);

    Ok(())
}
```

### Solana 链上集成

```rust
use multi_agent_oracle::sdk::{SolanaConfig, SolanaIntegration};

// 创建 Solana 集成实例
let solana_config = SolanaConfig::builder()
    .with_rpc_url("https://api.devnet.solana.com")
    .with_oracle_program_id("YourOracleProgramId111111111111111111111111")
    .build();

let solana = SolanaIntegration::new(solana_config);

// 提交共识结果到链上
let tx_hash = solana.submit_consensus(&consensus).await?;
println!("交易哈希: {}", tx_hash);
```

### 运行示例

```bash
cargo run --example sdk_quick_start
```

## 🎯 核心创新：因果指纹验证

传统预言机只负责搬运数据，无法验证 AI 智能体的推理逻辑。本系统通过**因果指纹法**，将因果推理降维成密码学级别的"挑战-响应"协议：

```
传统预言机：验证 "数据准不准"
本系统：    验证 "逻辑对不对" + "是否存在供应商垄断"
```

### 为什么数学上难以攻破？

1. **非线性锁定**：AI 模型是高度非线性的，攻击者必须知道模型在特定点的局部曲率才能伪造响应
2. **高维防御**：注入 n 个随机干预，伪造成功率随 n 呈指数级下降
3. **模型异构性红利**：即使攻击者控制多个同源 Agent，协议会检测到"指纹熵"过低并自动降权

## 🏗️ 系统架构

### 三层验证体系

| 层级 | 名称 | 作用 | 防御场景 |
|------|------|------|----------|
| **第一层** | 干预响应 | 收集 Agent 的因果指纹 Δy | 单次任务逻辑自洽性 |
| **第二层** | 谱分析 | 提取特征值分布 | 供应商一致性攻击、投毒检测 |
| **第三层** | 全局指纹 | 长期逻辑声誉积累 | 女巫攻击、模型崩溃 |

### 因果指纹生命周期

```
┌─────────────────────────────────────────────────────────────────┐
│  第一阶段：任务定格                                               │
│  用户发起请求 → Agent 提交基准预测 y₀ (锁定立场)                    │
├─────────────────────────────────────────────────────────────────┤
│  第二阶段：因果扰动                                               │
│  链上生成随机扰动向量 δ → 发布挑战                                 │
├─────────────────────────────────────────────────────────────────┤
│  第三阶段：指纹提取                                               │
│  Agent 计算 Δy = f(x+δ) - f(x) → 提交因果指纹                     │
├─────────────────────────────────────────────────────────────────┤
│  第四阶段：聚合判定                                               │
│  谱分析 → 余弦相似度聚类 → 离群点剔除 → 共识达成                    │
└─────────────────────────────────────────────────────────────────┘
```

## 🔐 安全性

### 概率性博弈安全

与传统密码学的"代数硬度"不同，因果指纹采用**"统计/博弈硬度"**：

| 特性 | ZKP (代数硬度) | 因果指纹 (博弈硬度) |
|------|---------------|-------------------|
| 防御类型 | 一堵墙 | 充满陷阱的迷宫 |
| 单点故障 | 致命 | 非致命（单个 Agent 被攻破不影响全局） |
| 攻击成本 | 恒定 | 动态增加（随验证维度和节点数指数级上升） |

### 安全强度演进

- **初期 (Day 1-7)**：安全性约 10⁻¹⁰ ~ 10⁻²⁰
- **中期 (Month 1)**：节点数 20+，安全强度达 10⁻⁴⁰
- **成熟期 (Month 6+)**：节点数 50-100，安全性进入 10⁻¹⁰⁰ 区间

## 💡 核心价值

### 解决的问题

1. **黑盒决策可验证性**：证明 AI 决策不是幻觉，而是经过因果逻辑推演
2. **反垄断与多样性**：通过数学手段强制要求节点具备"逻辑熵"
3. **逻辑层面去中心化**：构建"能够自我审计、自我进化、不被大模型厂商绑架"的全球逻辑大脑

### 与原有预言机的区别

| 维度 | 传统预言机 | 因果指纹预言机 |
|------|-----------|--------------|
| 验证对象 | 数据结果 | **因果路径** |
| 抗攻击手段 | 质押削减 + 节点声誉 | **随机因果干预 (do-算子)** |
| 节点关系 | 同质化 | **异构化（逻辑多样性奖励）** |
| 协作模式 | 简单多数投票 | **谱分析主成分聚合** |

## 🛠️ 技术栈

### 后端
- **核心语言**: Rust
- **P2P 网络**: Iroh
- **区块链**: Solana (Anchor 框架)
- **线性代数**: nalgebra (谱分析)

### 智能合约
- **身份注册**: 存储 Agent 全局指纹
- **任务管理**: 发布干预挑战、收集响应
- **聚合验证**: 定点数余弦距离计算

## 📁 项目结构

```
MultiAgentOracle/
├── src/
│   ├── lib.rs                 # 库入口
│   ├── sdk/                   # SDK 便捷层 (新增)
│   │   ├── mod.rs             # SDK 模块入口
│   │   ├── types.rs           # SDK 专用类型
│   │   ├── builder.rs         # 配置构建器
│   │   ├── oracle.rs          # 核心 Oracle 类
│   │   └── solana.rs          # Solana 链上集成
│   ├── oracle_agent/          # 预言机智能体
│   ├── consensus/             # 因果指纹共识引擎
│   ├── reputation/            # 信誉系统（全局指纹）
│   ├── network/               # P2P 网络 (Iroh)
│   └── solana/                # Solana 交互
├── solana-oracle/             # Anchor 智能合约
├── examples/
│   └── sdk_quick_start.rs     # SDK 快速开始示例
├── docs/                      # 详细技术文档
│   ├── Causal Fingerprinting.md  # 因果指纹详解
│   ├── Spectral Analysis.md      # 谱分析实现
│   ├── safety.md                 # 安全性分析
│   └── ...
└── Cargo.toml
```

## 📚 深入了解

详细的技术文档请查看 [docs/](./docs/) 目录：

- [因果指纹实现](./docs/Causal%20Fingerprinting.md) - 核心算法详解
- [谱分析](./docs/Spectral%20Analysis.md) - 特征值提取与供应商检测
- [安全性分析](./docs/safety.md) - 概率安全性证明
- [系统架构](./docs/structure.md) - 三层验证体系
- [价值主张](./docs/value.md) - 市场定位与创新点

## 📄 许可证

MIT License
