# Oracle Agent参照設計書（Reference Architecture）

- 研究シリーズ: NETSUJO LAB 001 — TRUSTED EXTERNAL DATA
- 対象: ブロックチェーンのオラクル問題
- STATUS: REFERENCE ARCHITECTURE
- STAGE: DESIGN / LOCAL MVP SPECIFICATION
- PRODUCTION DEPLOYMENT: NOT YET
- VERSION: 0.1.0
- 発行: Netsujo株式会社（https://netsujo.jp/web3-lab/blockchain-oracle-problem）
- Author: 飯田友広
- Technical review: Pending

> 本書は研究用の参照設計です。オラクル問題の完全な解決や、外部世界の真実の保証を主張するものではありません。本番資産を扱う運用・経済安全性の証明・BFTの形式検証は本研究の対象外です。

---

## 1. 研究仮説

単一の値を直接オンチェーンへ渡すのではなく、複数ソース、観測時刻、乖離、署名、履歴、判定理由を一つの証拠パッケージとして扱えば、完全な真実保証はできなくても、採用判断の透明性と監査可能性を高められる。

- 研究対象のoracleType: price / weather / inventory / event / generic
- 研究対象外: 経済インセンティブを含むDON全体の安全性証明、Byzantine fault toleranceの形式検証、市場操作耐性の実証、本番資産を扱うオラクル運用、TEE / ZKの実装検証

## 2. 設計原則

1. データソースの多重化
2. 検証過程の記録
3. 人間レビューの挿入余地
4. 署名・監査ログ・hashによる説明責任
5. LLMを真実判定者にしない
6. オンチェーンには最小限の証跡のみ載せる

## 3. アーキテクチャ

```txt
[User / Admin]
      ↓
[Oracle Agent]
      ↓
[Data Source Connectors]
      ↓
[Normalization Layer]
      ↓
[Validation Engine]
      ↓
[Trust Scoring Engine]
      ↓
[Decision Layer]
      ↓
[Output]
  ├─ JSON Record
  ├─ Audit Log
  ├─ Human Review Request
  └─ Blockchain Submission Payload
```

各レイヤーは、入力・処理内容・出力・失敗条件・責任主体を明示して分離する。

| レイヤー | 入力 | 処理 | 出力 | 主な失敗条件 |
|---|---|---|---|---|
| Data Source Connectors | OracleRequest | 各ソースへの取得・raw保存 | SourceResult[] | 取得失敗・タイムアウト・allowlist外 |
| Normalization Layer | SourceResult[] | 単位・型・時刻の正規化 | 正規化済みSourceResult[] | 単位不明・型変換不能 |
| Validation Engine | SourceResult[] | schema / source agreement / freshness / threshold / signature | ValidationResult | 型不一致・必要ソース数不足・許容乖離超過・鮮度超過 |
| Trust Scoring Engine | ValidationResult他 | スコア算出・内訳生成 | TrustScore | 履歴不足時の初期値扱い |
| Decision Layer | TrustScore, policy | approved / needs_human_review / rejectedの判定・理由生成 | OracleDecision | 該当なし（判定は必ず返す） |

## 4. データモデル

### OracleRequest

| フィールド | 型 | 説明 |
|---|---|---|
| id | string | リクエスト識別子 |
| oracleType | 'price' \| 'weather' \| 'inventory' \| 'event' \| 'generic' | データ種別 |
| target | string | 対象（例: ETH/USD） |
| requiredSources | number | 採用に必要な最小ソース数 |
| maxSourceDeviationRate | number | 許容乖離率 |
| freshnessThresholdSec | number | 鮮度閾値（秒） |
| humanReviewThreshold | number | 人間レビューへ回すスコア閾値 |
| createdAt | string (ISO 8601) | 作成時刻 |

### SourceResult

| フィールド | 型 | 説明 |
|---|---|---|
| sourceId / sourceName / sourceType | string | ソース識別情報 |
| value | string | 観測値（精度保持のため文字列） |
| unit | string | 単位 |
| observedAt | string | 元データの観測時刻 |
| fetchedAt | string | 取得時刻（observedAtと必ず区別する） |
| rawData | unknown | raw response（オフチェーン保存のみ） |
| success | boolean | 取得成否 |
| error | string \| null | 失敗理由 |

### ValidationResult

isValid / errors[] / warnings[] / sourceAgreementRate / deviationRate / freshnessOk

### TrustScore

totalScore / sourceDiversityScore / sourceAgreementScore / freshnessScore / historicalReliabilityScore / anomalyPenalty / requiresHumanReview

### OracleDecision

status ('approved' | 'needs_human_review' | 'rejected') / finalValue / trustScore / validation / reason / auditHash / createdAt

## 5. 検証エンジン

1. **Schema Validation** — 外部レスポンスをzodで検証。型・必須項目・日時形式が不正なデータは採用候補から外す。
2. **Source Agreement** — `maxDeviationRate = abs(max - min) / abs(median)`。中央値は平均値より外れ値の影響を受けにくいが、中央値も真実を保証しない。値が0近傍になり得るデータ（気温など）では比率ではなく絶対差の閾値を使う。
3. **Freshness Validation** — `now - observedAt <= freshnessThresholdSec`。fetchedAtが新しくてもobservedAtが古い可能性があるため両者を分離する。
4. **Threshold Validation** — 閾値は用途ごとの設計例（固定ルールではない）:

| oracleType | 許容乖離の例 | 鮮度の例 |
|---|---:|---:|
| price | 0.5〜2.0% | 60〜300秒 |
| weather | 5〜10% | 1800〜3600秒 |
| inventory | 原則0% | 300〜3600秒 |
| event | 0〜5% | 3600秒〜1日 |

上記は参照値。資産規模、更新頻度、障害時の影響、データ取得方式に応じて個別設計が必要。

## 6. 信頼スコア

```txt
totalScore =
  sourceDiversityScore * 0.20 +
  sourceAgreementScore * 0.30 +
  freshnessScore * 0.20 +
  historicalReliabilityScore * 0.20 -
  anomalyPenalty * 0.10
```

| スコア | 判定 |
|---:|---|
| 80以上 | approved |
| 60〜79 | needs_human_review |
| 59以下 | rejected |

この重みと閾値は研究用の参照設計であり、スコアは外部世界の真実を保証しない。用途ごとの損失許容度、データ更新頻度、ソース構成、法的責任に応じた調整が必要。

## 7. 判定フロー

```txt
requiredSourcesを満たすか
  ├─ NO → rejected
  └─ YES
       ↓
schema validationを通過するか
  ├─ NO → rejected
  └─ YES
       ↓
鮮度・乖離・署名に問題があるか
  ├─ HIGH RISK → rejected
  ├─ REVIEWABLE → needs_human_review
  └─ NO → approved候補
       ↓
trust scoreとpolicyを確認
       ↓
OracleDecision生成
```

approvedであっても、重要データではmulti-sigや人間レビューを追加できる設計とする。

## 8. 人間レビュー（ReviewAgent）

レビュー要求には以下を含める: 何が問題か / どのソースが乖離しているか / なぜ自動承認できないか / 承認・再取得・却下の選択肢 / 推奨アクション / 判断者 / 判断時刻 / 判断理由。

## 9. LLM利用境界

- 任せてよい: ソース間差分の説明、人間レビュー向け要約、異常理由の仮説出し、データソース候補の提案、audit logの自然言語化
- 任せてはいけない: 最終的な真偽判定、価格データの生成、APIレスポンスの代替、署名検証の代替、オンチェーン投稿の自動承認

## 10. オンチェーン投稿payload

```json
{
  "requestId": "oracle_20260521_001",
  "oracleType": "price",
  "target": "ETH/USD",
  "value": "3760.12",
  "unit": "USD",
  "observedAt": "2026-05-21T10:00:00Z",
  "trustScore": 87,
  "sourceCount": 3,
  "auditHash": "0x..."
}
```

方針: 投稿者アドレス制限 / payload hash保存 / raw dataはオンチェーンに載せない / オフチェーン監査ログのhashのみ記録 / 重要データはmulti-sig承認 / approved以外は投稿しない。

## 11. 失敗ケーステスト（Failure Test Matrix）

| # | ケース | 期待するvalidation | 期待するdecision | オンチェーン投稿 |
|---:|---|---|---|---|
| 1 | 3ソースのうち1つが極端に乖離 | 乖離超過を検出 | needs_human_reviewまたはrejected | blocked |
| 2 | 取得時刻が古い | freshnessOk = false | rejected | blocked |
| 3 | requiredSources未達 | ソース数不足エラー | rejected | blocked |
| 4 | API取得失敗 | success=falseを除外して再評価 | ソース数次第で判定 | 条件付き |
| 5 | normalizedValue不正 | schema/型エラー | rejected | blocked |
| 6 | trustScoreがレビュー閾値未満 | 検証は通過 | needs_human_review | blocked |
| 7 | approved以外でのpayload投稿 | — | 投稿レイヤーで拒否 | blocked |
| 8 | schema変更 | zod検証エラー | rejected | blocked |
| 9 | 署名欠落 | signature警告/エラー | policy次第でreview/rejected | blocked |
| 10 | allowlist外ドメイン | コネクタ層で拒否 | ソース除外として扱う | blocked |

いずれのケースも、Input / Expected validation / Expected decision / Expected log / On-chain submission（allowed / blocked）を記録する。

## 12. この設計で解決していないこと

- 複数ソースが同じ誤情報を参照する可能性
- 独立して見えるソースが同じ一次ソースに依存する可能性
- 署名は送信者を証明しても内容の真実性までは証明しない
- 人間レビュー担当者が不正・誤判断する可能性
- trust scoreの重みが誤っている可能性
- 突発的な市場変動と攻撃の区別
- オンチェーン反映までの遅延
- 経済インセンティブと談合耐性
- 規制・契約上の責任分界

## 13. 既存オラクルネットワークとの関係

本研究は、既存の分散型オラクルネットワーク（Chainlink、Pyth等）を置き換えるものではない。汎用的な価格フィードや外部計算には既存サービスを利用する方が合理的な場合がある。本参照設計は、企業固有の在庫、イベント、来訪、業務データなど、汎用フィードだけでは扱いにくい外部データの取得・検証・責任分界・監査を整理するためのもの。

## Changelog

- v0.1.0 — Initial reference architecture published

## License

CC BY 4.0（出典明記のうえ再利用可） — © Netsujo株式会社