solana_sdk/
commitment_config.rs

1//! Definitions of commitment levels.
2
3#![cfg(feature = "full")]
4
5use {std::str::FromStr, thiserror::Error};
6
7#[derive(Serialize, Deserialize, Default, Clone, Copy, Debug, PartialEq, Eq, Hash)]
8#[serde(rename_all = "camelCase")]
9pub struct CommitmentConfig {
10    pub commitment: CommitmentLevel,
11}
12
13impl CommitmentConfig {
14    pub const fn finalized() -> Self {
15        Self {
16            commitment: CommitmentLevel::Finalized,
17        }
18    }
19
20    pub const fn confirmed() -> Self {
21        Self {
22            commitment: CommitmentLevel::Confirmed,
23        }
24    }
25
26    pub const fn processed() -> Self {
27        Self {
28            commitment: CommitmentLevel::Processed,
29        }
30    }
31
32    pub fn ok(self) -> Option<Self> {
33        if self == Self::default() {
34            None
35        } else {
36            Some(self)
37        }
38    }
39
40    pub fn is_finalized(&self) -> bool {
41        self.commitment == CommitmentLevel::Finalized
42    }
43
44    pub fn is_confirmed(&self) -> bool {
45        self.commitment == CommitmentLevel::Confirmed
46    }
47
48    pub fn is_processed(&self) -> bool {
49        self.commitment == CommitmentLevel::Processed
50    }
51
52    pub fn is_at_least_confirmed(&self) -> bool {
53        self.is_confirmed() || self.is_finalized()
54    }
55
56    #[deprecated(
57        since = "2.0.2",
58        note = "Returns self. Please do not use. Will be removed in the future."
59    )]
60    pub fn use_deprecated_commitment(commitment: CommitmentConfig) -> Self {
61        commitment
62    }
63}
64
65impl FromStr for CommitmentConfig {
66    type Err = ParseCommitmentLevelError;
67
68    fn from_str(s: &str) -> Result<Self, Self::Err> {
69        CommitmentLevel::from_str(s).map(|commitment| Self { commitment })
70    }
71}
72
73#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq, Hash)]
74#[serde(rename_all = "camelCase")]
75/// An attribute of a slot. It describes how finalized a block is at some point in time. For example, a slot
76/// is said to be at the max level immediately after the cluster recognizes the block at that slot as
77/// finalized. When querying the ledger state, use lower levels of commitment to report progress and higher
78/// levels to ensure state changes will not be rolled back.
79pub enum CommitmentLevel {
80    /// The highest slot of the heaviest fork processed by the node. Ledger state at this slot is
81    /// not derived from a confirmed or finalized block, but if multiple forks are present, is from
82    /// the fork the validator believes is most likely to finalize.
83    Processed,
84
85    /// The highest slot that has been voted on by supermajority of the cluster, ie. is confirmed.
86    /// Confirmation incorporates votes from gossip and replay. It does not count votes on
87    /// descendants of a block, only direct votes on that block, and upholds "optimistic
88    /// confirmation" guarantees in release 1.3 and onwards.
89    Confirmed,
90
91    /// The highest slot having reached max vote lockout, as recognized by a supermajority of the
92    /// cluster.
93    Finalized,
94}
95
96impl Default for CommitmentLevel {
97    fn default() -> Self {
98        Self::Finalized
99    }
100}
101
102impl FromStr for CommitmentLevel {
103    type Err = ParseCommitmentLevelError;
104
105    fn from_str(s: &str) -> Result<Self, Self::Err> {
106        match s {
107            "processed" => Ok(CommitmentLevel::Processed),
108            "confirmed" => Ok(CommitmentLevel::Confirmed),
109            "finalized" => Ok(CommitmentLevel::Finalized),
110            _ => Err(ParseCommitmentLevelError::Invalid),
111        }
112    }
113}
114
115impl std::fmt::Display for CommitmentLevel {
116    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
117        let s = match self {
118            CommitmentLevel::Processed => "processed",
119            CommitmentLevel::Confirmed => "confirmed",
120            CommitmentLevel::Finalized => "finalized",
121        };
122        write!(f, "{s}")
123    }
124}
125
126#[derive(Error, Debug)]
127pub enum ParseCommitmentLevelError {
128    #[error("invalid variant")]
129    Invalid,
130}
solana_sdk/commitment_config.rs

solana_sdk/
commitment_config.rs
