Codificador Base58Check

Base58Check é o formato binário para texto do Bitcoin que envolve um payload com um checksum de quatro bytes derivado de SHA-256 duplo e depois codifica a sequência completa com o alfabeto Base58 do Bitcoin. Este codificador Base58Check aceita um payload em hex ou UTF-8 e devolve uma string Base58Check; o decodificador inverte o mapa, recalcula SHA256(SHA256(payload)) e reporta um erro invalid_input claro quando o checksum armazenado não coincide. O caminho é aritmética determinística pura — sem rede, sem sementes aleatórias e sem dependência de relógio — de modo que o executor gratuito do navegador e a API pré-paga devolvem o mesmo JSON sempre.

O que o Base58Check acrescenta ao Base58

O Base58 simples mapeia bytes para cinquenta e oito caracteres inequívocos tratando o payload como um inteiro big-endian e dividindo repetidamente por cinquenta e oito, com o alfabeto Bitcoin que remove o zero, o O maiúsculo, o I maiúsculo e o L minúsculo. Antes de codificar, o codificador calcula o SHA-256 do payload, depois o SHA-256 desse resumo, e anexa os primeiros quatro bytes do hash externo como checksum. O buffer combinado — payload original mais esses quatro bytes — é então codificado em Base58 exatamente como o Base58 bruto, inclusive a convenção de zeros iniciais para uns iniciais. Na decodificação, o processo inverte: a decodificação Base58 produz bytes; os últimos quatro são o checksum reivindicado; o SHA-256 duplo do payload restante deve igualar esses quatro bytes ou a operação falha.

Como chamar a API e o que a resposta contém

Com format utf8, text é codificado como bytes UTF-8 antes do checksum. Envie um corpo JSON com um campo de string obrigatório text (aliases input, value, data e payload), um mode opcional encode ou decode (padrão encode) e um format opcional hex ou utf8 (padrão hex). Espaços no hex são removidos; comprimento ímpar ou dígitos não hex devolvem invalid_input. O mode decode trata text como uma string Base58Check no alfabeto Bitcoin, verifica o checksum de SHA-256 duplo e devolve o payload em hex minúsculo quando format é hex, ou como string UTF-8 quando format é utf8 (payloads binários que não são UTF-8 válido devem usar hex). Em encode bem-sucedido a resposta inclui mode, format, input, result e base58check com a mesma string codificada, payload_hex, checksum_hex, a constante alphabet e alphabet_name bitcoin, payload_bytes, output_length e uma mensagem curta em inglês. Em decode bem-sucedido você também obtém checksum_valid true, input_length e uma mensagem confirmando a verificação. Validação falha — text ausente, hex inválido, mode ou format desconhecido, caracteres Base58 inválidos, payloads curtos demais para o checksum ou mismatch de checksum — devolve invalid_input e nunca é cobrada. O preço é uma tarifa fixa de US$ 0,002 por requisição bem-sucedida com unidade item.

Dicas práticas, vetores clássicos e diferenças do Base58 simples

Use o Base58 simples irmão quando só precisar de conversão de alfabeto sem checksums; use esta capacidade Base58Check quando a integridade importar. Prefira encode quando você tiver um hash com prefixo de versão ou outro payload binário em hex e precisar de uma string segura para colar com integridade; prefira decode quando já tiver uma string tipo endereço Base58Check e precisar recuperar o payload só se o checksum estiver intacto. Testes de fumaça de ida e volta são diretos: codifique o payload hex conhecido 00010966776006953D5567439E5E39F86A0D273BEE, confirme o resultado 16UwLL9Risc3QfPqBUvKofHmBQ7wMtjvM, decodifique essa string e confirme payload_hex e checksum_hex d61967f6. Altere de propósito o último caractere de uma string válida e afirme que o cliente trata invalid_input com uma mensagem que nomeia os checksums de quatro bytes recebido e esperado. Mantenha requisições abaixo do limite de caracteres publicado; payloads extremamente longos expandem como inteiros grandes e é melhor dividi-los offline. Tarefas falhas que devolvem invalid_input não consomem saldo pré-pago, o que mantém scripts exploratórios baratos ao testar checksums ruins. Ao ensinar, mostre o mesmo payload codificado com e sem checksum para que alunos vejam por que strings no estilo Bitcoin são mais longas e por que um erro de um caractere quase sempre falha de forma fechada em vez de abrir a carteira errada.