feat: Add startup-time config validator with deprecation mapping

Makefile

@@ -0,0 +1,27 @@
+.PHONY: doctor validate-config help
+
+help:
+	@echo "Available targets:"
+	@echo "  doctor          - Validate configuration (alias for validate-config)"
+	@echo "  validate-config - Validate environment configuration file"
+	@echo ""
+	@echo "Usage:"
+	@echo "  make doctor [ENV_FILE=.env.mainnet]"
+	@echo "  make validate-config [ENV_FILE=.env.mainnet]"
+
+doctor: validate-config
+
+validate-config:
+	@if [ -z "$(ENV_FILE)" ]; then \
+		if [ -f ".env.mainnet" ]; then \
+			./scripts/validate-config.sh .env.mainnet; \
+		elif [ -f ".env.sepolia" ]; then \
+			./scripts/validate-config.sh .env.sepolia; \
+		else \
+			echo "Error: No .env file found. Please specify ENV_FILE=path/to/.env"; \
+			exit 1; \
+		fi \
+	else \
+		./scripts/validate-config.sh $(ENV_FILE); \
+	fi
+

README.md

@@ -123,6 +123,68 @@ Supported clients:
 
 For full configuration options, see the `.env.mainnet` file.
 
+## Configuration Validation
+
+The repository includes a built-in configuration validator that helps detect configuration issues before starting the node. This validator:
+
+- ✅ Validates required environment variables are present
+- ⚠️ Detects deprecated environment variables and suggests replacements
+- 🔍 Identifies unknown/typo variables and suggests corrections
+- 📋 Validates URL, port, and numeric format requirements
+- 📊 Provides a consolidated report with actionable suggestions
+
+### Using the Validator
+
+#### Option 1: Using Make (Recommended)
+
+```bash
+# Validate default .env.mainnet
+make doctor
+
+# Validate a specific env file
+make doctor ENV_FILE=.env.sepolia
+```
+
+#### Option 2: Direct Script Execution
+
+```bash
+# Validate default .env.mainnet
+./scripts/validate-config.sh
+
+# Validate a specific env file
+./scripts/validate-config.sh .env.sepolia
+```
+
+#### Option 3: Using Docker Compose
+
+```bash
+# Validate configuration before starting services
+docker compose --profile validation run --rm config-doctor
+
+# Validate a specific env file
+NETWORK_ENV=.env.sepolia docker compose --profile validation run --rm config-doctor
+```
+
+### Example Output
+
+```
+Validating configuration file: .env.mainnet
+Detected client: reth
+
+❌ ERRORS:
+  Missing required variables:
+    - OP_NODE_L1_BEACON_ARCHIVER
+
+⚠️  WARNINGS:
+  Deprecated variable 'OLD_VAR_NAME' found. Use 'NEW_VAR_NAME' instead.
+  Unknown variable 'OP_NODE_TYPO' found. Did you mean 'OP_NODE_NETWORK'?
+  Invalid URL format for 'OP_NODE_L1_ETH_RPC': 'invalid-url' (must start with http://, https://, ws://, or wss://)
+```
+
+### Deprecation Mapping
+
+When environment variables are renamed across releases, the deprecation mapping in `config/deprecations.json` automatically suggests the correct replacement. This file can be updated as variables are deprecated in future releases.
+
 ## Snapshots
 
 Snapshots are available to help you sync your node more quickly. See [docs.base.org](https://docs.base.org/chain/run-a-base-node#snapshots) for links and more details on how to restore from a snapshot.

config-doctor/Dockerfile

@@ -0,0 +1,14 @@
+FROM bash:5.2
+
+WORKDIR /app
+
+# Copy validation scripts and config
+COPY scripts/validate-config.sh /app/validate-config.sh
+COPY config/deprecations.json /app/config/deprecations.json
+
+# Make script executable
+RUN chmod +x /app/validate-config.sh
+
+# Default command runs validation
+CMD ["/app/validate-config.sh"]
+

config/deprecations.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "This file maps deprecated environment variable names to their replacements.",
+  "_comment2": "Example format: \"OLD_VAR_NAME\": \"NEW_VAR_NAME\"",
+  "_comment3": "If a variable was removed without replacement, map it to null: \"OLD_VAR\": null",
+  "_comment4": "Add deprecated variables here as they are renamed in future releases"
+}
+

docker-compose.yml

@@ -1,4 +1,19 @@
 services:
+  config-doctor:
+    build:
+      context: .
+      dockerfile: config-doctor/Dockerfile
+    env_file:
+      - ${NETWORK_ENV:-.env.mainnet}
+    environment:
+      - NETWORK_ENV=${NETWORK_ENV:-.env.mainnet}
+      - CLIENT=${CLIENT:-geth}
+    volumes:
+      - .:/workspace:ro
+    working_dir: /workspace
+    command: ["/app/validate-config.sh", "/workspace/${NETWORK_ENV:-.env.mainnet}"]
+    profiles:
+      - validation
   execution:
     build:
       context: .