DNS discovery publishes an authenticated list of Ethereum node records. A client needs a DNS name and the public key that signs the list. DNS resolves the list; the signature and content hashes provide its integrity.
Tree URL and root
The URL has this form:
enrtree://<base32-compressed-public-key>@<dns-name>
The username is the base32 encoding of the compressed secp256k1 public key. The root TXT record is:
enrtree-root:v1 e=<enr-root> l=<link-root> seq=<sequence> sig=<signature>
enr-root and link-root identify the roots of the ENR and link subtrees.
sequence is a decimal tree-update number. signature is a 65-byte secp256k1
signature over the root text before sig=. The client knows the signing key
from the enrtree URL.
Tree entries
Each entry is stored in a DNS TXT record below a label derived from an abbreviated Keccak-256 hash of its text. The entry type selects the next step:
| Entry | Meaning |
|---|---|
enrtree-branch:<h1>,<h2>,... |
Child hashes in an intermediate branch. |
enrtree://<key>@<fqdn> |
A signed link to another node list. It is valid only below link-root. |
enr:<node-record> |
A URL-safe base64 ENR. It is valid only below enr-root. |
TXT content must fit within the 512-byte UDP DNS limit. This bounds the number of hashes in one branch but does not bound the total number of records in the tree.
Client process
- Resolve the root TXT record for the configured DNS name.
- Check the
enrtree-root:v1fields, the root signature, and the sequence number. Do not roll back to a lower sequence already accepted for that name. - Resolve a child at its hash subdomain and check that the TXT text hashes to the requested label.
- For a branch, resolve its child hashes. For a link, add the linked signed tree to the discovery set. For an ENR leaf, decode and validate the record.
- Track visited hashes and domains to stop cycles. Traverse in random order and fetch entries when the client needs candidates instead of downloading the full tree during normal operation.
Validation and failure handling
- Reject a root with an invalid signature or a stale sequence number.
- Reject a child whose content does not match its hash label.
- Reject a link outside the link subtree or an ENR outside the ENR subtree.
- Reject an ENR with an invalid signature, encoding, or size.
- Stop traversal when a hash or domain repeats.
- Treat DNS lookup failure as unavailable discovery data. Do not treat it as a failed transport session with a candidate peer.
Design rationale
One signed root authenticates a large, updateable set of records. Hash labels protect each child from changes by an intermediate resolver. The sequence number prevents replacement by an older root. Separate link and ENR subtrees let a client synchronize federation links and node records independently.