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

# RPC 및 API

## 목적 및 범위

이 문서는 go-stablenet의 RPC(Remote Procedure Call) 서버 아키텍처 및 API 레이어를 설명합니다. RPC 엔드포인트 구성, 사용 가능한 API 네임스페이스, 백엔드 추상화 레이어, 이벤트 필터링 및 구독, 트랜잭션 제출 메커니즘을 다룹니다. RPC 레이어는 HTTP, WebSocket 또는 IPC 전송을 통해 JSON-RPC로 블록체인 노드와 상호 작용하기 위한 외부 인터페이스를 제공합니다.

P2P 네트워킹 및 프로토콜 핸들러에 대한 정보는 [Networking](/ko/networking)을 참조하세요. 노드 초기화 및 라이프사이클 관리에 대한 자세한 내용은 [Node Initialization and Lifecycle](/ko/core-architecture/3.1-node-initialization-and-lifecycle)을 참조하세요.

## RPC 서버 구성

노드는 세 가지 RPC 전송 메커니즘을 지원합니다: HTTP, WebSocket(WS), 프로세스 간 통신(IPC). 각 전송은 명령줄 플래그 또는 구성 파일을 통해 독립적으로 활성화되고 구성될 수 있습니다.

### 전송 구성

| Transport | Enable Flag          | Address Flag  | Port Flag     | Default Port  |
| --------- | -------------------- | ------------- | ------------- | ------------- |
| HTTP      | `--http`             | `--http.addr` | `--http.port` | 8545          |
| WebSocket | `--ws`               | `--ws.addr`   | `--ws.port`   | 8546          |
| IPC       | (enabled by default) | `--ipcpath`   | N/A           | `gstable.ipc` |

**주요 구성 플래그:**

* `--http.api`: HTTP를 통해 노출할 API 네임스페이스의 쉼표로 구분된 목록(예: "eth,net,web3")
* `--ws.api`: WebSocket 인터페이스용 API 네임스페이스
* `--http.corsdomain`: HTTP 요청용 CORS 도메인
* `--ws.origins`: WebSocket 연결용 Origins
* `--http.vhosts`: HTTP 서버가 허용하는 가상 호스트명
* `--ipcdisable`: IPC-RPC 서버 비활성화

**보안 및 제한:**

* `--rpc.gascap`: `eth_call` 및 `eth_estimateGas`용 가스 캡(기본값: 50,000,000)
* `--rpc.evmtimeout`: `eth_call` 실행 타임아웃(기본값: 5초)
* `--rpc.txfeecap`: 이더 단위의 트랜잭션 수수료 캡(기본값: 0, 캡 없음)
* `--rpc.batch-request-limit`: 배치의 최대 요청 수
* `--rpc.batch-response-max-size`: 배치 응답의 최대 바이트 수
* `--allow-insecure-unlock`: HTTP를 통한 계정 잠금 해제 허용(보안상 기본적으로 비활성화됨)

## RPC 서버 초기화 흐름

RPC 서버는 노드 초기화 과정에서 전송 설정 파싱, API 네임스페이스 결정, Backend 인스턴스 생성, RPC 서버 초기화, 전송별 리스너 바인딩, API 등록 순서로 구성됩니다.

## 핵심 API 네임스페이스

### eth 네임스페이스

eth 네임스페이스는 블록체인 상태 조회, 트랜잭션 제출, 가스 추정을 위한 기본 인터페이스를 제공합니다.

| Method                     | Description       |
| -------------------------- | ----------------- |
| `eth_chainId`              | 체인 ID 반환          |
| `eth_blockNumber`          | 현재 블록 번호          |
| `eth_getBalance`           | 계정 잔액 조회          |
| `eth_getStorageAt`         | 저장소 슬롯 값 조회       |
| `eth_getCode`              | 컨트랙트 코드 조회        |
| `eth_getTransactionCount`  | 계정 nonce 조회       |
| `eth_call`                 | 상태 변경 없는 EVM 실행   |
| `eth_estimateGas`          | 트랜잭션 가스 추정        |
| `eth_sendRawTransaction`   | 서명된 트랜잭션 제출       |
| `eth_gasPrice`             | 레거시 가스 가격 제안      |
| `eth_maxPriorityFeePerGas` | EIP-1559 우선순위 수수료 |
| `eth_feeHistory`           | 수수료 히스토리          |

### txpool 네임스페이스

txpool 네임스페이스는 트랜잭션 풀 내부 상태를 조회하기 위한 진단 API를 제공합니다.

### admin 네임스페이스

admin 네임스페이스는 피어 관리 및 RPC 서버 제어를 포함한 노드 관리 기능을 제공합니다. 이 네임스페이스는 공용 RPC 엔드포인트에 노출해서는 안 됩니다.

### debug 네임스페이스

debug 네임스페이스는 트랜잭션 추적, 상태 덤프, 체인 되감기, 데이터베이스 진단 등 고급 디버깅 기능을 제공합니다.

### personal 네임스페이스

personal 네임스페이스는 로컬 계정 기반 서명 기능을 제공하며 보안상의 이유로 기본적으로 비활성화되어 있습니다.

### miner 네임스페이스

miner 네임스페이스는 블록 생성, 봉인 제어, 가스 정책 설정 기능을 제공합니다.

### net 네임스페이스

net 네임스페이스는 네트워크 ID, 피어 연결 상태 등 기본적인 네트워크 정보를 제공합니다.

### web3 네임스페이스

web3 네임스페이스는 클라이언트 버전(`web3_clientVersion`), SHA3 해시(`web3_sha3`) 등 보조 유틸리티 API를 제공합니다.

### istanbul 네임스페이스

istanbul 네임스페이스는 Anzeon/WBFT 합의 엔진이 노출하는 RPC로, 검증자·블록 서명자·라운드 통계 등 합의 관련 조회를 제공합니다.

## 이벤트 시스템 및 필터링

RPC 필터 시스템은 새 블록, 로그, 대기 중인 트랜잭션 이벤트를 폴링 기반 필터 또는 WebSocket 구독 방식으로 제공합니다.

### 로그 필터 기준 구조

```go theme={null}
type FilterCriteria struct {
    BlockHash *common.Hash
    FromBlock *big.Int
    ToBlock   *big.Int
    Addresses []common.Address
    Topics    [][]common.Hash
}
```

## 요약

go-stablenet의 RPC 및 API 레이어는 다중 전송 방식, 포괄적인 네임스페이스 구성, 효율적인 이벤트 시스템, 유연한 트랜잭션 제출 메커니즘, 강력한 보안 제어를 제공하며 표준 Ethereum JSON-RPC와의 호환성을 유지하면서 StableNet 고유의 기능을 통합합니다.