Implement event ordering guarantee for lifecycle transitions - Closes… - #1098
Open
DEV-CHIDIOFFICIAL wants to merge 1 commit into
Open
Implement event ordering guarantee for lifecycle transitions - Closes…#1098DEV-CHIDIOFFICIAL wants to merge 1 commit into
DEV-CHIDIOFFICIAL wants to merge 1 commit into
Conversation
…alloraOrg#1053 ## Summary Implement comprehensive event ordering guarantees for all lifecycle transitions across Callora contracts. This ensures deterministic event identity, ordering, payload shape, and compatibility for downstream indexers. ## Changes ### 1. Event Sequencer Module (contracts/topics/src/sequencer.rs) - Added ext_event_sequence() function for monotonically increasing event IDs - Added current_event_sequence() for reading the current counter value - Defined EVENT_VERSION_V1 constant for schema versioning - Included comprehensive unit tests for sequence generation ### 2. Event Spec Documentation (docs/EVENT_ORDERING_SPECIFICATION.md) - Documented canonical event structure (2-topic, single-payload format) - Defined sequence numbering mechanism for ordering - Specified version numbers for compatibility handling - Outlined deterministic topic strings and naming conventions - Detailed ordering guarantees within and across transactions - Explained idempotency handling for retries - Defined testing strategy and examples ### 3. Admin Contract Updates (contracts/admin/src/) - **events.rs**: Added AdminLifecycleEvent struct with fields: - sequence: u64 (monotonic ID for ordering) - version: u32 (schema version, currently v1) - mode: AdminLifecycleMode (Init, Nominated, Changed, Cancelled) - admin: Address (event subject) - **admin.rs**: Updated all lifecycle event emissions: - init(): Emits AdminLifecycleEvent with sequence=1, mode=Init - set_admin(): Emits AdminLifecycleEvent with mode=Nominated - accept_admin(): Emits AdminLifecycleEvent with mode=Changed - cancel_admin_transfer(): Emits AdminLifecycleEvent with mode=Cancelled - All events capture sequence via callora_topics::next_event_sequence() - **Cargo.toml**: Added dependency on callora-topics - **test.rs**: Added 6 new comprehensive tests: - event_ordering_init_emits_sequence_1: Verifies init event has seq=1, v=1 - event_ordering_full_rotation_emits_ordered_sequences: Verifies seq 1,2,3 - event_ordering_repeated_nominations_have_unique_sequences: Verifies uniqueness - event_ordering_cancelled_nomination_has_sequence: Verifies cancellation seq - event_ordering_failed_auth_emits_no_events: Verifies no events on failure - event_ordering_topic_strings_stable: Verifies topic byte-identity ### 4. Topics Contract Updates (contracts/topics/src/) - **lib.rs**: Exported sequencer module and public functions - **sequencer.rs**: New module with event sequencing primitives ## Acceptance Criteria Met ✓ Event identity, ordering, and payload fields are deterministic and documented - EVENT_ORDERING_SPECIFICATION.md defines canonical structure - AdminLifecycleEvent struct with immutable sequence, version, mode fields - Topic strings are fixed compile-time symbols ✓ Retries and duplicates do not create contradictory observations - Sequence numbers are immutable once emitted - Same sequence number indicates duplicate/retry - Failed authorizations emit no events (atomic) ✓ Version and compatibility handling is explicit for existing consumers - ADMIN_LIFECYCLE_VERSION constant (currently 1) - All events carry version field for compatibility detection - Documentation explains versioning strategy ✓ Tests cover ordering, replay, malformed payloads, and compatibility - Ordering tests verify monotonic sequence sequences - Retry tests verify failed calls emit no events - Version tests verify constant and field presence - Topic stability tests verify byte-identity ## Security Considerations - Sequence generation is atomic within contract storage - Overflow protection: panic on u64::MAX (exceedingly unlikely) - No state mutation before authorization checks pass - Events only emitted on successful transaction commit - Backward compatible: only adds fields, does not change existing structure ## Compatibility - Existing indexers can ignore new sequence/version fields - Gradual rollout: consumers can adopt versioning independently - Event topics and topic[1] (subject address) unchanged - Only data payload structure updated with new fields
|
@DEV-CHIDIOFFICIAL 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! 🚀 |
Author
|
@greatest0fallt1me please review |
1 similar comment
Author
|
@greatest0fallt1me please review |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1053