L’API du nœud

Chaque nœud ZooBC sert une API HTTP publique unique. C’est par elle que les portefeuilles, les explorateurs, les outils en ligne de commande et n’importe quelle page web lisent la chaîne et soumettent des transactions. La lecture ne nécessite ni clé, ni compte, ni clé API, et l’API répond aux pages hébergées n’importe où. L’écriture ne nécessite qu’une transaction signée par son expéditeur.

L’essentiel

• Où : HTTP/1.1 en clair sur le port 8080 par défaut, avec plus d’une centaine de routes sous /api/v1/. Le nœud sert aussi le portefeuille web à / et à /wallet.
• Pas de TLS sur le nœud : les sites publics atteignent l’API en HTTPS par l’intermédiaire d’une passerelle, qui place aussi en amont un service d’archivage pour l’historique profond.
• Ouverte à toutes les pages : chaque réponse porte Access-Control-Allow-Origin: *, et la vérification OPTIONS du navigateur reçoit une réponse immédiate, si bien qu’une page de n’importe quel domaine peut appeler l’API (construire une appli en une seule page HTML).
• Surtout des lectures : toutes les routes sauf huit sont des lectures qui ne nécessitent aucune authentification. Envoyer une transaction ne nécessite aucune clé API, car la transaction porte sa propre signature.
• Limites par adresse de client : 300 requêtes d’écriture par minute par défaut (au-delà, le nœud répond 429 avec un en-tête Retry-After) ; les lectures sont illimitées, sauf si l’opérateur fixe une limite.

Ce que vous pouvez lire

Tous les chemins de la deuxième colonne se trouvent sous /api/v1/. /movements liste chaque changement du solde d’un compte avec sa cause, y compris le loyer payé et les récompenses gagnées. /pubkey renvoie la clé publique d’un compte natif à partir de sa seule adresse. Depuis la version 0.5.8, les routes de la chaîne indiquent la finalized_height, et chaque transaction un drapeau finalized, levé dès qu’un bloc dorsal cosigné couvre son bloc (finalité et retour arrière).

N’importe qui peut consulter n’importe quelle adresse de cette façon. La chaîne enregistre des clés, pas des noms : sur ZooBC, la confidentialité vient donc de la façon dont les adresses sont utilisées, et non de soldes cachés (comptes et adresses).

Soumettre une transaction

Un client construit les octets de la transaction, signe le condensé lié à la chaîne avec la clé de l’expéditeur, en utilisant le genesis_hash lu à /api/v1/node/info (signer une transaction), et envoie le résultat à POST /api/v1/transactions. Aucun SDK n’est nécessaire : Ed25519, SHA3-256 et le hachage de genèse suffisent.

Le nœud répond HTTP 202, ce qui signifie «  acceptée  », et non «  terminée  », et renvoie le hachage de la transaction. Le client interroge ensuite /api/v1/transactions/<hash>/status, qui passe successivement par :

1. staging, puis mempool, tant que la transaction attend un bloc ;
2. confirmed, avec la hauteur du bloc, dès qu’un bloc l’inclut ;
3. ou rejected, avec la raison et l’étape, si elle est refusée ; not_found (404) si le nœud ne la connaît pas.

À raison d’un bloc toutes les 15 secondes, interroger toutes les deux secondes environ est largement suffisant. Avant de livrer des biens contre un paiement, attendez la confirmation, et de préférence le drapeau de finalisation.

Si une réponse se perd, renvoyez les octets signés à l’identique. Le hachage est calculé à partir de ces octets : un nœud qui détient déjà la transaction, même si elle est déjà incluse dans un bloc, répond de nouveau 202 en la marquant comme doublon, et elle n’est exécutée qu’une seule fois. Signer de nouveau avec un nouvel horodatage crée une transaction différente, et c’est ainsi que surviennent les doubles paiements.

Requêtes signées et annulation

Quelques requêtes portent leur propre signature : une signature Ed25519 sur METHOD:PATH:TIMESTAMP:BODY, valable 300 secondes. Un client qui échoue à 20 authentifications signées en 5 minutes est bloqué pendant 300 secondes. Une transaction en attente peut être retirée du mempool d’un nœud par une requête DELETE signée (messages signés et chiffrés).

Autres interfaces d’un nœud

• Port 8001 : le réseau pair à pair entre nœuds.
• Port 8545 : un adaptateur JSON-RPC de style Ethereum, limité par défaut à la machine du nœud, utilisé par MetaMask.
• Port 8332 : un adaptateur RPC de style Bitcoin Core, désactivé par défaut, qui nécessite les identifiants propres de l’opérateur.

Voir aussi

• Construire une appli en une seule page HTML
• Les outils en ligne de commande
• Les passerelles
• Signer une transaction
• L’explorateur et les nœuds d’archivage