목적 및 범위
이 문서는 StableNet의 JSON-RPC API 아키텍처를 설명하며, 사용 가능한 API 네임스페이스, 서비스 구현, API 서비스를 핵심 블록체인 구성 요소에 연결하는 백엔드 추상화 레이어를 포함합니다.API 시스템은 HTTP, WebSocket, IPC 전송을 통해 노드 기능에 대한 외부 액세스를 제공합니다. 이벤트 필터링 및 구독에 대한 정보는 이벤트 필터링 및 구독을 참조하세요.
API 아키텍처 개요
StableNet RPC API는 API 서비스 구현이Backend 인터페이스에 의존하는 계층화된 아키텍처를 따르며, Ethereum 백엔드와의 긴밀한 결합 없이 핵심 블록체인 기능에 액세스할 수 있도록 설계되었습니다.
API 네임스페이스 구성
StableNet은 API를 여러 네임스페이스로 구성하며, 각각 명확한 책임과 목적을 가집니다.네임스페이스는
internal/ethapi.GetAPIs, eth.Ethereum.APIs(), 노드 레벨 apis(), 그리고 합의 엔진(WBFT)의 APIs()를 통해 등록되고 RPC 핸들러를 통해 외부로 노출됩니다.
API 네임스페이스 매핑
| Namespace | Service Implementation | Purpose |
|---|---|---|
eth | EthereumAPI, BlockChainAPI, TransactionAPI, EthereumAccountAPI, DownloaderAPI | 핵심 프로토콜·블록·트랜잭션·동기화 |
txpool | TxPoolAPI | 트랜잭션 풀 조회 |
personal | PersonalAccountAPI | 비밀번호 기반 계정 관리 및 수수료 위임 서명 |
debug | DebugAPI (ethapi·eth·node) | 디버깅 및 진단 |
admin | AdminAPI (node·eth) | 노드 및 피어 관리 |
miner | MinerAPI | 블록 생성 제어 |
net | NetAPI | 네트워크 정보 |
web3 | web3API | Web3 유틸리티 |
istanbul | WBFT API | WBFT 합의 검증자·서명자·상태 통계 |
eth 네임스페이스
eth 네임스페이스는 핵심 Ethereum 프로토콜 기능을 제공하며 여러 API 서비스 클래스로 구성됩니다.
EthereumAPI 서비스
EthereumAPI는 네트워크 상태 및 수수료 관련 쿼리를 담당합니다.
| Method | Description |
|---|---|
GasPrice() | 레거시 트랜잭션용 가스 가격 반환 |
MaxPriorityFeePerGas() | EIP-1559 트랜잭션용 우선순위 수수료 반환 |
FeeHistory() | 과거 수수료 히스토리 반환 |
Syncing() | 노드 동기화 상태 반환 |
MaxPriorityFeePerGas가 가스 가격 오라클을 사용하지 않고 GovValidator 컨트랙트에 의해 강제된 가스 팁 값을 반환합니다.
BlockChainAPI 서비스
BlockChainAPI는 블록체인 상태 및 데이터를 조회하기 위한 인터페이스를 제공합니다.
| Method | Description | RPC Method |
|---|---|---|
ChainId() | 체인 ID 반환 | eth_chainId |
BlockNumber() | 현재 블록 번호 반환 | eth_blockNumber |
GetBalance() | 계정 잔액 조회 | eth_getBalance |
GetCode() | 컨트랙트 코드 조회 | eth_getCode |
GetStorageAt() | 스토리지 슬롯 조회 | eth_getStorageAt |
GetProof() | Merkle Proof 반환 | eth_getProof |
GetBlockByNumber() | 블록 번호 기준 조회 | eth_getBlockByNumber |
GetBlockByHash() | 블록 해시 기준 조회 | eth_getBlockByHash |
GetTransactionByHash() | 트랜잭션 조회 | eth_getTransactionByHash |
GetTransactionReceipt() | 트랜잭션 영수증 조회 | eth_getTransactionReceipt |
TransactionAPI 서비스
TransactionAPI는 트랜잭션 생성, 서명, 제출을 담당합니다.
| Method | Description | RPC Method |
|---|---|---|
SendTransaction() | 트랜잭션 서명 및 제출 | eth_sendTransaction |
SendRawTransaction() | 서명된 트랜잭션 제출 | eth_sendRawTransaction |
SignTransaction() | 트랜잭션 서명만 수행 | eth_signTransaction |
FillTransaction() | 트랜잭션 기본 필드 보완 | eth_fillTransaction |
EstimateGas() | 가스 사용량 추정 | eth_estimateGas |
Call() | 상태 변경 없는 호출 실행 | eth_call |
txpool 네임스페이스
TxPoolAPI는 트랜잭션 풀 상태를 읽기 전용으로 제공합니다.
| Method | Description | RPC Method |
|---|---|---|
Content() | 풀 내 모든 트랜잭션 조회 | txpool_content |
ContentFrom() | 특정 주소 트랜잭션 조회 | txpool_contentFrom |
Status() | pending/queued 개수 반환 | txpool_status |
Inspect() | 사람이 읽을 수 있는 요약 | txpool_inspect |
- pending: 다음 블록에 포함 가능한 상태
- queued: nonce 불일치 또는 잔액 부족으로 대기 중
personal 네임스페이스
PersonalAccountAPI는 비밀번호 기반 계정 관리를 제공합니다.보안상 이유로 일반적으로 외부 RPC에서는 비활성화됩니다.
| Method | Description | RPC Method |
|---|---|---|
NewAccount() | 계정 생성 | personal_newAccount |
ListAccounts() | 계정 목록 | personal_listAccounts |
UnlockAccount() | 계정 잠금 해제 | personal_unlockAccount |
LockAccount() | 계정 잠금 | personal_lockAccount |
SendTransaction() | 비밀번호 기반 전송 | personal_sendTransaction |
SignTransaction() | 비밀번호 기반 서명 | personal_signTransaction |
Sign() | 임의 데이터 서명 | personal_sign |
ImportRawKey() | 개인키 임포트 | personal_importRawKey |
debug 네임스페이스
DebugAPI는 개발 및 운영 진단을 위한 고급 기능을 제공합니다.
주요 기능 범주
트랜잭션 및 블록 추적TraceTransaction()TraceBlock()TraceBlockByNumber()TraceBlockByHash()TraceCall()
DumpBlock()AccountRange()StorageRangeAt()
DbGet()DbAncient()ChaindbProperty()ChaindbCompact()
CpuProfile()BlockProfile()MemStats()GcStats()
web3 네임스페이스
web3API는 기본 Web3 유틸리티를 제공합니다.
| Method | Description | RPC Method |
|---|---|---|
ClientVersion() | 클라이언트 버전 반환 | web3_clientVersion |
Sha3() | Keccak-256 해시 계산 | web3_sha3 |
istanbul 네임스페이스
WBFT 합의 사용 시에만 노출됩니다.| Method | Description | RPC Method |
|---|---|---|
NodeAddress() | 서명 노드 주소 반환 | istanbul_nodeAddress |
GetCommitSignersFromBlock() | 제안자·커밋 서명자 조회 | istanbul_getCommitSignersFromBlock |
GetCommitSignersFromBlockByHash() | 해시 기준 조회 | istanbul_getCommitSignersFromBlockByHash |
GetValidators() | 검증자 목록 반환 | istanbul_getValidators |
GetValidatorsAtHash() | 해시 기준 검증자 | istanbul_getValidatorsAtHash |
Status() | 라운드·시일러 통계 | istanbul_status |
StableNet 수수료 위임 확장
수수료 위임 트랜잭션을 위해personal과 eth 네임스페이스에 다음 API를 확장 제공합니다.
| RPC Method | 설명 |
|---|---|
personal_signRawFeeDelegateTransaction | 수수료 지불자 비밀번호로 계정을 인증한 뒤, 발신자가 이미 서명한 트랜잭션에 수수료 지불자 서명을 붙여 RLP 바이트를 반환합니다. |
eth_signRawFeeDelegateTransaction | 이미 잠금 해제된 수수료 지불자 계정으로 위와 동일한 수수료 위임 서명을 수행합니다. |
eth_sendRawTransaction으로 제출하며, 가스 비용은 수수료 지불자가 부담합니다.
API 테스트 인프라
코드베이스는 다음 테스트 인프라를 포함합니다.- Mock Backend 기반 단위 테스트
- 제네시스 및 키 기반 통합 테스트
- RPC 직렬화 및 응답 검증 테스트