> ## 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 네트워크를 **처음부터 배포하는 절차**를 설명합니다.\
제네시스 파일 생성, nodekey 관리, bootnode 구성 등 **네트워크 초기 구성 단계**를 다룹니다.

StableNet 레포에서 소스로 빌드하여 배포합니다. `gstable`, `bootnode`, `genesis_generator` 등 필요한 바이너리는 Makefile 또는 `build/ci.go`로 빌드하며, 자세한 방법은 [설치 및 빌드](/ko/getting-started/2.1-installation-and-building)를 참고하세요.

다음 내용은 본 문서의 범위에 포함되지 않으며, 각 문서를 참고하세요.

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

## genesis\_generator를 사용한 제네시스 파일 생성

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

### 도구 개요

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

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

### 단일 노드 네트워크 구성

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

**프로세스 흐름:**

1. **nodekey 로딩**
   * nodekey 파일 경로 입력
   * 기본 경로: `./nodekey`

2. **검증자 키 파생**
   * nodekey(ECDSA private key)로부터 다음 정보 파생
     * 검증자 계정 주소
     * QBFT 합의용 BLS 공개 키

3. **검증자 세트 자동 구성**
   * 검증자 수: `1`
   * 쿼럼(quorum): `1`

4. **genesis.json 생성**
   * 단일 검증자를 검증자 세트에 등록
   * 해당 계정에 초기 잔액 할당
   * 선택된 합의 엔진 설정 적용

5. **config.toml 생성**
   * `StaticNodes` 항목은 비어 있는 상태로 생성
   * 단일 노드 실행을 위한 최소 설정만 포함

### 생성 결과물

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

### 다중 노드 네트워크 구성

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

**프로세스 흐름:**

1. **검증자 입력**
   * 검증자 주소 및 해당 BLS 공개 키 입력(빈 입력 시 종료)
   * 각 검증자마다 BLS 공개 키(0x 접두사, 96자 hex) 요청

2. **쿼럼 구성**
   * 거버넌스 쿼럼 값 입력
   * 다중 검증자일 때 최소 2, 최대 = 검증자 수

3. **정적 노드**
   * 선택 시 enode URL을 입력받아 `config.toml` 생성
   * 비선택 시 정적 노드는 수동 관리

4. **genesis.json 생성**
   * 입력한 검증자·BLS 키·쿼럼으로 Anzeon 설정 적용
   * `setAnzeonConfig()`로 시스템 컨트랙트 파라미터 설정

5. **저장**
   * 제네시스·설정 파일 저장 경로 지정 후 생성

### 생성 결과물

* `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 구성에 사용) |

```bash theme={null}
# nodekey 생성 (지정한 파일에 저장)
bootnode -genkey nodekey

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

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

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

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

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

### 초기화 명령

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

```bash theme={null}
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 테스트넷 노드 실행

```bash theme={null}
gstable --testnet --datadir /path/to/datadir
```

## Bootnode 구성 및 피어 연결

### 정적 노드 구성

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

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

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

```toml theme={null}
[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가 다음 규칙을 만족하는지 검사합니다.

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

### 피어 연결을 위한 Bootnode 배포

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

**1. 키 생성 및 실행**

```bash theme={null}
# 부트노드 키 생성
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를 통해 피어를 연결합니다.

```bash theme={null}
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`에서 초기 잔액 할당                 | 총 공급량이 예상과 일치하는지 확인  |

### 초기화 시퀀스

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

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

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

### 배포 후 검증

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

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

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

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