sui_rpc/light_client/
config.rs

1//! Tunables for the light-client ratchet driver.
2
3use std::time::Duration;
4
5/// Configuration for the committee ratchet driver.
6///
7/// Constructed with [`Default`] and adjusted via the public fields, or
8/// composed onto a [`crate::light_client::LightClient`] through its
9/// `with_ratchet_config` builder.
10#[derive(Debug, Clone)]
11pub struct RatchetConfig {
12    /// How many end-of-epoch checkpoint fetches to keep in flight at
13    /// once. The discovery phase of the ratchet is inherently serial
14    /// (each `GetEpoch` answer drives whether to walk to the next
15    /// epoch), but once the set of epochs to advance through is known
16    /// the end-of-epoch summaries can be fetched concurrently. The
17    /// per-summary BLS verification still happens sequentially in
18    /// epoch order — the cache is a state machine and updates must be
19    /// ordered.
20    ///
21    /// Defaults to 4 — high enough to amortize round-trip latency for
22    /// a fresh testnet bootstrap (~1000 epochs) without overwhelming a
23    /// fullnode with parallel requests. Set to 1 to fall back to fully
24    /// sequential behaviour.
25    pub concurrency: usize,
26
27    /// Maximum number of epochs the discovery walk is willing to
28    /// advance through in a single call to the ratchet driver.
29    ///
30    /// Defaults to 10,000 — well past a year of testnet (~600 epochs)
31    /// with significant margin. The guard exists so that a misbehaving
32    /// (or malicious) server that keeps reporting `last_checkpoint <
33    /// target_seq` cannot trap the client in an indefinite discovery
34    /// loop. When the cap is hit the ratchet fails with
35    /// [`crate::light_client::LightClientError::RatchetGapTooLarge`]
36    /// rather than continuing to issue `GetEpoch` calls.
37    pub max_ratchet_gap: u64,
38
39    /// Number of times the ratchet driver will retry a single
40    /// transient RPC failure before giving up. Set to 0 to disable
41    /// retry entirely (useful for tests and latency-sensitive
42    /// callers). Default 5.
43    pub max_retries: u32,
44
45    /// First retry sleep duration. Subsequent retries double the
46    /// sleep up to `max_retry_delay`. Default 250 ms.
47    pub base_retry_delay: Duration,
48
49    /// Upper bound on the exponentially-growing retry sleep. Default
50    /// 4 s.
51    pub max_retry_delay: Duration,
52
53    /// Maximum extra jitter added to each retry sleep. Jitter is
54    /// deterministic per attempt (no `rand` dependency); the point is
55    /// to avoid lockstep retries across concurrent ratchet futures,
56    /// not cryptographic randomness. Default 500 ms.
57    pub retry_jitter: Duration,
58}
59
60impl Default for RatchetConfig {
61    fn default() -> Self {
62        Self {
63            concurrency: 4,
64            max_ratchet_gap: 10_000,
65            max_retries: 5,
66            base_retry_delay: Duration::from_millis(250),
67            max_retry_delay: Duration::from_secs(4),
68            retry_jitter: Duration::from_millis(500),
69        }
70    }
71}
sui_rpc/light_client/config.rs

sui_rpc/light_client/
config.rs
