[4.2] Pyth Oracle Integration (on-chain) — 0xfave

[0xfave]

Summary

Implements Ticket 4.2 — Pyth Oracle Integration for the FluxDEX on-chain program. Zero new crate dependencies, zero [patch] sections, zero clippy warnings.

What changed

New file: src/oracle.rs (457 lines)

• Raw Pyth V2 price account parser with dynamic aggregate offset (HEADER_SIZE + num × COMP_SIZE) — works on real feeds with 25+ publishers
• 9 unit tests covering magic/type rejection, confidence ratio, staleness, zero publishers, multi-publisher offset correctness, and price normalization

Modified: src/instruction.rs

• MatchOrdersAccounts gains optional oracle_price: Option<&AccountView> (8th account)
• Accepts 7 (backward-compatible) or 8 accounts

Modified: src/processor.rs

• match_orders() validates oracle (confidence ≤ 5%, staleness ≤ 60 s), caches oracle_price + oracle_timestamp to Market account
• PMM effective price computed from inventory skew when PMM is configured
• Three-tier fallback: valid oracle → PMM / valid oracle no PMM → CLOB / invalid or missing → CLOB

Modified: tests/flux_dex_tests.rs

• match_orders_ix_with_oracle() — helper with optional 8th oracle account
• setup_pyth_oracle() — builds a correctly formed mock Pyth V2 price account
• 3 integration tests:
  • Valid oracle: orders fill + price cached in Market
  • Stale oracle: trade succeeds (advisory fallback)
  • No oracle: 7-account layout still works

Key design decisions

Decision	Rationale
Dynamic offset (48 + num × 96)	Hardcoded offsets from prior attempt would parse garbage on real feeds with publishers
Optional oracle in MatchOrdersAccounts	Backward-compatible — existing 7-account callers unchanged
No oracle in PlaceOrder	Oracle is only needed during matching, not order placement
Always cache to Market	Frontend reads oracle price from Market, no separate Pyth subscription needed
Clamped skew [-100%, +100%]	Prevents extreme PMM price deviation

Verification

• cargo test-sbf: 119 tests pass (44 unit + 75 integration)
• cargo clippy -- -D warnings: 0 warnings (only pre-existing edition2024 feature notice)
• cargo build-sbf: clean build

Closes #33