sui_rpc_api/grpc/v2/ledger_service/
get_epoch.rs1use 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#[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 if epoch < live_epoch && indexes.is_none() {
59 return Err(indexes_disabled());
60 }
61
62 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 if epoch == live_epoch {
79 let system_state = ¤t_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
172fn epoch_start_system_state(epoch_info: EpochInfo) -> Option<SuiSystemState> {
176 epoch_info.start_checkpoint?;
177 epoch_info.system_state
178}
179
180pub 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 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
286pub 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 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 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 assert!(message.attributes.keys().eq(settings.keys()));
410 }
411 }
412}