.env.example

# Settla local development environment
# Copy to .env: cp .env.example .env
#
# PRODUCTION SECURITY NOTICE:
#   Variables marked with "# CHANGE IN PRODUCTION" MUST be replaced with strong
#   random values before any production or staging deployment.
#   In Kubernetes, secrets are injected via External Secrets Operator (ESO) from
#   AWS Secrets Manager — see deploy/k8s/base/secrets/ for the ExternalSecret
#   definitions.  Never commit real secrets to version control.

# ── PostgreSQL ───────────────────────────────────────────────────
# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
# K8s: injected from settla-db-credentials ExternalSecret (secretKeyRef: app-password).
POSTGRES_USER=settla
POSTGRES_PASSWORD=settla  # CHANGE IN PRODUCTION
# RLS application role password (used by init-rls-role.sh in Docker).
# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
SETTLA_APP_DB_PASSWORD=settla_app  # CHANGE IN PRODUCTION

# DB URLs point to PgBouncer (pooled), NOT raw Postgres.
# Raw Postgres ports (5433/5434/5435) are for migrations and admin only.
SETTLA_LEDGER_DB_URL=postgres://settla:settla@localhost:6433/settla_ledger?sslmode=prefer
SETTLA_TRANSFER_DB_URL=postgres://settla:settla@localhost:6434/settla_transfer?sslmode=prefer
SETTLA_TREASURY_DB_URL=postgres://settla:settla@localhost:6435/settla_treasury?sslmode=prefer

# Raw Postgres URLs for migrations (PgBouncer doesn't support DDL well)
SETTLA_LEDGER_DB_MIGRATE_URL=postgres://settla:settla@localhost:5433/settla_ledger?sslmode=prefer
SETTLA_TRANSFER_DB_MIGRATE_URL=postgres://settla:settla@localhost:5434/settla_transfer?sslmode=prefer
SETTLA_TREASURY_DB_MIGRATE_URL=postgres://settla:settla@localhost:5435/settla_treasury?sslmode=prefer

# RLS-enforced DB URLs (settla_app role, subject to Row-Level Security).
# Used by settla-server for tenant-scoped API operations. Optional — when unset,
# all queries run as the owner role (settla) which bypasses RLS.
# NOTE: In production, SETTLA_TRANSFER_APP_DB_URL is REQUIRED — the server exits without it.
# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
SETTLA_TRANSFER_APP_DB_URL=postgres://settla_app:settla_app@localhost:6434/settla_transfer?sslmode=prefer
SETTLA_LEDGER_APP_DB_URL=postgres://settla_app:settla_app@localhost:6433/settla_ledger?sslmode=prefer
SETTLA_TREASURY_APP_DB_URL=postgres://settla_app:settla_app@localhost:6435/settla_treasury?sslmode=prefer
# PRODUCTION: use sslmode=verify-ca or sslmode=verify-full with certificates

# ── TigerBeetle ─────────────────────────────────────────────────
# Ledger write authority (1M+ TPS). Source of truth for balances.
SETTLA_TIGERBEETLE_ADDRESSES=localhost:3001

# ── Redis ────────────────────────────────────────────────────────
# CHANGE IN PRODUCTION — set via settla/production/app in AWS Secrets Manager.
REDIS_PASSWORD=settla-dev  # CHANGE IN PRODUCTION
SETTLA_REDIS_URL=redis://:settla-dev@localhost:6380
# SETTLA_REDIS_TLS=true           # Enable TLS for Redis (use rediss:// scheme in URL)

# ── NATS ─────────────────────────────────────────────────────────
SETTLA_NATS_URL=nats://localhost:4222
# NATS authentication (required in production). Choose one:
# SETTLA_NATS_TOKEN=              # Token auth — generate: openssl rand -hex 32
# SETTLA_NATS_USER=               # Username/password auth
# SETTLA_NATS_PASSWORD=

# ── Settla Server (Go) ──────────────────────────────────────────
# Tyk now owns external port 8080; settla-server HTTP exposed on 8081 for direct access
SETTLA_SERVER_HTTP_PORT=8081
SETTLA_SERVER_GRPC_PORT=9090
SETTLA_PPROF_PORT=6060
SETTLA_PPROF=true

# ── Database Connection Pool ─────────────────────────────────────
# Max connections per pgxpool (shared across transfer/ledger/treasury DBs)
# SETTLA_DB_MAX_CONNS=50
# Minimum idle connections kept warm in the pool
# SETTLA_DB_MIN_CONNS=10

# ── High-Throughput Tuning ───────────────────────────────────────
# Treasury: how often in-memory reservations flush to Postgres (ms)
SETTLA_TREASURY_FLUSH_INTERVAL_MS=100
# Treasury: per-currency sync flush thresholds (comma-separated CURRENCY:AMOUNT).
# Reserves >= threshold trigger an immediate synchronous DB flush for durability.
# Defaults approximate $100K USD equivalent per currency. Set to 0 to disable.
# SETTLA_TREASURY_SYNC_THRESHOLDS=NGN:160000000,GHS:1500000,KES:13000000,USD:100000,GBP:80000,EUR:92000,USDT:100000,USDC:100000
# Treasury: fallback sync threshold for currencies not in the per-currency map.
# SETTLA_TREASURY_SYNC_THRESHOLD_DEFAULT=100000
# Ledger: write-ahead batch window before flushing to TigerBeetle (ms)
SETTLA_LEDGER_BATCH_WINDOW_MS=10
# Ledger: maximum entries per write-ahead batch (increase for higher throughput)
SETTLA_LEDGER_BATCH_MAX_SIZE=500

# ── Settla Node (NATS Workers) ──────────────────────────────────
# Total partitions for event stream (must match across all nodes)
# 256 partitions supports ~1M concurrent tenants (~3,900/partition). Range: 1-256.
SETTLA_NODE_PARTITIONS=256
# Which partition this instance handles (omit in dev = handle all)
# SETTLA_NODE_PARTITION_ID=0

# ── Outbox Relay Tuning ─────────────────────────────────────────
# Batch size: entries fetched per poll cycle (higher = better throughput at peak)
SETTLA_RELAY_BATCH_SIZE=200
# Poll interval in milliseconds (lower = lower latency, higher CPU)
SETTLA_RELAY_POLL_INTERVAL_MS=30
# Production tuning for 5K TPS peak (25K outbox entries/sec):
#   SETTLA_RELAY_BATCH_SIZE=1000
#   SETTLA_RELAY_POLL_INTERVAL_MS=10

# ── Worker Pool Sizes ───────────────────────────────────────────
# Max concurrent handlers per worker type. Tuned for 5K TPS peak.
# At 256 partitions, transfer workers handle ~20 events/sec per partition.
SETTLA_WORKER_POOL_TRANSFER=8
SETTLA_WORKER_POOL_PROVIDER=16
SETTLA_WORKER_POOL_BLOCKCHAIN=16
SETTLA_WORKER_POOL_LEDGER=8
SETTLA_WORKER_POOL_TREASURY=8
SETTLA_WORKER_POOL_WEBHOOK=32
SETTLA_WORKER_POOL_INBOUND_WH=8

# ── Settla Gateway (TypeScript) ─────────────────────────────────
SETTLA_GATEWAY_PORT=3100
# Number of persistent gRPC connections to settla-server
SETTLA_GRPC_POOL_SIZE=50
# Local in-process tenant auth cache TTL (seconds)
SETTLA_TENANT_CACHE_TTL_SECONDS=30
# Max entries in the L1 tenant auth cache (default 500K, supports ~1M tenants)
# SETTLA_TENANT_CACHE_MAX_LOCAL=500000

# ── Provider Mode ─────────────────────────────────────────────────
# mock    — Mock providers, no blockchain (default for tests)
# testnet — Real testnet blockchains (Tron Nile, Sepolia, Solana Devnet)
# live    — Production providers (future)
SETTLA_PROVIDER_MODE=mock

# ── Mock Provider Tuning ────────────────────────────────────────
# Reduce for load testing (real providers take seconds, mock simulates delay)
SETTLA_MOCK_DELAY_MS=500

# ── Mock HTTP Provider (demo mode) ─────────────────────────────
# URL of the external mock provider service (used with SETTLA_PROVIDER_MODE=mock-http)
# SETTLA_MOCKPROVIDER_URL=http://mockprovider:9095

# ── Wallet Management ────────────────────────────────────────────
# Required for testnet mode. Generate with: openssl rand -hex 32
# SETTLA_WALLET_ENCRYPTION_KEY=
# Required for testnet mode. Generate with: openssl rand -hex 64
# SETTLA_MASTER_SEED=
# Wallet file storage path (default: .settla/wallets)
SETTLA_WALLET_STORAGE_PATH=.settla/wallets

# ── Blockchain RPC URLs (testnet defaults) ───────────────────────
# Override with private/authenticated endpoints for higher rate limits.
# For Alchemy, replace YOUR_ALCHEMY_KEY with your Alchemy API key.
SETTLA_TRON_RPC_URL=https://nile.trongrid.io
# SETTLA_TRON_API_KEY=                          # Optional TronGrid API key (Alchemy does not support Tron)
# SETTLA_ETHEREUM_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
SETTLA_ETHEREUM_RPC_URL=https://rpc.sepolia.org
# SETTLA_BASE_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
SETTLA_BASE_RPC_URL=https://sepolia.base.org
# SETTLA_SOLANA_RPC_URL=https://solana-devnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
SETTLA_SOLANA_RPC_URL=https://api.devnet.solana.com

# ── Chain Monitor RPC (settla-node, separate from above) ──────────
# Primary + optional backup endpoints for deposit detection pollers.
# SETTLA_ETH_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
# SETTLA_ETH_RPC_BACKUP_URL=https://rpc.sepolia.org
# SETTLA_BASE_RPC_API_KEY=
# SETTLA_BASE_RPC_BACKUP_URL=https://sepolia.base.org

# ── Ops Dashboard Auth ────────────────────────────────────────────
# API key for the internal ops routes (/v1/ops/*). Must be set to a strong
# random value in production. Requests without this key receive HTTP 403.
# CHANGE IN PRODUCTION — generate: openssl rand -hex 32
SETTLA_OPS_API_KEY=settla-ops-secret-change-me  # CHANGE IN PRODUCTION

# ── Tyk API Gateway ─────────────────────────────────────────────
# Tyk handles external traffic (auth, rate limiting, circuit breaking).
# CHANGE IN PRODUCTION — set via settla/production/app → tyk-secret in AWS Secrets Manager.
# K8s: injected from settla-app-secrets ExternalSecret (secretKeyRef: tyk-secret).
# Generate: openssl rand -hex 32
TYK_SECRET=settla-tyk-secret-change-me  # CHANGE IN PRODUCTION
TYK_GATEWAY_PORT=8080

# ── Dashboard ──────────────────────────────────────────────────────
# API key for the ops dashboard. Must be set to a valid tenant API key.
# In dev, use a seed tenant key. In production, use a dedicated admin key.
NUXT_PUBLIC_DASHBOARD_API_KEY=
# Ops API key for /v1/ops/* endpoints (must match SETTLA_OPS_API_KEY)
NUXT_OPS_API_KEY=settla-ops-secret-change-me

# ── Webhook Secrets (required in production) ──────────────────────
# HMAC-SHA256 secrets for outbound webhook signatures per seed tenant.
# In dev, defaults are used. In production, these MUST be set.
# CHANGE IN PRODUCTION — set via settla/production/webhooks in AWS Secrets Manager.
# K8s: injected from settla-webhook-secrets ExternalSecret.
# Generate: openssl rand -hex 32
# LEMFI_WEBHOOK_SECRET=    # CHANGE IN PRODUCTION — min 32 chars random string
# FINCRA_WEBHOOK_SECRET=   # CHANGE IN PRODUCTION — min 32 chars random string

# ── Inbound Provider Webhook Signing Secrets ──────────────────────
# HMAC-SHA256 secrets used to verify signatures on webhooks received FROM
# payment providers. Pattern: PROVIDER_{SLUG_UPPER}_WEBHOOK_SECRET
# The slug is the provider identifier in the URL path, with hyphens replaced
# by underscores and uppercased.
#
# Examples:
#   PROVIDER_YELLOW_CARD_WEBHOOK_SECRET=whsec_...   (slug: yellow-card)
#   PROVIDER_KOTANI_PAY_WEBHOOK_SECRET=whsec_...    (slug: kotani-pay)
#   PROVIDER_SETTLA_TESTNET_WEBHOOK_SECRET=whsec_... (slug: settla-testnet)
#
# Behaviour:
#   - Secret configured + signature present   -> verified with HMAC-SHA256
#   - Secret configured + signature missing   -> warning logged, request proceeds
#   - Secret configured + signature invalid   -> 401 returned
#   - No secret configured                    -> warning logged, request proceeds
#
# Optional: override the signature header name (defaults to x-webhook-signature):
#   PROVIDER_YELLOW_CARD_SIGNATURE_HEADER=x-yc-signature

# ── Observability Credentials ─────────────────────────────────────
# Grafana admin password for the ops dashboard.
# CHANGE IN PRODUCTION — set via settla/production/app → grafana-admin-password.
# K8s: injected from settla-app-secrets ExternalSecret (secretKeyRef: grafana-admin-password).
# Generate: openssl rand -hex 16
GRAFANA_ADMIN_PASSWORD=settla-dev-local  # CHANGE IN PRODUCTION

# Slack webhook URL for AlertManager notifications.
# CHANGE IN PRODUCTION — set via settla/production/alertmanager → slack-webhook-url.
# K8s: injected from alertmanager-secrets ExternalSecret.
# Create at: https://api.slack.com/apps → Incoming Webhooks
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/placeholder  # CHANGE IN PRODUCTION

# PagerDuty Events API v2 Integration Key for critical alerts.
# CHANGE IN PRODUCTION — set via settla/production/alertmanager → pagerduty-service-key.
# K8s: injected from alertmanager-secrets ExternalSecret.
PAGERDUTY_SERVICE_KEY=placeholder  # CHANGE IN PRODUCTION (leave blank for non-production)

# Remediation webhook auth token — used by the AlertManager remediation sidecar.
# CHANGE IN PRODUCTION — set via settla/production/alertmanager → remediation-webhook-token.
# K8s: injected from alertmanager-secrets ExternalSecret.
# Generate: openssl rand -hex 32
REMEDIATION_WEBHOOK_TOKEN=dev-token  # CHANGE IN PRODUCTION

# ── General ──────────────────────────────────────────────────────
SETTLA_LOG_LEVEL=debug
SETTLA_ENV=development
SETTLA_JWT_SECRET=  # Required. Generate with: openssl rand -base64 32
# HMAC secret for API key hashing. When set, keys are hashed with HMAC-SHA256
# instead of plain SHA-256, preventing offline brute-force if key_hash DB is leaked.
# CHANGE IN PRODUCTION — generate: openssl rand -hex 32
# Must be identical across all gateway instances and settla-server.
SETTLA_API_KEY_HMAC_SECRET=  # Required in production. Generate with: openssl rand -hex 32