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}