목적 및 범위
이 문서는 StableNet peer-to-peer 네트워킹 레이어와 상호작용하고 테스트하기 위한 개발자 유틸리티인devp2p 명령줄 도구를 설명합니다.devp2p는 DNS 기반 노드 발견 관리, 노드 발견 프로토콜 테스트(Discovery v4 및 v5), 노드 키 관리, 네트워크 크롤링, 프로토콜 준수 테스트를 위한 명령을 제공합니다.
도구 자체의 빌드 방법은 빌드 및 CI/CD를 참고하세요.
테스트 프레임워크 및 디버깅 전반에 대한 내용은 테스트 프레임워크을 참고하세요.
명령 구조 개요
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 레코드 형식의 텍스트 파일로 내보냅니다.이 파일은 수동 배포 또는 검토 용도로 사용됩니다.
CloudFlare, Route53 등 외부 DNS 공급자 자동 배포 기능은 StableNet에서 지원하지 않으므로 본 문서에서는 다루지 않습니다.
노드 발견 v4 도구
discv4 명령 그룹은 Discovery v4 프로토콜(UDP 기반 노드 발견)을 테스트하고 진단하기 위한 도구를 제공합니다.
Discovery v4 Ping
원격 노드에 PING 패킷을 전송하고 PONG 응답을 수신하여 연결성을 검증합니다. 주요 플래그(discoveryNodeFlags):--bootnodes: 부트스트랩 노드 목록--nodekeyhex: 16진수 인코딩된 노드 개인 키--nodekey: 노드 키 파일 경로--listen: 로컬 UDP 수신 주소--extip: ENR에 기록할 외부 IP
- UDP 리스너 생성
discover.UDPv4인스턴스 초기화- 대상 노드로 PING 전송
- PONG 응답 대기
- 왕복 시간(RTT) 계산 및 출력
Discovery v4 ENR 요청
EIP-868의ENRRequest 메시지를 사용하여 노드의 ENR(Ethereum Node Record)을 요청합니다.
동작 흐름:
- PING을 통한 연결성 확인
- ENRRequest 전송
- ENRResponse 수신
- ENR 검증 및 출력
Discovery v4 Resolve
Kademlia 스타일 조회를 통해 DHT에서 특정 노드를 탐색합니다. 동작 흐름:- 부트스트랩 노드 연결
- FINDNODE 요청 반복
- 대상 노드 발견 시 ENR 반환
Discovery v4 Crawl
DHT를 크롤링하여 접근 가능한 노드를 발견하고nodes.json 파일을 갱신합니다.
| Flag | Description | Default |
|---|---|---|
--timeout | 크롤링 제한 시간 | 30분 |
--parallel | 동시 조회 수 | 16 |
- 기존
nodes.json을 시드로 로드 - 랜덤 노드 조회 반복
- PING을 통한 노드 유효성 검증
- 응답 노드만 결과 세트에 유지
- 주기적 재검증 수행
- 노드는
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을 생성합니다.파일 형식
노드 키 파일 형식
P2P 스택과의 통합
devp2p CLI 도구는 전체 노드에서 사용하는 것과 동일한 네트워킹 구성 요소를 사용합니다.
p2p/discoverp2p/enodep2p/dnsdisccrypto