.env.example

# ─── Database ────────────────────────────────────────────────────────────────
# PostgreSQL connection string used by Prisma.
# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
# Leave as-is for local Docker Compose (see docker-compose.yml).
DATABASE_URL=postgresql://vortex:vortex@localhost:5432/vortex?schema=public

# ─── Server ──────────────────────────────────────────────────────────────────
# development | production | test
NODE_ENV=development
# Port the relay API + WebSocket feed listen on
PORT=4000
# Runtime mode. Production requires SOROBAN_SIGNING_KEY and an explicit
# ONCHAIN_DRY_RUN (see below); development and test default to the safest
# values. Valid: development | production | test
NODE_ENV=development

# ─── Stellar ─────────────────────────────────────────────────────────────────
# Network to operate against: testnet | futurenet | mainnet
STELLAR_NETWORK=testnet
ETHEREUM_RPC_URL=
ETHEREUM_ESCROW_ADDRESS=
BASE_RPC_URL=
BASE_ESCROW_ADDRESS=
POLYGON_RPC_URL=
POLYGON_ESCROW_ADDRESS=
ARBITRUM_RPC_URL=
ARBITRUM_ESCROW_ADDRESS=
OPTIMISM_RPC_URL=
OPTIMISM_ESCROW_ADDRESS=
AVALANCHE_RPC_URL=
AVALANCHE_ESCROW_ADDRESS=
EVM_RPC_ALLOWLIST=
# Soroban RPC endpoint (single-URL fallback — used when SOROBAN_RPC_URLS is unset)
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# Multi-endpoint RPC pool (#393): comma-separated URLs with optional weights.
# Format: "https://url1,https://url2@2"  (@2 = weight 2 = twice as likely to be selected)
# When set, SOROBAN_RPC_URLS takes precedence over SOROBAN_RPC_URL.
SOROBAN_RPC_URLS=
# Archival RPC URL for deep-history event backfill (#391).
# Leave blank to fall back to SOROBAN_RPC_URL for backfills within the retention window.
ARCHIVAL_RPC_URL=
# Horizon API endpoint (for account/balance queries)
HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_SIGNER_SECRET_KEY=

# Deployed contract IDs (leave blank until deployed)
SETTLEMENT_CONTRACT_ID=
SOLVER_REGISTRY_CONTRACT_ID=

# ─── Treasury ────────────────────────────────────────────────────────────────
# Stellar public key of the treasury account (fee accumulator)
TREASURY_ADDRESS=

# Secret key for the backend's own Soroban signer, used to submit on-chain
# writes (settlement, slashing). A Stellar secret seed: starts with "S",
# 56 base32 characters. Leave blank in development/test — no write path runs
# without it. REQUIRED in production (NODE_ENV=production), and validated
# against that format so it can never silently default to a placeholder.
#
# Local dev: generate a throwaway TESTNET-only keypair, do not reuse it
# anywhere real, and never commit a filled-in value:
#   npx @stellar/stellar-cli keys generate local-dev --network testnet
#   npx @stellar/stellar-cli keys show local-dev
# or, ad hoc, via the SDK:
#   node -e "console.log(require('@stellar/stellar-sdk').Keypair.random().secret())"
# Fund it on testnet with Friendbot before use:
#   curl "https://friendbot.stellar.org/?addr=<PUBLIC_KEY_FROM_ABOVE>"
SOROBAN_SIGNING_KEY=

# ─── Solver bot (scripts/solver-bot.ts) ─────────────────────────────────────
# Secret key for the reference solver bot — used to sign WS auth messages and
# REST request bodies (accept / fill). A Stellar secret seed (starts with "S").
# If unset, the bot runs in anonymous read-only mode (issue #121).
SOLVER_SECRET=
SOLVER_ADDRESS=
SOLVER_CHAINS=stellar,ethereum,base,polygon,arbitrum,optimism,avalanche

# ─── Persistence adapter selection ──────────────────────────────────────────
# Which repository adapter backs intents and solvers.
#   memory (default) — in-process Maps, no database required
#   prisma           — PostgreSQL via Prisma (staging / production)
# INTENTS_PERSISTENCE is a deprecated alias for INTENTS_STORE (issue #404).
INTENTS_PERSISTENCE=memory
ALLOW_LEGACY_STELLAR_SIGNATURES=false
SOLVERS_PERSISTENCE=memory
TOKENS_PERSISTENCE=memory

# CoinGecko-backed token USD pricing. Add aliases as {"SYMBOL":"coin-id"}.
PRICE_FEED_COIN_IDS={}
PRICE_FEED_API_KEY=
PRICE_FEED_REFRESH_INTERVAL_MS=60000
PRICE_FEED_CIRCUIT_BREAKER_THRESHOLD_PERCENT=50

# ─── On-chain writes ────────────────────────────────────────────────────────
# Register intents with the settlement contract on create().
ONCHAIN_INTENTS_ENABLED=false

# Simulate-only switch for every on-chain write path (invokeContract,
# slashSolver). When true, transactions are built and simulated but never
# broadcast. Defaults to true outside production; REQUIRED in production so a
# deployer must consciously choose simulate-only vs live writes. See
# docs/runbooks/onchain-cutover.md.
ONCHAIN_DRY_RUN=true

# Percentile of recent Soroban inclusion-fee stats used when estimating fees.
# One of: min mode p10 p20 p30 p40 p50 p60 p70 p80 p90 p95 p99 max
SOROBAN_FEE_PERCENTILE=p50

# ─── Intent retention ───────────────────────────────────────────────────────
# Days terminal (filled/cancelled/expired/slashed) intents are kept in the
# in-memory adapter, and how often the eviction sweep runs (ms). Set
# INTENT_RETENTION_DAYS=0 to disable retention-based eviction.
INTENT_RETENTION_DAYS=30
INTENT_RETENTION_SWEEP_MS=60000

# Time allowed to collect connected solver RFQ responses (1-1000 ms).
QUOTE_AUCTION_WINDOW_MS=300

# ─── CORS ────────────────────────────────────────────────────────────────────
# Comma-separated list of allowed origins for the frontend.
# Development default: "*"  (any origin allowed — convenient for local work)
# Production REQUIRED: must be an explicit origin, never "*"
#   e.g. CORS_ORIGIN=https://app.vortex.trade
# The app will refuse to start in production if this is "*" or unset.
CORS_ORIGIN=*

# ─── WebSocket ───────────────────────────────────────────────────────────────
# Maximum number of concurrent WebSocket connections accepted by the gateway.
# Connections beyond this limit are rejected with close code 1013 (try again later).
# Set to 0 to disable the cap (not recommended in production).
WS_MAX_CONNECTIONS=1000

# Optional backplane for multi-instance fan-out. Default is "memory".
# Set to "redis" to publish WS events through Redis pub/sub and maintain a
# globally-shared seq counter for replay semantics.
WS_BACKPLANE=memory
REDIS_URL=redis://localhost:6379

# WebSocket replay store: 'memory' (default) or 'redis'
WS_REPLAY_STORE=memory
# Maximum number of events to retain in the replay buffer
WS_REPLAY_MAX_COUNT=500
# Maximum age of events in milliseconds (optional, omit to disable)
# WS_REPLAY_MAX_AGE_MS=300000

# ── Read-path cache (issue #414) ───────────────────────────────────────────────
# memory (per process, default) | redis (shared store + pub/sub invalidation
# over REDIS_URL — use with more than one replica) | off
CACHE_DRIVER=memory
# TTL in seconds for aggregate read models (/stats, leaderboard). Entries are
# also invalidated on every intent/solver write, so this bounds staleness only
# for writes that bypass the service layer.
CACHE_TTL_SECONDS=15
# Random TTL spread (fraction of the TTL) so co-written keys do not expire together.
CACHE_TTL_JITTER=0.1

# ── Materialised stats views (issue #416) ──────────────────────────────────────
# auto (views when INTENTS_PERSISTENCE=prisma) | views | live
STATS_SOURCE=auto
# How often the worker runs REFRESH MATERIALIZED VIEW CONCURRENTLY.
STATS_VIEW_REFRESH_INTERVAL_MS=30000

# ── Durable idempotency keys (issue #418) ──────────────────────────────────────
# auto (Postgres when INTENTS_PERSISTENCE=prisma) | memory | prisma.
# Multi-replica deploys must use prisma so a retry on another replica replays.
IDEMPOTENCY_STORE=auto
# How long a completed response stays replayable (24 h).
IDEMPOTENCY_TTL_SECONDS=86400
# How long an in-progress key blocks duplicates (409) before a crashed
# request's claim may be retaken.
IDEMPOTENCY_LEASE_SECONDS=30
# Expired-key cleanup cadence.
IDEMPOTENCY_CLEANUP_INTERVAL_MS=3600000
# ─── Reconciler (#392) ───────────────────────────────────────────────────────
# Seconds a non-terminal intent must be stale (no ingestion update) before the
# reconciler reads its state from the settlement contract. Default: 300 (5 min).
RECONCILE_STALE_SECONDS=300

# ─── Soroban Fee & Channel Pool ───────────────────────────────────────────────
# Fee percentile used when estimating Soroban inclusion fees.
SOROBAN_FEE_PERCENTILE=p50

# Maximum fee in stroops for fee-bump escalation (#388).
# Default 1_000_000 stroops (0.1 XLM). Raise for busy mainnet periods.
SOROBAN_MAX_FEE_STROOPS=1000000

# Number of channel accounts in the pool (#387). Default 8.
CHANNEL_POOL_SIZE=8

# Comma-separated Stellar secret keys for channel accounts (#387).
# Generate with: tsx scripts/create-channels.ts
# NEVER commit real keys. Leave blank to disable channel pool.
CHANNEL_SECRET_KEYS=

# ─── Pluggable signer backend (issue #400) ───────────────────────────────────
# SIGNER_BACKEND selects the signing implementation:
#   "local"  (default) — key from SOROBAN_SIGNING_KEY / SOROBAN_SIGNING_KEY_FILE.
#                        Refused in NODE_ENV=production unless ALLOW_LOCAL_SIGNER_IN_PROD=true.
#   "vault"            — HashiCorp Vault Transit (ed25519); key never in process RAM.
#                        Requires VAULT_ADDR + VAULT_TOKEN.
SIGNER_BACKEND=local

# Required when SIGNER_BACKEND=vault:
VAULT_ADDR=
VAULT_TOKEN=
VAULT_TRANSIT_KEY_NAME=vortex-signer

# Emergency escape hatch — allow LocalKeypairSigner in production.
# Never set this on a real production deployment; migrate to SIGNER_BACKEND=vault.
ALLOW_LOCAL_SIGNER_IN_PROD=false
# ─── Resource-exhaustion limits (issue #476) ─────────────────────────────────
# Maximum JSON nesting depth accepted before the body is rejected with 400.
# Rejects stack-exhaustion attacks that craft deeply-nested payloads.
# Default: 10 (all real DTOs are flat or two levels deep; 10 gives ×3 margin).
JSON_MAX_DEPTH=10

# Maximum chain-filter values allowed in a single WS subscribe message.
# Default: 20 (2× the number of supported chains — generous for multi-chain bots).
WS_MAX_FILTER_CHAINS=20

# Maximum active subscriptions a single WS connection may hold.
# Default: 10
WS_MAX_SUBSCRIPTIONS=10

# Postgres statement_timeout (milliseconds) for standard route queries.
# Default: 5000 (5 s)
DB_QUERY_TIMEOUT_MS=5000

# Postgres statement_timeout (milliseconds) for batch-lookup queries.
# Default: 10000 (10 s)
DB_BATCH_QUERY_TIMEOUT_MS=10000

# Postgres statement_timeout (milliseconds) for stats/aggregate queries.
# Default: 15000 (15 s)
DB_STATS_QUERY_TIMEOUT_MS=15000

# Emergency kill-switch (issue #477)
# ---------------------------------
# Shared secret for the operator control plane at /api/v1/ops/killswitch.
# Leave empty to DISABLE those routes entirely (fail closed, never open).
# Required in production.
KILLSWITCH_OPERATOR_TOKEN=

# Redis URL for cross-replica pause propagation. Leave empty to rely on the
# database poll only, which still meets the 5 s budget. Defaults to REDIS_URL
# when WS_BACKPLANE=redis.
KILLSWITCH_REDIS_URL=

# Database change-probe interval (ms) that backstops Redis pub/sub.
# Worst-case propagation delay is roughly this value. 100-5000, default 2000.
KILLSWITCH_POLL_MS=2000

# Persistence backend for kill-switch state.
#   memory (default) - in-process, resets on restart. Dev/test only.
#   prisma           - Postgres, survives restarts. Required for a real
#                      multi-replica deployment.
KILLSWITCH_PERSISTENCE=memory
# ─── Observability ──────────────────────────────────────────────────────────
# Winston log level. One of: error warn info http verbose debug silly
LOG_LEVEL=debug
# Service name attached to every structured log line.
LOG_SERVICE_NAME=vortex-backend
# Console log format (issue #488): json = one schema record per line (what the
# OTel collector in ops/otel-collector parses), pretty = human-readable.
# Unset defaults to json in production and pretty elsewhere.
LOG_FORMAT=pretty
# Sentry DSN for error reporting. Leave blank to disable Sentry entirely.
SENTRY_DSN=

# ─── Metrics access control (issue #298) ─────────────────────────────────────
# Bearer token required for GET /metrics. Empty = endpoint disabled (403).
# Generate with: openssl rand -hex 32
# Required and validated (min 16 chars) in production.
METRICS_TOKEN=

# Optional log shipping to a central collector. Off by default so local dev and
# CI stay stdout-only. When enabled, LOG_SHIPPING_HOST is required.
LOG_SHIPPING_ENABLED=false
LOG_SHIPPING_HOST=
LOG_SHIPPING_PORT=514
LOG_SHIPPING_PATH=/
LOG_SHIPPING_SSL=false

# ─── Shadow-mode divergence monitor (issue #401) ────────────────────────────
# Runs on-chain *simulations* of every intent state transition in parallel with
# the authoritative off-chain path and reports where the two disagree, so the
# cutover runbook can quote a quantitative go/no-go threshold instead of a
# guess. Nothing is ever submitted: the only RPC call used is
# simulateTransaction, which never broadcasts, never signs and never charges a
# fee.
#
# Off by default — a sampled simulation is a real RPC call, so this is an
# explicit per-environment opt-in rather than something you discover you are
# paying for.
#
# Enable:
#   SHADOW_MODE_ENABLED=true
#
# Inspect the result:
#   curl http://localhost:4000/api/v1/admin/shadow-report?days=7
#   http://localhost:4000/metrics | grep vortex_shadow
#
# See docs/runbooks/onchain-cutover.md ("Shadow-mode go/no-go") for the
# threshold this has to clear before flipping ONCHAIN_DRY_RUN=false.
SHADOW_MODE_ENABLED=false

# Fraction of transitions to simulate, as a probability in [0, 1].
# 1 = every transition (recommended for a go/no-go soak: sampling makes the
# divergence rate a statistical estimate rather than a census).
SHADOW_SAMPLE_RATE=1

# Hard cap on queued observations. Beyond this, observations are dropped and
# counted (vortex_shadow_dropped_total) rather than queued — a slow or
# unreachable Soroban RPC degrades the monitor, never the request path.
SHADOW_QUEUE_MAX=256

# How many queued observations the background drain simulates concurrently.
SHADOW_CONCURRENCY=4

# Public key used as the transaction source for shadow simulations (strkey
# G...). Never signed, never submitted, never charged — it only has to be a
# valid address for the envelope. Optional: when empty the monitor reports
# "contract_unconfigured" instead of silently recording zero divergence.
#   npx @stellar/stellar-cli keys generate shadow-sim --network testnet
#   npx @stellar/stellar-cli keys show shadow-sim --public-key
SHADOW_SOURCE_ACCOUNT=
# ─── Governance / Protocol Parameters ────────────────────────────────────────
# On-chain governance parameters contract ID (Soroban contract address).
# When set, ProtocolParamsService reads fee bps, fill windows, deadlines,
# exposure ratio, and slash amount from the contract and exposes them via
# GET /api/v1/params.  Leave blank to use code/env defaults.
PARAMS_CONTRACT_ID=

# How often (ms) to poll the parameters contract.  Default: 30 000 (30 s).
# Lower values increase RPC load; raise in production if rate-limited.
PARAMS_POLL_INTERVAL_MS=30000
# ─── Leader election ─────────────────────────────────────────────────────────
# Set to true to enable Postgres advisory-lock based leader election so
# singleton workers (sweeper, event-ingestion) run on exactly one replica.
# Requires DATABASE_URL to point at a live Postgres instance.
# IMPORTANT: do not use PgBouncer in transaction-pooling mode for this;
# advisory locks are session-scoped and will be dropped when the connection
# is returned to the pool. Use a direct connection or session-mode pooling.
LEADER_ELECTION_ENABLED=false
# Heartbeat interval (ms). Default 5000 gives ≤ 15 s failover.
LEADER_ELECTION_HEARTBEAT_MS=5000

# ─── Background jobs (issue #494) ────────────────────────────────────────────
# api | worker | all — queue workers only run in "worker" or "all".
PROCESS_ROLE=all
# memory (single-process, dev/test) | bullmq (Redis-backed, uses REDIS_URL)
JOBS_DRIVER=memory
# Grace period for in-flight jobs on SIGTERM before they are returned to the queue.
JOBS_SHUTDOWN_TIMEOUT_MS=25000

# ─── Runtime feature flags (issue #495) ──────────────────────────────────────
# Change propagation across instances: memory (single instance) | redis
FLAGS_PUBSUB=memory
# Safety-net cache reload interval (ms)
FLAGS_REFRESH_MS=30000
# Break-glass pins that win over DB state, e.g. onchain-dry-run=true
FLAG_OVERRIDES=

# ─── Abuse detector (issues #604–#606) ───────────────────────────────────────
# Seed allowlist: addresses, exact IPs, key:<api-key>. Runtime entries live in
# Postgres and are managed via GET/POST/DELETE /api/v1/abuse/allowlist.
ABUSE_ALLOWLIST=
# Allowlist change propagation: memory | redis (empty follows FLAGS_PUBSUB)
ABUSE_ALLOWLIST_PUBSUB=
# Safety-net allowlist reload interval (ms); 0 disables the periodic reload
ABUSE_ALLOWLIST_REFRESH_MS=30000
# Raise one Sentry alert when an address or IP is blocked this many times in the window (0 disables)
ABUSE_BLOCK_ALERT_THRESHOLD=5
ABUSE_BLOCK_ALERT_WINDOW_SECONDS=600
# Captcha alternative to the PoW challenge: hcaptcha | turnstile | empty (disabled)
ABUSE_CAPTCHA_PROVIDER=
ABUSE_CAPTCHA_SECRET=
ABUSE_CAPTCHA_TIMEOUT_MS=3000

# ─── Admin RBAC ──────────────────────────────────────────────────────────────
# Comma-separated id:role:secret (role = admin | superadmin, secret >= 16 chars).
# Sent as the x-admin-key header (the secret part). Empty disables admin APIs.
ADMIN_API_KEYS=

# ─── Guardian emergency ingestion (issue #507) ───────────────────────────────
# Guardian / security-council contract ID. Leave blank to disable ingestion.
GUARDIAN_CONTRACT_ID=

# ─── Synthetic canary (issue #496) ───────────────────────────────────────────
# Canary user + solver addresses; excluded from public stats and leaderboards.
CANARY_ADDRESSES=

# Public anonymised datasets (docs/rfcs/0001)
# Master switch for the public dataset publication job.
DATASETS_ENABLED=false
# Hash user addresses with the rotating salt before export.
DATASETS_ANONYMIZE=true
# Base anonymisation salt. Required (>= 32 chars) when datasets are enabled
# and anonymisation is on; generate with `openssl rand -hex 32`.
DATASETS_SALT=
# How often the anonymisation salt rotates, in hours.
DATASETS_SALT_ROTATION_HOURS=24
# How many previous salt windows are retained for continuity.
DATASETS_SALT_RETENTION_WINDOWS=2
# Public bucket/prefix the published datasets live under.
DATASETS_PUBLIC_BUCKET=vortex-public-datasets
# Storage backend: local (writes to disk) | memory (tests only).
DATASETS_STORAGE=local
# Root directory for the local storage backend.
DATASETS_LOCAL_DIR=.datasets
# Optional comma-separated http(s) URLs POSTed the manifest after each
# publication (best-effort, retried, never fails the export). Deliveries go
# through HttpEgressService and are limited to WEBHOOK_ALLOWLIST when set.
DATASETS_WEBHOOK_URLS=
# Dedicated HMAC-SHA256 key (>= 32 chars) for the X-Vortex-Signature header.
# Required when DATASETS_WEBHOOK_URLS is set; never reuse SOROBAN_SIGNING_KEY.
DATASETS_WEBHOOK_SECRET=
# Widest range, in UTC days, the on-demand admin dataset export accepts.
DATASETS_EXPORT_MAX_DAYS=31

# Secrets Manager (issue #465)
# Provider: env | aws-secrets-manager | vault-kv
SECRETS_PROVIDER=env
# Poll interval for secret rotation (ms)
SECRETS_REFRESH_INTERVAL_MS=60000
# Extra secrets: comma-separated "name:envVar:required"
SECRETS_EXTRA=

# AWS Secrets Manager
AWS_SECRETS_MANAGER_PREFIX=
AWS_SECRETS_MANAGER_POLL_INTERVAL_MS=60000

# Vault KV
VAULT_KV_MOUNT=secret
VAULT_KV_PREFIX=vortex/
VAULT_KV_POLL_INTERVAL_MS=60000

# Extra secret env vars referenced by the default SecretConfig
JWT_SIGNING_KEY=
WEBHOOK_SECRET=
CHANNEL_KEY=

# Egress/SSRF Protection
EGRESS_TIMEOUT_MS=10000
EGRESS_MAX_REDIRECTS=3
EGRESS_MAX_BODY_SIZE_BYTES=10485760
SOROBAN_RPC_ALLOWLIST=soroban-testnet.stellar.org,soroban-rpc.stellar.org
WEBHOOK_ALLOWLIST=hooks.example.com,hooks.trusted.com
ORACLE_ALLOWLIST=oracle.trusted.io
# Oracle minDstAmount gates (issue #434). Slippage/premium in basis points.
MAX_USER_SLIPPAGE_BPS=100
MAX_PREMIUM_BPS=50
ORACLE_FAIL_OPEN_MAX_USD=100
ORACLE_MAX_STALENESS_MS=60000
# Public anonymised datasets (RFC 0001). Disabled until an operator opts in.
DATASETS_ENABLED=false
DATASETS_ANONYMIZE=true
DATASETS_SALT=
DATASETS_SALT_ROTATION_HOURS=24
DATASETS_SALT_RETENTION_WINDOWS=2
DATASETS_PUBLIC_BUCKET=vortex-public-datasets
DATASETS_STORAGE_KIND=memory
DATASETS_LOCAL_DIR=./data/datasets
# ─── WS gateway hardening (issue #455) ───────────────────────────────────────
# Inbound frames larger than this close the socket (1009).
WS_MAX_PAYLOAD_BYTES=16384
# Concurrent WS connections per client IP (0 = unlimited).
WS_MAX_CONNECTIONS_PER_IP=20
# Trusted reverse-proxy hops for X-Forwarded-For (0 = socket address only).
WS_TRUST_PROXY_HOPS=0
# Inbound token bucket per connection; repeat violators are disconnected.
WS_RATE_LIMIT_PER_SEC=10
WS_RATE_LIMIT_BURST=20
WS_RATE_LIMIT_MAX_VIOLATIONS=5
# Outbound backpressure: messages held per slow consumer, socket buffer
# threshold (bytes), and what to do when the queue is full.
WS_OUTBOUND_QUEUE_MAX=1000
WS_OUTBOUND_BUFFER_BYTES=1048576
WS_SLOW_CONSUMER_POLICY=drop_oldest

# ─── WS graceful shutdown (Activity 2) ───────────────────────────────────────
# Time (ms) to drain connections on SIGTERM before forceful shutdown.
# Should align with Kubernetes terminationGracePeriodSeconds (default 30s).
WS_DRAIN_TIMEOUT_MS=25000

# HS256 secret for solver JWTs from the SEP-10 auth flow (#442); >= 32 chars.
# Empty disables JWT auth on the WS gateway.
AUTH_JWT_SECRET=

# ─── SEP-10 solver authentication (issue #442) ────────────────────────────────
# Home domain bound into the challenge (`<domain> auth` manage-data operation);
# the same value is used for the challenge's `web_auth_domain` operation.
SEP10_HOME_DOMAIN=localhost
# Ed25519 PKCS#8 private key signing the 15-minute session JWTs — REQUIRED in
# production (generate: openssl genpkey -algorithm ed25519). Must be distinct
# from STELLAR_SIGNER_SECRET_KEY; empty uses an ephemeral dev-only key.
SEP10_JWT_SIGNING_KEY=
# Comma-separated G-addresses issued role=admin. Empty = nobody.
SEP10_ADMIN_ACCOUNTS=
# Single-use challenge nonce store: memory | redis. Use redis in multi-replica
# deployments so a captured challenge cannot be replayed on another replica.
SEP10_NONCE_STORE=memory

# ─── API keys & distributed rate limiting (issue #441) ─────────────────────────
# How often (ms) the local rate-limiter fallback prunes expired window entries.
# Only relevant during a Redis outage; keeps the fallback map bounded.
RATE_LIMIT_LOCAL_PRUNE_MS=60000
# Redis URL for the shared rate-limit window. Leave empty to force the bounded
# local limiter (the limit is still enforced, just per process).
RATE_LIMIT_REDIS_URL=

# ─── Scoped solver credentials (issue #443) ───────────────────────────────────
# Cross-replica transport for credential revocation invalidation:
# memory (single instance) | redis (pub/sub, uses REDIS_URL).
CREDENTIAL_REVOCATION_PUBSUB=memory

# ─── SSE intent feed (issue #433) ─────────────────────────────────────────────
# Heartbeat comment interval (ms) for GET /api/v1/stream/intents.
SSE_HEARTBEAT_MS=15000
# Maximum buffered output bytes per SSE client before it is disconnected.
SSE_MAX_BUFFER_BYTES=1048576

# ─── Public anonymised datasets ──────────────────────────────────────────────
DATASETS_ENABLED=false
DATASETS_ANONYMIZE=true
DATASETS_SALT=
DATASETS_SALT_ROTATION_HOURS=24
DATASETS_SALT_RETENTION_WINDOWS=2
DATASETS_PUBLIC_BUCKET=
DATASETS_STORAGE_KIND=memory
DATASETS_LOCAL_DIR=

# ─── Health probes (issue #492) ──────────────────────────────────────────────
# Roles served by this process (api, ws, worker); readiness checks follow them.
SERVICE_ROLES=api,ws,worker
HEALTH_CHECK_INTERVAL_MS=5000
# Readiness hysteresis: failures before not-ready, successes before ready again.
HEALTH_READY_FAILURE_THRESHOLD=3
HEALTH_READY_SUCCESS_THRESHOLD=2
# Liveness fails when event-loop delay exceeds this.
HEALTH_EVENT_LOOP_MAX_LAG_MS=1000
# Soroban RPC endpoints for the quorum check (default: SOROBAN_RPC_URL).
SOROBAN_RPC_HEALTH_URLS=
# Fee rules and integrator referrals (issue #438). JSON arrays; empty uses the built-in 5 bps default.
FEE_RULES_JSON=[]
FEE_REFERRALS_JSON=[]

# Low-frequency scan that catches deadline jobs the queue did not run (issue #437).
SAFETY_SWEEP_INTERVAL_MS=300000

# JSON map of EVM chain name to HTTPS JSON-RPC URL for admin token verification.
# Example: {"ethereum":"https://ethereum.example/rpc","base":"https://base.example/rpc"}
EVM_RPC_URLS={}
# Public anonymised datasets (RFC 0001). Disabled until an operator opts in.
DATASETS_ENABLED=false
DATASETS_ANONYMIZE=true
DATASETS_SALT=
DATASETS_SALT_ROTATION_HOURS=24
DATASETS_SALT_RETENTION_WINDOWS=2
DATASETS_PUBLIC_BUCKET=vortex-public-datasets
DATASETS_STORAGE_KIND=memory
DATASETS_LOCAL_DIR=./data/datasets
# ─── Intents store (issue #404) ──────────────────────────────────────────────
# memory | dual | postgres — supersedes INTENTS_PERSISTENCE above.
#   memory   — in-process only; everything is lost on restart (dev/test)
#   dual     — writes to both memory and Postgres, reads from memory, and a
#              consistency verifier reports mismatches (migration phase)
#   postgres — Postgres is the only store (production)
# See docs/runbooks/intents-store-migration.md before changing this in a
# deployed environment. Leave unset to fall back to INTENTS_PERSISTENCE.
INTENTS_STORE=memory
# How often (ms) the dual-write consistency verifier compares the two stores.
INTENTS_VERIFY_INTERVAL_MS=60000

# ─── Source-chain deposit verification (issue #403) ──────────────────────────
# When true, intents from EVM chains stay hidden from solvers (srcVerified=false)
# until the escrow's Deposited log is found at the chain's confirmation depth.
# See docs/runbooks/evm-deposit-verification.md.
EVM_DEPOSIT_VERIFICATION_ENABLED=false
# JSON maps keyed by chain: ethereum | base | polygon | arbitrum | optimism | avalanche
#   EVM_RPC_URLS={"ethereum":"https://eth.example","base":"https://base.example"}
EVM_RPC_URLS=
EVM_ESCROW_ADDRESSES=
# Shortfall allowed for fee-on-transfer tokens, in basis points (0 = exact amount).
EVM_TRANSFER_FEE_TOLERANCE_BPS=0
# Blocks searched for the Deposited log when an intent has no srcTxHash.
EVM_LOG_LOOKBACK_BLOCKS=10000

# ── Transactional outbox relay (issue #396) ──────────────────────────────────
OUTBOX_RELAY_ENABLED=true
OUTBOX_RELAY_INTERVAL_MS=2000
OUTBOX_RELAY_BATCH_SIZE=10
OUTBOX_MAX_ATTEMPTS=8
# Must exceed the signed transaction's 30 s time bound.
OUTBOX_LEASE_SECONDS=120

# ── Slashing saga (issue #397) ───────────────────────────────────────────────
SLASH_CHALLENGE_WINDOW_SECONDS=600
SLASH_CLOCK_SKEW_TOLERANCE_SECONDS=30
SLASH_MAX_SUBMIT_ATTEMPTS=5

# Maximum number of concurrent WebSocket connections accepted by the gateway.
# Connections beyond this limit are rejected with close code 1013 (try again later).
# Set to 0 to disable the cap (not recommended in production).
WS_MAX_CONNECTIONS=1000

# Optional backplane for multi-instance fan-out. Default is "memory".
# Set to "redis" to publish WS events through Redis pub/sub and maintain a
# globally-shared seq counter for replay semantics.
WS_BACKPLANE=memory
REDIS_URL=redis://localhost:6379

# Public anonymised datasets (RFC 0001). Disabled until an operator opts in.
DATASETS_ENABLED=false
DATASETS_ANONYMIZE=true
DATASETS_SALT=
DATASETS_SALT_ROTATION_HOURS=24
DATASETS_SALT_RETENTION_WINDOWS=2
DATASETS_PUBLIC_BUCKET=vortex-public-datasets
DATASETS_STORAGE_KIND=memory
DATASETS_LOCAL_DIR=./data/datasets


# ─── Solver reputation (issue #444) ──────────────────────────────────────────
# Weights for each reputation sub-component. Sum must be exactly 1.0 in production;
# dev/test renormalises any valid positive set so local experimentation doesn't
# prevent boot.
REP_WEIGHT_FILL_RATE=0.35
REP_WEIGHT_LATENCY=0.15
REP_WEIGHT_SLASHES=0.25
REP_WEIGHT_QUOTE_HONOUR=0.15
REP_WEIGHT_VOLUME=0.10
# Shared exponential-decay half-life (seconds) for all events.
# Default: 30 days — scores dominated by the last ~1 month of activity.
REP_DECAY_HALFLIFE_SECONDS=2592000
# Beta-distribution priors for the Bayesian cold-start lower bound on fill rate.
# (α=4, β=1) ≈ prior mean 80%, 2.5% lower bound ~37%.
REP_BAYES_ALPHA=4
REP_BAYES_BETA=1
# Volume-component knee in USD-equivalent notional; $100k default.
REP_VOLUME_LAMBDA_USD=100000
# How many trailing days of daily snapshots the /reputation endpoint exposes (1..365).
REP_HISTORY_WINDOW_DAYS=30
# ─── Read replicas (#411) ─────────────────────────────────────────────────────
# Comma-separated read-replica Postgres connection strings.
# Leave blank to route all reads to the primary.
# Example: postgresql://vortex:vortex@replica1:5432/vortex?schema=public,postgresql://vortex:vortex@replica2:5432/vortex?schema=public
DATABASE_REPLICA_URLS=
# Maximum replica replication lag (ms) before a replica is bypassed for reads.
# Default: 5000 (5 s). Requests that arrive with a recent-write token always use the primary.
MAX_REPLICA_LAG_MS=5000

# ─── Cursor HMAC secret (#412) ────────────────────────────────────────────────
# HMAC-SHA256 key used to sign opaque pagination cursors.
# Required in production — generate with: openssl rand -hex 32
CURSOR_HMAC_SECRET=dev-cursor-hmac-secret-do-not-use-in-prod

# ─── Cold-storage archival (#413) ─────────────────────────────────────────────
# Enable the daily archival job that moves terminal intents to Parquet in S3.
ARCHIVAL_ENABLED=false
# S3 bucket name. Works with MinIO locally (docker compose --profile archival up).
ARCHIVAL_BUCKET_NAME=vortex-archives
# S3-compatible endpoint URL. Leave blank for AWS S3 in production.
# For local MinIO: http://localhost:9000
ARCHIVAL_S3_ENDPOINT=
ARCHIVAL_S3_REGION=us-east-1
ARCHIVAL_S3_ACCESS_KEY_ID=
ARCHIVAL_S3_SECRET_ACCESS_KEY=
# Intents older than this many days (from their terminal transition) are eligible for archival.
ARCHIVAL_RETENTION_DAYS=30
# S3 key prefix for date partitions. Written as: <prefix>YYYY-MM-DD/
ARCHIVAL_PARTITION_PREFIX=date=
# Maximum rows written to a single Parquet file before rotating to a new file.
ARCHIVAL_MAX_ROWS_PER_FILE=100000

# ── intent_audit_log monthly partitions (issue #407) ─────────────────────────
# The leader creates partitions AUDIT_PARTITION_PREMAKE_MONTHS ahead. With
# AUDIT_RETENTION_MONTHS > 0, older partitions are detached and exported to the
# archival bucket (ARCHIVAL_*), and kept as tables unless
# AUDIT_RETENTION_DROP_AFTER_EXPORT=true. See RUNBOOK_BACKUP_RESTORE.md.
AUDIT_PARTITION_MAINTENANCE_ENABLED=true
AUDIT_PARTITION_INTERVAL_MS=21600000
AUDIT_PARTITION_PREMAKE_MONTHS=3
AUDIT_RETENTION_MONTHS=0
AUDIT_RETENTION_DROP_AFTER_EXPORT=false

# ── Contract-state TTL keeper (issue #395) ───────────────────────────────────
# Extends the TTL of protocol-owned persistent entries (contract instances and
# WASM code, active intents, active solver bonds) before they archive. Submits
# paid ExtendFootprintTTL transactions, so it is off by default. Runs on the
# elected leader only. Ledger counts assume ~5 s ledgers (17,280 per day).
TTL_KEEPER_ENABLED=false
TTL_KEEPER_INTERVAL_MS=3600000
TTL_KEEPER_THRESHOLD_LEDGERS=120960
TTL_KEEPER_EXTEND_TO_LEDGERS=518400
TTL_KEEPER_DAILY_BUDGET_STROOPS=50000000
TTL_KEEPER_MAX_KEYS_PER_TX=20
# Contract DataKey variant names used to derive intent / bond ledger keys.
TTL_KEEPER_INTENT_KEY_VARIANT=Intent
TTL_KEEPER_BOND_KEY_VARIANT=Bond
# ── Epoch → timestamptz migration (issue #409) ───────────────────────────────
# Where epoch timestamps are read from while both columns exist. Switch to
# `timestamptz` only after `npm run db:backfill-timestamps -- --verify` reports
# zero rows out of sync. Writes always go to both columns.
TIMESTAMP_READ_SOURCE=epoch
# ─── Destination preflight (issue #439) ─────────────────────────────────────
# Check the user's Stellar account exists and can receive minDstAmount of the
# destination asset (trustline, authorization, remaining limit) before an
# intent is listed and again at accept time.
DST_PREFLIGHT_ENABLED=false
# Let creation through (logged) when Horizon is unreachable.
DST_PREFLIGHT_FAIL_OPEN=true
DST_PREFLIGHT_CACHE_TTL_MS=30000

# ─── Webhooks (issue #432) ──────────────────────────────────────────────────
# memory (default, dev/test) | prisma (durable; required for multi-replica)
WEBHOOKS_PERSISTENCE=memory
WEBHOOK_TIMEOUT_MS=5000
WEBHOOK_MAX_RETRIES=5
WEBHOOK_BACKOFF_BASE_MS=30000
WEBHOOK_DISABLE_AFTER_FAILURES=10
WEBHOOK_CONCURRENCY=16
# Permit http:// and private-network targets. Local development only;
# rejected when NODE_ENV=production.
WEBHOOK_ALLOW_INSECURE_URLS=false

# ─── Partial fills (issue #427) ─────────────────────────────────────────────
PARTIAL_FILLS_ENABLED=true
# The settlement contract has no partial-fill entrypoints yet; keep false.
PARTIAL_FILLS_ONCHAIN_ENABLED=false