Skip to main content

sui_rpc/light_client/events/
client.rs

1//! `AuthenticatedEventsClient` — the public surface for streaming
2//! authenticated events.
3
4use std::time::Duration;
5
6use futures::Stream;
7use futures::StreamExt;
8use sui_sdk_types::framework::EventStreamHead;
9use sui_sdk_types::framework::derive_event_stream_head_object_id;
10use tokio::sync::mpsc;
11use tokio::time::Instant;
12
13use super::config::AuthenticatedEventsConfig;
14use super::envelope::AuthenticatedEvent;
15use super::state::StreamState;
16use super::state::apply_stream_frame;
17use super::state::extract_event_stream_head;
18use super::state::fold_and_reconcile;
19use crate::client::Delivery;
20use crate::client::EventStreamFrame;
21use crate::client::EventStreamRequest;
22use crate::client::EventStreamStart;
23use crate::client::LedgerStreamConfig;
24use crate::field::FieldMask;
25use crate::field::FieldMaskUtil;
26use crate::light_client::CheckpointObjectProof;
27use crate::light_client::LightClient;
28use crate::light_client::error::LightClientError;
29use crate::proto::sui::rpc::v2::EventFilter;
30use crate::proto::sui::rpc::v2::ExecutedTransaction;
31use crate::proto::sui::rpc::v2::ListTransactionsRequest;
32use crate::proto::sui::rpc::v2::QueryOptions;
33use crate::proto::sui::rpc::v2::TransactionFilter;
34use crate::proto::sui::rpc::v2::filter::event;
35use crate::proto::sui::rpc::v2::filter::transaction;
36
37/// A streaming verifier for a single authenticated event stream.
38///
39/// Construct with [`AuthenticatedEventsClient::new`], passing a
40/// configured [`LightClient`] and an [`AuthenticatedEventsConfig`].
41/// Call [`Self::stream`] to spawn the background verifier task and
42/// receive an async stream of cryptographically-authenticated events.
43///
44/// Once [`Self::stream`] is called the client is consumed. The
45/// returned stream pulls events from the spawned task via a bounded
46/// channel; events are yielded only after the periodic reconciliation
47/// confirms the local MMR matches the on-chain
48/// [`EventStreamHead`](sui_sdk_types::framework::EventStreamHead).
49pub struct AuthenticatedEventsClient {
50    light: LightClient,
51    config: AuthenticatedEventsConfig,
52}
53
54impl AuthenticatedEventsClient {
55    /// Construct a new streaming client.
56    pub fn new(light: LightClient, config: AuthenticatedEventsConfig) -> Self {
57        Self { light, config }
58    }
59
60    /// Spawn the verifier task and return a stream of authenticated
61    /// events.
62    ///
63    /// The stream terminates when the spawned task exits — either
64    /// because the consumer dropped the receiver, or because the task
65    /// hit an unrecoverable error (the error is yielded as the last
66    /// item before termination).
67    pub fn stream(
68        self,
69    ) -> impl Stream<Item = Result<AuthenticatedEvent, LightClientError>> + Send + 'static {
70        let (tx, rx) = mpsc::channel(self.config.channel_capacity);
71        tokio::spawn(run_stream_task(self.light, self.config, tx));
72        futures::stream::unfold(rx, |mut rx| async move { rx.recv().await.map(|v| (v, rx)) })
73    }
74}
75
76/// Driver loop for a single stream subscription.
77///
78/// On startup: fetch the latest checkpoint as the race-free floor,
79/// then fetch the on-chain stream head. If the head exists, resume
80/// from `head.checkpoint + 1`; otherwise start from
81/// `latest_checkpoint + 1`. Either way the floor ensures no event can
82/// land in the interval without being picked up by the head check.
83///
84/// Steady state: follow the ledger event stream
85/// ([`crate::Client::stream_events_with_config`], polling the List
86/// API) from the first unconfirmed checkpoint, buffering its events and
87/// recording the highest `covered_checkpoint` it claims. A checkpoint
88/// is complete only once that claim reaches it. Reconcile when complete
89/// checkpoints are buffered and either
90/// [`AuthenticatedEventsConfig::head_check_interval`] has elapsed since
91/// the last reconciliation or a progress-only frame's claim covers every
92/// buffered event (the stream has caught up). A reconciliation fetches
93/// the settlement boundaries for the complete, unconfirmed range via
94/// `ListTransactions(affected_object = event_stream_head)`, folds the
95/// buffered events into the local MMR partitioned by settlement, and
96/// reconciles the resulting head against the on-chain head proven at
97/// the last settled checkpoint. On match, drain the confirmed events
98/// through the channel. On mismatch, send the error and exit.
99async fn run_stream_task(
100    mut light: LightClient,
101    config: AuthenticatedEventsConfig,
102    tx: mpsc::Sender<Result<AuthenticatedEvent, LightClientError>>,
103) {
104    // The startup helper can fail; route the error through the channel
105    // and exit cleanly so the consumer sees one final item.
106    let start = match initial_state(&mut light, &config).await {
107        Ok(start) => start,
108        Err(e) => {
109            let _ = tx.send(Err(e)).await;
110            return;
111        }
112    };
113
114    let mut state = StreamState::new(start.initial_head, start.start_checkpoint);
115    let stream_head_object_id = derive_event_stream_head_object_id(config.stream_id);
116
117    let request = EventStreamRequest::new()
118        .with_read_mask(AuthenticatedEvent::read_mask())
119        .with_filter(build_filter(config.stream_id))
120        .with_start(EventStreamStart::Checkpoint(
121            start.start_checkpoint.saturating_add(1),
122        ))
123        .with_delivery(Delivery::Poll);
124    let mut frames = std::pin::pin!(
125        light
126            .rpc()
127            .stream_events_with_config(request, config.event_stream_config())
128    );
129
130    let mut last_reconcile = Instant::now();
131    // Set when the stream catches up with buffered events still waiting
132    // to be released; cleared by the next successful reconciliation.
133    let mut release_due = false;
134
135    loop {
136        // While complete checkpoints are buffered, wait for the next frame
137        // no longer than the head-check deadline, so a stream waiting on
138        // its next poll never holds back reconciliation. Abandoning the
139        // wait keeps the stream's in-flight work for the next call.
140        let next_frame = if state.has_complete_buffered_events() {
141            tokio::time::timeout_at(last_reconcile + config.head_check_interval, frames.next())
142                .await
143                .ok()
144        } else {
145            Some(frames.next().await)
146        };
147
148        match next_frame {
149            // The head-check deadline passed first.
150            None => {}
151            Some(Some(Ok(frame))) => match apply_frame(&mut state, frame) {
152                Ok(caught_up) => release_due |= caught_up,
153                Err(e) => {
154                    let _ = tx.send(Err(e)).await;
155                    return;
156                }
157            },
158            // The stream retries transient failures itself, so any error
159            // it yields is terminal.
160            Some(Some(Err(status))) => {
161                let _ = tx.send(Err(status.into())).await;
162                return;
163            }
164            Some(None) => {
165                let _ = tx
166                    .send(Err(LightClientError::Rpc(tonic::Status::internal(
167                        "ledger event stream ended",
168                    ))))
169                    .await;
170                return;
171            }
172        }
173
174        let reconcile_due = release_due || last_reconcile.elapsed() >= config.head_check_interval;
175        if !reconcile_due || !state.has_complete_buffered_events() {
176            continue;
177        }
178
179        match reconcile_once(&mut light, &mut state, &stream_head_object_id, &config).await {
180            Ok(released) => {
181                last_reconcile = Instant::now();
182                release_due = false;
183                for ev in released {
184                    if tx.send(Ok(ev)).await.is_err() {
185                        return;
186                    }
187                }
188            }
189            Err(e) => {
190                let _ = tx.send(Err(e)).await;
191                return;
192            }
193        }
194    }
195}
196
197/// Decode `frame` and apply it to `state` with [`apply_stream_frame`].
198/// Returns whether the stream has caught up with every buffered event.
199fn apply_frame(state: &mut StreamState, frame: EventStreamFrame) -> Result<bool, LightClientError> {
200    let event = frame
201        .event
202        .as_ref()
203        .map(AuthenticatedEvent::try_from)
204        .transpose()?;
205    Ok(apply_stream_frame(state, event, frame.covered_checkpoint))
206}
207
208struct InitialState {
209    initial_head: EventStreamHead,
210    start_checkpoint: u64,
211}
212
213/// Establish the starting position. Fetch the latest checkpoint
214/// *before* the head so that if an event lands in between, the head
215/// fetch observes it and we resume from `head.checkpoint + 1` rather
216/// than the now-stale tip.
217///
218/// Known limitation: an `EventStreamHead` object that exists on chain
219/// but was *not modified* in the checkpoint we query produces an
220/// authenticated `NonInclusion` result, which this function treats the
221/// same as "no head yet" — it falls back to the tip. The OCS-per-
222/// checkpoint commitment scheme attests only to objects modified at a
223/// given checkpoint, not to the contents of unmodified objects, so we
224/// cannot distinguish the two cases through this API alone. In
225/// practice this is rarely an issue because new events on a stream
226/// modify its head, so a head that hasn't been touched at the tip
227/// means the stream has been quiet — and starting from the tip is the
228/// correct resume point in both cases.
229async fn initial_state(
230    light: &mut LightClient,
231    config: &AuthenticatedEventsConfig,
232) -> Result<InitialState, LightClientError> {
233    let latest_tip = light.latest_checkpoint_seq().await?;
234    let stream_head_object_id = derive_event_stream_head_object_id(config.stream_id);
235
236    let proof = light
237        .prove_object_at_checkpoint(&stream_head_object_id, latest_tip)
238        .await?;
239
240    let (initial_head, start_checkpoint) = match proof {
241        CheckpointObjectProof::Inclusion {
242            object: Some(object),
243            ..
244        } => {
245            let head = extract_event_stream_head(&object)?;
246            let cp = head.checkpoint_seq;
247            (head, cp)
248        }
249        CheckpointObjectProof::Inclusion { object: None, .. } => {
250            // The head object was deleted or wrapped at the tip.
251            // For an authenticated event stream this is unrecoverable
252            // — the on-chain anchor is gone, so no future reconciliation
253            // can succeed.
254            return Err(LightClientError::UnexpectedObjectShape {
255                reason: "event stream head was deleted or wrapped at the initial tip",
256            });
257        }
258        CheckpointObjectProof::NonInclusion => (
259            EventStreamHead::default(),
260            config.start_checkpoint.unwrap_or(latest_tip),
261        ),
262    };
263
264    let start_checkpoint = config.start_checkpoint.unwrap_or(start_checkpoint);
265    Ok(InitialState {
266        initial_head,
267        start_checkpoint,
268    })
269}
270
271/// Drive one reconciliation round: fetch settlements for the complete,
272/// unconfirmed range, fold the buffered events through the latest
273/// settled checkpoint into the local MMR, prove the on-chain head at
274/// that checkpoint, and release the folded events on a match.
275///
276/// Returns the released events on success. Returns `Ok(Vec::new())`
277/// when there's nothing to reconcile yet (no settlement modified the
278/// head anywhere in the range the settlement listing covered, so
279/// there's no chain anchor to compare against).
280async fn reconcile_once(
281    light: &mut LightClient,
282    state: &mut StreamState,
283    stream_head_object_id: &sui_sdk_types::Address,
284    config: &AuthenticatedEventsConfig,
285) -> Result<Vec<AuthenticatedEvent>, LightClientError> {
286    // Settlements are only fetched for checkpoints the event stream has
287    // claimed complete — partitioning a checkpoint whose events haven't
288    // all been buffered yields an MMR that can never match.
289    let Some(checkpoints) = state.complete_unconfirmed_checkpoints() else {
290        return Ok(Vec::new());
291    };
292
293    let settlements =
294        fetch_settlements_for_range(light, stream_head_object_id, checkpoints, config).await?;
295
296    let Some((reconcile_cp, _)) = settlements.last().copied() else {
297        // No settlement in the listed range — the head wasn't modified
298        // there, so there's no anchor to reconcile against. Pending
299        // events stay buffered; the next reconciliation round retries
300        // once a settlement lands.
301        return Ok(Vec::new());
302    };
303
304    let mut consecutive_failures = 0u32;
305    let proof = loop {
306        match light
307            .prove_object_at_checkpoint(stream_head_object_id, reconcile_cp)
308            .await
309        {
310            Ok(proof) => break proof,
311            Err(e) => backoff_or_give_up(config, &mut consecutive_failures, e).await?,
312        }
313    };
314    let chain_head = match proof {
315        CheckpointObjectProof::Inclusion {
316            object: Some(object),
317            ..
318        } => extract_event_stream_head(&object)?,
319        CheckpointObjectProof::Inclusion { object: None, .. } => {
320            // The on-chain head was deleted or wrapped at the
321            // settlement checkpoint. The local replay cannot be
322            // reconciled against a missing head; this is terminal for
323            // the stream.
324            return Err(LightClientError::UnexpectedObjectShape {
325                reason: "event stream head was deleted or wrapped at the reconciliation tip",
326            });
327        }
328        CheckpointObjectProof::NonInclusion => {
329            // `ListTransactions(affected_object)` placed a settlement
330            // at this checkpoint, but the OCS proof says the head
331            // wasn't modified there — the two indexes are
332            // inconsistent.
333            return Err(LightClientError::UnexpectedObjectShape {
334                reason: "settlement transaction listed at checkpoint but OCS proof reports \
335                         the event stream head was not modified",
336            });
337        }
338    };
339
340    fold_and_reconcile(state, &settlements, chain_head, reconcile_cp)
341}
342
343/// List transactions filtered on `affected_object =
344/// stream_head_object_id` over `checkpoints` and return the ascending
345/// `(checkpoint, transaction_index)` settlement boundaries at
346/// checkpoints the listing claimed complete.
347///
348/// Each `settle_events` transaction mutates the stream's head object,
349/// so this filter returns exactly the per-stream settlement boundaries.
350/// `checkpoints` is half-open, matching the proto `start_checkpoint` /
351/// `end_checkpoint` semantics.
352///
353/// The listing can end early at the ledger tip when it reaches a server
354/// that has not yet indexed the whole range. Only settlements at or
355/// below the highest `Watermark.checkpoint` the listing reported are
356/// returned: a later checkpoint may hold settlements the listing has
357/// not reached, so it is left for a later reconciliation round.
358async fn fetch_settlements_for_range(
359    light: &mut LightClient,
360    stream_head_object_id: &sui_sdk_types::Address,
361    checkpoints: std::ops::Range<u64>,
362    config: &AuthenticatedEventsConfig,
363) -> Result<Vec<(u64, u64)>, LightClientError> {
364    let request = ListTransactionsRequest {
365        read_mask: Some(settlement_read_mask()),
366        start_checkpoint: Some(checkpoints.start),
367        end_checkpoint: Some(checkpoints.end),
368        filter: Some(build_affected_object_filter(stream_head_object_id)),
369        options: Some(QueryOptions {
370            limit: Some(config.page_size),
371            after: None,
372            before: None,
373            ordering: None, // ascending
374        }),
375        start_transaction_index: None,
376        end_transaction_index: None,
377    };
378    let mut frames = std::pin::pin!(
379        light
380            .rpc()
381            .list_transactions_with_config(request, config.settlement_list_config())
382    );
383
384    let mut settlements: Vec<(u64, u64)> = Vec::new();
385    let mut covered_checkpoint: Option<u64> = None;
386    while let Some(frame) = frames.next().await {
387        let frame = frame?;
388        if let Some(checkpoint) = frame.watermark.as_ref().and_then(|w| w.checkpoint) {
389            covered_checkpoint = covered_checkpoint.max(Some(checkpoint));
390        }
391        if let Some(transaction) = frame.transaction.as_ref() {
392            let checkpoint =
393                transaction
394                    .checkpoint
395                    .ok_or(LightClientError::UnexpectedObjectShape {
396                        reason: "settlement transaction missing checkpoint",
397                    })?;
398            let tx_offset =
399                transaction
400                    .transaction_index
401                    .ok_or(LightClientError::UnexpectedObjectShape {
402                        reason: "settlement transaction missing transaction_index",
403                    })?;
404            settlements.push((checkpoint, tx_offset));
405        }
406    }
407
408    let complete = match covered_checkpoint {
409        Some(covered) => settlements.partition_point(|(checkpoint, _)| *checkpoint <= covered),
410        None => 0,
411    };
412    settlements.truncate(complete);
413    Ok(settlements)
414}
415
416fn build_filter(stream_id: sui_sdk_types::Address) -> EventFilter {
417    EventFilter::matching(event::event_stream_head(stream_id))
418}
419
420fn build_affected_object_filter(object_id: &sui_sdk_types::Address) -> TransactionFilter {
421    TransactionFilter::matching(transaction::affected_object(*object_id))
422}
423
424/// Read mask selecting the settlement position fields
425/// [`fetch_settlements_for_range`] reads from each listed transaction.
426fn settlement_read_mask() -> FieldMask {
427    FieldMask::from_paths([
428        ExecutedTransaction::CHECKPOINT_FIELD.name,
429        ExecutedTransaction::TRANSACTION_INDEX_FIELD.name,
430    ])
431}
432
433fn e_is_retryable(err: &LightClientError) -> bool {
434    matches!(
435        err,
436        LightClientError::Rpc(status)
437            if matches!(
438                status.code(),
439                tonic::Code::Unavailable
440                    | tonic::Code::DeadlineExceeded
441                    | tonic::Code::ResourceExhausted
442                    | tonic::Code::Aborted
443            )
444    )
445}
446
447/// Decide whether to retry a failed RPC the client issues itself.
448///
449/// Returns `err` when it is not transient or when
450/// [`AuthenticatedEventsConfig::max_consecutive_retries`] consecutive
451/// retries have already been made. Otherwise sleeps for
452/// `retry_backoff * attempts`, capped at the ledger stream's default
453/// maximum retry delay, plus jitter, and returns `Ok(())` so the caller
454/// reissues the RPC.
455async fn backoff_or_give_up(
456    config: &AuthenticatedEventsConfig,
457    consecutive_failures: &mut u32,
458    err: LightClientError,
459) -> Result<(), LightClientError> {
460    if !e_is_retryable(&err)
461        || config
462            .max_consecutive_retries
463            .is_some_and(|max_retries| *consecutive_failures >= max_retries)
464    {
465        return Err(err);
466    }
467    *consecutive_failures = consecutive_failures.saturating_add(1);
468    let base = config
469        .retry_backoff
470        .saturating_mul(*consecutive_failures)
471        .min(LedgerStreamConfig::default().max_retry_delay);
472    let jitter = pseudo_jitter(*consecutive_failures, config.retry_jitter);
473    tokio::time::sleep(base.saturating_add(jitter)).await;
474    Ok(())
475}
476
477/// Deterministic jitter derived from the attempt count. Avoids
478/// pulling in `rand` for a single call; the goal is just to avoid
479/// lockstep retries across many concurrent streams, not cryptographic
480/// randomness.
481fn pseudo_jitter(attempts: u32, ceiling: Duration) -> Duration {
482    if ceiling.is_zero() {
483        return Duration::ZERO;
484    }
485    // Mix the attempt count with a fixed prime to spread values.
486    let mix = (u64::from(attempts).wrapping_mul(0x9E3779B97F4A7C15)) as u128;
487    let ceiling_ms = ceiling.as_millis().max(1);
488    let offset_ms = (mix % ceiling_ms) as u64;
489    Duration::from_millis(offset_ms)
490}
491
492#[cfg(test)]
493mod tests {
494    use super::*;
495    use crate::field::FieldMaskTree;
496    use crate::merge::Merge;
497
498    /// A server honoring the settlement read mask returns both position
499    /// fields the settlement listing reads.
500    #[test]
501    fn settlement_read_mask_selects_settlement_position() {
502        let transaction = ExecutedTransaction::default()
503            .with_checkpoint(12)
504            .with_transaction_index(4)
505            .with_digest("unused");
506
507        let mask = FieldMaskTree::from(settlement_read_mask());
508        let masked = ExecutedTransaction::merge_from(&transaction, &mask);
509
510        assert_eq!(masked.checkpoint, Some(12));
511        assert_eq!(masked.transaction_index, Some(4));
512        assert_eq!(masked.digest, None);
513    }
514}