iota_sdk/apis/
governance.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::sync::Arc;
6
7use iota_json_rpc_api::GovernanceReadApiClient;
8use iota_json_rpc_types::{DelegatedStake, DelegatedTimelockedStake, IotaCommittee, ValidatorApys};
9use iota_types::{
10    base_types::IotaAddress, iota_serde::BigInt,
11    iota_system_state::iota_system_state_summary::IotaSystemStateSummary,
12};
13
14use crate::{RpcClient, error::IotaRpcResult};
15
16/// Defines methods to get committee and staking info.
17#[derive(Debug, Clone)]
18pub struct GovernanceApi {
19    api: Arc<RpcClient>,
20}
21
22impl GovernanceApi {
23    pub(crate) fn new(api: Arc<RpcClient>) -> Self {
24        Self { api }
25    }
26
27    /// Get a list of delegated stakes for the given address.
28    pub async fn get_stakes(&self, owner: IotaAddress) -> IotaRpcResult<Vec<DelegatedStake>> {
29        Ok(self.api.http.get_stakes(owner).await?)
30    }
31
32    /// Get a list of delegated timelocked stakes for the given address.
33    pub async fn get_timelocked_stakes(
34        &self,
35        owner: IotaAddress,
36    ) -> IotaRpcResult<Vec<DelegatedTimelockedStake>> {
37        Ok(self.api.http.get_timelocked_stakes(owner).await?)
38    }
39
40    /// Get committee information for the given epoch.
41    ///
42    /// The epoch defaults to the current epoch.
43    ///
44    /// # Examples
45    ///
46    /// ```rust,no_run
47    /// use iota_sdk::IotaClientBuilder;
48    ///
49    /// #[tokio::main]
50    /// async fn main() -> Result<(), anyhow::Error> {
51    ///     let iota = IotaClientBuilder::default().build_testnet().await?;
52    ///     let committee_info = iota.governance_api().get_committee_info(None).await?;
53    ///     Ok(())
54    /// }
55    /// ```
56    pub async fn get_committee_info(
57        &self,
58        epoch: impl Into<Option<BigInt<u64>>>,
59    ) -> IotaRpcResult<IotaCommittee> {
60        Ok(self.api.http.get_committee_info(epoch.into()).await?)
61    }
62
63    /// Get the latest IOTA system state object on-chain.
64    ///
65    /// Use this method to access system information, such as the current epoch,
66    /// the protocol version, the reference gas price, the total stake, active
67    /// validators, and much more.
68    #[allow(deprecated)]
69    pub async fn get_latest_iota_system_state(&self) -> IotaRpcResult<IotaSystemStateSummary> {
70        if self.api.info.iota_system_state_v2_support {
71            Ok(self.api.http.get_latest_iota_system_state_v2().await?)
72        } else {
73            // Fallback to v1, v2 is not available on networks with protocol version < 5
74            Ok(self
75                .api
76                .http
77                .get_latest_iota_system_state()
78                .await
79                .map(IotaSystemStateSummary::from)?)
80        }
81    }
82
83    /// Get the reference gas price for the network.
84    pub async fn get_reference_gas_price(&self) -> IotaRpcResult<u64> {
85        Ok(*self.api.http.get_reference_gas_price().await?)
86    }
87
88    /// Get the validators APY.
89    pub async fn get_validators_apy(&self) -> IotaRpcResult<ValidatorApys> {
90        Ok(self.api.http.get_validators_apy().await?)
91    }
92}
iota_sdk/apis/governance.rs

iota_sdk/apis/
governance.rs
