Skip to main content

taskfast_agent/
faucet.rs

1// SPDX-License-Identifier: MIT
2//! Testnet faucet client. Wraps the public Tempo moderato faucet at
3//! `POST https://docs.tempo.xyz/api/faucet`, which returns `{"data": [{tx...}]}`
4//! with one entry per token dispensed (gas token + USDC).
5//!
6//! **Dev / staging only.** Production agents never hit a faucet — the
7//! owning human funds the wallet manually at <https://wallet.tempo.xyz>
8//! before the agent posts or settles. Callers must gate on network
9//! before calling in; this module does not self-gate because it has no
10//! network context of its own.
11//!
12//! Scope is narrow on purpose — we POST, parse enough to surface tx hashes
13//! to the caller, and return. Balance polling is the caller's concern
14//! (am-c74 is the beads ticket tracking the polling side).
15
16use serde::Deserialize;
17
18pub const TEMPO_TESTNET_FAUCET_URL: &str = "https://docs.tempo.xyz/api/faucet";
19
20#[derive(Debug, thiserror::Error)]
21pub enum FaucetError {
22    #[error("faucet http request failed: {0}")]
23    Http(#[from] reqwest::Error),
24    #[error("faucet returned status {status}: {body}")]
25    Status { status: u16, body: String },
26    #[error("faucet response missing data array")]
27    MalformedResponse,
28}
29
30#[derive(Debug, Deserialize)]
31struct FaucetResponse {
32    #[serde(default)]
33    data: Option<Vec<FaucetEntry>>,
34}
35
36#[derive(Debug, Deserialize)]
37struct FaucetEntry {
38    /// The faucet emits `{"hash": "0x..."}` per drop. Kept as a bare
39    /// `hash` here to match the server; aliased in case the schema ever
40    /// grows a `tx_hash` synonym without breaking us.
41    #[serde(default, alias = "tx_hash")]
42    hash: Option<String>,
43    #[serde(default)]
44    token: Option<String>,
45}
46
47/// Summary of one faucet dispense — what token was dropped and the
48/// broadcast tx hash, if the faucet surfaced one.
49#[derive(Debug, Clone)]
50pub struct FaucetDrop {
51    pub token: Option<String>,
52    pub tx_hash: Option<String>,
53}
54
55/// POST to the Tempo moderato faucet for `address` and return a summary
56/// per dispensed token. The faucet response shape varies (gas token +
57/// USDC come back as separate entries), so we keep the return loose.
58pub async fn request_testnet_funds(
59    http: &reqwest::Client,
60    address: &str,
61) -> Result<Vec<FaucetDrop>, FaucetError> {
62    let resp = http
63        .post(TEMPO_TESTNET_FAUCET_URL)
64        .json(&serde_json::json!({ "address": address }))
65        .send()
66        .await?;
67
68    let status = resp.status();
69    if !status.is_success() {
70        let body = resp.text().await.unwrap_or_default();
71        return Err(FaucetError::Status {
72            status: status.as_u16(),
73            body,
74        });
75    }
76
77    let parsed: FaucetResponse = resp.json().await?;
78    let entries = parsed.data.ok_or(FaucetError::MalformedResponse)?;
79    Ok(entries
80        .into_iter()
81        .map(|e| FaucetDrop {
82            token: e.token,
83            tx_hash: e.hash,
84        })
85        .collect())
86}