Skip to main content

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}