fix(#610): remove orphaned EventProcessor; add DuplicateStats to idempotency

.dockerignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+.git
+.github
+.vscode
+*.md
+!README.md
+coverage
+tests
+**/*.test.ts
+.env
+.env.local
+notes
+src/generated

.env.example

@@ -1,13 +1,291 @@
+# =============================================================================
+# 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.