1use std::collections::VecDeque;
12use std::ops::Range;
13
14use sui_sdk_types::Object;
15use sui_sdk_types::framework::EventBatch;
16use sui_sdk_types::framework::EventCommitment;
17use sui_sdk_types::framework::EventStreamHead;
18use sui_sdk_types::framework::apply_stream_updates;
19
20use super::envelope::AuthenticatedEvent;
21use crate::light_client::error::LightClientError;
22use crate::light_client::error::MmrMismatch;
23
24#[derive(Debug, Default)]
35pub(super) struct StreamState {
36 pub buffer: VecDeque<AuthenticatedEvent>,
46
47 pub local_head: EventStreamHead,
51
52 pub confirmed_through: u64,
56
57 pub events_scanned_through: u64,
68}
69
70impl StreamState {
71 pub(super) fn new(initial_head: EventStreamHead, confirmed_through: u64) -> Self {
72 Self {
73 buffer: VecDeque::new(),
74 local_head: initial_head,
75 confirmed_through,
76 events_scanned_through: confirmed_through,
77 }
78 }
79
80 pub(super) fn has_complete_buffered_events(&self) -> bool {
84 self.buffer
85 .front()
86 .is_some_and(|event| event.checkpoint <= self.events_scanned_through)
87 }
88
89 pub(super) fn complete_unconfirmed_checkpoints(&self) -> Option<Range<u64>> {
94 (self.events_scanned_through > self.confirmed_through).then(|| {
95 self.confirmed_through.saturating_add(1)..self.events_scanned_through.saturating_add(1)
96 })
97 }
98}
99
100pub(super) fn apply_stream_frame(
115 state: &mut StreamState,
116 event: Option<AuthenticatedEvent>,
117 covered_checkpoint: Option<u64>,
118) -> bool {
119 if let Some(covered) = covered_checkpoint {
120 state.events_scanned_through = state.events_scanned_through.max(covered);
121 }
122 match event {
123 Some(event) => {
124 state.buffer.push_back(event);
125 false
126 }
127 None => state
128 .buffer
129 .back()
130 .is_some_and(|event| event.checkpoint <= state.events_scanned_through),
131 }
132}
133
134pub(super) fn fold_and_reconcile(
159 state: &mut StreamState,
160 settlements: &[(u64, u64)],
161 chain_head: EventStreamHead,
162 reconcile_checkpoint: u64,
163) -> Result<Vec<AuthenticatedEvent>, LightClientError> {
164 let last_settlement =
168 settlements
169 .last()
170 .copied()
171 .ok_or(LightClientError::UnexpectedObjectShape {
172 reason: "fold_and_reconcile called with no settlements; \
173 reconciliation needs at least one settlement to anchor the chain head",
174 })?;
175 if last_settlement.0 != reconcile_checkpoint {
176 return Err(LightClientError::UnexpectedObjectShape {
177 reason: "settlement boundaries disagree with reconciliation checkpoint",
178 });
179 }
180 if reconcile_checkpoint > state.events_scanned_through {
181 return Err(LightClientError::UnexpectedObjectShape {
182 reason: "reconciliation checkpoint is past the checkpoints the event stream \
183 has claimed complete",
184 });
185 }
186
187 let fold_count = state
192 .buffer
193 .iter()
194 .take_while(|e| e.checkpoint <= reconcile_checkpoint)
195 .count();
196
197 let batches = bucket_events_by_settlement(
198 state.buffer.iter().take(fold_count),
199 settlements,
200 state.confirmed_through,
201 )?;
202
203 let new_head =
204 apply_stream_updates(state.local_head.clone(), &batches).map_err(LightClientError::from)?;
205
206 if new_head != chain_head {
207 return Err(LightClientError::MmrMismatch(Box::new(MmrMismatch {
208 checkpoint: reconcile_checkpoint,
209 expected: chain_head,
210 actual: new_head,
211 })));
212 }
213
214 state.local_head = new_head;
217 state.confirmed_through = reconcile_checkpoint;
218 let released: Vec<AuthenticatedEvent> = state.buffer.drain(..fold_count).collect();
219 Ok(released)
220}
221
222fn bucket_events_by_settlement<'a, I>(
233 events: I,
234 settlements: &[(u64, u64)],
235 floor_checkpoint: u64,
236) -> Result<Vec<EventBatch>, LightClientError>
237where
238 I: IntoIterator<Item = &'a AuthenticatedEvent>,
239{
240 let mut batches: Vec<EventBatch> = Vec::new();
241 let mut current_key: Option<(u64, u64)> = None;
242 let mut settlement_idx: usize = 0;
243
244 for event in events {
245 if event.checkpoint <= floor_checkpoint {
249 continue;
250 }
251
252 while settlement_idx < settlements.len()
255 && (settlements[settlement_idx].0 < event.checkpoint
256 || (settlements[settlement_idx].0 == event.checkpoint
257 && settlements[settlement_idx].1 < event.transaction_index))
258 {
259 settlement_idx += 1;
260 }
261
262 if settlement_idx >= settlements.len() || settlements[settlement_idx].0 != event.checkpoint
263 {
264 return Err(LightClientError::UnexpectedObjectShape {
269 reason: "no settlement transaction covering buffered event",
270 });
271 }
272
273 let settlement_key = settlements[settlement_idx];
274 let commitment = EventCommitment {
275 checkpoint_seq: event.checkpoint,
276 transaction_idx: event.transaction_index,
277 event_idx: event.event_index as u64,
278 digest: event.event.digest(),
279 };
280
281 match current_key {
282 Some(key) if key == settlement_key => {
283 batches
284 .last_mut()
285 .expect("current_key set ⇒ at least one batch exists")
286 .commitments
287 .push(commitment);
288 }
289 _ => {
290 batches.push(EventBatch {
291 checkpoint_seq: event.checkpoint,
292 commitments: vec![commitment],
293 });
294 current_key = Some(settlement_key);
295 }
296 }
297 }
298
299 Ok(batches)
300}
301
302pub(super) fn extract_event_stream_head(
324 object: &Object,
325) -> Result<EventStreamHead, LightClientError> {
326 const HEAD_OFFSET: usize = 64;
327
328 let move_struct = object
329 .as_struct()
330 .ok_or(LightClientError::UnexpectedObjectShape {
331 reason: "expected a Move struct (dynamic field), got a package",
332 })?;
333 let contents = move_struct.contents();
334 let head_bytes =
335 contents
336 .get(HEAD_OFFSET..)
337 .ok_or(LightClientError::UnexpectedObjectShape {
338 reason: "dynamic-field contents too short for EventStreamHead value",
339 })?;
340 bcs::from_bytes(head_bytes).map_err(LightClientError::from)
341}
342
343#[cfg(test)]
344mod tests {
345 use super::*;
346 use sui_sdk_types::Address;
347 use sui_sdk_types::Digest;
348 use sui_sdk_types::Event;
349 use sui_sdk_types::Identifier;
350 use sui_sdk_types::StructTag;
351 use sui_sdk_types::U256;
352
353 fn sample_event(checkpoint: u64, tx_idx: u64, event_idx: u32) -> AuthenticatedEvent {
354 AuthenticatedEvent {
355 checkpoint,
356 transaction_index: tx_idx,
357 event_index: event_idx,
358 transaction_digest: Digest::new([0xaa; 32]),
359 event: Event {
360 package_id: Address::TWO,
361 module: Identifier::from_static("m"),
362 sender: Address::TWO,
363 type_: StructTag::new(
364 Address::TWO,
365 Identifier::from_static("m"),
366 Identifier::from_static("E"),
367 vec![],
368 ),
369 contents: vec![checkpoint as u8, tx_idx as u8, event_idx as u8],
370 },
371 }
372 }
373
374 fn expected_chain_head(
379 events: &[AuthenticatedEvent],
380 settlements: &[(u64, u64)],
381 ) -> EventStreamHead {
382 let batches = bucket_events_by_settlement(events.iter(), settlements, 0).unwrap();
383 apply_stream_updates(EventStreamHead::default(), &batches).unwrap()
384 }
385
386 fn u256_from_decimal(s: &str) -> U256 {
387 s.parse().expect("decimal U256 literal must parse")
388 }
389
390 fn buffer_complete(
393 state: &mut StreamState,
394 events: Vec<AuthenticatedEvent>,
395 covered_checkpoint: u64,
396 ) {
397 for event in events {
398 apply_stream_frame(state, Some(event), None);
399 }
400 apply_stream_frame(state, None, Some(covered_checkpoint));
401 }
402
403 #[test]
407 fn apply_stream_frame_defers_folding() {
408 let mut state = StreamState::new(EventStreamHead::default(), 0);
409 buffer_complete(
410 &mut state,
411 vec![sample_event(7, 0, 0), sample_event(7, 0, 1)],
412 7,
413 );
414
415 assert_eq!(state.local_head, EventStreamHead::default());
416 assert_eq!(state.buffer.len(), 2);
417 assert_eq!(state.events_scanned_through, 7);
418 }
419
420 #[test]
423 fn apply_stream_frame_does_not_regress_scan_floor() {
424 let mut state = StreamState::new(EventStreamHead::default(), 0);
425 state.events_scanned_through = 20;
426 apply_stream_frame(&mut state, None, Some(5));
427 assert_eq!(state.events_scanned_through, 20);
428 }
429
430 #[test]
437 fn checkpoint_is_complete_only_once_claimed() {
438 let first_half = vec![sample_event(10, 0, 0), sample_event(10, 1, 0)];
439 let second_half = vec![sample_event(10, 3, 0)];
440 let all_events: Vec<_> = first_half.iter().chain(&second_half).cloned().collect();
441 let settlements = vec![(10u64, 4u64)];
442 let chain_head = expected_chain_head(&all_events, &settlements);
443
444 let mut state = StreamState::new(EventStreamHead::default(), 9);
445 assert!(!apply_stream_frame(&mut state, None, Some(9)));
448
449 for event in first_half {
452 assert!(!apply_stream_frame(&mut state, Some(event), Some(9)));
453 }
454 assert!(!apply_stream_frame(&mut state, None, Some(9)));
457 assert!(!apply_stream_frame(&mut state, None, None));
458
459 assert_eq!(state.events_scanned_through, 9);
460 assert!(!state.has_complete_buffered_events());
461 assert_eq!(state.complete_unconfirmed_checkpoints(), None);
462 let err = fold_and_reconcile(&mut state, &settlements, chain_head.clone(), 10).unwrap_err();
465 assert!(matches!(
466 err,
467 LightClientError::UnexpectedObjectShape { .. }
468 ));
469 assert_eq!(state.buffer.len(), 2);
470 assert_eq!(state.confirmed_through, 9);
471 assert_eq!(state.local_head, EventStreamHead::default());
472
473 for event in second_half {
475 assert!(!apply_stream_frame(&mut state, Some(event), None));
476 }
477 assert!(apply_stream_frame(&mut state, None, Some(10)));
478
479 assert!(state.has_complete_buffered_events());
480 assert_eq!(state.complete_unconfirmed_checkpoints(), Some(10..11));
481 let released =
482 fold_and_reconcile(&mut state, &settlements, chain_head.clone(), 10).unwrap();
483 assert_eq!(released, all_events);
484 assert_eq!(state.local_head, chain_head);
485 assert_eq!(state.confirmed_through, 10);
486 assert!(state.buffer.is_empty());
487 }
488
489 #[test]
492 fn fold_and_reconcile_single_settlement_per_checkpoint() {
493 let events = vec![
494 sample_event(7, 0, 0),
495 sample_event(7, 0, 1),
496 sample_event(7, 1, 0),
497 ];
498 let settlements = vec![(7u64, 2u64)];
499
500 let chain_head = expected_chain_head(&events, &settlements);
501
502 let mut state = StreamState::new(EventStreamHead::default(), 0);
503 buffer_complete(&mut state, events.clone(), 7);
504
505 let released = fold_and_reconcile(&mut state, &settlements, chain_head.clone(), 7).unwrap();
506
507 assert_eq!(released, events);
508 assert_eq!(state.local_head, chain_head);
509 assert_eq!(state.confirmed_through, 7);
510 assert!(state.buffer.is_empty());
511 }
512
513 #[test]
519 fn fold_and_reconcile_multiple_settlements_per_checkpoint() {
520 let events = vec![
521 sample_event(10, 0, 0),
522 sample_event(10, 1, 0),
523 sample_event(10, 3, 0),
524 ];
525 let settlements = vec![(10u64, 2u64), (10u64, 4u64)];
527
528 let chain_head = expected_chain_head(&events, &settlements);
529
530 let mut state = StreamState::new(EventStreamHead::default(), 0);
531 buffer_complete(&mut state, events.clone(), 10);
532
533 let single_batch = apply_stream_updates(
537 EventStreamHead::default(),
538 &[EventBatch {
539 checkpoint_seq: 10,
540 commitments: events
541 .iter()
542 .map(|e| EventCommitment {
543 checkpoint_seq: e.checkpoint,
544 transaction_idx: e.transaction_index,
545 event_idx: e.event_index as u64,
546 digest: e.event.digest(),
547 })
548 .collect(),
549 }],
550 )
551 .unwrap();
552 assert_ne!(single_batch, chain_head);
553
554 let released =
555 fold_and_reconcile(&mut state, &settlements, chain_head.clone(), 10).unwrap();
556
557 assert_eq!(released, events);
558 assert_eq!(state.local_head, chain_head);
559 assert_eq!(state.confirmed_through, 10);
560 }
561
562 #[test]
566 fn fold_and_reconcile_keeps_unfolded_tail_buffered() {
567 let events = vec![
568 sample_event(5, 0, 0),
569 sample_event(5, 0, 1),
570 sample_event(9, 0, 0), ];
572 let settlements = vec![(5u64, 0u64)];
575
576 let cp5_events: Vec<_> = events.iter().take(2).cloned().collect();
580 let chain_head_at_5 = expected_chain_head(&cp5_events, &settlements);
581
582 let mut state = StreamState::new(EventStreamHead::default(), 0);
583 buffer_complete(&mut state, events.clone(), 9);
584
585 let released =
586 fold_and_reconcile(&mut state, &settlements, chain_head_at_5.clone(), 5).unwrap();
587
588 assert_eq!(released, cp5_events);
589 assert_eq!(state.local_head, chain_head_at_5);
590 assert_eq!(state.confirmed_through, 5);
591 assert_eq!(state.buffer.len(), 1);
592 assert_eq!(state.buffer.front().unwrap().checkpoint, 9);
593 }
594
595 #[test]
599 fn fold_and_reconcile_rejects_divergence_without_mutating_observable_state() {
600 let events = vec![sample_event(3, 0, 0)];
601 let settlements = vec![(3u64, 0u64)];
602 let bogus = EventStreamHead {
603 mmr: vec![u256_from_decimal("999")],
604 checkpoint_seq: 3,
605 num_events: 1,
606 };
607
608 let mut state = StreamState::new(EventStreamHead::default(), 0);
609 buffer_complete(&mut state, events.clone(), 3);
610 let pre_local_head = state.local_head.clone();
611 let pre_buffer_len = state.buffer.len();
612 let pre_confirmed = state.confirmed_through;
613
614 let err = fold_and_reconcile(&mut state, &settlements, bogus.clone(), 3).unwrap_err();
615 assert!(matches!(err, LightClientError::MmrMismatch(_)));
616
617 assert_eq!(state.local_head, pre_local_head);
618 assert_eq!(state.buffer.len(), pre_buffer_len);
619 assert_eq!(state.confirmed_through, pre_confirmed);
620 }
621
622 #[test]
627 fn fold_and_reconcile_rejects_empty_settlements() {
628 let mut state = StreamState::new(EventStreamHead::default(), 0);
629 let err = fold_and_reconcile(&mut state, &[], EventStreamHead::default(), 0).unwrap_err();
630 assert!(matches!(
631 err,
632 LightClientError::UnexpectedObjectShape { .. }
633 ));
634 }
635
636 #[test]
640 fn fold_and_reconcile_rejects_misaligned_reconcile_checkpoint() {
641 let settlements = vec![(5u64, 0u64)];
642 let mut state = StreamState::new(EventStreamHead::default(), 0);
643 let err = fold_and_reconcile(&mut state, &settlements, EventStreamHead::default(), 7)
644 .unwrap_err();
645 assert!(matches!(
646 err,
647 LightClientError::UnexpectedObjectShape { .. }
648 ));
649 }
650
651 #[test]
656 fn fold_and_reconcile_rejects_event_without_matching_settlement() {
657 let events = vec![sample_event(5, 0, 0)];
659 let settlements = vec![(7u64, 0u64)];
660 let mut state = StreamState::new(EventStreamHead::default(), 0);
661 buffer_complete(&mut state, events, 7);
662
663 let err = fold_and_reconcile(&mut state, &settlements, EventStreamHead::default(), 7)
664 .unwrap_err();
665 assert!(matches!(
666 err,
667 LightClientError::UnexpectedObjectShape { .. }
668 ));
669 }
670
671 #[test]
679 fn extract_event_stream_head_skips_uid_and_key_prefix() {
680 use sui_sdk_types::Object;
681 use sui_sdk_types::ObjectData;
682 use sui_sdk_types::Owner;
683 use sui_sdk_types::Version;
684 use sui_sdk_types::framework::derive_event_stream_head_object_id;
685
686 let head = EventStreamHead {
687 mmr: vec![U256::ZERO, U256::ONE],
688 checkpoint_seq: 17,
689 num_events: 5,
690 };
691 let stream_id = Address::TWO;
692
693 let mut contents = Vec::new();
697 let uid = derive_event_stream_head_object_id(stream_id);
698 contents.extend_from_slice(uid.as_bytes());
699 contents.extend_from_slice(stream_id.as_bytes());
700 contents.extend(bcs::to_bytes(&head).unwrap());
701
702 let move_struct = sui_sdk_types::MoveStruct::new(
703 StructTag::new(
704 Address::TWO,
705 Identifier::from_static("dynamic_field"),
706 Identifier::from_static("Field"),
707 vec![],
708 ),
709 true,
710 Version::from(1u64),
711 contents,
712 )
713 .expect("contents are at least 32 bytes");
714 let object = Object::new(
715 ObjectData::Struct(move_struct),
716 Owner::Address(Address::ZERO),
717 Digest::new([0; 32]),
718 0,
719 );
720
721 let recovered = extract_event_stream_head(&object).unwrap();
722 assert_eq!(recovered, head);
723 }
724
725 #[test]
728 fn extract_event_stream_head_rejects_non_struct() {
729 use sui_sdk_types::MovePackage;
730 use sui_sdk_types::Object;
731 use sui_sdk_types::ObjectData;
732 use sui_sdk_types::Owner;
733 use sui_sdk_types::Version;
734
735 let pkg = MovePackage {
736 id: Address::TWO,
737 version: Version::from(1u64),
738 modules: Default::default(),
739 type_origin_table: Vec::new(),
740 linkage_table: Default::default(),
741 };
742 let object = Object::new(
743 ObjectData::Package(pkg),
744 Owner::Immutable,
745 Digest::new([0; 32]),
746 0,
747 );
748
749 let err = extract_event_stream_head(&object).unwrap_err();
750 assert!(matches!(
751 err,
752 LightClientError::UnexpectedObjectShape { .. }
753 ));
754 }
755}