> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 노드 구성

## 목적 및 범위

이 문서는 명령줄 플래그, 구성 파일, 배포 패턴을 통해 StableNet 노드를 구성하는 방법을 설명합니다.

노드 바이너리 빌드에 대한 정보는 [설치 및 빌드](/ko/getting-started/2.1-installation-and-building)를 참조하세요. 제네시스 블록 설정 및 네트워크 초기화는 [제네시스 설정 및 네트워크 초기화](/ko/getting-started/2.3-genesis-setup-and-network-initialization)를 참조하세요.

## 구성 시스템 개요

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`는 소각 되지 않고 검증자에게 분배됩니다

가스 수수료 정책에 대한 상세 정보는 [가스 수수료 정책](/ko/transaction-processing/6.4-gas-fee-policy)을 참조하세요. 검증자 거버넌스를 통한 가스 팁 관리는 [검증자 거버넌스](/ko/governance-system/5.3-validator-governance-\(govvalidator\))를 참조하세요.

## P2P 네트워크 구성

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

### P2P 구성 플래그

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

### 부트스트랩 노드 구성

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

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

### 정적 및 신뢰 피어

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

```toml theme={null}
[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 디스크 필요)

## 일반적인 구성 패턴

### 검증자 노드

```bash theme={null}
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 노드

```bash theme={null}
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`)

### 개발 노드

```bash theme={null}
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 계정 잠금 해제를 허용합니다 (개발 전용)

### 아카이브 노드

```bash theme={null}
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 파일로 내보내려면:

```bash theme={null}
gstable dumpconfig > config.toml
```

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

```bash theme={null}
gstable --config config.toml
```

주요 TOML 섹션 예시:

```toml theme={null}
[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` 명령을 통해 로드됩니다:

```bash theme={null}
gstable init /path/to/genesis.json --datadir /path/to/datadir
```

제네시스 파일 구조에 대한 자세한 내용은 [제네시스 설정 및 네트워크 초기화](/ko/getting-started/2.3-genesis-setup-and-network-initialization)를 참조하세요.