> ## 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 노드가 블록을 생성하고 마이닝하는 전체 흐름을 설명합니다.\
워커(worker)의 역할, 블록 후보 조립 과정, 트랜잭션 선택 및 실행, 그리고 생성된 블록을 합의 엔진(WBFT)에 제출하여 최종화하는 과정을 다룹니다.\
WBFT 합의 프로토콜 자체의 투표, BLS 서명 집계, 에포크 관리에 대한 세부사항은 [Anzeon WBFT 합의 프로토콜](/ko/consensus-and-block-production/4.1-anzeon-wbft-consensus-protocol)을 참조하세요.

## 워커 아키텍처

`worker`는 StableNet에서 블록 생성을 담당하는 핵심 컴포넌트입니다.\
트랜잭션 풀에서 트랜잭션을 선택하고 실행한 뒤 블록을 조립하며, 완성된 블록 후보를 합의 엔진에 전달하여 봉인을 요청합니다.

### 워커 구조

워커는 블록 생산의 각 단계를 병렬로 처리하기 위해 여러 고루틴을 유지합니다.

| Component     | Goroutine | Purpose                       |
| ------------- | --------- | ----------------------------- |
| `mainLoop`    | Yes       | 작업 요청과 이벤트를 처리하고 블록 조립을 조정    |
| `newWorkLoop` | Yes       | 체인 이벤트 또는 합의 신호에 따라 블록 생성 트리거 |
| `taskLoop`    | Yes       | 조립된 블록을 합의 엔진에 제출             |
| `resultLoop`  | Yes       | 봉인된 블록을 수신하여 체인에 기록           |

**주요 필드**

* `current *environment` : 현재 조립 중인 블록의 실행 환경
* `coinbase common.Address` : 블록 생성자 주소(검증자 주소)
* `tip *uint256.Int` : 트랜잭션 포함을 위한 최소 가스 팁
* `pendingTasks map[common.Hash]*task` : 봉인을 기다리는 블록 작업
* `txsCh`, `chainHeadCh`, `readyToCommitCh` : 트랜잭션, 체인 헤드, 합의 신호 채널

### 워커 초기화

Anzeon 모드가 활성화되면 워커는 시작 시 GovValidator 컨트랙트에서 네트워크 전역 가스 팁을 읽어 초기화합니다.\
이후 새 블록이 체인에 추가될 때마다 콜백을 통해 최신 가스 팁을 다시 읽고 내부 상태와 트랜잭션 풀 필터 기준을 갱신합니다.

## 블록 생성 흐름

### WBFT vs Origin Work Loop

StableNet은 합의 엔진이 WBFT인지 여부에 따라 블록 생성 전략이 달라집니다.

* **Origin(Ethereum 기본)**: 타이머 기반으로 주기적으로 새 블록을 시도합니다
* **WBFT**: 합의 엔진이 `readyToCommitCh` 신호를 보낼 때만 블록 생성을 시작합니다

WBFT 모드에서는 이 노드가 제안자(proposer)로 선택된 정확한 시점에만 블록을 생성하므로, 불필요한 재조립이 발생하지 않습니다.

### WBFT Ready-to-Commit 메커니즘

WBFT 엔진은 `readyToCommit(round)` 콜백을 통해 워커에 블록 생성을 요청합니다.\
`round` 값은 현재 합의 라운드를 나타내며, `round = 0`은 최초 시도, `round > 0`은 이전 시도가 실패한 후 재시도임을 의미합니다.

## 블록 조립 프로세스

### Main Loop 및 Commit Work

`mainLoop()`는 합의 신호 또는 체인 이벤트를 수신한 뒤 실제 블록 조립을 담당하는 `commitWork()`를 호출합니다.\
이 함수는 블록 헤더 생성, 실행 환경 구성, 트랜잭션 실행을 순차적으로 수행합니다.

### prepareWork – 블록 헤더 설정

`prepareWork()`는 새 블록의 헤더와 실행 환경을 준비합니다.

**단계**

1. **부모 블록 결정**: 현재 체인의 최신 헤드 또는 지정된 부모 블록 선택
2. **타임스탬프 검증**: 부모 블록 이후 시간이 되도록 보정
3. **헤더 생성**: `makeHeader()`를 호출하여 기본 헤더 필드 초기화
4. **환경 준비**: `makeEnv()`를 통해 상태 스냅샷과 가스 풀 생성
5. **엔진 준비**: `engine.Prepare()`를 호출하여 합의별 필드 설정(WBFT의 경우 proposer/coinbase 정보 반영)

### 트랜잭션 선택 및 실행

`fillTransactions()`는 트랜잭션 풀에서 현재 블록에 포함 가능한 트랜잭션을 선택합니다.\
선택 기준은 가스 팁, nonce 순서, 계정별 유효성 검사 결과를 종합하여 결정됩니다.

### commitTransactions – 실행 루프

`commitTransactions()`는 선택된 트랜잭션을 순서대로 실행합니다.

* `ErrNonceTooLow` 발생 시 해당 트랜잭션만 건너뛰고 동일 계정의 다음 nonce 트랜잭션을 시도
* 실행 성공 시 영수증을 기록하고 다음 트랜잭션으로 진행
* 치명적인 오류 발생 시 해당 계정의 이후 트랜잭션을 모두 제외

### applyTransaction – 상태 전환

각 트랜잭션은 `applyTransaction()`을 통해 상태에 반영됩니다.

1. 실행 전 상태 스냅샷 생성
2. `core.ApplyTransaction()`을 통해 EVM 실행 및 상태 변경
3. 실패 시 스냅샷으로 되돌림
4. 성공 시 트랜잭션과 영수증을 블록에 추가

실제 nonce 검증, 잔액 검사, 가스 계산, EVM 호출은 모두 `core.ApplyTransaction()` 내부에서 처리됩니다.

### 블록 최종화

모든 트랜잭션 실행이 완료되면 블록은 최종화 단계로 이동합니다.\
WBFT 환경에서는 블록 보상이 없으므로 `Finalize()` 단계는 상태 루트 및 영수증 루트 계산 위주로 최소한의 작업만 수행합니다.

## 봉인 및 결과 처리

### 작업 제출 루프

`taskLoop()`는 완성된 블록을 합의 엔진에 제출합니다.

* **WBFT**: 블록이 합의 엔진으로 전달되어 PREPARE/COMMIT 투표가 시작됨
* **기타 엔진**: 해당 합의 방식에 맞는 봉인 로직 수행

결과는 `resultCh`를 통해 워커로 전달됩니다.

### 결과 처리 루프

`resultLoop()`는 봉인된 블록을 수신하여 체인에 기록합니다.

* 영수증에 블록 해시, 블록 번호, 트랜잭션 인덱스 설정
* 블록과 상태 루트를 데이터베이스에 영구 저장
* Anzeon 모드에서는 블록 기록 후 GovValidator에서 최신 가스 팁을 다시 조회하여 내부 상태를 갱신

## 트랜잭션 필터링 및 가스 팁

### Anzeon의 가스 팁 처리

Anzeon 네트워크에서는 가스 팁이 검증자 개별 설정이 아니라 거버넌스(GovValidator)에 의해 전역적으로 관리됩니다.\
`updateGasTipFromContract()`는 컨트랙트 상태를 읽어 워커와 트랜잭션 풀의 최소 가스 팁 기준을 동시에 갱신합니다.

이를 통해 다음이 보장됩니다.

1. 충분한 가스 팁을 지불하는 트랜잭션만 블록 후보에 포함
2. 가스 팁 변경 사항이 다음 블록부터 즉시 반영
3. 트랜잭션 풀이 기준 미달 트랜잭션을 사전에 필터링

### 트랜잭션 우선순위 지정

트랜잭션은 `transactionsByPriceAndNonce` 구조를 통해 정렬됩니다.

**우선순위 규칙**

1. **로컬 트랜잭션 우선**
2. **유효 가스 가격 기준**: `min(gasTipCap + baseFee, gasFeeCap)`
3. **Nonce 순서 보장**: 계정 내 순차 처리
4. **계정 간 가격 비교**: 높은 유효 가스 가격 우선

Blob 트랜잭션과 일반 트랜잭션은 내부적으로 분리 관리되지만, 최종 선택은 동일한 가격 기준을 따릅니다.

## 환경 및 상태 관리

### 실행 환경

`environment` 구조체는 블록 조립 중 필요한 모든 실행 상태를 보유합니다.

| Field                       | Purpose     |
| --------------------------- | ----------- |
| `signer types.Signer`       | 트랜잭션 서명 검증  |
| `state *state.StateDB`      | 상태 트리       |
| `tcount int`                | 블록 내 트랜잭션 수 |
| `gasPool *core.GasPool`     | 남은 가스 한도    |
| `header *types.Header`      | 생성 중인 블록 헤더 |
| `txs []*types.Transaction`  | 포함된 트랜잭션    |
| `receipts []*types.Receipt` | 실행 영수증      |

환경은 `makeEnv()`에서 생성되며, 부모 블록 상태를 기반으로 한 상태 복사본과 가스 풀을 준비합니다.

### 상태 변경 및 커밋

상태 변경은 다음 순서로 관리됩니다.

1. 트랜잭션 실행을 통해 StateDB 수정
2. 필요 시 스냅샷을 이용한 롤백
3. 블록 봉인 성공 시 상태를 trie에 커밋
4. 블록과 상태 루트를 데이터베이스에 기록

`updateSnapshot()`은 `eth_getBlockByNumber("pending")`과 같은 RPC 호출을 지원하기 위해 대기 중인 블록 상태를 유지합니다.

## 마이너 래퍼와의 통합

`Miner` 타입은 `worker`를 감싸며 노드 동기화 상태에 따라 블록 생성을 제어합니다.\
체인 동기화 중에는 블록 생성을 중지하고, 동기화 완료 후 자동으로 재개합니다.

## 요약 흐름

블록 생성 과정은 다음과 같이 요약됩니다.

1. 합의 엔진 또는 체인 이벤트가 블록 생성 트리거
2. 워커가 블록 헤더와 실행 환경 준비
3. 트랜잭션 선택 및 실행
4. 블록 최종화 및 합의 엔진에 제출
5. 봉인 완료 후 체인에 기록 및 가스 팁 동기화

이 구조를 통해 StableNet은 WBFT 합의와 긴밀히 결합된 안정적인 블록 생성 파이프라인을 유지합니다.