feat(cat-gateway): cardano/assets V2 endpoint (#3606)

* Make stake_address optional parameter for the cardano assets endpoint

* Document remaining items

* Return information about all stake addresses

* Remove unused code

Author: stanislav-tkach

catalyst-gateway/bin/src/service/api/cardano/staking/assets_get.rs

@@ -85,7 +85,7 @@ struct TxoInfo {
 }
 
 /// Building a full stake info response from the provided arguments.
-async fn build_full_stake_info_response(
+pub(crate) async fn build_full_stake_info_response(
     stake_address: Cip19StakeAddress,
     provided_network: Option<Network>,
     slot_num: Option<SlotNo>,

catalyst-gateway/bin/src/service/api/cardano/staking/assets_get_v2.rs

@@ -0,0 +1,133 @@
+//! An implementation of the GET `v2/cardano/assets` endpoint.
+
+use std::collections::HashSet;
+
+use anyhow::Context;
+use futures::future::try_join_all;
+use poem_openapi::payload::Json;
+use poem_openapi_derive::ApiResponse;
+
+use crate::service::{
+    api::cardano::staking::assets_get::build_full_stake_info_response,
+    common::{
+        auth::{none_or_rbac::NoneOrRBAC, rbac::token::CatalystRBACTokenV1},
+        objects::cardano::{network::Network, stake_info::FullStakeInfo},
+        responses::WithErrorResponses,
+        types::{
+            cardano::{cip19_stake_address::Cip19StakeAddress, slot_no::SlotNo},
+            generic::error_msg::ErrorMessage,
+        },
+    },
+};
+
+/// An endpoint responses.
+#[derive(ApiResponse)]
+pub(crate) enum ResponsesV2 {
+    /// ## Ok
+    ///
+    /// The amount of ADA staked by the queried stake address, as at the indicated slot.
+    #[oai(status = 200)]
+    Ok(Json<FullStakeInfo>),
+
+    /// ## Not Found
+    ///
+    /// The queried stake address was not found at the requested slot number.
+    #[oai(status = 404)]
+    NotFound,
+
+    /// Response for unprocessable content.
+    #[oai(status = 422)]
+    UnprocessableContent(Json<ErrorMessage>),
+}
+
+/// All responses.
+pub type AllResponsesV2 = WithErrorResponses<ResponsesV2>;
+
+/// Get Cardano assets V2 endpoint.
+pub(crate) async fn endpoint(
+    address: Option<Cip19StakeAddress>,
+    network: Option<Network>,
+    slot: Option<SlotNo>,
+    auth: NoneOrRBAC,
+) -> AllResponsesV2 {
+    let token: Option<_> = auth.into();
+    if address.is_none() && token.is_none() {
+        return ResponsesV2::UnprocessableContent(Json(
+            "Either stake address parameter or token must be provided"
+                .to_string()
+                .into(),
+        ))
+        .into();
+    }
+
+    let stake_addresses = match stake_addresses(address, token).await {
+        Err(e) => return AllResponsesV2::handle_error(&e),
+        Ok(addresses) => addresses,
+    };
+    let infos: Vec<_> = match try_join_all(
+        stake_addresses
+            .into_iter()
+            .map(|a| build_full_stake_info_response(a, network.clone(), slot)),
+    )
+    .await
+    {
+        Err(e) => return AllResponsesV2::handle_error(&e),
+        Ok(r) => r.into_iter().flatten().collect(),
+    };
+
+    let info = infos.into_iter().reduce(|mut acc, mut info| {
+        acc.persistent.0.ada_amount = acc
+            .persistent
+            .0
+            .ada_amount
+            .saturating_add(info.persistent.0.ada_amount);
+        acc.persistent.0.slot_number =
+            std::cmp::max(acc.persistent.0.slot_number, info.persistent.0.slot_number);
+        acc.persistent
+            .0
+            .assets
+            .append(&mut info.persistent.0.assets);
+
+        acc.volatile.0.ada_amount = acc
+            .volatile
+            .0
+            .ada_amount
+            .saturating_add(info.volatile.0.ada_amount);
+        acc.volatile.0.slot_number =
+            std::cmp::max(acc.volatile.0.slot_number, info.volatile.0.slot_number);
+        acc.volatile.0.assets.append(&mut info.volatile.0.assets);
+
+        acc
+    });
+
+    match info {
+        Some(i) => ResponsesV2::Ok(Json(i)).into(),
+        None => ResponsesV2::NotFound.into(),
+    }
+}
+
+/// Returns a stake address from provided parameters.
+async fn stake_addresses(
+    address: Option<Cip19StakeAddress>,
+    token: Option<CatalystRBACTokenV1>,
+) -> anyhow::Result<HashSet<Cip19StakeAddress>> {
+    if let Some(address) = address {
+        return Ok([address].into());
+    }
+
+    if let Some(mut token) = token {
+        // This should never fail as a valid RBAC token can only be constructed after building a
+        // corresponding registration chain.
+        let chain = token
+            .reg_chain()
+            .await?
+            .context("Missing registration chain for token")?;
+        Ok(chain
+            .stake_addresses()
+            .into_iter()
+            .map(Into::into)
+            .collect())
+    } else {
+        Ok(HashSet::new())
+    }
+}

catalyst-gateway/bin/src/service/api/cardano/staking/mod.rs

@@ -13,6 +13,7 @@ use crate::service::common::{
 };
 
 mod assets_get;
+mod assets_get_v2;
 
 /// Cardano Staking API Endpoints
 pub(crate) struct Api;
@@ -54,4 +55,41 @@ impl Api {
         ))
         .await
     }
+
+    /// Get staked assets v2.
+    ///
+    /// This endpoint returns the total Cardano's staked assets to the corresponded
+    /// user's stake address or RBAC token.
+    #[oai(
+        path = "/v2/cardano/assets/",
+        method = "get",
+        operation_id = "stakedAssetsGetV2"
+    )]
+    async fn staked_ada_get_v2(
+        &self,
+        /// An optional stake address of the user.
+        /// Should be a valid Bech32 encoded address followed by the https://cips.cardano.org/cip/CIP-19/#stake-addresses.
+        Query(stake_address): Query<Option<Cip19StakeAddress>>,
+        /// Cardano network type.
+        /// If omitted network type is identified from the stake address.
+        /// If specified it must be correspondent to the network type encoded in the stake
+        /// address.
+        /// As `preprod` and `preview` network types in the stake address encoded as a
+        /// `testnet`, to specify `preprod` or `preview` network type use this
+        /// query parameter.
+        Query(network): Query<Option<Network>>,
+        /// A time point at which the assets should be calculated.
+        /// If omitted latest slot number is used.
+        asat: Query<Option<cardano::query::AsAt>>,
+        /// No Authorization required, but Token permitted.
+        auth: NoneOrRBAC,
+    ) -> assets_get_v2::AllResponsesV2 {
+        Box::pin(assets_get_v2::endpoint(
+            stake_address,
+            network,
+            SlotNo::into_option(asat.0),
+            auth,
+        ))
+        .await
+    }
 }

catalyst-gateway/bin/src/service/common/objects/cardano/stake_info.rs

@@ -86,7 +86,7 @@ impl Example for StakeInfo {
     to_header = false,
     example = true
 )]
-pub(crate) struct VolatileStakeInfo(StakeInfo);
+pub(crate) struct VolatileStakeInfo(pub(crate) StakeInfo);
 
 impl Example for VolatileStakeInfo {
     fn example() -> Self {
@@ -102,7 +102,7 @@ impl Example for VolatileStakeInfo {
     to_header = false,
     example = true
 )]
-pub(crate) struct PersistentStakeInfo(StakeInfo);
+pub(crate) struct PersistentStakeInfo(pub(crate) StakeInfo);
 
 impl Example for PersistentStakeInfo {
     fn example() -> Self {