검증자 작업

​

목적 및 범위

이 문서는 StableNet 네트워크에서 검증자 노드를 운영하기 위한 가이드를 제공합니다.
검증자 키 관리, 노드 구성, 블록 생성(마이닝), 거버넌스 참여, 모니터링 방법 및 일반적인 장애 대응 시나리오를 다룹니다. 검증자는 블록 생성과 합의 참여, 그리고 네트워크 거버넌스를 수행하는 StableNet 블록체인의 핵심 운영 주체입니다. 관련 문서:

• 네트워크 배포
• 노드 모니터링 및 유지보수
• Anzeon WBFT 합의 프로토콜
• 검증자 거버넌스 (GovValidator)

​

검증자 아키텍처 개요

​

검증자 키 구성

StableNet의 검증자는 목적에 따라 세 가지 유형의 키를 사용합니다.

• Operator Key는 일반 EOA(Externally Owned Account) 또는 보안 강화를 위한 멀티시그 컨트랙트 주소로 사용할 수 있습니다.
• Validator Key와 BLS Key는 합의 참여를 위해 노드 프로세스에서 항상 접근 가능해야 합니다.
• StableNet 노드는 nodekey로부터 검증자 주소를 자동으로 파생하여 Anzeon 체인에서 사용합니다.

​

검증자를 위한 제네시스 구성

검증자는 제네시스 파일에서 두 위치에 정의됩니다.

1. anzeon.init 섹션
   • 제네시스 블록(블록 0)의 EpochInfo 생성에 사용됨
   • 첫 번째 에포크(블록 0 ~ 첫 번째 에포크 블록 직전) 동안 활성 검증자 세트를 정의
2. anzeon.systemContracts.govValidator 섹션
   • GovValidator 컨트랙트의 초기 상태를 정의(제네시스에서 컨트랙트 스토리지 초기화)
   • 두 번째 에포크부터 에포크 블록에서 새 EpochInfo를 만들 때, 검증자 BLS 키를 이 컨트랙트에서 읽어 검증자 세트를 결정함
   • 이후 검증자 추가·제거는 거버넌스(GovValidator 제안·투표·실행)로만 변경 가능

govValidator.params에는 다음 세 가지 항목이 포함됩니다.

• members
• validators
• blsPublicKeys

members, validators, blsPublicKeys는 동일한 순서로 관리되는 병렬 목록이며, 각 목록의 항목 수는 반드시 동일해야 합니다. 각 목록의 같은 위치에 있는 값들이 하나의 검증자 신원을 구성합니다.

• 운영자 주소 (members): 거버넌스 투표·검증자 등록/제거에 사용하는 EOA 또는 멀티시그 주소
• 검증자 주소 (validators): 합의 메시지 서명·coinbase(블록 수수료 수신)에 쓰는 주소. 노드의 nodekey에서 파생
• BLS 공개 키 (blsPublicKeys): 검증자 키에서 파생된 BLS 공개 키. WBFT PREPARE/COMMIT 집계 서명에 사용

​

노드 구성

​

초기 설정

​

1. 검증자 키 생성

검증자 주소와 BLS 키는 노드의 nodekey에서 파생됩니다.
nodekey는 네트워크 배포의 Nodekey 생성 절에 따라 bootnode -genkey로 생성합니다. BLS 공개 키는 다음 중 하나의 방식으로 준비합니다.

• genesis_generator가 nodekey에서 자동 파생
• bootnode로 생성 후 제네시스 및 GovValidator에 등록

​

2. 구성 파일 설정

검증자 노드마다 config.toml 파일을 구성하며, 데이터 디렉터리, RPC, P2P, 정적 노드(StaticNodes) 또는 bootnode 정보 등을 설정합니다.
다중 노드 구성 시 genesis_generator가 생성한 config.toml을 그대로 사용하거나, 운영 환경에 맞게 수정할 수 있습니다.

​

3. 네트워크 구성

메인넷 및 테스트넷 검증자는 네트워크 프리셋(-mainnet, -testnet)을 사용하거나 -bootnodes 옵션으로 부트노드를 지정합니다.
프라이빗 네트워크의 경우 11.1 네트워크 배포에 정의된 정적 노드 및 bootnode 구성 방식을 따릅니다.

​

중요한 구성 매개변수

​

마이닝 구성

Anzeon/WBFT 체인의 경우 etherbase는 -miner.etherbase와 관계없이 자동으로 노드의 nodekey에서 파생된 주소로 설정됩니다. 따라서 검증자 키와 블록 coinbase가 항상 일치하며, 코드(예: eth/backend.go)에서 P2P 노드 키에서 검증자 주소를 파생해 일관성을 유지합니다.

​

검증자 작업 시작

​

노드 시작

제네시스로 초기화된 데이터 디렉터리를 사용해 노드를 실행합니다.
마이닝(블록 생성)을 활성화하려면 -mine 플래그를 지정합니다. 예시: gstable -datadir <경로> -networkid <chainId> -mine -config config.toml 필요한 경우 -bootnodes 옵션을 추가해 부트노드를 지정할 수 있습니다.

​

마이닝 라이프사이클

노드가 네트워크와 동기화된 이후 마이닝이 시작됩니다.
WBFT 합의에서는 현재 라운드의 제안자(proposer) 로 선택된 검증자만 블록을 제안하며, 그 외 검증자들은 prepare / commit 메시지를 통해 합의에 참여합니다.

​

WBFT 특화 마이닝 루프

WBFT 합의에서 마이닝은 타이머 기반이 아닌 이벤트 기반으로 동작합니다.
합의 엔진이 새 라운드가 시작될 때 워커에게 신호를 전달하면, 워커는 그 시점에 맞춰 블록을 생성·제출합니다. 동작 요약:

• 트리거
  WBFT 코어에서 새 라운드를 시작할 때(startNewRound), 백엔드의 NotifyNewRound가 호출되며 이 신호가 워커의 readyToCommit으로 전달됩니다.
  필요 시 다음 블록 시점까지의 대기 시간이 함께 전달됩니다.
• 워커
  readyToCommitCh에서 라운드 신호를 수신하면 새 sealing work를 생성합니다.
  이때 기존에 진행 중이던 블록 빌드는 중단되고 새 라운드 기준으로 재시도됩니다.
  WBFT가 활성화된 경우, 새 블록 생성은 이 채널 신호에 의해서만 트리거되며 단순한 체인 헤드 변경만으로는 새 work가 커밋되지 않습니다.
• 제안자
  매 라운드마다 제안자(proposer)가 결정되며, 실제 합의에 사용되는 블록은 해당 제안자가 생성한 PRE-PREPARE 블록입니다.
  모든 검증자가 라운드마다 블록을 빌드할 수 있지만, 최종적으로 채택되는 것은 해당 라운드 제안자의 블록뿐입니다.

이 흐름은 백엔드의 Start 단계에서 WBFT 엔진에 readyToCommit 콜백을 등록하여, 합의 엔진과 실행 백엔드(워커)를 연결하는 방식으로 구성됩니다.

​

거버넌스 참여

​

제안 투표

거버넌스 멤버는 GovValidator 컨트랙트를 통해 거버넌스에 참여합니다.
운영자 키를 사용해 제안 생성(propose), 투표(vote), 실행(execute)을 수행합니다.
세부 절차는 검증자 거버넌스 (GovValidator)를 참고하세요.

​

가스 팁 거버넌스

거버넌스 멤버는 일반 계정이 지불하는 가스 팁(우선순위 수수료)을 GovValidator 거버넌스를 통해 결정합니다.
결정된 가스 팁은 매 블록마다 GovValidator에서 조회되며, 워커와 트랜잭션 풀에 자동으로 반영됩니다.

​

키 관리 모범 사례

​

보안 고려 사항

​

운영자 키 보호

운영자 키는 거버넌스 제안과 투표를 수행할 수 있으므로 가장 높은 권한을 가집니다.
다음과 같은 보안 모범 사례를 권장합니다.

1. 멀티시그 컨트랙트 사용
   운영자 주소를 단순 EOA가 아닌 멀티시그 컨트랙트 주소로 구성
2. 콜드 스토리지 유지
   투표 시점을 제외하고 운영자 키는 오프라인 상태로 보관
3. 하드웨어 지갑 사용
   운영자 키 서명 시 하드웨어 지갑 사용
4. 별도 서명 서비스 분리
   운영자 작업 전용 서명 서비스를 별도로 운영

​

BLS 키 관리

BLS 키는 WBFT 합의 참여에 필수적입니다. 다음 사항을 반드시 준수해야 합니다.

1. 등록 정보 일치
   GovValidator(또는 제네시스의 init)에 등록된 BLS 공개 키는 해당 노드의 nodekey에서 파생된 BLS 공개 키와 동일해야 합니다.
   합의 엔진은 등록된 BLS 공개 키로 서명을 검증하므로, 노드의 BLS 키가 일치하지 않으면 해당 노드는 합의에 참여할 수 없습니다.
2. 초기화 시 파생
   WBFT 백엔드는 초기화 과정에서 노드의 ECDSA 개인 키(nodekey)로부터 bls.DeriveFromECDSA를 호출해 BLS 시크릿 키를 파생·보관합니다.
   별도의 BLS 키 파일을 로드하는 경로는 없으므로, 검증자로 사용하는 노드는 제네시스 또는 GovValidator에 등록된 BLS 공개 키가 반드시 해당 nodekey에서 파생된 값이어야 합니다.
3. 안전한 백업
   nodekey를 분실하면 동일한 BLS 키 쌍을 복구할 수 없습니다.
   이 경우 거버넌스를 통해 새 nodekey·BLS 키 쌍을 가진 검증자를 등록하는 절차가 필요합니다.

제네시스 및 GovValidator에 등록할 BLS 공개 키를 얻는 방법은 다음을 참고하세요.

• ECDSA nodekey에서 BLS 키를 파생하는 로직: genesis_generator의 deriveAccount()
• 관련 문서: 네트워크 배포의 Nodekey에서 파생되는 정보

프로덕션 환경에서는 genesis_generator에 nodekey를 입력해 검증자 주소와 BLS 공개 키를 생성하거나, BLS12-381을 지원하는 유틸리티로 키를 생성한 뒤 동일한 키 쌍을 노드에서 사용하도록 구성합니다.

​

검증자 변경

활성 검증자 및 BLS 키는 거버넌스를 통해서만 변경할 수 있으며, 사전 준비를 통해 무중단 순환을 구성할 수 있습니다.

1. 사전 준비
   genesis_generator 또는 BLS 유틸리티로 새 nodekey·BLS 키 쌍을 생성하고, GovValidator에 등록할 검증자 주소와 BLS 공개 키를 확보합니다.
2. 검증자 추가 제안
   운영자 키를 사용해 새 검증자 추가 제안을 제출합니다.
3. 기존 검증자 제거 제안
   추가 제안이 승인된 후, 이전 검증자 제거 제안을 제출합니다.
4. 무중단 전환
   두 검증자 노드를 일정 기간 동시에 실행해 가동 중지 없이 전환합니다.

거버넌스 프로세스는 다음 단계로 진행됩니다.

• 운영자 키로 GovValidator.propose() 호출
• 다른 거버넌스 멤버가 GovValidator.vote()로 투표
• 쿼럼 충족 시 GovValidator.execute()로 검증자 세트 갱신
• 변경 사항은 다음 에포크 블록에서 적용됩니다.

​

키 저장소

nodekey 등 민감한 키 파일은 검증자 노드에서만 읽을 수 있도록 파일 권한을 제한합니다.
예: chmod 600 nodekey
키 파일이 위치한 디렉터리 역시 불필요한 접근이 없도록 권한을 설정합니다.

​

검증자 상태 모니터링

​

모니터링할 주요 메트릭

블록 생성률, 피어 수, 동기화 지연, 디스크·메모리 사용량, BLS 및 합의 관련 오류 여부를 주기적으로 확인합니다.
자세한 항목은 노드 모니터링 및 유지보수를 참고하세요.

​

모니터링 명령

gstable attach로 노드 콘솔에 접속한 뒤 다음 명령으로 상태를 확인할 수 있습니다.

• eth.mining : 마이닝(블록 생성) 여부
• eth.blockNumber : 현재 블록 높이
• admin.peers.length : 연결된 피어 수
• admin.peers : 피어 상세 정보

GovValidator의 검증자 목록은 컨트랙트 호출을 통해 조회합니다.

​

로그 모니터링

다음 항목을 로그에서 확인합니다.

• 블록 제안 및 커밋 과정
• BLS 서명 실패 및 합의 오류
• 피어 연결 및 해제
• 가스 팁 갱신
• 거버넌스 관련 이벤트

오류 또는 경고 로그 발생 시 원인을 분석한 후 조치합니다.

​

로그 레벨

기본 -verbosity 설정으로 충분한 경우가 많습니다.
합의, P2P, 워커 동작을 상세히 확인해야 할 경우 -verbosity 값을 높이거나, -vmodule 옵션으로 특정 패키지에 대해서만 상세 로그를 활성화할 수 있습니다.

​

메트릭 내보내기

-metrics 옵션을 사용하면 Prometheus 형식의 메트릭이 노출됩니다.
기본 엔드포인트는 다음과 같습니다.

• http://localhost:6060/debug/metrics

메트릭 포트 및 경로는 플래그로 변경할 수 있습니다.

​

일반적인 문제 해결

​

문제: 마이닝이 시작되지 않음

증상: eth.mining이 false를 반환하고 블록이 생성되지 않음 진단 단계:

1. gstable attach 후 eth.mining, eth.coinbase로 마이닝 여부 및 etherbase 확인
2. 노드 실행 시 -mine 플래그가 전달되었는지 확인
3. eth.syncing으로 동기화 상태 확인 (동기화 중인 경우 마이닝이 지연될 수 있음)

해결 방법:

• -mine 플래그를 지정해 노드 재시작
• Anzeon 체인에서는 etherbase가 자동으로 노드 키 주소로 설정되므로, nodekey 파일이 -datadir(또는 기본 데이터 디렉터리)에 존재하는지 확인
• 동기화 완료 후 마이닝 상태를 다시 확인

​

문제: 블록 생성이 멈춤

증상
검증자가 더 이상 블록을 생성하지 않음 진단 단계

1. GovValidator 컨트랙트에서 현재 검증자 목록을 조회해 해당 노드 주소가 포함되어 있는지 확인
2. 로그에서 WBFT 제안·커밋 메시지 및 오류 발생 여부 확인
3. admin.peers.length, admin.peers로 피어 수와 연결 상태 확인

해결 방법

• GovValidator에 검증자 주소 및 BLS 공개 키가 올바르게 등록되어 있는지 확인
• 노드의 BLS 키가 제네시스 또는 GovValidator에 등록된 공개 키와 쌍을 이루는지 확인
• 피어 수를 늘려 네트워크 연결성을 개선 (합의 안정성을 위해 일반적으로 20~30개 피어 권장)
• P2P 포트(기본값 30303)에 대한 방화벽 및 네트워크 연결 상태 확인

​

문제: 가스 팁 불일치

증상
트랜잭션이 "gas tip too low" 오류로 실패함 진단 단계

1. GovValidator 컨트랙트의 gasTip() 또는 RPC API eth.maxPriorityFeePerGas 호출로 현재 요구되는 가스 팁 확인
2. 실패한 트랜잭션의 maxPriorityFeePerGas 값이 네트워크 요구값 이상인지 확인
3. 최근 블록에 가스 팁 변경 사항이 반영되었는지, 노드가 정상적으로 동기화되어 있는지 확인

해결 방법

• 워커는 GovValidator에서 가스 팁을 자동으로 조회해 반영하므로, 노드가 동기화 상태인지 확인
• 거버넌스를 통해 가스 팁이 변경된 경우, 블록 전파 및 반영까지 일정 시간이 소요될 수 있음
• 클라이언트는 네트워크 요구 가스 팁 이상의 maxPriorityFeePerGas 값을 지정해 트랜잭션을 제출해야 함

​

문제: 노드 충돌 또는 재시작

증상
노드 프로세스가 예기치 않게 종료됨 진단 단계

1. df 등으로 -datadir 볼륨의 여유 디스크 공간 확인
2. 재시작 후 데이터베이스 오류 로그 발생 여부 확인 (손상이 의심되는 경우 재동기화가 필요할 수 있음)
3. 시스템 및 커널 로그에서 OOM Kill, I/O 오류 등 확인

해결 방법

• 디스크 여유 공간 확보 (운영 환경에서는 최소 500GB 권장)
  필요 시 -datadir.minfreedisk 옵션으로 임계값 설정
• 메모리 부족 시 RAM 증설 또는 -cache 옵션 조정으로 메모리 사용량 제한
• DB 손상이 의심될 경우 백업 후 -datadir을 비우고 재동기화
• 노드 종료 시 SIGINT 또는 SIGTERM을 사용해 정상 종료하며, 필요 시 우아한 종료(graceful shutdown) 로그 확인

​

문제: 검증자가 세트에서 제거됨

증상
노드가 블록 생성을 중지하고 검증자 목록에서 제외됨 진단 단계

1. GovValidator.getValidators() 등으로 현재 검증자 세트에 해당 노드 주소가 포함되어 있는지 확인
2. 최근 제안, 투표, 실행 이벤트 중 검증자 제거 제안이 있었는지 확인
3. 운영자 키를 통한 제거 투표가 이루어졌는지 확인하고, 키 유출 또는 오용 가능성 검토

해결 방법

• 운영자 키 유출 또는 오용이 의심될 경우 즉시 키 순환을 준비하고 거버넌스 절차 진행
• 다른 거버넌스 멤버와 협의해 검증자 재추가 제안을 제출
• 거버넌스 제안·투표 이력과 노드 로그를 통해 제거 사유 파악
• 운영자 키는 멀티시그, 콜드 스토리지 등으로 안전하게 보호

​

성능 최적화

​

리소스 요구 사항

​

캐시 구성

-cache 옵션으로 노드에 할당할 메모리(MB)를 지정할 수 있습니다.
검증자 노드는 풀 동기화 및 블록 생성 부하를 고려해 4096MB 이상을 권장합니다.
메모리가 충분한 경우 값을 늘리면 디스크 I/O를 줄이는 데 도움이 됩니다.

​

네트워크 최적화

안정적인 P2P 통신을 위해 -maxpeers 값을 적절히 설정하고, -bootnodes 및 정적 노드(StaticNodes)를 통해 신뢰할 수 있는 피어와의 연결을 유지합니다. 방화벽에서 P2P 포트(기본값 30303)를 개방하고, 지연 및 패킷 손실이 적은 네트워크 환경을 사용하는 것이 권장됩니다.

​

에포크 전환 및 검증자 세트 업데이트

​

에포크 구조

WBFT는 블록을 에포크 단위로 관리하며, 검증자 세트 변경은 에포크 블록에서만 적용됩니다. 에포크 길이는 제네시스의 config.anzeon.epochLength로 설정됩니다
(예: epochLength = 10). 각 에포크의 마지막 블록 (blockNumber % epochLength == 0)에서 WBFT 엔진은 다음 작업을 수행합니다.

1. GovValidator 컨트랙트에서 현재 검증자 목록 조회
2. GovValidator 컨트랙트에서 BLS 공개 키 목록 조회
3. 다음 블록 헤더의 WBFTExtra.EpochInfo 갱신
4. 갱신된 검증자 세트는 다음 블록(epochLength + 1)부터 활성화됨

​

검증자 세트 동기화

새로 참여하거나 재시작한 노드는 체인 동기화 과정에서 최신 블록의 WBFTExtra.EpochInfo로부터 검증자 세트를 읽습니다. GovValidator 컨트랙트의 검증자 및 BLS 공개 키 목록은 에포크 블록에서 반영되므로, 노드 동기화가 완료되면 현재 네트워크에서 활성화된 검증자 세트와 자동으로 일치합니다.

​

검증자 보상 및 경제학

StableNet의 검증자는 다음 구조를 통해 보상을 받습니다.

​

검증자 보상 구조

트랜잭션 수수료

• 기본 수수료(Base Fee)와 우선순위 수수료(Gas Tip) 모두 검증자에게 귀속
• 기본 수수료는 소각되지 않음
  (Ethereum과 달리, 안정화폐 1:1 담보 보존을 위해 소각 메커니즘 미사용)
• 우선순위 수수료(Gas Tip) 는 블록 생산자에게 직접 지급
  (Header.Coinbase를 통해 정산)
• 블록 보상 없음
  인플레이션 기반 블록 보상이 존재하지 않으며, 이는 법정화폐 담보 안정성 유지를 위한 설계임

​

가스 수수료 정책

StableNet의 가스 수수료 시스템은 안정화폐 환경에 최적화된 정책을 따릅니다.

​

Gas Tip 정책

Gas Tip은 계정 유형에 따라 다음과 같이 적용됩니다.

1. 인증 계정 (Authorized Account)

• 기존 Ethereum과 동일하게 트랜잭션별 Gas Tip을 사용자가 직접 설정
• maxPriorityFeePerGas 값이 그대로 적용됨

2. 일반 계정 (Non-Authorized Account)

• 거버넌스에서 설정한 고정 Gas Tip 값 사용
• Gas Tip 값은 GovValidator 거버넌스를 통해 변경 가능
• 트랜잭션에서 더 높은 maxPriorityFeePerGas를 지정하더라도 거버넌스에 의해 설정된 고정 Gas Tip 값이 강제로 적용됨

​

Base Fee 정책

StableNet의 Base Fee는 Ethereum EIP-1559와 달리, 이중 임계값(dual-threshold) 기반 고정 비율 조정 방식을 사용합니다. Base Fee 파라미터 Base Fee 변경 규칙 Base Fee는 이전 블록(Parent Block) 의 가스 사용률을 기준으로 다음 규칙에 따라 조정됩니다.

1. 가스 사용률 > 20%
   • 이전 블록의 가스 사용량이 블록 가스 리밋 대비 20%를 초과한 경우
   • 이전 블록 Base Fee 대비 2% 증가
   • 예: 일반 전송 트랜잭션 기준 약 1,000건 초과 처리 수준
2. 6% ≤ 가스 사용률 ≤ 20%
   • 가스 사용률이 6% 이상 20% 이하인 경우
   • Base Fee 변동 없이 유지
3. 가스 사용률 < 6%
   • 가스 사용률이 6% 미만인 경우
   • 이전 블록 Base Fee 대비 2% 감소
   • 예: 일반 전송 트랜잭션 기준 약 300건 미만 처리 수준

Base Fee는 위 규칙에 따라 MinBaseFee와 MaxBaseFee 범위 내에서만 조정됩니다.

​

검증자를 위한 요약 체크리스트

설정

• 운영자 키, 검증자 키, BLS 키 생성 및 안전한 보관
• 운영 환경에 맞게 config.toml 구성
• 거버넌스 프로세스를 통해 검증자 등록
• 모니터링 및 알림 시스템 구성

운영

• -mine 플래그로 검증자 노드 실행
• 마이닝 상태 및 블록 생성 여부 확인
• 피어 수 및 동기화 상태 지속 모니터링
• 거버넌스에서 가스 팁 변경 사항 모니터링
• 거버넌스 제안 및 투표 참여

유지보수

• 설정 파일 및 키의 정기 백업
• 디스크 공간 및 시스템 리소스 사용량 모니터링
• 오류 및 경고 로그 주기적 점검
• 업그레이드 전 테스트넷에서 사전 검증
• 변경 사항에 대해 다른 검증자 및 거버넌스 멤버와 사전 조율

보안

• 운영자 키를 콜드 스토리지 또는 멀티시그로 보호
• 검증자 키 및 BLS 키 암호화 보관
• 키 파일 권한을 올바르게 설정 (chmod 600)
• 방화벽 설정으로 불필요한 접근 차단
• 접근 제어 및 키 관리에 대한 정기 보안 점검