sui_rpc/light_client/events/config.rs
1use std::time::Duration;
2
3use sui_sdk_types::Address;
4
5use crate::client::LedgerStreamConfig;
6use crate::client::ListConfig;
7
8/// Configuration for [`super::AuthenticatedEventsClient`].
9///
10/// All fields are public so callers can construct one inline. The
11/// defaults match the upstream reference client's choices unless noted
12/// otherwise.
13#[derive(Clone, Debug)]
14pub struct AuthenticatedEventsConfig {
15 /// The stream id (a Sui address, typically the publishing package's
16 /// id) to subscribe to.
17 pub stream_id: Address,
18
19 /// First checkpoint to read from. `None` means "start from the
20 /// network's current tip at construction time".
21 pub start_checkpoint: Option<u64>,
22
23 /// Maximum number of items to request per page, for both the
24 /// `ListEvents` pages of the event stream and the `ListTransactions`
25 /// pages of the settlement listing. The server clamps to 1000 per
26 /// the v2 List API contract.
27 pub page_size: u32,
28
29 /// Buffer capacity of the mpsc channel between the streaming task
30 /// and the consumer. Larger values smooth over bursts; smaller
31 /// values apply more backpressure to the producer.
32 pub channel_capacity: usize,
33
34 /// Maximum number of consecutive retries of a transient RPC failure
35 /// before the stream yields the failure as its terminal error. The
36 /// count restarts each time the failing call makes progress, so it
37 /// bounds how long the stream keeps retrying one outage, not how
38 /// many retries it makes in total. It applies to the ledger event
39 /// stream, the settlement listing, and the head proofs made while
40 /// reconciling; the startup reads are not retried.
41 /// `Some(0)` never retries. `None`, the default, retries
42 /// indefinitely.
43 pub max_consecutive_retries: Option<u32>,
44
45 /// Delay before the first retry of a transient RPC failure. The
46 /// ledger event stream and the settlement listing double the delay
47 /// on each consecutive retry; reconciliation head proofs wait an
48 /// additional `retry_backoff` per consecutive retry. Either way the
49 /// delay is capped at 30 seconds before jitter.
50 pub retry_backoff: Duration,
51
52 /// Upper bound on random jitter added to each retry sleep, to avoid
53 /// thundering-herd reconnects when multiple consumers see the same
54 /// failure mode.
55 pub retry_jitter: Duration,
56
57 /// Longest time events at checkpoints the event stream has claimed
58 /// complete stay buffered before the streaming task fetches the
59 /// on-chain [`EventStreamHead`], reconciles it against the locally
60 /// replayed MMR, and releases them. Once the event stream reports
61 /// that it has caught up with the server, buffered events are
62 /// reconciled without waiting for this interval, so it mainly
63 /// bounds buffering while the stream is catching up. Smaller values
64 /// release events to the consumer sooner at the cost of more OCS
65 /// inclusion-proof round trips.
66 ///
67 /// [`EventStreamHead`]: sui_sdk_types::framework::EventStreamHead
68 pub head_check_interval: Duration,
69}
70
71impl AuthenticatedEventsConfig {
72 /// Construct a config with the [`Default`] field values, scoped to
73 /// the given stream.
74 pub fn new(stream_id: Address) -> Self {
75 Self {
76 stream_id,
77 ..Self::default_for_dummy_stream()
78 }
79 }
80
81 /// Default field values for every field except `stream_id`, which
82 /// has no sensible default. Used by [`Self::new`] and the inline
83 /// builder pattern below.
84 fn default_for_dummy_stream() -> Self {
85 Self {
86 stream_id: Address::ZERO,
87 start_checkpoint: None,
88 page_size: 1000,
89 channel_capacity: 256,
90 max_consecutive_retries: None,
91 retry_backoff: Duration::from_millis(500),
92 retry_jitter: Duration::from_millis(250),
93 head_check_interval: Duration::from_secs(30),
94 }
95 }
96
97 /// Configuration for the ledger event stream.
98 pub(super) fn event_stream_config(&self) -> LedgerStreamConfig {
99 let mut stream_config = LedgerStreamConfig::default();
100 stream_config.list_page_limit = Some(self.page_size);
101 stream_config.base_retry_delay = self.retry_backoff;
102 stream_config.retry_jitter = self.retry_jitter;
103 stream_config.max_consecutive_retries = self.max_consecutive_retries;
104 stream_config
105 }
106
107 /// Configuration for the settlement `ListTransactions` listing.
108 pub(super) fn settlement_list_config(&self) -> ListConfig {
109 let mut list_config = ListConfig::default();
110 list_config.base_retry_delay = self.retry_backoff;
111 list_config.retry_jitter = self.retry_jitter;
112 list_config.max_consecutive_retries = self.max_consecutive_retries;
113 list_config
114 }
115}