메인 콘텐츠로 건너뛰기

​
목적 및 범위

이 문서는 명령줄 플래그, 구성 파일, 배포 패턴을 통해 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
APIRPC 엔드포인트--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 플래그는 블록체인이 동기화되는 방식을 제어합니다:
모드값설명사용 사례
Fullfull모든 블록을 다운로드하고 모든 트랜잭션과 상태 전환을 직접 실행검증자 노드, 표준 풀 노드
Snapsnap상태 스냅샷을 먼저 다운로드한 뒤 블록을 동기화하여 빠르게 전체 상태를 구성빠른 초기 동기화가 필요한 노드
Lightlight블록 헤더만 유지하며, 필요한 상태와 데이터는 원격 노드로부터 요청저사양 환경, 헤더 기반 검증 및 조회

​
상태 스키마

--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 구성 플래그

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

​
부트스트랩 노드 구성

부트스트랩 노드는 네트워크 플래그를 기반으로 자동 선택됩니다:
  1. --bootnodes 플래그가 설정된 경우 해당 enode 사용
  2. 구성 파일에 부트노드가 지정된 경우 해당 부트노드 사용
  3. --mainnet인 경우 StableNet mainnet 부트노드 사용
  4. --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 구성

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

​
WebSocket 구성

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

​
IPC 구성

IPC는 기본적으로 활성화되며 <datadir>/gstable.ipc 경로에 소켓이 생성됩니다.
플래그용도기본값
--ipcdisableIPC 비활성화false
--ipcpathIPC 소켓 경로gstable.ipc

​
API 네임스페이스 보안

모든 API 네임스페이스를 공개적으로 노출해서는 안 됩니다. 권장 구성:
배포 유형HTTP APIsWebSocket APIs비고
공용 RPC 노드eth,net,web3eth,net,web3읽기 전용, 공개 안전
검증자 노드없음 또는 localhost만없음공격 표면 최소화
개발 노드eth,net,web3,personal,debug,admin동일테스트용 전체 액세스
아카이브 노드eth,net,web3,txpool,debug동일분석용 Debug API
경고: personal, admin, debug 네임스페이스는 권한이 있는 작업을 제공합니다. 인증 없이 공개 인터페이스에서 노출하지 마세요.

​
RPC 제한 플래그

플래그용도기본값
--rpc.gascapeth_call / eth_estimateGas 최대 가스50,000,000
--rpc.evmtimeouteth_call 타임아웃5초
--rpc.txfeecapeth_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초기 동기화 가속
풀 노드2048full균형 잡힌 성능
아카이브 노드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
제네시스 파일 구조에 대한 자세한 내용은 제네시스 설정 및 네트워크 초기화를 참조하세요.