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.

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.

TAULA DE CONTINGUTS

rev.28/10/2020

DESCRIPCIONS

Imaginem que anem a un restaurant i volem menjar un plat de pasta, una possible opció seria dir al cambrer "Diguem tots els plats que tens", això pot suposar una llista molt llarga, a part que segurament estarem una estona escoltant la resposta.

Per altre banda, podem fer una pregunta més eficient, ja que volem pasta la nostre pregunta podria ser "Quins plats de pasta tens?". Amb això segurament tindrem una resposta molt acurada del que ens interessa i, en molts casos, també rebrem informació important relacionada (com seria la salsa a acompanyar).

Hem començat amb aquest exemple per poder entendre una mica com podem pensar a l'hora d'interactuar amb la cadena de blocs, el fet es no demanar sempre tota l'informació, es demanar informació concreta per tenir una resposta concreta i, en alguns casos, informació relacionada.

Repassem i introduïm alguns conceptes

NODE Croat: Un NODE Croat és un equip connectat a internet amb un programa engegat "croatd" que s'encarrega de diferents coses, entre elles, validar els blocs minats, tenir la cadena de blocs sincronitzada amb altres nodes, oferir serveis de consulta (JSON RPC API)

JSON (JavaScript Object Notation): És el format de l'intercanvi de dades.

RPC (Remote Procedure Call): És la manera d'intercanviar l'informació entre un client i un NODE.

API (Application Programming Interface): Són les funcions, procediments i rutines que ens permeten consultar l'informació.

cURL: Programa sense interfície gràfica (ms-dos) per a la transferència d'arxius que permet executar peticions a APIs.

Postman: Programa amb interfície gràfica que ens permet fer peticions a APIs, tractar les respostes i tenir exemples documentats de programació.

Amb tot això podem comencem els següents apartats per saber com utilitzar l'API del servei de NODE "croatd" mitjançant crides o mètodes en format 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.

Finalment demostrarem, amb un exemple senzill, com fer una petita pàgina web amb una consulta real.

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: