운영 가이드

​

목적 및 범위

​

네트워크 배포

​

제네시스 파일 생성

​

제네시스 구성 매개변수

​

시스템 컨트랙트 초기화

• members: 쉼표로 구분된 운영자 주소 목록
• validators: 쉼표로 구분된 검증자 주소 목록
• blsPublicKeys: 검증자 BLS 공개 키 목록 (validators 순서와 동일)
• quorum: 거버넌스 작업을 승인하기 위한 최소 투표 수
• expiry: 거버넌스 제안 만료 시간 (초 단위, 기본값: 604800 = 7일)
• gasTip: 일반 계정 트랜잭션에 적용되는 가스 팁 (wei 단위)

• name: 네이티브 토큰 이름 (예: "WKRC")
• symbol: 네이티브 토큰 심볼 (예: "WKRC")
• decimals: 토큰 소수점 자리 수 (일반적으로 18)
• currency: 토큰이 페그된 법정화폐 코드 (예: "KRW")
• masterMinter: GovMasterMinter 컨트랙트 주소
• minters: 민팅 권한을 가진 컨트랙트 주소 목록 (쉼표 구분)

​

부트노드 구성

--bootnodes enode://722f1f35c6fe2ac829aa9e0d7ef55bbe782ef3cea1e2354eefbe1584057a01b7@127.0.0.1:8589,enode://aa46e4a40781022e480bb05d1fd578fff164dc2ad379dc00370456c5ce9c2479@127.0.0.1:8589

1. --bootnodes 플래그로 명시적으로 지정된 값
2. 구성 파일에 정의된 BootstrapNodes
3. 네트워크 사전 설정 플래그 (--mainnet, --testnet)
4. 기본 Mainnet 부트노드 설정

​

네트워크 플래그 및 구성

​

검증자 운영

​

검증자 키 구조

​

키 생성 및 관리

​

ECDSA 키

# Generate operator key (for governance)
gstable account new --datadir /data/validator1

# Generate validator key (for block signing)
gstable account new --datadir /data/validator1 --keystore /data/validator1/validator-keystore

# Import existing private key
gstable account import private.key --datadir /data/validator1

​

BLS 키 파생

// Derive BLS key from ECDSA private key
blsKey, err := bls.DeriveFromECDSA(ecdsaPrivateKey)
if err != nil {
    log.Fatal("Failed to derive BLS key", "err", err)
}
blsPublicKey := blsKey.PublicKey()

​

검증자 등록

​

검증자 노드 시작

gstable \
    --datadir /data/validator1 \
    --networkid 8282 \
    --mine \
    --miner.etherbase 0xYOUR_VALIDATOR_ADDRESS

​

검증자 마이닝 프로세스

1. 검증자 상태 로드
   • 제네시스 및 최신 블록 상태를 기준으로 GovValidator 컨트랙트에 등록된 검증자 목록을 로드합니다.
   • 현재 노드의 etherbase(coinbase)가 활성 검증자 집합에 포함되어 있는지 확인합니다.
2. 검증자 키 검증
   • 합의 메시지 서명에 사용되는 키에서 파생된 주소가 etherbase 주소와 일치하는지 검증합니다.
   • 해당 검증자에 대응하는 BLS 공개 키가 GovValidator.blsPublicKeys에 올바르게 등록되어 있는지 확인합니다.
3. WBFT 합의 엔진 초기화
   • 제네시스에 정의된 Anzeon WBFT 매개변수(epoch length, block period, timeout 등)를 로드합니다.
   • 현재 블록 높이에 해당하는 WBFT 설정을 적용하여 합의 엔진을 초기화합니다.
4. 검증자 역할 결정
   • 현재 라운드와 proposer 정책에 따라 본 노드가 proposer인지 여부를 판단합니다.
   • proposer로 선택된 경우 블록 제안을 준비합니다.
5. 합의 메시지 처리 시작
   • 합의 메시지 수신을 위한 네트워크 핸들러를 활성화합니다.
   • 합의 단계별 서명 생성 및 검증 로직을 준비합니다 (BLS 서명 집계 포함).
6. 블록 생성 및 합의 참여
   • proposer인 경우 WBFTExtra를 포함한 블록을 제안합니다.
   • proposer가 아닌 경우 제안된 블록을 검증하고, 합의 단계에 따라 서명된 메시지를 전파합니다.

​

가스 팁 정책

​

인증 계정 (Authorized Account)

• 트랜잭션마다 개별 가스 팁 설정 가능
• 설정된 maxPriorityFeePerGas 값이 실제 우선순위 수수료로 적용됨
• 네트워크 혼잡 시 경쟁적 우선순위 지정 가능
• 거버넌스에서 정의된 고정 가스 팁 정책의 적용을 받지 않음

​

일반 계정 (Non-Authorized Account)

• 트랜잭션에 설정된 maxPriorityFeePerGas 값과 관계없이 거버넌스에서 정의된 고정 가스 팁이 실제 우선순위 수수료로 적용됨
• 트랜잭션에 설정된 가스 팁 값은 트랜잭션 교체(replacement) 판단을 위한 용도로만 사용됨
• 고정 가스 팁 미만의 트랜잭션은 트랜잭션 풀에서 필터링됨

​

가스 팁 업데이트

• 검증자는 거버넌스 제안을 통해 새로운 고정 가스 팁 값을 제안할 수 있습니다.
• 제안은 정족수 승인을 거쳐야 하며, 승인 및 실행 시점부터 즉시 적용됩니다.

​

에포크 전환

• 에포크 길이는 anzeon.wbft.epochLength로 구성되며, 기본값은 10블록입니다.
• 에포크 N 동안 제안 및 승인된 검증자 세트 변경 사항은 에포크 N+1 시작 시점부터 적용됩니다.
• 첫 번째 에포크의 검증자 세트는 제네시스에 정의된 anzeon.init.validators를 사용합니다.
• 이후 에포크의 검증자 세트는 GovValidator.validators 배열을 기준으로 로드됩니다.

​

거버넌스 참여

​

제안 타입

• ADD_VALIDATOR: 검증자 세트에 새로운 검증자를 추가
• REMOVE_VALIDATOR: 검증자 세트에서 기존 검증자를 제거
• SET_GAS_TIP: 필수 가스 팁 값 업데이트
• CONFIGURE_SYSTEM: 시스템 매개변수 및 설정 변경

​

투표 프로세스

• 모든 거버넌스 구성원은 컨트랙트 호출을 통해 제안을 생성할 수 있습니다.
• 다른 구성원은 vote(proposalId, approve) 호출을 통해 제안에 대해 찬성 또는 반대 투표를 수행합니다.
• 제안이 정족수에 도달하면 자동으로 실행됩니다.
• 제안은 설정된 만료 기간(기본값: 7일)이 경과하면 만료됩니다.

​

노드 모니터링 및 유지 관리

​

로깅 구성

# 전역 로그 레벨 설정
gstable --verbosity 3  # 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace

# 모듈별 로그 레벨 설정
gstable --vmodule "consensus/*=5,miner=4,eth/*=3"

# 파일 로그 출력 및 로테이션
gstable --log.file /var/log/gstable/node.log --log.rotate

# 로그 수집을 위한 JSON 포맷 출력
gstable --log.json

​

메트릭 및 모니터링

# 메트릭 서버 활성화
gstable --metrics --metrics.addr 0.0.0.0 --metrics.port 6060

# InfluxDB 메트릭 전송 활성화
gstable \
    --metrics.influxdb \
    --metrics.influxdb.endpoint http://influxdb:8086 \
    --metrics.influxdb.database gstable \
    --metrics.influxdb.username monitor \
    --metrics.influxdb.password secret

​

디스크 공간 관리

​

최소 여유 디스크 공간

# 최소 여유 디스크 공간 설정 (MB 단위)
gstable --datadir.minfreedisk 50000  # 여유 공간이 50GB 미만일 경우 종료

​

데이터베이스 크기 모니터링

• chaindata/: 메인 블록체인 상태 및 블록 데이터베이스
• ancient/: 오래된 블록 데이터를 저장하는 프리저 디렉터리 (별도 구성 시)
• blobpool/: Blob 트랜잭션 풀 관련 데이터
• ethash/: Ethash 합의 사용 시 DAG 파일 저장소

​

프루닝 및 가비지 컬렉션

# Archive 모드 (프루닝 비활성화)
gstable --gcmode archive --cache.gc 0

# Full 모드 (프루닝 활성화)
gstable --gcmode full --cache.gc 25  # 캐시의 25%를 GC에 사용

​

데이터베이스 유지 관리

​

상태 스키마 선택

# Hash-based scheme (traditional)
gstable --state.scheme hash

# Path-based scheme (recommended for new nodes)
gstable --state.scheme path

• 상태 데이터가 자동으로 프루닝됨
• 디스크 사용량이 상대적으로 낮음
• 동기화 성능이 우수함

• 구조가 성숙하고 충분히 검증됨
• 프루닝 및 가비지 컬렉션을 수동으로 제어 가능
• 오프라인 프루닝 도구 사용이 필요한 환경에 적합

​

오프라인 프루닝 복구

// Automatic recovery at startup
if scheme == rawdb.HashScheme {
    if err := pruner.RecoverPruning(stack.ResolvePath(""), chainDb); err != nil {
        log.Error("Failed to recover state", "error", err)
    }
}

​

체인 복구 및 SetHead

# 특정 블록 번호로 되돌리기
gstable attach /data/gstable.ipc --exec 'debug.setHead("0x10000")'  # 블록 65536으로 이동

# 블록 수 기준으로 되돌리기
gstable attach /data/gstable.ipc --exec 'debug.setHead("0x-100")'  # 현재 위치에서 256블록 이전으로 이동

• 손상된 블록 데이터로부터 복구
• 체인 이상 감지 후 이전 상태로 롤백
• 네트워크 분할 이후 올바른 포크로 체인 재구성

​

노드 업그레이드 절차

1. 노드 중지
   • 실행 중인 gstable 노드를 정상적으로 종료합니다.
2. 바이너리 교체
   • 기존 바이너리를 백업한 후, 새 버전의 gstable 바이너리로 교체합니다.
   • 실행 권한 및 경로 설정이 올바른지 확인합니다.
3. 구성 파일 확인
   • 새로운 버전에서 추가되거나 변경된 설정 항목이 있는지 확인합니다.
   • 기존 구성 파일과의 호환성을 검토하고 필요한 경우 값을 보완합니다.
4. 노드 재시작
   • 기존과 동일한 옵션으로 노드를 재시작합니다.
   • 검증자 노드의 경우 --mine 옵션이 포함되었는지 확인합니다.
5. 초기 로그 확인
   • 노드 시작 직후 로그를 확인하여 데이터베이스 마이그레이션, 합의 엔진 초기화, 네트워크 연결 과정에서 오류가 발생하지 않았는지 점검합니다.

• 변경 사항에 대한 릴리스 노트 검토
• 데이터베이스 백업 (chaindata/ 디렉터리)
• 중요하지 않은 노드에서 업그레이드 사전 테스트
• 검증자 노드의 경우 계획된 다운타임을 피어에 사전 공지

# 노드 버전 확인
gstable version

# 데이터베이스 버전 확인
gstable --datadir /data version-check

# 동기화 상태 확인
gstable attach --exec 'eth.syncing'

# 피어 연결 상태 확인
gstable attach --exec 'admin.peers.length'

# 검증자 노드의 경우 마이닝 상태 확인
gstable attach --exec 'eth.mining'

​

비정상 종료 감지

​

비정상 종료 처리 방식

• 노드 시작 시 LevelDB의 WAL(Write-Ahead Log)을 통해 이전 실행에서 미완료된 쓰기 작업을 자동으로 복구합니다.
• 상태 데이터베이스, 스냅샷, freezer(ancient) 데이터 간의 정합성을 검사하고, 필요 시 내부 복구 로직을 수행합니다.
• 데이터베이스가 일관된 상태로 복구되지 않을 경우 동기화 또는 상태 재구성이 트리거될 수 있습니다.

# 데이터베이스 무결성 확인
gstable --datadir /data verify-db

# 필요한 경우 인덱스 재구성
gstable --datadir /data rebuild-indexes

​

부트노드 운영

# 부트노드 키 생성
bootnode --genkey=boot.key

# 부트노드 실행
bootnode \
    --nodekey=boot.key \
    --addr=:30303 \
    --netrestrict=0.0.0.0/0 \
    --verbosity=3

# enode URL 출력
bootnode --nodekey=boot.key --writeaddress

gstable --bootnodes enode://[nodekey-pubkey]@[ip]:30303

​

네트워크 모니터링 대시보드