Skip to main content
Parallax discovers peers with a Bitcoin-style TCP gossip model, which replaced the UDP-based discv4 discovery of v1.x releases. Each node runs:
  • a Bitcoin Core-style address manager (addrman) that stores up to ~65k peer records in stochastic “new” and “tried” bucket tables, keyed by a per-node secret nKey;
  • the parallax-disc/1 RLPx subprotocol, carrying a mandatory session-opening Hello followed by GetPeers / Peers / YourAddr gossip messages on top of existing TCP sessions — Hello must be each side’s first disc message, and anything else first ends the session;
  • a BIP324-style v2 handshake that lets two nodes authenticate a TCP connection knowing only each other’s ip:port — no persistent secp256k1 identity, no enode URL, no ENR.
These three pieces are always on in v2.0+ builds. Operators choose their compatibility posture with a single flag. Addresses travel in BIP155 form, so the same gossip carries IPv4, IPv6 and Tor v3 onion addresses — see Tor Integration for how onion peers behave.

​
The --legacy-discovery flag

--legacy-discovery controls how much of the v1.x transport surface the node exposes. UDP discovery and legacy RLPx handshake acceptance are coupled: they share the same v1.x identity model (persistent secp256k1 key, enode URL, ENR record), so the flag drives both in lockstep. auto is the transitional posture: the node answers inbound discv4 PING/FINDNODE so v1.x peers can still contact it, but the addrman is the primary dial source. Most mainnet operators will never need to change it. on matches pre-2.0 behaviour — discv4.RandomNodes() is plumbed into the dial scheduler, useful when debugging against a pure v1.x network. off is the v3.0 posture available as an early opt-in: no UDP socket, the listener rejects anything that isn’t the v2 magic byte 0xA0, and the dialer refuses addrman entries that carry a legacy NodeID. The enode URL logged at startup becomes diagnostic-only — no peer handshake consumes the persistent secp256k1 key in this mode.

​
Topology examples

The canonical three-role mainnet setup:
Under this topology, B connects to both A (legacy RLPx) and C (v2 handshake) simultaneously on the same listener. C never peers with A directly; all A-discovered addresses reach C via parallax-disc/1 gossip through B.

​
Addrbook persistence

The addrman persists to <datadir>/addrbook.rlp on clean shutdown and reloads it on next startup. The on-disk format is versioned (v1 today); upgrades introduce a new version byte plus a migration function rather than appending fields in place. Unknown newer file versions are refused without truncation — a downgrade-then-upgrade never loses the original file.

​
Operator RPC

The admin namespace exposes the addrbook and dial controls:
  • admin_addnode <ip:port | <addr>.onion:port | enode://…> — pin a peer as source=manual; persists across restarts and is heavily weighted in dial selection (a 4x chance multiplier, not a strict front-of-queue guarantee).
  • admin_removenode <ip:port | <addr>.onion:port | enode://…> — inverse of addnode.
  • admin_addrbookStatus — read-only addrbook snapshot (total/new/tried, per-source counts).
  • admin_addrbookResetKey — regenerate nKey and clear the tried table. Operator-only; use after a credible nKey leak.
  • admin_dialV2 <ip:port | <addr>.onion:port> — directly dial a remote over the v2 handshake. Operator-testing entry point.
Three more manage the persistent ban list (see Peer management for behaviour):
  • admin_setban <subnet> <add|remove> [bantime] [absolute]
  • admin_listbanned
  • admin_clearbanned
Corresponding parallax-cli subcommands are addnode, removenode, addrbook-status, addrbook-resetkey, dialv2, setban, listbanned, clearbanned.

​
Deprecation timeline