Yellow Paper blockchain : rôle, contenu et méthode de lecture

Un Yellow Paper blockchain est une spécification technique qui décrit précisément le fonctionnement d’un protocole : états, transactions, règles de validation, calcul des frais ou comportement d’une machine virtuelle. Plus formel qu’un whitepaper, il vise surtout les développeurs, chercheurs et auditeurs. Sa présence peut améliorer la transparence d’un projet, mais elle ne garantit ni que le code respecte le document ni que la spécification est encore à jour.

Qu’est-ce qu’un Yellow Paper blockchain ?

Le terme désigne un document de référence suffisamment détaillé pour expliquer les règles internes d’un système. Il peut utiliser des mathématiques, du pseudocode, des diagrammes d’état et des définitions formelles. Pour replacer ces notions dans leur contexte, le glossaire crypto de Bref Crypto explique blockchain, consensus, transaction, smart contract et machine virtuelle.

« Yellow Paper » n’est pas un label réglementé ni un format universel. Certains projets parlent de spécification, de documentation protocolaire ou de papier technique. Le nom est surtout devenu connu grâce au document formel d’Ethereum rédigé à l’origine par Gavin Wood.

Yellow Paper, whitepaper et documentation : les différences

Le whitepaper présente la vision

Un whitepaper explique généralement le problème, la solution, l’architecture, l’économie du token et la feuille de route. Il peut s’adresser aux utilisateurs, partenaires et investisseurs. Son niveau de détail varie fortement et son contenu peut inclure une dimension commerciale.

Le Yellow Paper formalise les règles

Le Yellow Paper cherche à lever les ambiguïtés. Il définit les objets manipulés, les entrées, les sorties et les transitions entre deux états. Une implémentation conforme devrait produire le résultat prévu pour les mêmes données initiales.

La documentation aide à utiliser et développer

Les guides développeurs, références d’API et tutoriels expliquent comment interagir avec le système. Ils sont souvent plus lisibles et plus fréquemment mis à jour qu’un document académique. La meilleure documentation relie spécification, code, tests et historique des changements.

Que doit contenir une bonne spécification technique ?

• Périmètre et hypothèses : ce que le document couvre, les versions concernées et les éléments volontairement exclus.
• Modèle d’état : comptes, soldes, stockage et informations nécessaires pour représenter le réseau à un instant donné.
• Format des transactions : champs, signatures, validité et ordre d’exécution.
• Transitions d’état : règles qui transforment l’état initial en état final après une opération.
• Consensus et validation : conditions selon lesquelles un bloc ou une transaction est accepté.
• Calcul des ressources : frais, gas, limites d’exécution et prévention des boucles infinies.
• Cryptographie : fonctions de hachage, signatures et preuves utilisées, avec leurs paramètres.
• Erreurs et cas limites : comportement en cas d’entrée invalide, dépassement ou conflit.
• Version et historique : date, numéro de révision, mises à niveau intégrées et changements en attente.

Un bon document permet de relier chaque règle à une partie du code ou à un test. Une formule élégante sans implémentation, sans exemples et sans version identifiable reste difficile à vérifier.

L’exemple du Yellow Paper d’Ethereum

Le Yellow Paper d’Ethereum formalise notamment l’état de la blockchain, les transactions, le gas et l’exécution de la machine virtuelle Ethereum. Il emploie une notation mathématique afin de décrire le résultat attendu avec le moins d’ambiguïté possible.

Cette référence montre aussi la principale limite d’un document figé. Le dépôt officiel indique que la version publiée ne couvre pas toutes les mises à niveau récentes et renvoie vers des spécifications d’exécution maintenues en parallèle. Un lecteur doit donc commencer par vérifier la version du réseau décrite. La documentation Ethereum propose un tutoriel de lecture des spécifications de l’EVM qui relie les symboles aux concepts de programmation.

Comment lire un Yellow Paper étape par étape ?

1. Identifier la version : date, commit, mise à niveau du réseau et branche de référence.
2. Lire le résumé et le périmètre : comprendre ce que le document cherche à spécifier.
3. Créer un lexique : noter chaque symbole, ensemble, fonction et abréviation.
4. Repérer le modèle d’état : identifier les données qui décrivent le système avant une opération.
5. Suivre une transaction simple : entrée, vérifications, frais, exécution et nouvel état.
6. Relier les règles au code : rechercher l’implémentation correspondante dans le client officiel.
7. Comparer avec les tests : vérifier les cas normaux, erreurs et limites.
8. Consulter l’historique : propositions d’amélioration, correctifs et spécifications plus récentes.

Il n’est pas nécessaire de comprendre toutes les équations à la première lecture. Pour un analyste non développeur, l’objectif peut être plus ciblé : vérifier que le modèle est défini, que les hypothèses sont explicites et que l’équipe maintient une documentation cohérente avec son code.

Comment vérifier que le code respecte le document ?

• Comparer les versions de la spécification et du logiciel exécuté.
• Repérer les liens entre règles, modules du code et tests de conformité.
• Vérifier si plusieurs clients indépendants produisent les mêmes résultats.
• Examiner les rapports d’audit, leurs dates, leur périmètre et les correctifs appliqués.
• Lire les propositions de changement et les discussions sur les cas limites.
• Contrôler si des divergences connues sont documentées publiquement.

Un audit n’est pas une garantie permanente. Notre article sur les audits de sécurité rendus rapidement obsolètes rappelle que le code, les dépendances et les menaces évoluent. Le bilan des piratages crypto et DeFi montre également que les incidents proviennent souvent de clés, de contrats ou de composants qui dépassent le seul protocole de base.

Les signaux d’alerte

• document sans date, version ou dépôt vérifiable ;
• formules non définies ou termes techniques utilisés sans précision ;
• absence de lien avec le code et les tests ;
• copie de spécifications d’un autre projet sans adaptation visible ;
• document présenté comme une preuve de sécurité absolue ;
• écart entre la gouvernance décrite et les clés réellement contrôlées par l’équipe ;
• spécification ancienne alors que le réseau a subi plusieurs mises à niveau.

Le guide sur Bitcoin constitue un bon point de comparaison pour distinguer règles de protocole, fonctionnement du réseau et usages économiques. Deux projets peuvent utiliser le mot blockchain tout en faisant des choix très différents.

À retenir

Le Yellow Paper est une carte technique, pas un certificat de qualité. Il permet de comprendre ce que le protocole est censé faire et fournit une base utile pour l’implémentation et les audits. Sa valeur dépend toutefois de sa précision, de sa version, de son lien avec le code et de sa maintenance. Avant de lui faire confiance, il faut toujours vérifier la date, les changements du réseau et les tests de conformité.

Ce contenu est fourni à titre pédagogique et ne constitue pas un conseil financier.