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

iota_sdk/apis/
governance.rs
