Update enr.md to document protocol-specific ENR entries
The current enr.md defines the Record Structure with a core key/value table (id, secp256k1, ip, tcp, udp, ip6, tcp6, udp6) and notes generically that "consensus is not required" for additional keys. It does not list or formally define any of the protocol-specific extension entries that have been added to ENR over time.
Some extension entries are referenced in other docs but not catalogued in enr.md itself:
eth — eth protocol fork-id / cap, referenced in caps/eth.md
snap — referenced in caps/snap.md
discng — added by the new DISC-NG section in discv5/discv5-theory.md (commit 7111aa5). Capability flag for service discovery.
It would help implementations to have a single place in enr.md listing all standardised ENR entries together with their key names, value formats, and semantics. Otherwise implementers have to grep across the protocol docs to discover them.
Specific items for this update
-
Add an "Extension Entries" section to enr.md (after Record Structure) listing protocol-specific keys defined elsewhere in this repo. Format similar to the existing core-key table.
-
Define the discng entry formally. The theory section (discv5/discv5-theory.md) says:
"discng = <version> — The value of discng is an unsigned integer identifying the supported DISC-NG protocol version."
But the go-ethereum DISC-NG implementation uses discng as a presence-only flag (empty struct, no value), not a versioned integer. This is a real divergence: either:
- (A) Update the theory +
enr.md to specify discng as presence-only (no version field). Simplest. Defers versioning to a future revision when needed.
- (B) Update the implementation to write a version integer (e.g.
1 for DISC-NG v1) and update enr.md to define the encoding (uint, semantics on mismatch, etc.).
Need to pick one for enr.md to document the entry correctly.
-
Version-mismatch handling. If discng carries a version, the spec should say what happens when a node observes a peer with an unsupported version:
- Treat the peer as non-DISC-NG (exclude from service tables)?
- Accept if major versions match?
- Reject the ENR?
This is currently undefined.
-
Other DISC-NG ENR keys? If the service binding for a specific service requires payload in the advertiser's ENR (per the theory's "Service-specific connection metadata should be encoded in the ENR where possible"), should enr.md cite where those are defined, or leave that to the per-service binding docs?
Cross-references
Update
enr.mdto document protocol-specific ENR entriesThe current
enr.mddefines the Record Structure with a core key/value table (id,secp256k1,ip,tcp,udp,ip6,tcp6,udp6) and notes generically that "consensus is not required" for additional keys. It does not list or formally define any of the protocol-specific extension entries that have been added to ENR over time.Some extension entries are referenced in other docs but not catalogued in
enr.mditself:eth— eth protocol fork-id / cap, referenced incaps/eth.mdsnap— referenced incaps/snap.mddiscng— added by the new DISC-NG section indiscv5/discv5-theory.md(commit 7111aa5). Capability flag for service discovery.It would help implementations to have a single place in
enr.mdlisting all standardised ENR entries together with their key names, value formats, and semantics. Otherwise implementers have to grep across the protocol docs to discover them.Specific items for this update
Add an "Extension Entries" section to
enr.md(after Record Structure) listing protocol-specific keys defined elsewhere in this repo. Format similar to the existing core-key table.Define the
discngentry formally. The theory section (discv5/discv5-theory.md) says:But the
go-ethereumDISC-NG implementation usesdiscngas a presence-only flag (empty struct, no value), not a versioned integer. This is a real divergence: either:enr.mdto specifydiscngas presence-only (no version field). Simplest. Defers versioning to a future revision when needed.1for DISC-NG v1) and updateenr.mdto define the encoding (uint, semantics on mismatch, etc.).Need to pick one for
enr.mdto document the entry correctly.Version-mismatch handling. If
discngcarries a version, the spec should say what happens when a node observes a peer with an unsupported version:This is currently undefined.
Other DISC-NG ENR keys? If the service binding for a specific service requires payload in the advertiser's ENR (per the theory's "Service-specific connection metadata should be encoded in the ENR where possible"), should
enr.mdcite where those are defined, or leave that to the per-service binding docs?Cross-references
discv5/discv5-theory.mdsection "DISC-NG Capability" (introduced in commit 7111aa5)datahop/go-ethereump2p/discover/topicindex/common.go(DiscNG type)