Skip to content

Update enr.md to document protocol-specific ENR entries (including discng) #5

Description

@srene

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

  1. 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.

  2. 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.

  3. 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.

  4. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions