Skip to main content

​
Purpose and Scope

This document describes the devp2p command-line tool, a developer utility for interacting with and testing the StableNet peer-to-peer networking layer.
devp2p provides commands for DNS-based node discovery management, node discovery protocol testing (Discovery v4 and v5), node key management, network crawling, and protocol conformance testing. For instructions on building the tool itself, see Build and CI/CD. For broader information on testing frameworks and debugging, see Testing Framework.

​
Command Structure Overview

The devp2p CLI consists of multiple top-level commands, each providing a related set of operations for network development and testing.

​
Command Hierarchy

  • dns
    DNS-based node discovery (EIP-1459) tree management
  • discv4
    Discovery v4 (UDP-based) protocol testing and diagnostics
  • discv5
    Discovery v5 (encrypted, topic-based) protocol testing and diagnostics
  • key
    Node key generation and conversion, enode URL generation
  • crawl
    Network crawling and node set maintenance
  • test
    Execution of Discovery protocol conformance test suites

​
DNS Discovery Management

The dns command group provides tools for managing DNS-based node discovery trees as defined in EIP-1459.
DNS discovery is used in environments where node lists are distributed and updated via DNS TXT records.

​
DNS Command Architecture

A DNS discovery tree consists of the following elements:
  • Root TXT record (enrtree-root)
  • Signed tree nodes
  • Child TXT records pointing to ENR records
  • Sequence numbers and signatures
The devp2p dns commands manage this entire structure using a local directory-based representation.

​
DNS Sync Command

dns sync downloads a DNS discovery tree from a remote URL and stores it in a local directory.
FlagDescriptionDefault
--timeoutDNS query timeoutNone
Behavior:
  • Fetch the DNS tree root from the URL
  • Traverse the entire tree by following TXT records
  • Verify signatures for each node
  • Store the complete tree as local files

​
DNS Sign Command

dns sign signs an existing DNS discovery tree with a private key, updating the sequence number and root signature.
FlagDescriptionRequired
--domainTree domain nameYes
--seqSequence numberNo (auto-incremented)
Behavior:
  • Load the local tree
  • Load the private key
  • Update the sequence number
  • Sign the root node
  • Save the updated tree

​
DNS TXT Export

The to-txt subcommand exports a signed DNS discovery tree into a text file containing standard DNS TXT record entries.
This file can be used for manual deployment or inspection. 
example.com. TXT "enrtree-root:v1 e=ABC123... l=DEF456... seq=1 sig=789..."
_abc123.example.com. TXT "enrtree://..."
Automated deployment to external DNS providers such as Cloudflare or Route53 is not supported by StableNet and is therefore out of scope for this document.

​
Node Discovery v4 Tools

The discv4 command group provides tools for testing and diagnosing the Discovery v4 protocol (UDP-based node discovery).

​
Discovery v4 Ping

Sends a PING packet to a remote node and waits for a PONG response to verify connectivity. Key Flags (discoveryNodeFlags):
  • --bootnodes: Bootstrap node list
  • --nodekeyhex: Hex-encoded node private key
  • --nodekey: Path to node key file
  • --listen: Local UDP listen address
  • --extip: External IP to record in the ENR
Execution Flow:
  1. Create a UDP listener
  2. Initialize a discover.UDPv4 instance
  3. Send a PING to the target node
  4. Wait for a PONG response
  5. Calculate and print round-trip time (RTT)

​
Discovery v4 ENR Request

Requests a node’s ENR (Ethereum Node Record) using the EIP-868 ENRRequest message. Execution Flow:
  1. Verify connectivity via PING
  2. Send an ENRRequest
  3. Receive an ENRResponse
  4. Validate and display the ENR

​
Discovery v4 Resolve

Performs a Kademlia-style lookup to locate a specific node in the DHT. Execution Flow:
  1. Connect to bootstrap nodes
  2. Repeatedly send FINDNODE requests
  3. Return the ENR when the target node is found

​
Discovery v4 Crawl

Crawls the DHT to discover reachable nodes and updates the nodes.json file.
FlagDescriptionDefault
--timeoutCrawl time limit30 minutes
--parallelNumber of parallel queries16
Crawling Algorithm:
  1. Load existing nodes.json as the seed set
  2. Repeatedly query random nodes
  3. Validate nodes via PING
  4. Retain only responsive nodes in the result set
  5. Perform periodic revalidation
Revalidation Policy:
  • Nodes are re-pinged after revalidateInterval
  • Unresponsive nodes are removed from the result set

​
Discovery v4 Test Suite

Runs Discovery v4 protocol conformance tests against a target node. Test Categories:
  • Ping tests
  • FindNode tests
  • Amplification tests
  • Spoofing tests

​
Node Discovery v5 Tools

The discv5 command group provides tools for testing and diagnosing the Discovery v5 protocol.

​
Discovery v5 Operations

​
Ping

Verifies node connectivity through Discovery v5 PING/PONG exchanges.

​
Resolve

Searches for nodes using Discovery v5 DHT lookups.

​
Crawl

Crawls the network using the Discovery v5 protocol.

​
Node Key Management

The key command group provides utilities for node key generation and conversion.

​
Key Generation

Generates a new ECDSA private key used for node identity.

​
Enode URL Generation

Generates an enode URL from a private key. 
enode://pubkey@ip:port?discport=udp

​
File Formats

​
Node Key File Format

64-character-hex-string

​
Integration with the P2P Stack

The devp2p CLI tool uses the same networking components as the full node.
  • p2p/discover
  • p2p/enode
  • p2p/dnsdisc
  • crypto