Add ENR v5 bootnodes support for DiscV5 discovery

[usmansaleem]

PR description

Add ENR (enr:) bootnode support for DiscV5 discovery by introducing a new v5Bootnodes section in genesis config alongside the existing bootnodes (enode) section.

• Add v5Bootnodes section to genesis config (config.discovery.v5Bootnodes) for ENR-format bootnodes used by DiscV5
• Add getV5BootNodes() to DiscoveryOptions to parse the new section
• Populate mainnet.json with 17 ENR bootnodes from eth-clients/mainnet and hoodi.json with 9 ENR bootnodes from eth-clients/hoodi
• Simplify BesuCommand bootnode parsing: use --Xv5-discovery-enabled flag to determine format (ENR vs enode) instead of prefix detection
• EthNetworkConfig.getNetworkConfig() reads bootnodes and v5Bootnodes independently instead of mixing formats
• Remove dead MAINNET fallback null-checks in RunnerBuilder (record constructor enforces non-null)
• When CLI --bootnodes is provided, clear the unused protocol's bootnode list; genesis defaults keep both lists intact
• Replace heuristic fallback in DiscoveryConfiguration.getBootnodeIdentifiers() with explicit discoveryV5Enabled flag check

DiscV5 peer connection pipeline fixes

• Handle compressed public keys (33-byte 0x02/0x03 prefix) in NodeKeySigner.deriveECDHKeyAgreement used by the discovery library
• Fix candidatePeers() to use isListening() instead of isReadyForConnections() — the latter requires DiscV4 bonding status that is never set for DiscV5-discovered peers, causing all discovered peers to be filtered out
• Filter out the local node record from candidate peers returned by streamLiveNodes()

Documentation change

Once this PR merges, the genesis file can take both discovery v4 bootnodes and discovery v5 bootnodes. Discovery v5 bootnodes will be utilized when --Xv5-discovery-enabled is set to true. This flag is currently experimental, but it will marked as non-experimental in a future PR.

https://besu.hyperledger.org/public-networks/reference/genesis-items#discovery-configuration-items

Example section from hoodi file:

"discovery": {
      "dns": "enrtree://AKA3AM6LPBYEUDMVNU3BSVQJ5AD45Y7YPOHJLEF6W26QOE4VTUDPE@all.hoodi.ethdisco.net",
      "bootnodes": [
        "enode://2112dd3839dd752813d4df7f40936f06829fc54c0e051a93967c26e5f5d27d99d886b57b4ffcc3c475e930ec9e79c56ef1dbb7d86ca5ee83a9d2ccf36e5c240c@134.209.138.84:30303",
        "enode://60203fcb3524e07c5df60a14ae1c9c5b24023ea5d47463dfae051d2c9f3219f309657537576090ca0ae641f73d419f53d8e8000d7a464319d4784acd7d2abc41@209.38.124.160:30303",
        "enode://8ae4a48101b2299597341263da0deb47cc38aa4d3ef4b7430b897d49bfa10eb1ccfe1655679b1ed46928ef177fbf21b86837bd724400196c508427a6f41602cd@134.199.184.23:30303"
      ],
      "v5Bootnodes": [
        "enr:-Mq4QLkmuSwbGBUph1r7iHopzRpdqE-gcm5LNZfcE-6T37OCZbRHi22bXZkaqnZ6XdIyEDTelnkmMEQB8w6NbnJUt9GGAZWaowaYh2F0dG5ldHOIABgAAAAAAACEZXRoMpDS8Zl_YAAJEAAIAAAAAAAAgmlkgnY0gmlwhNEmfKCEcXVpY4IyyIlzZWNwMjU2azGhA0hGa4jZJZYQAS-z6ZFK-m4GCFnWS8wfjO0bpSQn6hyEiHN5bmNuZXRzAIN0Y3CCIyiDdWRwgiMo",
        "enr:-Ku4QLVumWTwyOUVS4ajqq8ZuZz2ik6t3Gtq0Ozxqecj0qNZWpMnudcvTs-4jrlwYRQMQwBS8Pvtmu4ZPP2Lx3i2t7YBh2F0dG5ldHOIAAAAAAAAAACEZXRoMpBd9cEGEAAJEP__________gmlkgnY0gmlwhNEmfKCJc2VjcDI1NmsxoQLdRlI8aCa_ELwTJhVN8k7km7IDc3pYu-FMYBs5_FiigIN1ZHCCIyk",
        "enr:-LK4QAYuLujoiaqCAs0-qNWj9oFws1B4iy-Hff1bRB7wpQCYSS-IIMxLWCn7sWloTJzC1SiH8Y7lMQ5I36ynGV1ASj4Eh2F0dG5ldHOIYAAAAAAAAACEZXRoMpDS8Zl_YAAJEAAIAAAAAAAAgmlkgnY0gmlwhIbRilSJc2VjcDI1NmsxoQOmI5MlAu3f5WEThAYOqoygpS2wYn0XS5NV2aYq7T0a04N0Y3CCIyiDdWRwgiMo",
        "enr:-Ku4QIC89sMC0o-irosD4_23lJJ4qCGOvdUz7SmoShWx0k6AaxCFTKviEHa-sa7-EzsiXpDp0qP0xzX6nKdXJX3X-IQBh2F0dG5ldHOIAAAAAAAAAACEZXRoMpBd9cEGEAAJEP__________gmlkgnY0gmlwhIbRilSJc2VjcDI1NmsxoQK_m0f1DzDc9Cjrspm36zuRa7072HSiMGYWLsKiVSbP34N1ZHCCIyk",
        "enr:-Ku4QNkWjw5tNzo8DtWqKm7CnDdIq_y7xppD6c1EZSwjB8rMOkSFA1wJPLoKrq5UvA7wcxIotH6Usx3PAugEN2JMncIBh2F0dG5ldHOIAAAAAAAAAACEZXRoMpBd9cEGEAAJEP__________gmlkgnY0gmlwhIbHuBeJc2VjcDI1NmsxoQP3FwrhFYB60djwRjAoOjttq6du94DtkQuaN99wvgqaIYN1ZHCCIyk",
        "enr:-OS4QMJGE13xEROqvKN1xnnt7U-noc51VXyM6wFMuL9LMhQDfo1p1dF_zFdS4OsnXz_vIYk-nQWnqJMWRDKvkSK6_CwDh2F0dG5ldHOIAAAAADAAAACGY2xpZW502IpMaWdodGhvdXNljDcuMC4wLWJldGEuM4RldGgykNLxmX9gAAkQAAgAAAAAAACCaWSCdjSCaXCEhse4F4RxdWljgiMqiXNlY3AyNTZrMaECef77P8k5l3PC_raLw42OAzdXfxeQ-58BJriNaqiRGJSIc3luY25ldHMAg3RjcIIjKIN1ZHCCIyg",
        "enr:-LK4QDwhXMitMbC8xRiNL-XGMhRyMSOnxej-zGifjv9Nm5G8EF285phTU-CAsMHRRefZimNI7eNpAluijMQP7NDC8kEMh2F0dG5ldHOIAAAAAAAABgCEZXRoMpDS8Zl_YAAJEAAIAAAAAAAAgmlkgnY0gmlwhAOIT_SJc2VjcDI1NmsxoQMoHWNL4MAvh6YpQeM2SUjhUrLIPsAVPB8nyxbmckC6KIN0Y3CCIyiDdWRwgiMo",
        "enr:-LK4QPYl2HnMPQ7b1es6Nf_tFYkyya5bj9IqAKOEj2cmoqVkN8ANbJJJK40MX4kciL7pZszPHw6vLNyeC-O3HUrLQv8Mh2F0dG5ldHOIAAAAAAAAAMCEZXRoMpDS8Zl_YAAJEAAIAAAAAAAAgmlkgnY0gmlwhAMYRG-Jc2VjcDI1NmsxoQPQ35tjr6q1qUqwAnegQmYQyfqxC_6437CObkZneI9n34N0Y3CCIyiDdWRwgiMo",
        "enr:-KG4QKRSUi4IOAIK_xt5ERrwW_J47wmNCLWFh7Jo0hFE69drZsiZ5Pb5CEcM_njFTTLlIR6SCf67HTcSV1g6hCXdhWkCgmlkgnY0gmlwhLkvrBODaXA2kCoGxcAWAAAYAAAAAAAAABCJc2VjcDI1NmsxoQPU7g2jQGTz8BYbB2vLTb39S_PrcZAehwMM0b3bWsM5rIN1ZHCCIyiEdWRwNoIjKA"
      ]
    }
  },

Activity Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Genesis JSON Config                       │
│                                                             │
│  "config": {                                                │
│    "discovery": {                                           │
│      "bootnodes": ["enode://..."],     ← DiscV4 (enode)     │
│      "v5Bootnodes": ["enr:..."],       ← DiscV5 (ENR)      │
│      "dns": "enrtree://..."            ← DNS discovery      │
│    }                                                        │
│  }                                                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              EthNetworkConfig.getNetworkConfig()             │
│                                                             │
│  Reads both sections independently via DiscoveryOptions:    │
│    enodeBootNodes ← discovery.bootnodes                     │
│    enrBootNodes   ← discovery.v5Bootnodes                   │
│                                                             │
│  Note: GenesisReader.normalizeKeys() lowercases all JSON    │
│  keys, so lookup uses "v5bootnodes" internally.             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│           BesuCommand.updateNetworkConfig()                  │
│                                                             │
│  1. Builder initialized from EthNetworkConfig (both lists)  │
│                                                             │
│  2. Determine protocol: isV5 = --Xv5-discovery-enabled      │
│                                                             │
│  3. Resolve bootnodes (CLI --bootnodes overrides genesis):  │
│     ┌─────────────────────┬────────────────────────────┐    │
│     │  --bootnodes given   │  --bootnodes NOT given     │    │
│     ├─────────────────────┼────────────────────────────┤    │
│     │  Use CLI values      │  Read from genesis:        │    │
│     │  (BootnodeResolver)  │   isV5 → v5Bootnodes      │    │
│     │                     │   !isV5 → bootnodes        │    │
│     └─────────────────────┴────────────────────────────┘    │
│                                                             │
│  4. Set active list; if CLI override, clear the other:      │
│     isV5  → setEnrBootNodes(resolved), clearEnodeBootNodes  │
│     !isV5 → setEnodeBootNodes(resolved), clearEnrBootNodes  │
│                                                             │
│  5. Empty --bootnodes → clears both lists                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    RunnerBuilder                             │
│                                                             │
│  Sets both lists on DiscoveryConfiguration:                 │
│    discoveryConfiguration.setEnodeBootnodes(enodeBootNodes)  │
│    discoveryConfiguration.setEnrBootnodes(enrBootNodes)      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│            DefaultPeerDiscoveryAgentFactory                   │
│                                                             │
│  isDiscoveryV5Enabled?                                      │
│    ├── YES → PeerDiscoveryAgentFactoryV5                     │
│    │           └─ uses enrBootnodes only                    │
│    │                                                        │
│    └── NO  → PeerDiscoveryAgentFactoryV4                     │
│               └─ uses enodeBootnodes only                   │
└─────────────────────────────────────────────────────────────┘

Fixed Issue(s)

fixes #9968

Thanks for sending a pull request! Have you done the following?

• Checked out our contribution guidelines?
• Considered documentation and added the doc-change-required label to this PR if updates are required.
• Considered the changelog and included an update if required.
• For database changes (e.g. KeyValueSegmentIdentifier) considered compatibility and performed forwards and backwards compatibility tests

Locally, you can run these tests to catch failures early:

• spotless: ./gradlew spotlessApply
• unit tests: ./gradlew build
• acceptance tests: ./gradlew acceptanceTest
• integration tests: ./gradlew integrationTest
• reference tests: ./gradlew ethereum:referenceTests:referenceTests
• hive tests: Engine or other RPCs modified?

[Copilot]

Pull request overview

Adds explicit ENR (DiscV5) bootnode support alongside existing enode (DiscV4) bootnodes, wiring parsing through config and CLI so both formats can be configured and cleared correctly.

Changes:

• Introduces v5Bootnodes genesis config support and parsing via DiscoveryOptions.getV5BootNodes()
• Loads ENR bootnodes for mainnet/hoodi and validates via updated tests
• Updates CLI/network config plumbing to keep enode vs ENR bootnodes separate and clearable

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
config/src/main/java/org/hyperledger/besu/config/DiscoveryOptions.java	Adds parsing for v5 (ENR) bootnodes
config/src/test/java/org/hyperledger/besu/config/DiscoveryOptionsTest.java	Adds unit tests covering v5bootnodes parsing behavior
config/src/main/resources/mainnet.json	Adds ENR bootnodes list for DiscV5
config/src/main/resources/hoodi.json	Adds ENR bootnodes list for DiscV5
app/src/main/java/org/hyperledger/besu/cli/config/EthNetworkConfig.java	Loads enode and ENR bootnodes independently from genesis
app/src/main/java/org/hyperledger/besu/cli/BesuCommand.java	Simplifies bootnode parsing based on DiscV5 flag; clears both lists on explicit empty
app/src/main/java/org/hyperledger/besu/RunnerBuilder.java	Removes MAINNET fallback null-checks; logs enode+ENR bootnodes
app/src/test/java/org/hyperledger/besu/cli/config/EthNetworkConfigTest.java	Asserts ENR bootnodes load for mainnet/hoodi
app/src/test/java/org/hyperledger/besu/cli/BesuCommandTest.java	Asserts empty --bootnodes clears both enode and ENR lists

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

The comment says ENR identity scheme v4 always uses secp256k1, but the code initializes SECP256K1 using DEFAULT_SIGNATURE_ALGORITHM_TYPE. If the default signature algorithm is ever changed/configurable, ENR public-key decompression would use the wrong curve. Use an explicit secp256k1 algorithm/type (e.g., a dedicated SECP256K1/SECP256K1 enum constant or factory selector) rather than the default.

Suggested change

	SignatureAlgorithmType.DEFAULT_SIGNATURE_ALGORITHM_TYPE.get();
	SignatureAlgorithmType.SECP256K1.get();

[usmansaleem]

will not fix. Default Ethereum signature will remain secp256k1. If it ever changes to a different algorithm, the ENR would also reflect the same.

[Copilot]

The comment says ENR identity scheme v4 always uses secp256k1, but the code initializes SECP256K1 using DEFAULT_SIGNATURE_ALGORITHM_TYPE. If the default signature algorithm is ever changed/configurable, ENR public-key decompression would use the wrong curve. Use an explicit secp256k1 algorithm/type (e.g., a dedicated SECP256K1/SECP256K1 enum constant or factory selector) rather than the default.

[macfarla]

think it's worth noting somewhere that while you can specify both types of bootnodes in the genesis, they can't be both used simultaneously

[macfarla]

think it would be more helpful to say "must contain strings of the form enr:-xyz"

[usmansaleem]

I followed how bootnodes were parsed from the genesis configuration file in getBootNodes in the same file.

[usmansaleem]

think it's worth noting somewhere that while you can specify both types of bootnodes in the genesis, they can't be both used simultaneously

Do you mean in the documentation? https://besu.hyperledger.org/public-networks/reference/genesis-items#discovery-configuration-items

[macfarla]

besu.hyperledger.org/public-networks/reference/genesis-items#discovery-configuration-items

now you can specify v4 and v5 bootnodes in the genesis - as long as we doc it so it makes sense for users

[usmansaleem]

besu.hyperledger.org/public-networks/reference/genesis-items#discovery-configuration-items

now you can specify v4 and v5 bootnodes in the genesis - as long as we doc it so it makes sense for users

Added the doc-changed-requried label and updated the PR description as well.

[macfarla]

should this have a changelog entry?

Also a couple of validations that could be added, otherwise LGTM

Missing validation of ENR strings from CLI — When isV5 && cliBootnodesProvided, the raw strings go through BootnodeResolver.resolve() then EthereumNodeRecord.fromEnr(). If the user passes enode URLs with --Xv5-discovery-enabled, they'll get a parse error from fromEnr(). A more helpful error message saying "ENR format expected when V5 discovery is enabled" would improve UX.

No test for CLI --bootnodes with V5 enabled — The BesuCommandTest changes verify empty bootnodes behavior, but there's no test covering the isV5 = true path where --bootnodes enr:... is provided via CLI. This is the main new code path.