Feature/monitoring hooks

[Tola-byte]

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 #445
Fixes #445
Related to #445

Priority Level

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

---

📝 Detailed Description

What does this PR do?

Adds indexer-observable monitoring hooks for critical lifecycle transitions:

1. Introduces transition hook types/events in monitoring.rs:

• TransitionDomain
• TransitionHookEvent
• ContractMonitor::emit_resolution_transition_hook
• ContractMonitor::emit_dispute_transition_hook
• ContractMonitor::emit_pause_transition_hook

2. Wires hooks into runtime transitions:

• Resolution transitions in resolution.rs
  • timeout cancellation transition
  • automated resolution transition
• Dispute lifecycle in disputes.rs
  • dispute created
  • dispute resolved
• Pause lifecycle in circuit_breaker.rs
  • paused
  • manual unpause/recovery
  • auto-recovery unpause

3. Adds regression tests in monitoring.rs to assert emitted indexer events for each domain.

4. Updates gas/ops docs with indexer hook topic/payload guidance in docs/gas/GAS_MONITORING.md.

Why is this change needed?

Previously, critical transitions were not uniformly observable via emitted indexer-friendly hooks. This made off-chain monitoring/indexing unreliable for:

• market resolution transitions,
• dispute lifecycle changes,
• contract pause/unpause states.

This PR guarantees explicit event emission for those transitions.

How was this tested?

• Focused test run:

cargo +stable test -p predictify-hybrid monitoring::tests:: -- --nocapture

• Full suite:

cargo +stable test -p predictify-hybrid
# result: ok. 275 passed; 0 failed

Alternative Solutions Considered

• Emitting all events generically from EventEmitter::store_event.
• Rejected: would broaden behavior unexpectedly across many event types and reduce reviewability for this targeted issue.

---

🏗️ 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 +stable test -p predictify-hybrid
# test result: ok. 275 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Manual Testing Steps

1. Emit each hook directly in monitoring tests (resolution, dispute, pause) and verify event stream increments.
2. Run full crate test suite to ensure no regression.
3. Verify docs describe topics/payload for indexers.

---

📚 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

Migration Guide:

• No contract/storage migration required.

---

🔍 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: Slight increase only on transition paths due extra event publish.
• Storage Impact: None from new hooks (event stream only).
• Computational Complexity: Constant overhead per monitored transition.

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: N/A
• Migration Required: No
• Special Instructions: Indexers should subscribe to idx_transition topic root.

Integration Points

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

---

📊 Impact Assessment

User Impact

• End Users: No UX/API breakage.
• Developers: Easier off-chain indexing of resolution/dispute/pause transitions.
• Admins: Better observability of pause/recovery and dispute lifecycle operations.

Business Impact

• Revenue: Neutral.
• User Experience: Indirectly improved via better monitoring/alerting.
• Technical Debt: Reduced observability gaps.

---

✅ 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

🔗 Additional Resources

• Design Document: N/A
• Technical Spec: GAS_MONITORING.md
• Related Discussion: Monitoring hooks for transitions #445
• External Documentation: N/A

---

💬 Notes for Reviewers

Please pay special attention to:

• Hook emission points in:
  • resolution.rs
  • disputes.rs
  • circuit_breaker.rs
• Hook schema/topic stability in:
  • monitoring.rs

Questions for reviewers:

• Should we also add equivalent hook emissions for manual/admin resolution flows in lib.rs wrappers for complete symmetry?

---

Security Notes (for PR body addendum)

• Threat model: indexers missing critical state transitions creates monitoring blind spots and delayed incident response.
• Invariants proven:
  • resolution transitions emit idx_transition/resolution
  • dispute transitions emit idx_transition/dispute
  • pause transitions emit idx_transition/pause
• Explicit non-goals:
  • no payout formula changes
  • no storage layout migration
  • no change to access control policy

[drips-wave]

@Tola-byte 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