.env.example

# =============================================================================
# Stellar BatchPay — Environment Variable Reference
# =============================================================================
# Copy this file to .env and fill in your values.
# NEVER commit .env or any file containing real secrets to version control.
# =============================================================================

# -----------------------------------------------------------------------------
# Wallet/Signing (server-only — never prefix with NEXT_PUBLIC_)
# -----------------------------------------------------------------------------
# Enables the API routes /api/batch-submit and /api/batch-retry to sign
# transactions server-side using the secret below. Default is disabled (false).
# ALLOW_SERVER_SIGNING=false

# Secret key for the Stellar account that pays batches. Keep this private.
# STELLAR_SECRET_KEY="S..."

# Secret API key required in the Authorization: Bearer header when ALLOW_SERVER_SIGNING=true.
# REQUIRED whenever ALLOW_SERVER_SIGNING=true — without it, /api/batch-submit
# and /api/batch-retry refuse every server-signing request with 403 (fail
# closed, #728). See DEPLOYMENT.md for the local-demo-only escape hatch.
# SERVER_SIGNING_API_KEY="generate-with-openssl-rand-hex-32"

# HMAC secret for wallet session tokens on batch read/recover APIs.
# WALLET_AUTH_SECRET="generate-with-openssl-rand-hex-32"

# Optional dedicated SEP-10 server signing key (defaults to a deterministic key derived from WALLET_AUTH_SECRET).
# WALLET_AUTH_SERVER_SECRET="S..."

# SEP-10 challenge domain configuration for wallet authentication.
# WALLET_AUTH_HOME_DOMAIN="localhost"
# WALLET_AUTH_WEB_AUTH_DOMAIN="stellar-batch-pay"
# WALLET_AUTH_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
# WALLET_AUTH_CHALLENGE_TIMEOUT_SEC=300
# WALLET_AUTH_SESSION_TTL_SEC=3600

# Maximum retries when the server encounters tx_bad_seq errors.
# STELLAR_BAD_SEQUENCE_RETRY_LIMIT=3

# -----------------------------------------------------------------------------
# Client-Side / Browser Variables (must use NEXT_PUBLIC_ prefix)
# -----------------------------------------------------------------------------
# Public site URL used in sitemap.xml and robots.txt.
# NEXT_PUBLIC_SITE_URL="https://stellar-batch-pay.vercel.app"

# Sentry DSN for browser error reporting (only active in production).
# NEXT_PUBLIC_SENTRY_DSN="https://..."

# Enable/disable Vercel Analytics.
# NEXT_PUBLIC_ENABLE_ANALYTICS=false

# Which Stellar network the wallet/UI should target: "testnet" or "mainnet".
# Read by app/layout.tsx to set the WalletProvider's expected network; the
# dashboard warns the user if their connected wallet is on a different
# network than this value. Defaults to "testnet" when unset.
# NEXT_PUBLIC_STELLAR_NETWORK="testnet"

# -----------------------------------------------------------------------------
# Horizon/RPC (server + client)
# -----------------------------------------------------------------------------
# Client bundles need the NEXT_PUBLIC_ prefix; the server-only versions are
# used for backend operations. If either is set, the NEXT_PUBLIC_ one wins
# on the client so the browser can target a different RPC than the server.
# HORIZON_URL_MAINNET="https://horizon.stellar.org"
# HORIZON_URL_TESTNET="https://horizon-testnet.stellar.org"
# HORIZON_URL_FUTURENET="https://horizon-futurenet.stellar.org"
# SOROBAN_RPC_URL_MAINNET="https://soroban-mainnet.stellar.org"
# SOROBAN_RPC_URL_TESTNET="https://soroban-testnet.stellar.org"
# SOROBAN_RPC_URL_FUTURENET="https://soroban-futurenet.stellar.org"
# NEXT_PUBLIC_HORIZON_URL_MAINNET="https://horizon.stellar.org"
# NEXT_PUBLIC_HORIZON_URL_TESTNET="https://horizon-testnet.stellar.org"
# NEXT_PUBLIC_HORIZON_URL_FUTURENET="https://horizon-futurenet.stellar.org"
# NEXT_PUBLIC_SOROBAN_RPC_URL_MAINNET="https://soroban-mainnet.stellar.org"
# NEXT_PUBLIC_SOROBAN_RPC_URL_TESTNET="https://soroban-testnet.stellar.org"
# NEXT_PUBLIC_SOROBAN_RPC_URL_FUTURENET="https://soroban-futurenet.stellar.org"

# Network passphrase for the Soroban RPC URL above.
# NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

# -----------------------------------------------------------------------------
# Vesting Contract ID (server + client)
# -----------------------------------------------------------------------------
# Contract ID of the deployed batch-vesting Soroban contract (starts with
# "C..."), read by lib/stellar/vesting-config.ts. For each network, the first
# defined value wins, in this order:
#   NEXT_PUBLIC_CONTRACT_ID_<NETWORK> -> CONTRACT_ID_<NETWORK> ->
#   NEXT_PUBLIC_CONTRACT_ID -> CONTRACT_ID
# The NEXT_PUBLIC_ versions are required if the browser bundle needs to read
# the contract ID directly; when both a NEXT_PUBLIC_ and non-prefixed value
# are set for the same key, the NEXT_PUBLIC_ one wins on the client. There is
# no default — the app throws a startup error if none of these resolve, and
# also rejects the well-known all-zero placeholder contract ID.
# NEXT_PUBLIC_CONTRACT_ID="C..."
# NEXT_PUBLIC_CONTRACT_ID_TESTNET="C..."
# NEXT_PUBLIC_CONTRACT_ID_MAINNET="C..."
# NEXT_PUBLIC_CONTRACT_ID_FUTURENET="C..."
# CONTRACT_ID_TESTNET="C..."
# CONTRACT_ID_MAINNET="C..."
# CONTRACT_ID_FUTURENET="C..."

# -----------------------------------------------------------------------------
# Persistence & Storage
# -----------------------------------------------------------------------------
# Deployment mode: "single-node" (default, SQLite) or "ha" (Postgres/Redis).
# DEPLOYMENT_MODE="single-node"

# Job store backend: "sqlite" (default for single-node) or "postgres" (default for ha).
# JOB_STORE_BACKEND="sqlite"

# Rate limit backend: "sqlite" (default for single-node), "redis" (default for ha), or "postgres".
# RATE_LIMIT_BACKEND="sqlite"

# Postgres connection string (required when JOB_STORE_BACKEND=postgres or RATE_LIMIT_BACKEND=postgres).
# DATABASE_URL="postgres://user:pass@host/dbname"

# Redis connection string (required when RATE_LIMIT_BACKEND=redis).
# REDIS_URL="redis://host:6379"

# SQLite path for durable batch job state. Defaults to ./data/jobs.db.
# JOB_STORE_PATH="./data/jobs.db"

# Stable key used to encrypt webhook signing secrets in SQLite. Set this in
# every app process and keep it outside the database.
# WEBHOOK_ENCRYPTION_KEY="replace-with-a-long-random-secret"
# WEBHOOK_ADMIN_API_KEY="replace-with-a-long-random-secret"

# SQLite path for API rate-limit counters. Defaults to ./data/rate-limit.db.
# RATE_LIMIT_DB_PATH="./data/rate-limit.db"

# -----------------------------------------------------------------------------
# Rate limits
# -----------------------------------------------------------------------------
# JSON map of API keys to tiers. Example: {"abc123":"pro","def456":"enterprise"}
# RATE_LIMIT_API_KEY_TIERS=

# Per-endpoint free-tier limits. Prefix the endpoint key with RATE_LIMIT_.
# Enterprise limits follow the same pattern with suffix _ENTERPRISE.
# RATE_LIMIT_BATCH_BUILD_FREE=8
# RATE_LIMIT_BATCH_BUILD_PRO=20
# RATE_LIMIT_BATCH_BUILD_WINDOW_MS=60000
# RATE_LIMIT_BATCH_SUBMIT_FREE=5
# RATE_LIMIT_BATCH_SUBMIT_PRO=15
# RATE_LIMIT_BATCH_SUBMIT_WINDOW_MS=60000
# RATE_LIMIT_BATCH_SUBMIT_SIGNED_FREE=5
# RATE_LIMIT_BATCH_SUBMIT_SIGNED_PRO=15
# RATE_LIMIT_BATCH_SUBMIT_SIGNED_WINDOW_MS=60000
# RATE_LIMIT_WEBHOOK_REGISTER_FREE=3
# RATE_LIMIT_WEBHOOK_REGISTER_PRO=10
# RATE_LIMIT_WEBHOOK_REGISTER_WINDOW_MS=60000
# RATE_LIMIT_TX_STATUS_FREE=30
# RATE_LIMIT_TX_STATUS_PRO=100
# RATE_LIMIT_TX_STATUS_WINDOW_MS=60000
# RATE_LIMIT_DASHBOARD_METRICS_FREE=20
# RATE_LIMIT_DASHBOARD_METRICS_PRO=60
# RATE_LIMIT_DASHBOARD_METRICS_WINDOW_MS=60000
# RATE_LIMIT_BATCH_STATUS_FREE=60
# RATE_LIMIT_BATCH_STATUS_PRO=200
# RATE_LIMIT_BATCH_STATUS_WINDOW_MS=60000
# RATE_LIMIT_BATCH_EVENTS_FREE=10
# RATE_LIMIT_BATCH_EVENTS_PRO=30
# RATE_LIMIT_BATCH_EVENTS_WINDOW_MS=60000
# RATE_LIMIT_HEALTH_FREE=30
# RATE_LIMIT_HEALTH_PRO=100
# RATE_LIMIT_HEALTH_WINDOW_MS=60000

# -----------------------------------------------------------------------------
# Webhooks
# -----------------------------------------------------------------------------
# Webhook registrations are stored in SQLite and managed via
# /api/webhooks/register. Outgoing deliveries use the stored secret per
# registration. Delivery auditing and webhook management require this key.

# -----------------------------------------------------------------------------
# Secret Backend (Keeper Bot)
# -----------------------------------------------------------------------------
# Backend for fetching the KEEPER_SECRET. Options: env | aws | github
# In production, SECRET_BACKEND=env (or unset) is REFUSED at startup (#734).
# Use aws or github for all production and staging deployments.
# SECRET_BACKEND=aws

# When SECRET_BACKEND=env the secret is read directly from the environment.
# ⚠️  LOCAL DEVELOPMENT ONLY. Do not use in production.
# KEEPER_SECRET="S..."

# When SECRET_BACKEND=aws, these are required:
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID="..."
# AWS_SECRET_ACCESS_KEY="..."
#
# AWS dual-read rotation (recommended): to rotate a secret with zero downtime,
# store the new secret version alongside the current one in Secrets Manager and
# update the AWSCURRENT/AWSPENDING version stages. The AwsSecretsProvider always
# reads the AWSCURRENT stage, so flip the stage label after verifying the new
# secret is live — no keeper restart required.

# When SECRET_BACKEND=github the secret is injected by GitHub Actions.
# No additional env vars are needed.

# ⚠️  EMERGENCY OVERRIDE — do not set this in normal operation.
# Allows SECRET_BACKEND=env in production. Set only if you are temporarily
# forced to use env secrets in production and have no other option.
# Rotate to SECRET_BACKEND=aws or github as soon as possible.
# ALLOW_ENV_SECRETS_IN_PROD=true

# -----------------------------------------------------------------------------
# Keeper Bot
# -----------------------------------------------------------------------------
# Contract ID the keeper bot bumps schedules on (starts with C...). This is
# the same contract as the "Vesting Contract ID" section above and also
# serves as the generic fallback in resolveVestingContractId's lookup order.
# CONTRACT_ID="C..."

# Maintenance window size — number of schedule indices bumped per recipient per run.
# MAINTENANCE_LIMIT=10

# JSON path for persisting per-recipient pagination cursor between keeper runs.
# KEEPER_STATE_PATH="./data/keeper-state.json"

# Optional Slack/Discord webhook URL for keeper alert notifications.
# ALERT_WEBHOOK_URL="https://hooks.slack.com/services/..."

# Low XLM balance threshold that triggers a keeper alert.
# LOW_BALANCE_THRESHOLD=50

# -----------------------------------------------------------------------------
# Idempotency & Retries
# -----------------------------------------------------------------------------
# Staleness threshold (ms) after which a queued/processing job is considered
# stranded and replayed on an idempotent request.
# IDEMPOTENCY_REPLAY_STALE_MS=30000

# -----------------------------------------------------------------------------
# Error Tracking
# -----------------------------------------------------------------------------
# Server-side Sentry DSN (requires @sentry/nextjs or similar integration).
# SENTRY_DSN="https://..."

# -----------------------------------------------------------------------------
# General
# -----------------------------------------------------------------------------
# NODE_ENV=development
# LOG_LEVEL=info

# -----------------------------------------------------------------------------
# End-to-End Tests (Playwright)
# -----------------------------------------------------------------------------
# Base URL for Playwright tests. Defaults to http://localhost:3000.
# E2E_BASE_URL="http://localhost:3000"