feat: oracle fail-closed on stale data + stable error mappings

[Chris-P-web]

Closes #1392, Closes #1411

#1392 — Oracle resolution fail-closed on stale data

Problem

resolve_with_median's fetch_quote helper silently absorbed OracleStale errors by marking the stale quote as included=false. This allowed resolution to proceed on fewer sources than intended when staleness was the cause of exclusion — a fail-open behaviour that could produce incorrect outcomes from insufficient fresh data.

Additionally, ReflectorOracle::get_price_data used the current ledger timestamp as publish_time when the oracle returned no data (mock fallback path), which bypassed staleness validation entirely.

Fix

• Added fetch_quote_fail_closed() to OracleResolutionManager: this variant checks publish_time against the configured staleness threshold before returning a quote. If the data is stale, it returns Err(Error::OracleStale) which aborts the entire resolution rather than silently excluding the source.
• Updated resolve_with_median to use fetch_quote_fail_closed() for all three oracle sources (Pyth, Reflector, Band). Non-stale unavailability (oracle offline, feed not found) still produces included=false so the min_sources check remains effective.
• Fixed ReflectorOracle::get_price_data: in non-test builds, when the on-chain oracle returns None, the function now returns Err(Error::OracleUnavailable) instead of a mock price with publish_time=now. Test builds retain the mock path but the publish_time is set clearly.
• Emits emit_oracle_validation_failed event on stale detection so operators can diagnose which oracle was stale without reading state.

#1411 — Stable error mappings for client integrations

Problem

The Error enum had no stable off-chain mapping for client SDKs. Clients were forced to rely on the raw discriminant value (e.g. 202 for OracleStale), which can shift if a new variant is inserted between existing ones. The error_code_tests.rs required client_code() and recoverability() methods that did not yet exist.

Fix

• Added Error::client_code() -> u32: stable, category-partitioned numeric codes that must never change once assigned. Ranges: Oracle 1000-1099, Market 1100-1199, Validation 1200-1299, Financial 1300-1399, Dispute 1400-1499, Auth 1500-1599, CircuitBreaker 1600-1699, System 1700-1799, UserOp 1800-1899, Metadata 1900-1999.
• Added Error::recoverability() -> Recoverability: labels each variant as Retryable | RequiresAdmin | Terminal so client SDKs can implement retry policies without maintaining their own mapping table.
• Fixed OperationWouldExceedBudget discriminant: moved from 418 to 444 to restore AdminNotSet = 418 as frozen by err_stability.rs.
• Fixed StorageTtlPressure: replaced Val field (incompatible with #[contracttype]) with String key_repr field.
• Fixed oracles.rs test structs: added missing auto_pause_duration_secs field to GlobalOracleValidationConfig initialisers in test code.

Tests

• tests/oracle_fail_closed_and_error_codes.rs: 22 new focused tests covering range validation, uniqueness, stability pinning, recoverability labels, and oracle-stale error surface behaviour.
• All 7 err_stability tests pass.
• All 15 proptest_fee tests pass.
• Library builds cleanly (cargo build -p predictify-hybrid).

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 #(issue number)
Fixes #(issue number)
Related to #(issue number)

Priority Level

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

---

📝 Detailed Description

What does this PR do?

Why is this change needed?

How was this tested?

Alternative Solutions Considered

---

🏗️ 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

# Paste test output here
cargo test
# Expected output: X tests passed, Y tests failed

Manual Testing Steps

---

📚 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:

Migration Guide:

---

🔍 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:
• Storage Impact:
• Computational Complexity:

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: Testnet/Mainnet
• Contract Address:
• Migration Required: Yes/No
• Special Instructions:

Integration Points

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

---

📊 Impact Assessment

User Impact

• End Users:
• Developers:
• Admins:

Business Impact

• Revenue:
• User Experience:
• Technical Debt:

---

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

🔗 Additional Resources

• Design Document:
• Technical Spec:
• Related Discussion:
• External Documentation:

---

💬 Notes for Reviewers

Please pay special attention to:

Questions for reviewers:

---

Thank you for your contribution to Predictify! 🚀

Closes #1392, Closes #1411

[drips-wave]

@Chris-P-web Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits