Task/deprecated registry

[muhsar27]

Closes #748

---

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

(No specific issue linked)

Priority Level

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

---

📝 Detailed Description

What does this PR do?

This PR implements a centralised, compile-time registry for deprecated contract entrypoints (DeprecatedRegistry in deprecated.rs), mirroring the EventSchemaRegistry pattern. It:

1. Replaces scattered, ad-hoc emit_deprecated calls in lib.rs with a single, unified registry routing (emit_if_deprecated).
2. Adds a new list_deprecated read-only entrypoint so off-chain callers can query all deprecated functions, their recommended replacements, and planned removal versions programmatically.
3. Adds comprehensive documentation in docs/DEPRECATED.md.

Why is this change needed?

Previously, deprecated functions lacked a single source of truth for their replacements, deprecation dates, and planned removal versions. This made it difficult for consumers and indexers to discover and migrate away from obsolete entrypoints. This registry solves that by providing all metadata in one place.

How was this tested?

Added 11 focused unit tests in deprecated.rs that cover:

• Lookups for known and unknown functions (including edge cases like empty strings).
• Correctness of predicates (is_deprecated).
• Verification that all registered entries have unique names and non-empty replacements.
• Safe no-op execution when attempting to emit events for non-deprecated names.

Alternative Solutions Considered

We considered storing the registry in contract storage, but chose a compile-time unit struct with Symbols. This ensures the registry remains zero-cost at rest, requires no storage reads, and consumes minimal gas.

---

🏗️ Smart Contract Specific

Contract Changes

Please check all that apply:

• Core contract logic modified
• Oracle integration changes (Pyth/Reflector)
• New functions added (list_deprecated)
• Existing functions modified (verify_result, resolve_market)
• Storage structure changes
• Events added/modified (centralised routing for DeprecatedCall events)
• 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 (safe no-op execution for unknown string inputs)
• Overflow/underflow protection
• Oracle manipulation protection

---

🧪 Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• All tests passing locally (Note: Blocked by pre-existing unrelated build failures in edge_cases and disputes)
• Manual testing completed
• Oracle integration tested
• Edge cases covered (empty strings, unknown modules)
• Error conditions tested
• Gas usage optimized
• Cross-contract interactions tested

Test Results

cargo test -p predictify-hybrid -- deprecated
# Tests for deprecated module are successfully authored, but execution is blocked by pre-existing compilation errors in other modules (e.g. `edge_cases`, `disputes`).

Manual Testing Steps

1. Visual verification of lib.rs syntax to ensure DeprecatedRegistry::emit_if_deprecated safely replaces emit_deprecated.
2. Verified docs/DEPRECATED.md aligns precisely with the new code registry.

---

📚 Documentation

Documentation Updates

• README updated
• Code comments added/updated (Extensive NatSpec-style rustdocs added to deprecated.rs)
• API documentation updated (DEPRECATED.md added)
• Examples updated
• Deployment instructions updated
• Contributing guidelines updated
• Architecture documentation updated

Breaking Changes

Breaking Changes:

• None. This is a non-breaking additive feature and refactor of internal event emission.

Migration Guide:

• Review docs/DEPRECATED.md to see the new recommended replacements for verify_result and resolve_market.

---

🔍 Code Quality

Code Review Checklist

• Code follows Rust/Soroban best practices
• Self-review completed
• No unnecessary code duplication
• Error handling is appropriate (Safe fallbacks implemented)
• 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: Negligible. The registry uses Symbol types and operates entirely at compile-time with O(1) matching. No heap allocations for standard lookups.
• Storage Impact: Zero. The registry performs no storage reads or writes.
• Computational Complexity: O(1) for lookups.

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: (TBD)
• Migration Required: No
• Special Instructions: None.

Integration Points

• Frontend integration considered (Frontend can now call list_deprecated to alert users of upcoming breaking changes dynamically).
• API changes documented
• Backward compatibility maintained
• Third-party integrations updated

---

📊 Impact Assessment

User Impact

• End Users: No direct impact.
• Developers: Massive improvement in discovering obsolete functions and their correct replacements.
• Admins: Better visibility into the contract deprecation lifecycle.

Business Impact

• Revenue: No impact.
• User Experience: Improved developer experience (DX).
• Technical Debt: Significantly reduces technical debt by establishing a unified pattern for retiring legacy endpoints.

---

✅ Final Checklist

Pre-Submission

• Code follows Rust/Soroban best practices
• All CI checks passing (Note: Repo-wide CI currently broken due to pre-existing missing modules)
• 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

---

💬 Notes for Reviewers

Please pay special attention to:

• The use of Symbol instead of String in DeprecatedEntrypoint to enforce zero-cost abstraction at rest.
• The removal_version field currently defaults to "TBD" across all entries.

Questions for reviewers:

---

Thank you for your contribution to Predictify! 🚀