PIP-0003: Enable DNS-based discv4 peer discovery for Parallax

[andrepatta]

PIP-0003: Enable DNS-based discv4 peer discovery for Parallax

Author: Andre Patta
Status: Draft
Type: Standards Track
Category: Networking
Created: 2025-11-26

Simple Summary

Enable DNS based discv4 peer discovery for Parallax mainnet by wiring KnownDNSNetwork to Parallax specific DNS node lists, following the Ethereum DNS discovery specification (EIP-1459).

Abstract

Parallax currently ships with DNS based discv4 peer discovery disabled. Nodes can only discover peers through static bootnodes, manual peer configuration or previously known peers stored on disk.

This proposal defines DNS node lists for Parallax networks and updates the KnownDNSNetwork helper to return a network appropriate DNS tree for the given genesis hash and protocol. This makes it possible for new nodes to join the network without hard coded bootnodes, improves resilience when bootnodes are down, and aligns Parallax with the more robust discovery model adopted by Ethereum.

Motivation

Right now, Parallax depends on hard coded bootnodes and manual peer configuration for initial peer discovery. This has several drawbacks:

• Centralization risk: If one or more bootnodes go offline or are censored, new nodes may fail to discover the network.
• Operational overhead: Bootnodes must be maintained and upgraded, and clients need a software release to update their addresses.
• Poor UX for new users: Users running a node in a hostile network environment or after long downtime may need to manually specify peers.

EIP-1459 introduced DNS based discovery for Ethereum, where a DNS tree encodes ENR (Ethereum Node Records) for a rotating set of well behaved peers. This mechanism:

• Decouples node discovery from a fixed list of bootnodes;
• Uses standard DNS infrastructure that is globally replicated and cache friendly;
• Is backward compatible and optional for nodes that do not wish to use it.

Parallax should adopt the same approach so that:

• New nodes can join using only the network genesis and DNS;
• The set of initial peers can be updated without client upgrades;
• The network is more robust against failures and targeted attacks on bootnodes.

Specification

Terminology

• DNS tree: A DNS based authenticated data structure as defined in EIP-1459, containing references to ENR entries and subtrees.
• ENR: Ethereum Node Record (EIP-778), used by discv4 to describe a node's identity and reachable endpoints.
• Protocol: The logical protocol namespace used by the discovery system, such as "nodes" or "snap".

Networks

This proposal defines DNS node lists for the following Parallax networks:

• Mainnet: the canonical Parallax production network.

Implementations must map the known genesis hash constants to their respective DNS domains.

Proposed canonical domains (examples, actual domains to be registered by Parallax maintainers):

• Mainnet nodes: nodes.mainnet.parallaxchain.org

These domains will host EIP-1459 compatible DNS trees that encode ENR entries for a rotating set of stable, well connected Parallax nodes.

KnownDNSNetwork behavior

The KnownDNSNetwork function must be updated as follows:

• For unknown genesis hashes, return the empty string.
• For known networks, return a DNS based discovery URL that includes a protocol specific label and the network label.

The function signature is unchanged:

func KnownDNSNetwork(genesis common.Hash, protocol string) string

Example mapping (non normative, concrete domains may differ):

• Mainnet:
  • KnownDNSNetwork(MainnetGenesisHash, "nodes") returns dnsPrefix + "nodes.mainnet.parallaxchain.org"

dnsPrefix is the same constant used by go-ethereum's EIP-1459 implementation (for example enrtree://), and is defined elsewhere in the codebase.

DNS tree requirements

For each configured network domain, the following requirements apply:

1. The root record must be an EIP-1459 compatible DNS tree root, signed by a designated DNS discovery key controlled by the Parallax maintainers.
2. The tree must contain leaf entries that reference ENRs of:
   • Publicly reachable Parallax nodes;
   • Running the current or recent client versions;
   • With high uptime and healthy peer connectivity.
3. The tree must be maintained over time so that:
   • Stale or unreachable nodes are removed;
   • New nodes are added regularly;
   • The set of nodes is geographically and topologically diverse.

The DNS zone and signing infrastructure are out of scope for this EIP but must follow best practices for DNSSEC and key management where applicable.

Rationale

Why DNS based discovery

DNS based discovery has several advantages:

• Resilience: DNS infrastructure is global, cached and replicated. A single bootnode failure does not prevent node discovery.
• Update without client release: New nodes can be added to the tree without changing the client code or shipping a new binary.
• Alignment with Ethereum: Reusing the EIP-1459 mechanism reduces implementation complexity and keeps Parallax closer to well tested, battle hardened discovery code.

Why per network domains

Using separate domains per network keeps discovery data clean and avoids accidental cross network connections. The genesis hash is used to select the appropriate domain, which matches the existing KnownDNSNetwork design.

Optionality

Nodes that do not want to use DNS discovery can still rely on:

• Static bootnodes;
• Manual peers;
• Previously known peers stored on disk.

Enabling KnownDNSNetwork only adds an extra source of potential peers; it does not remove any existing mechanism.

Backwards Compatibility

This change is fully backward compatible:

• Existing nodes with persisted peer tables continue to work as before.
• Nodes that do not use DNS discovery are unaffected.
• For networks without a configured DNS tree, KnownDNSNetwork continues to return an empty string.

The only behavioral change is that nodes which previously had no DNS tree available will now have an extra discovery source once the domains are live.

Security Considerations

DNS poisoning and control of discovery

Since the DNS tree defines which nodes are advertised to new participants, control of the signing key and DNS zone is security sensitive.

Mitigations:

• The discovery tree must be signed with a dedicated key whose private half is held by trusted Parallax maintainers.
• Access to the DNS zone and registrar accounts must follow security best practices, including multi factor authentication and restricted access.
• Clients should verify the EIP-1459 signatures as implemented in go-ethereum. Nodes that serve invalid or unsigned trees must be rejected.

If the DNS tree is compromised, an attacker could attempt to route new nodes through their own peers. However:

• Nodes still accept incoming connections from non DNS discovered peers.
• Existing nodes with established peer tables are largely unaffected.
• The impact can be minimized with swift key and DNS rotation procedures.

Availability

If the DNS service or tree is temporarily unavailable, node discovery falls back to existing mechanisms such as bootnodes and manual peers. Nodes must handle DNS failures gracefully, treating DNS discovery as an optional enhancement rather than a critical dependency.

Privacy

DNS based discovery leaks the fact that a client is attempting to join the Parallax network to any observers of its DNS traffic. This is already the case for bootnode hostnames and many other network interactions. Users requiring stronger privacy can:

• Disable DNS discovery entirely;
• Use privacy preserving DNS transports such as DNS over TLS or DNS over HTTPS.

Test Cases

Implementations should include at least the following tests:

1. Unknown network

   • Input: genesis equal to an unknown hash, protocol = "nodes".
   • Expected: KnownDNSNetwork returns "".

2. Mainnet mapping

   • Input: MainnetGenesisHash, protocol = "nodes".
   • Expected: Return string is non empty and contains "nodes.mainnet.".

3. Unsupported protocol

   • Input: MainnetGenesisHash, protocol = "foo".
   • Expected: KnownDNSNetwork returns "".

4. End to end discovery (integration test)

   • With a live DNS tree and at least one ENR entry:
     • Start a node with an empty peer table.
     • Enable DNS based discovery.
     • Verify that the node discovers and connects to at least one peer within a reasonable time window.

Deployment Considerations

Deployment should proceed in the following phases:

1. DNS infrastructure setup

   • Register the domains (for example parallaxchain.org).
   • Configure DNS hosting and optional DNSSEC.
   • Generate discovery signing keys for each network.

2. Tree bootstrap

   • Bring up a small set of stable, geographically diverse Parallax nodes.
   • Create initial ENRs and build the DNS tree as per EIP-1459.
   • Publish the tree and verify that go-ethereum tools can resolve it.

3. Client release

   • Merge the KnownDNSNetwork changes.
   • Ship a Parallax client release with DNS discovery enabled by default.

4. Monitoring and maintenance

   • Continuously monitor the reachability and health of nodes listed in the tree.
   • Rotate nodes and keys as needed.
   • Document for the community how to contribute candidate nodes for inclusion.

Once deployed, new Parallax nodes will benefit from a more robust, flexible and decentralized discovery mechanism while remaining compatible with existing setups that rely on bootnodes and manual peering.