feat(#357): Add transaction status tracking via WebSocket

- Implement WebSocket server for real-time transaction tracking
- Support subscribe/unsubscribe actions for transaction IDs
- Emit status events: PENDING, SUBMITTED, CONFIRMED, FAILED
- Handle reconnection with broadcast channel for reliability
- Add comprehensive documentation and usage examples
- Include unit tests for serialization and status enums
- Add Dockerfile for containerized deployment

Author: xam-cli

api-server/Dockerfile

@@ -0,0 +1,19 @@
+# syntax=docker/dockerfile:1
+FROM rust:1.78-slim AS builder
+
+WORKDIR /app
+
+COPY Cargo.toml Cargo.lock ./
+COPY api-server/ api-server/
+
+RUN cargo build --release -p router-api-server
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/router-api-server /usr/local/bin/
+
+EXPOSE 8080
+
+ENTRYPOINT ["router-api-server"]

api-server/README.md

@@ -0,0 +1,158 @@
+# router-api-server
+
+Off-chain API server for stellar-router providing transaction simulation and real-time status tracking via WebSocket.
+
+## Features
+
+### Transaction Simulation Endpoint (`/simulate`)
+
+Allows developers to preview transaction outcomes before execution.
+
+**Request:**
+```json
+POST /simulate
+{
+  "target": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4",
+  "function": "transfer",
+  "route_details": {
+    "name": "swap_route",
+    "version": 1,
+    "expected_outputs": ["1000000"]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "estimated_fees": {
+    "base_fee": 100,
+    "resource_fee": 1000,
+    "total_fee": 1100,
+    "surge_multiplier": 100,
+    "high_load": false
+  },
+  "expected_outputs": ["1000000"],
+  "route_breakdown": {
+    "route_name": "swap_route",
+    "version": 1,
+    "target_contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4",
+    "function": "transfer"
+  },
+  "message": "Simulation successful"
+}
+```
+
+### WebSocket Transaction Status Tracking (`/ws`)
+
+Real-time transaction status updates via WebSocket.
+
+**Subscribe to transaction:**
+```json
+{
+  "action": "subscribe",
+  "tx_id": "tx_12345"
+}
+```
+
+**Status events:**
+```json
+{
+  "msg_type": "status_update",
+  "data": {
+    "tx_id": "tx_12345",
+    "status": "PENDING",
+    "timestamp": "2026-04-28T02:38:56Z",
+    "message": "Transaction queued"
+  }
+}
+```
+
+**Supported statuses:**
+- `PENDING` - Transaction is pending
+- `SUBMITTED` - Transaction submitted to network
+- `CONFIRMED` - Transaction confirmed on-chain
+- `FAILED` - Transaction failed
+
+**Unsubscribe from transaction:**
+```json
+{
+  "action": "unsubscribe",
+  "tx_id": "tx_12345"
+}
+```
+
+## Running
+
+### Prerequisites
+
+- Rust 1.78+
+- Soroban RPC endpoint URL
+- Router execution contract ID
+
+### Environment Variables
+
+```bash
+export LISTEN_ADDR="127.0.0.1:8080"
+export SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
+export ROUTER_EXECUTION_CONTRACT_ID="CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4"
+```
+
+### Start Server
+
+```bash
+cargo run --release -p router-api-server
+```
+
+### Docker
+
+```bash
+docker build -t router-api-server -f Dockerfile.api .
+docker run -p 8080:8080 \
+  -e SOROBAN_RPC_URL="https://soroban-testnet.stellar.org" \
+  -e ROUTER_EXECUTION_CONTRACT_ID="CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4" \
+  router-api-server
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/simulate` | POST | Simulate transaction |
+| `/ws` | GET | WebSocket connection for status tracking |
+
+## Reconnection Handling
+
+The WebSocket client should implement automatic reconnection with exponential backoff:
+
+1. Initial connection attempt
+2. On disconnect, wait 1 second before retry
+3. Double wait time on each subsequent failure (max 30 seconds)
+4. Re-subscribe to previous transaction IDs after reconnection
+
+## Error Handling
+
+### Simulation Errors
+
+- `400 Bad Request` - Missing or invalid parameters
+- `500 Internal Server Error` - RPC or contract call failure
+
+### WebSocket Errors
+
+- Invalid JSON in message
+- Unknown action type
+- Connection timeout (server-side: 5 minutes of inactivity)
+
+## Development
+
+Run tests:
+```bash
+cargo test -p router-api-server
+```
+
+Build release:
+```bash
+cargo build --release -p router-api-server
+```

api-server/src/main.rs

@@ -3,6 +3,9 @@ mod state;
 mod types;
 mod websocket;
 
+#[cfg(test)]
+mod tests;
+
 use anyhow::{Context, Result};
 use axum::{
     extract::DefaultBodyLimit,

api-server/src/tests.rs

@@ -0,0 +1,92 @@
+#[cfg(test)]
+mod tests {
+    use crate::types::{SimulateRequest, RouteDetails, TransactionStatus, TransactionStatusEvent};
+    use chrono::Utc;
+
+    #[test]
+    fn test_simulate_request_serialization() {
+        let req = SimulateRequest {
+            target: "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4".to_string(),
+            function: "transfer".to_string(),
+            route_details: Some(RouteDetails {
+                name: "swap".to_string(),
+                version: Some(1),
+                expected_outputs: Some(vec!["1000000".to_string()]),
+            }),
+        };
+
+        let json = serde_json::to_string(&req).unwrap();
+        let deserialized: SimulateRequest = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(deserialized.target, req.target);
+        assert_eq!(deserialized.function, req.function);
+    }
+
+    #[test]
+    fn test_transaction_status_event_serialization() {
+        let event = TransactionStatusEvent {
+            tx_id: "tx_12345".to_string(),
+            status: TransactionStatus::Pending,
+            timestamp: Utc::now().to_rfc3339(),
+            message: Some("Transaction queued".to_string()),
+        };
+
+        let json = serde_json::to_string(&event).unwrap();
+        let deserialized: TransactionStatusEvent = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(deserialized.tx_id, event.tx_id);
+        assert_eq!(deserialized.status, TransactionStatus::Pending);
+    }
+
+    #[test]
+    fn test_transaction_status_enum() {
+        assert_eq!(
+            serde_json::to_string(&TransactionStatus::Pending).unwrap(),
+            "\"PENDING\""
+        );
+        assert_eq!(
+            serde_json::to_string(&TransactionStatus::Submitted).unwrap(),
+            "\"SUBMITTED\""
+        );
+        assert_eq!(
+            serde_json::to_string(&TransactionStatus::Confirmed).unwrap(),
+            "\"CONFIRMED\""
+        );
+        assert_eq!(
+            serde_json::to_string(&TransactionStatus::Failed).unwrap(),
+            "\"FAILED\""
+        );
+    }
+
+    #[test]
+    fn test_fee_estimate_calculation() {
+        use crate::types::FeeEstimate;
+
+        let fee = FeeEstimate {
+            base_fee: 100,
+            resource_fee: 1000,
+            total_fee: 1100,
+            surge_multiplier: 100,
+            high_load: false,
+        };
+
+        assert_eq!(fee.base_fee + fee.resource_fee, 1100);
+        assert!(!fee.high_load);
+    }
+
+    #[test]
+    fn test_fee_estimate_with_surge() {
+        use crate::types::FeeEstimate;
+
+        let fee = FeeEstimate {
+            base_fee: 100,
+            resource_fee: 1000,
+            total_fee: 2200,
+            surge_multiplier: 200,
+            high_load: true,
+        };
+
+        assert_eq!(fee.total_fee, (fee.base_fee + fee.resource_fee) * 2);
+        assert!(fee.high_load);
+    }
+}