.env.example

# =============================================================================

# Aframp Backend — Environment Variable Reference
# =============================================================================
# Copy this file to .env for local development.
# NEVER commit .env, .env.staging, or .env.production to the repository.
# In staging/production all values marked [SECRET] must come from a secrets
# manager (AWS Secrets Manager, HashiCorp Vault, etc.) — never from files.
#
# Legend:
#   [REQUIRED]  Application will refuse to start without this value.
#   [SECRET]    Must be stored in a secrets manager in non-dev environments.
#   [DEFAULT]   Has a safe default; override as needed.
# =============================================================================

# -----------------------------------------------------------------------------
# Application
# -----------------------------------------------------------------------------
APP_ENV=development          # development | staging | production  [REQUIRED]
SERVER_HOST=127.0.0.1        # [DEFAULT] Use 0.0.0.0 inside Docker
SERVER_PORT=8000             # [DEFAULT]
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000  # [DEFAULT]

# -----------------------------------------------------------------------------
# Database  [REQUIRED]
# -----------------------------------------------------------------------------
# Format: postgres://user:password@host:port/dbname?sslmode=require
# Production MUST use sslmode=require (or verify-full).
DATABASE_URL=postgres://aframp:aframp_dev@localhost:5432/aframp_dev?sslmode=disable  # [SECRET in prod]

# Connection pool
DB_MAX_CONNECTIONS=20        # [DEFAULT] Production: 50–100
DB_MIN_CONNECTIONS=5         # [DEFAULT] Production: 10
DB_CONNECTION_TIMEOUT=30     # seconds [DEFAULT]
DB_IDLE_TIMEOUT=600          # seconds [DEFAULT]
DB_SSL_MODE=disable          # disable | require | verify-full  — production: verify-full

# Read replica (optional — leave blank to disable)
DATABASE_READ_REPLICA_URL=   # [SECRET in prod] postgres://...?sslmode=require

# -----------------------------------------------------------------------------
# Redis  [REQUIRED]
# -----------------------------------------------------------------------------
# Format: redis://[:password@]host:port[/db]
# Production MUST use rediss:// (TLS).
REDIS_URL=redis://127.0.0.1:6379  # [SECRET in prod]
CACHE_DEFAULT_TTL=3600       # seconds [DEFAULT]
CACHE_MAX_CONNECTIONS=10     # [DEFAULT] Production: 20–50

# Redis persistence / eviction (document only — set in redis.conf)
# maxmemory-policy: allkeys-lru
# appendonly: yes  (AOF persistence)
# save: 900 1 300 10 60 10000  (RDB snapshots)

# -----------------------------------------------------------------------------
# Authentication & Security  [SECRET]
# -----------------------------------------------------------------------------
JWT_SECRET=change-me-in-production-min-32-chars  # [REQUIRED][SECRET] min 32 chars
JWT_EXPIRY_SECS=3600         # [DEFAULT] 1 hour
REFRESH_TOKEN_EXPIRY_SECS=604800  # [DEFAULT] 7 days
ENCRYPTION_KEY=change-me-in-production-32-byte-hex  # [REQUIRED][SECRET] AES-256 key (32 bytes hex)

# -----------------------------------------------------------------------------
# Payment Providers  [SECRET]
# -----------------------------------------------------------------------------

# Paystack
PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx  # [REQUIRED][SECRET]
PAYSTACK_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxxxxxx  # [SECRET]
PAYSTACK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx  # [SECRET]
PAYSTACK_BASE_URL=https://api.paystack.co         # [DEFAULT]
PAYSTACK_TIMEOUT_SECS=30     # [DEFAULT]
PAYSTACK_MAX_RETRIES=3       # [DEFAULT]
PAYSTACK_FEE_BPS=150         # [DEFAULT] basis points

# Flutterwave
FLUTTERWAVE_SECRET_KEY=FLWSECK_TEST-xxxxxxxxxxxxxxxxxxxx  # [REQUIRED][SECRET]
FLUTTERWAVE_PUBLIC_KEY=FLWPUBK_TEST-xxxxxxxxxxxxxxxxxxxx  # [SECRET]
FLUTTERWAVE_WEBHOOK_SECRET=xxxxxxxxxxxxxxxxxxxx  # [SECRET]
FLUTTERWAVE_BASE_URL=https://api.flutterwave.com/v3  # [DEFAULT]
FLUTTERWAVE_TIMEOUT_SECS=30  # [DEFAULT]
FLUTTERWAVE_MAX_RETRIES=3    # [DEFAULT]
FLUTTERWAVE_FEE_BPS=155      # [DEFAULT]

# M-Pesa (Safaricom Daraja)
MPESA_CONSUMER_KEY=xxxxxxxxxxxxxxxxxxxx  # [REQUIRED][SECRET]
MPESA_CONSUMER_SECRET=xxxxxxxxxxxxxxxxxxxx  # [SECRET]
MPESA_PASSKEY=xxxxxxxxxxxxxxxxxxxx  # [SECRET]
MPESA_SHORTCODE=174379       # [REQUIRED] Business shortcode
MPESA_BASE_URL=https://sandbox.safaricom.co.ke  # [DEFAULT] prod: https://api.safaricom.co.ke
MPESA_TIMEOUT_SECS=30        # [DEFAULT]
MPESA_FEE_BPS=170            # [DEFAULT]

# Payment routing
DEFAULT_PAYMENT_PROVIDER=paystack  # [DEFAULT]
ENABLED_PAYMENT_PROVIDERS=paystack,flutterwave,mpesa  # [DEFAULT]

# -----------------------------------------------------------------------------
# Stellar / Blockchain  [SECRET]
# -----------------------------------------------------------------------------
STELLAR_NETWORK=testnet      # testnet | mainnet  [REQUIRED]
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org  # [DEFAULT]
STELLAR_REQUEST_TIMEOUT=15   # seconds [DEFAULT]
STELLAR_MAX_RETRIES=3        # [DEFAULT]
STELLAR_HEALTH_CHECK_INTERVAL=30  # seconds [DEFAULT]

SYSTEM_WALLET_ADDRESS=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # [REQUIRED][SECRET]
SYSTEM_WALLET_SECRET=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # [REQUIRED][SECRET]
HOT_WALLET_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # [SECRET]

CNGN_ISSUER_TESTNET=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # [REQUIRED]
CNGN_ISSUER_MAINNET=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # [REQUIRED in prod]

# -----------------------------------------------------------------------------
# Logging
# -----------------------------------------------------------------------------
LOG_LEVEL=INFO               # TRACE | DEBUG | INFO | WARN | ERROR  [DEFAULT]
LOG_FORMAT=plain             # plain | json  [DEFAULT] Production: json
ENABLE_TRACING=false         # [DEFAULT] Production: true

# -----------------------------------------------------------------------------
# OpenTelemetry / Distributed Tracing
# -----------------------------------------------------------------------------
OTEL_SERVICE_NAME=aframp-backend  # [DEFAULT]
OTEL_SAMPLING_RATE=1.0       # [DEFAULT] Production: 0.1
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317  # [DEFAULT]

# -----------------------------------------------------------------------------
# Workers
# -----------------------------------------------------------------------------
WORKER_POLL_INTERVAL_SECS=5  # [DEFAULT]
WORKER_BATCH_SIZE=100        # [DEFAULT]
WORKER_MAX_RETRIES=3         # [DEFAULT]
TRANSACTION_MONITOR_INTERVAL_SECS=10  # [DEFAULT]
PAYMENT_POLLER_INTERVAL_SECS=5  # [DEFAULT]
OFFRAMP_PROCESSOR_INTERVAL_SECS=5  # [DEFAULT]

# -----------------------------------------------------------------------------
# Rate Limiting
# -----------------------------------------------------------------------------
RATE_LIMIT_REQUESTS_PER_MINUTE=60  # [DEFAULT]
RATE_LIMIT_BURST=10          # [DEFAULT]

# -----------------------------------------------------------------------------
# TLS (production only — handled by reverse proxy / load balancer)
# -----------------------------------------------------------------------------
# TLS termination is performed by the reverse proxy (nginx / ALB).
# The application itself listens on plain HTTP internally.
# Minimum TLS version enforced at proxy: TLSv1.2 (prefer TLSv1.3)
# Certificate renewal: automated via Let's Encrypt / ACM
TLS_CERT_PATH=               # Path to TLS cert (if terminating at app level)
TLS_KEY_PATH=                # Path to TLS key  (if terminating at app level)
# Aframp Backend — environment variable reference
#
# Copy this file to .env and fill in the values for local development.
# NEVER commit .env to version control.
#
#   cp .env.example .env
#
# Variables marked REQUIRED must be set before the application will start.
# Variables marked OPTIONAL have defaults shown; omit them to use the default.
# =============================================================================


# -----------------------------------------------------------------------------
# Server
# -----------------------------------------------------------------------------

# Host the HTTP server binds to.
# Use 0.0.0.0 inside Docker; 127.0.0.1 for local cargo run.
# OPTIONAL — default: 127.0.0.1
SERVER_HOST=0.0.0.0

# Port the HTTP server listens on.
# OPTIONAL — default: 8000
SERVER_PORT=8000

# Comma-separated list of allowed CORS origins.
# OPTIONAL — default: http://localhost,http://127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000


# -----------------------------------------------------------------------------
# PostgreSQL
# -----------------------------------------------------------------------------

# Full connection URL used by sqlx.
# REQUIRED
DATABASE_URL=postgres://aframp:changeme@localhost:5432/aframp

# Individual parts used by docker-compose to configure the postgres service.
# REQUIRED when using docker-compose
POSTGRES_DB=aframp
POSTGRES_USER=aframp
POSTGRES_PASSWORD=changeme
POSTGRES_PORT=5432

# Connection pool tuning.
# OPTIONAL
DB_MAX_CONNECTIONS=20
DB_MIN_CONNECTIONS=5
DB_CONNECTION_TIMEOUT=30
DB_IDLE_TIMEOUT=600
DB_MAX_LIFETIME=1800


# -----------------------------------------------------------------------------
# Redis
# -----------------------------------------------------------------------------

# Full Redis URL used by the cache layer.
# REQUIRED
REDIS_URL=redis://:changeme@localhost:6379

# Password used by docker-compose to configure the redis service.
# REQUIRED when using docker-compose
REDIS_PASSWORD=changeme
REDIS_PORT=6379

# Connection pool tuning.
# OPTIONAL
REDIS_MAX_CONNECTIONS=20
REDIS_MIN_IDLE=5
REDIS_CONNECTION_TIMEOUT=5
REDIS_MAX_LIFETIME=300
REDIS_IDLE_TIMEOUT=60
REDIS_HEALTH_CHECK_INTERVAL=30


# -----------------------------------------------------------------------------
# Application
# -----------------------------------------------------------------------------

# Deployment environment. Must be one of: development, staging, production, test
# OPTIONAL — default: development
APP_ENV=development

# Log verbosity. One of: TRACE, DEBUG, INFO, WARN, ERROR
# OPTIONAL — default: INFO
LOG_LEVEL=INFO

# Log format. One of: json, plain
# OPTIONAL — default: plain
LOG_FORMAT=json

# Enable distributed tracing bridge (true/false).
# OPTIONAL — default: false
ENABLE_TRACING=false


# -----------------------------------------------------------------------------
# JWT Authentication
# -----------------------------------------------------------------------------

# Secret key used to sign and verify JWT tokens.
# Generate with: openssl rand -hex 64
# REQUIRED
JWT_SECRET=replace-with-a-long-random-secret-at-least-64-characters


# -----------------------------------------------------------------------------
# Stellar / Horizon
# -----------------------------------------------------------------------------

# Network to connect to. One of: testnet, mainnet, futurenet
# OPTIONAL — default: testnet
STELLAR_NETWORK=testnet

# Horizon API base URL. Defaults to the public testnet/mainnet endpoint.
# OPTIONAL
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# HTTP request timeout in seconds for Horizon calls.
# OPTIONAL — default: 15
STELLAR_REQUEST_TIMEOUT=15

# Maximum number of retries for failed Horizon requests.
# OPTIONAL — default: 3
STELLAR_MAX_RETRIES=3

# Stellar health check interval in seconds.
# OPTIONAL — default: 30
STELLAR_HEALTH_CHECK_INTERVAL=30

# System wallet used to send cNGN to users on onramp.
# REQUIRED for onramp/offramp workers
SYSTEM_WALLET_ADDRESS=
SYSTEM_WALLET_SECRET=

# cNGN issuer account address on Stellar.
# REQUIRED for onramp quote generation
CNGN_ISSUER_ADDRESS=


# -----------------------------------------------------------------------------
# Payment Providers
# -----------------------------------------------------------------------------

# Paystack
# REQUIRED if Paystack provider is enabled
PAYSTACK_SECRET_KEY=
PAYSTACK_PUBLIC_KEY=

# Flutterwave
# REQUIRED if Flutterwave provider is enabled
FLUTTERWAVE_SECRET_KEY=
FLUTTERWAVE_PUBLIC_KEY=

# M-Pesa (Safaricom Daraja)
# REQUIRED if M-Pesa provider is enabled
MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=
MPESA_PASSKEY=
MPESA_SHORTCODE=

# External exchange rate API (optional — falls back to fixed rates)
# OPTIONAL
EXTERNAL_RATE_API_URL=
EXTERNAL_RATE_API_KEY=


# -----------------------------------------------------------------------------
# Background Workers
# -----------------------------------------------------------------------------

# Set any of these to "false" to disable the corresponding worker.
# OPTIONAL — all default to true
TX_MONITOR_ENABLED=true
OFFRAMP_PROCESSOR_ENABLED=true
ONRAMP_PROCESSOR_ENABLED=true
BILL_PROCESSOR_ENABLED=true
PAYMENT_POLLER_ENABLED=true
WEBHOOK_RETRY_ENABLED=true
STELLAR_CONFIRM_WORKER_ENABLED=true


# -----------------------------------------------------------------------------
# OpenTelemetry / Distributed Tracing
# -----------------------------------------------------------------------------

# Service name emitted in every span.
# OPTIONAL — default: aframp-backend
OTEL_SERVICE_NAME=aframp-backend

# Fraction of root spans to sample (0.0 – 1.0).
# OPTIONAL — default: 1.0
OTEL_SAMPLING_RATE=1.0

# gRPC endpoint of the OTLP collector (Jaeger, Grafana Tempo, etc.)
# OPTIONAL — default: http://localhost:4317
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317


# -----------------------------------------------------------------------------
# Startup behaviour
# -----------------------------------------------------------------------------

# Set to "true" to skip waiting for the database before starting.
# Useful for running the binary locally without Docker.
# OPTIONAL — default: true (wait is enabled)
RUN_MIGRATIONS=true

# Set to "true" to skip all external service connections (DB, Redis, Stellar).
# Useful for smoke-testing the binary in isolation.
# OPTIONAL — default: false
SKIP_EXTERNALS=false

# -----------------------------------------------------------------------------
# Transparency / Proof-of-Reserves API
# -----------------------------------------------------------------------------
# 64-character lowercase hex string representing the 32-byte Ed25519 seed used
# to sign the /v1/public/transparency response.  Rotate via key management.
# [SECRET in prod] — if unset, an ephemeral key is generated (dev only).
# TRANSPARENCY_SIGNING_KEY=<64-hex-chars>