> ## 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의 핵심 블록체인 컴포넌트와 그 상호 작용 구조에 대한 개요를 제공합니다. 각 컴포넌트의 역할과 컴포넌트 간 관계를 중심으로 StableNet의 전체 아키텍처를 설명합니다.

특정 하위 시스템에 대한 상세 정보는 다음을 참조하세요:

* 노드 시작 및 서비스 등록: [노드 초기화 및 라이프사이클](/ko/core-architecture/3.1-node-initialization-and-lifecycle)
* 블록 삽입 및 체인 재구성: [블록체인 관리](/ko/core-architecture/3.2-blockchain-management)
* 상태 trie 및 계정 관리: [상태 관리](/ko/core-architecture/3.3-state-management)
* 트랜잭션 검증 및 대기열: [트랜잭션 풀](/ko/core-architecture/3.4-transaction-pool)
* 트랜잭션 데이터 구조: [트랜잭션 유형 및 인코딩](/ko/core-architecture/3.5-transaction-types-and-encoding)
* 블록 데이터 구조: [블록 구조 및 인코딩](/ko/core-architecture/3.6-block-structure-and-encoding)
* 합의 메커니즘: [합의 및 블록 생성](/ko/consensus-and-block-production/index)
* P2P 네트워킹: [네트워킹](/ko/networking/index)
* RPC 인터페이스: [RPC 및 API](/ko/rpc-and-apis/index)

## 아키텍처 개요

StableNet 노드는 계층형 아키텍처로 구성됩니다. 최상위에는 노드 컨테이너(`node.Node`)가 위치하며, 그 내부에서 Ethereum 프로토콜 구현체(`eth.Ethereum`)가 블록체인, 트랜잭션 풀, 합의 엔진 등 핵심 컴포넌트를 조정합니다.

```
  node.Node (서비스 컨테이너)                    
  ├─ P2P 서버, RPC/IPC/WS 서버, 계정 관리자       
  │                                          
  └─ eth.Ethereum (프로토콜 구현)               
     ├─ BlockChain   ← 정식 체인, 블록 삽입/검증  
     ├─ StateDB      ← 계정/스토리지 상태 관리    
     ├─ TxPool       ← 대기 트랜잭션 관리        
     ├─ Miner/Worker ← 블록 조립 및 봉인         
     ├─ Engine       ← 합의 (WBFT/Clique/Ethash)
     └─ Handler      ← P2P 동기화, 블록/TX 전파  
```

## 핵심 컴포넌트

### node.Node — 서비스 컨테이너

모든 서비스의 라이프사이클을 관리하는 최상위 컨테이너입니다. P2P 서버, RPC/IPC/WebSocket 서버, 데이터베이스를 초기화하고 등록된 서비스를 순서대로 시작·종료합니다. 블록체인 로직은 포함하지 않으며, 노드 실행을 위한 인프라 계층을 제공합니다.

### eth.Ethereum — Ethereum 프로토콜 구현

핵심 블록체인 컴포넌트를 조정하는 메인 서비스입니다. 초기화 과정에서 데이터베이스, 블록체인, 트랜잭션 풀, 마이너/워커, 합의 엔진을 생성하고 연결합니다. 또한 RPC API와 P2P 프로토콜을 노드에 등록하여 외부와의 상호 작용을 가능하게 합니다.

### BlockChain — 정식 체인 관리

정식(canonical) 체인을 관리하는 핵심 컴포넌트입니다. 블록 검증, 삽입, 상태 실행, 체인 재구성(reorg)을 조정합니다. 합의 엔진을 통해 블록의 유효성을 검증하고, StateDB를 통해 계정 및 스토리지 상태를 관리합니다. 자주 접근되는 블록과 영수증은 LRU 캐시를 활용해 조회 성능을 최적화합니다. 상세 내용은 [블록체인 관리](/ko/core-architecture/3.2-blockchain-management)를 참조하세요.

### StateDB — 상태 관리

Merkle Patricia Trie 위에 캐싱 레이어를 제공하여 계정 잔액, nonce, 컨트랙트 코드, 스토리지를 관리합니다. 트랜잭션 실행 중 상태 변경을 저널링하여 실패 시 롤백을 지원하고, 스냅샷을 통해 빠른 상태 조회를 제공합니다. 상세 내용은 [상태 관리](/ko/core-architecture/3.3-state-management)를 참조하세요.

### TxPool — 트랜잭션 풀

블록에 아직 포함되지 않은 대기 트랜잭션을 관리합니다. RPC와 P2P를 통해 트랜잭션을 수신한 후 서명, nonce, 잔액, 가스 조건을 검증하고 실행 가능한 트랜잭션(pending)과 미래 트랜잭션(queued)으로 분류합니다. 표준 트랜잭션을 처리하는 `legacypool`과 blob 트랜잭션(EIP-4844)을 처리하는 `blobpool`로 구성됩니다. 상세 내용은 [트랜잭션 풀](/ko/core-architecture/3.4-transaction-pool)을 참조하세요.

### Miner/Worker — 블록 생성

블록 제안자가 대기 중인 트랜잭션을 블록에 포함하여 블록 후보를 생성하고, 합의 엔진을 통해 검증자 간 합의를 거쳐 최종 블록으로 봉인(seal)합니다. Worker는 `mainLoop`, `newWorkLoop`, `taskLoop`, `resultLoop` 네 개의 goroutine을 통해 트랜잭션 선택, 블록 조립, 봉인 요청, 결과 처리를 병렬로 수행합니다.

### consensus.Engine — 합의 엔진

블록 검증과 봉인을 추상화하는 인터페이스입니다. StableNet에서는 Anzeon WBFT 합의 엔진이 사용되며, 블록 제안, 투표, 봉인 검증을 담당합니다.

## StableNet 특화 설계

StableNet은 go-ethereum을 기반으로 하지만, 스테이블코인 운영과 거버넌스 중심 합의를 위해 다음과 같은 확장이 적용되었습니다.

### Anzeon WBFT 합의

* **거버넌스 기반 검증자**: GovValidator 컨트랙트의 투표 결과에 따라 검증자 세트가 결정되며 스테이킹은 사용하지 않습니다.
* **블록 보상 없음**: 신규 발행에 의한 인플레이션이 없으며, 트랜잭션 수수료만 검증자에게 분배됩니다.
* **BLS 서명 집계**: PREPARE/COMMIT 단계의 합의 메시지에 BLS 집계 서명을 사용하여 검증 비용을 줄입니다.
* **에포크 기반 검증자 업데이트**: 검증자 세트 변경은 에포크 블록에서만 적용됩니다.

### 가스 수수료 정책

* **거버넌스 제어 가스 팁**: 최소 가스 팁(priority fee)은 GovValidator 컨트랙트에서 네트워크 전역 값으로 관리됩니다.
* **승인된 계정 예외**: 거버넌스가 승인한 계정은 개별 가스 팁 설정이 허용됩니다.
* **동적 가스 팁 반영**: 새 블록이 체인에 반영될 때마다 최신 가스 팁이 워커와 트랜잭션 풀에 동기화됩니다.

### 수수료 위임 (Fee Delegation)

StableNet 전용 트랜잭션 타입(0x16)을 통해 발신자와 별도의 수수료 지불자(FeePayer)를 분리할 수 있습니다. 이 경우 발신자와 수수료 지불자 모두의 ECDSA 서명이 필요합니다.

### Etherbase 자동 설정

Anzeon 네트워크에서는 etherbase가 노드의 운영 키(nodekey)에서 파생된 주소로 자동 설정되며, 사용자가 수동으로 지정할 수 없습니다.

## 초기화 흐름 요약

StableNet 노드는 다음 순서로 초기화됩니다.

1. **CLI 플래그 파싱** — 네트워크 설정, 데이터 디렉터리, TOML 설정 로드
2. **노드 생성** — `node.Node`가 P2P, RPC, 데이터베이스 인프라를 준비
3. **데이터베이스 열기** — chaindata 및 ancient(freezer) 저장소 초기화
4. **합의 엔진 생성** — 체인 설정에 따라 WBFT/Clique/Ethash 선택
5. **블록체인 초기화** — 제네시스 로드, BlockChain 생성, 스냅샷 구성
6. **트랜잭션 풀 설정** — legacypool과 blobpool 생성
7. **마이너/워커 생성** — 블록 조립 관련 goroutine 시작
8. **API 및 프로토콜 등록** — RPC 핸들러와 P2P 프로토콜 등록
9. **서비스 시작** — 등록된 서비스 순서대로 기동

상세한 초기화 과정은 [노드 초기화 및 라이프사이클](/ko/core-architecture/3.1-node-initialization-and-lifecycle)을 참조하세요.

## 데이터 흐름 개요

### 트랜잭션 처리 흐름

```
사용자/DApp → RPC (eth_sendRawTransaction)
           → TxPool.Add() — 서명·nonce·잔액·가스 검증
           → pending 트랜잭션으로 분류
           → P2P 네트워크로 전파
           → Miner가 Pending() 호출 → 블록 조립
           → consensus.Engine.Seal() → 블록 봉인
           → BlockChain.InsertChain() → 체인 삽입
           → 상태 커밋 및 이벤트 게시
```

### 블록 동기화 흐름

```
피어 노드 → P2P 프로토콜
          → Handler가 블록 수신
          → BlockChain.InsertChain() — 헤더·본문·상태 검증
          → 필요 시 체인 재구성(reorg)
          → TxPool에 새 헤드 알림 → 풀 상태 업데이트
```

## 데이터베이스 구조

저장소 레이어는 다음과 같은 계층 구조로 구성됩니다.

* **ChainDB**: LevelDB 또는 Pebble 기반의 영구 저장소로 블록, 영수증, 정식 매핑을 저장합니다.
* **Ancient Store (Freezer)**: 오래된 블록 데이터를 append-only 저장소로 분리하여 ChainDB 크기를 관리합니다.
* **TrieDB**: Merkle Patricia Trie 노드를 관리하며 해시 기반과 경로 기반 스키마를 지원합니다.
* **Snapshot**: 평탄화된 키-값 구조로 상태를 저장하여 빠른 조회를 제공합니다.

상세 내용은 [저장소 아키텍처](/ko/storage-architecture/index)를 참조하세요.

## 체인 구성

체인별 매개변수는 `params.ChainConfig`에 정의되며 포크 활성화 시점, 합의 규칙, 네트워크별 설정을 제어합니다.

| 항목        | 설명                         |
| --------- | -------------------------- |
| `ChainID` | 체인 고유 식별자                  |
| 포크 활성화 블록 | EIP별 활성화 블록 높이             |
| `Anzeon`  | WBFT 합의 매개변수 및 시스템 컨트랙트 설정 |

Anzeon 구성에는 블록 간격(`BlockPeriod`), 에포크 크기(`Epoch`), 요청 타임아웃(`RequestTimeout`) 등 합의 매개변수와 시스템 컨트랙트 초기화 정보가 포함됩니다.