reth_engine_primitives/
config.rs

1//! Engine tree configuration.
2
3use alloy_eips::merge::EPOCH_SLOTS;
4use core::time::Duration;
5
6/// Triggers persistence when the number of canonical blocks in memory exceeds this threshold.
7pub const DEFAULT_PERSISTENCE_THRESHOLD: u64 = 2;
8
9/// Maximum canonical-minus-persisted gap before engine API processing is stalled.
10pub const DEFAULT_PERSISTENCE_BACKPRESSURE_THRESHOLD: u64 = 16;
11
12/// How close to the canonical head we persist blocks.
13pub const DEFAULT_MEMORY_BLOCK_BUFFER_TARGET: u64 = 0;
14
15/// The size of proof targets chunk to spawn in one multiproof calculation.
16pub const DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE: usize = 5;
17
18/// Default number of cache hits before an invalid header entry is evicted and reprocessed.
19pub const DEFAULT_INVALID_HEADER_HIT_EVICTION_THRESHOLD: u8 = 128;
20
21/// Gas threshold below which the small block chunk size is used.
22pub const SMALL_BLOCK_GAS_THRESHOLD: u64 = 20_000_000;
23
24/// Default number of reserved CPU cores for non-reth processes.
25///
26/// This will be deducted from the thread count of main reth global threadpool.
27pub const DEFAULT_RESERVED_CPU_CORES: usize = 1;
28
29/// Default depth for sparse trie pruning.
30///
31/// Nodes at this depth and below are converted to hash stubs to reduce memory.
32/// Depth 4 means we keep roughly 16^4 = 65536 potential branch paths at most.
33pub const DEFAULT_SPARSE_TRIE_PRUNE_DEPTH: usize = 4;
34
35/// Default LFU hot-slot capacity for sparse trie pruning.
36///
37/// Limits the number of `(address, slot)` pairs retained across prune cycles.
38pub const DEFAULT_SPARSE_TRIE_MAX_HOT_SLOTS: usize = 1500;
39
40/// Default LFU hot-account capacity for sparse trie pruning.
41///
42/// Limits the number of account addresses retained across prune cycles.
43pub const DEFAULT_SPARSE_TRIE_MAX_HOT_ACCOUNTS: usize = 1000;
44
45/// Default timeout for the state root task before spawning a sequential fallback.
46pub const DEFAULT_STATE_ROOT_TASK_TIMEOUT: Duration = Duration::from_secs(1);
47
48const DEFAULT_BLOCK_BUFFER_LIMIT: u32 = EPOCH_SLOTS as u32 * 2;
49const DEFAULT_MAX_INVALID_HEADER_CACHE_LENGTH: u32 = 256;
50const DEFAULT_MAX_EXECUTE_BLOCK_BATCH_SIZE: usize = 4;
51const DEFAULT_CROSS_BLOCK_CACHE_SIZE: usize = default_cross_block_cache_size();
52
53const fn assert_backpressure_threshold_invariant(
54    persistence_threshold: u64,
55    persistence_backpressure_threshold: u64,
56) {
57    debug_assert!(
58        persistence_backpressure_threshold > persistence_threshold,
59        "persistence_backpressure_threshold must be greater than persistence_threshold",
60    );
61}
62
63const fn default_cross_block_cache_size() -> usize {
64    if cfg!(test) {
65        1024 * 1024 // 1 MB in tests
66    } else if cfg!(target_pointer_width = "32") {
67        usize::MAX // max possible on wasm32 / 32-bit
68    } else {
69        4 * 1024 * 1024 * 1024 // 4 GB on 64-bit
70    }
71}
72
73/// Determines if the host has enough parallelism to run the payload processor.
74///
75/// It requires at least 5 parallel threads:
76/// - Engine in main thread that spawns the state root task.
77/// - Multiproof task in payload processor
78/// - Sparse Trie task in payload processor
79/// - Multiproof computation spawned in payload processor
80/// - Storage root computation spawned in trie parallel proof
81pub fn has_enough_parallelism() -> bool {
82    #[cfg(feature = "std")]
83    {
84        std::thread::available_parallelism().is_ok_and(|num| num.get() >= 5)
85    }
86    #[cfg(not(feature = "std"))]
87    false
88}
89
90/// The configuration of the engine tree.
91#[derive(Debug, Clone)]
92pub struct TreeConfig {
93    /// Maximum number of blocks to be kept only in memory without triggering
94    /// persistence.
95    persistence_threshold: u64,
96    /// How close to the canonical head we persist blocks. Represents the ideal
97    /// number of most recent blocks to keep in memory for quick access and reorgs.
98    ///
99    /// Note: this should be less than or equal to `persistence_threshold`.
100    memory_block_buffer_target: u64,
101    /// Maximum canonical-minus-persisted gap before engine API processing is stalled.
102    persistence_backpressure_threshold: u64,
103    /// Number of pending blocks that cannot be executed due to missing parent and
104    /// are kept in cache.
105    block_buffer_limit: u32,
106    /// Number of invalid headers to keep in cache.
107    max_invalid_header_cache_length: u32,
108    /// Number of cache hits before an invalid header entry is evicted and reprocessed.
109    ///
110    /// Setting this to `0` effectively disables the cache because entries are evicted on the
111    /// first lookup.
112    invalid_header_hit_eviction_threshold: u8,
113    /// Maximum number of blocks to execute sequentially in a batch.
114    ///
115    /// This is used as a cutoff to prevent long-running sequential block execution when we receive
116    /// a batch of downloaded blocks.
117    max_execute_block_batch_size: usize,
118    /// Whether to use the legacy state root calculation method instead of the
119    /// new state root task.
120    legacy_state_root: bool,
121    /// Whether to always compare trie updates from the state root task to the trie updates from
122    /// the regular state root calculation.
123    always_compare_trie_updates: bool,
124    /// Whether to disable state cache.
125    disable_state_cache: bool,
126    /// Whether to disable parallel prewarming.
127    disable_prewarming: bool,
128    /// Whether to enable state provider metrics.
129    state_provider_metrics: bool,
130    /// Cross-block cache size in bytes.
131    cross_block_cache_size: usize,
132    /// Whether the host has enough parallelism to run state root task.
133    has_enough_parallelism: bool,
134    /// Multiproof task chunk size for proof targets.
135    multiproof_chunk_size: usize,
136    /// Number of reserved CPU cores for non-reth processes
137    reserved_cpu_cores: usize,
138    /// Whether to disable the precompile cache
139    precompile_cache_disabled: bool,
140    /// Whether to use state root fallback for testing
141    state_root_fallback: bool,
142    /// Whether to always process payload attributes and begin a payload build process
143    /// even if `forkchoiceState.headBlockHash` is already the canonical head or an ancestor.
144    ///
145    /// The Engine API specification generally states that client software "MUST NOT begin a
146    /// payload build process if `forkchoiceState.headBlockHash` references a `VALID`
147    /// ancestor of the head of canonical chain".
148    /// See: <https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_forkchoiceupdatedv1> (Rule 2)
149    ///
150    /// This flag allows overriding that behavior.
151    /// This is useful for specific chain configurations (e.g., OP Stack where proposers
152    /// can reorg their own chain), various custom chains, or for development/testing purposes
153    /// where immediate payload regeneration is desired despite the head not changing or moving to
154    /// an ancestor.
155    always_process_payload_attributes_on_canonical_head: bool,
156    /// Whether to unwind canonical header to ancestor during forkchoice updates.
157    allow_unwind_canonical_header: bool,
158    /// Whether to disable cache metrics recording (can be expensive with large cached state).
159    disable_cache_metrics: bool,
160    /// Depth for sparse trie pruning after state root computation.
161    sparse_trie_prune_depth: usize,
162    /// LFU hot-slot capacity: max `(address, slot)` pairs retained across prune cycles.
163    sparse_trie_max_hot_slots: usize,
164    /// LFU hot-account capacity: max account addresses retained across prune cycles.
165    sparse_trie_max_hot_accounts: usize,
166    /// When set, blocks whose total processing time (execution + state reads + state root +
167    /// DB commit) exceeds this duration trigger a structured `warn!` log with detailed timing,
168    /// state-operation counts, and cache hit-rate metrics. `Duration::ZERO` logs every block.
169    slow_block_threshold: Option<Duration>,
170    /// Whether to fully disable sparse trie cache pruning between blocks.
171    disable_sparse_trie_cache_pruning: bool,
172    /// Timeout for the state root task before spawning a sequential fallback computation.
173    /// If `Some`, after waiting this duration for the state root task, a sequential state root
174    /// computation is spawned in parallel and whichever finishes first is used.
175    /// If `None`, the timeout fallback is disabled.
176    state_root_task_timeout: Option<Duration>,
177    /// Whether to share execution cache with the payload builder.
178    share_execution_cache_with_payload_builder: bool,
179    /// Whether to share sparse trie with the payload builder.
180    share_sparse_trie_with_payload_builder: bool,
181    /// Whether to suppress persistence cycles while building a payload.
182    ///
183    /// When enabled, persistence is deferred from the moment an FCU with payload attributes
184    /// arrives until the next FCU without attributes. This avoids persistence I/O competing
185    /// with block building on latency-sensitive chains.
186    suppress_persistence_during_build: bool,
187    /// Whether to disable BAL (Block Access List, EIP-7928) based parallel execution.
188    /// When disabled, uses the sequential execution path even when a BAL is available.
189    disable_bal_parallel_execution: bool,
190    /// Whether to disable BAL-driven parallel state root computation.
191    /// Only valid when BAL parallel execution is also disabled.
192    disable_bal_parallel_state_root: bool,
193    /// Whether to disable BAL (Block Access List) storage prefetch IO during prewarming.
194    /// When set, BAL storage slots are not read into the execution cache. BAL hashed-state
195    /// streaming for parallel state-root computation is controlled separately.
196    disable_bal_batch_io: bool,
197    /// Maximum random jitter applied before each proof computation (trie-debug only).
198    /// When set, each proof worker sleeps for a random duration up to this value
199    /// before starting a proof calculation.
200    #[cfg(feature = "trie-debug")]
201    proof_jitter: Option<Duration>,
202}
203
204impl Default for TreeConfig {
205    fn default() -> Self {
206        assert_backpressure_threshold_invariant(
207            DEFAULT_PERSISTENCE_THRESHOLD,
208            DEFAULT_PERSISTENCE_BACKPRESSURE_THRESHOLD,
209        );
210        Self {
211            persistence_threshold: DEFAULT_PERSISTENCE_THRESHOLD,
212            memory_block_buffer_target: DEFAULT_MEMORY_BLOCK_BUFFER_TARGET,
213            persistence_backpressure_threshold: DEFAULT_PERSISTENCE_BACKPRESSURE_THRESHOLD,
214            block_buffer_limit: DEFAULT_BLOCK_BUFFER_LIMIT,
215            max_invalid_header_cache_length: DEFAULT_MAX_INVALID_HEADER_CACHE_LENGTH,
216            invalid_header_hit_eviction_threshold: DEFAULT_INVALID_HEADER_HIT_EVICTION_THRESHOLD,
217            max_execute_block_batch_size: DEFAULT_MAX_EXECUTE_BLOCK_BATCH_SIZE,
218            legacy_state_root: false,
219            always_compare_trie_updates: false,
220            disable_state_cache: false,
221            disable_prewarming: false,
222            state_provider_metrics: false,
223            cross_block_cache_size: DEFAULT_CROSS_BLOCK_CACHE_SIZE,
224            has_enough_parallelism: has_enough_parallelism(),
225            multiproof_chunk_size: DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE,
226            reserved_cpu_cores: DEFAULT_RESERVED_CPU_CORES,
227            precompile_cache_disabled: false,
228            state_root_fallback: false,
229            always_process_payload_attributes_on_canonical_head: false,
230            allow_unwind_canonical_header: false,
231            disable_cache_metrics: false,
232            sparse_trie_prune_depth: DEFAULT_SPARSE_TRIE_PRUNE_DEPTH,
233            sparse_trie_max_hot_slots: DEFAULT_SPARSE_TRIE_MAX_HOT_SLOTS,
234            sparse_trie_max_hot_accounts: DEFAULT_SPARSE_TRIE_MAX_HOT_ACCOUNTS,
235            slow_block_threshold: None,
236            disable_sparse_trie_cache_pruning: false,
237            state_root_task_timeout: Some(DEFAULT_STATE_ROOT_TASK_TIMEOUT),
238            share_execution_cache_with_payload_builder: false,
239            share_sparse_trie_with_payload_builder: false,
240            suppress_persistence_during_build: false,
241            disable_bal_parallel_execution: false,
242            disable_bal_parallel_state_root: false,
243            disable_bal_batch_io: false,
244            #[cfg(feature = "trie-debug")]
245            proof_jitter: None,
246        }
247    }
248}
249
250impl TreeConfig {
251    /// Create engine tree configuration.
252    #[expect(clippy::too_many_arguments)]
253    pub const fn new(
254        persistence_threshold: u64,
255        memory_block_buffer_target: u64,
256        persistence_backpressure_threshold: u64,
257        block_buffer_limit: u32,
258        max_invalid_header_cache_length: u32,
259        invalid_header_hit_eviction_threshold: u8,
260        max_execute_block_batch_size: usize,
261        legacy_state_root: bool,
262        always_compare_trie_updates: bool,
263        disable_state_cache: bool,
264        disable_prewarming: bool,
265        state_provider_metrics: bool,
266        cross_block_cache_size: usize,
267        has_enough_parallelism: bool,
268        multiproof_chunk_size: usize,
269        reserved_cpu_cores: usize,
270        precompile_cache_disabled: bool,
271        state_root_fallback: bool,
272        always_process_payload_attributes_on_canonical_head: bool,
273        allow_unwind_canonical_header: bool,
274        disable_cache_metrics: bool,
275        sparse_trie_prune_depth: usize,
276        sparse_trie_max_hot_slots: usize,
277        sparse_trie_max_hot_accounts: usize,
278        slow_block_threshold: Option<Duration>,
279        state_root_task_timeout: Option<Duration>,
280        share_execution_cache_with_payload_builder: bool,
281        share_sparse_trie_with_payload_builder: bool,
282    ) -> Self {
283        assert_backpressure_threshold_invariant(
284            persistence_threshold,
285            persistence_backpressure_threshold,
286        );
287        Self {
288            persistence_threshold,
289            memory_block_buffer_target,
290            persistence_backpressure_threshold,
291            block_buffer_limit,
292            max_invalid_header_cache_length,
293            invalid_header_hit_eviction_threshold,
294            max_execute_block_batch_size,
295            legacy_state_root,
296            always_compare_trie_updates,
297            disable_state_cache,
298            disable_prewarming,
299            state_provider_metrics,
300            cross_block_cache_size,
301            has_enough_parallelism,
302            multiproof_chunk_size,
303            reserved_cpu_cores,
304            precompile_cache_disabled,
305            state_root_fallback,
306            always_process_payload_attributes_on_canonical_head,
307            allow_unwind_canonical_header,
308            disable_cache_metrics,
309            sparse_trie_prune_depth,
310            sparse_trie_max_hot_slots,
311            sparse_trie_max_hot_accounts,
312            slow_block_threshold,
313            disable_sparse_trie_cache_pruning: false,
314            state_root_task_timeout,
315            share_execution_cache_with_payload_builder,
316            share_sparse_trie_with_payload_builder,
317            suppress_persistence_during_build: false,
318            disable_bal_parallel_execution: false,
319            disable_bal_parallel_state_root: false,
320            disable_bal_batch_io: false,
321            #[cfg(feature = "trie-debug")]
322            proof_jitter: None,
323        }
324    }
325
326    /// Return the persistence threshold.
327    pub const fn persistence_threshold(&self) -> u64 {
328        self.persistence_threshold
329    }
330
331    /// Return the memory block buffer target.
332    pub const fn memory_block_buffer_target(&self) -> u64 {
333        self.memory_block_buffer_target
334    }
335
336    /// Return the persistence backpressure threshold.
337    pub const fn persistence_backpressure_threshold(&self) -> u64 {
338        self.persistence_backpressure_threshold
339    }
340
341    /// Return the block buffer limit.
342    pub const fn block_buffer_limit(&self) -> u32 {
343        self.block_buffer_limit
344    }
345
346    /// Return the maximum invalid cache header length.
347    pub const fn max_invalid_header_cache_length(&self) -> u32 {
348        self.max_invalid_header_cache_length
349    }
350
351    /// Return the invalid header cache hit eviction threshold.
352    ///
353    /// Setting this to `0` effectively disables the cache because entries are evicted on the
354    /// first lookup.
355    pub const fn invalid_header_hit_eviction_threshold(&self) -> u8 {
356        self.invalid_header_hit_eviction_threshold
357    }
358
359    /// Return the maximum execute block batch size.
360    pub const fn max_execute_block_batch_size(&self) -> usize {
361        self.max_execute_block_batch_size
362    }
363
364    /// Return the multiproof task chunk size.
365    pub const fn multiproof_chunk_size(&self) -> usize {
366        self.multiproof_chunk_size
367    }
368
369    /// Return the effective multiproof task chunk size.
370    pub const fn effective_multiproof_chunk_size(&self) -> usize {
371        self.multiproof_chunk_size
372    }
373
374    /// Return the number of reserved CPU cores for non-reth processes
375    pub const fn reserved_cpu_cores(&self) -> usize {
376        self.reserved_cpu_cores
377    }
378
379    /// Returns whether to use the legacy state root calculation method instead
380    /// of the new state root task
381    pub const fn legacy_state_root(&self) -> bool {
382        self.legacy_state_root
383    }
384
385    /// Returns whether or not state provider metrics are enabled.
386    pub const fn state_provider_metrics(&self) -> bool {
387        self.state_provider_metrics
388    }
389
390    /// Returns whether or not state cache is disabled.
391    pub const fn disable_state_cache(&self) -> bool {
392        self.disable_state_cache
393    }
394
395    /// Returns whether or not parallel prewarming is disabled.
396    pub const fn disable_prewarming(&self) -> bool {
397        self.disable_prewarming
398    }
399
400    /// Returns whether to always compare trie updates from the state root task to the trie updates
401    /// from the regular state root calculation.
402    pub const fn always_compare_trie_updates(&self) -> bool {
403        self.always_compare_trie_updates
404    }
405
406    /// Returns the cross-block cache size.
407    pub const fn cross_block_cache_size(&self) -> usize {
408        self.cross_block_cache_size
409    }
410
411    /// Returns whether precompile cache is disabled.
412    pub const fn precompile_cache_disabled(&self) -> bool {
413        self.precompile_cache_disabled
414    }
415
416    /// Returns whether to use state root fallback.
417    pub const fn state_root_fallback(&self) -> bool {
418        self.state_root_fallback
419    }
420
421    /// Sets whether to always process payload attributes when the FCU head is already canonical.
422    pub const fn with_always_process_payload_attributes_on_canonical_head(
423        mut self,
424        always_process_payload_attributes_on_canonical_head: bool,
425    ) -> Self {
426        self.always_process_payload_attributes_on_canonical_head =
427            always_process_payload_attributes_on_canonical_head;
428        self
429    }
430
431    /// Returns true if payload attributes should always be processed even when the FCU head is
432    /// canonical.
433    pub const fn always_process_payload_attributes_on_canonical_head(&self) -> bool {
434        self.always_process_payload_attributes_on_canonical_head
435    }
436
437    /// Returns true if canonical header should be unwound to ancestor during forkchoice updates.
438    pub const fn unwind_canonical_header(&self) -> bool {
439        self.allow_unwind_canonical_header
440    }
441
442    /// Setter for persistence threshold.
443    pub const fn with_persistence_threshold(mut self, persistence_threshold: u64) -> Self {
444        self.persistence_threshold = persistence_threshold;
445        assert_backpressure_threshold_invariant(
446            self.persistence_threshold,
447            self.persistence_backpressure_threshold,
448        );
449        self
450    }
451
452    /// Setter for memory block buffer target.
453    pub const fn with_memory_block_buffer_target(
454        mut self,
455        memory_block_buffer_target: u64,
456    ) -> Self {
457        self.memory_block_buffer_target = memory_block_buffer_target;
458        self
459    }
460
461    /// Setter for persistence backpressure threshold.
462    pub const fn with_persistence_backpressure_threshold(
463        mut self,
464        persistence_backpressure_threshold: u64,
465    ) -> Self {
466        self.persistence_backpressure_threshold = persistence_backpressure_threshold;
467        assert_backpressure_threshold_invariant(
468            self.persistence_threshold,
469            self.persistence_backpressure_threshold,
470        );
471        self
472    }
473
474    /// Setter for block buffer limit.
475    pub const fn with_block_buffer_limit(mut self, block_buffer_limit: u32) -> Self {
476        self.block_buffer_limit = block_buffer_limit;
477        self
478    }
479
480    /// Setter for maximum invalid header cache length.
481    pub const fn with_max_invalid_header_cache_length(
482        mut self,
483        max_invalid_header_cache_length: u32,
484    ) -> Self {
485        self.max_invalid_header_cache_length = max_invalid_header_cache_length;
486        self
487    }
488
489    /// Setter for the invalid header cache hit eviction threshold.
490    pub const fn with_invalid_header_hit_eviction_threshold(
491        mut self,
492        invalid_header_hit_eviction_threshold: u8,
493    ) -> Self {
494        self.invalid_header_hit_eviction_threshold = invalid_header_hit_eviction_threshold;
495        self
496    }
497
498    /// Setter for maximum execute block batch size.
499    pub const fn with_max_execute_block_batch_size(
500        mut self,
501        max_execute_block_batch_size: usize,
502    ) -> Self {
503        self.max_execute_block_batch_size = max_execute_block_batch_size;
504        self
505    }
506
507    /// Setter for whether to use the legacy state root calculation method.
508    pub const fn with_legacy_state_root(mut self, legacy_state_root: bool) -> Self {
509        self.legacy_state_root = legacy_state_root;
510        self
511    }
512
513    /// Setter for whether to disable state cache.
514    pub const fn without_state_cache(mut self, disable_state_cache: bool) -> Self {
515        self.disable_state_cache = disable_state_cache;
516        self
517    }
518
519    /// Setter for whether to disable parallel prewarming.
520    pub const fn without_prewarming(mut self, disable_prewarming: bool) -> Self {
521        self.disable_prewarming = disable_prewarming;
522        self
523    }
524
525    /// Setter for whether to always compare trie updates from the state root task to the trie
526    /// updates from the regular state root calculation.
527    pub const fn with_always_compare_trie_updates(
528        mut self,
529        always_compare_trie_updates: bool,
530    ) -> Self {
531        self.always_compare_trie_updates = always_compare_trie_updates;
532        self
533    }
534
535    /// Setter for cross block cache size.
536    pub const fn with_cross_block_cache_size(mut self, cross_block_cache_size: usize) -> Self {
537        self.cross_block_cache_size = cross_block_cache_size;
538        self
539    }
540
541    /// Setter for has enough parallelism.
542    pub const fn with_has_enough_parallelism(mut self, has_enough_parallelism: bool) -> Self {
543        self.has_enough_parallelism = has_enough_parallelism;
544        self
545    }
546
547    /// Setter for state provider metrics.
548    pub const fn with_state_provider_metrics(mut self, state_provider_metrics: bool) -> Self {
549        self.state_provider_metrics = state_provider_metrics;
550        self
551    }
552
553    /// Setter for multiproof task chunk size for proof targets.
554    pub const fn with_multiproof_chunk_size(mut self, multiproof_chunk_size: usize) -> Self {
555        self.multiproof_chunk_size = multiproof_chunk_size;
556        self
557    }
558
559    /// Setter for the number of reserved CPU cores for any non-reth processes
560    pub const fn with_reserved_cpu_cores(mut self, reserved_cpu_cores: usize) -> Self {
561        self.reserved_cpu_cores = reserved_cpu_cores;
562        self
563    }
564
565    /// Setter for whether to disable the precompile cache.
566    pub const fn without_precompile_cache(mut self, precompile_cache_disabled: bool) -> Self {
567        self.precompile_cache_disabled = precompile_cache_disabled;
568        self
569    }
570
571    /// Setter for whether to use state root fallback, useful for testing.
572    pub const fn with_state_root_fallback(mut self, state_root_fallback: bool) -> Self {
573        self.state_root_fallback = state_root_fallback;
574        self
575    }
576
577    /// Setter for whether to unwind canonical header to ancestor during forkchoice updates.
578    pub const fn with_unwind_canonical_header(mut self, unwind_canonical_header: bool) -> Self {
579        self.allow_unwind_canonical_header = unwind_canonical_header;
580        self
581    }
582
583    /// Whether or not to use state root task
584    pub const fn use_state_root_task(&self) -> bool {
585        self.has_enough_parallelism && !self.legacy_state_root
586    }
587
588    /// Returns whether cache metrics recording is disabled.
589    pub const fn disable_cache_metrics(&self) -> bool {
590        self.disable_cache_metrics
591    }
592
593    /// Setter for whether to disable cache metrics recording.
594    pub const fn without_cache_metrics(mut self, disable_cache_metrics: bool) -> Self {
595        self.disable_cache_metrics = disable_cache_metrics;
596        self
597    }
598
599    /// Returns the sparse trie prune depth.
600    pub const fn sparse_trie_prune_depth(&self) -> usize {
601        self.sparse_trie_prune_depth
602    }
603
604    /// Setter for sparse trie prune depth.
605    pub const fn with_sparse_trie_prune_depth(mut self, depth: usize) -> Self {
606        self.sparse_trie_prune_depth = depth;
607        self
608    }
609
610    /// Returns the LFU hot-slot capacity for sparse trie pruning.
611    pub const fn sparse_trie_max_hot_slots(&self) -> usize {
612        self.sparse_trie_max_hot_slots
613    }
614
615    /// Setter for LFU hot-slot capacity.
616    pub const fn with_sparse_trie_max_hot_slots(mut self, max_hot_slots: usize) -> Self {
617        self.sparse_trie_max_hot_slots = max_hot_slots;
618        self
619    }
620
621    /// Returns the LFU hot-account capacity for sparse trie pruning.
622    pub const fn sparse_trie_max_hot_accounts(&self) -> usize {
623        self.sparse_trie_max_hot_accounts
624    }
625
626    /// Setter for LFU hot-account capacity.
627    pub const fn with_sparse_trie_max_hot_accounts(mut self, max_hot_accounts: usize) -> Self {
628        self.sparse_trie_max_hot_accounts = max_hot_accounts;
629        self
630    }
631
632    /// Returns the slow block threshold, if configured.
633    ///
634    /// When `Some`, blocks whose total processing time exceeds this duration emit a structured
635    /// warning with timing, state-operation, and cache-hit-rate details. `Duration::ZERO` logs
636    /// every block.
637    pub const fn slow_block_threshold(&self) -> Option<Duration> {
638        self.slow_block_threshold
639    }
640
641    /// Setter for slow block threshold.
642    pub const fn with_slow_block_threshold(
643        mut self,
644        slow_block_threshold: Option<Duration>,
645    ) -> Self {
646        self.slow_block_threshold = slow_block_threshold;
647        self
648    }
649
650    /// Returns whether sparse trie cache pruning is disabled.
651    pub const fn disable_sparse_trie_cache_pruning(&self) -> bool {
652        self.disable_sparse_trie_cache_pruning
653    }
654
655    /// Setter for whether to disable sparse trie cache pruning.
656    pub const fn with_disable_sparse_trie_cache_pruning(mut self, value: bool) -> Self {
657        self.disable_sparse_trie_cache_pruning = value;
658        self
659    }
660
661    /// Returns the state root task timeout.
662    pub const fn state_root_task_timeout(&self) -> Option<Duration> {
663        self.state_root_task_timeout
664    }
665
666    /// Setter for state root task timeout.
667    pub const fn with_state_root_task_timeout(mut self, timeout: Option<Duration>) -> Self {
668        self.state_root_task_timeout = timeout;
669        self
670    }
671
672    /// Returns whether to share execution cache with the payload builder.
673    pub const fn share_execution_cache_with_payload_builder(&self) -> bool {
674        self.share_execution_cache_with_payload_builder
675    }
676
677    /// Returns whether to share sparse trie with the payload builder.
678    pub const fn share_sparse_trie_with_payload_builder(&self) -> bool {
679        self.share_sparse_trie_with_payload_builder
680    }
681
682    /// Setter for whether to share execution cache with the payload builder.
683    pub const fn with_share_execution_cache_with_payload_builder(
684        mut self,
685        share_execution_cache_with_payload_builder: bool,
686    ) -> Self {
687        self.share_execution_cache_with_payload_builder =
688            share_execution_cache_with_payload_builder;
689        self
690    }
691
692    /// Setter for whether to share sparse trie with the payload builder.
693    pub const fn with_share_sparse_trie_with_payload_builder(
694        mut self,
695        share_sparse_trie_with_payload_builder: bool,
696    ) -> Self {
697        self.share_sparse_trie_with_payload_builder = share_sparse_trie_with_payload_builder;
698        self
699    }
700
701    /// Returns whether persistence is suppressed during payload building.
702    pub const fn suppress_persistence_during_build(&self) -> bool {
703        self.suppress_persistence_during_build
704    }
705
706    /// Setter for whether to suppress persistence during payload building.
707    pub const fn with_suppress_persistence_during_build(mut self, value: bool) -> Self {
708        self.suppress_persistence_during_build = value;
709        self
710    }
711
712    /// Returns whether BAL-based parallel execution is disabled.
713    pub const fn disable_bal_parallel_execution(&self) -> bool {
714        self.disable_bal_parallel_execution
715    }
716
717    /// Setter for whether to disable BAL-based parallel execution.
718    pub const fn without_bal_parallel_execution(
719        mut self,
720        disable_bal_parallel_execution: bool,
721    ) -> Self {
722        self.disable_bal_parallel_execution = disable_bal_parallel_execution;
723        self
724    }
725
726    /// Returns whether BAL-driven parallel state root computation is disabled.
727    pub const fn disable_bal_parallel_state_root(&self) -> bool {
728        self.disable_bal_parallel_state_root
729    }
730
731    /// Setter for whether to disable BAL-driven parallel state root computation.
732    pub const fn without_bal_parallel_state_root(
733        mut self,
734        disable_bal_parallel_state_root: bool,
735    ) -> Self {
736        self.disable_bal_parallel_state_root = disable_bal_parallel_state_root;
737        self
738    }
739
740    /// Returns whether BAL state prefetching during prewarm is disabled.
741    pub const fn disable_bal_batch_io(&self) -> bool {
742        self.disable_bal_batch_io
743    }
744
745    /// Setter for whether to disable BAL state prefetching during prewarm.
746    pub const fn without_bal_batch_io(mut self, disable_bal_batch_io: bool) -> Self {
747        self.disable_bal_batch_io = disable_bal_batch_io;
748        self
749    }
750
751    /// Returns the proof jitter duration, if configured (trie-debug only).
752    #[cfg(feature = "trie-debug")]
753    pub const fn proof_jitter(&self) -> Option<Duration> {
754        self.proof_jitter
755    }
756
757    /// Setter for proof jitter (trie-debug only).
758    #[cfg(feature = "trie-debug")]
759    pub const fn with_proof_jitter(mut self, proof_jitter: Option<Duration>) -> Self {
760        self.proof_jitter = proof_jitter;
761        self
762    }
763}
764
765#[cfg(test)]
766mod tests {
767    use super::TreeConfig;
768
769    #[test]
770    #[should_panic(
771        expected = "persistence_backpressure_threshold must be greater than persistence_threshold"
772    )]
773    fn rejects_backpressure_threshold_at_or_below_persistence_threshold() {
774        let _ = TreeConfig::default()
775            .with_persistence_threshold(4)
776            .with_persistence_backpressure_threshold(4);
777    }
778}
reth_engine_primitives/config.rs

reth_engine_primitives/
config.rs
