.env.example

# ============================================================
# Nester — Root Environment Variables
# Copy this file to .env and fill in your values.
# .env is gitignored — never commit it.
# ============================================================

# --- Stellar Network ---
STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_USDC_ISSUER=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
# Protocol operator signing key (S..., 56 chars). Leave blank for read-only mode.
STELLAR_OPERATOR_SECRET=
STELLAR_SOURCE_KEY=
# Default compound flag when POST /api/v1/vaults/{id}/harvest omits "compound".
HARVEST_DEFAULT_COMPOUND=true

# --- API ---
DATABASE_DSN=postgres://nester:nester_dev_password@localhost:5432/nester_dev?sslmode=disable
REDIS_URL=redis://localhost:6379
# Must be a strong random string (>= 32 chars). DO NOT use this default in production.
AUTH_JWT_SECRET=dev-nester-jwt-secret-change-in-production
APP_ENV=development
LOG_LEVEL=info
# Set to "true" to run golang-migrate automatically on startup (used in docker-compose).
RUN_MIGRATIONS=true
PORT=8080

# --- Frontend (dapp) ---
NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080
NEXT_PUBLIC_STELLAR_NETWORK=testnet

# --- Distributed tracing (nester#1054) ---------------------------------
# Opt-in. With TRACING_ENABLED unset the API installs a no-op tracer
# provider, dials no collector, and tracing costs nothing.
# Local setup: docker compose --profile observability up
# See docs/observability/tracing.md
TRACING_ENABLED=false
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
OTEL_EXPORTER_OTLP_INSECURE=true
OTEL_SERVICE_NAME=nester-api
OTEL_EXPORTER_TIMEOUT=10s
# Head sampling probability for normal traffic. Set to 1.0 wherever the
# collector's tail sampler is deployed, otherwise the head discards traces
# the tail would have kept. See the sampling section of the docs.
TRACING_SAMPLE_RATIO=0.05
# Requests at or above this are always retained.
TRACING_LATENCY_THRESHOLD=1s

# --- Metrics and SLOs (nester#1043, #1056) -----------------------------
# The API serves Prometheus exposition on its own listener, separate from
# the public port, so an open /metrics cannot leak internal route names and
# traffic volumes. Keep METRICS_ADDR on loopback unless a scraper needs to
# reach it across the network, and never point it at the public address.
METRICS_ENABLED=true
METRICS_ADDR=127.0.0.1:9090

# Balance freshness (nester#1088). How far behind the chain the event
# indexer's view may fall before the API reports it stale and the
# IndexerStalenessBudgetExceeded alert pages.
#
# 5m is the balance-freshness SLO restated in seconds: 60 ledgers at a ~5s
# close interval is exactly 300s. Healthy operation sits well under 20s — the
# indexer polls every 6s and advances to the tip it just read — so the gap
# absorbs a slow RPC round trip, a rolling restart, and the 12-ledger
# cold-start rewind without paging.
#
# This single value drives the alert threshold AND the X-Indexer-Stale header
# clients read, so they cannot drift apart. Lower it only with the runbook's
# recovery verification steps in mind; a value near the 6s poll interval will
# flap permanently.
INDEXER_STALENESS_BUDGET=5m

# --- Chain circuit breakers (nester#1087) ------------------------------
# Soroban RPC and Horizon each get their own breaker. When one degrades,
# calls to it fail immediately and locally instead of piling onto it until
# they time out — which is what turns a partial upstream outage into a
# total one by exhausting the connection pool.
#
# Independent state, shared policy: a Horizon outage never sheds Soroban
# traffic. See docs/observability/circuit-breakers.md.
#
# The kill switch exists because a resilience mechanism can itself cause an
# outage if its thresholds are wrong for an environment.
CIRCUIT_BREAKER_ENABLED=true
# Share of calls that must fail, within the window, to open the breaker.
CIRCUIT_BREAKER_FAILURE_RATIO=0.5
# Calls that must be observed before the ratio may open it. Without this,
# one failure out of one is a 100% failure ratio and an idle upstream would
# be shed on a single blip.
CIRCUIT_BREAKER_MIN_REQUESTS=10
# How far back outcomes are counted; older ones expire.
CIRCUIT_BREAKER_WINDOW=60s
# How long to shed before admitting a single probe (~3 ledger closes).
CIRCUIT_BREAKER_OPEN_DURATION=15s

# --- Soroban RPC retry (nester#1086) -----------------------------------
# Bounded, jittered retry shared by every Soroban RPC call site, so a
# transient failure is absorbed instead of surfacing as a user-facing error.
#
# ONLY IDEMPOTENT READS ARE RETRIED. sendTransaction never is — a
# resubmitted envelope is a second attempt to move real money — and the
# write path's durability comes from the submission record instead.
#
# The retry loop sits outside the circuit breaker: each attempt is real load
# the breaker should see, and an open breaker stops the loop immediately.
# See docs/observability/circuit-breakers.md.
#
# Set MAX_ATTEMPTS=1 to disable retrying without losing the metrics or the
# typed error.
RPC_RETRY_MAX_ATTEMPTS=3
# Backoff cap for the first retry; doubles per attempt up to MAX_DELAY. The
# delay actually waited is drawn uniformly from [0, cap) — full jitter, so a
# wave of clients that failed together does not retry in lockstep.
RPC_RETRY_BASE_DELAY=100ms
RPC_RETRY_MAX_DELAY=2s
# Total wall-clock allowance for one logical call, backoff included. Applied
# as a context deadline, so one hung attempt cannot outlive it. Keep it below
# SERVER_WRITE_TIMEOUT.
RPC_RETRY_BUDGET=12s

# Local SLO stack (Prometheus, Alertmanager, Grafana):
#   docker compose --profile observability up
# Prometheus http://localhost:9091, Alertmanager http://localhost:9093,
# Grafana http://localhost:3002. See docs/observability/slo.md