transport/ethernet: rename config discovery flag to listen

Rename the Ethernet per-interface config flag from discovery to listen,
so the receive/transmit toggle pair reads as the symmetric announce
(transmit) / listen (receive) neighbor-beacon vocabulary. The old
discovery: key is still accepted via a serde alias, so deployed configs
load unchanged; to_yaml re-emits it under the canonical listen: name.
Marked deprecated for removal at the v2 cutover.

Updates the config field + accessor, the transport listen_enabled local,
the one struct-literal test consumer, the chaos sim config generator,
packaged fips.yaml examples, and the classified operator-facing docs
(ethernet neighbor-beacon subsystem prose; the generic Transport
discovery capability prose is left unchanged). Adds a compat parse test
asserting the legacy alias, the new key, and that deny_unknown_fields
still rejects unknown keys. Behavior-neutral.

CHANGELOG.md

@@ -11,6 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- The Ethernet transport's per-interface `discovery` flag was renamed to
+  `listen` (`transports.ethernet.*`) to match the symmetric `announce`
+  (transmit) / `listen` (receive) neighbor-beacon vocabulary. The old
+  `discovery:` key is still accepted via a serde alias, so deployed configs
+  continue to load unchanged; `Config::to_yaml()` re-emits it under the
+  canonical `listen:` name. Update your `fips.yaml` to `listen:`.
+
 - The mesh-lookup control-metrics family is now emitted under the key
   `lookup` in `fipsctl stats metrics` and `show routing`. The former key
   `discovery` is still emitted as a deprecated alias carrying identical
@@ -32,6 +39,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (mesh-lookup) and `node.rendezvous.*` (peer rendezvous). A legacy
   `node.discovery:` block still applies for now with a deprecation warning and
   will be removed; migrate to `node.lookup.*` / `node.rendezvous.*`.
+- The Ethernet `transports.ethernet.discovery` flag, renamed to
+  `transports.ethernet.listen`. The old key is still accepted via a serde
+  alias and will be removed at the v2 cutover; migrate to `listen`.
 
 ### Fixed
 

docs/design/fips-transport-layer.md

@@ -262,7 +262,7 @@ UDP (1500 vs 1472 MTU).
 - **No IP dependency**: Operates below the IP layer. Nodes on the same
   Ethernet segment can communicate without IP addresses or routing
   infrastructure
-- **Broadcast discovery**: Nodes discover each other via periodic beacon
+- **Broadcast neighbor detection**: Nodes discover each other via periodic beacon
   broadcasts on the shared medium, with no static peer configuration required
 - **Higher MTU**: Standard Ethernet frames carry 1500 bytes of payload,
   yielding an effective FIPS MTU of 1499 after the frame type prefix
@@ -293,7 +293,7 @@ socket.
 | Addressing | 6-byte MAC address |
 | Platform | Linux only (`CAP_NET_RAW` required) |
 
-### Beacon Discovery
+### Neighbor Beacons
 
 Ethernet nodes discover peers via broadcast beacons sent to
 ff:ff:ff:ff:ff:ff. Each beacon is a 34-byte frame containing the sender's
@@ -301,7 +301,7 @@ x-only public key. Receiving nodes extract the MAC source address from the
 frame and the public key from the payload, then report the discovered peer
 to FMP.
 
-Four configuration flags control discovery behavior — `discovery`
+Four configuration flags control neighbor behavior — `listen`
 (listen for beacons), `announce` (broadcast beacons), `auto_connect`
 (initiate handshakes to discovered peers), and `accept_connections`
 (accept inbound handshakes). The flag table and per-flag defaults
@@ -310,13 +310,13 @@ under `transports.ethernet.*`.
 
 A typical discoverable node sets `announce`, `auto_connect`, and
 `accept_connections` all true. A passive listener uses just
-`discovery: true` to observe the network without announcing itself.
+`listen: true` to observe the network without announcing itself.
 
 ### WiFi Compatibility
 
 WiFi interfaces in infrastructure (managed) mode work transparently for
 unicast — the mac80211 subsystem handles frame translation between 802.11
-and 802.3. Broadcast beacon discovery is unreliable in managed mode because
+and 802.3. Broadcast neighbor detection is unreliable in managed mode because
 access points commonly isolate clients from each other's broadcast traffic.
 
 Startup logging:
@@ -895,7 +895,7 @@ transitions through `Starting` to `Up` (operational). `stop()` moves to
 | --------- | ------ | ----- |
 | UDP/IP | **Implemented** | Primary transport, AsyncFd/recvmsg, SO_RXQ_OVFL kernel drop detection |
 | TCP/IP | **Implemented** | FMP header-based framing, non-blocking connect, per-connection MSS MTU |
-| Ethernet | **Implemented** | AF_PACKET SOCK_DGRAM, EtherType 0x2121, beacon discovery, Linux only |
+| Ethernet | **Implemented** | AF_PACKET SOCK_DGRAM, EtherType 0x2121, neighbor beacons, Linux only |
 | WiFi | **Implemented** (via Ethernet transport, infrastructure mode) | mac80211 translates 802.11↔802.3; broadcast beacons unreliable through APs |
 | Tor | **Implemented** | Outbound SOCKS5, inbound via onion service, .onion and clearnet addressing |
 | Nym | **Implemented** | Outbound-only SOCKS5 through nym-socks5-client, mixnet anonymity, IP/hostname addressing |

docs/reference/configuration.md

@@ -436,7 +436,7 @@ Requires `CAP_NET_RAW` or running as root. Linux only.
 | `mtu` | u16 | *(auto)* | Override MTU. Default: interface MTU minus 3 (for frame type + length prefix) |
 | `recv_buf_size` | usize | `2097152` | Socket receive buffer size in bytes (2 MB) |
 | `send_buf_size` | usize | `2097152` | Socket send buffer size in bytes (2 MB) |
-| `discovery` | bool | `true` | Listen for discovery beacons from other nodes |
+| `listen` | bool | `true` | Listen for neighbor beacons from other nodes |
 | `announce` | bool | `false` | Broadcast announcement beacons on the LAN |
 | `auto_connect` | bool | `false` | Auto-connect to discovered peers |
 | `accept_connections` | bool | `false` | Accept incoming connection attempts from discovered peers |
@@ -450,7 +450,7 @@ transports:
   ethernet:
     lan:
       interface: "eth0"
-      discovery: true
+      listen: true
       announce: true
     backbone:
       interface: "eth1"
@@ -458,7 +458,7 @@ transports:
 ```
 
 Each named instance operates independently with its own socket and
-discovery state. The instance name is used in log messages and the
+neighbor state. The instance name is used in log messages and the
 `name()` method on the Transport trait.
 
 ### TCP (`transports.tcp.*`)
@@ -840,7 +840,7 @@ peers:
 ### Mixed UDP + Ethernet Example
 
 A node bridging internet peers (UDP) and a local Ethernet segment with
-beacon discovery:
+neighbor beacons:
 
 ```yaml
 node:
@@ -856,7 +856,7 @@ transports:
     mtu: 1472
   ethernet:
     interface: "eth0"
-    discovery: true
+    listen: true
     announce: true
     auto_connect: true
     accept_connections: true
@@ -999,7 +999,7 @@ transports:
   #   mtu: null                      # null = interface MTU - 3 (typically 1497)
   #   recv_buf_size: 2097152         # 2 MB
   #   send_buf_size: 2097152         # 2 MB
-  #   discovery: true                # listen for beacons
+  #   listen: true                   # listen for beacons
   #   announce: false                # broadcast beacons
   #   auto_connect: false            # connect to discovered peers
   #   accept_connections: false      # accept inbound handshakes

docs/reference/security.md

@@ -209,7 +209,7 @@ for the metadata-privacy model and the rejection of onion routing.
 | --------- | --------------- | ------------ | ------ |
 | UDP | None until `bind_addr` set | `0.0.0.0:2121` typical | Operator sets `transports.udp.bind_addr` |
 | TCP | None until `bind_addr` set | None — outbound-only without bind | Operator sets `transports.tcp.bind_addr` |
-| Ethernet | Listens on configured interface (raw `AF_PACKET`) | EtherType 0x2121 on selected interface | Per-flag `discovery`, `announce`, `auto_connect`, `accept_connections` |
+| Ethernet | Listens on configured interface (raw `AF_PACKET`) | EtherType 0x2121 on selected interface | Per-flag `listen`, `announce`, `auto_connect`, `accept_connections` |
 | Tor | None until `directory_service` configured | `127.0.0.1:8443` (loopback only) | Operator sets `transports.tor.directory_service` and configures `HiddenServiceDir` in `torrc` |
 | BLE | Off by default | n/a | Operator enables `transports.ble.*` |
 | Nostr discovery | Off by default | n/a (relay client, not a listener) | Operator sets `node.discovery.nostr.enabled: true` |

docs/tutorials/ground-up-mesh.md

@@ -71,7 +71,7 @@ supplies the rest:
 - **Addressing**: the `fips0` adapter takes an `fd97:...` ULA
   derived from the npub. No DHCP. No SLAAC. The address is
   cryptographically tied to the identity.
-- **Discovery**: each daemon broadcasts a small beacon on the
+- **Neighbor detection**: each daemon broadcasts a small beacon on the
   link advertising its npub; the other daemon's listener picks
   it up and dials in over the same link.
 - **Routing**: the FIPS mesh layer builds its own spanning tree
@@ -177,7 +177,7 @@ different interface names — that is normal.
 
 Edit `/etc/fips/fips.yaml` on **both** nodes. Under
 `transports:`, add an `ethernet:` block. The key settings are
-the four discovery flags — both nodes must opt in to all four,
+the four neighbor flags — both nodes must opt in to all four,
 and they default to off:
 
 ```yaml
@@ -185,7 +185,7 @@ transports:
   ethernet:
     interface: "<eth>"        # the name from Step 1
     announce: true            # broadcast our beacon on the link
-    discovery: true           # listen for beacons (default; shown for clarity)
+    listen: true              # listen for beacons (default; shown for clarity)
     auto_connect: true        # dial peers we discover
     accept_connections: true  # accept dial-ins from peers we discover
 ```
@@ -194,7 +194,7 @@ Each flag does one thing:
 
 - `announce: true` — emit a small beacon every
   `beacon_interval_secs` (default 30s) carrying our npub.
-- `discovery: true` — listen for incoming beacons; populate a
+- `listen: true` — listen for incoming beacons; populate a
   candidate-peer list keyed by source MAC and observed npub.
 - `auto_connect: true` — when we see a beacon from an npub
   we have not yet peered with, initiate the outbound Noise
@@ -218,7 +218,7 @@ is "all four flags on both ends."
 >     lan:
 >       interface: "eth0"
 >       announce: true
->       discovery: true
+>       listen: true
 >       auto_connect: true
 >       accept_connections: true
 >     dongle:
@@ -227,7 +227,7 @@ is "all four flags on both ends."
 >       # ...
 > ```
 >
-> Each named instance runs its own socket and discovery state.
+> Each named instance runs its own socket and neighbor state.
 > A single ground-up link only needs the flat form shown
 > first; named instances become useful when the same node
 > bridges multiple physical segments.
@@ -390,7 +390,7 @@ What you do need on the AP side:
   networks and "secure" enterprise APs ship with it on.
   When client isolation is on, the AP refuses to forward
   station-to-station frames — the broadcast beacons never
-  arrive at the other node, and discovery fails silently.
+  arrive at the other node, and neighbor detection fails silently.
   If beacons aren't crossing, this is the first thing to
   check.
 
@@ -401,7 +401,7 @@ adapter name.
 ### Bluetooth LE (experimental but works)
 
 BLE is a separate transport (`transports.ble.*`) with its own
-discovery model — L2CAP advertisements rather than raw L2
+neighbor-detection model — L2CAP advertisements rather than raw L2
 broadcasts. The shape of the tutorial is the same (advertise +
 scan + auto-connect + accept), but the prerequisites are
 different: BlueZ, `bluetoothd`, an HCI adapter, and the
@@ -424,7 +424,7 @@ Windows builds skip it.
   a radio link), `CAP_NET_RAW`, and a few config flags on each
   end are sufficient. The mesh supplies its own identity,
   addressing, discovery, and routing.
-- **Discovery is a four-flag opt-in.** `announce`, `discovery`,
+- **Neighbor detection is a four-flag opt-in.** `announce`, `listen`,
   `auto_connect`, and `accept_connections` each control one
   thing; both ends must agree before a link will form.
 - **The two modes coexist.** Overlay peers and ground-up peers

packaging/common/fips.yaml

@@ -98,7 +98,7 @@ transports:
   # Ethernet transport — uncomment and set your interface name.
   # ethernet:
   #   interface: "eth0"
-  #   discovery: true
+  #   listen: true
   #   announce: true
   #   auto_connect: true
   #   accept_connections: true

packaging/openwrt-ipk/files/etc/fips/fips.yaml

@@ -83,19 +83,19 @@ transports:
   ethernet:
     wan:
       interface: "eth0"
-      discovery: true
+      listen: true
       announce: true
       auto_connect: true
       accept_connections: true
     wwan:
       interface: "phy0-sta0"
-      discovery: true
+      listen: true
       announce: true
       auto_connect: true
       accept_connections: true
     lan:
       interface: "br-lan"
-      discovery: true
+      listen: true
       announce: true
       auto_connect: true
       accept_connections: true

packaging/systemd/README.install.md

@@ -68,7 +68,7 @@ and set the interface name:
 transports:
   ethernet:
     interface: "eth0"
-    discovery: true
+    listen: true
     announce: true
     auto_connect: true
     accept_connections: true

src/config/transport.rs

@@ -282,9 +282,10 @@ pub struct EthernetConfig {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub send_buf_size: Option<usize>,
 
-    /// Listen for discovery beacons from other nodes. Default: true.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub discovery: Option<bool>,
+    /// Listen for neighbor beacons from other nodes. Default: true.
+    /// (Renamed from `discovery`; the old key is still accepted.)
+    #[serde(default, alias = "discovery", skip_serializing_if = "Option::is_none")]
+    pub listen: Option<bool>,
 
     /// Broadcast announcement beacons on the LAN. Default: false.
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -319,9 +320,9 @@ impl EthernetConfig {
         self.send_buf_size.unwrap_or(DEFAULT_ETHERNET_SEND_BUF)
     }
 
-    /// Whether to listen for discovery beacons. Default: true.
-    pub fn discovery(&self) -> bool {
-        self.discovery.unwrap_or(true)
+    /// Whether to listen for neighbor beacons. Default: true.
+    pub fn listen(&self) -> bool {
+        self.listen.unwrap_or(true)
     }
 
     /// Whether to broadcast announcement beacons. Default: false.
@@ -1046,4 +1047,22 @@ mod tests {
         assert_eq!(parse_bind_port("[::]:443"), Some(443));
         assert_eq!(parse_bind_port("not-a-socket-addr"), None);
     }
+
+    #[test]
+    fn ethernet_listen_accepts_legacy_discovery_alias_and_rejects_unknown() {
+        // (a) The legacy `discovery:` key is still accepted via serde alias.
+        let legacy: EthernetConfig =
+            serde_yaml::from_str("interface: eth0\ndiscovery: true\n").unwrap();
+        assert_eq!(legacy.listen, Some(true));
+
+        // (b) The new canonical `listen:` key parses into the renamed field.
+        let renamed: EthernetConfig =
+            serde_yaml::from_str("interface: eth0\nlisten: true\n").unwrap();
+        assert_eq!(renamed.listen, Some(true));
+
+        // (c) `deny_unknown_fields` still rejects an unknown ethernet key.
+        let bogus: Result<EthernetConfig, _> =
+            serde_yaml::from_str("interface: eth0\nbogus: true\n");
+        assert!(bogus.is_err());
+    }
 }

src/node/tests/ethernet.rs

@@ -83,7 +83,7 @@ async fn make_test_node_ethernet(interface: &str) -> TestNode {
 
     let config = EthernetConfig {
         interface: interface.to_string(),
-        discovery: Some(false),
+        listen: Some(false),
         announce: Some(false),
         accept_connections: Some(true),
         ..Default::default()

src/transport/ethernet/mod.rs

@@ -163,7 +163,7 @@ impl EthernetTransport {
         let transport_id = self.transport_id;
         let packet_tx = self.packet_tx.clone();
         let mtu = self.effective_mtu;
-        let discovery_enabled = self.config.discovery();
+        let listen_enabled = self.config.listen();
         let neighbor_buffer = self.neighbor_buffer.clone();
         let stats = self.stats.clone();
         let recv_socket = socket.clone();
@@ -174,7 +174,7 @@ impl EthernetTransport {
                 transport_id,
                 packet_tx,
                 mtu,
-                discovery_enabled,
+                listen_enabled,
                 neighbor_buffer,
                 stats,
             )
@@ -390,7 +390,7 @@ async fn ethernet_receive_loop(
     transport_id: TransportId,
     packet_tx: PacketTx,
     mtu: u16,
-    discovery_enabled: bool,
+    listen_enabled: bool,
     neighbor_buffer: Arc<NeighborBuffer>,
     stats: Arc<EthernetStats>,
 ) {
@@ -448,7 +448,7 @@ async fn ethernet_receive_loop(
                     FRAME_TYPE_BEACON => {
                         stats.record_beacon_recv();
 
-                        if discovery_enabled && let Some(pubkey) = parse_beacon(&buf[..len]) {
+                        if listen_enabled && let Some(pubkey) = parse_beacon(&buf[..len]) {
                             neighbor_buffer.add_peer(src_mac, pubkey);
                             trace!(
                                 transport_id = %transport_id,

testing/chaos/sim/config_gen.py

@@ -67,7 +67,7 @@ def _build_ethernet_config(iface: str) -> dict:
     """Build an Ethernet transport config dict for a single interface."""
     return {
         "interface": iface,
-        "discovery": True,
+        "listen": True,
         "announce": True,
         "auto_connect": True,
         "accept_connections": True,