feat(client-lib): get cardano stake distribution for latest epoch with/without offset

Author: Alenar

mithril-client/src/aggregator_client.rs

@@ -145,6 +145,12 @@ pub enum AggregatorRequest {
         epoch: Epoch,
     },
 
+    /// Get a specific [Cardano stake distribution][crate::CardanoStakeDistribution] from the aggregator for the latest epoch
+    GetCardanoStakeDistributionForLatestEpoch {
+        /// Optional offset to subtract to the latest epoch
+        offset: Option<u64>,
+    },
+
     /// Lists the aggregator [Cardano stake distribution][crate::CardanoStakeDistribution]
     ListCardanoStakeDistributions,
 
@@ -218,6 +224,12 @@ impl AggregatorRequest {
             AggregatorRequest::GetCardanoStakeDistributionByEpoch { epoch } => {
                 format!("artifact/cardano-stake-distribution/epoch/{epoch}")
             }
+            AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset } => {
+                format!(
+                    "artifact/cardano-stake-distribution/epoch/latest{}",
+                    offset.map(|o| format!("-{o}")).unwrap_or_default()
+                )
+            }
             AggregatorRequest::ListCardanoStakeDistributions => {
                 "artifact/cardano-stake-distributions".to_string()
             }
@@ -705,6 +717,17 @@ mod tests {
             AggregatorRequest::GetCardanoStakeDistributionByEpoch { epoch: Epoch(123) }.route()
         );
 
+        assert_eq!(
+            "artifact/cardano-stake-distribution/epoch/latest".to_string(),
+            AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset: None }.route()
+        );
+
+        assert_eq!(
+            "artifact/cardano-stake-distribution/epoch/latest-8".to_string(),
+            AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset: Some(8) }
+                .route()
+        );
+
         assert_eq!(
             "artifact/cardano-stake-distributions".to_string(),
             AggregatorRequest::ListCardanoStakeDistributions.route()

mithril-client/src/cardano_stake_distribution_client.rs

@@ -47,15 +47,20 @@
 //! # Get a Cardano stake distribution by epoch
 //!
 //! To get a Cardano stake distribution by epoch using the [ClientBuilder][crate::client::ClientBuilder].
-//! The epoch represents the epoch at the end of which the Cardano stake distribution is computed by the Cardano node
+//!
+//! **Note:** The epoch represents the epoch at the end of which the Cardano stake distribution is computed by the Cardano node
 //!
 //! ```no_run
 //! # async fn run() -> mithril_client::MithrilResult<()> {
-//! use mithril_client::ClientBuilder;
-//! use mithril_client::common::Epoch;
+//! use mithril_client::{ClientBuilder, common::Epoch};
 //!
 //! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
+//! // For a specific epoch
 //! let cardano_stake_distribution = client.cardano_stake_distribution().get_by_epoch(Epoch(500)).await?.unwrap();
+//! // For the latest epoch known by the Mithril aggregator
+//! let cardano_stake_distribution = client.cardano_stake_distribution().get_for_latest_epoch().await?.unwrap();
+//! // For the latest epoch known by the Mithril aggregator with an offset
+//! let cardano_stake_distribution = client.cardano_stake_distribution().get_for_latest_epoch_with_offset(4).await?.unwrap();
 //!
 //! println!(
 //!     "Cardano stake distribution hash={}, epoch={}, stake_distribution={:?}",
@@ -117,6 +122,27 @@ impl CardanoStakeDistributionClient {
         .await
     }
 
+    /// Get the given Cardano stake distribution data by epoch.
+    pub async fn get_for_latest_epoch(&self) -> MithrilResult<Option<CardanoStakeDistribution>> {
+        self.fetch_with_aggregator_request(
+            AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset: None },
+        )
+        .await
+    }
+
+    /// Get the given Cardano stake distribution data by epoch.
+    pub async fn get_for_latest_epoch_with_offset(
+        &self,
+        offset: u64,
+    ) -> MithrilResult<Option<CardanoStakeDistribution>> {
+        self.fetch_with_aggregator_request(
+            AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch {
+                offset: Some(offset),
+            },
+        )
+        .await
+    }
+
     /// Fetch the given Cardano stake distribution data with an aggregator request.
     /// If it cannot be found, a None is returned.
     async fn fetch_with_aggregator_request(
@@ -280,4 +306,50 @@ mod tests {
 
         assert_eq!(expected_message, cardano_stake_distribution);
     }
+
+    #[tokio::test]
+    async fn get_cardano_stake_distribution_for_latest_epoch_returns_message() {
+        let expected_message = CardanoStakeDistribution::dummy();
+        let mut http_client = MockAggregatorClient::new();
+        http_client
+            .expect_get_content()
+            .with(eq(
+                AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset: None },
+            ))
+            .return_once(move |_| {
+                Ok(serde_json::to_string(&CardanoStakeDistribution::dummy()).unwrap())
+            });
+        let client = CardanoStakeDistributionClient::new(Arc::new(http_client));
+
+        let cardano_stake_distribution = client
+            .get_for_latest_epoch()
+            .await
+            .unwrap()
+            .expect("This test returns a Cardano stake distribution");
+
+        assert_eq!(expected_message, cardano_stake_distribution);
+    }
+
+    #[tokio::test]
+    async fn get_cardano_stake_distribution_for_latest_with_offset_epoch_returns_message() {
+        let expected_message = CardanoStakeDistribution::dummy();
+        let mut http_client = MockAggregatorClient::new();
+        http_client
+            .expect_get_content()
+            .with(eq(
+                AggregatorRequest::GetCardanoStakeDistributionForLatestEpoch { offset: Some(4) },
+            ))
+            .return_once(move |_| {
+                Ok(serde_json::to_string(&CardanoStakeDistribution::dummy()).unwrap())
+            });
+        let client = CardanoStakeDistributionClient::new(Arc::new(http_client));
+
+        let cardano_stake_distribution = client
+            .get_for_latest_epoch_with_offset(4)
+            .await
+            .unwrap()
+            .expect("This test returns a Cardano stake distribution");
+
+        assert_eq!(expected_message, cardano_stake_distribution);
+    }
 }