네트워크 배포

목적 및 범위

이 문서는 프라이빗 StableNet 네트워크를 처음부터 배포하는 절차를 설명합니다.
제네시스 파일 생성, nodekey 관리, bootnode 구성 등 네트워크 초기 구성 단계를 다룹니다. StableNet 레포에서 소스로 빌드하여 배포합니다. gstable, bootnode, genesis_generator 등 필요한 바이너리는 Makefile 또는 build/ci.go로 빌드하며, 자세한 방법은 설치 및 빌드를 참고하세요. 다음 내용은 본 문서의 범위에 포함되지 않으며, 각 문서를 참고하세요.

노드별 설정 및 실행 옵션:
/ko/getting-started/2.2-node-configuration
제네시스 구조 및 시스템 컨트랙트 초기화:
/ko/getting-started/2.3-genesis-setup-and-network-initialization
네트워크 배포 이후 검증자 운영 절차:
/ko/operations-guide/11.2-validator-operations

genesis_generator를 사용한 제네시스 파일 생성

genesis_generator는 StableNet 네트워크 초기화를 위해 제공되는 제네시스 생성 전용 CLI 도구입니다.
합의 엔진, 검증자 구성, 네트워크 토폴로지에 맞는 제네시스 파일과 기본 설정 파일을 생성합니다.

도구 개요

genesis_generator는 다음 작업을 자동으로 수행합니다.

nodekey 기반 검증자 정보 추출
합의 엔진에 맞는 제네시스 구조 생성
초기 검증자 세트 및 쿼럼(quorum) 계산
genesis.json, config.toml 생성

단일 노드 네트워크 구성

개발 및 테스트 목적의 최소 구성으로 단일 노드 기반 네트워크 설정을 생성할 수 있습니다.
해당 구성은 네트워크 초기화 및 기능 검증용이며, 실제 노드 배포 또는 운영 환경에는 적합하지 않습니다. 프로세스 흐름:

nodekey 로딩
- nodekey 파일 경로 입력
- 기본 경로: ./nodekey
검증자 키 파생
- nodekey(ECDSA private key)로부터 다음 정보 파생
  - 검증자 계정 주소
  - QBFT 합의용 BLS 공개 키
검증자 세트 자동 구성
- 검증자 수: 1
- 쿼럼(quorum): 1
genesis.json 생성
- 단일 검증자를 검증자 세트에 등록
- 해당 계정에 초기 잔액 할당
- 선택된 합의 엔진 설정 적용
config.toml 생성
- StaticNodes 항목은 비어 있는 상태로 생성
- 단일 노드 실행을 위한 최소 설정만 포함

생성 결과물

genesis.json
네트워크 ID, 합의 설정, 검증자 정보, 초기 상태 포함
config.toml
노드 실행을 위한 기본 설정 파일(단일 노드 시 StaticNodes는 빈 배열)

다중 노드 네트워크 구성

개발 및 테스트, 프로덕션 네트워크를 위해 다중 노드 기반 네트워크 설정을 생성할 수 있습니다.
거버넌스 쿼럼이 있는 검증자 세트를 지원하며, 대화형으로 검증자·쿼럼·정적 노드를 입력합니다. 프로세스 흐름:

검증자 입력
- 검증자 주소 및 해당 BLS 공개 키 입력(빈 입력 시 종료)
- 각 검증자마다 BLS 공개 키(0x 접두사, 96자 hex) 요청
쿼럼 구성
- 거버넌스 쿼럼 값 입력
- 다중 검증자일 때 최소 2, 최대 = 검증자 수
정적 노드
- 선택 시 enode URL을 입력받아 config.toml 생성
- 비선택 시 정적 노드는 수동 관리
genesis.json 생성
- 입력한 검증자·BLS 키·쿼럼으로 Anzeon 설정 적용
- setAnzeonConfig()로 시스템 컨트랙트 파라미터 설정
저장
- 제네시스·설정 파일 저장 경로 지정 후 생성

생성 결과물

genesis.json
네트워크 ID, 합의 설정, 검증자 목록·BLS 공개 키·쿼럼, 시스템 컨트랙트 파라미터(GovValidator 등) 포함
config.toml
노드 실행을 위한 기본 설정 파일(정적 노드 선택 시 입력한 enode URL로 StaticNodes 구성, 비선택 시 빈 배열)

Nodekey 생성 및 관리

검증자를 배포하기 전에 각 노드에는 여러 용도로 사용되는 고유한 nodekey가 필요합니다:

Nodekey에서 파생되는 정보

각 노드의 nodekey(ECDSA 개인 키)는 검증자 주소(블록 서명·coinbase)와 BLS 키 쌍(합의 서명)으로 파생됩니다. 이 파생은 genesis_generator의 deriveAccount(), bootnode, 그리고 노드 네트워크 구성(정적 노드·enode URL 등)에서 사용됩니다.

Nodekey 생성

bootnode 유틸리티로 nodekey를 생성하고, 필요 시 공개 키(enode용)를 확인할 수 있습니다. 주요 플래그는 다음과 같습니다.

플래그	설명
`-genkey`	nodekey를 생성하여 지정한 파일에 저장
`-nodekey`	사용할 개인 키 파일 경로 지정
`-writeaddress`	노드 공개 키를 출력하고 종료(enode URL 구성에 사용)

# nodekey 생성 (지정한 파일에 저장)
bootnode -genkey nodekey

# 저장된 키에서 공개 키 출력 (enode URL의 공개키 부분)
bootnode -nodekey nodekey -writeaddress

네트워크 초기화 워크플로우

제네시스 초기화 프로세스

제네시스·설정 생성: genesis_generator로 genesis.json(및 선택 시 config.toml) 생성
파일 배치: 각 노드의 데이터 디렉터리로 쓸 위치에 동일한 genesis.json을 복사
데이터 디렉터리 초기화: 노드마다 gstable init으로 제네시스 블록을 쓰고, 이후 해당 디렉터리로 노드 실행

init은 기존 데이터를 덮어쓰는 동작이므로, 초기화할 디렉터리에는 사용 중인 체인 데이터가 없어야 합니다. Anzeon 제네시스인 경우 init 시 합의·시스템 컨트랙트 설정이 검증됩니다.

초기화 명령

gstable init은 인자로 제네시스 파일 경로 하나만 받습니다. 데이터를 쓸 디렉터리는 --datadir로 지정합니다.

gstable --datadir /path/to/datadir init /path/to/genesis.json

--datadir: 초기화할 데이터 디렉터리(생략 시 기본값 사용)
<genesisPath>: 사용할 genesis.json 경로

노드 실행 시에도 같은 --datadir을 주고, 제네시스의 config.chainId와 맞추려면 --networkid를 지정합니다.

네트워크 프리셋 (—mainnet, —testnet)

프라이빗 네트워크가 아니라 이미 구성된 StableNet 공용 네트워크에 참여할 때는 네트워크 프리셋 플래그를 사용합니다. 제네시스와 부트노드가 내장되어 있어 별도 genesis.json 없이 노드를 실행할 수 있습니다.

플래그	설명	네트워크 ID	용도
`--mainnet`	StableNet 메인넷	8282	StableNet 메인넷 연결
`--testnet`	StableNet 테스트넷	8283	사전 구성된 StableNet 테스트 네트워크 연결

두 플래그는 서로 배타적이며 동시에 지정할 수 없습니다.
--mainnet 또는 --testnet을 쓰면 해당 제네시스와 부트노드 목록이 자동 적용되고, --networkid를 지정하지 않으면 위 표의 네트워크 ID가 사용됩니다.

예: StableNet 테스트넷 노드 실행

gstable --testnet --datadir /path/to/datadir

Bootnode 구성 및 피어 연결

정적 노드 구성

정적 노드(StaticNodes)는 노드가 시작 시 연결을 시도할 피어 목록입니다. genesis_generator가 생성하는 config.toml의 [Node.P2P] 섹션에서 이 목록을 정의합니다.

단일 노드: StaticNodes는 빈 배열([])로 생성됩니다. 별도 피어 없이 단일 노드만 실행하는 구성입니다.
다중 노드: 대화형으로 enode URL을 입력하면, 그 목록으로 StaticNodes가 채워진 config.toml이 생성됩니다. 각 검증자 노드의 enode를 넣어 두면 노드 간 피어 연결이 수월해집니다.

다중 노드 구성 시 config.toml 예시:

[Node.P2P]
StaticNodes = [
  "enode://<128자_hex_공개키>@<IP>:<포트>",
  "enode://<128자_hex_공개키>@<IP>:<포트>"
]

Enode URL 구조

enode URL은 P2P에서 노드를 식별하며, 정적 노드·bootnode 목록에 사용합니다. 형식: enode://<공개키(128자 16진수)>@<호스트>:<포트>

공개키: 노드의 ECDSA 공개 키 64바이트를 16진수 128자로 표현
호스트·포트: 노드가 리스닝하는 IP(또는 호스트명)와 포트

genesis_generator의 validateEnodeURL()은 입력한 enode가 다음 규칙을 만족하는지 검사합니다.

enode:// 프로토콜 접두사로 시작
공개 키는 정확히 128개의 16진수 문자
호스트는 유효한 IPv4 또는 IPv6 주소
포트는 1–65535 범위의 정수

피어 연결을 위한 Bootnode 배포

프로덕션 네트워크에서는 피어 연결을 위해 전용 bootnode를 두는 것을 권장합니다. bootnode는 전체 체인을 유지하지 않고 디스커버리만 제공합니다. 1. 키 생성 및 실행

# 부트노드 키 생성
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

2. 클라이언트에서 사용 각 노드 실행 시 -bootnodes에 bootnode의 enode URL을 넣으면, 해당 bootnode를 통해 피어를 연결합니다.

gstable -bootnodes enode://<공개키>@<bootnode-IP>:30303 -datadir /path/to/datadir

프로덕션 네트워크 배포 체크리스트

배포 전 준비

Task	Details	Verification
Generate Nodekeys	`bootnode -genkey`를 사용하여 검증자당 하나씩	주소 및 BLS 키 파생 확인
Create Genesis File	모든 검증자 주소/BLS 키로 `genesis_generator` 사용	JSON 구조 검증, 쿼럼 설정 확인
Configure Static Nodes	모든 검증자 enode URL로 `config.toml` 빌드	enode URL 연결성 테스트
Set Chain Parameters	고유한 chainId 선택, 가스 제한 설정, 시스템 컨트랙트 구성	가스 팁 정책 검토, 민트/번 쿼럼
Pre-fund Accounts	제네시스 `alloc`에서 초기 잔액 할당	총 공급량이 예상과 일치하는지 확인

초기화 시퀀스

모든 노드에 동일한 genesis.json 복사
노드마다 gstable -datadir <경로> init <genesis.json 경로> 실행
각 노드에서 gstable -datadir <경로> -networkid <chainId> (및 필요 시 -bootnodes, -config)로 실행

노드 실행 시 자주 쓰는 플래그:

플래그	설명
`-datadir`	데이터 디렉터리(init 시와 동일하게 지정)
`-networkid`	제네시스의 chainId와 동일하게 지정
`-bootnodes`	bootnode enode URL(쉼표 구분, 피어 연결용)
`-config`	config.toml 경로(정적 노드 등 설정)

배포 후 검증

노드 기동 후 다음을 확인합니다.

피어 수: gstable attach로 연결 후 admin.peers.length로 연결된 피어 수 확인
합의: 블록 생성 및 최종화가 정상적으로 이어지는지 모니터링
트랜잭션: 각 노드에 테스트 트랜잭션을 보내 전파·실행 여부 확인
가스 팁: 거버넌스에서 정한 가스 팁이 적용되는지 확인
시스템 컨트랙트: GovValidator.getValidators() 호출로 검증자 세트가 제네시스와 일치하는지 확인

시스템 컨트랙트 배포 검증

네트워크 초기화 후, 제네시스에 정의된 시스템 컨트랙트가 올바르게 배포되었는지 확인할 수 있습니다. 제네시스 적용 시 GetSystemContractsTransition()이 호출되어 컨트랙트 코드를 설정하고, 제네시스 매개변수로 저장소를 초기화합니다. RPC로 시스템 컨트랙트 주소에 대해 코드·저장소를 조회하면 배포 여부를 검증할 수 있습니다.

StableNet 개요

시작하기

핵심 아키텍처

합의 및 블록 생성

거버넌스 시스템

트랜잭션 처리

네트워킹

RPC 및 API

저장소 아키텍처

개발 도구

운영 가이드

네트워크 배포

목적 및 범위

genesis_generator를 사용한 제네시스 파일 생성

도구 개요

단일 노드 네트워크 구성

생성 결과물

다중 노드 네트워크 구성

생성 결과물

Nodekey 생성 및 관리

Nodekey에서 파생되는 정보

Nodekey 생성

네트워크 초기화 워크플로우

제네시스 초기화 프로세스

초기화 명령

네트워크 프리셋 (—mainnet, —testnet)

Bootnode 구성 및 피어 연결

정적 노드 구성

Enode URL 구조

피어 연결을 위한 Bootnode 배포

프로덕션 네트워크 배포 체크리스트

배포 전 준비

초기화 시퀀스

배포 후 검증

시스템 컨트랙트 배포 검증

StableNet 개요

시작하기

핵심 아키텍처

합의 및 블록 생성

거버넌스 시스템

트랜잭션 처리

네트워킹

RPC 및 API

저장소 아키텍처

개발 도구

운영 가이드

​목적 및 범위

​genesis_generator를 사용한 제네시스 파일 생성

​도구 개요

​단일 노드 네트워크 구성

​생성 결과물

​다중 노드 네트워크 구성

​생성 결과물

​Nodekey 생성 및 관리

​Nodekey에서 파생되는 정보

​Nodekey 생성

​네트워크 초기화 워크플로우

​제네시스 초기화 프로세스

​초기화 명령

​네트워크 프리셋 (—mainnet, —testnet)

​Bootnode 구성 및 피어 연결

​정적 노드 구성

​Enode URL 구조

​피어 연결을 위한 Bootnode 배포

​프로덕션 네트워크 배포 체크리스트

​배포 전 준비

​초기화 시퀀스

​배포 후 검증

​시스템 컨트랙트 배포 검증

목적 및 범위

genesis_generator를 사용한 제네시스 파일 생성

도구 개요

단일 노드 네트워크 구성

생성 결과물

다중 노드 네트워크 구성

생성 결과물

Nodekey 생성 및 관리

Nodekey에서 파생되는 정보

Nodekey 생성

네트워크 초기화 워크플로우

제네시스 초기화 프로세스

초기화 명령

네트워크 프리셋 (—mainnet, —testnet)

Bootnode 구성 및 피어 연결

정적 노드 구성

Enode URL 구조

피어 연결을 위한 Bootnode 배포

프로덕션 네트워크 배포 체크리스트

배포 전 준비

초기화 시퀀스

배포 후 검증

시스템 컨트랙트 배포 검증