feat: add per-topic replay nonce to EventEmitter

[probablyABug]

Pull Request Description

📋 Basic Information

Type of Change

• 🐛 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 #674

Priority Level

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

---

📝 Detailed Description

What does this PR do?

Adds replay-protection support to EventEmitter by introducing a monotonic per-topic nonce. Every emitted event now includes a nonce: u64 field that increments independently for each event topic, allowing downstream consumers to safely deduplicate events when cross-contract retries or fallback execution paths emit the same logical event multiple times.

Why is this change needed?

Cross-contract retries and batch fallback mechanisms may legitimately execute the same event emission logic more than once. Without a deterministic replay identifier, downstream indexers and applications cannot reliably distinguish duplicate emissions from new events.

This change provides an efficient, deterministic replay-protection mechanism while maintaining topic isolation and minimal storage overhead.

How was this tested?

• Added dedicated unit tests for per-topic nonce behavior.
• Verified nonce increments monotonically for repeated emissions on the same topic.
• Verified different topics maintain independent nonce sequences.
• Verified emitted event payloads include the expected nonce value.
• Executed the targeted test suite:

cargo test -p predictify-hybrid event_replay_nonce

Alternative Solutions Considered

Alternative approaches such as timestamp-based identifiers and transaction-hash-based deduplication were considered. These approaches either cannot guarantee monotonic ordering or depend on external execution context.

A persistent per-topic counter provides deterministic ordering, low storage overhead, and straightforward consumer-side deduplication.

---

🏗️ Smart Contract Specific

Contract Changes

• 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 -p predictify-hybrid event_replay_nonce

test event_replay_nonce::increments_nonce_per_topic ... ok
test event_replay_nonce::maintains_topic_isolation ... ok

test result: all tests passed

Manual Testing Steps

1. Emit two consecutive events using the same topic.
2. Verify the emitted payload contains incrementing nonce values.
3. Emit an event for a different topic and verify its nonce begins independently.

---

📚 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 migration is required. Event consumers may optionally begin using the new nonce field for replay detection and deduplication.

Documentation notes that nonce state is reset only after a contract upgrade.

---

🔍 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 additional storage read/write for nonce maintenance.
• Storage Impact: One persistent EventNonce(topic) entry maintained per event topic.
• Computational Complexity: Constant-time (O(1)) nonce lookup and increment.

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: Consumers may optionally update event parsers to read and persist the new nonce field.

Integration Points

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

---

📊 Impact Assessment

User Impact

• End Users: No direct user-facing changes.
• Developers: Gain deterministic replay protection for emitted events.
• Admins: No operational changes.

Business Impact

• Revenue: None.
• User Experience: Improves reliability of downstream event processing.
• Technical Debt: Reduces ambiguity around duplicate event emissions during retries.

---

✅ 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: Event replay protection design notes
• Technical Spec: Per-topic replay nonce implementation
• Related Discussion: Issue Add events.rs replay protection nonce in EventEmitter to dedup retried emissions #674
• External Documentation: Soroban Events documentation

---

💬 Notes for Reviewers

Please pay special attention to:

• Monotonic nonce generation across repeated emissions.
• Topic isolation using DataKey::EventNonce(topic).
• Event payload compatibility with downstream consumers.
• Upgrade behavior and nonce reset documentation.

Questions for reviewers:

• Does the event payload expose sufficient information for downstream deduplication?
• Is the documented contract-upgrade reset behavior consistent with project expectations?

---

Thank you for your contribution to Predictify!

[drips-wave]

@probablyABug 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

[greatest0fallt1me]

Merged — thanks for jumping on this one!