feat: implemented graceful degradation

[davedumto]

Pull Request Description

closes #73

📋 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

Fixes oracle reliability issues when external oracle services become unavailable or fail.

Priority Level

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

---

📝 Detailed Description

What does this PR do?

Adds a simple oracle backup system so markets don't get stuck when the primary oracle fails. If the main oracle is down, it automatically tries a backup oracle.

Why is this change needed?

Currently, markets become unresolvable when oracle services fail with no backup mechanism. This leaves markets permanently stuck and users unable to claim winnings. The backup system provides automatic failover to ensure market resolution reliability.

How was this tested?

• 4 unit tests covering backup creation, health checks, and partial resolution
• Integration with existing Reflector oracle
• Timeout handling for slow oracles
• Event emission for monitoring

Alternative Solutions Considered

• Simple retry mechanism - Rejected due to lack of fallback capability
• Manual intervention only - Rejected due to poor user experience
• Cache-based fallback - Considered but kept as future enhancement for 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 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

Test Results

cargo test graceful_degradation --quiet
running 4 tests
....
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 194 filtered out; finished in 0.00s

Manual Testing Steps

1. Created backup with Reflector primary + Pyth fallback
2. Simulated primary oracle failure - automatic fallback triggered
3. Tested timeout handling - proper event emission after 60s
4. Validated partial resolution with confidence thresholds
5. Verified event emission for monitoring integration
6. Confirmed health status transitions (Working → Broken)

---

📚 Documentation

Documentation Updates

• README updated
• Code comments added/updated
• API documentation updated
• Examples updated
• Deployment instructions updated
• Contributing guidelines updated
• Architecture documentation updated

Breaking Changes

Breaking Changes:
None - All new functionality is additive

Migration Guide:

No migration required. Existing oracle calls continue to work unchanged.

---

🔍 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
• 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: Minimal increase only when fallback is triggered (~5-10% for backup oracle call)
• Storage Impact: Small increase for backup configuration (~50 bytes per market)
• Computational Complexity: O(1) for health checks, O(2) for fallback attempts

Security Review

• No obvious security vulnerabilities
• Access controls properly implemented
• Input validation in place
• Oracle data properly validated
• No sensitive data exposed

---

🚀 Deployment & Integration

Deployment Notes

• Network: Ready for Testnet and Mainnet
• Contract Address: No changes to existing addresses
• Migration Required: No
• Special Instructions: Configure backup oracle addresses in deployment

Integration Points

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

---

📊 Impact Assessment

User Impact

• End Users: Markets no longer get permanently stuck due to oracle failures
• Developers: New API endpoints available for oracle health monitoring
• Admins: Enhanced visibility into oracle health and automatic failover

Business Impact

• Revenue: Prevents revenue loss from unresolvable markets
• User Experience: Significantly improved market reliability
• Technical Debt: Reduces manual intervention requirements

---

✅ 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)

N/A - Backend contract changes only

🔗 Additional Resources

• Design Document: Simple oracle backup for reliability
• Technical Spec: OracleBackup struct with primary/backup providers
• Related Discussion: Oracle reliability improvements
• External Documentation: Soroban SDK oracle patterns

---

💬 Notes for Reviewers

Please pay special attention to:

• Oracle timeout handling logic in handle_oracle_timeout()
• Event emission patterns in backup scenarios
• Health status state transitions
• Integration with existing oracle interface

Questions for reviewers:

• Should we add configurable timeout values per oracle type?
• Any concerns about the 70% confidence threshold for partial resolution?
• Would you like additional backup strategies beyond the 2 implemented?

---

Thank you for your contribution to Predictify! 🚀

[greatest0fallt1me]

@davedumto Conflicts detected, please resolve when you get a chance. Thanks!

[greatest0fallt1me]

@davedumto Any updates?

[davedumto]

Hey I'll fix the conflict tonight

[greatest0fallt1me]

LGTM!