Configuration Reference

This document describes every environment variable in Lumenqraph, its default value, valid range, which service(s) read it, and the performance/security tradeoff of changing it.

Quick Start

# Minimal (.env.local)
DATABASE_URL=postgres://lumenqraph:lumenqraph@localhost:5432/lumenqraph
RPC_URL=https://soroban-testnet.stellar.org

# Production (see Security Hardening section)
REQUIRE_API_KEY=true
ANON_RATE_LIMIT_PER_MIN=20
RPC_ROUTE_RATE_LIMIT_PER_MIN=5
GRAPHQL_INTROSPECTION_ENABLED=false
WEBHOOK_ENCRYPTION_KEY=<random-hex>

Environment Variables by Service

Database

All services read the database URL.

`DATABASE_URL`

Property	Value
Default	None (required)
Example	`postgres://user:pass@localhost:5432/lumenqraph`
Valid Range	Valid PostgreSQL connection string
Services	Indexer, API, Webhooks
Tradeoff	None — must be set. Use SSL: `?sslmode=require` for production

Soroban RPC

`RPC_URL`

Property	Value
Default	None (required)
Example	`https://soroban-testnet.stellar.org` (testnet) or `https://mainnet.sorobanrpc.com` (mainnet)
Valid Range	Valid HTTPS URL to a Soroban RPC endpoint
Services	Indexer, API
Tradeoff	Trust: Using an untrusted RPC corrupts the index. Throughput: Paid endpoints may offer lower latency

`RPC_TIMEOUT_SECS`

Property	Value
Default	30
Example	`10` (tight), `60` (generous)
Valid Range	1 ≤ timeout ≤ 3600
Services	Indexer, API
Tradeoff	Liveness vs Reliability: Lower timeout fails faster if RPC hangs; higher timeout tolerates slow endpoints but delays failure detection. Recommended: 30–60 for reliable production RPC

Indexer Configuration

The indexer is the core component that reads events from Soroban RPC and indexes them into PostgreSQL.

Contract Filtering

`CONTRACT_IDS`

Property	Value
Default	(empty) — index all contracts
Example	`CADQZ123...,CADQZ456...` (comma-separated)
Valid Range	Comma-separated list of valid Soroban contract addresses (C… strkeys) or empty
Services	Indexer
Tradeoff	Scope vs Cost: Empty = index all contract events (unbounded, high RPC cost). Bounded set (1–100 contracts) = predictable cost, essential for `UPGRADE_WATCH` and optional features. Recommendation: Always set a bounded list for production, even if broad

Example:

# Index all contracts (high RPC cost, unbounded)
CONTRACT_IDS=

# Index specific contracts (predictable cost, UPGRADE_WATCH enabled for free)
CONTRACT_IDS=CADQZ123...,CADQZ456...,CADQZ789...

Polling & Catchup

`POLL_INTERVAL_SECS`

Property	Value
Default	5
Example	`3` (frequent), `15` (conservative)
Valid Range	1 ≤ interval ≤ ∞
Services	Indexer
Tradeoff	Latency vs RPC Throughput: Lower interval = near-real-time indexing but more RPC calls. Higher interval = batch processing, less RPC cost but stale data. Recommended: 3–10 seconds for production

`MAX_CATCHUP_LEDGERS`

Property	Value
Default	4000 (≈5–6 hours at ~5 sec/ledger)
Example	`1000` (1–2 hours), `10000` (12–15 hours)
Valid Range	1 ≤ catchup ≤ ∞ (clamped by RPC retention window)
Services	Indexer
Tradeoff	Recovery Speed vs RPC Load: Higher value allows catching up faster after downtime but risks hitting RPC processing limits (`-32001`). SDF public RPC retention is ~120k ledgers (7 days); paid endpoints may be higher. If you fall further behind, the indexer skips the gap and logs it. Recommended: 4000 for SDF public, higher (10000+) for paid endpoints

`START_LEDGER`

Property	Value
Default	0 (start near chain tip)
Example	`1000000` (start from specific ledger)
Valid Range	0 ≤ ledger ≤ current_tip
Services	Indexer (on first run only)
Tradeoff	Historical Depth vs Sync Time: 0 = start indexing from ~7 days ago (RPC retention). Higher value = skip early history, faster initial sync but shallower index. For new deployments, 0 is typical. Ignored on subsequent runs (cursor advances from DB)

Reorg Handling

`REORG_OVERLAP_LEDGERS`

Property	Value
Default	0 (disabled)
Example	`10` (conservative), `100` (aggressive)
Valid Range	0 ≤ overlap ≤ 10000
Services	Indexer
Tradeoff	Reorg Safety vs RPC Cost: Enabled = re-scan the last N ledgers each cycle, catching shallow reorgs. Cost: N extra RPC calls per cycle. Disabled = trust RPC (most reliable endpoints never reorg after finalization). Recommendation: Enable (10–50) for untrusted/public RPC, disable for trusted private RPC

Example:

# For SDF public RPC (best effort)
REORG_OVERLAP_LEDGERS=20

# For trusted private RPC (skip re-scans, save cost)
REORG_OVERLAP_LEDGERS=0

Data Fetching

`PAGE_SIZE`

Property	Value
Default	1000
Example	`100` (conservative), `5000` (aggressive)
Valid Range	1 ≤ size ≤ 10000
Services	Indexer
Tradeoff	Throughput vs Latency: Larger pages = fewer RPC calls, higher throughput, but longer per-call latency. Smaller pages = finer-grained progress, faster recovery if a request hangs. Recommended: 1000–5000 for most setups

Contract Upgrade Watching

`UPGRADE_WATCH`

Property	Value
Default	Automatic: ON if `CONTRACT_IDS` is set, OFF otherwise
Example	`true` or `false`
Valid Range	`true` \| `false`
Services	Indexer
Tradeoff	Automatic Upgrade Detection vs RPC Cost: When ON, costs 1 RPC call per tracked contract per cycle (cheap for bounded CONTRACT_IDS). When OFF, no upgrade detection. In index-all mode (empty CONTRACT_IDS), enabling this costs 1 call per active contract per cycle (potentially expensive). If STATE_INDEXING=true, UPGRADE_WATCH adds zero cost (already reading each contract). Recommended: Leave as default (auto-enabled when CONTRACT_IDS is set)

Contract State Indexing

`STATE_INDEXING`

Property	Value
Default	`false` (disabled)
Example	`true`
Valid Range	`true` \| `false`
Services	Indexer
Tradeoff	Contract State Snapshots vs RPC Cost: When ON, snapshots each tracked contract's instance storage into `contract_state` table each cycle. Cost: 1 RPC call per tracked contract per cycle. Provides `/contracts/:id/state` endpoint. Recommended: Enable if using CONTRACT_IDS (bounded, predictable cost); optional for index-all (high variable cost)

Per-Key Storage Indexing

`KEY_INDEXING`

Property	Value
Default	`false` (disabled)
Example	`true`
Valid Range	`true` \| `false`
Services	Indexer
Tradeoff	Per-Holder Balances vs RPC Cost: When ON, snapshots per-holder balances into `contract_data` for each holder mentioned in events. Cost: ~1 RPC call per newly-active holder per cycle (variable, can be high for popular tokens). Enables balance queries. Recommended: Pair with CONTRACT_IDS to bound the holder set; use sparingly for high-volume tokens

`KEY_TEMPLATES`

Property	Value
Default	`[]` (empty array)
Example	`[{"symbol":"Balance","events":["transfer","mint"],"params":[1,2],"durability":"persistent","label":"balance"}]`
Valid Range	JSON array of key template objects
Services	Indexer
Tradeoff	Custom State Indexing vs RPC Cost: Each template triggers state fetching for matching events. Advanced feature for custom data models (allowances, liquidity positions, etc.). Cost: ~1 RPC call per template per active key per cycle. Recommended: Use sparingly; reserved for specialized use cases

Template Schema:

{
  "symbol": "string (storage key variant)",
  "events": ["string (event names triggering this key)"],
  "params": [0, 1],  // topic indices to extract addresses from
  "durability": "persistent | temporary",
  "label": "string (optional, for grouping)"
}

`BALANCE_KEY_SYMBOL`

Property	Value
Default	`Balance`
Example	`BalanceV2` (if token renamed the key)
Valid Range	Any valid symbol name
Services	Indexer (when KEY_INDEXING=true)
Tradeoff	None — cosmetic. Customize only if your token doesn't use standard `Balance` symbol

`BALANCE_KEY_DURABILITY`

Property	Value
Default	`persistent`
Example	`temporary`
Valid Range	`persistent` \| `temporary`
Services	Indexer (when KEY_INDEXING=true)
Tradeoff	None — must match the token's schema. Set to `temporary` only if the token stores balances as temporary entries (rare)

Data Retention

`RETENTION_LEDGERS`

Property	Value
Default	0 (disabled, keep all history)
Example	`120960` (7 days at ~5 sec/ledger), `525600` (30 days)
Valid Range	0 ≤ ledgers ≤ ∞
Services	Indexer
Tradeoff	Historical Depth vs Database Size: 0 = unbounded (disk is yours to manage). N > 0 = keep only last N ledgers, pruning older events and state snapshots (newest version per key always kept). Example: ~500 events/ledger at busy contracts, so 120960 ledgers ≈ 60M events ≈ ~50GB disk. Recommended: Tune to your database size cap; free-tier Postgres (~500MB) ≈ 0 ledgers or aggressive retention

API Configuration

The API service serves indexed data over HTTP, with rate limiting and optional API key authentication.

Server Binding

`API_BIND_ADDR`

Property	Value
Default	`0.0.0.0:8080`
Example	`127.0.0.1:3000` (localhost only) or `:8080` (all interfaces)
Valid Range	Valid `ip:port`
Services	API
Tradeoff	Exposure vs Convenience: `0.0.0.0` = accessible from anywhere (expect to be behind a reverse proxy in production with TLS). `127.0.0.1` = localhost only (for development or reverse proxy on same machine)

Authentication

`REQUIRE_API_KEY`

Property	Value
Default	`false` (open access)
Example	`true`
Valid Range	`true` \| `false`
Services	API
Tradeoff	Access Control vs Usability: When ON, all requests require a valid API key header (`X-API-Key`). `/health` and `/metrics` remain public. Recommended: `true` for production to meter usage and prevent abuse

`RPC_REQUIRE_API_KEY`

Property	Value
Default	`false`
Example	`true`
Valid Range	`true` \| `false`
Services	API
Tradeoff	RPC Quota Protection vs Public Simulation: When ON, endpoints that hit RPC (like `/contracts/:id/call` and `/contracts/:id/simulate`) require API key even if REQUIRE_API_KEY=false. Recommended: `true` if you have a shared/expensive RPC quota

Rate Limiting

`ANON_RATE_LIMIT_PER_MIN`

Property	Value
Default	60
Example	`10` (strict), `100` (generous)
Valid Range	1 ≤ limit ≤ ∞
Services	API
Tradeoff	Protection vs Usability: Lower limit = stricter rate limiting (prevents abuse, reduces RPC cost). Higher limit = easier for legitimate users but allows more abuse. Typical: 10–60 req/min per IP. Recommended: Start at 20–30 and tune based on observed legitimate traffic

`RPC_ROUTE_RATE_LIMIT_PER_MIN`

Property	Value
Default	10
Example	`5` (strict), `20` (generous)
Valid Range	1 ≤ limit ≤ ∞
Services	API
Tradeoff	RPC Quota Protection vs User Experience: Applies only to expensive routes (`/contracts/:id/call`, `/contracts/:id/simulate`). These hit upstream RPC directly. Lower limit = protects shared RPC quota. Recommended: 5–10 req/min for public RPC, 20–50 for paid/private RPC

`RATE_LIMIT_TRUST_XFF`

Property	Value
Default	`false`
Example	`true`
Valid Range	`true` \| `false`
Services	API
Tradeoff	Proxy-behind Setup vs Security: When ON, uses `X-Forwarded-For` header to identify client IP (necessary when behind nginx/HAProxy). When OFF, uses connection source IP. Only enable if behind a trusted proxy; otherwise attackers can forge IPs and bypass rate limits. Recommended: `true` if behind reverse proxy, `false` otherwise

CORS

`CORS_ALLOWED_ORIGINS`

Property	Value
Default	(unset — no CORS headers added)
Example	`https://app.example.com,https://dashboard.example.com` or `*`
Valid Range	(empty/unset) \| `*` \| comma-separated HTTPS URLs
Services	API
Tradeoff	Security vs Flexibility: (unset) = strict, browsers enforce same-origin by default (recommended). `*` = permissive but leaks session cookies to all origins (risky). Specific list = balance. Recommended: Use specific origins for production, leave unset for development

GraphQL

`GRAPHQL_INTROSPECTION_ENABLED`

Property	Value
Default	`false`
Example	`true`
Valid Range	`true` \| `false`
Services	API
Tradeoff	Developer Experience vs Security: When ON, exposes GraphQL schema to clients (easier client code generation, but reveals all queries to attackers). When OFF, schema must be obtained separately. Recommended: `false` in production, `true` in development

`GRAPHQL_MAX_DEPTH`

Property	Value
Default	12
Example	`8` (strict), `20` (generous)
Valid Range	1 ≤ depth ≤ ∞
Services	API
Tradeoff	DoS Prevention vs Query Flexibility: Lower depth = prevents deeply-nested queries that could exhaust memory/CPU. Typical legitimate queries are 3–5 levels deep. Recommended: 8–12

`GRAPHQL_MAX_COMPLEXITY`

Property	Value
Default	1000
Example	`500` (strict), `2000` (generous)
Valid Range	1 ≤ complexity ≤ ∞
Services	API
Tradeoff	DoS Prevention vs Query Power: Complexity is estimated per-field. Lower value = prevents expensive aggregations and bulk fetches. Recommended: 500–1000 for production

Body Limits

`MAX_BODY_SIZE_BYTES`

Property	Value
Default	10MB
Example	`1MB` or `100MB`
Valid Range	Any valid byte size
Services	API
Tradeoff	Memory vs Flexibility: Larger limit = accept larger payloads (e.g., GraphQL queries). Smaller = prevent memory exhaustion. Typical: 1–10MB

Webhook Configuration

The webhook service delivers indexed data to subscriber URLs with HMAC-SHA256 signatures.

Service Behavior

`WEBHOOK_TICK_SECS`

Property	Value
Default	3
Example	`1` (frequent), `10` (batched)
Valid Range	1 ≤ ticks ≤ ∞
Services	Webhooks
Tradeoff	Latency vs Database Load: Lower interval = near-real-time deliveries but more frequent DB polls. Higher interval = batched deliveries, less DB load but higher latency. Recommended: 3–5 seconds

`WEBHOOK_BATCH_SIZE`

Property	Value
Default	100
Example	`10` (small batches), `500` (large batches)
Valid Range	1 ≤ batch ≤ ∞
Services	Webhooks
Tradeoff	Throughput vs Database Memory: Larger batches = fetch more deliveries per query, higher throughput. Smaller batches = less memory/query cost. Recommended: 50–200 based on event volume

`WEBHOOK_MAX_ATTEMPTS`

Property	Value
Default	6
Example	`3` (aggressive), `10` (patient)
Valid Range	1 ≤ attempts ≤ ∞
Services	Webhooks
Tradeoff	Reliability vs Database Churn: More attempts = retry failed deliveries longer (recovers from temporary outages). Fewer attempts = fail fast, save database space. Retries use exponential backoff (2^N seconds, max 1 hour). Recommended: 6 for critical webhooks, 3 for best-effort

Timeouts

`WEBHOOK_CONNECT_TIMEOUT_SECS`

Property	Value
Default	5
Example	`3` (tight), `10` (generous)
Valid Range	1 ≤ timeout ≤ 3600
Services	Webhooks
Tradeoff	Liveness vs Reliability: Lower timeout = fail faster if subscriber is down (frees up resources). Higher timeout = tolerates slow networks. Recommended: 3–5 seconds

`WEBHOOK_TOTAL_TIMEOUT_SECS`

Property	Value
Default	10
Example	`5` (tight), `30` (generous)
Valid Range	1 ≤ timeout ≤ 3600
Services	Webhooks
Tradeoff	Liveness vs Reliability: Total time for connect + request. Should be ≥ CONNECT_TIMEOUT. Recommended: 10–30 seconds

Concurrency

`WEBHOOK_MAX_CONCURRENT_PER_HOST`

Property	Value
Default	5
Example	`1` (serialize), `20` (aggressive)
Valid Range	1 ≤ concurrency ≤ ∞
Services	Webhooks
Tradeoff	Throughput vs Target Respect: Limits concurrent deliveries to a single host (e.g., `app.example.com`). Higher = faster delivery but may overwhelm target. Recommended: 2–10 per host

`WEBHOOK_MAX_CONCURRENT_DELIVERIES`

Property	Value
Default	100
Example	`20` (conservative), `500` (aggressive)
Valid Range	1 ≤ concurrency ≤ ∞
Services	Webhooks
Tradeoff	Throughput vs Memory/Connections: Total concurrent deliveries across all hosts. Higher = faster throughput, more memory/TCP connections. Recommended: 50–200 depending on infrastructure

Failure Handling

`WEBHOOK_FAILURE_THRESHOLD`

Property	Value
Default	10
Example	`5` (aggressive), `20` (patient)
Valid Range	1 ≤ threshold ≤ ∞
Services	Webhooks
Tradeoff	Auto-Disable vs Tolerance: If a subscription has N consecutive delivery failures, it's automatically disabled. Lower = faster disable (saves resources). Higher = tolerate intermittent outages. Recommended: 5–10

Security

`WEBHOOK_ENCRYPTION_KEY`

Property	Value
Default	`default-key-for-testing` (insecure!)
Example	`$(openssl rand -hex 32)`
Valid Range	Any string (recommend 32+ random hex chars)
Services	Webhooks
Tradeoff	At-Rest Security vs Complexity: When set, webhook secrets are encrypted in database using pgcrypto AES-128. Enables secure secret storage. Strongly recommended for production. If changed, previously-encrypted secrets cannot be decrypted; rotate keys with caution

Production Setup:

WEBHOOK_ENCRYPTION_KEY="$(openssl rand -hex 32)"

Security Hardening Configuration

Recommended settings for different deployment scenarios.

Development (Local Testing)

# .env.development
DATABASE_URL=postgres://lumenqraph:lumenqraph@localhost:5432/lumenqraph
RPC_URL=https://soroban-testnet.stellar.org

REQUIRE_API_KEY=false
ANON_RATE_LIMIT_PER_MIN=1000
GRAPHQL_INTROSPECTION_ENABLED=true
GRAPHQL_MAX_DEPTH=50
GRAPHQL_MAX_COMPLEXITY=5000

WEBHOOK_TICK_SECS=1
WEBHOOK_BATCH_SIZE=10
WEBHOOK_MAX_ATTEMPTS=2

Staging (Internal Testing)

# .env.staging
DATABASE_URL=postgres://user:pass@db-staging:5432/lumenqraph?sslmode=require
RPC_URL=https://soroban-testnet.stellar.org

REQUIRE_API_KEY=true
ANON_RATE_LIMIT_PER_MIN=100
RPC_ROUTE_RATE_LIMIT_PER_MIN=20
RPC_REQUIRE_API_KEY=false
GRAPHQL_INTROSPECTION_ENABLED=true
GRAPHQL_MAX_DEPTH=15
GRAPHQL_MAX_COMPLEXITY=1000

WEBHOOK_ENCRYPTION_KEY="$(openssl rand -hex 32)"
WEBHOOK_TICK_SECS=3
WEBHOOK_MAX_ATTEMPTS=4
WEBHOOK_FAILURE_THRESHOLD=20

Production (Hardened)

# .env.production
DATABASE_URL=postgres://user:$(openssl rand -hex 16)@db-private:5432/lumenqraph?sslmode=require
RPC_URL=https://your-trusted-soroban-rpc.example.com
RPC_TIMEOUT_SECS=30

# Security
REQUIRE_API_KEY=true
RPC_REQUIRE_API_KEY=true
ANON_RATE_LIMIT_PER_MIN=20
RPC_ROUTE_RATE_LIMIT_PER_MIN=5
RATE_LIMIT_TRUST_XFF=true  # Only if behind trusted reverse proxy

# Hardening
GRAPHQL_INTROSPECTION_ENABLED=false
GRAPHQL_MAX_DEPTH=10
GRAPHQL_MAX_COMPLEXITY=500
CORS_ALLOWED_ORIGINS="https://app.example.com,https://dashboard.example.com"

# Webhooks
WEBHOOK_ENCRYPTION_KEY="$(openssl rand -hex 32)"
WEBHOOK_TICK_SECS=3
WEBHOOK_BATCH_SIZE=100
WEBHOOK_MAX_ATTEMPTS=6
WEBHOOK_FAILURE_THRESHOLD=10
WEBHOOK_CONNECT_TIMEOUT_SECS=5
WEBHOOK_TOTAL_TIMEOUT_SECS=10
WEBHOOK_MAX_CONCURRENT_PER_HOST=5
WEBHOOK_MAX_CONCURRENT_DELIVERIES=100

# Indexing
CONTRACT_IDS="CADQZ...,CADQZ...,..."  # Bounded set (required for production)
POLL_INTERVAL_SECS=5
PAGE_SIZE=1000
MAX_CATCHUP_LEDGERS=4000
RETENTION_LEDGERS=120960  # 7 days

# Logging
RUST_LOG=info,lumenqraph_indexer=warn,lumenqraph_api=warn,lumenqraph_webhooks=warn

Configuration Validation

Lumenqraph validates configuration at startup. Examples of validation errors:

❌ DATABASE_URL is required
❌ RPC_URL is required
❌ invalid CONTRACT_ID C1234: expected a C… strkey
❌ PAGE_SIZE 10001 out of range [1, 10000]; clamping to 10000
❌ POLL_INTERVAL_SECS cannot be zero; clamping to 1
❌ RETENTION_LEDGERS cannot be negative; clamping to 0
❌ BALANCE_KEY_DURABILITY "invalid" not recognized; expected "persistent" or "temporary"
❌ invalid origin in CORS_ALLOWED_ORIGINS: "not-a-url", skipping

Fix errors by adjusting .env and restarting.

Configuration Tips

Tuning for Different Workloads

High-Volume Token (e.g., USDC)

CONTRACT_IDS="CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4" (single token)
KEY_INDEXING=true, KEY_TEMPLATES=[{"symbol":"Balance","events":["mint","burn","transfer","transfer_from"],"params":[1,2],"durability":"persistent"}]
ANON_RATE_LIMIT_PER_MIN=30, RPC_ROUTE_RATE_LIMIT_PER_MIN=10

Multi-Contract Ecosystem

CONTRACT_IDS="C1...,C2...,..." (10–50 contracts)
UPGRADE_WATCH=true, STATE_INDEXING=true
POLL_INTERVAL_SECS=5, PAGE_SIZE=2000
ANON_RATE_LIMIT_PER_MIN=50, RPC_ROUTE_RATE_LIMIT_PER_MIN=15

All-Contracts Indexing (Rare)

CONTRACT_IDS= (empty)
UPGRADE_WATCH=false, STATE_INDEXING=false, KEY_INDEXING=false
POLL_INTERVAL_SECS=10, PAGE_SIZE=5000
RETENTION_LEDGERS=43200 (3 days) — keep DB small
ANON_RATE_LIMIT_PER_MIN=100 (high, since serving many contracts)

Monitoring Configuration Changes

Use cargo audit and cargo deny to check for dependency vulnerabilities after updating:

# After changing RUST_LOG or other config
cargo build --release

# Before deploying
cargo audit
cargo deny check

Uh oh!

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

Configuration Reference

Quick Start

Environment Variables by Service

Database

DATABASE_URL

Soroban RPC

RPC_URL

RPC_TIMEOUT_SECS

Indexer Configuration

Contract Filtering

CONTRACT_IDS

Polling & Catchup

POLL_INTERVAL_SECS

MAX_CATCHUP_LEDGERS

START_LEDGER

Reorg Handling

REORG_OVERLAP_LEDGERS

Data Fetching

PAGE_SIZE

Contract Upgrade Watching

UPGRADE_WATCH

Contract State Indexing

STATE_INDEXING

Per-Key Storage Indexing

KEY_INDEXING

KEY_TEMPLATES

BALANCE_KEY_SYMBOL

BALANCE_KEY_DURABILITY