Décimales ERC-20 : comprendre les unités brutes et l’affichage

Le paramètre decimals d’un jeton ERC-20 indique comment passer d’un montant entier en unités brutes à un nombre lisible dans une interface. Le principe est une conversion d’échelle : le montant brut est divisé par dix élevé à la puissance indiquée par decimals. Pour interpréter correctement le résultat, il faut connaître la valeur propre au jeton concerné.

Deux questions doivent donc rester distinctes : le jeton fournit-il cette métadonnée facultative, et quelle valeur son implémentation utilise-t-elle ? Le nombre 18, employé par défaut dans l’implémentation ERC20 d’OpenZeppelin, ne répond pas à ces questions pour tous les jetons. Voici comment comprendre la conversion, vérifier ses hypothèses et conserver ses limites.

Ce que définit le paramètre decimals

La norme EIP-20 présente decimals() comme une méthode qui fournit le nombre de décimales utilisé pour obtenir la représentation destinée à l’utilisateur. Elle précise que cette méthode est facultative. Les interfaces et les autres contrats ne doivent donc pas supposer qu’elle est présente.

Cette précision est essentielle : connaître la formule de conversion ne suffit pas si l’un de ses paramètres manque. Une valeur choisie par habitude permet de calculer un résultat, mais elle ne permet pas d’établir que ce résultat représente correctement le montant du jeton étudié.

Pour raisonner clairement, conservez deux descriptions du même montant : le nombre entier d’unités brutes et sa représentation après application de l’échelle. Le paramètre decimals relie ces deux descriptions. Il ne demande pas au contrat de tenir ses comptes avec des fractions d’unité brute.

Dans les expressions ci-dessous, 10 ** decimals signifie « dix élevé à la puissance decimals ». Avec une valeur de 4, le facteur d’échelle est donc 10 000. Le calcul reste incomplet tant que la valeur utilisée n’est pas rattachée au jeton concerné.

Unités brutes et montant affiché : deux lectures du même nombre

Le guide ERC-20 d’OpenZeppelin explique cette distinction à partir d’une comptabilité en nombres entiers. Dans le fonctionnement décrit, les calculs internes au contrat portent sur des entiers. Les interfaces, notamment les portefeuilles, doivent ajuster la présentation selon decimals.

La relation s’écrit ainsi : montant affiché = montant brut / (10 ** decimals). Le résultat est une autre manière d’exprimer le montant fourni en entrée. Il ne constitue pas un nouveau solde créé par la division.

La présence d’une virgule à l’écran ne signifie donc pas que la comptabilité décrite utilise des fractions d’unité brute. C’est la conversion d’échelle qui permet de présenter un entier sous une forme décimale plus facile à lire.

Il faut aussi distinguer la responsabilité d’une interface de la vérification de son affichage. La documentation explique que l’interface doit appliquer cette conversion ; elle ne démontre pas qu’une application particulière a retenu la bonne valeur. Pour examiner un montant, cherchez les deux données qui rendent le calcul explicable : l’entier brut et le nombre de décimales utilisé.

Un exemple hypothétique, étape par étape

Imaginons un jeton fictif dont le paramètre decimals vaut 4, ainsi qu’un compte fictif contenant 1 234 500 unités brutes. Ces données sont inventées pour expliquer le calcul. Elles ne décrivent ni un contrat déployé, ni un compte réel, ni une transaction effectuée.

1. Relever la valeur supposée de decimals : 4.
2. Calculer le facteur d’échelle : 10 ** 4 = 10000.
3. Diviser le montant brut par ce facteur : 1234500 / 10000 = 123,45.
4. Présenter le résultat comme 123,45 jetons affichés, tout en conservant l’entier brut 1234500.

Le résultat est une déduction de la formule et des hypothèses annoncées. Les deux nombres expriment ici un seul montant, à deux échelles différentes. Écrire les deux formes côte à côte aide à comprendre ce qui a été converti.

Revenir du montant affiché aux unités brutes

En inversant algébriquement la même relation, on obtient : montant brut = montant affiché × (10 ** decimals). Dans cet exemple, multiplier 123,45 par 10 000 redonne 1 234 500.

Cette conversion inverse découle de la formule d’affichage. La comptabilité décrite reposant sur des entiers, une conversion exacte vers les unités brutes exige un résultat entier. Il s’agit d’un contrôle mathématique de la représentation, pas d’une instruction de transfert ni d’une garantie qu’une opération serait exécutée avec succès.

Pourquoi 18 est une valeur par défaut, pas une règle universelle

La référence ERC20 d’OpenZeppelin Contracts 5.x documente une valeur par défaut de 18 pour decimals. Elle précise également qu’un contrat dérivé peut redéfinir la fonction pour renvoyer une autre valeur.

Ces indications concernent cette implémentation. Redéfinir une fonction dans un contrat dérivé relève de sa personnalisation technique. Cela ne signifie pas qu’un utilisateur dispose d’un réglage lui permettant de modifier les décimales d’un jeton déjà déployé.

La déduction à retenir repose sur trois éléments : EIP-20 rend la méthode facultative ; OpenZeppelin utilise 18 par défaut ; cette valeur peut être remplacée dans une implémentation dérivée. La seule mention ERC-20 ne permet donc d’établir ni la présence de decimals(), ni une valeur de 18. Cette déduction explique pourquoi une interprétation doit être propre au jeton, sans déterminer les métadonnées d’un contrat particulier.

Dans un document de travail, séparez ainsi une hypothèse pédagogique, comme celle de notre exemple, d’une information établie pour un jeton précis. Recopier la valeur d’un exemple dans l’analyse d’un autre jeton laisserait ce point sans justification.

Ce que la conversion d’affichage ne change pas

Dans l’implémentation documentée par OpenZeppelin, decimals est une information de présentation. La référence indique qu’elle ne modifie pas les calculs du contrat, notamment ceux associés à balanceOf et à transfer.

Appliquer un diviseur à un montant pour le lire ne met donc pas, à lui seul, le solde brut à jour. De même, effectuer cette conversion n’exécute aucun transfert. Dans notre exemple hypothétique, l’entrée du calcul reste 1 234 500 unités brutes après avoir exprimé ce montant sous la forme 123,45.

Cette explication porte sur la relation d’échelle documentée. Elle n’évalue pas le comportement d’un contrat personnalisé et n’authentifie aucun jeton. Les sources permettent de justifier l’explication ; leur citation ne constitue pas une validation de sécurité d’un contrat particulier.

La lecture d’une opération déjà enregistrée répond à une autre question. Pour approfondir cette démarche distincte, consultez notre guide pour lire une transaction Ethereum dans un explorateur de blocs. Une conversion d’unités ne permet pas, à elle seule, d’établir le résultat d’une transaction.

La liste de vérification pour interpréter un montant

• Noter le montant brut. Conserver l’entier utilisé comme point de départ, sans le confondre avec sa forme affichée.
• Établir la valeur de decimals. Déterminer si cette métadonnée est fournie pour le jeton concerné et quelle valeur est retenue.
• Justifier le paramètre. Ne pas combler une information manquante avec 18 au seul motif qu’OpenZeppelin utilise cette valeur par défaut.
• Montrer la conversion. Diviser le montant brut par 10 ** decimals, puis identifier clairement le résultat comme montant affiché.
• Contrôler le retour aux unités brutes. Multiplier par le même facteur ; une représentation exacte doit redonner un entier.
• Conserver les limites. Le calcul ne prouve ni une modification de solde, ni la réussite d’un transfert, ni l’authenticité du contrat.

Si la valeur propre au jeton reste indéterminée, son interprétation à l’échelle affichée reste elle aussi indéterminée. Dans un processus éditorial, ce point nécessite une vérification humaine, signalée par editorial_review. Une valeur par défaut générique ne résout pas cette incertitude.

Contenu pédagogique préparé avec l’aide de l’IA. L’exemple fictif explique une conversion d’unités et ne recommande aucune transaction réelle.