[simplex]: Add Prometheus metrics and Grafana dashboard

sdk/packages/simplex/README.md

@@ -56,12 +56,81 @@ We provide a simple script for Docker operations:
 # Run as container
 ./scripts/docker.sh run
 
-# Use Docker Compose
+# Use Docker Compose (includes Prometheus + Grafana)
 ./scripts/docker.sh up
 ./scripts/docker.sh down
 ./scripts/docker.sh logs
 ```
 
+## Monitoring
+
+Simplex exposes Prometheus metrics when started with the `-p` flag. The Docker Compose stack includes Prometheus and Grafana pre-configured with a dashboard.
+
+### Quick Start
+
+```bash
+# Start everything (simplex + prometheus + grafana)
+cd scripts && docker compose up -d
+
+# Grafana is at http://localhost:3420 (admin/admin)
+# Prometheus is at http://localhost:9091
+```
+
+### Without Docker
+
+```bash
+# Start simplex with metrics on port 9090
+simplex run -c config.toml -p 9090
+
+# Point your own Prometheus at http://localhost:9090/metrics
+```
+
+### Exposed Metrics
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `simplex_orders_detected_total` | counter | | Orders detected on-chain |
+| `simplex_orders_filled_total` | counter | | Orders successfully filled |
+| `simplex_orders_executed_total` | counter | `success`, `strategy` | Orders executed (pass/fail) |
+| `simplex_orders_skipped_total` | counter | | Orders skipped (not profitable) |
+| `simplex_bids_submitted_total` | counter | `success` | Bids submitted to Hyperbridge |
+| `simplex_balance_usdc` | gauge | `chain_id` | USDC balance per chain |
+| `simplex_balance_usdt` | gauge | `chain_id` | USDT balance per chain |
+| `simplex_balance_native` | gauge | `chain_id`, `symbol` | Native token balance per chain |
+| `simplex_balance_exotic` | gauge | `chain_id`, `symbol` | Exotic token balance per chain |
+| `simplex_bids_pending` | gauge | | Bids pending retraction |
+| `simplex_bids_successful` | gauge | | Total successful bids |
+| `simplex_bids_failed` | gauge | | Total failed bids |
+| `simplex_bids_retracted` | gauge | | Total retracted bids |
+| `simplex_hyperbridge_balance_free` | gauge | | Substrate free balance |
+| `simplex_hyperbridge_balance_reserved` | gauge | | Substrate reserved balance |
+| `simplex_uptime_seconds` | gauge | | Process uptime |
+| `simplex_order_processing_duration_seconds` | histogram | `success` | Detection-to-execution latency |
+
+Node.js process metrics (CPU, memory, GC, event loop) are also exported with the `simplex_` prefix.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `GRAFANA_PORT` | `3420` | Grafana host port |
+| `GRAFANA_USER` | `admin` | Grafana admin username |
+| `GRAFANA_PASSWORD` | `admin` | Grafana admin password |
+| `PROMETHEUS_PORT` | `9091` | Prometheus host port |
+| `CONFIG_PATH` | `../config.toml` | Path to simplex config file |
+
+### Grafana Dashboard
+
+A pre-provisioned "Simplex Filler" dashboard is included with panels for:
+
+- Order throughput and success rate
+- Order processing latency percentiles (p50/p95/p99)
+- USDC/USDT/native/exotic balance history per chain
+- Total stablecoin balance across all chains
+- Hyperbridge substrate balance
+- Bid status breakdown
+- Process memory usage
+
 ## Configuration
 
 The filler uses a TOML configuration file. See `filler-config-example.toml` for a complete example.

sdk/packages/simplex/package.json

@@ -73,6 +73,7 @@
 		"ethers": "^5.7.2",
 		"p-queue": "^8.1.0",
 		"pino": "^9.9.5",
+		"prom-client": "^15.1.0",
 		"pino-pretty": "^11.3.0",
 		"scale-ts": "^1.6.1",
 		"toml": "^3.0.0",

sdk/packages/simplex/scripts/Dockerfile

@@ -32,9 +32,9 @@ RUN cd packages/sdk && pnpm build
 # Build simplex
 RUN cd packages/simplex && pnpm build
 
-# Create a healthcheck script
+# Create a healthcheck script that hits the metrics /health endpoint
 RUN echo '#!/bin/sh' > /app/healthcheck.sh && \
-    echo 'ps -ef | grep "node" | grep -v grep > /dev/null || exit 1' >> /app/healthcheck.sh && \
+    echo 'node -e "fetch(\"http://localhost:9090/health\").then(r=>{if(!r.ok)throw 1})" 2>/dev/null || ps -ef | grep "node" | grep -v grep > /dev/null || exit 1' >> /app/healthcheck.sh && \
     chmod +x /app/healthcheck.sh
 
 USER simplex

sdk/packages/simplex/scripts/docker-compose.yml

@@ -8,7 +8,7 @@ services:
             dockerfile: packages/simplex/scripts/Dockerfile
         container_name: hyperbridge-simplex
         restart: unless-stopped
-        command: ["run", "-c", "/app/config/config.toml"]
+        command: ["run", "-c", "/app/config/config.toml", "-p", "9090"]
         volumes:
             - ${CONFIG_PATH:-../config.toml}:/app/config/config.toml:ro
         environment:
@@ -21,12 +21,48 @@ services:
                 max-size: "10m"
                 max-file: "3"
         healthcheck:
-            test: ["CMD", "/app/healthcheck.sh"]
+            test: ["CMD", "node", "-e", "fetch('http://localhost:9090/health').then(r=>{if(!r.ok)throw 1})"]
             interval: 30s
             timeout: 10s
             retries: 3
             start_period: 5s
 
+    prometheus:
+        image: prom/prometheus:latest
+        container_name: simplex-prometheus
+        restart: unless-stopped
+        volumes:
+            - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+            - prometheus-data:/prometheus
+        command:
+            - "--config.file=/etc/prometheus/prometheus.yml"
+            - "--storage.tsdb.retention.time=30d"
+        networks:
+            - simplex-network
+        ports:
+            - "${PROMETHEUS_PORT:-9091}:9090"
+
+    grafana:
+        image: grafana/grafana:latest
+        container_name: simplex-grafana
+        restart: unless-stopped
+        volumes:
+            - ./monitoring/grafana/provisioning:/etc/grafana/provisioning:ro
+            - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro
+            - grafana-data:/var/lib/grafana
+        environment:
+            - GF_SECURITY_ADMIN_USER=${GRAFANA_USER:-admin}
+            - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
+            - GF_USERS_ALLOW_SIGN_UP=false
+        networks:
+            - simplex-network
+        ports:
+            - "${GRAFANA_PORT:-3420}:3000"
+
+volumes:
+    prometheus-data:
+    grafana-data:
+
 networks:
     simplex-network:
         driver: bridge