Discovery
How a WeftOS node finds peers at v0.8.4: seed peers dialed at boot, pairing, the leaf discovery socket, and the DiscoveryBackend library (bootstrap, peer exchange, mDNS, Kademlia) and which parts the daemon actually runs.
There are two layers to peer discovery in the source: what the daemon does at boot today, and a library of pluggable discovery backends. They are not the same thing, and this page keeps them apart. The transport is on Mesh networking and node tracking is on Clustering.
Source: crates/clawft-kernel/src/mesh_discovery.rs, mesh_bootstrap.rs,
mesh_mdns.rs, mesh_kad.rs, boot.rs.
What the daemon does
-
Seed peers. Boot connects every entry of
[kernel.mesh] seed_peersdirectly, by iterating the addresses and callingMeshTransport::connect(mesh_bootstrap.rsmodule notes, the WEFT-151 audit). An entry may beaddress#node-id, which pins the node id the seed must claim; without a pin a seed is bound to the first id it names (MeshConfig,crates/clawft-types/src/config/kernel.rs). -
Join structures are not on the wire.
JoinRequestandJoinResponse(which carries apeer_list) are defined inmesh_listener.rs, but that module records that the frame types of the same names never serialise them and that the connection pool it defines has no production caller. Nodes are reached from the seed list, by pairing and by explicit join, not through a join exchange. -
The Kademlia table. With
discovery = true, boot builds the mesh runtime with a Kademlia routing table and a heartbeat tracker, keyed by the BLAKE3 hash of the node id (boot.rs,MeshRuntime::with_discovery). Peer events are published on aMeshPeerEventBus. -
Pairing. Between machines that should trust each other for project work, one node asks and the other approves; approval verifies the peer's Ed25519 key against its node id before writing the trust files (ADR-108 P2b):
weaver mesh pair listA node that cannot pair imports a signed mesh record exported elsewhere (
weaver mesh export,weaver mesh import). -
Leaf discovery. Certified leaves such as ESP32 devices find a node by a UDP discovery socket kept apart from the main listener. By default it binds on the main port plus 1, and the leaf TCP listener on the main port plus 2 (
leaf_listen_addr,leaf_discovery_any). -
Adding a node by address.
weaver cluster join <ADDRESS>. -
Trust is separate from finding. Being discovered grants nothing. A peer is
discovered,pairedorpinnedfor placement, and admission to the mesh is a signature and policy check (Mesh networking).
The discovery library
DiscoveryBackend is the trait for a pluggable mechanism
(mesh_discovery.rs):
#[async_trait]
pub trait DiscoveryBackend: Send + Sync + 'static {
fn name(&self) -> &str;
async fn start(&mut self) -> Result<(), DiscoveryError>;
async fn poll(&mut self) -> Vec<DiscoveredPeer>;
async fn stop(&mut self) -> Result<(), DiscoveryError>;
}A DiscoveredPeer records where it came from, as a DiscoverySource:
SeedPeer, Mdns, Kademlia, PeerExchange or Manual.
DiscoveryCoordinator::poll_all() queries every registered backend and returns
only peers it has not seen, deduplicating by node id.
| Backend | Module | What it does |
|---|---|---|
BootstrapDiscovery | mesh_bootstrap.rs | Reports the configured seed addresses. Idempotent, no dependencies |
PeerExchangeDiscovery | mesh_bootstrap.rs | Designed to learn peers from a JoinResponse.peer_list; see above |
MdnsDiscovery | mesh_mdns.rs | DNS-SD over multicast UDP 224.0.0.251:5353, advertising _weftos._tcp.local; announcements carry the governance genesis hash so clusters stay separate |
KademliaDiscovery | mesh_kad.rs | A Kademlia table (bucket size 20, alpha 3, 256-bit keys) with governance-namespaced keys |
NamespacedDhtKey prefixes every DHT key with the governance genesis so one
cluster's records do not pollute another's.
Which of these the daemon runs
Not the coordinator, and not the backends. Reading the source at v0.8.4:
mesh_bootstrap.rsrecords thatBootstrapDiscoveryandPeerExchangeDiscoveryare library only: boot dialsseed_peersitself and never constructs them, andDiscoveryCoordinatoris exercised only in its unit tests.- I found no call site outside
mesh_mdns.rsthat constructsMdnsDiscovery(method:grepovercrates/forMdnsDiscovery; the only hits are its definition, its tests and the re-export inlib.rs). So multicast LAN discovery is not started by the daemon. KademliaDiscoverylikewise has no daemon call site. The Kademlia routing table itself is created whendiscovery = true, as above.
The module notes schedule wiring a coordinator into boot for 0.8.x. Until that
lands, treat seed_peers, pairing and weaver cluster join as the ways a node
finds peers, and do not rely on mDNS to find them on a LAN.
Mesh Networking
The WeftOS mesh as of v0.8.4: transports (TCP, WebSocket, QUIC), Noise encryption, peer admission, the machine mesh service, wire frames, cross-node IPC, artifact and topic transfer, and the [kernel.mesh] configuration.
Clustering
How WeftOS nodes track each other as a cluster at v0.8.4: node identity and state, the liveness ping and the heartbeat tracker, signed node facts, the service registry that placement reads, and which of the replicated-state designs (process table, chain and tree sync) are library code only.