API des nœuds et accès aux données

Chaque explorateur, jeu de données et plateforme d’analyse lit en définitive la chaîne par l’intermédiaire de l’API d’un nœud. La connaissance de ces API vous permet de récupérer précisément les données dont dépend un constat, de vérifier ce qu’un outil tiers vous montre et de comprendre pourquoi une requête qui fonctionne pour un bloc récent échoue pour un bloc ancien. Cette leçon présente les méthodes les plus utilisées par les analystes, les types de nœuds requis et les limites pratiques des fournisseurs et des jeux de données publics.

Deux familles d’API

Bitcoin Core expose une interface JSON-RPC : une requête HTTP POST avec un nom de method et un tableau params, authentifiée au moyen d’un fichier cookie ou d’un utilisateur configuré. Les mêmes méthodes sont disponibles en ligne de commande par l’intermédiaire de bitcoin-cli. Les montants sont renvoyés en BTC sous forme de nombres JSON.

Les clients d’exécution Ethereum implémentent une spécification JSON-RPC commune, maintenue par la communauté Ethereum. Les méthodes eth_ principales se comportent donc de la même manière dans Geth, Nethermind, Besu, Erigon et Reth. La plupart des chaînes EVM, y compris les rollups et les chaînes latérales, proposent la même interface. Les espaces de noms supplémentaires comme debug_ et trace_ dépendent du client. Les quantités sont renvoyées sous forme de chaînes hexadécimales ("0x1b4"), et les arguments de bloc acceptent un nombre hexadécimal ou une étiquette (latest, safe, finalized, earliest, pending), comme l’explique la leçon Les blocs et les en-têtes comme données.

Méthodes Bitcoin Core utilisées par les analystes

Voici une séquence typique pour examiner un paiement :

getblockhash 880214                 -> "0000…3f1a"
getblock "0000…3f1a" 1              -> champs d’en-tête et liste des txids
getrawtransaction "4f3a…c21e" 2     -> transaction décodée avec valeurs prevout et frais
gettxout "4f3a…c21e" 1              -> sortie 1 si elle n’a pas encore été dépensée, sinon null

Le dernier appel vérifie uniquement l’ensemble UTXO actuel : il vous indique si une sortie n’a pas encore été dépensée maintenant, et non quand ni par quoi elle a été dépensée. Pour trouver la transaction qui l’a dépensée, il fallait traditionnellement un indexeur ou un entrepôt de données ; depuis la version 31.0, Bitcoin Core propose un index facultatif des dépenses (txospenderindex) qui permet à gettxspendingprevout de renvoyer la transaction confirmée ayant dépensé une sortie. Bitcoin Core ne dispose toujours d’aucune méthode qui répertorie l’historique d’une adresse ; cette recherche nécessite un indexeur d’adresses ou un entrepôt de données.

Méthodes Ethereum JSON-RPC

Deux comportements surprennent les débutants. eth_getTransactionReceipt renvoie null pour une transaction en attente ou inconnue du nœud, ce qui ne signifie pas qu’elle a échoué. Par ailleurs, les méthodes d’état prennent un argument de bloc : eth_getBalance avec latest donne une réponse différente toutes les quelques secondes ; indiquez donc un numéro de bloc explicite pour tout chiffre que vous comptez communiquer.

eth_getLogs est l’outil de travail essentiel pour l’analyse des jetons et des protocoles. Son filtre prend fromBlock et toBlock (ou un seul blockHash à la place), une adresse address facultative et un tableau positionnel topics. Cette requête demande à un contrat de jeton les événements Transfer envoyés à une adresse donnée sur 1 000 blocs :

{"jsonrpc": "2.0", "id": 1, "method": "eth_getLogs",
 "params": [{
   "fromBlock": "0x1406f40",
   "toBlock": "0x1407327",
   "address": "0x5d3a…7c10",
   "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              null,
              "0x000000000000000000000000c3d4…22e1"]
 }]}

Les blocs vont de 21 000 000 (0x1406f40) à 21 000 999 (0x1407327). Les sujets sont mis en correspondance par position : le premier est la signature Transfer, null accepte n’importe quel expéditeur, et le troisième, topics[2], définit le destinataire. Une position peut aussi contenir un tableau, ce qui signifie « l’un de ceux-ci ». Déplacer l’adresse complétée par des zéros à la deuxième position renverrait plutôt les transferts qu’elle a envoyés.

Méthodes de débogage et de traçage

Les appels internes nécessitent une réexécution. Les clients de type Geth proposent debug_traceTransaction, debug_traceBlockByNumber et debug_traceCall, avec une option tracer telle que callTracer (l’arbre des appels) ou prestateTracer (l’état touché par une transaction). Les clients de type Parity, comme Erigon, Nethermind et Reth, proposent également trace_transaction, trace_block, trace_filter et trace_replayTransaction, qui renvoient des listes d’appels à plat.

Ces méthodes sont coûteuses : un nœud rejoue chaque opcode de la transaction et, pour les blocs anciens, doit d’abord reconstruire l’état historique. Les fournisseurs les désactivent souvent, les limitent ou les facturent plus cher. Les deux styles diffèrent également par leur structure et par des détails tels que la présence ou non des appels aux précompilés. Normalisez donc les résultats avant de combiner ceux provenant de différents clients.

Quels types de nœuds sont nécessaires selon la question

Les nœuds élagués de l’une ou l’autre chaîne ne peuvent pas fournir les anciens blocs, et un nœud Ethereum complet auquel on demande un état antérieur à la période qu’il conserve renvoie une erreur plutôt qu’un nombre erroné. Cette erreur indique utilement qu’il vous faut un nœud d’archive.

Limites de débit, pagination et confiance envers les fournisseurs

Les fournisseurs hébergés protègent leurs nœuds par des limites de débit, comptabilisées en requêtes par seconde ou en « unités de calcul » pondérées, ainsi que par des plafonds appliqués à eth_getLogs : une plage de blocs maximale, un nombre maximal de résultats, ou les deux. Un code d’extraction robuste découpe une plage en segments, réduit de moitié un segment lorsque le fournisseur le rejette, réessaie avec un délai exponentiel et consigne les plages terminées. De nombreux fournisseurs acceptent les requêtes groupées JSON-RPC (un tableau d’appels dans une seule requête HTTP), ce qui réduit la surcharge, mais reste soumis aux mêmes limites.

Les fournisseurs soulèvent également des questions de confiance :

• Têtes incohérentes. Derrière un répartiteur de charge, des appels consécutifs peuvent atteindre des nœuds de hauteurs différentes ; un bloc renvoyé par un appel peut donc être « introuvable » au suivant. Ancrez votre travail à un hachage de bloc plutôt qu’à latest.
• Erreurs et retard. Le nœud d’un fournisseur peut être désynchronisé, mal configuré ou utiliser une autre version de client. Pour les faits dont dépend un constat, comparez le hachage de bloc à votre hauteur d’ancrage entre deux sources indépendantes ou vérifiez-le par rapport à votre propre nœud. Consignez la version du client avec web3_clientVersion sur Ethereum ou le champ subversion de getnetworkinfo dans Bitcoin Core.
• Confidentialité des requêtes. Un fournisseur voit chaque adresse et chaque transaction sur lesquelles vous vous renseignez. Pour les enquêtes sensibles, les journaux d’un fournisseur révèlent le sujet de votre intérêt ; votre propre nœud, non.

Jeux de données publics et frameworks ETL

Pour l’historique en masse, tout extraire par RPC est lent. Deux solutions de rechange existent.

Les jeux de données publics hébergés par de grands fournisseurs de cloud contiennent déjà Bitcoin, Ethereum et d’autres chaînes sous forme de tables : par exemple, les jeux de données sur les cryptomonnaies du programme de données publiques de Google BigQuery, produits par le projet open source blockchain-etl, et le jeu de données AWS Public Blockchain Data, publié sous forme de fichiers Parquet. Ils offrent un accès SQL à l’historique complet en quelques minutes. En contrepartie, vous acceptez leur schéma, leurs choix de décodage, le délai de mise à jour et la politique de réorganisation ; vous devez examiner chacun de ces éléments avant de vous fier à une table.

Les frameworks ETL vous permettent de créer vos propres tables à partir d’un nœud : Bitcoin ETL et Ethereum ETL (blockchain-etl), cryo (qui extrait les blocs, les transactions, les journaux et les traces au format Parquet ou CSV), TrueBlocks (qui indexe chaque apparition d’une adresse) et The Graph (qui indexe les événements de protocoles spécifiques par l’intermédiaire de sous-graphes). Exécuter votre propre pipeline demande des efforts, mais vous donne le contrôle sur le nœud, le décodage et la provenance de chaque ligne. La leçon La pile de données analytiques compare ces options.

Points clés pour l’examen : les niveaux de verbosité de getblock et getrawtransaction dans Bitcoin Core et l’exigence de txindex ; le fait que gettxout vérifie uniquement l’ensemble UTXO actuel et que Bitcoin Core ne dispose pas de méthode pour obtenir l’historique d’une adresse ; les principales méthodes Ethereum, notamment eth_getBlockByNumber, eth_getTransactionReceipt, eth_getBlockReceipts et eth_chainId ; le filtre eth_getLogs et la mise en correspondance positionnelle des sujets avec des jokers null ; les méthodes debug_trace* de type Geth par opposition aux méthodes trace_* de type Parity ; les recherches qui nécessitent un nœud d’archive et la gestion des limites de débit et des plages maximales ; la vérification des fournisseurs et la consignation des versions des clients ; les jeux de données publics et les frameworks ETL ainsi que les compromis qu’ils impliquent.