Référence de l’API RPC

L’interface HTTP qu’un nœud sert aux portefeuilles§: quatre points d’accès, du JSON pour l’état et les erreurs, un encodage binaire compact pour les blocs et les paiements.

L’URL de base du nœud de test public est https://node.tint.top. L’interface ne voit jamais une clé ni un montant§: un portefeuille envoie des paiements terminés et lit des blocs entiers, qu’il déchiffre lui-même.

Points d’accès

Méthode et chemin	Répond avec
`GET /v1/status`	L’état de la chaîne, en JSON.
`GET /v1/blocks/{height}`	Un bloc finalisé, dans l’encodage de transmission.
`GET /v1/blocks?from=N`	Les blocs contenant des paiements à partir de la hauteur N, sous forme de lot de blocs.
`POST /v1/transactions`	Reçoit un paiement dans l’encodage de transmission§; répond avec son identifiant en JSON.

GET /v1/status

request

curl -s https://node.tint.top/v1/status

response (example values)

{
  "chain_id": 6073471695170043905,
  "height": 128431,
  "tip": "9f3c…e21a",
  "genesis": "04b7…c9d0",
  "queued": 0,
  "pools": [
    { "asset": 1, "native": 20000000000000, "other": 10000000000000, "fee_bps": 30 }
  ]
}

Champ	Signification
`chain_id`	Identifiant du réseau, intégré à chaque signature et à chaque hachage de bloc.
`height`	Hauteur du dernier bloc finalisé.
`tip`	Hachage du dernier bloc finalisé, en hexadécimal.
`genesis`	Hachage du premier bloc, en hexadécimal. Deux réseaux de test peuvent partager un `chain_id`§; ce champ permet de les distinguer.
`queued`	Paiements en attente d’un bloc.
`pools[].asset`	La pièce que le pool échange contre la pièce native (1 correspond à `TUSD`).
`pools[].native`, `pools[].other`	Ce que contient le pool, en unités (1 pièce = 100,000,000 unités), à la date du dernier bloc finalisé.
`pools[].fee_bps`	Les frais du pool en dix-millièmes§; 30 correspond à 0.3 %.

GET /v1/blocks/{height}

Renvoie un bloc finalisé en application/octet-stream. Un bloc finalisé ne change jamais, donc la réponse porte Cache-Control: public, max-age=31536000, immutable. Une hauteur non numérique renvoie invalid_height, une hauteur inconnue not_found.

GET /v1/blocks?from=N

Renvoie les blocs qui contiennent des paiements à partir de la hauteur N, sous forme d’un seul lot de blocs (application/octet-stream), avec la dernière hauteur prise en compte par la réponse (through). Un portefeuille qui se met à jour redemande à partir de la hauteur suivant through. La réponse grossit avec la chaîne, elle est donc envoyée avec Cache-Control: no-store. from doit être un nombre entier.

POST /v1/transactions

Envoyez un paiement terminé, dans l’encodage de transmission, comme corps de la requête. Le portefeuille le construit§; le format est défini dans le module wire.rs de tint-core§: champs de largeur fixe, un seul encodage valide par valeur, aucun octet en trop à la fin.

request

curl -s -X POST https://node.tint.top/v1/transactions \
  -H 'content-type: application/octet-stream' \
  --data-binary @payment.bin

response

{ "txid": "5be1…07af" }

Une transaction commence par l’actif (u32), une hauteur d’expiration (u64) et un type (0 pour un paiement, 1 pour un échange), suivis d’un lot§: des drapeaux, un solde de valeur, une ancre, le nombre d’actions et les actions avec leur preuve. Un échange ajoute la pièce achetée, le montant versé et un second lot.

Erreurs

Les erreurs sont en JSON§: {"error":{"code":"...","message":"..."}}.

HTTP	code	Signification
400	`malformed`	Le corps n’est pas un paiement.
400	`invalid_height`	La hauteur ou `from` n’est pas un nombre entier.
404	`not_found`	Aucun bloc finalisé à cette hauteur, ou ressource inexistante.
409	`double_spend`	Une note de ce paiement est déjà dépensée.
409	`conflict`	Un autre paiement en attente dépense l’une des mêmes notes.
409	`price_moved`	Le pool ne donne plus ce que demande cet échange.
413	`too_large`	Le paiement dépasse ce que la chaîne autorise.
422	`rejected`	Le paiement enfreint une règle de la chaîne§; le message précise laquelle.
429	`rate_limited`	Cette adresse cliente a épuisé son quota de requêtes. Réessayez après le délai de l’en-tête `Retry-After`.
500	`internal`	Le nœud n’a pas pu vérifier ou encoder.
503	`busy`, `queue_full`	Le nœud vérifie d’autres paiements, ou sa file est pleine. Réessayez§; `Retry-After: 1`.

Limites de débit

Par défaut, chaque adresse cliente peut effectuer 50 requêtes par seconde en continu, avec une rafale de 100, et au plus 4 paiements sont vérifiés à la fois pour l’ensemble des clients. Les opérateurs peuvent modifier ces deux valeurs. Derrière un proxy inverse, le nœud compte les clients d’après la dernière adresse que le proxy a écrite dans X-Forwarded-For§; il ne croit pas les entrées précédentes.

Exemple§: suivre la chaîne

python (server side)

import json, time, urllib.request

BASE = "https://node.tint.top"

while True:
    with urllib.request.urlopen(f"{BASE}/v1/status", timeout=10) as r:
        status = json.load(r)
    print(status["height"], status["queued"])
    time.sleep(5)

Ce qu’un opérateur de nœud peut encore apprendre de cette interface, c’est l’adresse réseau d’où provient un paiement. Les montants, les expéditeurs et les destinataires sont à l’intérieur de la preuve et des notes chiffrées.