Feat/market recovery functions

[armandocodecr]

ISSUE #94

📋 Basic Information

Type of Change

• 🐛 Bug fix
• ✅ New feature
• 💥 Breaking change
• 📝 Documentation update
• 🧪 Test addition/update
• 🔄 Refactoring
• ⚡ Performance improvement
• 🔒 Security fix
• 🎨 UI/UX improvement
• 🚀 Deployment/Infrastructure change

Related Issues
Closes #
Related to recovery mechanisms and market integrity validation.

Priority Level

• 🔴 Critical
• 🟠 High
• 🟡 Medium
• 🔵 Low

📖 Detailed Description

What does this PR do?

Introduces a market recovery system that enables:

• State integrity validation (validate_market_state_integrity).
• Recovering affected markets (recover_market_state).
• Executing safe partial refunds (partial_refund_mechanism).
• Checking recovery status (get_recovery_status).
• Emitting recovery events (emit_recovery_event).
• Persisting recovery history (MarketRecovery) with actions and metrics. Includes automated initial tests (recovery_tests.rs).

Why is this change needed?

Markets can end up in inconsistent states (e.g., imbalances between total_staked and individual stakes). Previously, there was no mechanism to:

• Detect integrity.
• Repair inconsistencies without manual intervention.
• Provide traceability via events.
• Partially refund affected users.

This adds resiliency and facilitates auditing and secure protocol operation.

How was this tested?

Added recovery_tests::test_recovery_mechanisms which:

1. Creates a test market.
2. Invokes integrity validation.
3. Forces recovery execution (if applicable).
4. Executes partial refund.
5. Verifies totals update and recovery status.

• All package tests pass locally (cargo test).

Alternative Solutions Considered

• Store each recovery record with compound symbolic keys. Rejected due to risk of invalid bytes in Symbol.
• Add new specific errors in Error enum. Rejected due to #[contracterror] macro limit.

⚖️ Smart Contract Specific

Contract Changes

• Core contract logic modified
• Oracle integration changes
• New functions added
• Existing functions modified (public exposure in lib.rs)
• Storage structure changes (recovery map and states)
• Events added/modified (ad-hoc recovery event)
• Error handling improved (reuse of existing errors)
• Gas optimization
• Access control changes (reuses existing admin check)
• Admin functions modified
• Fee structure changes

Oracle Integration

• No changes

Market Resolution Logic

• No direct changes to resolution

Security Considerations

• Access control reviewed (only admin for state-changing functions)
• Reentrancy protection (flow similar to others; no external loops or callbacks)
• Input validation (reuses basic market validations)
• Overflow/underflow protection (controlled i128 operations)
• Oracle manipulation protection (not applicable)

🧪 Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• All tests passing locally
• Manual testing completed
• Oracle integration tested
• Edge cases covered (valid market skips recovery)
• Error conditions tested (invalid state triggers skip)
• Gas usage optimized
• Cross-contract interactions tested

Test Results
cargo test
Expected result: all existing tests + new recovery test pass.

Manual Testing Steps

1. Deploy contract in local/sandbox environment.
2. Create a market and manipulate stakes to simulate inconsistency.
3. Invoke recover_market_state.
4. Query get_recovery_status.
5. Verify emitted events.

📚 Documentation

Documentation Updates

• README updated (short note pending)
• Code comments added/updated
• API documentation updated
• Examples updated
• Deployment instructions updated
• Contributing guidelines updated
• Architecture documentation updated

Breaking Changes

• None (non-disruptive addition).

Migration Guide

• No migration required; new storage maps initialize on-demand.

🔍 Code Quality

Code Review Checklist

• Code follows Rust/Soroban best practices
• Self-review completed
• No unnecessary code duplication
• Error handling appropriate (reuse of Error)
• Logging/event emission added
• Security considerations addressed
• Performance implications considered (O(n) operations over existing stakes)
• Code is readable and well-commented
• Variable names are descriptive
• Functions are focused and small

Performance Impact

• Gas Usage: Slight increase only when recovery functions run.
• Storage Impact: Two additional maps (recovery_records, recovery_status_map).
• Computational Complexity: O(k), where k = number of participants with stake when recalculating totals or refunding.

Security Review

• No obvious security vulnerabilities
• Proper access controls (admin gating)
• Input validation in place
• Oracle data properly validated (no interaction)
• No sensitive data exposed

🚀 Deployment & Integration

Deployment Notes

• Network: Testnet recommended for initial trials.
• Contract Address: (fill in after deployment).
• Migration Required: No.
• Special Instructions: Run cargo test before deploying.

Integration Points

• Frontend integration considered (new public methods)
• API changes documented (pending)
• Backward compatibility maintained
• Third-party integrations updated (not applicable)

📊 Impact Assessment

User Impact

• End Users: Greater trust in market integrity.
• Developers: Tooling to debug and stabilize data.
• Admins: Ability to mitigate state corruption.

Business Impact

• Revenue: Indirect (retention and trust).
• User Experience: Improved resilience.
• Technical Debt: Reduced by detecting and repairing inconsistencies.

✅ Final Checklist

Pre-Submission

• Code follows Rust/Soroban best practices
• All CI checks passing (local)
• No breaking changes
• Ready for review
• PR description is complete
• Test results included
• Documentation updated (short note pending)

Review Readiness

• Self-review completed
• Code clean and formatted
• Commit messages clear
• Branch up to date
• No merge conflicts

📸 Screenshots (if applicable)

📂 Additional Resources

• Internal recovery design (logic in recovery.rs)
• Existing events adapted via emit_recovery_event

💬 Notes for Reviewers

Please pay special attention to:

• Storage strategy (double Map).
• Idempotence of recover_market_state when the market is already consistent.
• Security of partial_refund_mechanism (no real fund transfers yet).

Questions for reviewers:

[greatest0fallt1me]

@armandocodecr Great work! Mind resolving the conflicts so we can merge?

[armandocodecr]

@armandocodecr Great work! Mind resolving the conflicts so we can merge?

Done!

[greatest0fallt1me]

@armandocodecr Just a few conflicts to resolve before we can merge. Thanks!

[armandocodecr]

@armandocodecr Just a few conflicts to resolve before we can merge. Thanks!

Done! Again haha