ar-io/ar-io-node r69

Release 69

on GitHub

This is a recommended release that introduces DNS-based multi-peer discovery via Envoy's Endpoint Discovery Service, enabling automatic Arweave peer detection with health-checked routing and consensus-based failover. It also adds multi-layered HyperBEAM request loop prevention using header, via-chain, and User-Agent detection to block infinite forwarding loops between gateways. Additionally, this release includes comprehensive CDB64 documentation covering operator guides, format specifications, and tooling reference.

Added

• DNS-Based Multi-Peer Discovery with Envoy EDS: Automatic Arweave peer discovery and health-checked routing via Envoy's Endpoint Discovery Service

  • Resolves DNS records (e.g., peers.arweave.xyz) to discover Arweave peers automatically
  • Health-checks peers and classifies them as "full" (complete blockchain data) or "partial" (incomplete) based on sync status
  • Routes requests to fully-synced peers first with automatic failover to partial peers
  • Consensus-based reference height calculation prevents routing to stale or outlier peers
  • New Prometheus metrics for peer discovery, classification, and health check monitoring
  • Configurable via ARWEAVE_PEER_DNS_RECORDS, ARWEAVE_PEER_DNS_PORT, ARWEAVE_PEER_HEALTH_CHECK_INTERVAL_MS, and related environment variables
  • Enabled by default with ENABLE_ARWEAVE_PEER_EDS=true; falls back to static TRUSTED_NODE_HOST when disabled
  • EDS files validated on startup with corrupt files automatically removed and re-seeded

• HyperBEAM Request Loop Prevention: Multi-layered detection of compute-origin requests to prevent infinite forwarding loops between gateways. Local data sources (cache, S3, database) always continue to serve data normally.

  • Header-based detection: Requests with configured headers (default: ao-peer-port) are identified as compute-origin and blocked from remote forwarding. Configurable via SKIP_FORWARDING_HEADERS.
  • Via-chain loop detection: New X-AR-IO-Via header tracks the chain of gateway identities across hops. When a gateway detects its own identity in the via chain, it stops forwarding to prevent loops. Gracefully degrades when ARNS_ROOT_HOST is not configured.
  • User-Agent detection: Requests with missing or empty User-Agent headers skip remote forwarding by default, catching HTTP clients like Erlang's gun (used by HyperBEAM) that don't send a User-Agent. Configurable via SKIP_FORWARDING_EMPTY_USER_AGENT (default: true). Additionally, SKIP_FORWARDING_USER_AGENTS allows specifying User-Agent substrings for case-insensitive matching (e.g., HyperBEAM).

• CDB64 Documentation: Comprehensive documentation for the CDB64 root transaction index feature

  • Operator guide (docs/cdb64-guide.md) covering configuration, monitoring, custom index sources, and troubleshooting
  • Format specification (docs/cdb64-format.md) detailing the CDB64 binary format, key encoding, and location types
  • Tools reference (docs/cdb64-tools.md) documenting all 6 CDB64 CLI tools with usage examples
  • Overview page (docs/cdb64.md) linking all CDB64 documentation
  • Documentation index (docs/INDEX.md) providing a navigable overview of all gateway documentation
  • CDB64 section added to README for quick orientation
  • Glossary entries for CDB64-related terms
  • Fixed default values for CDB64_CACHE_SIZE and CDB64_ROOT_TX_INDEX_SOURCES in docs/envs.md
  • Build script (tools/build-cdb64-napi) for compiling the native CDB64 N-API module from source

Changed

• Updated observer to increase default chunk observation sample rate to 20%

Docker Images