.env.example

# =============================================================================
# Commitlabs - Environment Variable Reference
# Copy this file to .env.local (git-ignored) and fill in your values.
#
# Validation:
# - Backend env vars: src/lib/backend/env.ts (Zod schema)
# - Client env vars (NEXT_PUBLIC_*): src/lib/clientEnv.ts (Zod schema)
# =============================================================================

# -----------------------------------------------------------------------------
# Client-Side Environment Variables (NEXT_PUBLIC_*)
# These variables are exposed to the browser and validated by src/lib/clientEnv.ts.
# Never include secrets in NEXT_PUBLIC_* variables.
# -----------------------------------------------------------------------------

# Soroban RPC endpoint (client-accessible)
# Used by the frontend for blockchain interactions.
# Must be a valid URL when provided.
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org:443

# Stellar network passphrase (client-accessible)
# Defaults to testnet value when not set.
NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# Contract addresses (client-accessible)
# These are the public contract addresses used by the frontend.
# For server-side routes, use the non-public variants (e.g., COMMITMENT_CORE_CONTRACT).
NEXT_PUBLIC_COMMITMENT_NFT_CONTRACT=
NEXT_PUBLIC_COMMITMENT_CORE_CONTRACT=
NEXT_PUBLIC_ATTESTATION_ENGINE_CONTRACT=

# Contract configuration (client-accessible)
# JSON blob defining multiple contract versions. See docs/config.md for structure.
# NEXT_PUBLIC_CONTRACTS_JSON={"v1":{"commitmentNFT":{"address":"C..."},"commitmentCore":{"address":"C..."}}}

# Active contract version (client-accessible)
# Selects which configured version to use (defaults to "v1").
NEXT_PUBLIC_ACTIVE_CONTRACT_VERSION=v1

# Mock mode flag (client-accessible)
# Set to "true" to use mock data instead of real blockchain interactions.
NEXT_PUBLIC_USE_MOCKS=true

# Application URLs (client-accessible)
# Used for CORS configuration and generating links.
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Google Site Verification (client-accessible)
# Optional: Required for Google Search Console verification.
# Omit or leave empty to disable the meta tag.
NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION=

# -----------------------------------------------------------------------------
# Server-Side Environment Variables
# These variables are NOT exposed to the browser and validated by src/lib/backend/env.ts.
# Use these for secrets and server-only configuration.
# -----------------------------------------------------------------------------

# Soroban RPC endpoint (server-only)
# Use this for server-side routes. Takes precedence over NEXT_PUBLIC_SOROBAN_RPC_URL.
# SOROBAN_RPC_URL=https://soroban-testnet.stellar.org:443

# Stellar network passphrase (server-only)
# Defaults to testnet value when not set.
# SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# -----------------------------------------------------------------------------
# Contract addresses (server-only)
# Provide either the private or the NEXT_PUBLIC_ variant.
# Deployment note:
# - contracts/scripts/deploy-testnet.sh upserts the deployed id into .env.local.
# - Never commit a real deployer secret or signer credential.
# - If server-side routes submit writes, keep COMMITMENT_CORE_CONTRACT or
#   SOROBAN_COMMITMENT_CORE_CONTRACT aligned with the public contract id.
# -----------------------------------------------------------------------------
# COMMITMENT_NFT_CONTRACT=
# COMMITMENT_CORE_CONTRACT=
# ATTESTATION_ENGINE_CONTRACT=

# -----------------------------------------------------------------------------
# Signing credentials (server-side only - NEVER expose to the browser)
# SOROBAN_SERVER_SECRET_KEY is used for on-chain write operations.
# Values are ALWAYS redacted from error messages and logs.
# -----------------------------------------------------------------------------
# SOROBAN_SERVER_SECRET_KEY=S...
# SOROBAN_SOURCE_ACCOUNT=G...

# Enable on-chain writes (set to "true" to activate; default false)
# COMMITLABS_ENABLE_CHAIN_WRITES=false

# Per-call timeout (ms) for Soroban RPC interactions (default: 30000 = 30 s).
# When a call exceeds this limit an AbortController fires and the route returns
# HTTP 504 GATEWAY_TIMEOUT with retryable: true. Increase for high-latency
# testnets; decrease for strict latency budgets.
# SOROBAN_RPC_TIMEOUT_MS=30000

# -----------------------------------------------------------------------------
# Session secret (REQUIRED in production)
# Used to sign session tokens. Generate with: openssl rand -hex 32
# Must be at least 32 characters. Value is ALWAYS redacted from error messages.
# -----------------------------------------------------------------------------
# SESSION_SECRET=

# -----------------------------------------------------------------------------
# Storage connection (optional; required if blob/DB storage is used)
# Value is ALWAYS redacted from error messages.
# -----------------------------------------------------------------------------
# STORAGE_CONNECTION=

# -----------------------------------------------------------------------------
# RPC URL allowlist (REQUIRED in production)
# Comma-separated list of permitted Soroban RPC endpoint URLs.
# The active SOROBAN_RPC_URL must be present in this list in production.
# Example:
# SOROBAN_RPC_URL_ALLOWLIST=https://soroban-testnet.stellar.org:443,https://rpc-mainnet.stellar.org
# -----------------------------------------------------------------------------
# SOROBAN_RPC_URL_ALLOWLIST=

# -----------------------------------------------------------------------------
# Feature flags (all default to false)
# Individual boolean strings or a single JSON override blob (JSON takes precedence).
# -----------------------------------------------------------------------------
COMMITLABS_FEATURE_ANALYTICS_USER=false
COMMITLABS_FEATURE_MARKETPLACE=false
# Example:
# COMMITLABS_FEATURE_FLAGS_JSON={"analyticsUser":true,"marketplace":false}

# -- Rate limiting -------------------------------------------------------------
# Controls the fixed-window rate limits applied to API routes.
# All limits are optional — remove the comment (#) to override a default.
# Invalid values (non-numeric, zero, negative) fall back to the defaults below
# so that a misconfigured deployment never accidentally disables rate limiting.
#
# Auth routes — kept tight to resist credential-farming and brute-force attacks.
# Raise these during planned load tests; restore before going back to production.
# RATE_LIMIT_AUTH_NONCE_MAX_REQUESTS=5     # api/auth/nonce     (default: 5 req / 60 s)
# RATE_LIMIT_AUTH_NONCE_WINDOW_SECONDS=60
# RATE_LIMIT_AUTH_VERIFY_MAX_REQUESTS=5    # api/auth/verify    (default: 5 req / 60 s)
# RATE_LIMIT_AUTH_VERIFY_WINDOW_SECONDS=60
# RATE_LIMIT_NONCE_ADDRESS_MAX_REQUESTS=3  # auth:nonce:address — per-wallet secondary bucket
# RATE_LIMIT_NONCE_ADDRESS_WINDOW_SECONDS=300  # (default: 3 req / 300 s)
#
# Write-heavy routes — protects on-chain operations and the signing budget.
# RATE_LIMIT_WRITE_MAX_REQUESTS=10    # api/commitments/{create,settle,early-exit}
# RATE_LIMIT_WRITE_WINDOW_SECONDS=60
#
# Default bucket — fallback for all routes not listed above.
# RATE_LIMIT_DEFAULT_MAX_REQUESTS=20
# RATE_LIMIT_DEFAULT_WINDOW_SECONDS=60

# -- Cache layer ---------------------------------------------------------------
# CACHE_ADAPTER=memory
# REDIS_URL=redis://localhost:6379

# Examples:
# redis://localhost:6379
# redis://:mypassword@redis.example.com:6379/0
# rediss://:mypassword@redis.example.com:6380/0

# -- Upstash Redis (serverless KV) ---------------------------------------------
# Used by src/lib/backend/kv.ts when CACHE_ADAPTER=upstash.
# UPSTASH_REDIS_REST_URL=
# UPSTASH_REDIS_REST_TOKEN=

# -- Storage provider -----------------------------------------------------------
# Selects the storage backend used by src/lib/backend/storage.ts.
# Valid values: "memory" | "redis" | "kv"
# COMMITLABS_STORAGE_PROVIDER=memory

# -----------------------------------------------------------------------------
# Admin & Security (server-side only)
# These variables control admin authorization and sensitive endpoint access.
# -----------------------------------------------------------------------------

# Comma-separated list of Stellar addresses treated as admins.
# Used by src/lib/backend/requireAuth.ts for requireAdmin / dispute resolution.
# ADMIN_ADDRESSES=GABC...,GDEF...

# Bearer token for the admin audit-log endpoint (src/app/api/admin/audit-events/route.ts).
# The route returns 403 if this is unset. Value is ALWAYS redacted from logs.
# COMMITLABS_ADMIN_SECRET=

# -----------------------------------------------------------------------------
# Feature flags — audit log & seed endpoint
# -----------------------------------------------------------------------------

# Gates the audit-log endpoint on/off (src/lib/backend/auditLog.ts).
# Set to "true" to enable audit logging.
# COMMITLABS_FEATURE_AUDIT_LOG=false

# Enables the mock-data seeding endpoint (src/app/api/seed/route.ts).
# Set to "true" to allow seed requests.
# SEED_ROUTE_ENABLED=false

# Shared secret required by the seed endpoint (src/app/api/seed/route.ts).
# Only checked when SEED_ROUTE_ENABLED=true.
# SEED_SECRET=

# -----------------------------------------------------------------------------
# Protocol constants (server-side only)
# Override the defaults baked into src/lib/backend/services/protocolConstants.ts.
# -----------------------------------------------------------------------------

# JSON array of penalty tier objects for early-exit calculations.
# COMMITLABS_PENALTY_TIERS_JSON=[{"type":"standard","earlyExitPenaltyPercent":10}]

# -----------------------------------------------------------------------------
# CORS origins (server-side only)
# Override the defaults in src/lib/backend/cors.ts.
# -----------------------------------------------------------------------------

# First-party origins (app pages, admin panels).
# COMMITLABS_FIRST_PARTY_ORIGINS=https://app.commitlabs.com

# Public API origins (external integrations). Use "*" to allow all.
# COMMITLABS_PUBLIC_API_ORIGINS=*

# -----------------------------------------------------------------------------
# SSE tuning (server-side only)
# Controls polling/keepalive intervals for the commitments events SSE stream
# (src/app/api/commitments/[id]/events/route.ts).
# -----------------------------------------------------------------------------

# Poll interval in ms for checking commitment status updates (default: 5000).
# SSE_POLL_INTERVAL_MS=5000

# Keepalive interval in ms to prevent connection timeout (default: 30000).
# SSE_KEEPALIVE_INTERVAL_MS=30000