koios_sdk/api/

asset.rs

use crate::{
    error::Result,
    models::{
        asset::{AssetHistory, AssetInfo, AssetList, AssetTokenRegistry, PolicyAssetList},
        requests::{AssetListRequest, AssetListWithExtendedRequest},
        AddressTransaction, AssetNftAddress, AssetSummary, PolicyAssetAddresses, PolicyAssetInfo,
        PolicyAssetMint, UtxoInfo,
    },
    types::{AfterBlockHeight, AssetName, AssetNameNft, AssetPolicy, AssetPolicyNft},
    Client,
};
use urlencoding::encode;

impl Client {
    /// Get the list of all native assets (paginated)
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let assets = client.get_asset_list().await?;
    ///     println!("Asset list: {:?}", assets);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_list(&self) -> Result<Vec<AssetList>> {
        self.get("/asset_list").await
    }

    /// Get the list of assets under the given policy (including balances)
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::AssetPolicy;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let assets = client.get_policy_asset_list(&policy_id).await?;
    ///     println!("Policy assets: {:?}", assets);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_policy_asset_list(
        &self,
        policy_id: &AssetPolicy,
    ) -> Result<Vec<PolicyAssetList>> {
        self.get(&format!(
            "/policy_asset_list?_asset_policy={}",
            encode(policy_id.value())
        ))
        .await
    }

    /// Get a list of assets registered via token registry on github
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let registry = client.get_asset_token_registry().await?;
    ///     println!("Token registry: {:?}", registry);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_token_registry(&self) -> Result<Vec<AssetTokenRegistry>> {
        self.get("/asset_token_registry").await
    }

    /// Get the information of a list of assets including first minting & token registry metadata
    ///
    /// # Arguments
    ///
    /// * `asset_list` - List of asset pairs (policy_id, asset_name) to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let asset_list = vec![
    ///         vec![
    ///             "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209".to_string(),
    ///             "token1".to_string()
    ///         ]
    ///     ];
    ///     let asset_info = client.get_asset_info(&asset_list).await?;
    ///     println!("Asset info: {:?}", asset_info);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_info(&self, asset_list: &[Vec<String>]) -> Result<Vec<AssetInfo>> {
        let request = AssetListRequest::new(asset_list.to_vec());
        self.post("/asset_info", &request).await
    }

    /// Get the UTXO information of a list of assets
    ///
    /// # Arguments
    ///
    /// * `asset_list` - List of asset pairs (policy_id, asset_name) to query
    /// * `extended` - Optional flag to include extended information
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let asset_list = vec![
    ///         vec![
    ///             "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209".to_string(),
    ///             "token1".to_string()
    ///         ]
    ///     ];
    ///     let utxos = client.get_asset_utxos(&asset_list, Some(true)).await?;
    ///     println!("Asset UTXOs: {:?}", utxos);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_utxos(
        &self,
        asset_list: &[Vec<String>],
        extended: Option<bool>,
    ) -> Result<Vec<UtxoInfo>> {
        let request = AssetListWithExtendedRequest::new(asset_list.to_vec(), extended);
        self.post("/asset_utxos", &request).await
    }

    /// Get the mint/burn history of an asset
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    /// * `asset_name` - Asset name to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::{AssetPolicy, AssetName};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let asset_name = AssetName::new("token1");
    ///     let history = client.get_asset_history(&policy_id, &asset_name).await?;
    ///     println!("Asset history: {:?}", history);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_history(
        &self,
        policy_id: &AssetPolicy,
        asset_name: &AssetName,
    ) -> Result<Vec<AssetHistory>> {
        self.get(&format!(
            "/asset_history?_asset_policy={}&_asset_name={}",
            encode(policy_id.value()),
            encode(asset_name.value())
        ))
        .await
    }

    /// Get the address where specified NFT currently resides
    ///
    /// # Arguments
    ///
    /// * `policy_id` - NFT policy ID to query
    /// * `asset_name` - NFT asset name to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::{AssetPolicyNft, AssetNameNft};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicyNft::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let asset_name = AssetNameNft::new("nft1");
    ///     let address = client.get_asset_nft_address(&policy_id, &asset_name).await?;
    ///     println!("NFT address: {:?}", address);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_nft_address(
        &self,
        policy_id: &AssetPolicyNft,
        asset_name: &AssetNameNft,
    ) -> Result<Vec<AssetNftAddress>> {
        self.get(&format!(
            "/asset_nft_address?_asset_policy_nft={}&_asset_name_nft={}",
            encode(policy_id.value()),
            encode(asset_name.value())
        ))
        .await
    }

    /// Get the list of addresses with quantity for each asset on the given policy
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::AssetPolicy;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let addresses = client.get_policy_asset_addresses(&policy_id).await?;
    ///     println!("Policy asset addresses: {:?}", addresses);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_policy_asset_addresses(
        &self,
        policy_id: &AssetPolicy,
    ) -> Result<Vec<PolicyAssetAddresses>> {
        self.get(&format!(
            "/policy_asset_addresses?_asset_policy={}",
            encode(policy_id.value())
        ))
        .await
    }

    /// Get the information for all assets under the same policy
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::AssetPolicy;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let info = client.get_policy_asset_info(&policy_id).await?;
    ///     println!("Policy asset info: {:?}", info);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_policy_asset_info(
        &self,
        policy_id: &AssetPolicy,
    ) -> Result<Vec<PolicyAssetInfo>> {
        self.get(&format!(
            "/policy_asset_info?_asset_policy={}",
            encode(policy_id.value())
        ))
        .await
    }

    /// Get a list of mint or burn count details for all assets minted under a policy
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::AssetPolicy;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let mints = client.get_policy_asset_mints(&policy_id).await?;
    ///     println!("Policy asset mints: {:?}", mints);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_policy_asset_mints(
        &self,
        policy_id: &AssetPolicy,
    ) -> Result<Vec<PolicyAssetMint>> {
        self.get(&format!(
            "/policy_asset_mints?_asset_policy={}",
            encode(policy_id.value())
        ))
        .await
    }

    /// Get the summary of an asset
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    /// * `asset_name` - Asset name to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::{AssetPolicy, AssetName};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let asset_name = AssetName::new("token1");
    ///     let summary = client.get_asset_summary(&policy_id, &asset_name).await?;
    ///     println!("Asset summary: {:?}", summary);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_summary(
        &self,
        policy_id: &AssetPolicy,
        asset_name: &AssetName,
    ) -> Result<Vec<AssetSummary>> {
        self.get(&format!(
            "/asset_summary?_asset_policy={}&_asset_name={}",
            encode(policy_id.value()),
            encode(asset_name.value())
        ))
        .await
    }

    /// Get the list of current or all asset transaction hashes
    ///
    /// # Arguments
    ///
    /// * `policy_id` - Policy ID to query
    /// * `asset_name` - Asset name to query
    /// * `after_block_height` - Optional block height to filter from
    /// * `history` - Optional flag to include historical transactions
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::{AssetPolicy, AssetName, AfterBlockHeight};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let policy_id = AssetPolicy::new(
    ///         "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
    ///     );
    ///     let asset_name = AssetName::new("token1");
    ///     let txs = client.get_asset_transactions(
    ///         &policy_id,
    ///         &asset_name,
    ///         Some(AfterBlockHeight::new(42000000)),
    ///         Some(true)
    ///     ).await?;
    ///     println!("Asset transactions: {:?}", txs);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_asset_transactions(
        &self,
        policy_id: &AssetPolicy,
        asset_name: &AssetName,
        after_block_height: Option<AfterBlockHeight>,
        history: Option<bool>,
    ) -> Result<Vec<AddressTransaction>> {
        let mut endpoint = format!(
            "/asset_txs?_asset_policy={}&_asset_name={}",
            encode(policy_id.value()),
            encode(asset_name.value())
        );

        if let Some(height) = after_block_height {
            endpoint.push_str(&format!("&_after_block_height={}", height.value()));
        }

        if let Some(include_history) = history {
            endpoint.push_str(&format!("&_history={}", include_history));
        }

        self.get(&endpoint).await
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use wiremock::matchers::{method, path, query_param};
    use wiremock::{Mock, MockServer, ResponseTemplate};

    #[tokio::test]
    async fn test_get_asset_list() {
        let mock_server = MockServer::start().await;
        let client = Client::builder()
            .base_url(mock_server.uri())
            .build()
            .unwrap();

        let mock_response = json!([{
            "policy_id": "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209",
            "asset_name": "token1",
            "asset_name_ascii": "token1",
            "fingerprint": "asset1sl88uq7vjx4vf7qq98v5vjml8ufztrs9tq9l4m"
        }]);

        Mock::given(method("GET"))
            .and(path("/asset_list"))
            .respond_with(ResponseTemplate::new(200).set_body_json(&mock_response))
            .mount(&mock_server)
            .await;

        let response = client.get_asset_list().await.unwrap();
        assert_eq!(response.len(), 1);
        assert_eq!(
            response[0].policy_id,
            "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209"
        );
    }

    #[tokio::test]
    async fn test_get_policy_asset_info() {
        let mock_server = MockServer::start().await;
        let client = Client::builder()
            .base_url(mock_server.uri())
            .build()
            .unwrap();

        let policy_id = "1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209";
        let mock_response = json!([{
            "asset_name": "token1",
            "asset_name_ascii": "token1",
            "fingerprint": "asset1sl88uq7vjx4vf7qq98v5vjml8ufztrs9tq9l4m",
            "minting_tx_hash": "6ed09ba58a56c6e946668038ba4d3cef8eb97a20cbf76c5970e1402e8a8d6541",
            "total_supply": "1000",
            "mint_cnt": 1,
            "burn_cnt": 0,
            "creation_time": 1628222400,
            "minting_tx_metadata": null,
            "token_registry_metadata": null
        }]);

        Mock::given(method("GET"))
            .and(path("/policy_asset_info"))
            .and(query_param("_asset_policy", policy_id))
            .respond_with(ResponseTemplate::new(200).set_body_json(&mock_response))
            .mount(&mock_server)
            .await;

        let response = client
            .get_policy_asset_info(&AssetPolicy::new(policy_id))
            .await
            .unwrap();
        assert_eq!(response.len(), 1);
        assert_eq!(response[0].asset_name, "token1");
    }

    // Add more tests for other endpoints...
}