Décimales ERC-20 : transformer un solde brut en quantité lisible

Pour convertir un solde brut ERC-20 en quantité lisible de jetons, divisez l’entier par 10 élevé à la puissance correspondant aux décimales vérifiées du jeton. Faites-le uniquement si la valeur est encore en unités de base brutes. Un portefeuille ou un explorateur peut avoir déjà effectué la conversion.

Par exemple, un solde brut de 1234567 avec 6 décimales représente 1.234567 jeton. Le même entier brut avec 18 décimales représente 0.000000000001234567 jeton. Aucun résultat ne donne une valeur en dollars. Ce sont des exemples arithmétiques hypothétiques, pas des soldes interrogés dans un portefeuille.

Ce que changent les décimales dans la lecture d’un solde

La méthode balanceOf d’un contrat ERC-20 renvoie un entier. La spécification ERC-20 décrit decimals comme l’échelle servant à présenter une quantité de jetons à l’utilisateur. Considérez l’entier comme le nombre des plus petites unités comptables du jeton. Les décimales indiquent à l’affichage où placer le point décimal.

Le calcul est le suivant :

Quantité lisible de jetons = entier brut divisé par (10 élevé à la puissance decimals).

Dans cet article, tous les entiers bruts sont écrits en base 10, sans séparateur de milliers. Une valeur hexadécimale commençant par 0x doit d’abord être décodée en entier. Les lettres et chiffres de cet encodage ne sont pas une quantité décimale de jetons que vous pouvez recopier telle quelle dans cette division.

Voici le même entier hypothétique selon trois échelles différentes :

Entier brut	Décimales	Quantité de jetons
1234567	6	1.234567
1234567	18	0.000000000001234567
1234567	0	1234567

Avec 0 décimale, le diviseur est 1. Avec 6 décimales, un jeton entier correspond à 1000000 unités brutes. Avec 18, il correspond à 1000000000000000000 unités brutes. La taille de l’entier ne permet pas à elle seule de déterminer l’échelle applicable.

Établissez l’échelle avant le calcul

Commencez par le réseau et l’adresse complète du contrat du jeton. Un symbole est une étiquette, pas un identifiant unique. Si vous hésitez entre l’adresse du jeton et celle du détenteur, consultez d’abord le guide de l’adresse de portefeuille et du contrat de jeton.

Utilisez les informations officielles de déploiement du projet pour ce réseau afin d’établir l’identité du contrat. Consultez ensuite son résultat decimals en lecture seule via un explorateur ou un lecteur de contrat fiable. Notez le résultat avec le contrat et le réseau. Des métadonnées lues sur un autre déploiement ne déterminent pas l’échelle de votre avoir.

Ne remplacez pas une valeur decimals manquante par 18. ERC-20 rend la méthode facultative. La référence ERC20 d’OpenZeppelin documente une valeur par défaut de 18 dans son implémentation, qui peut être redéfinie. Ce défaut d’implémentation n’est pas une règle universelle des jetons. La même référence explique que les décimales servent à l’affichage. Elles ne changent pas l’arithmétique entière du contrat pour les soldes et transferts.

Si la lecture échoue, distinguez une source indisponible d’un contrat qui n’expose pas de métadonnées utilisables. Essayez une source fiable pour le même déploiement ou vérifiez son implémentation documentée. Si l’échelle reste indéterminée, conservez l’entier brut et marquez la quantité lisible comme non résolue. Un nombre plausible n’est pas une conversion vérifiée.

Vérifiez si le nombre est déjà formaté

Avant d’appliquer la formule, lisez le libellé du champ et la documentation de la source. Un résultat brut de contrat, une quantité normalisée d’API et un affichage arrondi de portefeuille peuvent décrire différemment le même avoir. Un point décimal suggère un formatage, mais son absence ne prouve pas que la valeur est brute : une quantité formatée peut être exactement de 2 jetons.

Pour un jeton hypothétique à 6 décimales, la valeur brute 2500000 devient 2.5 jetons. Si votre portefeuille affiche déjà 2.5 jetons, diviser ce nombre affiché par 1000000 donne 0.0000025, soit une seconde conversion incorrecte.

Une fois la quantité exacte obtenue, appliquez séparément l’arrondi d’affichage. La valeur brute 1 avec 6 décimales correspond à 0.000001 jeton. Une interface limitée à 4 chiffres après le point peut afficher 0.0000. Ce libellé arrondi ne prouve pas un solde vide. Gardez le résultat précis accessible lors de l’étude d’un écart, sans inventer de chiffres significatifs supplémentaires au-delà de la précision de la source.

Pour un script ou un tableur, conservez l’entier brut comme texte ou entier exact jusqu’au formatage. Les grands entiers peuvent perdre en précision dans un Number JavaScript ordinaire, comme l’explique la référence MDN sur les entiers sûrs. La division ne restaure pas une précision déjà perdue. La documentation ethers v6 propose formatUnits, qui renvoie une chaîne décimale. Passez explicitement les décimales vérifiées et conservez cette chaîne au lieu de la transformer en nombre imprécis par commodité.

Rapprochez deux lectures sans déplacer de jetons

Utilisez un seul avoir pour cette vérification. Lire les données publiques d’un contrat ne nécessite ni transfert, ni approbation, ni phrase de récupération, ni signature du portefeuille.

1. Fixez l’identité. Notez le réseau, l’adresse publique du détenteur et le contrat vérifié du jeton. Ne remplacez pas l’adresse du détenteur par celle du contrat pour lire son solde.
2. Consignez l’observation. Gardez l’heure et le numéro de bloc lorsqu’il est disponible. Préférez des lectures du même bloc. Sinon, un transfert entre les observations peut empêcher une correspondance exacte.
3. Étiquetez les entrées. Enregistrez la valeur d’origine, son caractère brut ou formaté et la preuve des décimales du contrat. Si une source n’explique pas ses unités, arrêtez la conversion à ce stade.
4. Appliquez l’échelle une fois. Convertissez l’entier brut avec ces décimales, en gardant les chiffres exacts avant tout arrondi d’affichage. Laissez telle quelle une quantité déjà fournie en unités de jeton.
5. Comparez les mêmes unités. Comparez cette quantité à celle de l’autre écran avec une précision compatible. Pour un zéro arrondi, demandez plus de détails avant de conclure que le solde brut est nul.
6. Traitez l’écart restant. Si l’identité, l’instantané et les unités concordent, mais que les quantités divergent encore, notez les deux lectures et leurs sources. En cas d’échec d’une source, marquez la lecture indisponible au lieu d’insérer zéro. Le guide des écarts de portefeuille traite les réponses manquantes, les prix et la couverture des positions.

Le résultat utile est un relevé qu’une autre personne peut reproduire : quel contrat, le solde de qui, quelle observation, quelle valeur brute, quelles décimales et quelle quantité convertie. Une transaction ne fait pas partie de la preuve de conversion.

Séparez quantité de jetons et valeur

Le formatage vous donne un nombre de ces jetons. Une estimation en dollars exige aussi un prix pour cet actif exact, dans une devise et à un instant indiqués. Les décimales ne déterminent ni ce prix, ni la liquidité de négociation, ni la sécurité du contrat. Un jeton inconnu peut renvoyer une valeur decimals parfaitement ordinaire.

Un jeton de reçu ou un jeton enveloppé soulève une autre question : quelle quantité d’actif sous-jacent chaque jeton représente-t-il ? Convertir son solde brut donne des jetons de reçu ou enveloppés. Tout équivalent en actif sous-jacent exige la méthode de conversion et les unités du protocole concerné. Les décimales du jeton ne remplacent pas ce taux de change. Un ratio de protocole tel qu’un facteur de santé nécessite sa propre échelle documentée.

Si le nombre semble toujours erroné, conservez l’inconnue pertinente. Des décimales inconnues laissent la quantité lisible non résolue. Une quantité connue avec un prix inconnu laisse la valorisation non résolue. Expliciter ces lacunes donne une prochaine vérification utile sans modifier l’avoir que vous cherchez à comprendre.