.env.example

# Server Configuration
PORT=3000

# API Authentication
# Set this to enable API key authentication
# The frontend's BACKEND_API_KEY must match this value
SERVER_API_KEY=your-secure-api-key-here

# Database Configuration
# PostgreSQL connection string
# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
DATABASE_URL=postgresql://user:password@localhost:5432/cgov_db

# Blockfrost API (for reading blockchain data)
# Get your API key from: https://blockfrost.io/
MAINNET_BLOCKFROST_API_KEY=mainnetxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
IPFS_BLOCKFROST_API_KEY=ipfsxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Koios API (for governance data ingestion)
# API Documentation: https://api.koios.rest/
# Get your API key from: https://koios.rest/ (if required)
KOIOS_BASE_URL=https://api.koios.rest/api/v1
KOIOS_API_KEY=your_koios_api_key_here
#
# Koios concurrency/retry tuning for ingestion reliability.
# Lower values reduce burst pressure against Koios at the cost of slower syncs.
KOIOS_MAX_CONCURRENT_REQUESTS=3
KOIOS_MAX_CONCURRENT_VOTE_LIST=1
KOIOS_MAX_CONCURRENT_PROPOSAL_VOTING_SUMMARY=1
KOIOS_MAX_CONCURRENT_PROPOSAL_LIST=1
KOIOS_MAX_CONCURRENT_TIP=1
KOIOS_MAX_CONCURRENT_EPOCH_INFO=1
KOIOS_MAX_CONCURRENT_DREP_EPOCH_SUMMARY=1
KOIOS_MAX_CONCURRENT_DREP_DELEGATORS=1
KOIOS_MAX_CONCURRENT_DREP_VOTING_POWER_HISTORY=1
KOIOS_MAX_CONCURRENT_POOL_INFO=2
KOIOS_NON_429_RETRY_JITTER_MAX_MS=250
KOIOS_NON_429_RETRY_JITTER_HIGH_VOLUME_MAX_MS=250
KOIOS_RETRY_MAX_HIGH_VOLUME=2
KOIOS_RETRY_TIMEOUT_HIGH_VOLUME=1
KOIOS_RETRY_429_HIGH_VOLUME=4
KOIOS_RETRY_MAX_TX_METADATA=2
KOIOS_RETRY_TIMEOUT_TX_METADATA=1
KOIOS_RETRY_MAX_SLOW_ENDPOINT=3
KOIOS_RETRY_TIMEOUT_SLOW_ENDPOINT=2
KOIOS_ADAPTIVE_CONCURRENCY_ENABLED=true
KOIOS_ADAPTIVE_PRESSURE_SCALE_PERCENT=50
KOIOS_ADAPTIVE_COOLDOWN_SCALE_PERCENT=34
KOIOS_TIMEOUT_COOLOFF_THRESHOLD=5
KOIOS_TIMEOUT_COOLOFF_WINDOW_MS=20000
KOIOS_TIMEOUT_COOLOFF_MS=10000
KOIOS_PRESSURE_SHEDDING_ENABLED=true
KOIOS_PRESSURE_WINDOW_MS=30000
KOIOS_PRESSURE_THRESHOLD=5
KOIOS_PRESSURE_COOLDOWN_MS=60000
KOIOS_SKIP_NON_CRITICAL_JOBS_WHEN_DEGRADED=true
KOIOS_HEAVY_JOB_LANE_ENABLED=true
KOIOS_HEAVY_JOB_LANE_TTL_MS=1800000
KOIOS_SKIP_EXPENSIVE_ENRICHMENTS_WHEN_DEGRADED=true
KOIOS_SKIP_TX_METADATA_WHEN_DEGRADED=true
SYNC_ON_READ_SKIP_WHEN_PROPOSAL_SYNC_RUNNING=true
SYNC_ON_READ_SKIP_WHEN_KOIOS_DEGRADED=true
SYNC_ON_READ_PRESSURE_COOLDOWN_MULTIPLIER=3
SYNC_ON_READ_PROPOSAL_GUARD_TTL_MS=120000

# Cron Job Configuration
# Enable or disable automatic proposal sync cron job
ENABLE_CRON_JOBS=true

# Cron schedule for proposal sync (cron syntax)
# Default: */5 * * * * (every 5 minutes)
# Examples:
#   */5 * * * *   - Every 5 minutes
#   */15 * * * *  - Every 15 minutes
#   0 * * * *     - Every hour at minute 0
#   0 */6 * * *   - Every 6 hours
PROPOSAL_SYNC_SCHEDULE=*/5 * * * *

# Cron schedule for DRep and SPO voting power sync (cron syntax)
# Default: 8 0 * * * (once daily at 00:08 UTC)
# Examples:
#   8 0 * * *     - Once daily at 00:08 UTC
#   8 */12 * * *  - Every 12 hours at minute 8
#   8 */6 * * *   - Every 6 hours at minute 8
#   8 * * * *     - Every hour at minute 8
VOTER_POWER_SYNC_SCHEDULE=8 0 * * *

# Deprecated: split analytics jobs now use per-step schedules:
# DREP_INVENTORY_SYNC_SCHEDULE, DREP_INFO_SYNC_SCHEDULE,
# DREP_LIFECYCLE_SYNC_SCHEDULE, EPOCH_TOTALS_SYNC_SCHEDULE, POOL_GROUPS_SYNC_SCHEDULE,
# MISSING_EPOCHS_SYNC_SCHEDULE and DREP_DELEGATOR_SYNC_SCHEDULE.
# EPOCH_ANALYTICS_SYNC_SCHEDULE is ignored by current code.
EPOCH_ANALYTICS_SYNC_SCHEDULE=10 * * * *

# Cron schedule for DRep delegation change sync (cron syntax)
# Default: 52 * * * * (every hour at :52 UTC) — ~24 runs/day; ~70k stakes get a full
# account_info sweep in ~1.2 days at 2500 stakes/run (tune DREP_DELEGATION_ACCOUNT_INFO_MAX_STAKES_PER_RUN in code if inventory grows).
# Examples:
#   52 * * * *    - Every hour at :52 (default; staggered with other jobs)
#   15 */4 * * *  - Every 4 hours at :15 (lower Koios load; longer full sweep)
#   15 3 * * *    - Once daily (only if you raise stakes/run or accept slower sweeps)
DREP_DELEGATOR_SYNC_SCHEDULE=52 * * * *

# Parallel processing concurrency for voter power sync
# Controls how many Koios API calls are made concurrently
# Default: 5, Maximum: 20
# Higher values = faster sync but more API load
VOTER_SYNC_CONCURRENCY=5

# Ingestion DB write concurrency controls
# Lower values reduce write spikes against Postgres.
DREP_INFO_SYNC_CONCURRENCY=2
DELEGATION_PHASE3_UPDATE_CHUNK_SIZE=100

# GitHub API Token
# Required for GitHub development activity tracking
GH_API_TOKEN=your-github-token-here

# Cron schedule for GitHub activity sync (cron syntax)
# Default: */30 * * * * (every 30 minutes)
# Syncs active repos every run; moderate repos at 4am UTC; dormant repos on Sundays at 5am UTC
GITHUB_SYNC_SCHEDULE=*/30 * * * *

# Cron schedule for GitHub aggregation (cron syntax)
# Default: 0 4 * * * (daily at 4am UTC)
# Rolls up recent data into historical aggregates and precomputes network graphs
GITHUB_AGGREGATION_SCHEDULE=0 4 * * *

# Cron schedule for GitHub backfill (cron syntax)
# Default: 15 * * * * (hourly at minute 15)
# Backfills historical data for repositories in batches
GITHUB_BACKFILL_SCHEDULE=15 * * * *

# Batch size for GitHub backfill job
# Default: 10
GITHUB_BACKFILL_BATCH_SIZE=10

# Cron schedule for GitHub repository discovery (cron syntax)
# Default: 0 3 * * 0 (weekly, Sunday at 3am UTC)
# Discovers new repositories in the ecosystem
GITHUB_DISCOVERY_SCHEDULE=0 3 * * 0

# Cron schedule for GitHub daily snapshot (cron syntax)
# Default: 0 1 * * * (daily at 1am UTC)
# Snapshots stars, forks, etc. for all tracked repositories
GITHUB_SNAPSHOT_SCHEDULE=0 1 * * *

# Optional lock TTL overrides (ms) for cross-instance safety on GitHub jobs
STRICT_SYNC_LOCK_ENABLED=true
GITHUB_SYNC_LOCK_TTL_MS=1500000
GITHUB_AGGREGATION_LOCK_TTL_MS=1800000
GITHUB_BACKFILL_LOCK_TTL_MS=2700000
GITHUB_SNAPSHOT_LOCK_TTL_MS=2700000
GITHUB_DISCOVERY_LOCK_TTL_MS=1800000

# Rollback toggles for batched DB write paths
GITHUB_ACTIVITY_BATCHED_DB_WRITES_ENABLED=true
GITHUB_AGGREGATION_BATCHED_DB_WRITES_ENABLED=true

# DB pressure guards for non-critical jobs
DB_SKIP_NON_CRITICAL_JOBS_WHEN_DEGRADED=true
DB_WRITE_QUEUE_SKIP_THRESHOLD=100

# Prisma DB resilience/circuit-breaker settings
DB_RESILIENCE_ENABLED=true
DB_RETRY_MAX_ATTEMPTS=3
DB_RETRY_BASE_DELAY_MS=300
DB_RETRY_MAX_DELAY_MS=5000
DB_RETRY_JITTER_MS=200
DB_CIRCUIT_THRESHOLD=8
DB_CIRCUIT_WINDOW_MS=30000
DB_CIRCUIT_COOLDOWN_MS=20000
DB_WRITE_SEMAPHORE_ENABLED=true
DB_WRITE_MAX_IN_FLIGHT=8
DB_WRITE_QUEUE_MAX_DEPTH=500
INGESTION_DB_FAILFAST_ENABLED=true
INGESTION_DB_FAILFAST_COOLDOWN_MS=60000