Skip to content

PR_277_DESCRIPTION.md

Latest commit

 

History

History
163 lines (136 loc) · 6.59 KB

PR_277_DESCRIPTION.md

File metadata and controls

163 lines (136 loc) · 6.59 KB
Raw

PR for Issue #277: Oracle consumer expectations for commitment_core/marketplace

Summary

This PR implements oracle consumer expectation functions in the price_oracle contract to provide specialized validation and safety checks for commitment_core and marketplace contract integration. The implementation defines clear expectations and validation patterns for consumer contracts.

Changes Made

New Oracle Consumer Functions Added

1. get_price_for_commitment()

  • Purpose: Specialized price validation for commitment_core operations
  • Features:
    • 5-minute maximum staleness (stricter than default 1 hour)
    • Optional price variation percentage validation (prevents flash manipulation)
    • Positive price validation
  • Use Case: Commitment creation, settlement, and value updates

2. get_price_for_marketplace()

  • Purpose: Price validation optimized for marketplace operations
  • Features:
    • 30-minute maximum staleness (operational flexibility)
    • Minimum USD price validation (prevents zero-price attacks)
    • Decimal conversion support for cross-decimal comparisons
  • Use Case: NFT listings, offers, and marketplace transactions

3. get_batch_prices()

  • Purpose: Efficient multi-asset price queries
  • Features:
    • Single-call validation for multiple assets
    • Configurable staleness per batch
    • Gas optimization for portfolio operations
  • Use Case: Portfolio valuation, multi-asset commitments

4. get_price_for_high_value_operation()

  • Purpose: Enhanced validation for high-value operations
  • Features:
    • Dynamic staleness based on operation value
    • Stricter validation for >$1,000 operations (1-minute staleness)
    • Additional safety checks for >$10,000 operations
  • Use Case: Large settlements, high-value transfers

5. get_oracle_health()

  • Purpose: Oracle system health monitoring
  • Features:
    • Health status reporting
    • Configuration transparency
    • Consumer-friendly monitoring interface
  • Use Case: Pre-operation health checks, fallback triggers

New Data Structures

  • OracleHealth: Struct for health status reporting
    • is_healthy: Boolean health indicator
    • max_staleness_seconds: Current configuration
    • last_check: Last health check timestamp
    • active_oracles_count: Active oracle count (extensible)

Security Enhancements

Manipulation Resistance

  • Price Variation Checks: Prevents flash manipulation attacks
  • Staleness Tiers: Different requirements based on operation risk
  • Value-Based Validation: Stricter controls for high-value operations
  • Health Monitoring: Early detection of oracle issues

Consumer Protection

  • Clear Error Handling: Specific error types for different failure modes
  • Graceful Degradation: Fallback mechanisms for stale data
  • Configurable Parameters: Consumers can adjust validation strictness
  • Comprehensive Documentation: Security notes and usage guidelines

Test Coverage Impact

New Test Functions (12 total)

  • test_get_price_for_commitment_fresh(): Basic commitment price validation
  • test_get_price_for_commitment_stale(): Staleness rejection
  • test_get_price_for_commitment_excessive_variation(): Price manipulation prevention
  • test_get_price_for_marketplace_valid(): Marketplace price validation
  • test_get_price_for_marketplace_below_minimum(): Minimum price enforcement
  • test_get_price_for_marketplace_different_decimals(): Cross-decimal support
  • test_get_batch_prices_success(): Multi-asset validation
  • test_get_batch_prices_one_stale(): Batch failure handling
  • test_get_price_for_high_value_operation_normal_value(): Value-based staleness
  • test_get_price_for_high_value_operation_high_value(): High-value validation
  • test_get_price_for_high_value_operation_very_high_value_stale(): Very high-value strictness
  • test_get_oracle_health(): Health monitoring
  • test_oracle_consumer_functions_edge_cases(): Input validation
  • test_oracle_consumer_integration_scenario(): End-to-end integration

Test Scenarios Covered

  1. Fresh Data Validation: All functions with current prices
  2. Staleness Rejection: Proper failure with old data
  3. Price Manipulation: Variation percentage enforcement
  4. Value-Based Tiers: Different staleness for operation values
  5. Batch Operations: Multi-asset efficiency and partial failures
  6. Edge Cases: Zero prices, negative values, invalid inputs
  7. Integration Scenarios: Realistic usage patterns

Consumer Integration Guidance

For commitment_core Contracts

// Recommended usage for commitment operations
let price_data = oracle_client.get_price_for_commitment(
    &asset_address,
    Some(10) // 10% max price variation
)?;

For marketplace Contracts

// Recommended usage for marketplace operations
let price_data = oracle_client.get_price_for_marketplace(
    &asset_address,
    Some(1_00000000) // $1 minimum USD price
)?;

For High-Value Operations

// Recommended usage for high-value operations
let price_data = oracle_client.get_price_for_high_value_operation(
    &asset_address,
    operation_value_usd,
    5 // 5% max deviation
)?;

Configuration Recommendations

Commitment Operations

  • Staleness: 5 minutes (300 seconds)
  • Price Variation: 5-15% depending on asset volatility
  • Health Checks: Before critical operations

Marketplace Operations

  • Staleness: 30 minutes (1800 seconds)
  • Minimum Prices: Asset-specific minimums
  • Batch Queries: For portfolio operations

High-Value Operations

  • Thresholds: >$100 uses 5-minute, >$1,000 uses 1-minute
  • Additional Validation: Consider multi-source verification
  • Circuit Breakers: Automatic pause on suspicious patterns

Files Modified

  • contracts/price_oracle/src/lib.rs: Added consumer expectation functions
  • contracts/price_oracle/src/tests.rs: Comprehensive test coverage

Security Documentation

  • Threat Model: Updated with consumer expectations
  • Manipulation Resistance: Multi-layer validation approach
  • Fail-Safe Design: Graceful degradation and error handling
  • Audit Trail: Clear documentation of security assumptions

Verification

All new functions pass comprehensive test coverage including:

  • Functional correctness with valid inputs
  • Proper error handling with invalid inputs
  • Edge case coverage (boundary conditions)
  • Integration scenario testing
  • Performance characteristics (gas optimization)

This implementation provides a robust foundation for commitment_core and marketplace contracts to consume oracle data safely and efficiently, with clear expectations and comprehensive error handling.