linera_faucet_client/

lib.rs

// Copyright (c) Zefchain Labs, Inc.
// SPDX-License-Identifier: Apache-2.0

//! The client component of the Linera faucet.

#![deny(missing_docs)]

// TODO(#3362): generate this code

use std::collections::BTreeMap;

use linera_base::{
    crypto::{CryptoHash, ValidatorPublicKey},
    data_types::{Amount, ArithmeticError, ChainDescription, Timestamp},
    identifiers::{AccountOwner, ChainId},
};
use linera_client::config::GenesisConfig;
use linera_execution::{committee::ValidatorState, Committee, ResourceControlPolicy};
use linera_version::VersionInfo;

/// The kinds of error that the faucet client can return.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// A response from the faucet could not be parsed as JSON.
    #[error("JSON parsing error: {0:?}")]
    Json(#[from] serde_json::Error),
    /// The faucet returned one or more GraphQL errors.
    #[error("GraphQL error: {0:?}")]
    GraphQl(Vec<serde_json::Value>),
    /// An HTTP request to the faucet failed.
    #[error("{}", describe_http_failure(.0))]
    Http(#[from] reqwest::Error),
    /// An arithmetic operation overflowed.
    #[error(transparent)]
    ArithmeticError(#[from] ArithmeticError),
    /// A GraphQL query could not be sent to the faucet.
    #[error("failed to execute query {query:?}: {}", describe_http_failure(.source))]
    Query {
        /// The query that could not be sent.
        query: String,
        /// The underlying HTTP failure.
        #[source]
        source: reqwest::Error,
    },
}

/// Describes a `reqwest` failure without reproducing its source.
///
/// On wasm that source is built with `format!("{js_val:?}")`, which embeds the JavaScript
/// stack trace of the failed `fetch`. The trace differs per browser and per bundle hash, so
/// carrying it splits one underlying failure across many distinct-looking reports. It buys
/// little in exchange: browsers deliberately report CORS rejections, offline and DNS
/// failures as the same opaque `TypeError`, so the text that varies is mostly the browser's
/// own phrasing. The error is still available through `source()` for anything that wants it.
fn describe_http_failure(error: &reqwest::Error) -> String {
    let where_ = match error.url() {
        Some(url) => format!(" at {url}"),
        None => String::new(),
    };
    if let Some(status) = error.status() {
        format!("the faucet{where_} returned {status}")
    } else if error.is_timeout() {
        format!("the request to the faucet{where_} timed out")
    } else if error.is_decode() {
        format!("could not decode the faucet's response{where_}")
    } else if error.is_body() {
        format!("the request body sent to the faucet{where_} was rejected")
    } else {
        format!("could not reach the faucet{where_}")
    }
}

/// The result of a successful claim mutation.
#[derive(Clone, Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ClaimOutcome {
    /// The ID of the chain.
    pub chain_id: ChainId,
    /// The hash of the certificate containing the operation.
    pub certificate_hash: CryptoHash,
    /// The amount of tokens transferred.
    pub amount: Amount,
}

/// Information about the initial chain claim.
#[derive(Clone, Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct InitialClaim {
    /// The chain ID that was created.
    pub chain_id: ChainId,
    /// The block timestamp when the chain was created.
    pub timestamp: Timestamp,
}

/// Returns the `destination` argument to append to a claim mutation, which is omitted for the
/// chain account so that queries stay compatible with faucets that predate the argument.
fn destination_argument(destination: &AccountOwner) -> String {
    if destination.is_chain() {
        String::new()
    } else {
        format!(", destination: \"{destination}\"")
    }
}

/// A faucet instance that can be queried.
#[derive(Debug, Clone)]
pub struct Faucet {
    url: String,
}

impl Faucet {
    /// Creates a faucet client querying the faucet service at the given URL.
    pub fn new(url: String) -> Self {
        Self { url }
    }

    /// Returns the URL of the faucet service.
    pub fn url(&self) -> &str {
        &self.url
    }

    async fn query<Response: serde::de::DeserializeOwned>(
        &self,
        query: impl AsRef<str>,
    ) -> Result<Response, Error> {
        let query = query.as_ref();

        #[derive(serde::Deserialize)]
        struct GraphQlResponse<T> {
            data: Option<T>,
            errors: Option<Vec<serde_json::Value>>,
        }

        let builder = reqwest::ClientBuilder::new();

        #[cfg(not(target_arch = "wasm32"))]
        let builder = builder.timeout(linera_base::time::Duration::from_secs(30));

        let response: GraphQlResponse<Response> = builder
            .build()
            .unwrap()
            .post(&self.url)
            .json(&serde_json::json!({
                "query": query,
            }))
            .send()
            .await
            .map_err(|source| Error::Query {
                query: query.to_string(),
                source,
            })?
            .error_for_status()?
            .json()
            .await?;

        if let Some(errors) = response.errors {
            // Extract just the error messages, ignore locations and path
            let messages = errors
                .iter()
                .filter_map(|error| {
                    error
                        .get("message")
                        .and_then(|msg| msg.as_str())
                        .map(|s| s.to_string())
                })
                .collect::<Vec<_>>();

            if messages.is_empty() {
                Err(Error::GraphQl(errors))
            } else {
                Err(Error::GraphQl(vec![serde_json::Value::String(
                    messages.join("; "),
                )]))
            }
        } else {
            Ok(response
                .data
                .expect("no errors present but no data returned"))
        }
    }

    /// Fetches the network's genesis configuration from the faucet.
    pub async fn genesis_config(&self) -> Result<GenesisConfig, Error> {
        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            genesis_config: GenesisConfig,
        }

        Ok(self
            .query::<Response>("query { genesisConfig }")
            .await?
            .genesis_config)
    }

    /// Fetches the faucet's version information.
    pub async fn version_info(&self) -> Result<VersionInfo, Error> {
        #[derive(serde::Deserialize)]
        struct Response {
            version: VersionInfo,
        }

        Ok(self.query::<Response>("query { version }").await?.version)
    }

    /// Claims a new chain for the given owner, returning its chain description. The tokens are
    /// credited to the new chain's own account.
    pub async fn claim(&self, owner: &AccountOwner) -> Result<ChainDescription, Error> {
        self.claim_to(owner, &AccountOwner::CHAIN).await
    }

    /// Claims a new chain for the given owner, crediting the tokens to `destination` on it.
    ///
    /// A chain funded only in an owner's account can pay fees just for the blocks that owner
    /// authenticates.
    pub async fn claim_to(
        &self,
        owner: &AccountOwner,
        destination: &AccountOwner,
    ) -> Result<ChainDescription, Error> {
        #[derive(serde::Deserialize)]
        struct Response {
            claim: ChainDescription,
        }
        Ok(self
            .query::<Response>(format!(
                "mutation {{ claim(owner: \"{owner}\"{}) }}",
                destination_argument(destination)
            ))
            .await?
            .claim)
    }

    /// Claims daily tokens for the given owner, credited to their chain's own account.
    /// The user must have already claimed a chain. Each user can claim once per
    /// 24-hour period.
    pub async fn daily_claim(&self, owner: &AccountOwner) -> Result<ClaimOutcome, Error> {
        self.daily_claim_to(owner, &AccountOwner::CHAIN).await
    }

    /// Claims daily tokens for the given owner, crediting them to `destination` on their chain.
    pub async fn daily_claim_to(
        &self,
        owner: &AccountOwner,
        destination: &AccountOwner,
    ) -> Result<ClaimOutcome, Error> {
        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            daily_claim: ClaimOutcome,
        }

        Ok(self
            .query::<Response>(format!(
                "mutation {{ dailyClaim(owner: \"{owner}\"{}) }}",
                destination_argument(destination)
            ))
            .await?
            .daily_claim)
    }

    /// Returns the initial claim for the given owner, if any.
    pub async fn initial_claim(&self, owner: &AccountOwner) -> Result<Option<InitialClaim>, Error> {
        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            initial_claim: Option<InitialClaim>,
        }

        Ok(self
            .query::<Response>(format!(
                "query {{ initialClaim(owner: \"{owner}\") {{ chainId timestamp }} }}"
            ))
            .await?
            .initial_claim)
    }

    /// Returns the earliest time at which the owner can make a daily claim.
    /// If the returned timestamp is in the past (or now), the user can claim immediately.
    /// Returns `None` if the user has not yet completed the initial claim.
    pub async fn next_daily_claim(&self, owner: &AccountOwner) -> Result<Option<Timestamp>, Error> {
        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            next_daily_claim: Option<Timestamp>,
        }

        Ok(self
            .query::<Response>(format!("query {{ nextDailyClaim(owner: \"{owner}\") }}"))
            .await?
            .next_daily_claim)
    }

    /// Returns the current validators' public keys and network addresses.
    pub async fn current_validators(&self) -> Result<Vec<(ValidatorPublicKey, String)>, Error> {
        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Validator {
            public_key: ValidatorPublicKey,
            network_address: String,
        }

        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            current_validators: Vec<Validator>,
        }

        Ok(self
            .query::<Response>("query { currentValidators { publicKey networkAddress } }")
            .await?
            .current_validators
            .into_iter()
            .map(|validator| (validator.public_key, validator.network_address))
            .collect())
    }

    /// Returns the current committee: its validators and resource-control policy.
    pub async fn current_committee(&self) -> Result<Committee, Error> {
        #[derive(serde::Deserialize)]
        struct CommitteeResponse {
            validators: BTreeMap<ValidatorPublicKey, ValidatorState>,
            policy: ResourceControlPolicy,
        }

        #[derive(serde::Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Response {
            current_committee: CommitteeResponse,
        }

        let response = self
            .query::<Response>(
                "query { currentCommittee { \
                    validators \
                    policy \
                } }",
            )
            .await?;

        let committee_response = response.current_committee;

        Ok(Committee::new(
            committee_response.validators,
            committee_response.policy,
        )?)
    }
}