sui-graphql-client: support faucet v2 api (#108)

Author: stefan-mysten

.github/workflows/ci.yml

@@ -97,7 +97,7 @@ jobs:
       - name: Get the Sui testnet binary and start a local network
         shell: bash
         env:
-          SUI_BINARY_VERSION: "1.44.2" # used for downloading a specific Sui binary versions that matches the GraphQL schema for local network tests
+          SUI_BINARY_VERSION: "1.48.0" # used for downloading a specific Sui binary versions that matches the GraphQL schema for local network tests
           SUI_NETWORK_RELEASE: "testnet" # which release to use
         run: |
           ASSET_NAME="sui-$SUI_NETWORK_RELEASE-v$SUI_BINARY_VERSION-ubuntu-x86_64.tgz"

crates/sui-graphql-client/Cargo.toml

@@ -21,6 +21,7 @@ serde = { version = "1.0.144" }
 serde_json = {version = "1.0.95"}
 sui-types = { package = "sui-sdk-types", version = "0.0.4", path = "../sui-sdk-types", features = ["serde"] }
 tracing = "0.1.37"
+thiserror = "2.0.12"
 tokio = "1.36.0"
 url = "2.5.3"
 

crates/sui-graphql-client/README.md

@@ -37,7 +37,7 @@ async fn main() -> Result<()> {
 ```
 
 ## Requesting gas from the faucet
-The client provides an API to request gas from the faucet. The `request_and_wait` function sends a request to the faucet and waits until the transaction is confirmed. The function returns the transaction details if the request is successful.
+The client provides an API to request gas from the faucet. The `request` function sends a request to the faucet and waits until the transaction is confirmed. The function returns the transaction details if the request is successful.
 
 ### Example for standard devnet/testnet/local networks.
 ```rust, no_run
@@ -52,22 +52,21 @@ async fn main() -> Result<()> {
     let address = Address::from_str("SUI_ADDRESS_HERE")?;
     // Request gas from the faucet and wait until a coin is received
     // As the client is set to devnet, faucet will use the devnet faucet.
-    let faucet = FaucetClient::devnet().request_and_wait(address).await?;
-    if let Some(resp) = faucet {
-        let coins = resp.sent;
-        for coin in coins {
+    let faucet = FaucetClient::devnet().request(address).await;
+    if let Ok(resp) = faucet {
+        for coin in resp.coins_sent {
             println!("coin: {:?}", coin);
         }
     }
 
     // Request gas from the testnet faucet by explicitly setting the faucet to testnet
-    let faucet_testnet = FaucetClient::testnet().request_and_wait(address).await?;
+    let faucet_testnet = FaucetClient::testnet().request(address).await?;
     Ok(())
 }
 ```
 
 ### Example for custom faucet service.
-Note that this `FaucetClient` is explicitly designed to work with two endpoints: `v1/gas`, and `v1/status`. When passing in the custom faucet URL, skip the final endpoint and only pass in the top-level url (e.g., `https://faucet.devnet.sui.io`).
+Note that this `FaucetClient` is explicitly designed to work with this endpoint: `v2/gas`, When passing in the custom faucet URL, skip the final endpoint and only pass in the top-level url (e.g., `https://faucet.devnet.sui.io`).
 ```rust, no_run
 use sui_graphql_client::faucet::FaucetClient;
 use sui_types::Address;
@@ -80,10 +79,9 @@ async fn main() -> Result<()> {
     let address = Address::from_str("SUI_ADDRESS_HERE")?;
     // Request gas from the faucet and wait until a coin is received
     // As the client is set to devnet, faucet will use the devnet faucet.
-    let faucet = FaucetClient::new("https://myfaucet_testnet.com").request_and_wait(address).await?;
-    if let Some(resp) = faucet {
-        let coins = resp.sent;
-        for coin in coins {
+    let faucet = FaucetClient::new("https://myfaucet_testnet.com").request(address).await;
+    if let Ok(resp) = faucet {
+        for coin in resp.coins_sent {
             println!("coin: {:?}", coin);
         }
     }

crates/sui-graphql-client/src/faucet.rs

@@ -2,67 +2,40 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use sui_types::Address;
-use sui_types::ObjectId;
 use sui_types::TransactionDigest;
 
-use anyhow::anyhow;
 use anyhow::bail;
 use reqwest::StatusCode;
 use reqwest::Url;
 use serde::Deserialize;
 use serde::Serialize;
 use serde_json::json;
-use std::time::Duration;
-use tracing::error;
+use sui_types::ObjectId;
+use thiserror::Error;
+use tracing::error as tracing_error;
 use tracing::info;
 
 pub const FAUCET_DEVNET_HOST: &str = "https://faucet.devnet.sui.io";
 pub const FAUCET_TESTNET_HOST: &str = "https://faucet.testnet.sui.io";
 pub const FAUCET_LOCAL_HOST: &str = "http://localhost:9123";
 
-const FAUCET_REQUEST_TIMEOUT: Duration = Duration::from_secs(120);
-const FAUCET_POLL_INTERVAL: Duration = Duration::from_secs(2);
+pub const FAUCET_REQUEST_PATH: &str = "v2/gas";
 
 pub struct FaucetClient {
     faucet_url: Url,
     inner: reqwest::Client,
 }
 
-#[derive(serde::Deserialize)]
-struct FaucetResponse {
-    task: Option<String>,
-    error: Option<String>,
+#[derive(Serialize, Deserialize, Debug)]
+pub enum RequestStatus {
+    Success,
+    Failure(FaucetError),
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
-#[serde(rename_all = "camelCase")]
-struct BatchStatusFaucetResponse {
-    pub status: Option<BatchSendStatus>,
-    pub error: Option<String>,
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-#[serde(rename_all = "UPPERCASE")]
-pub enum BatchSendStatusType {
-    Inprogress,
-    Succeeded,
-    Discarded,
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone)]
-pub struct BatchSendStatus {
-    pub status: BatchSendStatusType,
-    pub transferred_gas_objects: Option<FaucetReceipt>,
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone)]
-pub struct FaucetReceipt {
-    pub sent: Vec<CoinInfo>,
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone)]
-struct BatchFaucetReceipt {
-    pub task: String,
+#[derive(Serialize, Deserialize, Debug)]
+pub struct FaucetResponse {
+    pub status: RequestStatus,
+    pub coins_sent: Option<Vec<CoinInfo>>,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone)]
@@ -73,13 +46,25 @@ pub struct CoinInfo {
     pub transfer_tx_digest: TransactionDigest,
 }
 
+#[derive(Serialize, Deserialize, Error, Debug, PartialEq, Eq)]
+pub enum FaucetError {
+    #[error("Missing X-Turnstile-Token header. For testnet tokens, please use the Web UI: https://faucet.sui.io")]
+    MissingTurnstileTokenHeader,
+
+    #[error("Request limit exceeded. {0}")]
+    TooManyRequests(String),
+
+    #[error("Internal error: {0}")]
+    Internal(String),
+
+    #[error("Invalid user agent: {0}")]
+    InvalidUserAgent(String),
+}
+
 impl FaucetClient {
     /// Construct a new `FaucetClient` with the given faucet service URL. This [`FaucetClient`]
-    /// expects that the service provides two endpoints: /v1/gas and /v1/status. As such, do not
+    /// expects that the service provides this endpoint: /v2/gas. As such, do not
     /// provide the request endpoint, just the top level service endpoint.
-    ///
-    /// - /v1/gas is used to request gas
-    /// - /v1/status/taks-uuid is used to check the status of the request
     pub fn new(faucet_url: &str) -> Self {
         let inner = reqwest::Client::new();
         let faucet_url = Url::parse(faucet_url).expect("Invalid faucet URL");
@@ -110,21 +95,17 @@ impl FaucetClient {
         }
     }
 
-    /// Request gas from the faucet. Note that this will return the UUID of the request and not
-    /// wait until the token is received. Use `request_and_wait` to wait for the token.
-    pub async fn request(&self, address: Address) -> Result<Option<String>, anyhow::Error> {
-        self.request_impl(address).await
-    }
-
-    /// Internal implementation of a faucet request. It returns the task Uuid as a String.
-    async fn request_impl(&self, address: Address) -> Result<Option<String>, anyhow::Error> {
+    /// Make a faucet request. It returns a [`FaucetResponse`] type, which upon success contains
+    /// the information about the coin sent.
+    pub async fn request(&self, address: Address) -> Result<FaucetResponse, anyhow::Error> {
         let address = address.to_string();
         let json_body = json![{
             "FixedAmountRequest": {
                 "recipient": &address
             }
         }];
-        let url = format!("{}v1/gas", self.faucet_url);
+
+        let url = format!("{}{}", self.faucet_url, FAUCET_REQUEST_PATH);
         info!(
             "Requesting gas from faucet for address {} : {}",
             address, url
@@ -137,112 +118,32 @@ impl FaucetClient {
             .send()
             .await?;
         match resp.status() {
-            StatusCode::ACCEPTED | StatusCode::CREATED => {
+            StatusCode::ACCEPTED | StatusCode::CREATED | StatusCode::OK => {
                 let faucet_resp: FaucetResponse = resp.json().await?;
 
-                if let Some(err) = faucet_resp.error {
-                    error!("Faucet request was unsuccessful: {err}");
-                    bail!("Faucet request was unsuccessful: {err}")
-                } else {
-                    info!("Request succesful: {:?}", faucet_resp.task);
-                    Ok(faucet_resp.task)
+                match faucet_resp.status {
+                    RequestStatus::Success => {
+                        info!("Faucet request was successful: {:?}", faucet_resp);
+                        Ok(faucet_resp)
+                    }
+                    RequestStatus::Failure(err) => {
+                        tracing_error!("Faucet request was unsuccessful: {:?}", err);
+                        bail!("Faucet request was unsuccessful: {:?}", err)
+                    }
                 }
             }
             StatusCode::TOO_MANY_REQUESTS => {
-                error!("Faucet service received too many requests from this IP address.");
+                tracing_error!("Faucet service received too many requests from this IP address.");
                 bail!("Faucet service received too many requests from this IP address. Please try again after 60 minutes.");
             }
             StatusCode::SERVICE_UNAVAILABLE => {
-                error!("Faucet service is currently overloaded or unavailable.");
+                tracing_error!("Faucet service is currently overloaded or unavailable.");
                 bail!("Faucet service is currently overloaded or unavailable. Please try again later.");
             }
             status_code => {
-                error!("Faucet request was unsuccessful: {status_code}");
+                tracing_error!("Faucet request was unsuccessful: {status_code}");
                 bail!("Faucet request was unsuccessful: {status_code}");
             }
         }
     }
-
-    /// Request gas from the faucet and wait until the request is completed and token is
-    /// transferred. Returns `FaucetReceipt` if the request is successful, which contains the list
-    /// of tokens transferred, and the transaction digest.
-    ///
-    /// Note that the faucet is heavily rate-limited, so calling repeatedly the faucet would likely
-    /// result in a 429 code or 502 code.
-    pub async fn request_and_wait(
-        &self,
-        address: Address,
-    ) -> Result<Option<FaucetReceipt>, anyhow::Error> {
-        let request_id = self.request(address).await?;
-        if let Some(request_id) = request_id {
-            let poll_response = tokio::time::timeout(FAUCET_REQUEST_TIMEOUT, async {
-                let mut interval = tokio::time::interval(FAUCET_POLL_INTERVAL);
-                loop {
-                    interval.tick().await;
-                    info!("Polling faucet request status: {request_id}");
-                    let req = self.request_status(request_id.clone()).await;
-
-                    if let Ok(Some(poll_response)) = req {
-                        match poll_response.status {
-                            BatchSendStatusType::Succeeded => {
-                                info!("Faucet request {request_id} succeeded");
-                                break Ok(poll_response);
-                            }
-                            BatchSendStatusType::Discarded => {
-                                break Ok(BatchSendStatus {
-                                    status: BatchSendStatusType::Discarded,
-                                    transferred_gas_objects: None,
-                                });
-                            }
-                            BatchSendStatusType::Inprogress => {
-                                continue;
-                            }
-                        }
-                    } else if let Some(err) = req.err() {
-                        error!("Faucet request {request_id} failed. Error: {:?}", err);
-                        break Err(anyhow!(
-                            "Faucet request {request_id} failed. Error: {:?}",
-                            err
-                        ));
-                    }
-                }
-            })
-            .await
-            .map_err(|_| {
-                error!(
-                    "Faucet request {request_id} timed out. Timeout set to {} seconds",
-                    FAUCET_REQUEST_TIMEOUT.as_secs()
-                );
-                anyhow!("Faucet request timed out")
-            })??;
-            Ok(poll_response.transferred_gas_objects)
-        } else {
-            Ok(None)
-        }
-    }
-
-    /// Check the faucet request status.
-    ///
-    /// Possible statuses are defined in: [`BatchSendStatusType`]
-    pub async fn request_status(
-        &self,
-        id: String,
-    ) -> Result<Option<BatchSendStatus>, anyhow::Error> {
-        let status_url = format!("{}v1/status/{}", self.faucet_url, id);
-        info!("Checking status of faucet request: {status_url}");
-        let response = self.inner.get(&status_url).send().await?;
-        if response.status() == StatusCode::TOO_MANY_REQUESTS {
-            bail!("Cannot fetch request status due to too many requests from this IP address.");
-        } else if response.status() == StatusCode::BAD_GATEWAY {
-            bail!("Cannot fetch request status due to a bad gateway.")
-        }
-        let json = response
-            .json::<BatchStatusFaucetResponse>()
-            .await
-            .map_err(|e| {
-                error!("Failed to parse faucet response: {:?}", e);
-                anyhow!("Failed to parse faucet response: {:?}", e)
-            })?;
-        Ok(json.status)
-    }
 }

crates/sui-graphql-client/src/lib.rs

@@ -588,7 +588,7 @@ impl Client {
         owner: Address,
         coin_type: Option<&str>,
         pagination_filter: PaginationFilter,
-    ) -> Result<Page<Coin>> {
+    ) -> Result<Page<Coin<'static>>> {
         let response = self
             .objects(
                 Some(ObjectFilter {
@@ -620,7 +620,7 @@ impl Client {
         address: Address,
         coin_type: Option<&'static str>,
         streaming_direction: Direction,
-    ) -> impl Stream<Item = Result<Coin>> {
+    ) -> impl Stream<Item = Result<Coin<'static>>> + use<'_> {
         stream_paginated_query(
             move |filter| self.coins(address, coin_type, filter),
             streaming_direction,
@@ -2176,7 +2176,7 @@ mod tests {
         };
         let key = Ed25519PublicKey::generate(rand::thread_rng());
         let address = key.derive_address();
-        faucet.request_and_wait(address).await.unwrap();
+        faucet.request(address).await.unwrap();
 
         const MAX_RETRIES: u32 = 10;
         const RETRY_DELAY: time::Duration = time::Duration::from_secs(1);

crates/sui-sdk-types/src/lib.rs

@@ -12,14 +12,14 @@
 //! compiled code. By default, no features are enabled which allows one to enable a subset
 //! specifically for their use case. Below is a list of the available feature flags.
 //!
-//! - `serde`: Enables support for serializing and deserializing types to/from BCS utilizing
-//!            [serde] library.
+//! - `serde`: Enables support for serializing and deserializing types to/from BCS utilizing [serde]
+//!   library.
 //! - `rand`: Enables support for generating random instances of a number of types via the [rand]
-//!           library.
+//!   library.
 //! - `hash`: Enables support for hashing, which is required for deriving addresses and calculating
-//!           digests for various types.
+//!   digests for various types.
 //! - `proptest`: Enables support for the [proptest] library by providing implementations of
-//!               [proptest::arbitrary::Arbitrary] for many types.
+//!   [proptest::arbitrary::Arbitrary] for many types.
 //!
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
 //! [serde]: https://docs.rs/serde