sui_types/
node_role.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::base_types::AuthorityName;
5use crate::committee::Committee;
6use serde::{Deserialize, Serialize};
7
8/// How a full node syncs data from the network.
9#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(rename_all = "kebab-case")]
11pub enum FullNodeSyncMode {
12    /// Syncs exclusively via the state-sync protocol.
13    StateSyncOnly = 0,
14    /// Streams consensus blocks for faster ingestion, in addition to state sync.
15    ConsensusObserver = 1,
16}
17
18/// Represents the role a node plays in the network for a given epoch.
19/// A node is either a Validator (in the committee) or a FullNode (not in
20/// the committee). FullNodes carry a sync mode that determines whether
21/// they also participate in consensus as an observer.
22///
23/// Behavior should be gated through capability methods (e.g. `runs_consensus()`) rather than matching on variants directly.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub enum NodeRole {
26    /// A validator that participates in consensus, proposes blocks and signs checkpoints.
27    Validator,
28    /// A full node that serves RPC/indexing and syncs via the configured mode.
29    FullNode(FullNodeSyncMode),
30}
31
32impl NodeRole {
33    /// Determines the node role from committee membership and the configured sync mode.
34    /// Used per-epoch in AuthorityPerEpochStore to derive the authoritative role.
35    pub fn from_committee(
36        committee: &Committee,
37        name: &AuthorityName,
38        fullnode_sync_mode: Option<FullNodeSyncMode>,
39    ) -> Self {
40        if committee.authority_exists(name) {
41            NodeRole::Validator
42        } else if let Some(mode) = fullnode_sync_mode {
43            NodeRole::FullNode(mode)
44        } else {
45            NodeRole::FullNode(FullNodeSyncMode::StateSyncOnly)
46        }
47    }
48
49    pub fn is_fullnode(&self) -> bool {
50        matches!(self, Self::FullNode(_))
51    }
52
53    pub fn is_validator(&self) -> bool {
54        matches!(self, Self::Validator)
55    }
56    // --- Capability methods ---
57
58    /// Whether this node participates in the consensus protocol.
59    pub fn runs_consensus(&self) -> bool {
60        matches!(
61            self,
62            Self::Validator | Self::FullNode(FullNodeSyncMode::ConsensusObserver)
63        )
64    }
65
66    /// Whether this node should create index stores for JSON-RPC and REST API.
67    pub fn should_enable_index_processing(&self) -> bool {
68        matches!(self, Self::FullNode(_))
69    }
70
71    /// Whether this node should process consensus commit output (execute
72    /// transactions, create checkpoints, etc.). Observers stream blocks but
73    /// rely on state-sync for execution, so they skip commit processing.
74    pub fn should_process_consensus_commits(&self) -> bool {
75        matches!(self, Self::Validator)
76    }
77
78    /// Whether this node should expose HTTP/RPC servers (JSON-RPC, REST).
79    pub fn should_run_rpc_servers(&self) -> bool {
80        matches!(self, Self::FullNode(_))
81    }
82}
83
84impl std::fmt::Display for NodeRole {
85    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86        match self {
87            Self::Validator => write!(f, "Validator"),
88            Self::FullNode(FullNodeSyncMode::StateSyncOnly) => write!(f, "FullNode"),
89            Self::FullNode(FullNodeSyncMode::ConsensusObserver) => {
90                write!(f, "FullNode(ConsensusObserver)")
91            }
92        }
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn test_validator_role() {
102        let role = NodeRole::Validator;
103        assert!(role.runs_consensus());
104        assert!(!role.should_enable_index_processing());
105        assert!(!role.should_run_rpc_servers());
106        assert!(role.should_process_consensus_commits());
107    }
108
109    #[test]
110    fn test_consensus_observer_role() {
111        let role = NodeRole::FullNode(FullNodeSyncMode::ConsensusObserver);
112        assert!(role.runs_consensus());
113        assert!(role.should_enable_index_processing());
114        assert!(role.should_run_rpc_servers());
115        assert!(!role.should_process_consensus_commits());
116    }
117
118    #[test]
119    fn test_fullnode_state_sync_role() {
120        let role = NodeRole::FullNode(FullNodeSyncMode::StateSyncOnly);
121        assert!(!role.runs_consensus());
122        assert!(role.should_enable_index_processing());
123        assert!(role.should_run_rpc_servers());
124        assert!(!role.should_process_consensus_commits());
125    }
126}
sui_types/node_role.rs

sui_types/
node_role.rs
