commonware_consensus/marshal/
config.rs

1use crate::{
2    Block,
3    simplex::types::Finalization,
4    types::{Epoch, Epocher, ViewDelta},
5};
6use commonware_cryptography::{
7    Digest, Digestible,
8    certificate::{Provider, Scheme},
9};
10use commonware_parallel::Strategy;
11use commonware_runtime::buffer::paged::CacheRef;
12use std::num::{NonZeroU64, NonZeroUsize};
13
14/// Startup anchor for marshal.
15///
16/// Durable progress from a previous run takes precedence when it already
17/// supersedes the configured anchor.
18pub enum Start<S: Scheme, C: Digest, B> {
19    /// Start from the height-zero genesis block.
20    Genesis(B),
21    /// Start from a finalized commitment.
22    Floor(Finalization<S, C>),
23}
24
25/// Marshal configuration.
26///
27/// # Epocher and Provider Coverage
28///
29/// Any height marshal is asked to sync must be covered by both the
30/// [epocher](Self::epocher) and the [provider](Self::provider). If
31/// either returns `None` for a requested height, resolved requests will
32/// be acknowledged and then dropped. If no longer needed (say a duplicate request
33/// for a height we've long since processed), this drop is harmless. However, failing
34/// to provide either the epocher or the provider for a height we still require to
35/// process the canonical chain will lead marshal to stall (acknowledged requests
36/// may not be retried).
37///
38/// ## Safe Pruning
39///
40/// Applications may prune epocher/provider entries once the last processed
41/// height passes a prune target. The last processed height can be
42/// derived from an `Update::Block` at height `H` as
43/// `H - max_pending_acks` (the maximum backlog of blocks the application can buffer).
44pub struct Config<P, ES, T, AB, B, C = <AB as Digestible>::Digest>
45where
46    AB: Block,
47    C: Digest,
48    P: Provider<Scope = Epoch>,
49    ES: Epocher,
50    T: Strategy,
51{
52    /// Provider for epoch-specific signing schemes.
53    ///
54    /// Must cover every epoch that contains heights the marshal will sync.
55    pub provider: P,
56
57    /// Configuration for epoch lengths across block height ranges.
58    ///
59    /// Must cover every height the marshal will sync.
60    pub epocher: ES,
61
62    /// Startup anchor for marshal's processed floor.
63    pub start: Start<P::Scheme, C, B>,
64
65    /// The prefix to use for all partitions.
66    pub partition_prefix: String,
67
68    /// Size of backfill request/response mailbox.
69    pub mailbox_size: NonZeroUsize,
70
71    /// Minimum number of views to retain temporary data after the application processes a block.
72    ///
73    /// Useful for keeping around information that peers may desire to have.
74    pub view_retention: ViewDelta,
75
76    /// Prunable archive partition prefix.
77    pub prunable_items_per_section: NonZeroU64,
78
79    /// The page cache to use for the freezer journal.
80    pub page_cache: CacheRef,
81
82    /// The size of the replay buffer for storage archives.
83    pub replay_buffer: NonZeroUsize,
84
85    /// The size of the write buffer for the key journal of storage archives.
86    pub key_write_buffer: NonZeroUsize,
87
88    /// The size of the write buffer for the value journal of storage archives.
89    pub value_write_buffer: NonZeroUsize,
90
91    /// Codec configuration for block type.
92    pub block_codec_config: AB::Cfg,
93
94    /// Maximum number of blocks to repair at once.
95    pub max_repair: NonZeroUsize,
96
97    /// Maximum number of blocks dispatched to the application that have not
98    /// yet been acknowledged. Increasing this value allows the application
99    /// to buffer work while marshal continues dispatching, hiding ack latency.
100    pub max_pending_acks: NonZeroUsize,
101
102    /// Strategy for parallel operations.
103    pub strategy: T,
104}
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109    use crate::{
110        marshal::{coding::types::CodedBlock, mocks::block::Block},
111        simplex::{scheme::ed25519, types::Context},
112        types::{FixedEpocher, coding::Commitment},
113    };
114    use commonware_coding::ReedSolomon;
115    use commonware_cryptography::{
116        certificate::ConstantProvider,
117        ed25519::PublicKey,
118        sha256::{Digest as Sha256Digest, Sha256},
119    };
120    use commonware_parallel::Sequential;
121
122    #[test]
123    fn config_compiles_with_distinct_application_and_start_blocks() {
124        type AB = Block<Sha256Digest, Context<Sha256Digest, PublicKey>>;
125        type TestCommitment = Commitment<AB, ReedSolomon<Sha256>, Sha256>;
126        type B = CodedBlock<AB, ReedSolomon<Sha256>, Sha256>;
127        type Provider = ConstantProvider<ed25519::Scheme, Epoch>;
128
129        fn assert_well_formed<T>() {}
130
131        assert_well_formed::<Config<Provider, FixedEpocher, Sequential, AB, B, TestCommitment>>();
132    }
133}
commonware_consensus/marshal/config.rs

commonware_consensus/marshal/
config.rs
