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 값으로 해당 블록에 포함된 트랜잭션의 수를 조회합니다.
    
    

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_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 표준 반영에 따라 서명되는 트랜잭션에 포함되어야 합니다.

• 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 해시값을 반환합니다.
    
    

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을 수행하였을 때 발생하는 모든 스택 변화를 추적할 수 있습니다.
    
    

Polygon Only

Polygon 체인에 특화된 JSON-RPC로 블록의 생성자 및 검증자의 데이터를 조회할 수 있는 JSON-RPC API 입니다.

• bor_getAuthor
  • 특정 블록의 Author정보를 조회합니다.
• bor_getCurrentProposer
  • 현재 Proposer의 주소를 반환합니다.

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을 이용할 때 빈번하게 경험할 수 있는 에러 코드에 대한 정의입니다.