Ce que documente le README de canopy-network/canopy : une référence des routes JSON-RPC

Ce que contient ce dépôt et ce que couvre le README

Le dépôt est l'implémentation Go officielle du protocole Canopy Network. Le README fourni, situé dans cmd/rpc/README.md, n'est pas une vue d'ensemble du projet ; c'est une référence des routes de l'API JSON-RPC exposée par le démon RPC du nœud. Ceux qui cherchent des instructions de compilation, des fichiers de configuration ou une description du moteur de consensus n'en trouveront pas ici. La portée du README est la surface HTTP : une liste de routes sous /v1/, /debug/pprof et /v1/eth, suivie de documentations détaillées par méthode avec schémas de requête et de réponse et exemples curl vers localhost:50002.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Ce que contient ce dépôt et ce que couvre le README », ce contrôle porte sur le point décrit et non sur une capacité générale.

L'index des routes et les méthodes documentées

Le README s'ouvre sur une liste plate de plus d'une centaine de routes. La majorité sont des requêtes en lecture seule sous /v1/query/, qui couvrent la hauteur, les comptes, les pools, les validateurs, les comités, les paramètres, l'offre, l'état, les blocs, les transactions, les événements, les ordres, les lots DEX, les preuves et les données de checkpoint. Un petit ensemble de routes d'écriture se trouve sous /v1/tx et /v1/txs, et la famille /v1/admin/ gère le keystore, la construction de transactions et l'inspection du nœud. La liste inclut aussi /v1/eth, /debug/pprof et /debug/pprof/*name, mais le README ne documente ces endpoints que par leur nom. Seule une partie des routes listées possède les sections détaillées qui suivent ; le reste n'apparaît que dans l'index.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « L'index des routes et les méthodes documentées », ce contrôle porte sur le point décrit et non sur une capacité générale.

Soumission de transactions

Deux routes soumettent des transactions. /v1/tx accepte une transaction unique et renvoie son hash en chaîne hexadécimale ; /v1/txs accepte un tableau et renvoie un tableau de hashes. Le schéma de requête est le même pour les deux : un nom de message dans type, une charge utile dans msg, une signature contenant la clé publique et la signature, un temps de création en microsecondes Unix pour la protection contre la relecture, une createdHeight qui doit être à +/- 4320 de la hauteur actuelle, des frais, un memo facultatif, une networkID et une chainID. Les exemples du README utilisent networkID 1 pour le mainnet et 2 pour le testnet, et chainID 1 pour canopy et 2 pour canary. Les noms de messages documentés incluent send, stake et edit-stake ; l'index des routes liste bien plus de types de transactions sous /v1/admin/.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Soumission de transactions », ce contrôle porte sur le point décrit et non sur une capacité générale.

Comptes, pools et validateurs

Les endpoints de requête pour les comptes et les pools partagent une convention de pagination : perPage vaut 10 par défaut avec un maximum de 5 000, et pageNumber vaut 1 par défaut. Les réponses de comptes séparent le solde dépensable de totalAmount et exposent un calendrier d'acquisition via vestedAmount, lockedAmount, vestingAmount, vestingStartHeight, vestingCliffHeight et vestingEndHeight, les champs d'acquisition étant omis quand ils sont nuls. Les réponses de pools portent un solde et une liste de points de pool avec adresses de destinataires. Les réponses de validateurs ajoutent publicKey, stakedAmount, la liste des comités pour lesquels le validateur a mis en jeu, une netAddress pair à pair, des hauteurs de pause et de désengagement, une adresse de sortie pour les récompenses et deux booléens : delegate et compound. L'endpoint validators accepte des filtres facultatifs pour le désengagement, la pause, la délégation et l'état de comité, chaque filtre prenant 0 pour désactivé, 1 pour doit être, ou 2 pour exclure.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Comptes, pools et validateurs », ce contrôle porte sur le point décrit et non sur une capacité générale.

Comités, consensus et preuves

Plusieurs endpoints décrivent le fonctionnement des comités. /v1/query/committee-data rapporte les dernières hauteurs de chaîne racine et de chaîne déclarées par un comité, ses destinataires de pourcentages de paiement et le nombre de transactions de résultats de certificat traitées. /v1/query/subsidized-committees et /v1/query/retired-committees renvoient des listes d'identifiants de chaîne. /v1/query/non-signers liste les validateurs qui ont manqué des blocs récents, avec un compteur qui augmente à chaque bloc manqué et se réinitialise à chaque non-sign-window. /v1/query/validator-set renvoie les validateurs non délégués actuellement en consensus pour un comité, avec clé publique, pouvoir de vote et adresse réseau. /v1/query/cert-by-height expose un certificat de quorum pour une hauteur donnée, y compris l'en-tête, le hash du bloc, un hash de résultats et les destinataires convenus des récompenses et des slashes.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Comités, consensus et preuves », ce contrôle porte sur le point décrit et non sur une capacité générale.

Paramètres et offre

Le nœud conserve les paramètres du protocole par catégorie et les expose individuellement ou regroupés. /v1/query/params renvoie les objets consensus, validateur, frais et gouvernance dans une seule réponse. Des routes séparées renvoient chaque catégorie isolément : con-params, val-params, fee-params, gov-params et eco-params. Les paramètres de validation couvrent les durées de désengagement, les limites de pause, les pourcentages de slash pour double signature et absence de signature, les limites de taille des comités, les tailles d'ordres et les seuils de subvention. Les paramètres de frais fixent des frais minimaux par type de transaction en micro-dénomination. Les paramètres de gouvernance incluent le pourcentage de récompense DAO. Les paramètres économiques décrivent la frappe par bloc, la distribution aux comités, la part DAO et les parts du proposant et du délégué. /v1/query/supply renvoie les montants totaux, mis en jeu et délégués uniquement, plus une ventilation par comité.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Paramètres et offre », ce contrôle porte sur le point décrit et non sur une capacité générale.

État, différences d'état et blobs d'indexeur

Trois endpoints donnent accès à l'état du registre. /v1/query/state renvoie l'export complet de l'état au format genesis.json, avec pools, comptes, non-signataires, validateurs, paramètres, offre et carnets d'ordres. /v1/query/state-diff compare deux hauteurs et montre les valeurs modifiées, l'ancienne et la nouvelle étant imprimées ensemble ; le README documente une variante GET pour le navigateur et une variante POST qui renvoie la même forme. /v1/query/indexer-blobs renvoie l'état à une hauteur demandée sous forme d'octets protobuf, y compris blocs, comptes, pools, validateurs, données DEX, comités, offre et compteurs pour les validateurs et délégués actifs, en pause et en désengagement, les comptes, pools et validateurs étant renvoyés comme deltas entre le blob actuel et le précédent.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « État, différences d'état et blobs d'indexeur », ce contrôle porte sur le point décrit et non sur une capacité générale.

Routes d'administration et questions ouvertes

La famille /v1/admin/ est le côté opérationnel de l'API. Elle gère un keystore (new-key, import, import-raw, delete, get), soumet des transactions par type (send, stake, edit-stake, unstake, pause, unpause, change-param, dao-transfer, création et édition d'ordres, ordres DEX, subvention, lancement de scrutin et vote) et expose des internals du nœud comme l'utilisation des ressources, les informations de pairs, les informations de consensus, le carnet de pairs, la configuration et le journal. Le README nomme ces routes mais ne documente pas leurs schémas de requête ou de réponse. Le README n'établit pas non plus comment le démon est démarré, comment les endpoints d'administration sont authentifiés, ce que les endpoints /v1/eth acceptent, ni lesquelles des routes listées sont considérées comme stables. Ces détails doivent être vérifiés ailleurs, et le README lui-même ne donne aucune instruction d'installation ou de compilation pour l'implémentation Go.

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Dans la section « Routes d'administration et questions ouvertes », ce contrôle porte sur le point décrit et non sur une capacité générale.

Conclusion éditoriale

Une lecture utile de Canopy passe par les routes JSON-RPC réellement documentées dans le README et par les exemples de requêtes. Il faut comparer les réponses de `state`, `account` et des routes de transaction avec le schéma annoncé, puis distinguer les routes publiques des routes d’administration. Le dépôt ne fournit pas une garantie de compatibilité pour chaque version cliente. Cette conclusion concerne canopy et ses fichiers ou commandes documentés.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes