Tech Lab3 min read

블록체인 코스 #18: 노드와 JSON-RPC 통신 기초 완전 정리

노드와 클라이언트의 차이, JSON-RPC 핵심 필드, curl 실습으로 RPC 호출 흐름을 이해합니다. 개발환경 없이도 곧바로 따라 할 수 있게 구성했습니다.

#블록체인#json-rpc#web3#api#ethereum#rpc#kaia

이 글을 통해 노드와 클라이언트의 역할을 구분하고, 개발 도구 없이도 curl만으로 RPC 호출을 실습해 통신 구조를 체감할 수 있습니다.

노드(클라이언트)와 dApp, RPC 엔드포인트의 관계

노드와 클라이언트, 무엇이 다른가

  • 블록체인은 블록·트랜잭션을 검증·전파하는 노드들의 분산 네트워크입니다.
  • 사용자는 노드를 구동하는 응용프로그램인 클라이언트를 설치해 네트워크에 참여합니다. (예: Bitcoin Core, Geth)
  • 모든 개발자가 자신의 노드를 운영할 필요는 없습니다. 공개 RPC 엔드포인트를 통해 다른 노드에 질의하고 데이터를 받아올 수 있습니다.

주의: 자체 노드를 운영하면 신뢰 의존을 줄일 수 있지만, 디스크·대역폭·관리 비용이 늘어납니다.

RPC란 무엇이고 왜 쓰는가

  • RPC(Remote Procedure Call) 는 다른 프로세스(원격)의 함수를 로컬 호출처럼 부르는 통신 모델입니다.
  • 분산 시스템과 MSA(Microservices Architecture) 에서 널리 쓰이며, 언어·환경에 독립적으로 서비스 간 상호작용을 가능하게 합니다.
  • 블록체인 클라이언트는 RPC 인터페이스를 제공해, 계정 잔액 조회·트랜잭션 전송·블록 탐색 등을 표준화된 호출로 노출합니다.

팁: 동기화 상태가 불완전한 노드는 최신 데이터를 응답하지 못할 수 있습니다. 엔드포인트의 싱크 상태를 확인하세요.

JSON-RPC 핵심 구조 살펴보기

  • JSON-RPC는 무상태(Stateless)·경량 프로토콜로, 메시지는 JSON 형식입니다.
  • 전송은 HTTP(S)나 소켓 등 다양한 채널을 사용할 수 있도록 추상화되어 있습니다.
  • dApp 개발자는 보통 web3.js, ethers.js 같은 라이브러리를 통해 간접 호출하지만, 원리를 이해하면 네트워크 이슈를 진단하기 쉬워집니다.

요청/응답 필드 요약

필드타입설명
jsonrpcstring프로토콜 버전(일반적으로 "2.0")
methodstring호출할 RPC 메서드명(예: eth_getBalance)
paramsarray메서드 인자 목록(순서 중요)
idnumber/string요청 식별자(응답 매칭용)
resultany성공 시 결과 값(응답)
errorobject실패 시 코드/메시지/데이터

참고: 내부 링크 — 더 깊은 배경은 타임스탬프 역사를 확인하세요.

실습: 터미널에서 잔액 조회 보내보기

아래 명령을 그대로 붙여 실행하면, 카이아(Kairos 테스트넷) 공개 엔드포인트에 잔액 조회를 보냅니다.

curl -X POST https://public-en-kairos.node.kaia.io \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x7F4eCb81082eE10c330B926F64E34a9102de4F03", "latest"],
    "id": 1
  }'
  • method: "eth_getBalance" → 특정 주소 잔액 조회 메서드
  • params[0] → 조회할 계정(체인 주소)
  • params[1] → 조회 기준 블록(예: "latest", 또는 블록 해시/높이)
  • id → 응답 매칭용 식별자(임의 값 가능)
  • jsonrpc: "2.0" → 프로토콜 버전

응답의 "result"는 16진수(HEX) 문자열이며, 카이아에서는 Peb 단위(이더리움의 Wei와 유사)입니다. 예: 0x8ac7230489e80000 = 10 KAIA (Peb → KAIA 변환 필요)

스크린샷 2025 12 10 오후 8.28.27

숫자 변환 빠르게 이해하기

  1. result에서 0x를 떼고 16진수 → 10진수로 변환합니다.
  2. 단위를 확인합니다. (Peb 또는 Wei)
  3. 체인의 기본 단위(예: KAIA, ETH)로 나누어 표시합니다.
  4. UI 표시는 소수 자리수와 라운딩 정책을 명확히 합니다.

팁: "pending"으로 조회하면 채굴/제출 대기 중 트랜잭션의 잔액 변화를 추적할 수 있습니다. 다만 노드 구현마다 지원 범위가 다를 수 있습니다.

자주 겪는 오류와 해결 가이드

  • -32601 Method not found: 메서드 철자·프리픽스(eth_, klay_ 등) 확인. 노드가 해당 메서드를 비활성화했을 수 있습니다.
  • Invalid params: 주소 형식(0x 접두, 20바이트)·인자 순서 재확인. "latest"/"earliest"/"pending" 키워드 오탈자 점검.
  • Unsupported chain / CORS: 브라우저에서 직접 호출 시 CORS 정책에 막힐 수 있으니 백엔드 프록시를 사용합니다.
  • Rate limit / 429: 공개 엔드포인트는 호출 빈도 제한이 있습니다. 지수백오프와 캐싱을 적용하세요.
  • Desync / stale data: 응답 블록 번호가 너무 과거면 다른 엔드포인트로 재시도하고, eth_blockNumber로 최신도 확인.

경고: 개인 키 서명이 필요한 eth_sendRawTransaction 등은 반드시 안전한 서명 환경에서 처리하고, RPC 노드에 키를 저장하지 마세요.

라이브러리로 더 편하게 쓰기

  • 자바스크립트 생태계에는 web3.js, ethers.js 등 고수준 API가 풍부합니다.
  • 내부적으로는 동일한 JSON-RPC를 사용하므로, 원리 이해 + 라이브러리 활용이 가장 생산적입니다.
  • 프로덕션에서는 HTTP Keep-Alive, 지수백오프, 장애조치(Failover) 엔드포인트를 구성하게 됩니다.

참고 링크

다음으로 읽어볼 글