> ## 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.

# 트랜잭션 풀

## 목적 및 범위

트랜잭션 풀은 노드에 제출되었지만 아직 블록에 포함되지 않은 **대기 중인 트랜잭션**을 관리합니다. 주요 역할은 다음과 같습니다.

1. **수락**: RPC 클라이언트 및 P2P 피어로부터 트랜잭션 수신
2. **검증**: 서명, nonce, 잔액, 가스 관련 규칙 검증
3. **보관**: 실행 가능성 상태에 따라 메모리에 트랜잭션 저장
4. **제공**: 블록 조립을 위해 마이너/워커에 트랜잭션 제공
5. **전파**: P2P 네트워크를 통한 트랜잭션 전파
6. **조회**: RPC API를 통한 풀 상태 노출

관련 문서:

* 트랜잭션 실행: [상태 전이](/ko/transaction-processing/6.2-state-transitions)
* 트랜잭션 데이터 구조: [트랜잭션 유형 및 인코딩](/ko/core-architecture/3.5-transaction-types-and-encoding)
* 블록 생성에서의 트랜잭션 소비: [블록 생성](/ko/consensus-and-block-production/4.2-block-production-and-mining)

## 아키텍처 개요

`txpool.TxPool`은 트랜잭션 관리의 중앙 조정자입니다.

```
RPC (eth_sendRawTransaction)  ──┐
                                 ├→ TxPool.Add() → 검증 → queued/pending 분류
P2P (NewPooledTransactionHashes) ┘                         │
                                                           ├→ NewTxsEvent 게시
                                                           ├→ P2P 전파
                                                           └→ Worker.Pending() → 블록 조립
```

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

* **legacypool**: 표준 트랜잭션 처리 (타입 0x00\~0x04, 0x16)
* **blobpool**: blob 트랜잭션 처리 (EIP-4844)

## 트랜잭션 제출 경로

트랜잭션은 다음 두 경로 중 하나로 풀에 유입됩니다.

### RPC 제출

`eth_sendRawTransaction` 또는 `eth_sendTransaction`을 통해 제출된 트랜잭션은 **로컬 트랜잭션**으로 분류됩니다.\
로컬 트랜잭션은 우선 처리되며, 풀 용량 초과 시 제거 정책에서 상대적으로 보호됩니다.

### P2P 제출

`eth` 프로토콜을 통해 피어로부터 수신된 트랜잭션은 **원격 트랜잭션**으로 분류됩니다.\
원격 트랜잭션은 보다 보수적인 검증 정책과 낮은 기본 우선순위가 적용됩니다.

## 트랜잭션 검증

`TxPool.Add()`를 통해 수락되는 모든 트랜잭션은 아래 검증 단계를 통과해야 합니다.

| 검증 항목       | 설명                                  |
| ----------- | ----------------------------------- |
| **서명**      | ECDSA 서명 검증 및 발신자 주소 복구             |
| **Nonce**   | 발신자의 현재 온체인 nonce와 비교               |
| **잔액**      | value + 최대 가스 비용을 충당할 수 있는 잔액 보유 여부 |
| **가스 한도**   | 블록 가스 한도 이하 및 내재적 가스 이상 여부          |
| **가스 가격/팁** | 풀의 최소 가스 요구사항 충족 여부                 |
| **트랜잭션 타입** | 타입별 필드 및 규칙 검증                      |
| **수수료 위임**  | 수수료 위임 트랜잭션의 경우 수수료 지불자 서명·잔액 검증    |

### 가스 가격 및 가스 팁 검증

EIP-1559 기반 트랜잭션(타입 0x02, 0x04, 0x16)의 유효 가스 팁은 다음과 같이 계산됩니다.

```
EffectiveGasTip = min(GasTipCap, GasFeeCap - BaseFee)
```

Anzeon 네트워크에서는 계정 유형에 따라 가스 팁 규칙이 달라집니다.

* **승인된 계정**: 트랜잭션에 명시된 `GasTipCap` 사용 가능
* **일반 계정**: 블록 헤더에 포함된 거버넌스 기준 `GasTip`을 반드시 충족해야 함

## 풀 내부 구조

### Pending 트랜잭션

* 발신자 nonce가 현재 온체인 nonce와 정확히 일치
* 즉시 실행 가능
* 다음 블록에 포함될 후보
* `Pending()` 호출을 통해 워커에 제공됨

### Queued 트랜잭션

* 발신자 nonce가 미래 값
* 선행 nonce 트랜잭션이 처리되어야 실행 가능
* 조건 충족 시 자동으로 pending으로 승격됨

## 용량 제한

트랜잭션 풀은 메모리 사용량을 제어하고 서비스 거부(DoS) 공격을 방지하기 위해 슬롯(slot) 기반 용량 제한을 사용합니다.
각 트랜잭션은 크기에 따라 하나 이상의 슬롯을 차지하며, 풀은 계정 단위 및 전체 단위 제한을 동시에 적용합니다.

| 제한 유형       | 파라미터           | 기본값    | 설명                                     |
| ----------- | -------------- | ------ | -------------------------------------- |
| 계정별 Pending | `AccountSlots` | 16     | 한 계정이 pending 상태로 동시에 보유할 수 있는 최대 슬롯 수 |
| 계정별 Queued  | `AccountQueue` | 64     | 한 계정이 queued 상태로 동시에 보유할 수 있는 최대 슬롯 수  |
| 전체 Pending  | `GlobalSlots`  | 5120   | 모든 계정의 pending 트랜잭션이 공유하는 전체 슬롯 한도     |
| 전체 Queued   | `GlobalQueue`  | 1024   | 모든 계정의 queued 트랜잭션이 공유하는 전체 슬롯 한도      |
| 최소 가스 가격    | `PriceLimit`   | 1 Gwei | 트랜잭션 풀이 수락하는 최소 유효 가스 가격               |
| 교체 가격 증가    | `PriceBump`    | 10%    | 동일 nonce 트랜잭션을 교체하기 위한 최소 가스 가격 인상 비율  |

PriceLimit의 기본값은 1 Gwei이지만, StableNet에서는 GovValidator 거버넌스에서 결정한 네트워크 전역 GasTip 값이 적용되어 해당 값이 기준으로 사용됩니다.

## 트랜잭션 제거 규칙

트랜잭션 풀의 용량이 한계에 도달하면, 풀은 우선순위가 가장 낮은 트랜잭션부터 제거하여 새로운 트랜잭션을 수용합니다.\
제거 대상은 **슬롯 기준 용량 초과 여부**와 **수수료 우선순위 정렬 결과**를 함께 고려하여 결정됩니다.

기본 원칙은 다음과 같습니다:

* **우선순위 기준 제거**\
  풀 내부에서 수수료 기준으로 정렬된 결과를 바탕으로, 가장 낮은 우선순위를 가진 트랜잭션부터 제거됩니다.

* **계정 단위 제한 우선 적용**\
  특정 계정이 계정별 슬롯 한도(`AccountSlots`, `AccountQueue`)를 초과한 경우, 해당 계정의 트랜잭션이 우선적으로 제거 대상이 됩니다.

* **전체 용량 초과 시 전역 제거**\
  전체 pending 또는 queued 슬롯 한도(`GlobalSlots`, `GlobalQueue`)를 초과하면, 모든 계정을 대상으로 가장 낮은 우선순위 트랜잭션이 제거됩니다.

* **로컬 트랜잭션 보호**\
  로컬에서 제출된 트랜잭션은 네트워크로부터 수신된 트랜잭션보다 제거 우선순위가 낮아, 가능한 한 보존됩니다.

이 제거 정책을 통해 트랜잭션 풀은 메모리 사용량을 안정적으로 유지하면서도, 수수료 및 실행 가능성이 높은 트랜잭션을 우선적으로 유지합니다.

## 트랜잭션 교체 규칙

동일한 발신자와 nonce를 가진 새 트랜잭션은 기존 트랜잭션보다 `PriceBump` 이상 높은 유효 가스 가격을 제시해야 교체할 수 있습니다.

`PriceBump`는 **퍼센트(%) 단위의 상대적 증가율**로 적용되며, 예를 들어 `PriceBump = 10%`인 경우 새 트랜잭션의 유효 가스 가격은 기존 트랜잭션 대비 최소 10% 이상 높아야 합니다.

이를 통해 사용자는 가스 조건을 상향 조정하여 처리 지연을 해소할 수 있습니다.

## 트랜잭션 조회 API

### txpool RPC 네임스페이스

* `txpool_content`: pending / queued 트랜잭션 전체 조회
* `txpool_contentFrom(address)`: 특정 주소 기준 조회
* `txpool_status`: pending / queued 개수 조회
* `txpool_inspect`: 사람이 읽기 쉬운 요약 정보 제공

### 백엔드 접근 메서드

`EthAPIBackend`를 통해 내부적으로 다음 기능이 제공됩니다.

* `SendTx(tx)`
* `GetPoolTransaction(hash)`
* `GetPoolTransactions()`
* `GetPoolNonce(addr)`
* `Stats()`

## 이벤트 시스템

트랜잭션이 풀에 수락되면 `NewTxsEvent`가 게시됩니다.

주요 구독자:

* **Worker**: 현재 블록 후보에 트랜잭션 반영
* **P2P 핸들러**: 다른 피어로 전파
* **RPC 구독자**: pending 트랜잭션 알림 제공

이벤트는 `SubscribeNewTxsEvent()`를 통해 구독됩니다.

## 블록 생성과의 연동

블록 조립 시 워커는 `TxPool.Pending()`을 호출하여 실행 가능한 트랜잭션을 가져옵니다.\
반환 구조는 `주소 → nonce 순서 트랜잭션 목록` 형태입니다.

### 정렬 우선순위

1. 유효 가스 팁
2. 계정 내 nonce 순서
3. 실행 가능 여부
4. Anzeon 승인 계정 여부

## P2P 네트워크 연동

### 전파 흐름

로컬 풀에 추가된 트랜잭션은 해시 단위로 피어에 전파되며, 필요 시 전체 트랜잭션이 요청됩니다.

### 수신 흐름

1. 피어가 트랜잭션 해시 알림
2. 미보유 해시 선별
3. 전체 트랜잭션 요청
4. 검증 후 풀에 추가
5. 수락 시 재전파

## 블록 수신 시 풀 갱신

새 블록이 체인에 삽입되면 트랜잭션 풀은 다음을 수행합니다.

1. 블록에 포함된 트랜잭션 제거
2. 발신자 nonce 업데이트
3. queued 트랜잭션 승격
4. 잔액 기반 재검증
5. 더 이상 유효하지 않은 트랜잭션 제거

Anzeon 네트워크에서는 이 과정에서 GovValidator 컨트랙트를 조회하여 최신 가스 팁 정책을 풀과 워커에 동기화합니다.