.env.example

NODE_ENV=development
PORT=3000
# Optional path every route is served under, e.g. api/v1 (GET /health stays
# at the root). Leave empty to serve from /. See docs/CONFIGURATION.md.
API_PREFIX=
CORS_ORIGINS=http://localhost:3001
# Pino logging level: fatal, error, warn, info, debug, trace, silent
LOG_LEVEL=debug

# Optional distributed tracing (OTLP/HTTP). See docs/TRACING.md.
OTEL_TRACING_ENABLED=false
# OTEL_SERVICE_NAME=stellar-tickets-backend
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

# Express `trust proxy`: unset/false (direct connections), a hop count such as
# 1 behind a single load balancer, or a comma-separated list of proxy IPs/CIDR
# ranges. See docs/DEPLOYMENT.md.
TRUST_PROXY=

# postgresql://user:password@host:5432/db
DATABASE_URL=

# Where secrets are read from: env (default), file, or custom. See the
# "Secret providers" section of docs/CONFIGURATION.md.
SECRETS_PROVIDER=env

# Must be at least 32 characters. In production it must also not be a
# placeholder and must have 10+ distinct characters — use e.g.
# `openssl rand -base64 48`. Required when SECRETS_PROVIDER=env.
JWT_SECRET=
# Path to a file holding the JWT secret. Required when SECRETS_PROVIDER=file.
# JWT_SECRET_FILE=/run/secrets/jwt_secret

# Soroban RPC endpoint (e.g. https://soroban-testnet.stellar.org). Boot fails
# if the URL names a different network than STELLAR_NETWORK, and must be
# https when STELLAR_NETWORK=mainnet.
SOROBAN_RPC_URL=
STELLAR_NETWORK=testnet

# Ticket prices are in this settlement token's smallest unit. These display
# defaults must match the PaymentToken deployed in the ticketing contract.
SETTLEMENT_ASSET_CODE=XLM
SETTLEMENT_ASSET_DECIMALS=7

# Deployed StellarTickets/blockchain `ticketing` contract address (C...)
TICKETING_CONTRACT_ID=

# Optional: enables the /metrics endpoint, protected by this bearer token.
# Use a randomly generated value of at least 32 characters.
# METRICS_TOKEN=

# Soroban transaction time-bound set on every build*Tx envelope, in seconds.
# TRANSACTION_BUILD_TIMEOUT_SECONDS=300
# How long submitSignedTransaction polls getTransaction for a result before
# giving up, in seconds.
# TRANSACTION_POLL_TIMEOUT_SECONDS=15

# Platform hot wallet used ONLY as a disposable source account for read-only
# contract simulations (verify_ticket, get_event). Never used to sign a
# write, and never a user's key.
PLATFORM_SIGNER_SECRET=

# Offline gate verification. See docs/OFFLINE_VERIFICATION.md for how to
# generate a keypair and how rotation works.
OFFLINE_SIGNING_KEY_ID=2026-01
# PEM-encoded Ed25519 private key, one line with \n escapes or a quoted
# multi-line value.
OFFLINE_SIGNING_PRIVATE_KEY=
# JSON map of every key id a scanner should still accept: {"2026-01":"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"}
OFFLINE_SIGNING_PUBLIC_KEYS=

# Ticket verification scan abuse prevention. Both have defaults if unset —
# see docs/RATE_LIMITING.md.
SCAN_RATE_LIMIT_MAX=10
SCAN_RATE_LIMIT_WINDOW_MS=60000

# Where rate-limit counters are stored: `memory` (default, per-process) or
# `redis` (shared across instances — required for multi-instance deployments).
# `redis` needs `npm install ioredis` and REDIS_URL. See docs/RATE_LIMITING.md.
RATE_LIMIT_STORE=memory
# REDIS_URL=redis://localhost:6379

# Where cached entries are stored: `memory` (default, per-process) or `redis`
# (shared across instances). `redis` needs `npm install ioredis` and REDIS_URL.
# See docs/CACHING.md.
CACHE_DRIVER=memory
# CACHE_TTL_SECONDS=60

# Outbound webhook delivery queue (BullMQ). Disabled by default. Enabling it
# needs `npm install bullmq` and REDIS_URL (Redis with maxmemory-policy
# noeviction). See docs/WEBHOOKS.md.
WEBHOOK_QUEUE_ENABLED=false
# WEBHOOK_QUEUE_ATTEMPTS=5
# WEBHOOK_QUEUE_BACKOFF_MS=5000

# Cron jobs registered through SchedulerModule run unless this is `false`.
# See docs/SCHEDULER.md.
SCHEDULER_ENABLED=true

# Maximum active resale listings per user (soft limit)
MAX_ACTIVE_RESALE_LISTINGS_PER_USER=5

# Maximum number of recipients in a single POST /tickets/issue-batch request.
# Defaults to 50 when unset.
ISSUE_BATCH_MAX_SIZE=50

# Rotating QR tokens (GET /tickets/:ticketId/qr-token). Both have defaults if
# unset — see docs/API.md. TTL is how long a freshly issued token lasts;
# CLOCK_SKEW is extra grace after expiry for scanners whose clock runs behind.
QR_TOKEN_TTL_SECONDS=30
QR_TOKEN_CLOCK_SKEW_SECONDS=5

# Pending transaction (build -> confirm intent) retention and cleanup cadence.
PENDING_TX_RETENTION_MINUTES=60
PENDING_TX_CLEANUP_INTERVAL_MINUTES=15
# Ticket DB status reconciliation cadence, in minutes (1-1440; default 60).
# TICKET_RECONCILIATION_INTERVAL_MINUTES=60

# How long a cached Idempotency-Key response is reused for build-transaction
# POST endpoints.
IDEMPOTENCY_KEY_TTL_MINUTES=15

# Experimental features. Flags are disabled unless explicitly set to true.
FEATURE_FEE_BUMP=false
FEATURE_INDEXER=false

# Max platform-paid fee, in stroops, for one sponsored attendee transaction
# when FEATURE_FEE_BUMP=true. Default 100000 (0.01 XLM).
# FEE_BUMP_MAX_FEE_STROOPS=100000

# JSON body size limit (e.g. 100kb, 1mb). Rejects payloads exceeding this with 413.
JSON_BODY_LIMIT=100kb

# CSP directives as JSON object string for helmet contentSecurityPolicy.
# Leave unset to use helmet defaults. Example:
# CSP_DIRECTIVES={"defaultSrc":["'self'"],"scriptSrc":["'self'"]}
# CSP_DIRECTIVES=