> ## 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 도구

## 목적 및 범위

이 문서는 StableNet peer-to-peer 네트워킹 레이어와 상호작용하고 테스트하기 위한 개발자 유틸리티인 `devp2p` 명령줄 도구를 설명합니다.\
`devp2p`는 DNS 기반 노드 발견 관리, 노드 발견 프로토콜 테스트(Discovery v4 및 v5), 노드 키 관리, 네트워크 크롤링, 프로토콜 준수 테스트를 위한 명령을 제공합니다.

도구 자체의 빌드 방법은 [빌드 및 CI/CD](/ko/development-tools/10.1-building-and-cicd)를 참고하세요.

테스트 프레임워크 및 디버깅 전반에 대한 내용은 [테스트 프레임워크](/ko/development-tools/10.4-testing-framework)을 참고하세요.

## 명령 구조 개요

`devp2p` CLI는 여러 최상위 명령으로 구성되며, 각 명령은 네트워크 개발 및 테스트를 위한 관련 작업 세트를 제공합니다.

### 명령 계층 구조

* `dns`\
  DNS 기반 노드 발견(EIP-1459) 트리 관리
* `discv4`\
  Discovery v4(UDP 기반) 프로토콜 테스트 및 진단
* `discv5`\
  Discovery v5(암호화·토픽 기반) 프로토콜 테스트 및 진단
* `key`\
  노드 키 생성 및 변환, enode URL 생성
* `crawl`\
  네트워크 크롤링 및 노드 세트 유지 관리
* `test`\
  Discovery 프로토콜 준수 테스트 suit 실행

## DNS Discovery 관리

`dns` 명령 그룹은 EIP-1459에 정의된 DNS 기반 노드 발견 트리를 관리하기 위한 도구를 제공합니다.\
DNS 발견은 TXT 레코드를 통해 노드 목록을 배포·갱신하는 환경에서 사용됩니다.

### DNS 명령 아키텍처

DNS 발견 트리는 다음 요소로 구성됩니다.

* 루트 TXT 레코드(`enrtree-root`)
* 서명된 트리 노드
* ENR 레코드를 가리키는 하위 TXT 레코드
* 시퀀스 번호 및 서명

`devp2p dns` 명령은 이 구조 전체를 로컬 디렉터리 기반으로 관리합니다.

### DNS Sync 명령

`dns sync`는 원격 URL에서 DNS 발견 트리를 내려받아 로컬 디렉터리에 저장합니다.

| Flag        | Description | Default |
| ----------- | ----------- | ------- |
| `--timeout` | DNS 조회 타임아웃 | 없음      |

**동작 내용:**

* URL에서 DNS 트리 루트 조회
* TXT 레코드를 따라 전체 트리 순회
* 각 노드의 서명 검증
* 트리 전체를 로컬 파일로 저장

### DNS Sign 명령

`dns sign`은 기존 DNS 발견 트리를 개인 키로 서명하여 시퀀스 번호 및 루트 서명을 갱신합니다.

| Flag       | Description | Required   |
| ---------- | ----------- | ---------- |
| `--domain` | 트리 도메인 이름   | Yes        |
| `--seq`    | 시퀀스 번호      | No (자동 증가) |

**동작 내용:**

* 로컬 트리 로드
* 개인 키 로드
* 시퀀스 번호 갱신
* 루트 노드 서명
* 갱신된 트리 저장

### DNS TXT 내보내기

`to-txt` 하위 명령은 서명된 DNS 발견 트리를 표준 DNS TXT 레코드 형식의 텍스트 파일로 내보냅니다.\
이 파일은 수동 배포 또는 검토 용도로 사용됩니다.

```
example.com. TXT "enrtree-root:v1 e=ABC123... l=DEF456... seq=1 sig=789..."
_abc123.example.com. TXT "enrtree://..."
```

> CloudFlare, Route53 등 외부 DNS 공급자 자동 배포 기능은 StableNet에서 지원하지 않으므로 본 문서에서는 다루지 않습니다.

## 노드 발견 v4 도구

`discv4` 명령 그룹은 Discovery v4 프로토콜(UDP 기반 노드 발견)을 테스트하고 진단하기 위한 도구를 제공합니다.

### Discovery v4 Ping

원격 노드에 PING 패킷을 전송하고 PONG 응답을 수신하여 연결성을 검증합니다.

**주요 플래그(discoveryNodeFlags):**

* `--bootnodes`: 부트스트랩 노드 목록
* `--nodekeyhex`: 16진수 인코딩된 노드 개인 키
* `--nodekey`: 노드 키 파일 경로
* `--listen`: 로컬 UDP 수신 주소
* `--extip`: ENR에 기록할 외부 IP

**동작 흐름:**

1. UDP 리스너 생성
2. `discover.UDPv4` 인스턴스 초기화
3. 대상 노드로 PING 전송
4. PONG 응답 대기
5. 왕복 시간(RTT) 계산 및 출력

### Discovery v4 ENR 요청

EIP-868의 `ENRRequest` 메시지를 사용하여 노드의 ENR(Ethereum Node Record)을 요청합니다.

**동작 흐름:**

1. PING을 통한 연결성 확인
2. ENRRequest 전송
3. ENRResponse 수신
4. ENR 검증 및 출력

### Discovery v4 Resolve

Kademlia 스타일 조회를 통해 DHT에서 특정 노드를 탐색합니다.

**동작 흐름:**

1. 부트스트랩 노드 연결
2. FINDNODE 요청 반복
3. 대상 노드 발견 시 ENR 반환

### Discovery v4 Crawl

DHT를 크롤링하여 접근 가능한 노드를 발견하고 `nodes.json` 파일을 갱신합니다.

| Flag         | Description | Default |
| ------------ | ----------- | ------- |
| `--timeout`  | 크롤링 제한 시간   | 30분     |
| `--parallel` | 동시 조회 수     | 16      |

**크롤링 알고리즘:**

1. 기존 `nodes.json`을 시드로 로드
2. 랜덤 노드 조회 반복
3. PING을 통한 노드 유효성 검증
4. 응답 노드만 결과 세트에 유지
5. 주기적 재검증 수행

**재검증 정책:**

* 노드는 `revalidateInterval` 이후 다시 ping
* 응답하지 않는 노드는 결과에서 제거

### Discovery v4 테스트 스위트

대상 노드에 대해 Discovery v4 프로토콜 준수 테스트를 실행합니다.

**테스트 범주:**

* Ping 테스트
* FindNode 테스트
* 증폭 테스트
* 스푸핑 테스트

## 노드 발견 v5 도구

`discv5` 명령 그룹은 Discovery v5 프로토콜을 테스트하고 진단하기 위한 도구를 제공합니다.

### Discovery v5 작업

#### Ping

Discovery v5 PING/PONG 교환을 통해 노드 연결성을 검증합니다.

#### Resolve

Discovery v5 DHT 조회를 통해 노드를 탐색합니다.

#### Crawl

Discovery v5 프로토콜을 사용하여 네트워크를 크롤링합니다.

## 노드 키 관리

`key` 명령 그룹은 노드 키 생성 및 변환을 위한 유틸리티를 제공합니다.

### 키 생성

노드 식별에 사용할 새로운 ECDSA 개인 키를 생성합니다.

### Enode URL 생성

개인 키에서 enode URL을 생성합니다.

```
enode://pubkey@ip:port?discport=udp
```

## 파일 형식

### 노드 키 파일 형식

```
64-character-hex-string
```

## P2P 스택과의 통합

`devp2p` CLI 도구는 전체 노드에서 사용하는 것과 동일한 네트워킹 구성 요소를 사용합니다.

* `p2p/discover`
* `p2p/enode`
* `p2p/dnsdisc`
* `crypto`