Xelma-Backend/.env.example at main · TevaLabs/Xelma-Backend · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
PORT=3001

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/xelma

# Auth — wallet challenge (SEP-10-style domain binding for anti-phishing)
JWT_SECRET=change-me
# Domain shown in the wallet signature prompt. Falls back to CLIENT_URL hostname, then "xelma.io".
# Set this to your production domain (e.g. xelma.io, app.xelma.io) so wallets display the correct origin.
# AUTH_DOMAIN=xelma.io
# Optional home domain (SEP-10 home_domain). Defaults to AUTH_DOMAIN when unset.
# HOME_DOMAIN=xelma.io
# Legacy alias also accepted: WEB_AUTH_DOMAIN=xelma.io

# Soroban / Stellar — prefer SOROBAN_* (canonical). Aliases also work:
#   CONTRACT_ID      → SOROBAN_CONTRACT_ID
#   STELLAR_RPC_URL  → SOROBAN_RPC_URL
# When both a canonical name and its alias are set, SOROBAN_* wins.
SOROBAN_CONTRACT_ID=
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_NETWORK=testnet
SOROBAN_ADMIN_SECRET=
SOROBAN_ORACLE_SECRET=
# Optional aliases (hackathon / older Render templates):
# STELLAR_RPC_URL=https://soroban-testnet.stellar.org
# CONTRACT_ID=
# Safety profile: "production" or "demo" (default).
# production — fail-closed: BET_STUB_MODE forbidden, SOROBAN_FAIL_CLOSED forced true,
#             Soroban secrets required. Refuses to boot if money-path invariants are violated.
# demo       — fail-open: stub mode allowed, secrets optional. Safe for local dev and demos.
SAFETY_PROFILE=demo

# Money-path chain verification policy (#401).
# false (default) = fail-open: log and continue with DB-only on Soroban failure (demos/local).
# true = fail-closed: abort bet/resolve when chain verification fails.
# Production / real-stakes deployments MUST set SOROBAN_FAIL_CLOSED=true
# (enforced by SAFETY_PROFILE=production preflight).
SOROBAN_FAIL_CLOSED=false

# Vendored @tevalabs/xelma-bindings skew check (see docs/bindings-upgrade.md).
# off    = skip the check entirely
# warn   = log the mismatch and start anyway
# strict = refuse to start when vendor/xelma-bindings drifts from bindings.pin.json
# Unset (default): strict in production when a contract ID is set and
# BET_STUB_MODE is not true, or for any fail-closed deployment; warn otherwise.
# BINDINGS_CHECK=strict

# Price oracle providers (primary: CoinGecko, fallback: CoinCap)
COINGECKO_API_URL=https://api.coingecko.com/api/v3/simple/price?ids=stellar&vs_currencies=usd
COINGECKO_MULTI_PRICE_URL=https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,stellar&vs_currencies=usd
COINCAP_API_URL=https://api.coincap.io/v2/assets/stellar
COINCAP_MULTI_PRICE_URL=https://api.coincap.io/v2/assets?ids=bitcoin,ethereum,stellar

# Oracle auto-resolve interval (seconds)
ORACLE_RESOLVE_INTERVAL_SECONDS=30

# Price oracle fetch tuning + staleness guard (#229)
#  - POLLING_INTERVAL_MS:    how often the background poller fetches a price
#  - REQUEST_TIMEOUT_MS:     per-request network timeout
#  - MAX_RETRIES:            retry attempts per provider before failing over
#  - STALENESS_THRESHOLD_MS: a price older than this is "stale". Round
#                            resolution (cron AND the manual oracle resolve
#                            route) is REFUSED while the feed is stale, so the
#                            platform never settles against a frozen price.
#                            MUST be greater than ORACLE_POLLING_INTERVAL_MS or
#                            the server refuses to start.
ORACLE_POLLING_INTERVAL_MS=10000
ORACLE_REQUEST_TIMEOUT_MS=5000
ORACLE_MAX_RETRIES=3
ORACLE_STALENESS_THRESHOLD_MS=60000

# Force database-only active round reads for local development
ROUNDS_MOCK_MODE=false

# Simulation QA endpoint (POST /api/rounds/:id/simulate) — Issue #553.
# false (default) = LOCKED DOWN: the endpoint returns 403 in every environment,
# including development and test. true = enabled; the endpoint then requires an
# ADMIN bearer token. Never set this on a production build.
ENABLE_SIMULATION=false

# Round Scheduler
ROUND_SCHEDULER_ENABLED=false
ROUND_SCHEDULER_MODE=UP_DOWN

# Bet Mode: true = stub mode (records intent without on-chain calls), false = on-chain via Soroban
BET_STUB_MODE=true

# Redis (required for distributed idempotency locks, scheduler leader election,
# and the Socket.IO adapter).
# Local default matches `docker compose up` (see docker-compose.yml).
#
# MULTI-INSTANCE: every replica MUST share one Redis, or cron jobs (round
# creation, oracle resolve, retention) will run on every replica at once.
# See docs/multi-instance-deployment.md.
REDIS_URL=redis://localhost:6379

# Scheduler leader election (Issue #601). When REDIS_URL is unset, locked cron
# jobs run behind an in-process guard with a warning, so a single-instance
# deploy still works. Set this to true to refuse to run them without Redis.
SCHEDULER_LOCK_REQUIRED=false

# Distributed idempotency lock tuning (Issue #493) — bet requests carrying an
# Idempotency-Key FAIL CLOSED (HTTP 503) when Redis is unreachable. No fallback.
IDEMPOTENCY_LOCK_TTL_SECONDS=30
IDEMPOTENCY_LOCK_ACQUIRE_TIMEOUT_MS=10000
IDEMPOTENCY_LOCK_RETRY_DELAY_MS=100

# Rate limits (demo defaults). Production may raise read limits; keep bet/prediction tight.
# RATE_LIMIT_API_MAX=100
# RATE_LIMIT_API_WINDOW_MS=60000
# RATE_LIMIT_WRITE_MAX=20
# RATE_LIMIT_WRITE_WINDOW_MS=60000
# RATE_LIMIT_BET_MAX=5
# RATE_LIMIT_BET_WINDOW_MS=60000
# RATE_LIMIT_PREDICTION_MAX=10
# RATE_LIMIT_PREDICTION_WINDOW_MS=60000

# Soroban circuit breaker + in-flight cap (#500)
# Demo: trip quickly (3 failures / 30s) and cap concurrent RPC at 8.
# Production: keep the same until a live load run says otherwise; never raise
# the in-flight cap without measuring p95 and RPC errors first.
# SOROBAN_BREAKER_FAILURE_THRESHOLD=3
# SOROBAN_BREAKER_OPEN_BACKOFF_MS=30000
# SOROBAN_MONEY_PATH_MAX_IN_FLIGHT=8

# Load / performance test harness (#21, #152, #500)
# LOAD_TEST_PREDICTION_CONCURRENCY=10
# LOAD_TEST_PREDICTION_ITERATIONS=30
# LOAD_TEST_PREDICTION_MIN_RPS=5
# LOAD_TEST_PREDICTION_P95_MS=500
# LOAD_TEST_BET_CONCURRENCY=8
# LOAD_TEST_BET_ITERATIONS=16
# LOAD_TEST_BET_MIN_RPS=3
# LOAD_TEST_BET_P95_MS=500
# LOAD_TEST_IDEMPOTENCY_CONCURRENCY=8
# LOAD_TEST_IDEMPOTENCY_ITERATIONS=16
# LOAD_TEST_ROUNDS_CONCURRENCY=10
# LOAD_TEST_ROUNDS_ITERATIONS=30
# LOAD_TEST_ROUNDS_MIN_RPS=5
# LOAD_TEST_ROUNDS_P95_MS=150
# LOAD_TEST_OVERLOAD_BET_BURST=12
# LOAD_TEST_WS_CLIENTS=20