.env.example

# =====================================
# Stellar Micro-Donation API — .env.example
#
# Copy this file to .env and fill in the values:
#   cp .env.example .env
#
# Variables marked REQUIRED must be set before the server will start.
# Variables marked OPTIONAL have safe defaults and can be left commented.
# =====================================


# =====================================
# Server Configuration
# =====================================

# Port the API server listens on.
PORT=3000

# Runtime environment. Use "development" locally, "production" in prod.
NODE_ENV=development


# =====================================
# Authentication (REQUIRED)
# =====================================

# Comma-separated list of API keys accepted by the server.
# At least one key is required for any request to be authenticated.
# Example: dev_key_1234567890,dev_key_abcdef123456
API_KEYS=dev_key_1234567890,dev_key_abcdef123456


# =====================================
# Encryption (REQUIRED)
# =====================================

# A stable 64-hex-character (32-byte) key used to encrypt sensitive data
# such as wallet secret keys stored in the database.
#
# ⚠  The server will REFUSE TO START if this is not set.
# ⚠  Changing this key makes all previously encrypted data unrecoverable.
#
# Generate a key:
#   npm run generate-key
#
# Then replace the placeholder below with the output.
ENCRYPTION_KEY=<run `npm run generate-key` and paste the 64-char hex output here>


# =====================================
# Stellar Network Configuration
# =====================================

# Stellar environment to target.
# Allowed values: testnet | mainnet | futurenet
STELLAR_NETWORK=testnet

# Use mock Stellar responses — no outbound network calls are made.
# ✅ Keep true for local development and CI (no Stellar account needed).
# Set to false only when you need to test against a real Stellar network.
MOCK_STELLAR=true

# Optional: override the Horizon endpoint for the selected network.
# Leave commented to use the default URL for STELLAR_NETWORK.
# HORIZON_URL=https://horizon-testnet.stellar.org


# =====================================
# Database Configuration
# =====================================

# Path to the SQLite database file (relative to project root).
DB_PATH=./data/stellar_donations.db

# Maximum number of reusable SQLite connections in the in-process pool.
# OPTIONAL — default: 5
# DB_POOL_SIZE=5

# Milliseconds to wait for a pooled connection before failing.
# OPTIONAL — default: 10000
# DB_ACQUIRE_TIMEOUT=10000


# =====================================
# CORS Configuration
# =====================================

# Comma-separated list of allowed origins for browser-based clients.
# Development default allows common localhost ports.
# Production: set this explicitly — leaving it unset rejects all browser origins.
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:8080

# OPTIONAL overrides (uncomment to customise):
# CORS_ALLOWED_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS
# CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-API-Key,X-Request-ID,X-Idempotency-Key
# CORS_MAX_AGE=86400


# =====================================
# Logging Configuration
# =====================================

# Enable verbose debug logging — useful for local troubleshooting.
# ⚠  Never enable in production; may expose sensitive information.
DEBUG_MODE=false

# Write logs to files in addition to the console.
LOG_TO_FILE=false

# Directory for log files when LOG_TO_FILE=true.
LOG_DIR=./logs

# Include request/response bodies in console output.
LOG_VERBOSE=false


# =====================================
# Donation Limits (XLM) — OPTIONAL
# =====================================

# Minimum donation amount accepted by validation.
MIN_DONATION_AMOUNT=0.01

# Maximum donation amount accepted by validation.
MAX_DONATION_AMOUNT=10000

# Daily cap per donor (0 = no limit).
MAX_DAILY_DONATION_PER_DONOR=0


# =====================================
# Rate Limiting — OPTIONAL
# =====================================

# Max requests per IP per time window.
RATE_LIMIT=100

# Auth token endpoint rate limit (requests per minute per IP)
# Default: 10 requests per minute
AUTH_TOKEN_RATE_LIMIT=10

# Auth refresh endpoint rate limit (requests per minute per IP)
# Default: 20 requests per minute
AUTH_REFRESH_RATE_LIMIT=20


# =====================================
# Service Account — OPTIONAL
# =====================================

# Stellar secret key for service-side signing operations.
# Leave commented unless you explicitly need service signing.
# ⚠  Never commit a real secret key.
# SERVICE_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX


# =====================================
# Geographic IP Blocking — OPTIONAL
# =====================================

# Comma-separated ISO country codes to block (e.g. RU,IR,KP,CU).
# GEO_BLOCKED_COUNTRIES=

# Comma-separated ISO country codes to always allow (overrides blocked list).
# GEO_ALLOWED_COUNTRIES=

# Comma-separated IPs / CIDR ranges that bypass geo-blocking.
# GEO_ALLOWED_IPS=

# Path to MaxMind GeoLite2-Country.mmdb (default: ./data/GeoLite2-Country.mmdb).
# MAXMIND_DB_PATH=./data/GeoLite2-Country.mmdb