fix(discv5): resolve ephemeral UDP ports in ENR after bind

When discovery is configured with port 0 (ephemeral bind), the OS
assigns the actual port only after the UDP socket is bound. Previously
NodeRecordManager.updateNodeRecord() was called before the library
resolved the bound port, leaving udp/udp6=0 in the persisted ENR.

Two issues are fixed:

1. The localNodeRecordListener in PeerDiscoveryAgentV5 now detects
   transitions from port 0 to a real port in the library's updated
   NodeRecord. It calls onDiscoveryPortResolved to sync the resolved
   port(s) into NodeRecordManager's primaryEndpoint/ipv6Endpoint
   before calling updateNodeRecord(), so the on-disk ENR contains
   the actual OS-assigned ports.

2. In dual-stack mode both UDP servers bind concurrently, each firing
   the listener once. The listener now defers the ENR write until the
   updated library record shows no remaining port-0 UDP addresses, so
   the seq counter increments exactly once for the combined
   port-resolution event rather than once per server.

A ReentrantLock guards onDiscoveryPortResolved and updateNodeRecord to
prevent a concurrent RocksDB "Busy" collision when both servers fire
their thenAccept callbacks simultaneously.

Signed-off-by: Usman Saleem <usman@usmans.info>

Author: usmansaleem

ethereum/p2p/src/main/java/org/hyperledger/besu/ethereum/p2p/discovery/NodeRecordManager.java

@@ -30,6 +30,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
+import java.util.concurrent.locks.ReentrantLock;
 import java.util.function.Supplier;
 
 import com.google.common.base.Suppliers;
@@ -70,6 +71,8 @@ public class NodeRecordManager {
   private final Supplier<List<Bytes>> forkIdSupplier;
   private final NatService natService;
 
+  private final ReentrantLock lock = new ReentrantLock();
+
   private Optional<DiscoveryPeerV4> localNode = Optional.empty();
   private HostEndpoint primaryEndpoint;
   private Optional<HostEndpoint> ipv6Endpoint = Optional.empty();
@@ -166,50 +169,122 @@ public void initializeLocalNode(final HostEndpoint primary, final Optional<HostE
    *
    * @throws IllegalStateException if the local node has not been initialized
    */
-  public void updateNodeRecord() {
-    final NodeRecordFactory factory = NodeRecordFactory.DEFAULT;
-
-    final Optional<NodeRecord> existingRecord =
-        variablesStorage.getLocalEnrSeqno().map(factory::fromBytes);
-
-    final Bytes ipAddressBytes =
-        Bytes.of(InetAddresses.forString(primaryEndpoint.host()).getAddress());
-
-    final int discoveryPort = primaryEndpoint.discoveryPort();
-    final int listeningPort = primaryEndpoint.tcpPort();
-    final List<Bytes> forkId = forkIdSupplier.get();
+  /**
+   * Updates the stored discovery port after the OS assigns an actual port for an ephemeral (port 0)
+   * bind, then persists the updated ENR to disk.
+   *
+   * <p>Called from the {@code localNodeRecordListener} in {@code PeerDiscoveryAgentV5} when the
+   * discovery library resolves a bound port via {@code onBoundPortResolved}. At that point the
+   * library's {@code LocalNodeRecordStore} already holds the updated record; this method ensures
+   * Besu's own {@link NodeRecordManager} state and the on-disk ENR are kept consistent.
+   *
+   * <p>This is a no-op if the currently stored discovery port is already non-zero.
+   *
+   * @param resolvedPort the actual OS-assigned port
+   * @param isIpv6 {@code true} to update the IPv6 endpoint, {@code false} for IPv4
+   */
+  public void onDiscoveryPortResolved(final int resolvedPort, final boolean isIpv6) {
+    lock.lock();
+    try {
+      if (isIpv6) {
+        if (ipv6Endpoint.map(ep -> ep.discoveryPort() != 0).orElse(false)) {
+          return;
+        }
+        ipv6Endpoint =
+            ipv6Endpoint.map(ep -> new HostEndpoint(ep.host(), resolvedPort, ep.tcpPort()));
+      } else {
+        if (primaryEndpoint.discoveryPort() != 0) {
+          return;
+        }
+        primaryEndpoint =
+            new HostEndpoint(primaryEndpoint.host(), resolvedPort, primaryEndpoint.tcpPort());
+      }
+      updateNodeRecord();
+    } finally {
+      lock.unlock();
+    }
+  }
 
-    final boolean primaryIsIpv4 = ipAddressBytes.size() == 4;
+  /**
+   * Updates the stored discovery endpoints with the actual OS-assigned ports after an ephemeral
+   * (port 0) bind.
+   *
+   * <p>Each argument is only applied when present and only if the currently stored port is 0. The
+   * caller is responsible for invoking {@link #updateNodeRecord()} afterwards to persist the
+   * change.
+   *
+   * @param resolvedIpv4Port the actual OS-assigned IPv4 UDP port, or empty if unchanged
+   * @param resolvedIpv6Port the actual OS-assigned IPv6 UDP port, or empty if unchanged
+   */
+  public void onDiscoveryPortResolved(
+      final Optional<Integer> resolvedIpv4Port, final Optional<Integer> resolvedIpv6Port) {
+    lock.lock();
+    try {
+      if (resolvedIpv4Port.isPresent() && primaryEndpoint.discoveryPort() == 0) {
+        primaryEndpoint =
+            new HostEndpoint(
+                primaryEndpoint.host(), resolvedIpv4Port.get(), primaryEndpoint.tcpPort());
+      }
+      if (resolvedIpv6Port.isPresent()
+          && ipv6Endpoint.map(ep -> ep.discoveryPort() == 0).orElse(false)) {
+        ipv6Endpoint =
+            ipv6Endpoint.map(
+                ep -> new HostEndpoint(ep.host(), resolvedIpv6Port.get(), ep.tcpPort()));
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
 
-    final Optional<Bytes> ipv6AddressBytes =
-        ipv6Endpoint.map(ep -> Bytes.of(InetAddresses.forString(ep.host()).getAddress()));
-
-    // Reuse the existing ENR if all relevant fields are unchanged.
-    final NodeRecord nodeRecord =
-        existingRecord
-            .filter(
-                record ->
-                    nodeId.equals(record.get(EnrField.PKEY_SECP256K1))
-                        && (primaryIsIpv4
-                            ? primaryIpv4AddressMatches(
-                                record, ipAddressBytes, discoveryPort, listeningPort)
-                            : primaryIpv6AddressMatches(
-                                record, ipAddressBytes, discoveryPort, listeningPort))
-                        && forkId.equals(record.get(FORK_ID_ENR_FIELD))
-                        && (!primaryIsIpv4 || ipv6FieldsMatch(record, ipv6AddressBytes)))
-            // Otherwise, create a new ENR with an incremented sequence number,
-            // sign it with the local node key, and persist it to disk.
-            .orElseGet(
-                () ->
-                    createAndPersistNodeRecord(
-                        factory,
-                        existingRecord,
-                        ipAddressBytes,
-                        discoveryPort,
-                        listeningPort,
-                        forkId));
-
-    localNode.get().setNodeRecord(nodeRecord);
+  public void updateNodeRecord() {
+    lock.lock();
+    try {
+      final NodeRecordFactory factory = NodeRecordFactory.DEFAULT;
+
+      final Optional<NodeRecord> existingRecord =
+          variablesStorage.getLocalEnrSeqno().map(factory::fromBytes);
+
+      final Bytes ipAddressBytes =
+          Bytes.of(InetAddresses.forString(primaryEndpoint.host()).getAddress());
+
+      final int discoveryPort = primaryEndpoint.discoveryPort();
+      final int listeningPort = primaryEndpoint.tcpPort();
+      final List<Bytes> forkId = forkIdSupplier.get();
+
+      final boolean primaryIsIpv4 = ipAddressBytes.size() == 4;
+
+      final Optional<Bytes> ipv6AddressBytes =
+          ipv6Endpoint.map(ep -> Bytes.of(InetAddresses.forString(ep.host()).getAddress()));
+
+      // Reuse the existing ENR if all relevant fields are unchanged.
+      final NodeRecord nodeRecord =
+          existingRecord
+              .filter(
+                  record ->
+                      nodeId.equals(record.get(EnrField.PKEY_SECP256K1))
+                          && (primaryIsIpv4
+                              ? primaryIpv4AddressMatches(
+                                  record, ipAddressBytes, discoveryPort, listeningPort)
+                              : primaryIpv6AddressMatches(
+                                  record, ipAddressBytes, discoveryPort, listeningPort))
+                          && forkId.equals(record.get(FORK_ID_ENR_FIELD))
+                          && (!primaryIsIpv4 || ipv6FieldsMatch(record, ipv6AddressBytes)))
+              // Otherwise, create a new ENR with an incremented sequence number,
+              // sign it with the local node key, and persist it to disk.
+              .orElseGet(
+                  () ->
+                      createAndPersistNodeRecord(
+                          factory,
+                          existingRecord,
+                          ipAddressBytes,
+                          discoveryPort,
+                          listeningPort,
+                          forkId));
+
+      localNode.get().setNodeRecord(nodeRecord);
+    } finally {
+      lock.unlock();
+    }
   }
 
   private boolean primaryIpv4AddressMatches(

ethereum/p2p/src/main/java/org/hyperledger/besu/ethereum/p2p/discovery/discv5/PeerDiscoveryAgentV5.java

@@ -154,7 +154,39 @@ public CompletableFuture<Integer> start(final int tcpPort) {
         new DiscoverySystemBuilder()
             .signer(new LocalNodeKeySigner(nodeKey))
             .localNodeRecord(localNodeRecord)
-            .localNodeRecordListener((previous, updated) -> nodeRecordManager.updateNodeRecord())
+            .localNodeRecordListener(
+                (previous, updated) -> {
+                  // When onBoundPortResolved resolves ephemeral (port 0) UDP ports, propagate
+                  // the actual ports to NodeRecordManager so the on-disk ENR stays correct.
+                  final Optional<Integer> ipv4ResolvedPort =
+                      previous.getUdpAddress().map(a -> a.getPort() == 0).orElse(false)
+                          ? updated
+                              .getUdpAddress()
+                              .filter(a -> a.getPort() != 0)
+                              .map(InetSocketAddress::getPort)
+                          : Optional.empty();
+                  final Optional<Integer> ipv6ResolvedPort =
+                      previous.getUdp6Address().map(a -> a.getPort() == 0).orElse(false)
+                          ? updated
+                              .getUdp6Address()
+                              .filter(a -> a.getPort() != 0)
+                              .map(InetSocketAddress::getPort)
+                          : Optional.empty();
+                  if (ipv4ResolvedPort.isPresent() || ipv6ResolvedPort.isPresent()) {
+                    nodeRecordManager.onDiscoveryPortResolved(ipv4ResolvedPort, ipv6ResolvedPort);
+                  }
+                  // In dual-stack mode both UDP servers bind concurrently, each firing this
+                  // listener once.  Defer the on-disk ENR write until the updated library
+                  // record shows no remaining port-0 UDP addresses, so the seq counter only
+                  // increments once for the combined port-resolution event.
+                  final boolean udpStillPending =
+                      updated.getUdpAddress().map(a -> a.getPort() == 0).orElse(false);
+                  final boolean udp6StillPending =
+                      updated.getUdp6Address().map(a -> a.getPort() == 0).orElse(false);
+                  if (!udpStillPending && !udp6StillPending) {
+                    nodeRecordManager.updateNodeRecord();
+                  }
+                })
             // Reject external address changes suggested by peers — Besu manages its own
             // advertised address via configuration.
             // TODO: confirm intent with original contributor; previously returned