Casas decimais ERC-20: transforme um saldo bruto em quantidade legível

Para converter um saldo bruto ERC-20 em uma quantidade legível de tokens, divida o inteiro por 10 elevado às casas decimais verificadas do token. Faça isso somente se o valor ainda estiver em unidades básicas brutas. Uma carteira ou um explorador pode já ter feito a conversão.

Por exemplo, um saldo bruto de 1234567 com 6 casas decimais representa 1.234567 tokens. O mesmo inteiro bruto com 18 casas decimais representa 0.000000000001234567 tokens. Nenhum resultado informa um valor em dólares. São exemplos aritméticos hipotéticos, não saldos consultados em uma carteira.

O que as casas decimais mudam na leitura de um saldo

O método balanceOf de um contrato ERC-20 retorna um inteiro. A especificação ERC-20 descreve decimals como a escala para apresentar uma quantidade de tokens ao usuário. Pense no inteiro como uma contagem das menores unidades contábeis do token. As casas decimais dizem à exibição onde colocar o ponto decimal.

O cálculo é:

Quantidade legível de tokens = inteiro bruto dividido por (10 elevado a decimals).

Neste artigo, todos os inteiros brutos estão escritos na base 10, sem separadores de milhar. Um valor hexadecimal começando com 0x precisa primeiro ser decodificado como inteiro. As letras e os algarismos dessa codificação não são uma quantidade decimal de tokens que você pode copiar sem alterações para esta divisão.

Veja o mesmo inteiro hipotético com três escalas diferentes:

Inteiro bruto	Casas decimais	Quantidade de tokens
1234567	6	1.234567
1234567	18	0.000000000001234567
1234567	0	1234567

Com 0 casas decimais, o divisor é 1. Com 6, um token inteiro corresponde a 1000000 unidades brutas. Com 18, corresponde a 1000000000000000000 unidades brutas. O tamanho do inteiro sozinho não informa qual escala se aplica.

Determine a escala antes de calcular

Comece pela rede e pelo endereço completo do contrato do token. Um símbolo é um rótulo, não um identificador único. Se não souber qual endereço pertence ao token e qual ao titular, use primeiro o guia de endereço de carteira e contrato de token.

Use as informações oficiais de implantação do projeto nessa rede para determinar a identidade do contrato. Depois consulte o resultado de somente leitura de decimals por um explorador ou leitor de contratos confiável. Registre o resultado junto com o contrato e a rede. Metadados lidos de outra implantação não determinam a escala da sua posição.

Não preencha um decimals ausente com 18. O ERC-20 torna o método opcional. A referência ERC20 da OpenZeppelin documenta um padrão de 18 em sua implementação, que pode ser sobrescrito. Esse padrão de implementação não é uma regra universal para tokens. A mesma referência explica que as casas decimais servem à formatação da exibição e não alteram a aritmética inteira de saldos e transferências do contrato.

Se a leitura falhar, diferencie uma fonte indisponível de um contrato que não expõe metadados utilizáveis. Tente uma fonte confiável para a mesma implantação ou confira sua implementação documentada. Se a escala continuar indeterminada, preserve o inteiro bruto e marque a quantidade legível como não resolvida. Um número aparentemente plausível não é uma conversão verificada.

Confira se o número já está formatado

Antes de aplicar a fórmula, leia o rótulo do campo e a documentação da fonte. Um resultado bruto do contrato, uma quantidade normalizada de API e uma exibição arredondada da carteira podem descrever a mesma posição de maneiras diferentes. Um ponto decimal sugere formatação, mas sua ausência não prova que o valor seja bruto: uma quantidade formatada pode ser exatamente 2 tokens.

Para um token hipotético com 6 casas decimais, o valor bruto 2500000 vira 2.5 tokens. Se sua carteira já mostra 2.5 tokens, dividir esse número exibido por 1000000 produz 0.0000025, uma segunda conversão incorreta.

Depois de obter a quantidade exata de tokens, aplique separadamente o arredondamento de exibição. O valor bruto 1 com 6 casas decimais é 0.000001 tokens. Uma interface limitada a 4 casas após o ponto pode mostrar 0.0000. Esse rótulo arredondado não comprova um saldo vazio. Mantenha o resultado preciso disponível ao investigar uma divergência, sem inventar algarismos significativos adicionais além da precisão da fonte.

Para um script ou uma planilha, preserve o inteiro bruto como texto ou inteiro exato até a formatação. Inteiros grandes podem perder precisão em um Number comum do JavaScript, como explica a referência da MDN sobre inteiros seguros. A divisão não recupera a precisão já perdida. A documentação do ethers v6 fornece formatUnits, que retorna uma string decimal. Passe explicitamente as casas decimais verificadas e mantenha essa string em vez de convertê-la em um número impreciso por conveniência.

Concilie duas leituras sem movimentar tokens

Use uma mesma posição para a conferência. Ler dados públicos do contrato não exige transferência, aprovação, frase de recuperação nem assinatura da carteira.

1. Fixe a identidade. Registre a rede, o endereço público do titular e o contrato verificado do token. Não substitua o titular pelo endereço do contrato ao consultar seu saldo.
2. Registre a observação. Guarde o horário e o número do bloco, quando disponível. Prefira leituras do mesmo bloco. Caso contrário, uma transferência entre as observações pode impedir uma correspondência exata.
3. Identifique as entradas. Salve o valor original, se é bruto ou formatado, e a evidência das casas decimais do contrato. Se uma fonte não explicar suas unidades, pare a conversão nesse ponto.
4. Ajuste a escala uma vez. Converta o inteiro bruto usando essas casas decimais, mantendo os algarismos exatos antes de qualquer arredondamento de exibição. Deixe como está uma quantidade já fornecida em unidades do token.
5. Compare unidades iguais. Compare essa quantidade de tokens com a da outra tela com precisão compatível. Para um zero arredondado, peça mais detalhes antes de concluir que o saldo bruto é zero.
6. Trate a diferença restante. Se identidade, instante observado e unidades coincidirem, mas as quantidades continuarem divergindo, registre as duas leituras e suas fontes. Se uma fonte falhou, marque a leitura como indisponível em vez de inserir zero. O guia de divergências do portfólio aborda respostas ausentes, preços e cobertura de posições.

O resultado útil é um registro que outra pessoa possa reproduzir: qual contrato, saldo de quem, qual observação, qual valor bruto, quais casas decimais e qual quantidade convertida. Uma transação não faz parte da comprovação da conversão.

Separe a quantidade de tokens do valor

A formatação fornece uma contagem desse token. Uma estimativa em dólares também precisa de um preço para esse ativo exato, em uma moeda e um momento declarados. As casas decimais não estabelecem esse preço, a liquidez de negociação nem a segurança do contrato. Um token desconhecido pode retornar um valor de decimals perfeitamente comum.

Um token de recibo ou um token encapsulado traz outra pergunta: quanto do ativo subjacente cada token representa? Converter seu saldo bruto fornece tokens de recibo ou encapsulados. Qualquer equivalente no ativo subjacente precisa do método de conversão e das unidades do protocolo correspondente. As casas decimais do token não substituem essa taxa de câmbio, e uma razão do protocolo como o fator de saúde precisa de sua própria escala documentada.

Se o número continuar parecendo errado, preserve a incógnita relevante. Casas decimais desconhecidas deixam a quantidade legível não resolvida. Uma quantidade conhecida com preço desconhecido deixa a avaliação não resolvida. Manter essas lacunas explícitas oferece uma próxima verificação útil sem alterar a posição que você está tentando entender.