.env.example

# Starting block height for node synchronization (0 = start from the beginning)
# START_HEIGHT=0

# Stop block height for node synchronization (Infinity = keep syncing until stopped)
# STOP_HEIGHT="Infinity"

# Arweave node to use for fetching data
# TRUSTED_NODE_URL="https://arweave.net"

# Arweave node to use for proxying requests
# TRUSTED_GATEWAY_URL="https://arweave.net"

# Trusted gateways configuration (JSON object with URL keys and priority/trust config)
# Simple format (implicitly trusted): TRUSTED_GATEWAYS_URLS='{"https://turbo-gateway.com": 1}'
# Extended format with trust control: TRUSTED_GATEWAYS_URLS='{"https://turbo-gateway.com": 1, "https://arweave.net": {"priority": 2, "trusted": false}}'
# Note: "trusted": false also omits the ar-io-* provenance *query params* (still sent as X-AR-IO-* headers),
# which is required for CDN-fronted gateways like arweave.net that 502 on those query params.
# Rollback lever (default false): set true to revert to sending those query params to every gateway.
# TRUSTED_GATEWAYS_SEND_UNTRUSTED_PARAMS=false
# TRUSTED_GATEWAYS_URLS='{"https://turbo-gateway.com": 1, "https://arweave.net": {"priority": 2, "trusted": false}}'

# Origins to block when forwarding to trusted gateways (comma-separated list)
# TRUSTED_GATEWAYS_BLOCKED_ORIGINS="self.gateway.com,loop.source.net"

# IPs and CIDR ranges to block when forwarding to trusted gateways (comma-separated list)
# TRUSTED_GATEWAYS_BLOCKED_IPS_AND_CIDRS="192.168.1.100/32,10.0.0.0/8,2001:db8::1"

# Client IPs/CIDRs that should only be served from local cache (comma-separated list).
# Requests from these IPs skip all upstream fetching on cache miss. Useful for HA peer
# setups where each node shares its cache but shouldn't do redundant upstream work.
# CACHE_ONLY_CLIENT_IPS_AND_CIDRS="10.0.1.11,10.0.1.12"

# ArNS gateway
# TRUSTED_ARNS_GATEWAY_URL="https://__NAME__.turbo-gateway.com"

# If true, skips the local cache and always fetches headers from the node
# SKIP_CACHE=false

# If true, skips the data cache (read-through data cache) and always fetches data from upstream
# SKIP_DATA_CACHE=false

# Adds an "INSTANCE_ID" field to output logs
# INSTANCE_ID=""

# Sets the format of output logs, accepts "simple" and "json"
# LOG_FORMAT="simple"

# AR.IO node exposed port number
# CORE_PORT=4000
# ENVOY_PORT=3000
# CLICKHOUSE_PORT=9000
# CLICKHOUSE_PORT_2=8123
# CLICKHOUSE_PORT_3=8443
# OBSERVER_PORT=5050

# Number from 0 to 1, representing the probability of a request failing
# SIMULATED_REQUEST_FAILURE_RATE=0

# Arweave wallet address used for staking and rewards
# AR_IO_WALLET=""

# Arweave wallet address used by the observer to upload report data and interact with the AR.IO process
# OBSERVER_WALLET=""

# Solana JSON-RPC endpoint. Required.
# SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# AR.IO Solana program IDs. Required — the SDK ships with mainnet
# placeholders, so devnet/testnet calls without overrides will silently
# miss. See devnet-config.json in the ar-io/solana-ar-io monorepo for
# canonical devnet values.
# ARIO_CORE_PROGRAM_ID=""
# ARIO_GAR_PROGRAM_ID=""
# ARIO_ARNS_PROGRAM_ID=""
# ARIO_ANT_PROGRAM_ID=""

# Solana wallet identities. AR.IO gateways have three distinct roles
# (operator/cranker, observer, report-uploader) that can be wired to one,
# two, three, or four separate wallets. Four supported configurations:
#
#   1. all-Solana single key:     only SOLANA_KEYPAIR_PATH set.
#   2. Solana ops + Arweave:      SOLANA_KEYPAIR_PATH + ARWEAVE_UPLOAD_KEY_FILE
#   3. three Solana keys:         SOLANA_KEYPAIR_PATH + OBSERVER_KEYPAIR_PATH
#                                   + SOLANA_UPLOAD_KEYPAIR_PATH
#   4. two Solana + Arweave:      SOLANA_KEYPAIR_PATH + OBSERVER_KEYPAIR_PATH
#                                   + ARWEAVE_UPLOAD_KEY_FILE
#
# Resolution precedence:
#   operator/cranker          = SOLANA_KEYPAIR_PATH                                (required)
#   observer (save_observations) = OBSERVER_KEYPAIR_PATH   ?? SOLANA_KEYPAIR_PATH
#   upload (Arweave wins if set) = ARWEAVE_UPLOAD_KEY_FILE | ARWEAVE_UPLOAD_JWK
#   upload (Solana fallback)     = SOLANA_UPLOAD_KEYPAIR_PATH ?? observer signer
#
# Required: SOLANA_KEYPAIR_PATH.
# SOLANA_KEYPAIR_PATH="/path/to/operator-keypair.json"
#
# Optional separate observer key. When set, must match the on-chain
# Gateway.observer_address (set via join_network --observer-address or
# update_observer_address later). Falls back to SOLANA_KEYPAIR_PATH.
# OBSERVER_KEYPAIR_PATH="/path/to/observer-keypair.json"
#
# Optional separate Solana key for report uploads (Solana-signed
# ANS-104 bundles via Turbo). Falls back to OBSERVER_KEYPAIR_PATH ??
# SOLANA_KEYPAIR_PATH. Ignored if ARWEAVE_UPLOAD_* is set.
# SOLANA_UPLOAD_KEYPAIR_PATH="/path/to/upload-keypair.json"
#
# Optional Arweave JWK for report uploads. Either as a file path or
# inline JSON. When set, takes precedence over Ethereum/Solana upload
# paths.
# ARWEAVE_UPLOAD_KEY_FILE="/path/to/arweave-jwk.json"
# ARWEAVE_UPLOAD_JWK='{"kty":"RSA",...}'

# Optional Ethereum private key for report uploads. Hex-encoded 32-byte
# key (with or without 0x prefix). Either as a file path or inline.
# Takes precedence over Solana upload paths but not over Arweave.
# Setting envs from MORE THAN ONE chain (arweave + ethereum + solana)
# at once raises a startup error — pick exactly one.
# ETHEREUM_UPLOAD_PRIVATE_KEY_FILE="/path/to/eth-key.hex"
# ETHEREUM_UPLOAD_PRIVATE_KEY="0x..."

# Admin key value used for accessing the admin API
# ADMIN_API_KEY="secret"

# Alternatively use filepath to admin key used for accessing the admin API
# it takes precedence over ADMIN_API_KEY
# ADMIN_API_KEY_FILE="/path/to/admin-key.txt"

# If true, ar.io node will start indexing missing bundles
# BACKFILL_BUNDLE_RECORDS=false

# If true, all indexed bundles will be reprocessed with the new filters (you can use this when you change the filters)
# FILTER_CHANGE_REPROCESS=false

# Only bundles compliant with this filter will be unbundled
# ANS104_UNBUNDLE_FILTER={"never": true}

# Only bundles compliant with this filter will be indexed
# ANS104_INDEX_FILTER={"never": true}

# Root host for ArNS
# ARNS_ROOT_HOST=""

# Protocol setting in process of creating sandbox domain in ArNS (ARNS_ROOT_HOST needs to be set for this env to have any effect)
# SANDBOX_PROTOCOL=""

# If true, start indexing blocks, tx, ANS104 bundles
# START_WRITERS=true

# If true, the observer runs when using docker-compose
# RUN_OBSERVER=false

# Sets target server for webhooks, webhooks disabled if not set
# WEBHOOK_TARGET_SERVERS="http://localhost:3000,http://localhost:3001"

# Sets the webhook index filter, webhooks disabled if both index and block filters are not set
# WEBHOOK_INDEX_FILTER={"never": true}

# Sets the webhook block filter, webhooks disabled if both index and block filters are not set
# WEBHOOK_BLOCK_FILTER={"never": true}

# If true, the observer will start indexing pending tx from the mempool
# ENABLE_MEMPOOL_WATCHER=true

# Sets the mempool polling interval in milliseconds
# MEMPOOL_POLLING_INTERVAL_MS=30000

# Data source retrieval order for on-demand data requests (comma-separated list of sources)
# Available sources: 'trusted-gateways', 'ar-io-network', 'chunks-offset-aware', 'chunks-data-item' (deprecated), 'turbo', 'tx-data'
# ON_DEMAND_RETRIEVAL_ORDER="trusted-gateways,ar-io-network,chunks-offset-aware,tx-data"

# Enable external API searches (GraphQL/Turbo) for finding root transaction when local attributes are incomplete
# ENABLE_DATA_ITEM_ROOT_TX_SEARCH=true

# Allow data retrieval without offset information in offset-aware data sources
# ENABLE_PASSTHROUGH_WITHOUT_OFFSETS=true

# Chunk data retrieval order (comma-separated list of sources)
# Available sources: 'arweave-network', 'ar-io-network', 'legacy-s3'
# CHUNK_DATA_RETRIEVAL_ORDER="arweave-network,ar-io-network"

# Chunk metadata retrieval order (comma-separated list of sources)
# Available sources: 'arweave-network', 'ar-io-network', 'legacy-psql'
# CHUNK_METADATA_RETRIEVAL_ORDER="arweave-network,ar-io-network"

# Parallelism settings for chunk source operations
# CHUNK_DATA_SOURCE_PARALLELISM=1
# CHUNK_METADATA_SOURCE_PARALLELISM=1

# Preferred chunk GET nodes (comma-separated URLs)
# Defaults to data-1 through data-17 and tip-1 through tip-5.arweave.xyz:1984 if not set
# To override defaults, provide your own comma-separated list of URLs
# PREFERRED_CHUNK_GET_NODE_URLS=http://custom1.example.com:1984,http://custom2.example.com:1984

# Preferred chunk POST nodes (comma-separated URLs)
# Defaults to http://tip-2.arweave.xyz:1984 through http://tip-4.arweave.xyz:1984 if not set
# To override defaults, provide your own comma-separated list of URLs
# PREFERRED_CHUNK_POST_NODE_URLS=http://custom1.example.com:1984,http://custom2.example.com:1984

# Arweave POST dry-run mode (for testing without posting to chain)
# If true, simulates both transaction header and chunk submission without posting to Arweave
# Useful for testing apps like ArDrive and large uploads without burning AR tokens
# Returns 200 OK to clients as if transactions were successfully posted
# Works on both port 3000 (Envoy) and port 4000 (direct to core service)
# When enabled, Envoy routes POST /tx and POST /chunk to core for dry-run handling
# When disabled, Envoy routes POST /tx and POST /chunk to trusted Arweave nodes
# GET /tx requests are always proxied to trusted Arweave nodes for retrieving data
# ARWEAVE_POST_DRY_RUN=false

# Skip validation in dry-run mode (for faster testing)
# If true, skips transaction signature and chunk merkle proof validation
# Useful when you want maximum upload speed without verification overhead
# Only applies when ARWEAVE_POST_DRY_RUN=true
# ARWEAVE_POST_DRY_RUN_SKIP_VALIDATION=false

# Include transaction/data item tags as X-Arweave-Tag-* HTTP response headers
# on /raw/:id and /:id endpoints. Disabled by default.
# ARWEAVE_TAG_RESPONSE_HEADERS_ENABLED=true
# ARWEAVE_TAG_RESPONSE_HEADERS_MAX=100
# ARWEAVE_TAG_RESPONSE_HEADERS_MAX_BYTES=8192

# DNS resolution interval for preferred chunk nodes (in seconds)
# DNS resolution reduces lookup overhead by resolving hostnames to IPs on startup
# Applies to both GET and POST nodes
# Set to 0 to disable periodic re-resolution (default: 3600 - 1 hour)
# PREFERRED_CHUNK_NODE_DNS_RESOLUTION_INTERVAL_SECONDS=3600

# ==============================================================================
# ClickHouse Connection (optional; enables the ClickHouse read path)
# ==============================================================================

# ClickHouse HTTP endpoint the core service reads from. Under the bundled
# docker-compose this is http://clickhouse:8123. Leave unset and the gateway
# serves GraphQL from SQLite instead; transactions(...) still works.
# CLICKHOUSE_URL=http://clickhouse:8123

# Username for the core service's ClickHouse connection.
#
# Set this explicitly whenever your ClickHouse uses an account other than
# `default`. Both the core and clickhouse-auto-import fall back to `default`
# when it is unset, so the risk is not one side defaulting differently; it is
# that the importer and the core can end up with different effective
# credentials, for example when only one of the two environments carries the
# password for a non-default account.
#
# The symptom is worth recognising because it does not look like an auth
# problem from the gateway: imports keep succeeding, so ClickHouse appears
# healthy, the healthcheck stays green, and blocks(...) and /raw/<id> keep
# working, while the stable ClickHouse transactions leg fails. The gateway log
# does not carry the reason, because the rejection is raised ClickHouse-side.
# Confirm there rather than guessing from the gateway:
#   SELECT * FROM system.text_log WHERE message LIKE '%Authentication failed%'
#   ORDER BY event_time DESC LIMIT 10;
# CLICKHOUSE_USER=default

# Password for CLICKHOUSE_USER.
# CLICKHOUSE_PASSWORD=

# ==============================================================================
# ClickHouse Auto-Import Configuration (optional)
# ==============================================================================

# Sleep interval between import cycles (seconds, default: 3600)
# CLICKHOUSE_AUTO_IMPORT_SLEEP_INTERVAL=3600

# Height range to process in each batch (default: 10000)  
# CLICKHOUSE_AUTO_IMPORT_HEIGHT_INTERVAL=10000

# Maximum rows per Parquet file (default: 1000000)
# CLICKHOUSE_AUTO_IMPORT_MAX_ROWS_PER_FILE=1000000

# Enable Apache Iceberg metadata generation (default: false)
# ENABLE_ICEBERG_GENERATION=false

# ==============================================================================
# Datasets Configuration
# ==============================================================================

# Enable datasets endpoint at /local/datasets (default: false)
# ENABLE_DATASETS_ENDPOINT=true

# Datasets proxy configuration (optional)
# By default, /local/datasets routes to the core service
# Set these to proxy to an external datasets service
# DATASETS_PROXY_HOST=datasets.example.com
# DATASETS_PROXY_PORT=8080

# ==============================================================================
# OpenTelemetry Configuration
# ==============================================================================

# Enable file-based export of OTEL spans for development/debugging
# When using 'yarn service:start', this defaults to 'true' (can be overridden here)
# When using 'yarn start', this defaults to 'false'
# OTEL_FILE_EXPORT_ENABLED=false

# Path to OTEL spans file (JSONL format)
# OTEL_FILE_EXPORT_PATH=logs/otel-spans.jsonl

# OTEL service name
# OTEL_SERVICE_NAME=ar-io-node

# OTEL tracing sampling rate (1/N spans will be sampled)
# OTEL_TRACING_SAMPLING_RATE_DENOMINATOR=1

# OTLP exporter endpoint (for production telemetry)
# If set, spans/logs will be sent to this endpoint via OTLP protocol
# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io

# OTLP exporter headers (for authentication)
# OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-api-key

# Alternative: Load OTLP headers from file
# OTEL_EXPORTER_OTLP_HEADERS_FILE=/path/to/headers.txt

# OTLP batch log processor settings
# OTEL_BATCH_LOG_PROCESSOR_SCHEDULED_DELAY_MS=2000
# OTEL_BATCH_LOG_PROCESSOR_MAX_EXPORT_BATCH_SIZE=10000

# ------------------------------------------------------------------------------
# OTEL Collector Configuration (for docker-compose deployments)
# ------------------------------------------------------------------------------

# The OTEL Collector implements tail-based sampling to reduce telemetry costs
# by 80-95% while maintaining 100% visibility into errors, performance issues,
# and ALL paid traffic (x402 payments and paid rate limit tokens).
#
# Sampling Policies:
# - 100% of errors (5xx, exceptions)
# - 100% of slow requests (>2s configurable)
# - 100% of x402 paid requests (for billing/compliance)
# - 100% of paid token usage (for revenue tracking)
# - 1% of free-tier successful requests (for baseline metrics)
#
# Architecture: ar-io-node → otel-collector → final destination
#
# By default in docker-compose, traces are sent to the collector (otel-collector:4318)
# which applies intelligent sampling before forwarding to your telemetry backend.

# Final telemetry destination - set based on your backend:
# Honeycomb: https://api.honeycomb.io
# Grafana Cloud Tempo: https://otlp-gateway-prod-us-central-0.grafana.net/otlp
# Datadog: https://trace.agent.datadoghq.com
# New Relic: https://otlp.nr-data.net
# Elastic APM: https://your-deployment.apm.region.cloud.es.io
# OTEL_COLLECTOR_DESTINATION_ENDPOINT=https://api.honeycomb.io

# Backend API Keys - Configure ONE based on your telemetry backend
# Honeycomb API key
# OTEL_COLLECTOR_HONEYCOMB_API_KEY=your-honeycomb-api-key
# Grafana Cloud API key (base64 encoded instance_id:api_key)
# OTEL_COLLECTOR_GRAFANA_CLOUD_API_KEY=your-base64-encoded-key
# Datadog API key
# OTEL_COLLECTOR_DATADOG_API_KEY=your-datadog-api-key
# New Relic license key
# OTEL_COLLECTOR_NEW_RELIC_API_KEY=your-new-relic-license-key
# Elastic APM secret token
# OTEL_COLLECTOR_ELASTIC_API_KEY=your-elastic-secret-token

# Tail sampling: percentage of successful/fast/unpaid traces to sample (1-100)
# Default: 1 (captures 1% of successful requests for baseline metrics)
# OTEL_TAIL_SAMPLING_SUCCESS_RATE=1

# Tail sampling: latency threshold in milliseconds for slow request capture
# Default: 2000 (2 seconds)
# OTEL_TAIL_SAMPLING_SLOW_THRESHOLD_MS=2000

# Tail sampling: percentage of error traces (5xx status codes) to sample (1-100)
# Default: 100 (captures all errors for debugging)
# Reduce only if you have very high error volumes and want to reduce telemetry costs
# OTEL_TAIL_SAMPLING_ERROR_RATE=100

# Tail sampling: percentage of slow request traces to sample (1-100)
# Default: 100 (captures all slow requests for performance analysis)
# Reduce only if you have many slow requests and want to reduce telemetry costs
# OTEL_TAIL_SAMPLING_SLOW_RATE=100

# Tail sampling: percentage of paid traffic traces (x402 verified payments) to sample (1-100)
# Default: 100 (captures all paid traffic for billing/compliance)
# Reduce only if you have very high paid traffic volumes
# OTEL_TAIL_SAMPLING_PAID_TRAFFIC_RATE=100

# Tail sampling: percentage of paid rate limit token usage traces to sample (1-100)
# Default: 100 (captures all paid token usage for billing/compliance)
# Reduce only if you have very high paid token usage volumes
# OTEL_TAIL_SAMPLING_PAID_TOKENS_RATE=100

# OTEL Collector image tag
# OTEL_COLLECTOR_IMAGE_TAG=0.119.0

#
# Index swarm sidecar (optional; enable with the `index-swarm` compose profile)
#
# Publishes the index artifacts this gateway offers and subscribes to those
# published by other gateways, installing and retiring bands under the running
# node. Off unless the profile is enabled. See docs/index-swarm.md.
#
# Runs the core image with a different entrypoint, so CORE_IMAGE_TAG pins both.

# Indexes this gateway publishes. Requires a registry-bound observer key,
# since a subscriber verifies a publication against the observerAddress on
# your gateway's registry record: OBSERVER_PRIVATE_KEY, or the keypair file
# below. Only that one file is mounted; the sidecar never sees the rest of
# the wallets directory.
# INDEX_SWARM_PUBLISH=[{"name":"root-tx-index","kind":"cdb64-root-tx"}]
# INDEX_SWARM_OBSERVER_KEYPAIR_FILE=./wallets/<observer keypair>.json

# Publishers to subscribe to, by registered gateway wallet. The URL is derived
# from the publisher's registry record; set `url` only to override it.
# INDEX_SWARM_SUBSCRIBE=[{"publisher":"<gateway wallet>","name":"root-tx-index"}]

# Optional allowlist that tightens the registry check for private deployments.
# INDEX_SWARM_TRUSTED_PUBLISHERS=

# Health and metrics, bound inside the container. Map the port only if you
# scrape it from outside the compose network.
# INDEX_SWARM_METRICS_PORT=9101

# Host path for the shared volume the gateway also reads.
# INDEX_SWARM_DATA_PATH=./data/indexes

# Container log rotation. Docker's default is unbounded.
# INDEX_SWARM_LOG_MAX_SIZE=50m
# INDEX_SWARM_LOG_MAX_FILE=3

# The torrent engine, for publishing and fetching bands over BitTorrent.
# Without it, bands move over HTTP only. Start it with:
#   docker compose --profile index-swarm --profile index-swarm-torrent \
#     up -d index-swarm index-swarm-engine
# The password is all it takes: with it set, the sidecar uses the compose
# engine (INDEX_SWARM_ENGINE_URL defaults to http://index-swarm-engine:8080).
# ./tools/index-swarm-setup --torrent generates one.
# INDEX_SWARM_ENGINE_AUTH=swarm:<a long random password>

# A publisher's torrents announce to its own closed tracker; open this port,
# and INDEX_SWARM_ENGINE_PORT (TCP and UDP), to peers.
# INDEX_SWARM_TRACKERS=http://<public host>:6969/announce
# INDEX_SWARM_TRACKER_PORT=6969
# INDEX_SWARM_ENGINE_PORT=6881

# The engine refuses private addresses for peers, trackers and WebSeeds, so
# other gateways cannot use it to reach this node's network. Only when the
# swarm itself runs on a private network (gateways on one LAN), turn that off
# and list the LAN tracker a publisher announces to.
# INDEX_SWARM_ENGINE_BLOCK_PRIVATE=false
# INDEX_SWARM_ALLOWED_TRACKERS=http://192.168.1.10:6969/announce