Skip to main content

sui_rpc_api/grpc/v2/ledger_service/
get_epoch.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::ErrorReason;
5use crate::Result;
6use crate::RpcService;
7use crate::error::EpochNotFoundError;
8use crate::reader::indexes_disabled;
9use prost_types::FieldMask;
10use prost_types::value::Kind;
11use std::collections::BTreeMap;
12use sui_rpc::field::FieldMaskTree;
13use sui_rpc::field::FieldMaskUtil;
14use sui_rpc::merge::Merge;
15use sui_rpc::proto::google::rpc::bad_request::FieldViolation;
16use sui_rpc::proto::sui::rpc::v2::Epoch;
17use sui_rpc::proto::sui::rpc::v2::GetEpochRequest;
18use sui_rpc::proto::sui::rpc::v2::GetEpochResponse;
19use sui_rpc::proto::sui::rpc::v2::ProtocolConfig;
20use sui_rpc::proto::sui::rpc::v2::SystemEpochInfo;
21use sui_rpc::proto::timestamp_ms_to_proto;
22use sui_sdk_types::EpochId;
23use sui_types::storage::EpochInfo;
24use sui_types::sui_system_state::SuiSystemState;
25use sui_types::sui_system_state::SuiSystemStateTrait;
26
27pub const READ_MASK_DEFAULT: &str = crate::read_mask_defaults::EPOCH;
28
29/// The latest epoch is the live system state's. The live epoch's `protocol_config`, `start`,
30/// `reference_gas_price` and `system_state` come from the live state; any other epoch's come from
31/// its rpc-store row, with `system_state` the epoch-start snapshot. The end-of-epoch fields are
32/// set exactly when `last_checkpoint` is, from the same rpc-store row, as soon as the row has
33/// them.
34#[tracing::instrument(skip(service))]
35pub fn get_epoch(service: &RpcService, request: GetEpochRequest) -> Result<GetEpochResponse> {
36    let read_mask = {
37        let read_mask = request
38            .read_mask
39            .unwrap_or_else(|| FieldMask::from_str(READ_MASK_DEFAULT));
40        read_mask.validate::<Epoch>().map_err(|path| {
41            FieldViolation::new("read_mask")
42                .with_description(format!("invalid read_mask path: {path}"))
43                .with_reason(ErrorReason::FieldInvalid)
44        })?;
45        FieldMaskTree::from(read_mask)
46    };
47
48    let mut message = Epoch::default();
49
50    let current_system_state = service.reader.get_system_state()?;
51    let live_epoch = current_system_state.epoch();
52
53    let indexes = service.reader.inner().indexes();
54    let epoch = request.epoch.unwrap_or(live_epoch);
55
56    // A past epoch's data lives only in the rpc indexes; the live system state is the live
57    // epoch's. An epoch after the live one does not exist yet, which needs no index to tell.
58    if epoch < live_epoch && indexes.is_none() {
59        return Err(indexes_disabled());
60    }
61
62    // Fetch epoch info, if indexing is available.
63    let epoch_info = indexes
64        .map(|indexes| indexes.get_epoch_info(epoch))
65        .transpose()?
66        .flatten();
67
68    if epoch != live_epoch && epoch_info.is_none() {
69        return Err(EpochNotFoundError::new(epoch).into());
70    }
71
72    if read_mask.contains(Epoch::EPOCH_FIELD.name) {
73        message.set_epoch(epoch);
74    }
75
76    // The live epoch's protocol config, start and reference gas price come from the live state;
77    // any other epoch's come from its rpc-store row below.
78    if epoch == live_epoch {
79        let system_state = &current_system_state;
80        if let Some(submask) = read_mask.subtree(Epoch::PROTOCOL_CONFIG_FIELD) {
81            let chain = service.reader.inner().get_chain_identifier()?.chain();
82            let config = protocol_config_for_version(system_state.protocol_version(), chain)?;
83
84            message.set_protocol_config(ProtocolConfig::merge_from(config, &submask));
85        }
86
87        if read_mask.contains(Epoch::START_FIELD) {
88            message.set_start(timestamp_ms_to_proto(
89                system_state.epoch_start_timestamp_ms(),
90            ));
91        }
92
93        if read_mask.contains(Epoch::REFERENCE_GAS_PRICE_FIELD) {
94            message.set_reference_gas_price(system_state.reference_gas_price());
95        }
96    }
97
98    if let Some(epoch_info) = &epoch_info {
99        if read_mask.contains(Epoch::FIRST_CHECKPOINT_FIELD) {
100            message.first_checkpoint = epoch_info.start_checkpoint;
101        }
102
103        if read_mask.contains(Epoch::LAST_CHECKPOINT_FIELD) {
104            message.last_checkpoint = epoch_info.end_checkpoint;
105        }
106
107        if read_mask.contains(Epoch::START_FIELD) && message.start.is_none() {
108            message.start = epoch_info.start_timestamp_ms.map(timestamp_ms_to_proto);
109        }
110
111        if read_mask.contains(Epoch::END_FIELD) {
112            message.end = epoch_info.end_timestamp_ms.map(timestamp_ms_to_proto);
113        }
114
115        if read_mask.contains(Epoch::REFERENCE_GAS_PRICE_FIELD.name)
116            && message.reference_gas_price.is_none()
117        {
118            message.reference_gas_price = epoch_info.reference_gas_price;
119        }
120
121        if let Some(submask) = read_mask.subtree(Epoch::PROTOCOL_CONFIG_FIELD.name)
122            && message.protocol_config.is_none()
123        {
124            let chain = service.reader.inner().get_chain_identifier()?.chain();
125            let protocol_config = epoch_info
126                .protocol_version
127                .map(|version| protocol_config_for_version(version, chain))
128                .transpose()?;
129
130            message.protocol_config =
131                protocol_config.map(|config| ProtocolConfig::merge_from(config, &submask));
132        }
133
134        if epoch_info.end_checkpoint.is_some() {
135            set_epoch_end_fields(&mut message, &read_mask, epoch_info);
136        }
137    }
138
139    if read_mask.contains(Epoch::TRANSACTION_START_INCLUSIVE_FIELD) {
140        message.transaction_start_inclusive = match epoch.checked_sub(1) {
141            None => Some(0),
142            Some(previous) => indexes
143                .map(|indexes| indexes.get_epoch_info(previous))
144                .transpose()?
145                .flatten()
146                .and_then(|info| info.tx_hi),
147        };
148    }
149
150    if read_mask.contains(Epoch::COMMITTEE_FIELD.name) {
151        message.committee = Some(
152            service
153                .reader
154                .get_committee(epoch)
155                .ok_or_else(|| CommitteeNotFoundError::new(epoch))?
156                .into(),
157        );
158    }
159
160    if read_mask.contains(Epoch::SYSTEM_STATE_FIELD) {
161        let system_state = if epoch == live_epoch {
162            Some(current_system_state)
163        } else {
164            epoch_info.and_then(epoch_start_system_state)
165        };
166        message.system_state = system_state.map(|system_state| Box::new(system_state.into()));
167    }
168
169    Ok(GetEpochResponse::new(message))
170}
171
172/// The rpc-store row's epoch-start snapshot. A restore that lands mid-epoch seeds the row from
173/// the state at the restore point and leaves `start_checkpoint` unset until the epoch's first
174/// checkpoint is indexed, so that state is not served as the start state.
175fn epoch_start_system_state(epoch_info: EpochInfo) -> Option<SuiSystemState> {
176    epoch_info.start_checkpoint?;
177    epoch_info.system_state
178}
179
180/// Set the end-of-epoch fields `read_mask` selects from `epoch_info`. Call it exactly when the
181/// response serves the epoch's `last_checkpoint`, so the end fields appear together with it.
182pub fn set_epoch_end_fields(
183    message: &mut Epoch,
184    read_mask: &FieldMaskTree,
185    epoch_info: &EpochInfo,
186) {
187    if read_mask.contains(Epoch::TRANSACTION_END_EXCLUSIVE_FIELD) {
188        message.transaction_end_exclusive = epoch_info.tx_hi;
189    }
190    if read_mask.contains(Epoch::ENDED_IN_SAFE_MODE_FIELD) {
191        message.ended_in_safe_mode = epoch_info.safe_mode;
192    }
193    if read_mask.contains(Epoch::SYSTEM_EPOCH_INFO_FIELD) {
194        let mut info = SystemEpochInfo::default();
195        info.total_stake = epoch_info.total_stake;
196        info.storage_fund_reinvestment = epoch_info.storage_fund_reinvestment;
197        info.storage_charge = epoch_info.storage_charge;
198        info.storage_rebate = epoch_info.storage_rebate;
199        info.storage_fund_balance = epoch_info.storage_fund_balance;
200        info.stake_subsidy_amount = epoch_info.stake_subsidy_amount;
201        info.total_gas_fees = epoch_info.total_gas_fees;
202        info.total_stake_rewards_distributed = epoch_info.total_stake_rewards_distributed;
203        info.leftover_storage_fund_inflow = epoch_info.leftover_storage_fund_inflow;
204        // An epoch that ended in safe mode emitted no `SystemEpochInfoEvent`, so every counter
205        // is unset and so is the message.
206        message.system_epoch_info = (info != SystemEpochInfo::default()).then_some(info);
207    }
208    if read_mask.contains(Epoch::EPOCH_COMMITMENTS_FIELD) {
209        message.epoch_commitments = epoch_info
210            .epoch_commitments
211            .iter()
212            .flatten()
213            .cloned()
214            .map(Into::into)
215            .collect();
216    }
217}
218
219#[derive(Debug)]
220pub struct CommitteeNotFoundError {
221    epoch: EpochId,
222}
223
224impl CommitteeNotFoundError {
225    pub fn new(epoch: EpochId) -> Self {
226        Self { epoch }
227    }
228}
229
230impl std::fmt::Display for CommitteeNotFoundError {
231    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
232        write!(f, "Committee for epoch {} not found", self.epoch)
233    }
234}
235
236impl std::error::Error for CommitteeNotFoundError {}
237
238impl From<CommitteeNotFoundError> for crate::RpcError {
239    fn from(value: CommitteeNotFoundError) -> Self {
240        Self::new(tonic::Code::NotFound, value.to_string())
241    }
242}
243
244#[derive(Debug)]
245pub(super) struct ProtocolVersionNotFoundError {
246    version: u64,
247}
248
249impl ProtocolVersionNotFoundError {
250    pub fn new(version: u64) -> Self {
251        Self { version }
252    }
253}
254
255impl std::fmt::Display for ProtocolVersionNotFoundError {
256    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
257        write!(f, "Protocol version {} not found", self.version)
258    }
259}
260
261impl std::error::Error for ProtocolVersionNotFoundError {}
262
263impl From<ProtocolVersionNotFoundError> for crate::RpcError {
264    fn from(value: ProtocolVersionNotFoundError) -> Self {
265        Self::new(tonic::Code::NotFound, value.to_string())
266    }
267}
268
269pub(super) fn protocol_config_for_version(
270    version: u64,
271    chain: sui_protocol_config::Chain,
272) -> Result<ProtocolConfig, ProtocolVersionNotFoundError> {
273    let config =
274        sui_protocol_config::ProtocolConfig::get_for_version_if_supported(version.into(), chain)
275            .ok_or_else(|| ProtocolVersionNotFoundError::new(version))?;
276    Ok(protocol_config_to_proto(config))
277}
278
279pub fn protocol_config_to_proto(config: sui_protocol_config::ProtocolConfig) -> ProtocolConfig {
280    let attributes = config
281        .render::<prost_types::Value>(&mut mysten_common::rpc_format::Unmetered)
282        .expect("render to prost Value should succeed");
283    protocol_config_from_parts(config.version.as_u64(), attributes, config.feature_map())
284}
285
286/// Builds the proto message from a version's rendered settings and its feature flags.
287///
288/// `attributes` is the output of `ProtocolConfig::render`, with a null value for each setting
289/// that has no value at `protocol_version`. `feature_flags` is `ProtocolConfig::feature_map`.
290/// Settings with no value are left out of both `configs` and `attributes`.
291pub fn protocol_config_from_parts(
292    protocol_version: u64,
293    attributes: BTreeMap<String, prost_types::Value>,
294    feature_flags: BTreeMap<String, bool>,
295) -> ProtocolConfig {
296    let mut message = ProtocolConfig::default();
297    message.set_protocol_version(protocol_version);
298
299    // The deprecated string view of the settings: complex types are JSON-stringified.
300    message.set_attributes(
301        attributes
302            .iter()
303            .filter_map(|(k, v)| match &v.kind {
304                Some(Kind::NullValue(_)) | None => None,
305                Some(Kind::NumberValue(n)) => Some((k.to_owned(), n.to_string())),
306                Some(Kind::StringValue(s)) => Some((k.to_owned(), s.to_owned())),
307                Some(Kind::BoolValue(b)) => Some((k.to_owned(), b.to_string())),
308                Some(Kind::StructValue(s)) => Some((
309                    k.to_owned(),
310                    serde_json::to_string(&sui_rpc::_serde::StructSerializer(s)).unwrap(),
311                )),
312                Some(Kind::ListValue(list)) => Some((
313                    k.to_owned(),
314                    serde_json::to_string(&sui_rpc::_serde::ListValueSerializer(list)).unwrap(),
315                )),
316            })
317            .collect(),
318    );
319
320    let mut configs: BTreeMap<_, _> = attributes
321        .into_iter()
322        .filter(|(_, v)| !matches!(v.kind, None | Some(Kind::NullValue(_))))
323        .collect();
324
325    // `configs` holds the feature flags alongside the settings, as bool values.
326    for (name, enabled) in &feature_flags {
327        let old = configs.insert(name.clone(), prost_types::Value::from(*enabled));
328        debug_assert!(
329            old.is_none(),
330            "feature flags and attributes can't have keys which are the same"
331        );
332    }
333
334    message.set_feature_flags(feature_flags);
335    message.set_configs(configs);
336
337    message
338}
339
340#[cfg(test)]
341mod tests {
342    use super::*;
343    use sui_protocol_config::Chain;
344    use sui_protocol_config::ProtocolVersion;
345
346    const BOOL_SETTING: &str = "bridge_should_try_to_finalize_committee";
347
348    fn config_at(version: ProtocolVersion) -> sui_protocol_config::ProtocolConfig {
349        sui_protocol_config::ProtocolConfig::get_for_version(version, Chain::Unknown)
350    }
351
352    fn is_null(value: &prost_types::Value) -> bool {
353        matches!(value.kind, Some(Kind::NullValue(_)))
354    }
355
356    #[test]
357    fn boolean_setting_is_not_a_feature_flag() {
358        let config = config_at(ProtocolVersion::MAX);
359        let enabled = config
360            .bridge_should_try_to_finalize_committee_as_option()
361            .expect("set at the highest version");
362
363        let message = protocol_config_to_proto(config);
364
365        assert!(!message.feature_flags.contains_key(BOOL_SETTING));
366        assert_eq!(
367            message.configs[BOOL_SETTING],
368            prost_types::Value::from(enabled)
369        );
370        assert_eq!(message.attributes[BOOL_SETTING], enabled.to_string());
371    }
372
373    #[test]
374    fn protocol_config_omits_unset_settings() {
375        let min_config = config_at(ProtocolVersion::MIN);
376        assert!(
377            min_config
378                .bridge_should_try_to_finalize_committee_as_option()
379                .is_none()
380        );
381        let message = protocol_config_to_proto(min_config);
382        assert!(!message.configs.contains_key(BOOL_SETTING));
383        assert!(!message.attributes.contains_key(BOOL_SETTING));
384
385        for version in [ProtocolVersion::MIN, ProtocolVersion::MAX] {
386            let config = config_at(version);
387            let feature_flags = config.feature_map();
388            let settings: BTreeMap<_, _> = config
389                .render::<prost_types::Value>(&mut mysten_common::rpc_format::Unmetered)
390                .unwrap()
391                .into_iter()
392                .filter(|(_, v)| !is_null(v))
393                .collect();
394
395            let message = protocol_config_to_proto(config);
396
397            assert_eq!(message.protocol_version, Some(version.as_u64()));
398            assert_eq!(message.feature_flags, feature_flags);
399
400            let mut expected_configs = settings.clone();
401            expected_configs.extend(
402                feature_flags
403                    .iter()
404                    .map(|(k, v)| (k.clone(), prost_types::Value::from(*v))),
405            );
406            assert_eq!(message.configs, expected_configs);
407
408            // `attributes` holds exactly the settings with a value.
409            assert!(message.attributes.keys().eq(settings.keys()));
410        }
411    }
412}