.env.example

# ============================================================================
# ACCESS API - ENVIRONMENT CONFIGURATION
# ============================================================================
# Copy this file to .env and fill in the required values.
# The API will fail to start if any REQUIRED settings are missing or malformed.
# ============================================================================

# ============================================================================
# SERVER (Optional - sensible defaults provided)
# ============================================================================

# Port the API listens on (default: 3000)
PORT=3000

# Node environment (default: development)
# Options: development | production | test
NODE_ENV=development

# Logging level (default: info)
# Options: error | warn | info | debug
LOG_LEVEL=info

# ============================================================================
# DATABASE (REQUIRED)
# ============================================================================

# PostgreSQL connection string
# Format: postgresql://user:password@host:port/database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/guildpass"

# ============================================================================
# RATE LIMITING (Optional - sensible defaults provided)
# ============================================================================

# Set to false to disable rate limiting entirely (useful for local development
# or integration tests that fire many requests). Default: true
# RATE_LIMIT_ENABLED=true

# Time window for rate limit counters, in milliseconds (default: 60000 = 1 minute)
# RATE_LIMIT_WINDOW_MS=60000

# Maximum requests per IP per window for standard endpoints (default: 100)
# RATE_LIMIT_DEFAULT_MAX=100

# Maximum requests per IP per window for expensive endpoints such as
# GET /v1/communities/:id/members (default: 20)
# RATE_LIMIT_EXPENSIVE_MAX=20

# ============================================================================
# ACCESS CHECK RATE LIMITING
# ============================================================================

# Maximum requests per IP / API key per window for POST /v1/access/check (default: 100).
# Exceeding the limit returns HTTP 429 with a Retry-After header (seconds).
# ACCESS_CHECK_RATE_LIMIT_IP_MAX=100

# Maximum requests per wallet per window for POST /v1/access/check (default: 50).
# Exceeding the limit returns HTTP 429 with a Retry-After header (seconds).
# ACCESS_CHECK_RATE_LIMIT_WALLET_MAX=50

# Time window for access check rate limit counters, in milliseconds (default: 60000 = 1 minute)
# ACCESS_CHECK_RATE_LIMIT_WINDOW_MS=60000

# Whether to fail open or fail closed if Redis goes down for access checks (default: true = fail open)
# ACCESS_CHECK_RATE_LIMIT_FAIL_OPEN=true

# Which proxies may set X-Forwarded-For. Rate limits key on the client IP, so
# this header is only honoured when the hop it came from is trusted — otherwise
# any caller could send a random value and get a fresh bucket on every request.
# Leave unset (false) when the API is exposed directly. Behind a load balancer
# or ingress, set the number of trusted hops or the proxy addresses/CIDRs.
#   TRUST_PROXY=false             # default — ignore X-Forwarded-For entirely
#   TRUST_PROXY=true              # trust the header unconditionally (dev only)
#   TRUST_PROXY=1                 # trust exactly one hop
#   TRUST_PROXY=10.0.0.0/8,127.0.0.1
# TRUST_PROXY=false

# Optional Redis connection string for distributed rate limiting across multiple
# instances. When omitted, an in-memory store is used (not shared across replicas).
# REDIS_URL="redis://localhost:6379"

# TTL (seconds) for cached GET /v1/communities/:communityId/memberships/:wallet
# responses. Entries are also invalidated on membership mutations, so this only
# bounds staleness for changes that bypass the event pipeline. Default: 30.
# MEMBERSHIP_CACHE_TTL_SECONDS=30

# ============================================================================
# AUTHENTICATION (Optional - sensible defaults provided)
# ============================================================================

# Shared API key gating admin/server-to-server routes (default: "test-api-key").
# Override in every non-local deployment.
# API_KEY="test-api-key"

# Require a verified SIWE session (EIP-4361) on admin/mutation routes. When true,
# the requester wallet is resolved from a Bearer session token issued by
# /v1/auth/verify and the x-wallet/x-user-wallet/x-requester-wallet headers are
# no longer trusted; requests without a valid session get 401. Default false
# preserves the legacy header behaviour so existing clients migrate first (#240).
# SIWE_ENFORCED=false

# ============================================================================
# MEMBERSHIP CHAIN CONFIGURATION
# ============================================================================

# Backward-compatible single-chain defaults. Existing deployments may keep using
# these values; the app treats them as one ChainConfig when MEMBERSHIP_CHAIN_CONFIGS
# is not set.
# MEMBERSHIP_NFT_ADDRESS=""
# CHAIN_ID=31337
# RPC_URL="http://127.0.0.1:8545"

# Preferred multi-chain configuration. Each community can reference one of these
# ChainConfig rows by chainConfigId after seeding/backfilling the database.
# MEMBERSHIP_CHAIN_CONFIGS='[{"name":"local-a","chainId":31337,"rpcUrl":"http://127.0.0.1:8545","membershipNftAddress":"0x0000000000000000000000000000000000000001"},{"name":"local-b","chainId":31338,"rpcUrl":"http://127.0.0.1:9545","membershipNftAddress":"0x0000000000000000000000000000000000000002"}]'

# Reserved for future metrics auth
# METRICS_TOKEN=""

# ============================================================================
# RECONCILIATION WORKER (Optional - sensible defaults provided)
# ============================================================================

# How often the membership reconciliation worker runs, in milliseconds (default: 60000)
# RECONCILIATION_INTERVAL_MS=60000

# ============================================================================
# OUTBOX WORKER (Optional - sensible defaults provided)
# ============================================================================

# How often the outbox worker polls for pending events, in milliseconds (default: 10000)
# OUTBOX_WORKER_INTERVAL_MS=10000

# Maximum outbox events processed per worker pass (default: 50)
# OUTBOX_WORKER_BATCH_SIZE=50

# How long a worker's claim on a batch of events is honored before another
# instance may reclaim them, in milliseconds (default: 60000 = 1 minute).
# Needed to run more than one outbox worker instance/shard safely — see the
# "Integration Event Outbox" section of the root README and apps/access-api/README.md.
# OUTBOX_WORKER_CLAIM_LEASE_MS=60000

# Optional stable identity for this process in OutboxEvent.claimedBy and the
# Prometheus worker_id label (default: random UUID per process start).
# Set to a pod name / hostname in multi-instance fleets for attributable metrics.
# OUTBOX_WORKER_ID=

# Number of concurrent outbox worker shards for horizontal scaling (default: 1)
# Each shard independently claims events via SELECT ... FOR UPDATE SKIP LOCKED
# with a claim lease (see OUTBOX_WORKER_CLAIM_LEASE_MS above).
# Throughput scales roughly linearly with shard count up to DB connection limits.
# OUTBOX_WORKER_COUNT=1

# Minimum batch size per shard when backpressure is active (default: 5)
# The worker shrinks its batch under sustained downstream failures and ramps
# back up as the consumer recovers.
# OUTBOX_WORKER_MIN_BATCH_SIZE=5

# Opt-in HMAC-signed HTTP webhook delivery via createWebhookHandler (default: false).
# When true, the outbox worker fans out events to active WebhookSubscription rows
# after the contribution-score handler. Failures use the existing retry/backoff
# and dead-letter store. See README "Production Webhook Handler" and
# docs/webhook-signature-verification.md.
# OUTBOX_WEBHOOK_ENABLED=false

# ============================================================================
# INDEXER WORKER (Optional - sensible defaults provided)
# ============================================================================

# How often the indexer worker polls for new blocks, in milliseconds (default: 5000)
# INDEXER_INTERVAL_MS=5000

# Number of blocks to wait for finality/confirmation depth before processing (default: 12).
# INDEXER_FINALITY_WINDOW, INDEXER_CONFIRMATION_DEPTH, and CONFIRMATION_BLOCKS are aliases (#273).
# INDEXER_FINALITY_WINDOW=12
# INDEXER_CONFIRMATION_DEPTH=12
# CONFIRMATION_BLOCKS=12

# ============================================================================
# ON-CHAIN RECONCILIATION WORKER (Optional - sensible defaults provided)
# ============================================================================

# How often the on-chain reconciliation worker runs, in milliseconds (default: 300000 = 5 minutes)
# ON_CHAIN_RECONCILIATION_INTERVAL_MS=300000

# Max tokens checked per reconciliation pass (default: 50)
# Increase for small communities; lower for cost-sensitive deployments.
# Set to a very large number for exhaustive checks (watch RPC costs).
# ON_CHAIN_RECONCILIATION_SAMPLE_SIZE=50