JSON-RPC

Como conectamos uma aplicação ou nosso terminal a uma blockchain para que ela possa interagir com ela? Precisamos nos conectar a um nó da blockchain utilizando um protocolo de comunicação.

No caso do Ethereum, cada cliente de execução (como Geth, Erigon, Besu ou Nethermind) implementa a mesma especificação JSON-RPC, permitindo o uso de um conjunto padronizado de métodos — independentemente do cliente usado.

JSON-RPC é um protocolo para executar métodos remotamente que utiliza JSON como formato padrão para transferência de dados. É independente da linguagem de programação, o que facilita sua implementação em diferentes tecnologias e ambientes.

A que nó devemos nos conectar? Você pode se conectar a qualquer nó da blockchain — seja um nó que você mesmo controla ou um de terceiros. No segundo caso, existem provedores de acesso à blockchain, como: Alchemy, Quicknode o Infura.

JSON-RPC pode ser transportado por diversos protocolos de comunicação, como HTTP, WebSockets, TCP, entre outros. No caso do HTTP, a conexão não permanece aberta, ao contrário do WebSockets, que mantém a conexão ativa.

Estrutura de uma notificação JSON-RPC

Uma notificação é uma requisição sem o campo id, o que indica que o cliente não espera uma resposta

• jsonrpc: A versão do protocolo (atualmente "2.0").

• method: El nombre del método a invocar.

• params: (Opcional) Los parámetros para el método, que pueden ser un array o un objeto.

• id: (Opcional) Un identificador único para la solicitud, utilizado para correlacionar las respuestas. Si no se especifica, la solicitud se considera una notificación y no se espera una respuesta.

• method: O nome do método a ser invocado.

• params: (Opcional) Os parâmetros do método, que podem ser um array ou um objeto.

• id: (Opcional) Um identificador único para a requisição, usado para correlacionar as respostas. Se não for especificado, a requisição é considerada uma notificação e não se espera uma resposta.

Vamos ver um exemplo:

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

Estrutura de uma resposta JSON-RPC

Uma resposta JSON-RPC contém os seguintes campos:

• jsonrpc: A versão do protocolo (atualmente "2.0").

• result: O resultado da execução do método (presente se não houve erro).

• error: Um objeto de erro (presente se houve um erro na execução).

• id: O identificador da requisição correspondente.

Exemplo de uma resposta bem-sucedida

{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 1
}

Exemplo de uma resposta com error

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

Estrutura de uma notificação JSON-RPC

Uma notificação é uma solicitação sem o campo id, o que indica que o cliente não espera uma resposta.

{
  "jsonrpc": "2.0",
  "method": "update",
  "params": ["parameter1", "parameter2"]
}

Uso de JSON-RPC no Ethereum

Os métodos JSON-RPC no Ethereum permitem enviar transações, consultar saldos, interagir com contratos inteligentes, e muitas outras operações. A seguir, alguns exemplos:

1. eth_blockNumber: Obtém o número do bloco mais recente. Requisição:

   {
     "jsonrpc": "2.0",
     "method": "eth_blockNumber",
     "params": [],
     "id": 1
   }

   Resposta:

   {
     "jsonrpc": "2.0",
     "result": "0x5b8d80",
     "id": 1
   }

   Pode-se observar que o resultado da resposta é retornado em hexadecimal. Convertido para decimal, o valor seria "6000000".

2. eth_getBalance: Obtém o saldo de um endereço especificado.

   Requisição:

   {
     "jsonrpc": "2.0",
     "method": "eth_getBalance",
     "params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest"],
     "id": 1
   }

   Neste caso, foi necessário especificar como parâmetros o endereço e o número do bloco em que queremos consultar o saldo (no exemplo, o mais recente: "latest").

   Resposta:

   {
     "jsonrpc": "2.0",
     "result": "0x0234c8a3397aab58",
     "id": 1
   }

   Expresso em decimal, o resultado seria “158972490234375000” wei, ou seja, 0,159 ETH.

3. eth_sendTransaction: Envia uma transação.

   Requisição:

   jsonCopiar código
   {
     "jsonrpc": "2.0",
     "method": "eth_sendTransaction",
     "params": [{
       "from": "0xYourAddress",
       "to": "0xReceiverAddress",
       "value": "0x9184e72a000"  // 0.01 ether
     }],
     "id": 1
   }

   Resposta:

   {
     "jsonrpc": "2.0",
     "result": "0xTransactionHash",
     "id": 1
   }

   O resultado que obteremos como resposta, neste caso, é o hash da transação.

Conexão com a Ethereum utilizando o terminal e JSON-RPC

Para estabelecer comunicação entre seu terminal e a blockchain Ethereum utilizando chamadas JSON-RPC, siga os passos abaixo:

Passo 1: Configurar um nó Ethereum ou utilizar um nó público

Como mencionado anteriormente, para interagir com a blockchain do Ethereum, é necessário conectar-se a um nó.

Você pode:

• Configurar seu próprio nó utilizando softwares como Geth ou Nethermind, ou

• Usar um nó público como Alchemy, Infura ou QuickNode.

Neste exemplo, utilizaremos um nó da Alchemy.

Passo 2: Obter um Endpoint JSON-RPC

Para se conectar a um nó da Alchemy, você deve criar uma conta em https://www.alchemy.com e obter uma URL de endpoint JSON-RPC.

• Registre-se na Alchemy.
• Crie um novo projeto e obtenha a URL do seu endpoint, que terá um formato semelhante a:

  <https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_PROJECT_ID>

Passo 3: Realizar chamadas JSON-RPC a partir do terminal

Você pode usar ferramentas como curl para enviar chamadas JSON-RPC diretamente do terminal.

Exemplo: Obter o número do bloco atual

Usando o curl, você pode fazer uma chamada JSON-RPC para obter o número do bloco atual da rede Ethereum.

curl -X POST <https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_PROJECT_ID> \\
     -H "Content-Type: application/json" \\
     -d '{
           "jsonrpc":"2.0",
           "method":"eth_blockNumber",
           "params":[],
           "id":1
         }'

Explicación del comando

• X POST: Indica que se trata de uma requisição POST.

• https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_PROJECT_ID: URL do nó Ethereum ao qual você está se conectando.

• H "Content-Type: application/json": Define o tipo de conteúdo da requisição como JSON.

• d '...': Define o corpo da requisição, que contém os parâmetros da chamada JSON-RPC.

Resposta esperada A resposta será um objeto JSON que contém o número do bloco atual em formato hexadecimal.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x131f640" // Número de bloque en formato hexadecimal
}

Alguns métodos JSON-RPC

Método	Descrição	Parâmetros	JSON
eth_chainId	Retorna o ID da blockchain atual. No caso do Ethereum, o valor retornado é 1.		{ "jsonrpc": "2.0", "method": "eth_chainId", "params": [] }
eth_blockNumber	Retorna o número do bloco mais recente.		{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [] }
eth_gasPrice	Retorna o preço atual do gás, expresso em wei.		{ "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [] }
eth_blobBaseFee	Retorna a tarifa base por gás de blob, expressa em wei.		{ "jsonrpc": "2.0", "method": "eth_blobBaseFee", "params": [] }
eth_getBalance	Retorna o saldo de uma conta em um bloco específico.	account, block (earliest, latest, safe, finalized, pending)	{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": [ "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest" ] }
eth_getCode	Retorna o código armazenado em um endereço específico.	account, block (earliest, latest, safe, finalized, pending)	{ "jsonrpc": "2.0", "method": "eth_getCode", "params": [ "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "latest" ] }
eth_call	Executa uma chamada sem criar uma transação na blockchain (somente leitura).	nonce, type, from, to, gas, value, data, gas price, max fee per gas, max priority fee per gas, max fee per blob gas, block.	{ "jsonrpc": "2.0", "method": "eth_call", "params": [ { "nonce": null, "type": null, "from": null, "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "gas": null, "value": null, "data": null, "gasPrice": null, "maxFeePerGas": null, "maxPriorityFeePerGas": null, "maxFeePerBlobGas": null }, "latest" ] }
eth_getBlockByNumber	Retorna informações de um bloco com base no número do bloco.	block, is full (boolean)	{ "jsonrpc": "2.0", "method": "eth_getBlockByNumber", "params": [ "latest", false ] }

Informação adicional

• JSON-RPC en ethereum.org
• Playground de JSON-RPC
• Especificación técnica de los métodos JSON-RPC