Overview

EVM 기반의 블록체인은 JSON-RPC 형식을 이용해 클라이언트와 블록체인 네트워크 간 통신을 합니다. Luniverse에서 제공하는 노드를 이용해 JSON-RPC를 호출할 수 있습니다. Luniverse에서 지원하는 JSON-RPC API에 대한 설명은 다음과 같습니다.


Account

계정에 대한 정보를 조회할 수 있는 JSON-RPC API 입니다.

  • eth_getBalance

    • 특정 계정 주소가 소유한 Native Token 자산 잔고를 조회할 수 있습니다.
  • eth_getCode

    • 입력한 컨트랙트 주소의 코드를 반환합니다.
  • eth_getStorageAt

    • 입력한 주소에 할당된 Storage slot을 조회할 수 있습니다.

Block

블록의 데이터를 조회할 수 있는 JSON-RPC API 입니다.

  • eth_blockNumber

    • 가장 최신 블록의 번호를 반환합니다.
  • eth_getBlockByHash

    • 블록의 Hash 값으로 해당 블록의 정보를 조회합니다.
  • eth_getBlockByNumber

    • 블록의 Number 값으로 해당 블록의 정보를 조회합니다.
  • eth_getBlockTransactionCountByHash

    • 블록의 Hash 값으로 해당 블록에 포함된 트랜잭션의 수를 조회합니다.
  • eth_getBlockTransactionCountByNumber

    • 블록의 Number 값으로 해당 블록에 포함된 트랜잭션의 수를 조회합니다.
  • eth_getBlockReceipts

    • 블록의 해시값으로 해당 블록의 Receipt를 조회합니다.

Transaction

트랜잭션과 관련된 JSON-RPC API 입니다.

  • eth_getTransactionByHash

    • 트랜잭션의 해시값으로 해당 트랜잭션의 정보를 조회합니다.
  • eth_getTransactionByBlockHashAndIndex

    • 블록의 해시 값과 지정한 블록 내 트랜잭션의 index 값을 입력하여 해당 index에 해당하는 트랜잭션의 정보를 조회합니다.
  • eth_getTransactionByBlockNumberAndIndex

    • 블록의 Number 값과 지정한 블록 내 트랜잭션의 index 값을 입력하여 해당 index에 해당하는 트랜잭션의 정보를 조회합니다.
  • eth_getTransactionReceipt

    • 트랜잭션의 해시값으로 해당 트랜잭션의 Receipt를 조회합니다.
  • eth_getTransactionCount

    • 특정 주소로부터 발행된 트랜잭션 수를 반환합니다.
  • eth_call

    • 실제로 트랜잭션을 생성하여 발행하지 않고 컨트랙트의 읽기 method를 실행한 결과를 조회할 수 있습니다. 주로 특정 스마트 컨트랙트의 현재 상태를 읽기 위해 사용됩니다. call로 인한 상태 변경은 일어나지 않습니다.
  • eth_sendRawTransaction

    • 서명된 트랜잭션 데이터를 네트워크에 전송합니다. 트랜잭션이 정상적으로 처리되는 경우, 트랜잭션의 해시 값이 반환됩니다. 트랜잭션 서명은 개인키에 의해 client에서 이루어져야 합니다. 노드에서는 해당 트랜잭션의 유효성만 검증합니다.

Event

발생한 이벤트를 조회할 수 있는 JSON-RPC API 입니다.

  • eth_newFilter

    • 노드에서 지원하는 다양한 필터 옵션을 사용하여 필터를 생성할 수 있습니다. 생성된 필터 ID를 반환합니다.
  • eth_newBlockFilter

    • 신규 블록이 생성되면 알림을 받기 위한 필터를 생성합니다. 필터 ID를 반환합니다.
  • eth_newPendingTransactionFilter

    • 신규 Pending 트랜잭션이 발생하면 알림을 받기 위한 필터를 생성합니다. 필터 ID를 반환합니다.
  • eth_getFilterLogs

    • 필터 ID를 활용하여 해당 필터 조건에 맞는 Log를 조회할 수 있습니다.
  • eth_getFilterChanges

    • 필터 ID를 활용하여 해당 필터 조건에 부합하는 Log들을 지속적으로 Polling할 수 있습니다. 실행시 마지막 실행 이후 결과가 조회됩니다.
  • eth_uninstallFilter

    • 필터 ID로 생성한 필터를 삭제합니다.
  • eth_getLogs

    • 입력한 필터 조건에 부합하는 Log들을 조회합니다. 별도의 필터를 생성하여 필터 ID로 조회하지 않고, 요청에 바로 필터 조건을 입력하여 조회합니다.

Chain Information

체인, 혹은 클라이언트의 메타데이터에 대한 정보를 JSON-RPC API 입니다.

  • eth_chainId

    • 현재 연결된 chain ID를 반환합니다. 반환된 chain ID는 Replay 공격을 방지하기 위한 EIP-155 표준 반영에 따라 서명되는 트랜잭션에 포함되어야 합니다.
  • eth_protocolVersion

    • 현재 이더리움 프로토콜의 버전을 반환합니다.
  • net_listening

    • 클라이언트가 현재 요청을 받을 수 있는 상태인지 확인합니다. Health check용으로 사용할 수 있는 method입니다.
  • net_version

    • 현재 네트워크의 ID를 반환합니다.

Uncle

Uncle Block에 대한 데이터를 조회할 수 있는 JSON-RPC API 입니다.

  • eth_getUncleByBlockHashAndIndex
    • 블록의 해시 값으로 특정 Index에 해당하는 Uncle 블록 정보를 조회합니다.
  • eth_getUncleByBlockNumberAndIndex
    • 블록의 Number 값으로 특정 Index에 해당하는 Uncle 블록 정보를 조회합니다.
  • eth_getUncleCountByBlockHash
    • 블록의 해시 값으로 해당 블록의 Uncle 블록 수를 조회합니다.
  • eth_getUncleCountByBlockNumber
    • 블록의 Number 값으로 해당 블록의 Uncle 블록 수를 조회합니다.

Gas Estimation

Gas와 관련된 데이터를 조회할 수 있는 JSON RPC API 입니다.

  • eth_gasPrice

    • 현재 이더리움 네트워크의 Gas Price를 반환합니다. 반환된 Gas당 Price의 단위는 Wei입니다.
  • eth_maxPriorityFeePerGas

    • eth_maxPriorityFeePerGas는 Ethereum 거래의 우선순위 수수료의 최대값을 반환합니다. 반환된 값을 참고한 후 조정하여 거래의 우선순위를 제어할 수 있습니다.
  • eth_feeHistory

    • Ethereum 네트워크에서의 최근 블록들의 거래 수수료 정보를 반환합니다. 이전 블록의 거래 수수료 추세와 현재 수수료 수준을 파악할 수 있습니다.
  • eth_estimateGas

    • 트랜잭션 처리를 완료하기위해 필요한 Gas양을 측정합니다. 해당 트랜잭션은 가스 소모량 측정에만 사용되며 실제로 submit되지 않습니다.
  • eth_createAccessList

    • EIP2930 기반의 접근 목록(access list)을 생성합니다. Access List는 컨트랙트에 접근을 허용하는 주소와 변경 가능한 상태 변수 목록을 정의하여 가스 비용을 최적화하는 데 도움을 줍니다.

Web3 Utils

노드에 대한 정보와 블록체인을 이용할 때 유용한 기능을 제공하는 JSON-RPC API 입니다.

  • web3_clientVersion

    • 현재 노드의 client 버전 정보를 조회합니다.
  • web3_sha3

    • 입력한 data의 Keccak-256 해시값을 반환합니다.

Trace

트랜잭션의 실행 경로에 대해 조회할 수 있는 JSON-RPC API 입니다. 이를 이용하여 내부 함수 호출, 상태 변경 등을 확인 할 수 있습니다.

  • trace_call

    • 입력한 Call object에 대한 실행 시뮬레이션을 수행하면서 다양한 Trace 옵션별 세부 정보를 제공합니다. 수행 과정을 디버깅하고 예측하기 위한 도구로 사용할 수 있습니다.
  • trace_replayBlockTransactions

    • 특정 블록에 포함된 모든 트랜잭션들에 대한 재실행 시뮬레이션을 수행하면서 각 트랜잭션에 대한 다양한 Trace 옵션별 세부 정보를 제공합니다.
  • trace_replayTransaction

    • 특정 트랜잭션에 대한 재실행 시뮬레이션을 수행하면서 다양한 Trace 옵션별 세부 정보를 제공합니다.
  • trace_block

    • 특정 블록에서 생성된 모든 Trace 정보를 조회합니다.
  • trace_filter

    • 설정한 필터 조건에 맞는 트랜잭션들에 대해서 trace 결과를 반환합니다.
  • trace_get

    • 특정 트랜잭션의 trace 정보 중 특정 index의 trace결과를 조회합니다.
  • trace_transaction

    • 특정 트랜잭션의 trace 정보를 모두 조회합니다.

Debug

Geth에서 제공하는 기능으로 트랜잭션 Processing에 대해 자세한 정보를 조회할 수 있는 JSON-RPC API 입니다.

  • debug_traceBlockByHash
    • 특정 블록에 대해 tracer를 설정하여 해당 tracer가 제공하는 정보들을 통해 트랜잭션으로 인한 체인의 상태 변화 및 실제 call의 발생 이력들을 Debug 합니다.
  • debug_traceBlockByNumber
    • 특정 블록에 대해 tracer를 설정하여 해당 tracer가 제공하는 정보들을 통해 트랜잭션으로 인한 체인의 상태 변화 및 실제 call의 발생 이력들을 Debug 합니다.
  • debug_traceCall
    • 이미 처리된 Transaction의 처리 과정을 노드 레벨에서 replay하면서 트랜잭션의 실행 과정에서 각각의 단계와 관련된 상세한 정보를 디버깅하여 확인합니다.
  • debug_traceTransaction
    • eth_call을 디버깅 모드로 실행하면서 trace 기능을 제공합니다. 현재 블록의 상태를 기반으로 특정 call을 수행하였을 때 발생하는 모든 스택 변화를 추적할 수 있습니다.

JSON-RPC Convention

JSON-RPC를 이용하여 블록체인 네트워크와 상호작용하기 위해서는 인터페이스에서 지정한 데이터 형식을 따라야 합니다. 이더리움의 JSON-RPC는 형식이 지정되지 않은 바이트 배열과 숫자를 JSON을 통해 전달합니다.

  • 숫자 입력 시

16진수로 인코딩 한 후, 0x를 접두사로 붙이며 최소한 하나의 숫자는 있어야 합니다.

  • 좋은 예

    • 100을 16진수로 변환 시 ⇒ 0x64
    • 10000을 16진수로 변환 시 ⇒ 0x2710

  • 잘못된 예

    • 0을 16진수로 변환 시 ⇒ 0x? ⇒ 최소한 하나의 숫자가 있어야 하므로 0x0이 맞습니다.
    • 100을 16진수로 변환 시 ⇒ 0x064? ⇒ 16진수의 맨 앞에 0을 허용하지 않으므로 0x64가 맞습니다.
    • 10000을 16진수로 변환 시 ⇒ 2710? ⇒ 0x를 접두사로 붙여야 하므로 **0x2710**이 맞습니다.

  • 바이트 배열 데이터 입력 시

바이트 배열로 입력하게 되는 데이터의 종류는 계정 주소, 해시, 바이트코드 배열 등이 있습니다. 이러한 데이터 입력 시 16진수로 인코딩하게 되며 접두사로 0x를 붙이게 됩니다. 숫자를 입력할 때와의 차이점은 Byte당 따라 2자리를 차지하게 됩니다.

  • 좋은 예
    • “A”를 16진수로 변환 시 ⇒ 0x41
    • “Hello”를 16진수로 변환 시 ⇒ 0x48656c6c6f

  • 잘못된 예
    • Random 텍스트를 16진수로 변환 시 ⇒ 0xab123? ⇒ 데이터 변환 시 Byte 당 2자리의 값을 가지게 되므로 결과값이 짝수로 반환되는 것이 맞습니다.
    • “Hello”를 16진수로 변환 시 ⇒ 48656c6c6f? ⇒ 0x를 접두사로 붙여야 하므로 0x48656c6c6f이 맞습니다.

JSON RPC Error Code 정의표

JSON을 이용할 때 빈번하게 경험할 수 있는 에러 코드에 대한 정의입니다.

CodeMessageDescription
-32000server error빈 배치에 대한 오류 응답으로 반환될 수 있는 에러
-32001notifications not supported알림이 지원되지 않을 때 반환될 수 있는 에러
-32002request timed outtime out이 발생했을 때 반횐될 수 있는 에러
-32600invalid request유효한 요청이 아닐 경우 반환 될 수 있는 에러
-32601"the method X does not exist/is not available”존재 하지 않는 method를 호출 했을 경우 반환될 수 있는 에러
-32601subscription not found존재하지 않는 subscription을 호출 했을 경우 반환될 수 있는 에러
-32602Invalid parameter
("missing value for required argument X”)
입력한 Parameters가 디코딩할 수 없거나 입력한 Parameters 수가 잘못되었을 때 반환될 수 있는 에러.
-32603Internal errorInternal JSON-RPC 에러
-32700parse error서버로 부터 Invalid된 JSON을 받았을 경우 반환될 수 있는 에러