.env.example

# =============================================================================
# Vatix Backend - Environment Variables Reference
# Copy this file to .env and fill in values before running the server.
# Required = server will not start or the feature will not work without it.
# Optional = has a safe default or is only needed for an optional component.
# =============================================================================

# -----------------------------------------------------------------------------
# Server
# -----------------------------------------------------------------------------

# Optional: Port the HTTP API server listens on. Default: 3000.
#
PORT=3000

# Optional: Service name returned in the GET /v1/health response body.
# Useful when running multiple services to identify which service responded.
# Default: vatix-backend
SERVICE_NAME=vatix-backend

# Required: Runtime environment. Controls error handler behaviour.
# In production, internal server error messages and stack traces are hidden
# from API responses to prevent leaking implementation details.
# In development or test, they are included to aid debugging.
# Accepted values: development | test | production
NODE_ENV=development

# Optional: Request body size limit in bytes. Default: 65536 (64 KB).
# Requests exceeding this limit are rejected with 413 Request Entity Too Large.
BODY_LIMIT_BYTES=65536

# -----------------------------------------------------------------------------
# CORS
# -----------------------------------------------------------------------------

# Optional: Comma-separated list of allowed browser origins.
# Development/test default: http://localhost:3000,http://localhost:5173.
# Production default: no cross-origin access unless explicitly configured.
CORS_ALLOWED_ORIGINS=

# -----------------------------------------------------------------------------
# Database
# -----------------------------------------------------------------------------

# Required: PostgreSQL connection string used by Prisma.
# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/vatix

# -----------------------------------------------------------------------------
# Redis
# -----------------------------------------------------------------------------

# Optional: Redis connection URL used by rate limiting and session cache.
# Required only when Redis-backed features are enabled.
REDIS_URL=redis://localhost:6379

# Optional: Redis connection timeout in milliseconds. Default: 5000.
REDIS_CONNECT_TIMEOUT=5000

# Optional: Redis key prefix to namespace keys per environment.
REDIS_KEY_PREFIX=vatix:

# -----------------------------------------------------------------------------
# Stellar
# -----------------------------------------------------------------------------

# Optional: Stellar network name used by chain integrations. Default: testnet.
STELLAR_NETWORK=testnet

# Optional: Stellar Horizon API URL.
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# Required for readiness checks, indexer reads, and oracle reads.
# Testnet: https://soroban-testnet.stellar.org
# Mainnet: https://soroban.stellar.org
STELLAR_RPC_URL=https://soroban-testnet.stellar.org

# -----------------------------------------------------------------------------
# Indexer
# -----------------------------------------------------------------------------

# Required: Stellar network passphrase used by the event parser to identify the network.
# The passphrase is embedded in every transaction envelope and must match the target network.
# Testnet : "Test SDF Network ; September 2015"
# Mainnet : "Public Global Stellar Network ; September 2015"
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# Optional: Network identifier stored as part of the ledger cursor composite key.
# Used together with INDEXER_CURSOR_KEY to uniquely identify the cursor row in the
# indexer_cursors table. Change when running the indexer against multiple networks
# with a shared database. Default: mainnet
INDEXER_NETWORK_ID=mainnet

# Optional: Persisted ledger cursor checkpoint key.
# Used together with INDEXER_NETWORK_ID to identify the cursor row in indexer_cursors.
# Change only when running multiple indexer consumers against the same network.
# Default: ingestion
INDEXER_CURSOR_KEY=ingestion

# Required: Soroban market contract whose events the indexer ingests.
# Alias: MARKET_CONTRACT_ID is also accepted.
INDEXER_CONTRACT_ID=

# Optional: Max ledgers scanned per ingestion tick. Default: 100.
INDEXER_LEDGER_WINDOW_SIZE=100

# Optional: How often (ms) the ingestion loop polls for new ledgers. Default: 5000.
# Minimum: 100.
INDEXER_INGESTION_INTERVAL_MS=5000

# Optional: Number of successful batches between cursor checkpoints. Default: 10.
# Lower values persist the cursor more frequently (safer on crash, more DB writes).
INDEXER_CHECKPOINT_FLUSH_EVERY_BATCHES=10

# Optional: Log level for the indexer service. Default: info.
# Accepted values: debug | info | warn | error
INDEXER_LOG_LEVEL=info

# -----------------------------------------------------------------------------
# Authentication
# -----------------------------------------------------------------------------

# Required: API key for internal/protected endpoints.
API_KEY=your-api-key-here

# Required for admin routes and integration tests.
# Used by requireAdmin middleware (Authorization: Bearer <ADMIN_TOKEN>).
ADMIN_TOKEN=your-admin-token-here

# -----------------------------------------------------------------------------
# Rate Limiting
# -----------------------------------------------------------------------------

# Optional: Global rate limit window in milliseconds. Default: 60000.
RATE_LIMIT_WINDOW_MS=60000

# Optional: Global max requests per window. Default: 100.
RATE_LIMIT_MAX=100

# Optional: Heavy-read endpoint rate limit window in milliseconds. Default: 60000.
RATE_LIMIT_HEAVY_WINDOW_MS=60000

# Optional: Heavy-read endpoint max requests per window. Default: 20.
RATE_LIMIT_HEAVY_MAX=20

# Optional: Write endpoint rate limit window in milliseconds. Default: 60000.
RATE_LIMIT_WRITE_WINDOW_MS=60000

# Optional: Write endpoint max requests per window. Default: 10.
RATE_LIMIT_WRITE_MAX=10

# -----------------------------------------------------------------------------
# Finalization Worker
# -----------------------------------------------------------------------------

# Optional: Maximum time (in milliseconds) the worker waits for in-flight cleanup
# (database disconnect, queue drain) before forcing process.exit(1).
# Prevents the process from hanging indefinitely on shutdown (SIGTERM / SIGINT).
# Must be a positive integer. Default: 30000 (30 seconds).
WORKERS_SHUTDOWN_TIMEOUT_MS=30000

# Optional: Finalization worker polling interval in milliseconds.
FINALIZATION_INTERVAL_MS=60000

# Optional: Resolution challenge window in seconds. Default: 86400.
FINALIZATION_CHALLENGE_WINDOW_SECONDS=3600

# Optional: Finalization worker log level. Values: debug | info | warn | error.
FINALIZATION_LOG_LEVEL=info

# Optional: Maximum time (in milliseconds) a single finalization job run is
# allowed to take before it is aborted. Prevents hung jobs from blocking the
# worker indefinitely. Must be a positive integer.
# Default: 30000 (30 seconds).
FINALIZATION_JOB_TIMEOUT_MS=30000

# -----------------------------------------------------------------------------
# Oracle
# -----------------------------------------------------------------------------

# Optional: Oracle scheduler polling interval in milliseconds. Default: 30000.
# Must be between 5000 and 3600000.
ORACLE_POLL_INTERVAL_MS=30000

# Optional. Duration of the oracle challenge window in seconds.
# Must be a positive integer. Default: 86400 (24 hours).
ORACLE_CHALLENGE_WINDOW_SECONDS=86400

# Optional. Log level for the oracle scheduler.
# Accepted values: debug | info | warn | error
# Controls verbosity of oracle logging. Default: info
ORACLE_LOG_LEVEL=info

# Optional. Redis queue name for oracle submission queue.
# Used to enqueue oracle resolution reports for on-chain submission.
# Default: oracle-submissions
SUBMISSION_QUEUE_NAME=oracle-submissions

# Optional. Redis stream name for settlement jobs.
# Used to enqueue settlement jobs for off-chain execution.
# Default: settlement-trades
SETTLEMENT_QUEUE_NAME=settlement-trades

# Optional. Log level for the finalization worker.
# Accepted values: debug | info | warn | error
# Controls verbosity of finalization worker logging.
FINALIZATION_LOG_LEVEL=info

# Optional. Global log level for all components.
# Accepted values: debug | info | warn | error
# Applies to all loggers unless overridden. Default: info
LOG_LEVEL=info

# Required for signing oracle resolution reports.
# Stellar secret key for the oracle service account.
ORACLE_SECRET_KEY=

# -----------------------------------------------------------------------------
# Signature Helper
# -----------------------------------------------------------------------------

# Optional. URL of the signature helper service for testing off-chain payload signing.
# If provided, enables automated signature generation for local development.
SIGNATURE_HELPER_URL=http://localhost:4000

# -----------------------------------------------------------------------------
# Test Utilities
# -----------------------------------------------------------------------------

# Optional: PostgreSQL connection string used by the test suite.
# Defaults to DATABASE_URL when not set. Override to point tests at a
# dedicated test database so they do not affect development data.
# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5433/vatix_test

# Optional: Log level used during test runs.
# Accepted values: debug | info | warn | error
# Set to "error" to suppress noise; "debug" to trace failures.
# Default: info
TEST_LOG_LEVEL=error


# =============================================================================
# Configuration Types Reference
# =============================================================================
# 
# REQUIRED vs OPTIONAL:
# 
#   REQUIRED
#     Variables that must be set. Missing values will cause startup failure.
#     Examples:
#       - NODE_ENV (controls error handling and feature availability)
#       - DATABASE_URL (connection to persistent storage)
#       - STELLAR_RPC_URL (connection to blockchain)
# 
#   OPTIONAL
#     Variables that may be omitted. Use defaults if not provided.
#     Examples:
#       - LOG_LEVEL (defaults to "info")
#       - REDIS_CONNECT_TIMEOUT (defaults to 5000 ms)
#       - CORS_ALLOWED_ORIGINS (uses env-specific defaults when unset)
# 
# CONFIGURATION TYPE VALIDATION:
# 
#   Enum Types (string choices)
#     Values constrained to a predefined list of strings.
#     Examples:
#       - NODE_ENV: "development" | "test" | "production"
#       - LOG_LEVEL: "debug" | "info" | "warn" | "error"
#     Invalid values cause startup failure with clear error message.
# 
#   Integer Types (whole numbers)
#     Values must be positive integers within optional bounds.
#     Examples:
#       - PORT: positive integer, range 1-65535
#       - ORACLE_POLL_INTERVAL_MS: positive integer, range 5000-3600000
#     Non-integer or out-of-range values cause startup failure.
# 
#   URL Types (connection strings)
#     Values must be valid URLs with specific schemes.
#     Examples:
#       - DATABASE_URL: must use postgresql:// or postgres:// scheme
#       - REDIS_URL: must use redis:// or rediss:// scheme
#     Invalid URLs cause startup failure with clear error message.
# 
#   String Types (free-form text)
#     Values are strings with minimal validation beyond type checking.
#     Examples:
#       - SERVICE_NAME (any non-empty string)
#       - REDIS_KEY_PREFIX (any string, commonly with colon suffix)
#     Empty strings are rejected unless explicitly allowed.