> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# devp2p CLI Tools

## 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](/en/development-tools/10.1-building-and-cicd).

For broader information on testing frameworks and debugging, see [Testing Framework](/en/development-tools/10.4-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.

| Flag        | Description       | Default |
| ----------- | ----------------- | ------- |
| `--timeout` | DNS query timeout | None    |

**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.

| Flag       | Description      | Required              |
| ---------- | ---------------- | --------------------- |
| `--domain` | Tree domain name | Yes                   |
| `--seq`    | Sequence number  | No (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.

```text theme={null}
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.

| Flag         | Description                | Default    |
| ------------ | -------------------------- | ---------- |
| `--timeout`  | Crawl time limit           | 30 minutes |
| `--parallel` | Number of parallel queries | 16         |

**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.

```text theme={null}
enode://pubkey@ip:port?discport=udp
```

## File Formats

### Node Key File Format

```text theme={null}
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`