env.example

# Core server binding.
HOST=0.0.0.0
PORT=8080

# Admin auth (Bearer token for /admin/api/**).
ADMIN_PASSWORD=change-me

# Persistent storage paths (disk).
DB_PATH=/var/lib/renderer/renderer.db
CACHE_DIR=/var/cache/renderer
# Admin-managed fallback assets (disk).
# Fallbacks are not cache; keep outside CACHE_DIR.
FALLBACKS_DIR=/var/lib/renderer/fallbacks
# Pinned IPFS store (never evicted).
PINNING_ENABLED=true
PINNED_DIR=/var/lib/renderer/pinned
# Local IPFS gateway (loopback only).
LOCAL_IPFS_ENABLED=true
LOCAL_IPFS_BIND=127.0.0.1
LOCAL_IPFS_PORT=18180

# Cache sizing + eviction (disk, not RAM).
# CACHE_MAX_SIZE_GB is GiB (1024^3 bytes) for *total* cache dir size.
CACHE_MAX_SIZE_GB=50
RENDER_CACHE_MIN_TTL_DAYS=7
ASSET_CACHE_MIN_TTL_DAYS=30
# Touch cached files at most once per interval (mtime bump for LRU-ish eviction).
CACHE_TOUCH_INTERVAL_SECONDS=300
CACHE_EVICT_INTERVAL_SECONDS=3600
# How often cached size stats are refreshed (used for /admin cache stats).
CACHE_SIZE_REFRESH_SECONDS=300

# Concurrency and rate limits.
MAX_CONCURRENT_RENDERS=4
MAX_CONCURRENT_IPFS_FETCHES=16
MAX_CONCURRENT_RPC_CALLS=16
# Cap CPU-heavy spawn_blocking tasks (defaults to CPU count if unset).
MAX_BLOCKING_TASKS=4
# Limit heavy SVG rasterization to avoid tail spikes.
HEAVY_SVG_CONCURRENCY=1
MAX_IN_FLIGHT_REQUESTS=512
MAX_ADMIN_BODY_BYTES=104857600
FALLBACK_UPLOAD_MAX_BYTES=5242880
FALLBACK_UPLOAD_MAX_PIXELS=16000000

# Metrics (Prometheus).
METRICS_PUBLIC=false
METRICS_REQUIRE_ADMIN_KEY=true
# Optional bearer token dedicated to /metrics access (recommended).
METRICS_BEARER_TOKEN=
METRICS_ALLOW_IPS=127.0.0.1/32
METRICS_TOP_IPS=20
METRICS_TOP_COLLECTIONS=50
METRICS_TOP_FAILURE_COLLECTIONS=50
METRICS_TOP_SOURCES=50
METRICS_TOP_FAILURE_REASONS=20
METRICS_TOP_SOURCE_FAILURE_REASONS=100
METRICS_IP_LABEL_MODE=sha256_prefix
# Set to 0 to disable the refresh loop entirely.
METRICS_REFRESH_INTERVAL_SECONDS=10
METRICS_EXPENSIVE_REFRESH_SECONDS=300

# Token override cache (to avoid hot-path DB reads).
TOKEN_OVERRIDE_CACHE_TTL_SECONDS=30
TOKEN_OVERRIDE_CACHE_CAPACITY=100000

# IP-based rate limiting (0 disables).
RATE_LIMIT_PER_MINUTE=0
RATE_LIMIT_BURST=0
# Required for ACCESS_MODE=open when rate limits are disabled.
I_KNOW_WHAT_I_AM_DOING=false

# Access control:
# ACCESS_MODE=open | key_required | hybrid | denylist_only | allowlist_only
ACCESS_MODE=open
API_KEY_SECRET=change-me
KEY_RATE_LIMIT_PER_MINUTE=0
KEY_RATE_LIMIT_BURST=0
AUTH_FAILURE_RATE_LIMIT_PER_MINUTE=0
AUTH_FAILURE_RATE_LIMIT_BURST=0
API_KEY_CACHE_TTL_SECONDS=300
API_KEY_CACHE_CAPACITY=10000
TRACK_KEYS_IN_OPEN_MODE=false

# Trusted proxy CIDRs (JSON array of CIDR strings).
TRUSTED_PROXY_CIDRS='[]'

# Usage tracking / aggregation.
USAGE_TRACKING_ENABLED=true
USAGE_SAMPLE_RATE=0.1
USAGE_CHANNEL_CAPACITY=2000
USAGE_FLUSH_INTERVAL_SECONDS=5
USAGE_FLUSH_MAX_ENTRIES=2000
USAGE_RETENTION_DAYS=7
# Controls how IP-derived identities are stored (usage + failure logs).
IDENTITY_IP_LABEL_MODE=sha256_prefix

# Failure logging (JSON lines, capped file). Set FAILURE_LOG_PATH=off or empty to disable.
# By default, only 5xx plus 401/403/429 are logged.
FAILURE_LOG_PATH=/var/lib/renderer/logs/renderer-failures.log
FAILURE_LOG_MAX_BYTES=102400
FAILURE_LOG_CHANNEL_CAPACITY=2000

# Render queue and layer-level concurrency.
RENDER_QUEUE_CAPACITY=256
# Soft limit for queue depth before rejecting new renders (0 = disabled).
RENDER_QUEUE_SOFT_LIMIT=64
RENDER_LAYER_CONCURRENCY=8
# Total render deadline in seconds (0 = disabled).
RENDER_TIMEOUT_SECONDS=60
# End-to-end request timeout (queue wait + render). Defaults to 2x render timeout.
RENDER_REQUEST_TIMEOUT_SECONDS=120
COMPOSITE_CACHE_ENABLED=true

# Primary asset cache (in-memory).
PRIMARY_ASSET_CACHE_TTL_SECONDS=60
PRIMARY_ASSET_NEGATIVE_TTL_SECONDS=15
PRIMARY_ASSET_CACHE_CAPACITY=10000

# Outbound HTTP client cache (in-memory).
OUTBOUND_CLIENT_CACHE_TTL_SECONDS=900
OUTBOUND_CLIENT_CACHE_CAPACITY=256
DNS_CACHE_TTL_SECONDS=300
DNS_CACHE_CAPACITY=1024

# Default render dimensions and cache epoch fallback.
DEFAULT_CANVAS_WIDTH=1080
DEFAULT_CANVAS_HEIGHT=1512
DEFAULT_CACHE_TIMESTAMP=0
# Default HTTP cache TTL when `cache` is omitted (seconds).
DEFAULT_CACHE_TTL_SECONDS=604800
# Allow anonymous cache overrides within this window (ms).
ANON_CACHE_EPOCH_WINDOW_MS=0

# Raster mismatch policy for layers whose decoded size != canvas size.
# RASTER_MISMATCH_FIXED applies to fixed parts, slot parts, and overlays.
# RASTER_MISMATCH_CHILD applies to equipped child parts.
# Child assets always render at the slot's z (no override).
# Values: error | scale_to_canvas | center_no_scale | top_left_no_scale
RASTER_MISMATCH_FIXED=top_left_no_scale
RASTER_MISMATCH_CHILD=top_left_no_scale

# Per-collection render overrides (JSON map: "chain:collection" => settings).
# Example:
# COLLECTION_RENDER_OVERRIDES='{"base:0xabc...":{"raster_mismatch_child":"scale_to_canvas"}}'
COLLECTION_RENDER_OVERRIDES='{}'

# RPC endpoints (JSON map: chain => [url1, url2, ...]).
RPC_ENDPOINTS='{"ethereum":["https://cloudflare-eth.com","https://rpc.ankr.com/eth"],"base":["https://mainnet.base.org"],"moonbeam":["https://rpc.api.moonbeam.network","https://rpc.ankr.com/moonbeam"],"polygon":["https://polygon-rpc.com","https://rpc.ankr.com/polygon"],"bsc":["https://bsc-dataseed.binance.org","https://rpc.ankr.com/bsc"],"moonriver":["https://rpc.api.moonriver.moonbeam.network"],"moonbase-alpha":["https://rpc.api.moonbase.moonbeam.network"],"base-sepolia":["https://sepolia.base.org"],"hardhat":["http://127.0.0.1:8545"]}'
# Render utils contract addresses (JSON map: chain => address).
# Values copied from shared utils; replace any 0xTODO placeholders if you enable those chains.
RENDER_UTILS_ADDRESSES='{"ethereum":"0x89c85a48d7dd136c152720a0cf2ee0a77fc6da64","base":"0x8c2CA0412c2bf5974535fb8Fcb12bE3B7F36d6aD","moonbeam":"0x415aEcB40E26Cda3D3Db8b475F56198A994501ea","polygon":"0x085Ac5cC465a81A8c6BCdF1DE421a48EBDCF35eb","bsc":"0x17F87355371C08fF0cd782c6423CC6877080cb8d","moonriver":"0xTODO","moonbase-alpha":"0x314e2cb6052de2caBfEbB76b32e531eE5876aEfe","base-sepolia":"0x097C3C5eB5554CbA9B48d4a0d2b07B621A73157E","hardhat":"0x8176614F5c65Da44e08aC1c53BB08a15be01D309"}'
RPC_TIMEOUT_SECONDS=30
RPC_CONNECT_TIMEOUT_SECONDS=5
# Failover: after N consecutive errors, cooldown for N seconds.
RPC_FAILURE_THRESHOLD=2
RPC_FAILURE_COOLDOWN_SECONDS=60

# IPFS + asset limits.
# IPFS_GATEWAYS is a JSON array of base URLs ending with /ipfs/.
IPFS_GATEWAYS='["https://rmrk.myfilebase.com/ipfs/","https://cloudflare-ipfs.com/ipfs/","https://ipfs.io/ipfs/"]'
IPFS_TIMEOUT_SECONDS=30
# Hedge a second gateway after delay (ms). Applies to metadata fetches only. Set 0 to disable.
IPFS_HEDGE_DELAY_MS=250
# Cache repeated IPFS failures (seconds). Set 0 to disable.
# Short TTL for transient errors (timeouts/429/5xx).
IPFS_NEGATIVE_CACHE_SECONDS=60
# Long TTL for 404/410 (likely missing content).
IPFS_NEGATIVE_CACHE_NOT_FOUND_SECONDS=86400
IPFS_NEGATIVE_CACHE_CAPACITY=10000
# Cache CID root after repeated failures across paths (0 disables).
IPFS_NEGATIVE_CACHE_CID_THRESHOLD=3
MAX_METADATA_JSON_BYTES=524288
MAX_SVG_BYTES=2097152
MAX_SVG_NODE_COUNT=200000
# Treat SVGs as "heavy" when complexity exceeds these thresholds.
HEAVY_SVG_NODE_THRESHOLD=20000
HEAVY_SVG_FEATURE_THRESHOLD=200
# Adaptive SVG rasterization for small output widths.
SVG_FAST_PATH_MAX_WIDTH=256
SVG_FAST_PATH_TARGET_WIDTH=512
SCALED_RENDER_MAX_WIDTH=256
MAX_RASTER_BYTES=10485760
MAX_RASTER_RESIZE_BYTES=52428800
MAX_RASTER_RESIZE_DIM=2048
MAX_LAYERS_PER_RENDER=200
MAX_CANVAS_PIXELS=16000000
MAX_TOTAL_RASTER_PIXELS=64000000
MAX_DECODED_RASTER_PIXELS=16000000
MAX_CACHE_VARIANTS_PER_KEY=5
MAX_OVERLAY_LENGTH=64
MAX_BG_LENGTH=64
# SSRF controls.
ALLOW_HTTP=false
ALLOW_PRIVATE_NETWORKS=false

# Approvals (on-chain policy).
REQUIRE_APPROVAL=false
# JSON map: chain => approvals contract address.
APPROVALS_CONTRACTS={"base":"0xYourRendererApprovalsContract"}
APPROVALS_CONTRACT_CHAIN=base
# JSON map: chainId (number) => chain name.
CHAIN_ID_MAP='{"1":"ethereum","56":"bsc","137":"polygon","8453":"base","84532":"base-sepolia","1284":"moonbeam","1285":"moonriver","1287":"moonbase-alpha","31337":"hardhat"}'
# JSON map: chain => start block for watcher.
APPROVAL_START_BLOCKS='{"base":123456}'
APPROVAL_POLL_INTERVAL_SECONDS=30
APPROVAL_CONFIRMATIONS=6
APPROVAL_SYNC_INTERVAL_SECONDS=900
# Negative cache for unknown collections (seconds + capacity).
APPROVAL_NEGATIVE_CACHE_SECONDS=3600
APPROVAL_NEGATIVE_CACHE_CAPACITY=50000
# On-demand approval RPC rate limits for unknown collections (per identity).
APPROVAL_ON_DEMAND_RATE_LIMIT_PER_MINUTE=30
APPROVAL_ON_DEMAND_RATE_LIMIT_BURST=10
APPROVAL_ENUMERATION_ENABLED=true
# 0 disables staleness guardrail; otherwise force recheck when approvals are old.
MAX_APPROVAL_STALENESS_SECONDS=0

# Warmup jobs.
# WARMUP_WIDTHS is JSON array (preset names: thumb/small/medium/large/xl/xxl).
WARMUP_WIDTHS='["medium","large"]'
WARMUP_INCLUDE_OG=true
WARMUP_MAX_TOKENS=1000
WARMUP_MAX_RENDERS_PER_JOB=6
WARMUP_JOB_TIMEOUT_SECONDS=600
# 0 disables; otherwise caps transfer_log block range size.
WARMUP_MAX_BLOCK_SPAN=0
# Max concurrent catalog asset pin workers.
WARMUP_MAX_CONCURRENT_ASSET_PINS=4
# Heavy SVG warmup (pre-rasterization) cap.
HEAVY_WARMUP_MAX_ASSETS=50
# Token state cache TTL (seconds).
TOKEN_STATE_CHECK_TTL_SECONDS=86400
# Token state error cache TTLs (seconds).
TOKEN_STATE_ERROR_TTL_SECONDS=300
TOKEN_STATE_ERROR_PERMANENT_TTL_SECONDS=3600
# Per-collection tokenURI negative cache (seconds / entry cap).
TOKEN_URI_NEGATIVE_CACHE_TTL_SECONDS=300
TOKEN_URI_NEGATIVE_CACHE_CAPACITY=10000
# Collection capability detection cache TTL (seconds).
COLLECTION_CAPABILITIES_TTL_SECONDS=86400
# Fresh revalidation cooldown (seconds) per NFT URL.
FRESH_RATE_LIMIT_SECONDS=300
# Retain fresh limiter rows for this many days (0 disables cleanup).
FRESH_REQUEST_RETENTION_DAYS=7

# Optional landing + status.
LANDING_DIR=/opt/renderer/landing
LANDING=index.html
LANDING_STRICT_HEADERS=true
LANDING_PUBLIC=false
STATUS_PUBLIC=false
# Public OpenAPI spec (bypass access gating when true).
OPENAPI_PUBLIC=true