feat: white-label branding support

.env.example

@@ -15,3 +15,14 @@ FETCH_WORKERS=10
 
 # Number of blocks to fetch per RPC batch request (reduces HTTP round-trips)
 RPC_BATCH_SIZE=20
+
+# Branding / White-label (all optional)
+# If not set, the default ev-node branding is used.
+CHAIN_NAME=MyChain
+# URL or path to logo (e.g., /branding/logo.png). Default: bundled ev-node logo
+CHAIN_LOGO_URL=
+ACCENT_COLOR="#dc2626"                # Primary accent color (links, buttons, active states)
+BACKGROUND_COLOR_DARK="#050505"       # Dark mode base background
+BACKGROUND_COLOR_LIGHT="#f4ede6"      # Light mode base background
+SUCCESS_COLOR="#22c55e"               # Success indicator color
+ERROR_COLOR="#dc2626"                 # Error indicator color

.gitignore

@@ -28,3 +28,7 @@ logs/
 frontend/node_modules/
 frontend/dist/
 frontend/.env.local
+
+# Branding assets (user-provided, not shared)
+branding/*
+!branding/.gitkeep

README.md

@@ -72,10 +72,13 @@ Copy `.env.example` to `.env` and set `RPC_URL`. Common options:
 | `IPFS_GATEWAY` | Gateway for NFT metadata | `https://ipfs.io/ipfs/` |
 | `REINDEX` | Wipe and reindex from start | `false` |
 
+See [White Labeling](docs/WHITE_LABELING.md) for branding customization (chain name, logo, colors).
+
 ## Documentation
 
 - [API Reference](docs/API.md)
 - [Architecture](docs/ARCHITECTURE.md)
+- [White Labeling](docs/WHITE_LABELING.md)
 - [Product Requirements](docs/PRD.md)
 
 ## License

backend/crates/atlas-api/src/handlers/config.rs

@@ -0,0 +1,84 @@
+use axum::{extract::State, Json};
+use serde::Serialize;
+use std::sync::Arc;
+
+use crate::AppState;
+
+#[derive(Serialize)]
+pub struct BrandingConfig {
+    pub chain_name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub logo_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub accent_color: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub background_color_dark: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub background_color_light: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub success_color: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error_color: Option<String>,
+}
+
+/// GET /api/config - Returns white-label branding configuration
+/// No DB access, no auth — returns static config from environment variables
+pub async fn get_config(State(state): State<Arc<AppState>>) -> Json<BrandingConfig> {
+    Json(BrandingConfig {
+        chain_name: state.chain_name.clone(),
+        logo_url: state.chain_logo_url.clone(),
+        accent_color: state.accent_color.clone(),
+        background_color_dark: state.background_color_dark.clone(),
+        background_color_light: state.background_color_light.clone(),
+        success_color: state.success_color.clone(),
+        error_color: state.error_color.clone(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn branding_config_skips_none_fields() {
+        let config = BrandingConfig {
+            chain_name: "TestChain".to_string(),
+            logo_url: None,
+            accent_color: Some("#3b82f6".to_string()),
+            background_color_dark: None,
+            background_color_light: None,
+            success_color: None,
+            error_color: None,
+        };
+
+        let json = serde_json::to_value(&config).unwrap();
+        assert_eq!(json["chain_name"], "TestChain");
+        assert_eq!(json["accent_color"], "#3b82f6");
+        assert!(json.get("logo_url").is_none());
+        assert!(json.get("background_color_dark").is_none());
+        assert!(json.get("success_color").is_none());
+        assert!(json.get("error_color").is_none());
+    }
+
+    #[test]
+    fn branding_config_includes_all_fields_when_set() {
+        let config = BrandingConfig {
+            chain_name: "MyChain".to_string(),
+            logo_url: Some("/branding/logo.svg".to_string()),
+            accent_color: Some("#3b82f6".to_string()),
+            background_color_dark: Some("#0a0a0f".to_string()),
+            background_color_light: Some("#faf5ef".to_string()),
+            success_color: Some("#10b981".to_string()),
+            error_color: Some("#ef4444".to_string()),
+        };
+
+        let json = serde_json::to_value(&config).unwrap();
+        assert_eq!(json["chain_name"], "MyChain");
+        assert_eq!(json["logo_url"], "/branding/logo.svg");
+        assert_eq!(json["accent_color"], "#3b82f6");
+        assert_eq!(json["background_color_dark"], "#0a0a0f");
+        assert_eq!(json["background_color_light"], "#faf5ef");
+        assert_eq!(json["success_color"], "#10b981");
+        assert_eq!(json["error_color"], "#ef4444");
+    }
+}

backend/crates/atlas-api/src/handlers/mod.rs

@@ -1,6 +1,7 @@
 pub mod addresses;
 pub mod auth;
 pub mod blocks;
+pub mod config;
 pub mod contracts;
 pub mod etherscan;
 pub mod labels;

backend/crates/atlas-api/src/main.rs

@@ -21,6 +21,14 @@ pub struct AppState {
     pub rpc_url: String,
     pub solc_path: String,
     pub admin_api_key: Option<String>,
+    // White-label branding
+    pub chain_name: String,
+    pub chain_logo_url: Option<String>,
+    pub accent_color: Option<String>,
+    pub background_color_dark: Option<String>,
+    pub background_color_light: Option<String>,
+    pub success_color: Option<String>,
+    pub error_color: Option<String>,
 }
 
 #[tokio::main]
@@ -42,6 +50,13 @@ async fn main() -> Result<()> {
     let rpc_url = std::env::var("RPC_URL").expect("RPC_URL must be set");
     let solc_path = std::env::var("SOLC_PATH").unwrap_or_else(|_| "solc".to_string());
     let admin_api_key = std::env::var("ADMIN_API_KEY").ok();
+    let chain_name = parse_chain_name(std::env::var("CHAIN_NAME").ok());
+    let chain_logo_url = parse_optional_env(std::env::var("CHAIN_LOGO_URL").ok());
+    let accent_color = parse_optional_env(std::env::var("ACCENT_COLOR").ok());
+    let background_color_dark = parse_optional_env(std::env::var("BACKGROUND_COLOR_DARK").ok());
+    let background_color_light = parse_optional_env(std::env::var("BACKGROUND_COLOR_LIGHT").ok());
+    let success_color = parse_optional_env(std::env::var("SUCCESS_COLOR").ok());
+    let error_color = parse_optional_env(std::env::var("ERROR_COLOR").ok());
     let host = std::env::var("API_HOST").unwrap_or_else(|_| "0.0.0.0".to_string());
     let port: u16 = std::env::var("API_PORT")
         .unwrap_or_else(|_| "3000".to_string())
@@ -63,6 +78,13 @@ async fn main() -> Result<()> {
         rpc_url,
         solc_path,
         admin_api_key,
+        chain_name,
+        chain_logo_url,
+        accent_color,
+        background_color_dark,
+        background_color_light,
+        success_color,
+        error_color,
     });
 
     tokio::spawn(handlers::sse::run_block_event_fanout(
@@ -225,6 +247,8 @@ async fn main() -> Result<()> {
         .route("/api/search", get(handlers::search::search))
         // Status
         .route("/api/status", get(handlers::status::get_status))
+        // Config (white-label branding)
+        .route("/api/config", get(handlers::config::get_config))
         // Health
         .route("/health", get(|| async { "OK" }))
         .layer(TimeoutLayer::with_status_code(
@@ -251,3 +275,68 @@ async fn main() -> Result<()> {
 
     Ok(())
 }
+
+fn parse_chain_name(val: Option<String>) -> String {
+    val.filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| "Unknown".to_string())
+}
+
+fn parse_optional_env(val: Option<String>) -> Option<String> {
+    val.map(|s| s.trim().to_string()).filter(|s| !s.is_empty())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn chain_name_defaults_to_unknown_when_unset() {
+        assert_eq!(parse_chain_name(None), "Unknown");
+    }
+
+    #[test]
+    fn chain_name_defaults_to_unknown_when_empty() {
+        assert_eq!(parse_chain_name(Some("".to_string())), "Unknown");
+    }
+
+    #[test]
+    fn chain_name_defaults_to_unknown_when_whitespace_only() {
+        assert_eq!(parse_chain_name(Some("   ".to_string())), "Unknown");
+    }
+
+    #[test]
+    fn chain_name_uses_provided_value() {
+        assert_eq!(parse_chain_name(Some("MyChain".to_string())), "MyChain");
+    }
+
+    #[test]
+    fn optional_env_returns_none_when_unset() {
+        assert_eq!(parse_optional_env(None), None);
+    }
+
+    #[test]
+    fn optional_env_returns_none_when_empty() {
+        assert_eq!(parse_optional_env(Some("".to_string())), None);
+    }
+
+    #[test]
+    fn optional_env_returns_none_when_whitespace_only() {
+        assert_eq!(parse_optional_env(Some("   ".to_string())), None);
+    }
+
+    #[test]
+    fn optional_env_trims_and_returns_value() {
+        assert_eq!(
+            parse_optional_env(Some("  #dc2626  ".to_string())),
+            Some("#dc2626".to_string())
+        );
+    }
+
+    #[test]
+    fn optional_env_returns_value_as_is_when_no_whitespace() {
+        assert_eq!(
+            parse_optional_env(Some("#3b82f6".to_string())),
+            Some("#3b82f6".to_string())
+        );
+    }
+}

docker-compose.yml

@@ -47,6 +47,13 @@ services:
       API_HOST: 0.0.0.0
       API_PORT: 3000
       RUST_LOG: atlas_api=info,tower_http=info
+      CHAIN_NAME: ${CHAIN_NAME:-Unknown}
+      CHAIN_LOGO_URL: ${CHAIN_LOGO_URL:-}
+      ACCENT_COLOR: ${ACCENT_COLOR:-}
+      BACKGROUND_COLOR_DARK: ${BACKGROUND_COLOR_DARK:-}
+      BACKGROUND_COLOR_LIGHT: ${BACKGROUND_COLOR_LIGHT:-}
+      SUCCESS_COLOR: ${SUCCESS_COLOR:-}
+      ERROR_COLOR: ${ERROR_COLOR:-}
     ports:
       - "3000:3000"
     depends_on:
@@ -60,6 +67,8 @@ services:
       dockerfile: Dockerfile
     ports:
       - "80:8080"
+    volumes:
+      - ${BRANDING_DIR:-./branding}:/usr/share/nginx/html/branding:ro
     depends_on:
       - atlas-api
     restart: unless-stopped