CROAT JSON RPC API

Us heu preguntat mai com es fa per a interactuar amb una blockchain? Un wallet és una aplicació que interactua amb la blockchain, en el cas del CROAT, tenim l’aplicació CROAT Desktop Wallet; però al darrere hi ha unes aplicacions més bàsiques que envien instruccions i consultes per a obtenir informació o escriure’n de nova.

En aquest apartat veurem com utilitzar l’API del servei de node “croatd” mitjançant crides o mètodes JSON RPC i així poder executar consultes directament a la cadena de blocs de CROAT.

Tractarem les diferents consultes disponibles i veurem com executar els exemples amb instruccions utilitzant cURL, des de la línia de comandes del propi node, o utilitzant Postman des d’un equip remot, ja que disposa d’una interfície gràfica.

Per fer-ho mes didàctic intentarem fer pas a pas tot el procés, tot i això, si tens dubtes, els pots plantejar sense problemes al canal de Telegram CROAT Coin.

HABILITAR RPC

Primer de tot hem de tenir actiu un node CROAT creat, tal com s’explica a l’apartat CROAT NODE

Editem l’arxiu de configuració “configs/croat.conf“.

nano configs/croat.conf

Revisarem que tinguem les següents línies.

rpc-bind-ip=0.0.0.0
rpc-bind-port=46348

Mirem d’arrencar croatd

./croatd --config-file configs/croat.conf

Si tot va bé podem sortir amb “exit” i arrancar croatd de fons. Deixarem un arxiu de log a la mateixa carpeta per si el volem consultar en cap moment.

nohup /home/ubuntu/Croat/croatd --config-file /home/ubuntu/Croat/configs/croat.conf --log-file /home/ubuntu/Croat/croatd.log > /dev/null 2>&1 &

Per tal d’assegurar-nos que estem acceptant connexions RPC per el port 46348, executem la següent comanda

netstat -ntlp

El port 46348 ha de sortir amb 0.0.0.0:*

cURL JSONRPC

Les proves més simples que podem fer en aquests moments per a saber si funciona són des del propi servidor. Utilitzarem curl per a enviar una consulta i esperarem la resposta. La documentació ens diu que la instrucció ha de tenir el següent format:

curl -s -X POST http://server:port/json_rpc -H 'Content-Type: application/json-rpc' -d '{ "method": "","params": {},"jsonrpc": "2.0", "id": ""}'
  • Ip del servidor, si es ell mateix cal posar 127.0.0.1
  • Port on tenim el servei RPC, en el nostre cas 46348
  • Serà la instrucció que cridem, el mètode.
  • Algunes instruccions necessiten paràmetres d’entrada per a donar una sortida. Imaginem un filtre per data; la data actuarà com a parametre d’entrada i, segons aquesta, tindrem diferents sortides.
  • Posarem un nom com a identificador

A continuació executem la nostra primera prova amb el mètode (getblockcount), que ens retornarà l’altura de la cadena de blocks.

curl -s -X POST http://127.0.0.1:46348/json_rpc -H 'Content-Type: application/json-rpc' -d '{"method":"getblockcount","params":{},"jsonrpc":"2.0","id":"json_test"}'

La sortida ens retorna 2 resultats

count: 539623 | El valor que volíem saber, corresponent a l’altura actual de la cadena de blocs.
status: OK | Codi d’error RPC general. “OK” significa correcte.

POSTMAN

El programa POSTMAN ens permet, mitjançant una interfície gràfica, fer proves d’una API. El podem descarregar per a diferents plataformes des de https://www.postman.com/downloads/. Un cop instal·lat, caldrà que ens registrem per a poder executar el programa.

Des del menú (File / Import) podem importar instruccions, fins i tot les fetes amb cURL.

Només cal seleccionar (Paste Raw Text) i enganxar la instrucció. Atenció amb una cosa, la IP ja no és 127.0.0.1, haurem de proveir la IP del servidor/equip on tinguem el croatd funcionant.

curl -s -X POST http://192.168.1.20:46348/json_rpc -H 'Content-Type: application/json-rpc' -d '{"method":"getblockcount","params":{},"jsonrpc":"2.0","id":"json_test"}'

Si tot ha anat bé ja tindrem la instrucció preparada. A l’apartat (Body) de la part superior tenim el “method”, “params”, “id”. Cal fer clic a (Send) per a executar. A l’apartat (Body) de la part inferior tenim el resultat.

LLISTAT DE MÈTODES (JSONRPC)

La documentació dels mètodes o crides les hem fet amb POSTMAN, així els podeu importar fàcilment, fer proves i fins i tot obtenir codis d’exemple.

https://documenter.getpostman.com/view/12889642/TVKHVFxb

Per exemple, un cop dins podeu importar els mètodes fent clic a (Run in Postman) i sel·leccionant (Postman for Windows).

També veureu que ja teniu per defecte 2 punts d’entrada on es fan les crides:

https://api.croat.community/v1/croatd/getinfo
https://api.croat.community/v1/croatd/json_rpc

Això s’ha fet per diferents motius:

  1. Ja no cal crear un NODE Croat propi, podem utilitzar el de CROAT.Community
  2. El punt d’entrada (getinfo  ) i (json_rpc) funcionen sobre SSL, útil per fer crides des de pàgines web HTTPS
  3. Aquestes entrades ataquen per defecte a un node, adicionalment, tenim 2 paràmetres GET a indicar a la url.
    • node=url:port, utilitzat per especificar un node personalitzat.
    • debug=1, utilitzat per mostrar informació adicional en el procés de la consulta.

Així doncs, el següent punt

http://api.croat.community/v1/croatd/json_rpc?node=node-01.croatpirineus.cat:46348&debug=1

Ens retornaria una consulta feta contra un node node-01.croatpirineus.cat:46348 i amb informació adicional debug=1 del procés de la consulta.

EXEMPLES

Un dels avantatges de tenir una crida JSON RPC amb postman es que el programa et genera l’exemple sobre diferents idiomes de programació i poder així executar el resultat, per exemple, si obrim el mètode (getblockcount) tenim:

  1. La documentació.
  2. Un exemple creat, en aquest cas amb javascript/jquery.
  3. Un exemple de resposta.

Això ens permet ràpidament fer un arxiu simple html amb el següent resultat:

https://api.croat.community/exemples/getblockcount.html (El podeu descarregar aquí:getblockcount.zip)

Prepararem més exemples dins (https://api.croat.community/)

En cas de voler un altre llenguatge de programació el podeu seleccionar amb el desplegable (LANGUAGE) de l’apartat superior: