feat: implement Real Estate Oracle Integration System #36

[CMI-James]

Description

Implement Real Estate Oracle Integration System for Property Valuations

Closes #36

Changes proposed

What were you told to do?

I was tasked with implementing a comprehensive real estate oracle system to provide real-time property valuations for the PropChain ecosystem. The requirements included:

• Designing a standardized oracle interface compatible with Chainlink, Pyth, and Substrate price feeds.
• Implementing a property valuation request/response mechanism.
• Adding support for multiple oracle sources for price consensus.
• Creating an oracle reputation and slashing system.
• Implementing historical price tracking and trend analysis.
• Adding failure detection and fallback mechanisms (staleness and source count).
• Including gas-efficient batch valuation requests.
• Providing data validation and anomaly detection.

What did I do?

1. Designed standardized Traits (contracts/traits/src/lib.rs):

   • Created #[ink::trait_definition] for Oracle and OracleRegistry.
   • Added OracleSourceType Supporting Chainlink, Pyth, and Substrate feeds.
   • Defined structured types: PropertyValuation, ValuationWithConfidence, and OracleSource.

2. Implemented the Core Oracle Logic (contracts/oracle/src/lib.rs):

   • Multi-Source Aggregation: Implemented a weighted average model combined with statistical filtering (2-sigma outlier detection).
   • Trust Management: Developed a Reputation System (0-1000 score) that tracks success/failure and automatically deactivates underperforming sources.
   • Slashing System: Added logic to penalize staked funds for malicious or inaccurate data reports.
   • Request Lifecycle: Implemented request_property_valuation with pending request tracking to handle asynchronous oracle updates.
   • Batching: Added batch_request_valuations to reduce gas costs for protocol-wide updates.

3. Integrated with Property Registry (contracts/lib/src/lib.rs):

   • Added oracle connectivity to the PropertyRegistry storage.
   • Implemented set_oracle and update_valuation_from_oracle to bridge property tokens with real-time market data.

4. Enhanced Security & Validation:

   • Anomaly Detection: Flags price changes >20% if they don't align with historical market volatility.
   • Staleness Checks: Prevents the consumption of outdated price data.
   • Fallback Mechanism: Ensures a minimum source count before a price is considered valid for the protocol.

5. Ensured Code Quality & Documentation:

   • Added comprehensive unit tests for aggregation, reputation, slashing, and batching.
   • Updated contracts/oracle/README.md with full API reference and architectural overviews.
   • Verified that the source code compiles and passes local tests.

Check List

• My code follows the code style of this project.
• This PR does not contain plagiarized content.
• The title and description of the PR is clear and explains the approach.
• I am making a pull request against the main/dev branch.
• My commit messages styles matches our requested structure.
• My code additions will fail neither code linting checks nor unit test.
• I am only making changes to files I was requested to.

Testing Evidence

• test_aggregate_prices_works: Verified weighted average and basic filtering.
• test_filter_outliers_works: Confirmed 2-sigma exclusion of extreme data points.
• test_source_reputation_works: Validated score increases/decreases based on performance.
• test_slashing_works: Verified stake deductions and secondary reputation hits.
• test_anomaly_detection_works: Confirmed flagging of suspicious price spikes.
• test_batch_request_works: Validated concurrent pending request state management.