Skip to main content

sui_rpc/light_client/events/
state.rs

1//! Pure verification helpers for the streaming client.
2//!
3//! Factored out of the spawned task so they can be unit-tested without
4//! standing up an RPC harness. The streaming task in `client` calls
5//! [`apply_stream_frame`] for each frame of the ledger event stream and
6//! [`fold_and_reconcile`] each reconciliation round — passing in the
7//! settlement boundaries fetched from `ListTransactions(affected_object =
8//! event_stream_head)` so events are folded into the local MMR in the
9//! same per-settlement partitions the framework used on chain.
10
11use 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/// In-memory state the streaming task carries across frames of the
25/// ledger event stream and reconciliation rounds.
26///
27/// Events are buffered (not folded) as they arrive: the framework can
28/// run multiple `settle_events` transactions per checkpoint (one per
29/// consensus commit per stream), and folding events into the wrong
30/// settlement bucket produces an MMR shape that will never match the
31/// on-chain head. The buffer is flushed at reconciliation time, once
32/// `ListTransactions(affected_object = event_stream_head)` has surfaced
33/// the per-settlement boundaries.
34#[derive(Debug, Default)]
35pub(super) struct StreamState {
36    /// Events received from the ledger event stream but not yet folded
37    /// into [`Self::local_head`]. Once a reconciliation round succeeds,
38    /// every entry with `checkpoint <= reconciled_checkpoint` is folded
39    /// into the local MMR, released to the consumer, and drained from
40    /// this queue.
41    ///
42    /// Items are stored in receipt order — which matches strictly
43    /// ascending `(checkpoint, transaction_index, event_index)` per the
44    /// v2 List API contract.
45    pub buffer: VecDeque<AuthenticatedEvent>,
46
47    /// The MMR head we've replayed by folding the settlement-partitioned
48    /// event batches. Compared byte-for-byte against the on-chain head
49    /// during reconciliation.
50    pub local_head: EventStreamHead,
51
52    /// The most recent checkpoint at which `local_head` was confirmed
53    /// to match the on-chain head. Subsequent reconciliations only need
54    /// to fold events landed strictly after this point.
55    pub confirmed_through: u64,
56
57    /// Highest checkpoint the ledger event stream has claimed complete:
58    /// the highest `covered_checkpoint` seen on its frames. Every
59    /// matching event at a checkpoint `<=` this value has been received.
60    ///
61    /// This is the only source of checkpoint completeness. The position
62    /// of the last received event says nothing about whether the rest
63    /// of its checkpoint has been delivered, so it never advances this
64    /// value. Reconciliation folds only checkpoints at or below it:
65    /// folding a checkpoint whose events have not all been received
66    /// produces an MMR that can never match the on-chain head.
67    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    /// True if the buffer holds at least one event at a checkpoint the
81    /// ledger event stream has claimed complete, so a reconciliation
82    /// round could fold and release it.
83    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    /// The unconfirmed checkpoints the ledger event stream has claimed
90    /// complete, `(confirmed_through, events_scanned_through]`, as the
91    /// half-open `[start, end)` range the settlement listing takes.
92    /// `None` when that range is empty.
93    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
100/// Apply one frame of the ledger event stream to `state`: buffer its
101/// event, if any, and advance `state.events_scanned_through` to the
102/// frame's `covered_checkpoint` claim when that claim is higher.
103///
104/// Events must arrive in strictly ascending
105/// `(checkpoint, transaction_index, event_index)` order — the ledger
106/// event stream guarantees this, and the fold-time partitioner relies
107/// on it.
108///
109/// Returns `true` when the frame is progress-only (`event` is `None`),
110/// events are buffered, and the stream's claim covers every one of
111/// them: the stream has caught up with the server, so the buffered
112/// events are ready to be reconciled and released without waiting for
113/// the next periodic reconciliation.
114pub(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
134/// Partition the events at the front of `state.buffer` by settlement,
135/// fold each partition into `state.local_head`, and reconcile the
136/// updated head against `chain_head` at the last settlement's
137/// checkpoint.
138///
139/// `settlements` is the ascending sequence of `(checkpoint,
140/// transaction_index)` pairs from `ListTransactions(affected_object =
141/// event_stream_head)`, covering `(state.confirmed_through,
142/// reconcile_checkpoint]`. `reconcile_checkpoint` is the checkpoint at
143/// which `chain_head` was authenticated — by construction the
144/// checkpoint of the last entry in `settlements`. It must not exceed
145/// `state.events_scanned_through`: a checkpoint the ledger event stream
146/// has not claimed complete may still be missing events.
147///
148/// Each event in the partitioned prefix is assigned to the next
149/// settlement whose `(cp, tx_offset)` lies at-or-after the event's
150/// position, and a settlement reject is a hard error (it indicates the
151/// stream's `ListEvents` and `ListTransactions` indexes have diverged).
152///
153/// On a matching reconciliation: drains the folded events from
154/// `state.buffer`, advances `state.confirmed_through` to
155/// `reconcile_checkpoint`, and returns the released events in receipt
156/// order. On any mismatch: returns the error without mutating the
157/// observable parts of `state` — the caller should abort the stream.
158pub(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    // Settlements must be non-empty and the last one's checkpoint must
165    // equal the reconciliation point — that's the load-bearing invariant
166    // the caller is contracted to uphold.
167    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    // Count the buffered events whose checkpoint lies at or below the
188    // reconciliation point — these are the ones we'll partition and
189    // fold. Anything past `reconcile_checkpoint` stays buffered for the
190    // next round.
191    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    // Reconciliation succeeded: commit the fold and drain the released
215    // events.
216    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
222/// Bucket `events` into per-settlement [`EventBatch`]es using the
223/// ascending `settlements` boundary list. Returns an empty `Vec` only if
224/// `events` is empty after the `floor_checkpoint` filter — every kept
225/// event must map to a settlement at its own checkpoint, or the function
226/// errors.
227///
228/// Mirrors the upstream e2e helper that drives the on-chain
229/// reconciliation: each event maps to the first settlement with `(cp ==
230/// event.cp, tx_offset >= event.tx_offset)`, and events sharing a
231/// settlement key form a single batch.
232fn 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        // Skip events that fall at-or-below the floor — those have
246        // already been folded into `state.local_head` by an earlier
247        // reconciliation (or are part of the initial-state head).
248        if event.checkpoint <= floor_checkpoint {
249            continue;
250        }
251
252        // Advance to the first settlement at-or-past the event's
253        // ledger position.
254        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            // The framework guarantees a `settle_events` transaction
265            // for every checkpoint that emitted events on this stream;
266            // a missing settlement means the server's event index and
267            // transaction index have diverged.
268            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
302/// Extract the BCS-encoded [`EventStreamHead`] out of an on-chain
303/// `Object` returned by the OCS inclusion proof flow.
304///
305/// The framework stores each stream head as the value of a dynamic
306/// field on the accumulator root object. The Move-side type is
307/// `sui::dynamic_field::Field<sui::accumulator::Key<EventStreamHead>,
308/// EventStreamHead>`, which BCS-serializes as:
309///
310/// ```text
311/// field = uid key value
312///
313/// uid   = address                 ; 32 bytes (Field.id)
314/// key   = address                 ; 32 bytes (AccumulatorKey { owner: address })
315/// value = bytes-of-EventStreamHead
316/// ```
317///
318/// Both the UID and the single-field-struct `AccumulatorKey` are
319/// fixed 32-byte addresses, so the head's BCS bytes start at offset
320/// 64. We BCS-decode just the tail rather than parsing through the
321/// dynamic-field wrapper to keep this independent of any generic
322/// `Field<K, V>` representation in the SDK.
323pub(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    /// Build the chain-head state expected after folding `events`
375    /// bucketed against `settlements`. Mirrors what the test cluster
376    /// would produce on chain so reconciliation calls can be exercised
377    /// against an authoritative reference.
378    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    /// Feed `events` to `state` as item frames without a claim, then a
391    /// progress-only frame claiming `covered_checkpoint` complete.
392    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    /// `apply_stream_frame` only buffers — folding is deferred to
404    /// `fold_and_reconcile`. The local head must not move just from
405    /// receiving events.
406    #[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    /// `events_scanned_through` is monotonic — a lower claim does not
421    /// regress it.
422    #[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    /// A page can end partway through a checkpoint, and the next request
431    /// can land on a lagging replica that answers with an empty page and
432    /// no checkpoint claim. Neither the last event's checkpoint nor the
433    /// end of a page says the checkpoint is complete: only a
434    /// `covered_checkpoint` claim does. Until a claim reaches the
435    /// checkpoint, its events are neither folded nor released.
436    #[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        // With nothing buffered, a progress-only frame is not a reason
446        // to reconcile.
447        assert!(!apply_stream_frame(&mut state, None, Some(9)));
448
449        // The first part of checkpoint 10 arrives under a claim that
450        // stops at checkpoint 9.
451        for event in first_half {
452            assert!(!apply_stream_frame(&mut state, Some(event), Some(9)));
453        }
454        // A progress-only frame whose claim does not reach checkpoint 10,
455        // and one with no claim at all.
456        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        // Folding checkpoint 10 is refused even if a settlement for it is
463        // known, and nothing is released.
464        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        // The rest of checkpoint 10 arrives, then a claim covering it.
474        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    /// Single settlement per checkpoint. All events at one checkpoint
490    /// fold into a single batch and the chain head matches.
491    #[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    /// Multiple settlements per checkpoint — the failure mode that
514    /// motivated this whole module. Three transactions in checkpoint
515    /// 10 settle in two `settle_events` calls, so events 0–1 fold as
516    /// one batch and event 2 folds as another. The chain head must
517    /// match only if both batches are folded separately.
518    #[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        // First two events settle at txn 2; the third settles at txn 4.
526        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        // Sanity-check that the two-batch fold differs from the
534        // (incorrect) single-batch fold — this is the regression we're
535        // guarding against.
536        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    /// Reconciliation only consumes the buffer prefix at-or-below the
563    /// reconciliation point; events past it stay buffered for the next
564    /// round.
565    #[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), // past the reconciliation point
571        ];
572        // Only the cp=5 settlement is in range; the cp=9 settlement
573        // hasn't been queried yet.
574        let settlements = vec![(5u64, 0u64)];
575
576        // Construct a chain head that represents folding only the cp=5
577        // events — this is what `prove_object_at_checkpoint(.., 5)`
578        // would return on chain.
579        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    /// A chain head that doesn't match the locally-folded head returns
596    /// `MmrMismatch` and does NOT advance `confirmed_through` or drain
597    /// the buffer.
598    #[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    /// Calling `fold_and_reconcile` with no settlements is a hard
623    /// error — the caller is contracted to only invoke it after
624    /// `ListTransactions` has surfaced at least one settlement in the
625    /// scan range.
626    #[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    /// The reconciliation checkpoint must match the last settlement's
637    /// checkpoint — otherwise the local fold would terminate at a
638    /// different head than the on-chain proof attests to.
639    #[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    /// A buffered event whose checkpoint has no settlement in range is
652    /// a server-side index inconsistency — surface it as
653    /// `UnexpectedObjectShape` rather than fold silently into the
654    /// wrong bucket.
655    #[test]
656    fn fold_and_reconcile_rejects_event_without_matching_settlement() {
657        // Event at cp=5 but settlement only exists at cp=7.
658        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    /// `extract_event_stream_head` skips the dynamic-field UID and
672    /// `AccumulatorKey` prefix (64 bytes total) and BCS-decodes the
673    /// tail. Synthesize a `MoveStruct` whose `contents` start with two
674    /// arbitrary 32-byte addresses followed by the BCS bytes of a
675    /// known `EventStreamHead`, then confirm we recover that exact
676    /// head. The 64-byte offset is the load-bearing assumption here;
677    /// shift it by one byte and the BCS decode fails.
678    #[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        // Synthesize the dynamic-field contents: UID = derived object
694        // id, AccumulatorKey = stream_id, then the EventStreamHead
695        // bytes.
696        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    /// Extracting from a package (not a Move struct) is a clean
726    /// `UnexpectedObjectShape` error rather than a panic.
727    #[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}