.env.example

# =============================================================================
# STELLAR INSIGHTS BACKEND - ENVIRONMENT CONFIGURATION
# =============================================================================
# Copy this file to .env and update with your actual values
# NEVER commit .env to version control!
# 
# IMPORTANT: Secrets should be managed via Vault, not environment variables.
# See docs/SECRETS_MANAGEMENT.md for setup instructions.
# =============================================================================

# Vault Configuration (REQUIRED for production)
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=s.your-app-token
VAULT_NAMESPACE=stellar-insights

# Database Configuration
# For SQLite (recommended for development):
DATABASE_URL=sqlite:./stellar_insights.db
# For PostgreSQL (production - use Vault):
# DATABASE_URL=postgresql://username:password@localhost:5432/stellar_insights

# SQL query logging (optional)
# Development: all queries logged. Production: only slow queries (see DB_SLOW_QUERY_MS).
# To see query logs, set RUST_LOG=info (or debug) and DB_LOG_LEVEL=debug in development.
# RUST_ENV=development
# DB_LOG_LEVEL=debug
# DB_SLOW_QUERY_MS=100

# Database Connection Pool Tuning
# Increase DB_POOL_MAX_CONNECTIONS under high load to reduce pool exhaustion.
# Decrease DB_POOL_CONNECT_TIMEOUT_SECONDS so callers get a fast 503 instead of hanging.
# DB_POOL_MAX_CONNECTIONS=100
# DB_POOL_MIN_CONNECTIONS=5
# DB_POOL_CONNECT_TIMEOUT_SECONDS=10
# DB_POOL_IDLE_TIMEOUT_SECONDS=600
# DB_POOL_MAX_LIFETIME_SECONDS=1800

# Concurrency Limiter
# Maximum number of in-flight HTTP requests before the server returns 503.
# Prevents resource exhaustion under traffic spikes (#1496).
# MAX_IN_FLIGHT_REQUESTS=500

# Logging
RUST_LOG=info
LOG_FORMAT=json

# ---------------------------------------------------------------------------
# ELK Stack Configuration
# ---------------------------------------------------------------------------
# Set LOGSTASH_ENABLED=true to forward structured logs to Logstash.
# LOGSTASH_HOST: host:port for the Logstash TCP/UDP input (default: 5000).
# ELASTICSEARCH_URL: REST endpoint for direct ES queries / health checks.
# KIBANA_URL: Kibana UI base URL (used for dashboard deep-links in alerts).
# LOGSTASH_URL: Logstash monitoring API endpoint (port 9600 by default).
# ENVIRONMENT: tag injected into every log record (development | staging | production).
LOGSTASH_ENABLED=true
LOGSTASH_HOST=localhost:5000
ELASTICSEARCH_URL=http://localhost:9200
KIBANA_URL=http://localhost:5601
LOGSTASH_URL=http://localhost:9600
# APP_ENV: development | staging | production
APP_ENV=development
ENVIRONMENT=development

# Encryption Configuration
# Must be a 32-byte (64-character hex) key for AES-256-GCM
# Generate with: openssl rand -hex 32
# For production, use Vault: vault kv put secret/encryption master_key=...
ENCRYPTION_KEY=CHANGE_ME_generate_with_openssl_rand_hex_32

# Observability (OpenTelemetry / Jaeger)
# ---------------------------------------------------------------------------
# Set OTEL_ENABLED=true to export traces via OTLP HTTP (port 4318).
# The default endpoint targets a local Jaeger all-in-one instance.
#
# Quick-start Jaeger (accepts OTLP HTTP on 4318, UI on 16686):
#   docker run --rm -p 4318:4318 -p 16686:16686 jaegertracing/all-in-one:latest
#
# Then open http://localhost:16686 and select service "stellar-insights-backend".
OTEL_ENABLED=false
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces

# JWT Secret (REQUIRED)
# Must be at least 32 characters. Generate with: openssl rand -base64 48
JWT_SECRET=CHANGE_ME_generate_with_openssl_rand_base64_48

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8080

# Request Timeout Configuration
# Maximum time (in seconds) to wait for a request to complete
# Prevents resource exhaustion from slow clients or hanging connections
REQUEST_TIMEOUT_SECONDS=30

# Redis Configuration
REDIS_URL=redis://127.0.0.1:6379

# RPC Configuration
RPC_MOCK_MODE=false
# Per-request HTTP timeout for all Stellar RPC / Horizon calls (seconds).
# Clamped to [5, 120]. Default: 30.
RPC_REQUEST_TIMEOUT_SECONDS=30
# Retry and circuit breaker (optional; defaults shown)
# RPC_MAX_RETRIES=3
# RPC_INITIAL_BACKOFF_MS=100
# RPC_MAX_BACKOFF_MS=5000
# RPC_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
# RPC_CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2
# RPC_CIRCUIT_BREAKER_TIMEOUT_SECONDS=30

# Webhook Dispatcher Supervision
# Maximum number of automatic restarts before the dispatcher gives up
# WEBHOOK_DISPATCHER_MAX_RESTARTS=10

# RPC Pagination Configuration
# Maximum records to fetch per request (Horizon API limit)
RPC_MAX_RECORDS_PER_REQUEST=200
# Maximum total records to fetch across all paginated requests
RPC_MAX_TOTAL_RECORDS=10000
# Delay between pagination requests in milliseconds (rate limiting)
RPC_PAGINATION_DELAY_MS=100

# Database Connection Pool Configuration
# Tuned for high-load resilience (#1497): larger max, shorter acquire timeout.
DB_POOL_MAX_CONNECTIONS=100
DB_POOL_MIN_CONNECTIONS=5
DB_POOL_CONNECT_TIMEOUT_SECONDS=10
DB_POOL_IDLE_TIMEOUT_SECONDS=600
DB_POOL_MAX_LIFETIME_SECONDS=1800

# Network Configuration (mainnet/testnet)
STELLAR_NETWORK=mainnet
STELLAR_RPC_URL_MAINNET=https://stellar.api.onfinality.io/public
STELLAR_HORIZON_URL_MAINNET=https://horizon.stellar.org
STELLAR_RPC_URL_TESTNET=https://soroban-testnet.stellar.org
STELLAR_HORIZON_URL_TESTNET=https://horizon-testnet.stellar.org

# ---------------------------------------------------------------------------
# Outbound Stellar RPC/Horizon Rate Limiting
# ---------------------------------------------------------------------------
# Token-bucket rate limiter for all outbound calls to Stellar RPC / Horizon.
# Keep RPC_RATE_LIMIT_REQUESTS_PER_MINUTE below Horizon's ~100 req/min public
# default to leave headroom for other consumers of the same API key.
#
# RPC_RATE_LIMIT_REQUESTS_PER_MINUTE
#   Maximum sustained request rate (requests per minute).
#   Sets the token-bucket refill rate. e.g. 90 → one token every ~0.67 s.
#   Default: 90
#
# RPC_RATE_LIMIT_BURST_SIZE
#   Maximum burst capacity (number of tokens the bucket can hold).
#   Allows short bursts above the sustained rate before throttling kicks in.
#   Default: 10
#
# RPC_RATE_LIMIT_QUEUE_SIZE
#   Maximum number of requests that can wait in the queue for a token.
#   Requests beyond this limit are rejected immediately (429-equivalent).
#   Tune this to control memory usage under heavy load.
#   Default: 100
RPC_RATE_LIMIT_REQUESTS_PER_MINUTE=90
RPC_RATE_LIMIT_BURST_SIZE=10
RPC_RATE_LIMIT_QUEUE_SIZE=100

# ---------------------------------------------------------------------------
# Redis Cache TTL Configuration
# ---------------------------------------------------------------------------
# Controls how long computed results are cached in Redis before expiry.
# Shorter TTLs mean fresher data but more DB/RPC load.
#
# CACHE_CORRIDOR_METRICS_TTL
#   TTL in seconds for corridor reliability metrics.
#   Default: 300 (5 minutes)
#
# CACHE_ANCHOR_DATA_TTL
#   TTL in seconds for anchor profile and metrics data.
#   Default: 600 (10 minutes)
#
# CACHE_DASHBOARD_STATS_TTL
#   TTL in seconds for dashboard summary statistics.
#   Default: 60 (1 minute)
CACHE_CORRIDOR_METRICS_TTL=300
CACHE_ANCHOR_DATA_TTL=600
CACHE_DASHBOARD_STATS_TTL=60

# CACHE_STATS_SUMMARY_TTL
#   TTL in seconds for /api/v1/stats/summary (issue #4). Defaults to
#   CACHE_DASHBOARD_STATS_TTL if unset -- only set this if the homepage
#   stat tiles need a different freshness window than /analytics/dashboard.
# CACHE_STATS_SUMMARY_TTL=60

BACKUP_S3_BUCKET=your-backup-bucket-name
BACKUP_RETENTION_DAYS=30
NOTIFICATION_EMAIL=admin@example.com
WALG_S3_PREFIX=s3://$BACKUP_S3_BUCKET/backups/
PGDATA=/var/lib/postgresql/data

# Local SQLite backup scheduler (disabled by default)
BACKUP_ENABLED=false
BACKUP_DIR=./backups
# Optional explicit DB path; if unset, derived from DATABASE_URL when possible
# BACKUP_DB_PATH=./stellar_insights.db
BACKUP_SCHEDULE_HOUR_UTC=2

# Backup Configuration (Optional - for production)
# BACKUP_S3_BUCKET=your-backup-bucket-name
# BACKUP_RETENTION_DAYS=30
# NOTIFICATION_EMAIL=admin@example.com
# WALG_S3_PREFIX=s3://your-backup-bucket-name/backups/
# PGDATA=/var/lib/postgresql/data

# Price Feed Configuration
PRICE_FEED_PROVIDER=coingecko
# PRICE_FEED_API_KEY=your_api_key_here
PRICE_FEED_CACHE_TTL_SECONDS=900
PRICE_FEED_REQUEST_TIMEOUT_SECONDS=10

# Compression Configuration
# Minimum response size in bytes to trigger compression (default: 1024)
# Responses smaller than this will not be compressed to avoid overhead
COMPRESSION_MIN_SIZE=1024
# Compression quality level: "fastest", "best", or a numeric level 0-9 (default: "default")
# "fastest" minimizes CPU overhead; "best" maximizes compression ratio
COMPRESSION_LEVEL=default

# ---------------------------------------------------------------------------
# CORS Configuration
# ---------------------------------------------------------------------------
# Comma-separated list of origins allowed to make cross-origin requests.
#
# Development: allow local frontend dev servers
CORS_ALLOWED_ORIGINS=http://localhost:3000,https://stellar-insights.com,https://app.stellar-insights.com
#
# Production: restrict to your actual deployed frontend domain(s)
# CORS_ALLOWED_ORIGINS=https://stellar-insights.com,https://www.stellar-insights.com
#
# WARNING: Setting this to "*" allows ALL origins and is NOT safe for production.
# CORS_ALLOWED_ORIGINS=*

# ---------------------------------------------------------------------------
# SEP-10 Authentication Configuration
# ---------------------------------------------------------------------------
# SEP-10 Authentication Configuration (REQUIRED)
# ---------------------------------------------------------------------------
# SECURITY CRITICAL: SEP-10 server public key for Stellar authentication
# This MUST be set to a valid Stellar public key - the placeholder will be rejected
# 
# Generate a new keypair:
#   stellar keys generate --network testnet
#   stellar keys generate --network mainnet
#
# NEVER use the placeholder value in production!
# Format: Must start with 'G' and be exactly 56 characters
SEP10_SERVER_PUBLIC_KEY=CHANGE_ME_generate_with_stellar_keys_generate

# Home domain for SEP-10 authentication
# This should match your application's domain
SEP10_HOME_DOMAIN=stellar-insights.local

# Stellar network passphrase (must match your network)
# Testnet: "Test SDF Network ; September 2015"
# Mainnet: "Public Global Stellar Network ; September 2015"
STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# SEP-10 challenge expiry in seconds (default: 300 = 5 minutes)
# SEP10_CHALLENGE_EXPIRY_SECONDS=300

# SEP-10 session expiry in days (default: 7)
# SEP10_SESSION_EXPIRY_DAYS=7

# ---------------------------------------------------------------------------
# Request Signing Configuration
# ---------------------------------------------------------------------------
# Maximum request body size in bytes for HMAC signature verification (default: 10MB)
# MAX_REQUEST_BODY_SIZE=10485760

# ---------------------------------------------------------------------------
# Background Job Configuration
# ---------------------------------------------------------------------------
# Enable/disable individual jobs and configure their intervals

# Corridor refresh job (default: 300 seconds = 5 minutes)
JOB_CORRIDOR_REFRESH_ENABLED=true
JOB_CORRIDOR_REFRESH_INTERVAL_SECONDS=300

# Anchor refresh job (default: 600 seconds = 10 minutes)
JOB_ANCHOR_REFRESH_ENABLED=true
JOB_ANCHOR_REFRESH_INTERVAL_SECONDS=600

# Price feed update job (default: 900 seconds = 15 minutes)
JOB_PRICE_FEED_UPDATE_ENABLED=true
JOB_PRICE_FEED_UPDATE_INTERVAL_SECONDS=900

# Cache cleanup job (default: 3600 seconds = 1 hour)
JOB_CACHE_CLEANUP_ENABLED=true
JOB_CACHE_CLEANUP_INTERVAL_SECONDS=3600

# Daily active accounts job (default: 900 seconds = 15 minutes).
# Computes DAA/tx-count for the current UTC calendar day and upserts into
# network_daily_metrics; backs the /api/v1/stats/summary and
# /api/v1/network/daily-active-accounts endpoints.
JOB_DAA_ENABLED=true
JOB_DAA_INTERVAL_SECONDS=900
# ---------------------------------------------------------------------------
# Telegram Bot Configuration
# ---------------------------------------------------------------------------
# Bot token from @BotFather. When set, the Telegram notification bot is enabled.
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# ---------------------------------------------------------------------------
# Slack Bot Configuration
# ---------------------------------------------------------------------------
# Slack webhook URL for sending alerts to Slack channels
# Create an incoming webhook at: https://api.slack.com/messaging/webhooks
# When set, corridor alerts and anchor notifications will be sent to Slack
# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# ---------------------------------------------------------------------------
# Admin IP Whitelisting Configuration
# ---------------------------------------------------------------------------
# Comma-separated list of IP addresses and CIDR ranges allowed to access admin endpoints
# Examples:
#   Single IP: 192.168.1.100
#   CIDR range: 192.168.1.0/24
#   Multiple: 192.168.1.100,10.0.0.0/8,172.16.0.1
#   IPv6: ::1,2001:db8::/32
# Development (localhost only):
ADMIN_IP_WHITELIST=127.0.0.1,::1
# Production example:
# ADMIN_IP_WHITELIST=203.0.113.0/24,198.51.100.50

# Trust X-Forwarded-For header when behind proxy/load balancer
# Set to true in production when using a reverse proxy (nginx, ALB, etc.)
ADMIN_IP_TRUST_PROXY=false

# Maximum number of IPs to check in X-Forwarded-For chain (prevents header injection)
# Default: 3
ADMIN_IP_MAX_FORWARDED=3

# ===========================================================================
# Debug Configuration
# ===========================================================================
# Rust backtrace for debugging
RUST_BACKTRACE=1