sui_rpc/light_client/events/
client.rs1use 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
37pub struct AuthenticatedEventsClient {
50 light: LightClient,
51 config: AuthenticatedEventsConfig,
52}
53
54impl AuthenticatedEventsClient {
55 pub fn new(light: LightClient, config: AuthenticatedEventsConfig) -> Self {
57 Self { light, config }
58 }
59
60 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
76async fn run_stream_task(
100 mut light: LightClient,
101 config: AuthenticatedEventsConfig,
102 tx: mpsc::Sender<Result<AuthenticatedEvent, LightClientError>>,
103) {
104 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 let mut release_due = false;
134
135 loop {
136 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 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 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
197fn 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
213async 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 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
271async 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 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 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 return Err(LightClientError::UnexpectedObjectShape {
325 reason: "event stream head was deleted or wrapped at the reconciliation tip",
326 });
327 }
328 CheckpointObjectProof::NonInclusion => {
329 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
343async 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, }),
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
424fn 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
447async 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
477fn pseudo_jitter(attempts: u32, ceiling: Duration) -> Duration {
482 if ceiling.is_zero() {
483 return Duration::ZERO;
484 }
485 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 #[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}