feat: add challenge custom events for WebSocket broadcast

- Add ChallengeCustomEvent to WsEvent enum
- Add POST /api/v1/events/broadcast endpoint
- Challenges can broadcast custom events to all connected validators
- Validators filter by challenge_id to receive relevant events

Author: echobt

crates/platform-server/src/api/events.rs

@@ -0,0 +1,61 @@
+//! Challenge Events API
+//!
+//! Allows challenges to broadcast custom events to validators via WebSocket.
+
+use crate::models::{ChallengeCustomEvent, WsEvent};
+use crate::state::AppState;
+use axum::{extract::State, http::StatusCode, Json};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use tracing::info;
+
+#[derive(Debug, Deserialize)]
+pub struct BroadcastEventRequest {
+    /// Challenge ID (must match a registered challenge)
+    pub challenge_id: String,
+    /// Event name (e.g., "new_submission", "evaluation_needed")
+    pub event_name: String,
+    /// Event payload - challenge-specific JSON data
+    pub payload: serde_json::Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct BroadcastEventResponse {
+    pub success: bool,
+    pub connections_notified: usize,
+    pub error: Option<String>,
+}
+
+/// POST /api/v1/events/broadcast - Broadcast a custom challenge event
+///
+/// Called by challenge containers to notify validators of events.
+/// Validators filter events by challenge_id to receive only relevant ones.
+pub async fn broadcast_event(
+    State(state): State<Arc<AppState>>,
+    Json(req): Json<BroadcastEventRequest>,
+) -> Result<Json<BroadcastEventResponse>, (StatusCode, String)> {
+    // Create the custom event
+    let event = ChallengeCustomEvent {
+        challenge_id: req.challenge_id.clone(),
+        event_name: req.event_name.clone(),
+        payload: req.payload,
+        timestamp: chrono::Utc::now().timestamp(),
+    };
+
+    // Get connection count before broadcast
+    let connections = state.broadcaster.connection_count();
+
+    // Broadcast to all connected clients
+    state.broadcaster.broadcast(WsEvent::ChallengeEvent(event));
+
+    info!(
+        "Broadcast challenge event: {}:{} to {} connections",
+        req.challenge_id, req.event_name, connections
+    );
+
+    Ok(Json(BroadcastEventResponse {
+        success: true,
+        connections_notified: connections,
+        error: None,
+    }))
+}

crates/platform-server/src/api/mod.rs

@@ -4,6 +4,7 @@ pub mod auth;
 pub mod bridge;
 pub mod challenges;
 pub mod evaluations;
+pub mod events;
 pub mod jobs;
 pub mod leaderboard;
 pub mod llm;

crates/platform-server/src/main.rs

@@ -232,6 +232,11 @@ async fn main() -> anyhow::Result<()> {
         )
         // === CENTRALIZED LLM PROXY ===
         .route("/api/v1/llm/chat", post(api::llm::chat))
+        // === CHALLENGE EVENTS (broadcast to validators) ===
+        .route(
+            "/api/v1/events/broadcast",
+            post(api::events::broadcast_event),
+        )
         .layer(TraceLayer::new_for_http())
         .layer(
             CorsLayer::new()

crates/platform-server/src/models/mod.rs

@@ -308,6 +308,11 @@ pub enum WsEvent {
     #[serde(rename = "job_assigned")]
     JobAssigned(JobAssignedEvent),
 
+    /// Custom challenge event - each challenge can define its own event types
+    /// Validators filter by challenge_id to receive only relevant events
+    #[serde(rename = "challenge_event")]
+    ChallengeEvent(ChallengeCustomEvent),
+
     #[serde(rename = "job_progress")]
     JobProgress(JobProgressEvent),
 
@@ -461,6 +466,20 @@ pub struct ChallengeStoppedEvent {
     pub id: String,
 }
 
+/// Custom event from a challenge - allows challenges to broadcast their own events
+/// Validators subscribe and filter by challenge_id
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ChallengeCustomEvent {
+    /// Challenge identifier (e.g., "term-challenge")
+    pub challenge_id: String,
+    /// Event name within the challenge (e.g., "new_submission", "evaluation_needed")
+    pub event_name: String,
+    /// Event payload as JSON - challenge-specific data
+    pub payload: serde_json::Value,
+    /// Timestamp when event was created
+    pub timestamp: i64,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ValidatorEvent {
     pub hotkey: String,