feat: enhance documentation and configuration for Docker setup, add subscription endpoint by ETH address, and improve error handling in API

Author: ai-chen2050

README.md

@@ -98,6 +98,18 @@
     ```
     The bot will start, generate a Nostr key pair for communication, and await configuration via its local API or admin panel.
 
+## **Docker Setup**
+
+**For Relayer:**
+```bash
+cd docker && docker compose -f docker-compose.relayer.yml up --build
+```
+
+**For Trader:**
+```bash
+cd docker && docker compose -f docker-compose.trader.yml up
+```
+
 ## **Architecture & Integration with Your Ecosystem**
 
 - **Core (MVP)**: This `moltrade-bot` and the cloud relay form the self-sustaining MVP.

docker/docker-compose.relayer.yml

@@ -0,0 +1,36 @@
+version: "3.9"
+
+services:
+  postgres:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: moltrade
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  relayer:
+    build: ../relayer
+    depends_on:
+      postgres:
+        condition: service_healthy
+    command: ["moltrade-relayer", "--config", "/etc/moltrade-relayer/config.toml"]
+    environment:
+      RUST_LOG: moltrade_relayer=info
+    volumes:
+      - ./relayer.config.toml:/etc/moltrade-relayer/config.toml:ro
+    ports:
+      - "8080:8080"  # REST + WebSocket
+      - "9090:9090"  # Prometheus metrics
+
+volumes:
+  postgres_data:
+    driver: local

docker/docker-compose.trader.yml

@@ -0,0 +1,14 @@
+version: "3.9"
+
+services:
+  trader:
+    image: python:3.11-slim
+    working_dir: /app
+    volumes:
+      - ../trader:/app:ro
+      - ./trader.config.json:/app/config.json:ro
+    environment:
+      PYTHONUNBUFFERED: "1"
+    command: >-
+      bash -c "pip install --no-cache-dir -r requirements.txt && \
+      python main.py --config /app/config.json --test --strategy momentum --symbol HYPE"

docker/relayer.config.toml

@@ -0,0 +1,47 @@
+# Relayer config for docker-compose
+[relay]
+bootstrap_relays = ["ws://62.72.41.239:8000"]
+max_connections = 10_000
+health_check_interval = 30
+
+[deduplication]
+hotset_size = 1_000_000
+bloom_capacity = 10_000_000
+lru_size = 100_000
+rocksdb_path = "./data/rocksdb"
+
+[filters]
+allowed_kinds = [30931, 30932, 30933, 30934]
+
+[output]
+websocket_enabled = true
+websocket_port = 8080
+batch_size = 100
+max_latency_ms = 50
+
+[postgres]
+dsn = "postgres://postgres:postgres@postgres:5432/moltrade"
+max_connections = 5
+
+[nostr]
+secret_key = "nsec1..."
+
+[settlement]
+explorer_base = "https://app.hyperliquid.xyz/explorer/transaction"
+poll_secs = 30
+batch_limit = 50
+token = ""
+
+[settlement.credit]
+leader_rate = 0.002
+follower_rate = 0.001
+min_credit = 0.5
+profit_multiplier = 1.2
+enable = true
+
+[subscriptions]
+daily_limit = 1000
+
+[monitoring]
+prometheus_port = 9090
+log_level = "info"

docker/trader.config.json

@@ -0,0 +1,75 @@
+{
+    "wallet_address": "0x_your_wallet",
+    "private_key": "your_private_key_here",
+    "telegram": {
+        "enabled": false,
+        "bot_token": "",
+        "chat_id": "",
+        "notify_startup": true,
+        "notify_signals": true,
+        "notify_trades": true,
+        "notify_closures": true,
+        "notify_errors": true,
+        "notify_daily_summary": true
+    },
+    "trading": {
+        "exchange": "hyperliquid",
+        "default_symbol": "HYPE",
+        "default_strategy": "test",
+        "position_size": 0.08,
+        "max_position_size": 0.2,
+        "stop_loss_percent": 0.03,
+        "take_profit_percent": 0.08
+    },
+    "strategies": {
+        "momentum": {
+            "rsi_period": 14,
+            "rsi_oversold": 30,
+            "rsi_overbought": 70,
+            "macd_fast": 12,
+            "macd_slow": 26,
+            "macd_signal": 9
+        },
+        "mean_reversion": {
+            "bollinger_period": 20,
+            "bollinger_std": 2,
+            "rsi_period": 14,
+            "rsi_oversold": 30,
+            "rsi_overbought": 70
+        },
+        "grid": {
+            "grid_levels": 10,
+            "grid_range_percent": 0.1,
+            "order_size_percent": 0.05
+        },
+        "trend_following": {
+            "min_trade_interval": 14400,
+            "min_adx": 30
+        }
+    },
+    "risk_management": {
+        "max_daily_loss": 0.05,
+        "max_trades_per_day": 8,
+        "cool_down_seconds": 300
+    },
+    "nostr": {
+        "nsec": "nsec1yourprivatekey",
+        "platform_shared_key": "64_hex_shared_key_from_platform",
+        "relays": [
+            "wss://nostr.parallel.hetu.org:8443"
+        ],
+        "sid": "subspace_op",
+        "role": "bot"
+    },
+    "copytrade": {
+        "enabled": false,
+        "follow_pubkeys": [
+            "npub_of_leader"
+        ],
+        "symbols": [
+            "HYPE"
+        ],
+        "size_pct": 0.05,
+        "min_order_value": 10.0
+    }
+}

docs/API.md

@@ -84,6 +84,12 @@ List subscriptions for a bot:
 curl http://localhost:8080/api/subscriptions/<bot_pubkey>
 ```
 
+List subscriptions for a bot by eth address (bot_pubkey == eth_address for EVM bots):
+
+```bash
+curl http://localhost:8080/api/subscriptions/by-eth/<eth_address>
+```
+
 Notes: subscription POSTs are rate-limited per bot `eth_address` via `[subscriptions].daily_limit` (default 1000; set to 0 to disable). GET is unrestricted. Exceeding the limit returns HTTP 429.
 
 ### Trades

relayer/Makefile

@@ -107,21 +107,18 @@ update: ## Update all dependencies to latest compatible version
 # ============================================================================
 # Run targets
 # ============================================================================
-run: build ## Run release version
-	@echo "🚀 Running release version..."
-	@$(RELEASE_BINARY)
-
-debug: dev ## Run development version (debug mode)
-	@echo "🚀 Running development version..."
-	@$(DEBUG_BINARY) --config config.template.toml
-
-run-with-config: build ## Run release version using config file
+run: build ## Run release version using config file
 	@echo "🚀 Running with config file..."
 	@if [ ! -f config.toml ]; then \
 		echo "⚠️  config.toml not found, using default config"; \
 	fi
 	@$(RELEASE_BINARY) --config config.toml
 
+
+debug: dev ## Run development version (debug mode)
+	@echo "🚀 Running development version..."
+	@$(DEBUG_BINARY) --config config.template.toml
+
 # ============================================================================
 # Test and check targets
 # ============================================================================

relayer/README.md

@@ -59,10 +59,10 @@ Rust service that ingests Nostr events, deduplicates, forwards to downstreams, a
 
 3. **Compile and run**
    ```bash
-   make build      # Build the project
-   make run        # Run the project
+   make build                  # Build the project
+   make run                    # Run the project with config.toml
    # Or
-   make dev        # Development mode (debug build)
+   make dev                    # Dev mode (debug build) with config.template.toml
    ```
 
 ### Using Makefile
@@ -154,6 +154,7 @@ lru_size = 50000                # LRU cache size
 # Output configuration
 websocket_enabled = true        # Enable WebSocket
 websocket_port = 8080           # WebSocket port
+bind_address = "127.0.0.1"      # Bind address for REST/WebSocket
 batch_size = 100                # Batch processing size
 max_latency_ms = 100            # Maximum latency (milliseconds)
 

relayer/config.template.toml

@@ -1,71 +1,52 @@
-# Relay configuration
-[relay]
-bootstrap_relays = [
-    "ws://62.72.41.239:8000",
-    # "wss://relay.damus.io",
-    # "wss://nostr.wine",
-    # "wss://relay.snort.social",
-]
-max_connections = 10000
-health_check_interval = 30
-
-# Deduplication configuration
 [deduplication]
-hotset_size = 1_000_000
-bloom_capacity = 10_000_000
-lru_size = 100_000
+bloom_capacity = 10000000
+hotset_size = 1000000
+lru_size = 100000
 rocksdb_path = "./data/rocksdb"
 
-# Nostr filtering configuration
 [filters]
-allowed_kinds = [30931, 30932, 30933, 30934]
+allowed_kinds = [
+    30931,
+    30932,
+    30933,
+    30934,
+]
+
+[monitoring]
+log_level = "debug"
+prometheus_port = 9090
+
+[nostr]
+secret_key = "nsec1kk97xcsmpdnh9e009f5987gtwh2jm0p3syvcva55ua98hvv3sk5sw2rt7k"
 
-# Output configuration
 [output]
-websocket_enabled = false
-websocket_port = 8080
 batch_size = 100
+bind_address = "127.0.0.1"
 max_latency_ms = 50
+websocket_enabled = false
+websocket_port = 8080
 
-# Postgres configuration (used for subscriptions/fanout)
 [postgres]
 dsn = "postgres://postgres:postgres@localhost:5432/moltrade"
 max_connections = 5
 
-# Nostr platform key (used to decrypt inbound and encrypt outbound)
-[nostr]
-# nsec... or hex sk
-secret_key = "nsec1..."
+[relay]
+bootstrap_relays = ["ws://62.72.41.239:8000"]
+health_check_interval = 30
+max_connections = 10000
 
-# Settlement worker (Hyperliquid tx hash polling)
 [settlement]
-# Base URL for tx lookup (defaults to Hyperliquid explorer tx endpoint)
+batch_limit = 50
 explorer_base = "https://app.hyperliquid.xyz/explorer/transaction"
-# Polling interval seconds
 poll_secs = 30
-# Max pending trades to check per tick
-batch_limit = 50
-# Optional shared token for settlement/reporting endpoints
 token = ""
 
-# Credit issuance config
 [settlement.credit]
-# Applied to leader trades (uses notional size * price * rate)
-leader_rate = 0.002
-# Applied to follower trades
+enable = true
 follower_rate = 0.001
-# Floor credit per confirmed trade
+leader_rate = 0.002
 min_credit = 0.5
-# Multiplier when pnl_usd > 0 (profit-making trades)
 profit_multiplier = 1.2
-enable = true
 
-# Subscription limits
 [subscriptions]
-# Daily POST limit for subscription endpoints (per bot eth_address). 0 disables limiting.
 daily_limit = 1000
-
-# Monitoring configuration
-[monitoring]
-prometheus_port = 9090
-log_level = "debug"