노드 구성 - StableNet

목적 및 범위

이 문서는 명령줄 플래그, 구성 파일, 배포 패턴을 통해 StableNet 노드를 구성하는 방법을 설명합니다. 노드 바이너리 빌드에 대한 정보는 설치 및 빌드를 참조하세요. 제네시스 블록 설정 및 네트워크 초기화는 제네시스 설정 및 네트워크 초기화를 참조하세요.

구성 시스템 개요

StableNet 노드 구성은 명령줄 플래그를 구조화된 설정 객체로 변환하고, 이를 통해 각 컴포넌트를 초기화하는 계층적 구성 시스템입니다. 구성 우선순위: 명령줄 플래그 > TOML 설정 파일 > 기본값

명령줄 플래그

모든 구성 플래그는 cmd/utils/flags.go에 정의되어 있으며 카테고리별로 구성됩니다.

핵심 플래그 카테고리

카테고리	용도	주요 플래그
체인/동기화	체인 및 동기화 설정	`--datadir`, `--networkid`, `--syncmode`, `--mainnet`, `--testnet`
계정	키 관리	`--keystore`, `--unlock`, `--password`
마이닝	블록 생성	`--mine`, `--miner.etherbase`, `--miner.gaslimit`
네트워킹	P2P 구성	`--port`, `--maxpeers`, `--bootnodes`, `--nat`
API	RPC 엔드포인트	`--http`, `--http.port`, `--ws`, `--http.api`
트랜잭션 풀	트랜잭션 풀	`--txpool.pricelimit`, `--txpool.globalslots`
성능	성능 튜닝	`--cache`, `--cache.database`, `--cache.trie`
상태	상태 관리	`--state.scheme`, `--gcmode`

네트워크 선택 플래그

StableNet은 사전 정의된 네트워크를 선택하기 위한 플래그를 제공합니다:

--mainnet: ChainID 8282, StableNet 메인넷에 연결
--testnet: ChainID 8283, StableNet 테스트넷에 연결
--networkid: 자동 네트워크 ID를 재정의 (기본값은 체인 ID)
부트스트랩 노드는 네트워크 플래그를 기반으로 자동 선택됩니다

데이터 디렉터리

—datadir 플래그는 노드가 블록체인 데이터와 상태를 저장하는 기본 루트 디렉터리를 지정합니다. 키스토어를 포함한 일부 하위 경로는 별도 플래그로 재정의할 수 있으며, 지정하지 않을 경우 내부 기본 디렉터리가 사용됩니다.

플래그	용도	기본값
`--datadir`	모든 데이터의 루트 디렉터리	Linux: `~/.stablenet`, macOS: `~/Library/StableNet`
`--datadir.ancient`	고대/프리저 데이터의 별도 위치	`<datadir>/gstable/ancient`
`--keystore`	키스토어 위치 재정의	`<datadir>/keystore`
`--datadir.minfreedisk`	자동 종료 디스크 임계값 (MB)	0 (비활성화)

데이터베이스 설정

노드가 사용하는 데이터베이스 엔진의 종류를 설정합니다. 이 설정은 상태(state)와 체인 데이터를 어떻게 저장하고 접근할지에 대한 내부 구현을 결정하며, 노드의 성능 특성과 리소스 사용 방식에 영향을 줍니다.

플래그	설명	기본값
`--db.engine`	상태 및 체인 데이터베이스 엔진 선택	`pebble`

동기화 모드

--syncmode 플래그는 블록체인이 동기화되는 방식을 제어합니다:

모드	값	설명	사용 사례
Full	`full`	모든 블록을 다운로드하고 모든 트랜잭션과 상태 전환을 직접 실행	검증자 노드, 표준 풀 노드
Snap	`snap`	상태 스냅샷을 먼저 다운로드한 뒤 블록을 동기화하여 빠르게 전체 상태를 구성	빠른 초기 동기화가 필요한 노드
Light	`light`	블록 헤더만 유지하며, 필요한 상태와 데이터는 원격 노드로부터 요청	저사양 환경, 헤더 기반 검증 및 조회

상태 스키마

--state.scheme 플래그는 상태 저장소 레이아웃을 선택합니다:

hash: 레거시 해시 기반 스키마 (기본값, 안정적)
path: 경로 기반 스키마, verkle trie 지원 (실험적)

지정하지 않으면 노드는 기존 데이터베이스와 일치하는 스키마를 자동 선택합니다.

마이닝 및 검증자 구성

StableNet 검증자(Anzeon 활성화 네트워크)의 블록 생성을 제어하는 플래그입니다.

마이닝 플래그

플래그	용도	기본값	비고
`--mine`	마이닝/검증 활성화	false	검증자 필수
`--miner.etherbase`	블록 보상 주소	노드 키 주소	Anzeon에서 자동 설정됨
`--miner.gaslimit`	블록 가스 상한	105,000,000	블록 가스 리밋 목표
`--miner.extradata`	블록 추가 데이터	클라이언트 버전	사용자 지정 식별자

Anzeon 네트워크 설계 특성

etherbase는 --nodekey에서 파생된 계정 주소로 자동 설정되며, 사용자 지정이 허용되지 않습니다
GasTip(우선순위 수수료)는 GovValidator 거버넌스를 통해 네트워크 전역 값으로 강제 적용됩니다 (인증 계정 제외)
BaseFee는 StableNet에서 커스터마이징된 계산 로직을 사용하며, 증가·감소 비율, 최소·최대 제한이 체인 파라미터에 의해 제어됩니다
BaseFee는 소각 되지 않고 검증자에게 분배됩니다

가스 수수료 정책에 대한 상세 정보는 가스 수수료 정책을 참조하세요. 검증자 거버넌스를 통한 가스 팁 관리는 검증자 거버넌스를 참조하세요.

P2P 네트워크 구성

P2P 네트워킹 플래그는 피어 발견과 연결 관리를 제어합니다.

P2P 구성 플래그

플래그	용도	기본값
`--port`	P2P 리스닝 포트	30303
`--maxpeers`	최대 피어 연결 수	50
`--nat`	NAT 포트 매핑 방식	`any`
`--bootnodes`	부트스트랩 노드 enode URL (쉼표 구분)	네트워크별 자동 선택
`--nodiscover`	피어 발견 비활성화	false
`--nodekey`	P2P 노드 키 파일 경로	자동 생성
`--netrestrict`	허용 네트워크 CIDR 마스크	없음 (모두 허용)

부트스트랩 노드 구성

부트스트랩 노드는 네트워크 플래그를 기반으로 자동 선택됩니다:

--bootnodes 플래그가 설정된 경우 해당 enode 사용
구성 파일에 부트노드가 지정된 경우 해당 부트노드 사용
--mainnet인 경우 StableNet mainnet 부트노드 사용
--testnet인 경우 StableNet testnet 부트노드 사용

정적 및 신뢰 피어

TOML 설정 파일의 [Node.P2P] 섹션에서 정적 피어와 신뢰 피어를 구성합니다:

[Node.P2P]
StaticNodes = [
  "enode://pubkey1@ip1:port1",
  "enode://pubkey2@ip2:port2"
]
TrustedNodes = [
  "enode://pubkey3@ip3:port3"
]

StaticNodes: 항상 연결을 유지하는 피어
TrustedNodes: 피어 제한에서 제외되는 피어

RPC API 구성

RPC API는 노드 기능을 외부 클라이언트에 노출합니다. StableNet은 HTTP, WebSocket, IPC 전송을 지원합니다.

HTTP 구성

플래그	용도	기본값
`--http`	HTTP-RPC 서버 활성화	비활성화
`--http.addr`	리스닝 인터페이스	`localhost`
`--http.port`	리스닝 포트	8545
`--http.api`	노출할 API 모듈	`eth,net,web3`
`--http.corsdomain`	CORS 허용 도메인	없음
`--http.vhosts`	가상 호스트 허용 목록	`localhost`

WebSocket 구성

플래그	용도	기본값
`--ws`	WebSocket 서버 활성화	비활성화
`--ws.addr`	리스닝 인터페이스	`localhost`
`--ws.port`	리스닝 포트	8546
`--ws.api`	노출할 API 모듈	`eth,net,web3`
`--ws.origins`	허용 오리진	없음

IPC 구성

IPC는 기본적으로 활성화되며 <datadir>/gstable.ipc 경로에 소켓이 생성됩니다.

플래그	용도	기본값
`--ipcdisable`	IPC 비활성화	false
`--ipcpath`	IPC 소켓 경로	`gstable.ipc`

API 네임스페이스 보안

모든 API 네임스페이스를 공개적으로 노출해서는 안 됩니다. 권장 구성:

배포 유형	HTTP APIs	WebSocket APIs	비고
공용 RPC 노드	`eth,net,web3`	`eth,net,web3`	읽기 전용, 공개 안전
검증자 노드	없음 또는 localhost만	없음	공격 표면 최소화
개발 노드	`eth,net,web3,personal,debug,admin`	동일	테스트용 전체 액세스
아카이브 노드	`eth,net,web3,txpool,debug`	동일	분석용 Debug API

경고: personal, admin, debug 네임스페이스는 권한이 있는 작업을 제공합니다. 인증 없이 공개 인터페이스에서 노출하지 마세요.

RPC 제한 플래그

플래그	용도	기본값
`--rpc.gascap`	`eth_call` / `eth_estimateGas` 최대 가스	50,000,000
`--rpc.evmtimeout`	`eth_call` 타임아웃	5초
`--rpc.txfeecap`	`eth_sendTransaction` 최대 수수료	0 (제한 없음)
`--rpc.batch-request-limit`	배치당 최대 요청 수	1000
`--rpc.batch-response-max-size`	배치 응답 최대 크기	25MB

이러한 제한은 악의적이거나 잘못 구성된 클라이언트로 인한 리소스 고갈을 방지합니다.

성능 튜닝

캐시 및 데이터베이스 설정은 노드 성능과 리소스 사용에 큰 영향을 미칩니다.

캐시 구성

--cache 플래그는 총 메모리 할당을 설정하며, 하위 시스템 간에 분할됩니다. 기본 할당:

총 캐시: 1024 MB
├─ Database: 512 MB (50%)
├─ Trie Clean: 154 MB (15%)
├─ Snapshot: 102 MB (10%)
└─ Trie Dirty (GC): 256 MB (25%)

아카이브 노드(--gcmode archive)의 경우 Trie Dirty 캐시가 비활성화되고 Trie Clean과 Snapshot으로 재할당됩니다. 노드 유형별 권장 설정:

노드 유형	`--cache`	`--gcmode`	비고
검증자 (동기화 완료)	4096+	`full`	빠른 상태 액세스
검증자 (초기 동기화)	8192+	`full`	초기 동기화 가속
풀 노드	2048	`full`	균형 잡힌 성능
아카이브 노드	8192+	`archive`	프루닝 없음, 대용량 디스크 필요

데이터베이스 엔진 선택

--db.engine 플래그는 기본 키-값 저장소를 선택합니다:

pebble (기본값): 현대적이고 빠르며 더 나은 압축
leveldb: 레거시, 안정적, 기존 데이터베이스 호환

새 배포에는 Pebble을 권장합니다.

가비지 컬렉션 및 프루닝

--gcmode 플래그는 상태 프루닝 동작을 제어합니다:

full (기본값): 오래된 상태 trie를 프루닝하고 최근 상태만 유지
archive: 프루닝 없이 모든 과거 상태 유지 (수 TB 디스크 필요)

일반적인 구성 패턴

검증자 노드

gstable --mainnet \
  --mine \
  --nodekey /path/to/nodekey \
  --syncmode full \
  --datadir /data/gstable \
  --cache 4096 \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --port 30303 \
  --maxpeers 50

--mine은 블록 생성을 활성화합니다
--nodekey는 검증자의 운영 키를 지정합니다 (Anzeon에서 etherbase로도 사용)
보안을 위해 RPC는 localhost에만 바인딩
검증자는 반드시 --syncmode full 사용

공용 RPC 노드

gstable --mainnet \
  --syncmode snap \
  --datadir /data/gstable \
  --cache 2048 \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --http.corsdomain "*" \
  --http.vhosts "*" \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  --maxpeers 100

검증자가 아니므로 --syncmode snap 허용
공용 액세스를 위해 0.0.0.0에 바인딩
안전한 API만 노출 (eth, net, web3)

개발 노드

gstable --dev \
  --dev.period 1 \
  --datadir /tmp/gstable-dev \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,personal,debug,admin \
  --allow-insecure-unlock

--dev는 사전 자금이 있는 계정으로 임시 개발 네트워크를 생성합니다
--dev.period 1은 매초 블록을 생성합니다
디버깅을 위해 모든 API 활성화
--allow-insecure-unlock은 HTTP 계정 잠금 해제를 허용합니다 (개발 전용)

아카이브 노드

gstable --mainnet \
  --syncmode full \
  --gcmode archive \
  --datadir /data/gstable-archive \
  --cache 8192 \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,debug,trace \
  --maxpeers 50

--gcmode archive는 상태 프루닝을 비활성화합니다
분석에 유용한 debug 및 trace API
상당한 디스크 공간 필요 (수 TB)

구성 파일

명령줄 플래그가 주요 구성 방법이지만, TOML 구성 파일을 사용하면 복잡한 배포를 편리하게 관리할 수 있습니다.

TOML 구성 파일

현재 노드 설정을 TOML 파일로 내보내려면:

gstable dumpconfig > config.toml

생성된 파일을 편집한 후 --config 플래그로 로드합니다:

gstable --config config.toml

주요 TOML 섹션 예시:

[Eth]
NetworkId = 8282
SyncMode = "full"
NoPruning = false

[Eth.Miner]
GasCeil = 105000000

[Node]
DataDir = "/data/gstable"
HTTPHost = "0.0.0.0"
HTTPPort = 8545
HTTPModules = ["eth", "net", "web3"]
WSHost = "0.0.0.0"
WSPort = 8546
WSModules = ["eth", "net", "web3"]
IPCPath = "gstable.ipc"

[Node.P2P]
MaxPeers = 100
ListenAddr = ":30303"
StaticNodes = []
TrustedNodes = []

구성 우선순위: 명령줄 플래그 > TOML 파일 설정 > 기본값

제네시스 구성

커스텀 네트워크의 경우 제네시스 구성은 JSON으로 제공되며 gstable init 명령을 통해 로드됩니다:

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

제네시스 파일 구조에 대한 자세한 내용은 제네시스 설정 및 네트워크 초기화를 참조하세요.

​목적 및 범위

​구성 시스템 개요

​명령줄 플래그

​핵심 플래그 카테고리

​네트워크 선택 플래그

​데이터 디렉터리

​데이터베이스 설정

​동기화 모드

​상태 스키마

​마이닝 및 검증자 구성

​마이닝 플래그

​Anzeon 네트워크 설계 특성

​P2P 네트워크 구성

​P2P 구성 플래그

​부트스트랩 노드 구성

​정적 및 신뢰 피어

​RPC API 구성

​HTTP 구성

​WebSocket 구성

​IPC 구성

​API 네임스페이스 보안

​RPC 제한 플래그

​성능 튜닝

​캐시 구성

​데이터베이스 엔진 선택

​가비지 컬렉션 및 프루닝

​일반적인 구성 패턴

​검증자 노드

​공용 RPC 노드

​개발 노드

​아카이브 노드

​구성 파일

​TOML 구성 파일

​제네시스 구성