add faucet page

.env.example

@@ -29,3 +29,9 @@ RPC_BATCH_SIZE=20
 # API_PORT=3000
 # API_DB_MAX_CONNECTIONS=20
 # SSE_REPLAY_BUFFER_BLOCKS=4096  # replay tail used only for active connected clients
+
+# Optional faucet feature
+# FAUCET_ENABLED=false
+# FAUCET_PRIVATE_KEY=0x...
+# FAUCET_AMOUNT=0.01
+# FAUCET_COOLDOWN_MINUTES=30

backend/Cargo.toml

@@ -17,6 +17,7 @@ tokio = { version = "1.43", features = ["full"] }
 
 # Web framework
 axum = { version = "0.8", features = ["macros"] }
+tower = "0.5"
 tower-http = { version = "0.6", features = ["cors", "trace", "timeout"] }
 
 # Database

backend/crates/atlas-common/src/error.rs

@@ -37,6 +37,12 @@ pub enum AtlasError {
 
     #[error("Bytecode mismatch: {0}")]
     BytecodeMismatch(String),
+
+    #[error("Too many requests: {message} (retry after {retry_after_seconds}s)")]
+    TooManyRequests {
+        message: String,
+        retry_after_seconds: u64,
+    },
 }
 
 impl AtlasError {
@@ -50,6 +56,7 @@ impl AtlasError {
             AtlasError::Config(_) => 500,
             AtlasError::Verification(_) | AtlasError::BytecodeMismatch(_) => 400,
             AtlasError::Compilation(_) => 422,
+            AtlasError::TooManyRequests { .. } => 429,
         }
     }
 }

backend/crates/atlas-server/Cargo.toml

@@ -11,6 +11,7 @@ path = "src/main.rs"
 atlas-common = { workspace = true }
 tokio = { workspace = true }
 axum = { workspace = true }
+tower = { workspace = true }
 tower-http = { workspace = true }
 sqlx = { workspace = true }
 alloy = { workspace = true }

backend/crates/atlas-server/src/api/error.rs

@@ -1,5 +1,5 @@
 use axum::{
-    http::StatusCode,
+    http::{header::RETRY_AFTER, HeaderValue, StatusCode},
     response::{IntoResponse, Response},
     Json,
 };
@@ -63,6 +63,7 @@ impl IntoResponse for ApiError {
             AtlasError::Verification(msg) => msg.clone(),
             AtlasError::BytecodeMismatch(msg) => msg.clone(),
             AtlasError::Compilation(msg) => msg.clone(),
+            AtlasError::TooManyRequests { message, .. } => message.clone(),
             // Opaque: log full detail, return generic message
             AtlasError::Database(inner) => {
                 tracing::error!(error = %inner, "Database error");
@@ -86,9 +87,52 @@ impl IntoResponse for ApiError {
             }
         };
 
-        let body = Json(json!({ "error": client_message }));
-        (status, body).into_response()
+        let body = match &self.0 {
+            AtlasError::TooManyRequests {
+                retry_after_seconds,
+                ..
+            } => Json(json!({
+                "error": client_message,
+                "retry_after_seconds": retry_after_seconds,
+            })),
+            _ => Json(json!({ "error": client_message })),
+        };
+
+        let mut response = (status, body).into_response();
+        if let AtlasError::TooManyRequests {
+            retry_after_seconds,
+            ..
+        } = &self.0
+        {
+            if let Ok(header_value) = HeaderValue::from_str(&retry_after_seconds.to_string()) {
+                response.headers_mut().insert(RETRY_AFTER, header_value);
+            }
+        }
+        response
     }
 }
 
 pub type ApiResult<T> = Result<T, ApiError>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::body::to_bytes;
+
+    #[tokio::test]
+    async fn too_many_requests_sets_retry_after_header_and_body() {
+        let response = ApiError(AtlasError::TooManyRequests {
+            message: "Faucet cooldown active".to_string(),
+            retry_after_seconds: 42,
+        })
+        .into_response();
+
+        assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);
+        assert_eq!(response.headers().get(RETRY_AFTER).unwrap(), "42");
+
+        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+        assert_eq!(value["error"], "Faucet cooldown active");
+        assert_eq!(value["retry_after_seconds"], 42);
+    }
+}