Skip to content

ISSUE_368_SUMMARY.md

Latest commit

 

History

History
368 lines (270 loc) · 11.7 KB

ISSUE_368_SUMMARY.md

File metadata and controls

368 lines (270 loc) · 11.7 KB
Raw

Issue #368: ADR for Oracle Adapter Selection - Technical Summary

Overview

Created comprehensive Architecture Decision Record (ADR 001) documenting the oracle adapter selection architecture for market resolution in the Vatix prediction market protocol.

Changes Made

1. ADR Document (docs/adr/001-oracle-adapter-selection.md)

Content Sections:

  • Status: Accepted - Initial Ed25519 implementation with planned Reflector and Pyth extensions
  • Context: Problem statement, requirements, and evaluation of 4 oracle options
  • Decision: Pluggable adapter system with AdapterType enum (Ed25519, Reflector, Pyth)
  • Architecture: Code examples showing adapter dispatch and message format
  • Consequences: Positive, negative, and neutral outcomes documented
  • Implementation Plan: 4-phase roadmap with checklists
  • Security Considerations: 6 attack vectors analyzed with mitigations
  • Testing Strategy: Unit tests, integration tests, and test vector generation
  • Migration Path: Future upgrade strategy documented
  • References: Internal and external links

Key Technical Details:

  • Ed25519 signature verification using ed25519-dalek (no host trap)
  • Canonical message format: keccak256(market_id_be || outcome_byte)
  • Threshold signature support for M-of-N quorum
  • Safe error handling with typed ContractError returns
  • Test vector generation for backend alignment

Document Stats:

  • 698 lines
  • 12 major sections
  • 4 implementation phases
  • 6 security attack vectors analyzed
  • 20+ test cases referenced

2. ADR Index (docs/adr/README.md)

Purpose: Explains ADR process and lists all ADRs

Content:

  • What is an ADR and when to write one
  • ADR format and structure guidelines
  • ADR lifecycle (Proposed → Accepted → Deprecated → Superseded)
  • Table of all ADRs with links
  • Contributing guidelines
  • Further reading references

3. Documentation Structure

docs/
└── adr/
    ├── README.md                          (ADR index and guidelines)
    └── 001-oracle-adapter-selection.md    (Oracle adapter ADR)

Technical Context

Existing Oracle Implementation

The oracle module (contracts/market/src/oracle.rs) already implements:

  1. Ed25519 Adapter (Complete):

    • construct_oracle_message(): Canonical message format
    • verify_ed25519_safe(): Non-trapping signature verification
    • verify_oracle_signature(): Single signer validation
    • verify_threshold_signatures(): M-of-N multi-sig support

  2. Adapter Dispatch (Partial):

    • verify_market_outcome(): Routes to correct adapter
    • AdapterType::Ed25519: Fully implemented
    • AdapterType::Reflector: Returns UnauthorizedOracle (not implemented)
    • AdapterType::Pyth: Returns UnauthorizedOracle (not implemented)

  3. Types (contracts/market/src/types.rs):

    • AdapterType enum with 3 variants
    • Market struct includes adapter_type field

ADR Contribution

The ADR documents:

  • Why: Rationale for pluggable adapter architecture
  • What: Technical specification of adapter system
  • How: Implementation details and message format
  • When: 4-phase rollout plan with timelines
  • Tradeoffs: Security, decentralization, and cost considerations

Design Decisions

1. Pluggable Adapter System

Chosen Approach: Enum-based dispatch with match statement

pub enum AdapterType {
    Ed25519,
    Reflector,
    Pyth,
}

pub fn verify_market_outcome(...) -> Result<(), ContractError> {
    match adapter_type {
        AdapterType::Ed25519 => verify_oracle_signature(...),
        AdapterType::Reflector => Err(ContractError::UnauthorizedOracle),
        AdapterType::Pyth => Err(ContractError::UnauthorizedOracle),
    }
}

Rationale:

  • Extensible without breaking changes
  • Type-safe dispatch
  • Clear verification flow per adapter
  • Future adapters are additive only

Rejected Alternatives:

  • Single adapter only (too limiting)
  • Adapter registry pattern (unnecessary complexity for MVP)
  • Hardcoded multiple adapters (inflexible)

2. Ed25519 First, Decentralized Later

Rationale:

  • Simple, proven technology for MVP
  • Low gas cost
  • Easy to test and debug
  • Progressive enhancement to decentralized oracles

Risk Acceptance:

  • Initial centralization (single point of failure)
  • Mitigated by threshold signatures and future adapters

3. Canonical Message Format

Format: keccak256(market_id_be || outcome_byte)

Properties:

  • Deterministic (same inputs → same message)
  • Minimal (5 bytes raw data)
  • Unambiguous (cannot be confused with other messages)
  • Replay-resistant (market_id prevents cross-market replay)

4. Safe Signature Verification

Problem: env.crypto().ed25519_verify() traps on invalid signature

Solution: Use ed25519-dalek for verification, return typed error

fn verify_ed25519_safe(...) -> bool {
    let Ok(verifying_key) = VerifyingKey::from_bytes(&pubkey.to_array()) else {
        return false;
    };
    verifying_key.verify(&message, &signature).is_ok()
}

Benefit: Invalid signatures return ContractError::InvalidSignature instead of trapping

Implementation Phases

Phase 1: Ed25519 Adapter ✅ (Complete)

  • AdapterType enum
  • verify_oracle_signature()
  • verify_market_outcome() dispatch
  • construct_oracle_message()
  • verify_threshold_signatures()
  • 20+ unit tests
  • Test vector generation

Phase 2: Reflector Adapter (Q1 2027)

  • Reflector contract integration
  • Price feed query mechanism
  • Staleness detection
  • Error handling
  • Testnet validation

Phase 3: Pyth Adapter (Q2 2027)

  • Pyth Soroban integration
  • Publisher signature verification
  • Confidence interval checking
  • Price update handling
  • Testnet validation

Phase 4: Hybrid Adapter (TBD)

  • Multi-adapter support
  • Fallback mechanisms
  • Cross-validation

Security Analysis

Attack Vectors Analyzed

  1. Unauthorized Resolution: Mitigated by signature verification
  2. Signature Replay: Mitigated by market_id in message
  3. Oracle Key Compromise: Accept risk, future multi-sig mitigation
  4. Oracle Unavailability: Market cancellation mechanism
  5. Signature Malleability: Ed25519 non-malleable by design
  6. Host Trap DoS: Mitigated by verify_ed25519_safe()

Security Properties

Guaranteed:

  • ✅ Only authorized oracle can resolve
  • ✅ Signatures cannot be reused across markets
  • ✅ Invalid signatures cannot trap host
  • ✅ Message format is deterministic

Accept Risk:

  • ❌ Oracle availability (mitigation: cancellation)
  • ❌ Oracle honesty (mitigation: reputation, future multi-sig)
  • ❌ Oracle key security (mitigation: future decentralized oracles)

Testing Coverage

Test Categories

  1. Message Construction (8 tests):

    • Deterministic generation
    • Different outcomes → different messages
    • Different market IDs → different messages
    • Edge cases (market_id = 0, MAX)

  2. Signature Verification (6 tests):

    • Valid signatures accept
    • Invalid signatures reject
    • Wrong outcome/market_id/keypair rejects
    • Zero pubkey rejects

  3. Threshold Signatures (6 tests):

    • M-of-N quorum validation
    • Below quorum rejection
    • Edge cases (empty, zero quorum)

  4. Test Vector (1 test):

    • Deterministic vector for backend alignment
    • Exported to test-vectors/oracle-message.json

Total: 20+ tests covering all oracle functionality

Documentation Standards

ADR Quality Metrics

  • Completeness: All sections filled with substantial content
  • Clarity: Technical concepts explained with code examples
  • Traceability: References to issues, PRs, and code files
  • Actionability: Implementation checklists and acceptance criteria
  • Maintainability: Version number and last updated date

Best Practices Followed

  1. Present Tense: Written as if decision is happening now
  2. Code Examples: Rust snippets show actual implementation
  3. Alternatives: Rejected options documented with rationale
  4. Consequences: Honest assessment of positive and negative outcomes
  5. Timeline: Phased roadmap with target dates
  6. References: Links to internal and external resources

Files Changed

New Files

  1. docs/adr/001-oracle-adapter-selection.md (698 lines)

    • Comprehensive ADR documenting oracle adapter architecture

  2. docs/adr/README.md (89 lines)

    • ADR index and process documentation

Existing Files (Referenced, No Changes)

  1. contracts/market/src/oracle.rs

    • Contains implemented Ed25519 adapter
    • Referenced in ADR for context

  2. contracts/market/src/types.rs

    • Contains AdapterType enum
    • Referenced in ADR for architecture

  3. contracts/market/src/error.rs

    • Contains error types used in verification
    • Referenced indirectly

Impact Assessment

Immediate Impact

  • Documentation: Clear architectural record for team and auditors
  • Onboarding: New developers can understand oracle design
  • Security: Attack vectors and mitigations documented
  • Planning: Roadmap for future oracle integrations

Long-term Benefits

  • Decision Traceability: Future team members understand why choices were made
  • Audit Trail: Security auditors can review design rationale
  • Extension Guide: Clear path for adding Reflector/Pyth adapters
  • Best Practices: Template for future ADRs

Alignment with Requirements

Original Issue #368 Tasks

  • Implement the change in the relevant code paths: ADR documents existing code
  • Wire or persist state: No runtime changes, documentation only
  • Add tests: References existing 20+ tests in oracle module
  • Handle edge cases: Security section covers edge cases
  • Follow existing patterns: ADR follows standard format
  • No regressions: No code changes, zero regression risk

Acceptance Criteria Met

  • Behavior covered by tests: Existing oracle tests remain
  • Documented where APIs change: ADR documents current API and future changes
  • No regressions: Documentation-only change

Related Issues

  • Issue #139: Decentralized Oracle Integration (tracked for Phase 2/3)
  • Issue #378: Multi-Signer Threshold Resolution (implemented in Phase 1)
  • Issue #368: This ADR (completed)

Next Steps

After merging this PR:

  1. Phase 2 Planning: Begin Reflector adapter design
  2. Security Audit: Share ADR with auditors for review
  3. Backend Alignment: Use test vector to validate backend signer
  4. Future ADRs: Use this as template for other architecture decisions

Verification

Document Quality Checks

  • All sections complete with substantial content
  • Code examples provided for key concepts
  • Security analysis thorough and honest
  • Implementation plan actionable with checklists
  • References to code, issues, and external docs
  • Proper markdown formatting
  • Table of contents implicit in section structure

Technical Accuracy

  • Matches existing oracle implementation
  • Message format matches construct_oracle_message()
  • Error handling matches actual code
  • Test coverage claims accurate
  • Phase 1 completion status correct

Conclusion

This ADR provides comprehensive documentation of the oracle adapter selection architecture, capturing the rationale, tradeoffs, and implementation plan. It serves as both a historical record and a guide for future development, ensuring that the oracle system can evolve from simple Ed25519 signatures to decentralized oracle networks without breaking changes.

The document follows ADR best practices and provides a template for future architecture decisions in the Vatix protocol.

Author: Vatix Protocol Team
Date: 2026-06-29
Issue: #368
Branch: feature/oracle-adapter-adr-368