Como usar nós de blockchain do Ethereum

Esta página descreve como chamar a API do nó Ethereum. Antes de acessar o nó da blockchain do Ethereum, você precisa saber a chave da API e o URL do endpoint do nó. Siga o guia usando nós de blockchain para determinar isso, se ainda não tiver feito.

JSON-RPC

Esta seção descreve como consultar a API JSON-RPC de um nó de blockchain do Ethereum.

Exemplo de RPC de cliente de execução

É possível consultar o cliente de execução (Geth para nós completos ou Erigon para nós de arquivo) por JSON-RPC. Consulte a especificação da API Ethereum para conferir a especificação genérica de JSON-RPC ou a documentação da RPC do Geth para conferir a documentação específica do Geth.

Por exemplo, para chamar o método eth_getBlockByNumber():

curl -H POST \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id":1,
    "jsonrpc":"2.0",
    "method": "eth_getBlockByNumber",
    "params": ["0x1", true]
  }' \
  http://YOUR_NODES_URL

Em que:

  • id é um identificador definido pelo cliente, ou seja, o originador da solicitação. Por exemplo, 1.
  • jsonrpc é a versão do JSON-RPC. Por exemplo, 2.0.
  • method é o nome do método. Por exemplo, eth_getBlockByNumber.
  • params são valores a serem usados com method.
  • YOUR_NODES_URL é o endereço retornado em Pegar os URLs do nó da blockchain. Por exemplo, json-rpc.ejp4j0b1rdiq06p8lxksd5z25.blockchainnodeengine.com.
  • YOUR_API_KEY é a chave que você criou em Criar uma chave de API.

Consulte a especificação JSON-RPC2.0 para mais informações sobre o formato do objeto de solicitação.

Confira um exemplo de resposta para o comando acima:

{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "difficulty" : "0x3ff800000",
      "extraData" : "0x476574682f76312e302e302f6c696e75782f676f312e342e32",
      "gasLimit" : "0x1388",
      "gasUsed" : "0x0",
      "hash" : "0x88e96d4537bea4d9c05d12549907b32561d3bf31f45aae734cdc119f13406cb6",
      "logsBloom": "0x0000000000000000000000000000000000000",
      "miner" : "0x05a56e2d52c817161883f50c441c3228cfe54d9f",
      "mixHash" : "0x969b900de27b6ac6a67742365dd65f55a0526c41fd18e1b16f1a1215c2e66f59",
      "nonce" : "0x539bd4979fef1ec4",
      "number" : "0x1",
      "parentHash" : "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3",
      "receiptsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "size" : "0x219",
      "stateRoot" : "0xd67e4d450343046425ae4271474353857ab860dbc0a1dde64b41b5cd3a532bf3",
      "timestamp" : "0x55ba4224",
      "totalDifficulty" : "0x7ff800000",
      "transactions" : [],
      "transactionsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "uncles" : []
   }
}

RPC do nó de beacon

O Blockchain Node Engine também expõe o endpoint do cliente de consenso do Ethereum. Por exemplo, para solicitar o estado do validador no slot 1:

curl \
-H "X-goog-api-key: YOUR_API_KEY" "Content-Type: application/json" \
'http://beacon.YOUR_NODES_URL/eth/v1/beacon/states/head/validators/1'

Você também pode fornecer a chave de API como um cabeçalho HTTP em vez de um parâmetro de consulta. A consulta abaixo é equivalente:

curl \
-H "Content-Type: application/json" \
'http://beacon.YOUR_NODES_URL/eth/v1/beacon/states/head/validators/1?key=YOUR_API_KEY'

Explicação detalhada:

Confira um exemplo de resposta para o comando acima:

{
  "execution_optimistic": false,
  "data": {
    "index": "1",
    "balance": "36835614902",
    "status": "active_ongoing",
    "validator": {
      "pubkey": "0x1234abcd",
      "withdrawal_credentials": "0x1234abcd",
      "effective_balance": "32000000000",
      "slashed": false,
      "activation_eligibility_epoch": "0",
      "activation_epoch": "0",
      "exit_epoch": "18446744073709551615",
      "withdrawable_epoch": "18446744073709551615"
    }
  }
}

WebSocket

Para se inscrever em feeds de dados em vez de consultar dados, use a API WebSocket do cliente de execução do nó da blockchain.

Por exemplo, para se inscrever em novos cabeçalhos de cadeia:

wscat -c wss://ws.YOUR_NODES_URL?key=YOUR_API_KEY
Connected (press CTRL+C to quit)
> {"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"]}

O cliente de execução vai responder com um identificador para a assinatura, como:

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

Em seguida, o cliente vai enviar detalhes de cada novo bloco de cabeça da cadeia conforme ele ocorre. Confira um exemplo de evento da assinatura acima:

{
   "jsonrpc" : "2.0",
   "method" : "eth_subscription",
   "params" : {
      "result" : {
         "baseFeePerGas" : "0x4bdc620b8",
         "difficulty" : "0x0",
         "extraData" : "0x496c6c756d696e61746520446d6f63726174697a6520447374726962757465",
         "gasLimit" : "0x1c9c380",
         "gasUsed" : "0xe24dae",
         "hash" : "0xbde840749c4d9086d17d66079d5f7d3d568ed4572329691e5b4a70f44a551816",
         "logsBloom": "0x0000000000000000000000000000000000000",
         "miner" : "0xb4c9e4617a16be36b92689b9e07e9f64757c1792",
         "mixHash" : "0xf68eb0b3ec50e1543de1cc7f09c7735ba20fa252124511756857078a3ff9a7cf",
         "nonce" : "0x0000000000000000",
         "number" : "0x109e280",
         "parentHash" : "0x54f78faba9fde0d15d7a9d6b80c4569435c7fdc5f1fef3255110373b66ce14de",
         "receiptsRoot" : "0x876bcb5772f8597fee4b063c57b7a51209eb428034efabf4cdf39a46901681b4",
         "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
         "stateRoot" : "0xfc5daf9608c8f2b9944bcfe0b9182148d85b1a6ad4dc52d3eb522dd02687c7e0",
         "timestamp" : "0x647fd287",
         "transactionsRoot" : "0x0acaef87e4609ea6075d88fdd404b3fbd25d796af9044522beefd3c708d37af8",
         "withdrawalsRoot" : "0x7adfc670253572678769e7d80db8c4c94b5d14d4e014274f39b679fdb5e72d98"
      },
      "subscription" : "0xf47df962ae9ba250ba9e9fb239b6894f"
   }
}

Métricas

Os nós do Ethereum fornecem várias métricas sobre o estado operacional do nó. Normalmente, elas são consumidas por uma ferramenta como o Prometheus ou o Grafana.

Para buscar as métricas expostas por um cliente de farol, use um comando como este:

curl https://bc-mc.YOUR_NODES_URL/metrics/prometheus?key=YOUR_API_KEY

Isso produz uma saída semelhante a esta:

# HELP async_tasks_count Total number of async tasks spawned using spawn
# TYPE async_tasks_count gauge
async_tasks_count{async_task_count="addr_broadcast"} 0
async_tasks_count{async_task_count="beacon_node"} 0
async_tasks_count{async_task_count="beacon_processor_manager"} 1
async_tasks_count{async_task_count="beacon_processor_reprocess_queue"} 1
async_tasks_count{async_task_count="beacon_processor_worker"} 0
async_tasks_count{async_task_count="discv5"} 4
async_tasks_count{async_task_count="el_fork_choice_update"} 0
async_tasks_count{async_task_count="eth1"} 1
...

Há endpoints de métricas separados para o cliente de execução e o cliente de beacon. Para o cliente de execução, eles geralmente têm o prefixo ec-mc, e para o cliente de beacon, geralmente têm o prefixo bc-mc (como no exemplo acima).

Leia mais sobre as métricas de cada software cliente em:

Guia de referência de portas do Private Service Connect

Os nós ativados pelo Private Service Connect usam um endereço IP estático gerado pelo usuário com a porta designada para gerar um endpoint. Use o mapeamento adequado na tabela a seguir.

Tipo de porta Número da porta
Endpoint da API JSON-RPC 8545
Endpoint da API Geth Websocket 8546
Endpoint da API Erigon Websocket 8545
Endpoint da API Beacon 5052
Endpoint da API Prometheus Metrics do Beacon 5054
Endpoint da API Execution Client Prometheus Metrics 8647