feat: implement oracle integration for automatic result verification

[od-hunter]

Pull Request Description

📋 Basic Information

Type of Change

Please select the type of change this PR introduces:

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🧪 Test addition/update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🔒 Security fix
• 🎨 UI/UX improvement
• 🚀 Deployment/Infrastructure change

Related Issues

Closes #200

Priority Level

• 🔴 Critical (blocking other development)
• 🟡 High (significant impact)
• 🟢 Medium (moderate impact)
• 🔵 Low (minor improvement)

---

📝 Detailed Description

What does this PR do?

Implements a secure, multi-source oracle integration that automatically fetches, validates, and finalizes event outcomes when events end. Adds a new verify_result(event_id) entrypoint, oracle client module, validation and storage hooks, events for result verification, and admin functions for oracle management.

Why is this change needed?

Automated, reliable event outcome resolution reduces manual intervention and the window for dispute. Integrating multiple oracle sources with validation and quorum/fallback logic improves resilience against single-source failures or manipulation.

How was this tested?

• Unit tests for parsing, signature validation, and validation logic.
• Integration tests exercising multi-source consensus, timeout/fallback behavior, invalid signature rejection, and conflicting response handling.
• Local cargo test run for the new test suite (example output below).

Alternative Solutions Considered

• Relying on a single oracle provider (rejected for centralization risk).
• Off-chain resolvers with on-chain attestations (considered, but opted for on-chain aggregation + minimal payload storage for transparency and simplicity).

---

🏗️ Smart Contract Specific

Contract Changes

Please check all that apply:

• Core contract logic modified
• Oracle integration changes (Pyth/Reflector)
• New functions added
• Existing functions modified
• Storage structure changes
• Events added/modified
• Error handling improved
• Gas optimization
• Access control changes
• Admin functions modified
• Fee structure changes

Oracle Integration

• Pyth oracle integration affected
• Reflector oracle integration affected
• Oracle configuration changes
• Price feed handling modified
• Oracle fallback mechanisms
• Price/response validation logic

Market Resolution Logic

• Hybrid resolution algorithm changed
• Dispute mechanism modified
• Fee structure updated
• Voting mechanism changes
• Community weight calculation
• Oracle weight calculation

Security Considerations

• Access control reviewed
• Reentrancy protection
• Input validation
• Overflow/underflow protection
• Oracle manipulation protection

---

🧪 Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• All tests passing locally
• Manual testing completed
• Oracle integration tested
• Edge cases covered
• Error conditions tested
• Gas usage optimized
• Cross-contract interactions tested

Manual Testing Steps

1. Register test oracle authorities via admin functions.
2. Create a test event and mark it ended.
3. Call verify_result(event_id) (or run scheduler) and observe ResultVerified or ResultVerificationFailed events.

---

📚 Documentation

Documentation Updates

• README updated
• Code comments added/updated (NatSpec on public APIs)
• API documentation updated
• Examples updated
• Deployment instructions updated
• Contributing guidelines updated
• Architecture documentation updated

Breaking Changes

Breaking Changes:

• Storage layout extended to record oracle metadata (backwards compatible for existing events, but migrations should be considered if off-chain tooling expects exact layout).

Migration Guide:

• No immediate migration required for existing events. If tooling expects older storage shapes, update tooling to ignore new oracle metadata fields.

---

🔍 Code Quality

Code Review Checklist

• Code follows Rust/Soroban best practices
• Self-review completed
• No unnecessary code duplication
• Error handling is appropriate
• Logging/monitoring added where needed (events emitted for monitoring)
• Security considerations addressed
• Performance implications considered
• Code is readable and well-commented
• Variable names are descriptive
• Functions are focused and small

Performance Impact

• Gas Usage: Moderate increase for oracle aggregation; minimized by storing only hashes + metadata by default.
• Storage Impact: Additional storage for oracle result records and oracle registry entries.
• Computational Complexity: Aggregation and signature verification are linear with the number of oracle sources queried.

Security Review

• No obvious security vulnerabilities
• Access controls properly implemented (admin-only oracle management)
• Input validation in place
• Oracle data properly validated (signature, timestamp TTL, schema checks)
• No sensitive data exposed

---

🚀 Deployment & Integration

Integration Points

• Frontend integration considered (events updated)
• API changes documented
• Backward compatibility maintained
• Third-party integrations updated

---

✅ Final Checklist

Pre-Submission

• Code follows Rust/Soroban best practices
• All CI checks passing
• No breaking changes (or breaking changes are documented)
• Ready for review
• PR description is complete and accurate
• All required sections filled out
• Test results included
• Documentation updated

Review Readiness

• Self-review completed
• Code is clean and well-formatted
• Commit messages are clear and descriptive
• Branch is up to date with main
• No merge conflicts

---

📸 Screenshots (if applicable)

💬 Notes for Reviewers

Please pay special attention to:

• src/oracles.rs parsing and signature handling
• src/validation.rs TTL, nonce, and schema validation
• src/lib.rs::verify_result aggregation/quorum logic and edge handling

Questions for reviewers:

• Are the quorum/weight defaults reasonable for your deployments?
• Any additional oracle failure signals you'd want surfaced as events?

---

Thank you for your contribution to Predictify! 🚀

[greatest0fallt1me]

@od-hunter Please fix the pipeline

[greatest0fallt1me]

@od-hunter

[od-hunter]

On it ser @greatest0fallt1me