> ## 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 노드의 초기화 시퀀스 및 라이프사이클 관리를 설명합니다. 명령줄 호출부터 완전한 종료까지의 과정을 다루며, 구성 로딩, 제네시스 설정, 컴포넌트 초기화, 서비스 조정, 정상 종료 절차를 포함합니다.

관련 문서:

* 제네시스 파일 생성 및 네트워크 초기화: [Genesis Setup and Network Initialization](/ko/getting-started/2.3-genesis-setup-and-network-initialization)
* 합의별 초기화(WBFT): [Anzeon WBFT 합의 프로토콜](/ko/consensus-and-block-production/4.1-anzeon-wbft-consensus-protocol)
* 일반 노드 구성 옵션: [Node Configuration](/ko/getting-started/2.2-node-configuration)

## 전체 초기화 시퀀스

노드 초기화는 CLI 플래그 파싱부터 완전히 실행 중인 노드까지 다음 순서를 따릅니다:

```
CLI 플래그 파싱 → 구성 로드 → node.Node 생성
→ eth.Ethereum 백엔드 초기화 (DB, 체인, 풀, 마이너)
→ API/프로토콜 등록 → 서비스 시작 → 런타임 모니터링
```

## 구성 단계

### 플래그 파싱 및 데이터 디렉터리 설정

노드는 시작 시 내부 기본값을 초기화한 후, 네트워크 설정, 설정 파일, 명령줄 플래그 순으로 설정을 적용하여 최종 실행 구성을 결정합니다.
후속 단계의 설정은 이전 단계에서 설정된 값을 덮어씁니다.

| 적용 단계 | 구성 소스      | 설명                              |
| ----- | ---------- | ------------------------------- |
| 4     | 명령줄 플래그    | 실행 시점에 지정되는 최종 오버라이드 값          |
| 3     | TOML 설정 파일 | 사용자가 정의한 영구 설정                  |
| 2     | 네트워크 사전 설정 | Mainnet / Testnet 등 네트워크별 기본 설정 |
| 1     | 하드코딩된 기본값  | 코드에 정의된 초기 기본값                  |

데이터 디렉터리를 별도로 지정하지 않을 경우 내부 기본 디렉터리를 사용합니다.

### 제네시스 블록 초기화

제네시스 블록은 블록체인의 초기 상태를 설정합니다. 노드는 기존 제네시스를 데이터베이스에서 로드하거나, 없는 경우 새로 초기화합니다.

Anzeon/WBFT 네트워크의 경우 제네시스 초기화에는 다음과 같은 추가 작업이 포함됩니다:

1. BLS 공개 키를 포함한 초기 검증자 세트 구성
2. 시스템 컨트랙트 배포 (GovValidator, NativeCoinAdapter 등)
3. WBFT 전용 Extra 데이터 인코딩
4. 초기 가스 팁 파라미터 설정

## 노드 및 백엔드 생성

### 노드 컨테이너

`node.Node`는 서비스 조정자 역할을 합니다. P2P 서버, RPC 엔드포인트, 등록된 서비스를 관리하며, `RegisterLifecycle()`과 `RegisterAPIs()`를 통해 하위 서비스를 등록받습니다.

### Ethereum 백엔드 초기화

`eth.Ethereum`은 전체 프로토콜을 구현하는 주요 서비스입니다. `eth.New()` 생성자는 다음 순서로 초기화를 수행합니다:

1. **데이터베이스 설정**: ancient/freezer 저장소를 포함한 chaindata 데이터베이스 열기
2. **상태 스키마 선택**: 해시 기반 또는 경로 기반 상태 저장소 구성
3. **합의 엔진 생성**: 체인 설정에 따라 WBFT, Clique 또는 Ethash 선택
4. **Etherbase 설정**: Anzeon 네트워크의 경우 노드 키에서 파생된 주소로 자동 설정
5. **BlockChain 생성**: 제네시스 로드, 캐시 및 스냅샷 구성
6. **트랜잭션 풀 설정**: legacypool과 blobpool 초기화
7. **프로토콜 핸들러 생성**: P2P 동기화 및 전파 로직 구성
8. **마이너 생성**: 블록 조립 워커 초기화
9. **API 및 라이프사이클 등록**: RPC API, P2P 프로토콜, 서비스 라이프사이클 등록

### 트랜잭션 풀 초기화

트랜잭션 풀은 두 개의 하위 풀로 구성됩니다:

* **legacypool**: 표준 트랜잭션 및 StableNet 전용 트랜잭션 처리
* **blobpool**: EIP-4844 blob 트랜잭션 처리

Anzeon 네트워크에서는 최소 가스 팁이 GovValidator 컨트랙트에서 초기화되어 마이너와 트랜잭션 풀에 반영됩니다.

### 마이너 및 합의 통합

Worker는 다음 네 가지 주요 goroutine을 실행합니다:

* **mainLoop**: 작업 요청 및 트랜잭션 이벤트 처리
* **newWorkLoop**: 새 블록 생성 트리거 (WBFT: 합의 라운드 이벤트 기반)
* **taskLoop**: 봉인 작업 관리 (`engine.Seal()` 호출)
* **resultLoop**: 봉인된 블록 처리 및 체인 삽입

## 서비스 등록 및 라이프사이클 관리

### API 등록

백엔드는 다음 RPC API 네임스페이스를 노출합니다:

* `eth`: 핵심 Ethereum RPC 메서드
* `miner`: 블록 생성 제어
* `admin`: 노드 및 피어 관리 기능
* `debug`: 트레이싱 및 진단 유틸리티
* `net`: 네트워크 정보
* 합의 엔진 전용 API (WBFT 관리 함수 등)

### 프로토콜 등록

P2P 프로토콜은 피어 간 통신을 담당합니다:

* **eth**: 블록 및 트랜잭션 전파
* **snap**: 상태 스냅샷 동기화 (활성화된 경우)
* **wbft**: WBFT 합의 메시지 교환

## 노드 시작 및 런타임

`StartNode()`가 호출되면 `stack.Start()`를 통해 서비스가 등록 순서대로 시작되며, 이후 런타임 모니터링이 활성화됩니다.

### 디스크 공간 모니터링

노드는 디스크 공간 부족으로 인한 데이터 손상을 방지하기 위해 주기적인 모니터링을 수행합니다.

* `--datadir.minfreedisk`가 설정된 경우 해당 임계값을 사용합니다
* 설정되지 않은 경우 내부 기본 임계값을 사용합니다
* 값이 0이면 모니터링이 비활성화됩니다

## 정상 종료 시퀀스

종료 신호를 수신하거나 디스크 공간 부족이 감지되면 노드는 순차적으로 종료를 수행합니다.

**종료 특성:**

* 서비스는 시작 순서의 역순으로 정상 종료됩니다
* 반복 신호 수신 시 강제 종료가 가능합니다
* 종료 과정은 추적되며 로그로 기록됩니다
* 모든 대기 중인 상태 변경은 디스크에 플러시됩니다

### 종료 추적기

종료 추적기(`shutdowncheck`)는 비정상 종료를 감지합니다:

* 시작 시 종료 마커 기록
* 정상 종료 시 마커 제거
* 마커가 남아 있는 경우 이전 비정상 종료로 판단하여 경고 로그 출력

이를 통해 데이터베이스 손상 가능성을 조기에 인지할 수 있습니다.

## 합의별 초기화

### WBFT 합의 시작

Anzeon/WBFT 네트워크에서는 다음과 같은 추가 초기화가 수행됩니다:

1. **Etherbase 자동 설정**: 노드 키에서 파생된 주소로 강제 설정
2. **가스 팁 초기화**: GovValidator 컨트랙트에서 네트워크 전역 값 로드
3. **WBFT 엔진 기동**: 합의 라운드 콜백 등록과 함께 엔진 시작
4. **Worker WBFT 모드 활성화**: 합의 이벤트 기반 블록 생성 루프 사용

## 컴포넌트 요약

| 컴포넌트             | 초기화 함수                              | 주요 책임                     |
| ---------------- | ----------------------------------- | ------------------------- |
| Node             | `node.New()`                        | 서비스 조정, P2P 서버, RPC 엔드포인트 |
| Ethereum Backend | `eth.New()`                         | 전체 프로토콜 구현 및 컴포넌트 연결      |
| Blockchain       | `core.NewBlockChain()`              | 정식 체인 관리 및 검증             |
| Transaction Pool | `txpool.New()`                      | 대기 트랜잭션 관리                |
| Miner            | `miner.New()`                       | 블록 생성 조정                  |
| Worker           | `newWorker()`                       | 트랜잭션 선택 및 블록 조립           |
| Consensus Engine | `ethconfig.CreateConsensusEngine()` | 블록 검증 및 봉인                |
| Protocol Handler | `newHandler()`                      | 블록·트랜잭션 전파                |
| Downloader       | `downloader.New()`                  | 체인 동기화                    |
| P2P Server       | `p2p.Server`                        | 피어 연결 및 프로토콜 멀티플렉싱        |