Codificatore Base58Check

Base58Check è il formato da binario a testo di Bitcoin che avvolge un payload con un checksum di quattro byte derivato dal doppio SHA-256 e poi codifica l’intera sequenza con l’alfabeto Base58 di Bitcoin. Questo codificatore Base58Check accetta un payload in hex o UTF-8 e restituisce una stringa Base58Check; il decodificatore inverte la mappa, ricalcola SHA256(SHA256(payload)) e segnala un errore invalid_input chiaro quando il checksum memorizzato non coincide. Il percorso è aritmetica puramente deterministica — senza rete, senza semi casuali e senza dipendenza dall’orologio — così l’esecutore gratuito del browser e l’API prepagata restituiscono sempre lo stesso JSON.

Cosa aggiunge Base58Check rispetto a Base58

Il Base58 semplice proietta i byte su cinquantotto caratteri non ambigui trattando il payload come un intero big-endian e dividendo ripetutamente per cinquantotto, con l’alfabeto Bitcoin che esclude lo zero, la O maiuscola, la I maiuscola e la L minuscola. Prima di codificare, il codificatore calcola lo SHA-256 del payload, poi lo SHA-256 di quel digest e aggiunge i primi quattro byte dell’hash esterno come checksum. Il buffer combinato — payload originale più quei quattro byte — viene quindi codificato in Base58 esattamente come il Base58 grezzo, inclusa la convenzione zero iniziali verso uno iniziali. In decodifica il processo si inverte: la decodifica Base58 produce byte; gli ultimi quattro sono il checksum dichiarato; il doppio SHA-256 del payload restante deve uguagliare quei quattro byte altrimenti l’operazione fallisce.

Come chiamare l’API e cosa contiene la risposta

Con format utf8, text viene codificato come byte UTF-8 prima del checksum. Invii un corpo JSON con un campo stringa obbligatorio text (alias input, value, data e payload), un mode opzionale encode o decode (predefinito encode) e un format opzionale hex o utf8 (predefinito hex). Gli spazi nell’hex vengono rimossi; lunghezza dispari o cifre non hex restituiscono invalid_input. Il mode decode tratta text come una stringa Base58Check sotto l’alfabeto Bitcoin, verifica il checksum a doppio SHA-256 e restituisce il payload in hex minuscolo se format è hex, o come stringa UTF-8 se format è utf8 (i payload binari non UTF-8 validi devono usare hex). In encode riuscito la risposta include mode, format, input, result e base58check con la stessa stringa codificata, payload_hex, checksum_hex, la costante alphabet e alphabet_name bitcoin, payload_bytes, output_length e un breve messaggio in inglese. In decode riuscito ottiene anche checksum_valid a true, input_length e un messaggio che conferma la verifica. Una validazione fallita — text assente, hex errato, mode o format sconosciuti, caratteri Base58 non validi, payload troppo corti per il checksum o mismatch del checksum — restituisce invalid_input e non viene mai addebitata. Il prezzo è una tariffa fissa di $0.002 per richiesta riuscita con unità item.

Consigli pratici, vettori classici e differenze dal Base58 semplice

Usi il Base58 semplice fratello quando le serve solo conversione di alfabeto senza checksum; usi questa capacità Base58Check quando conta l’integrità. Preferisca encode quando ha un hash con prefisso di versione o un altro payload binario in hex e le serve una stringa sicura da incollare con integrità; preferisca decode quando ha già una stringa tipo indirizzo Base58Check e deve recuperare il payload solo se il checksum è intatto. I test di fumo andata e ritorno sono diretti: codifichi il payload hex noto 00010966776006953D5567439E5E39F86A0D273BEE, confermi il risultato 16UwLL9Risc3QfPqBUvKofHmBQ7wMtjvM, decodifichi quella stringa e confermi payload_hex e checksum_hex d61967f6. Alteri deliberatamente l’ultimo carattere di una stringa valida e verifichi che il client gestisca invalid_input con un messaggio che nomina i checksum di quattro byte ricevuto e atteso. Mantenga le richieste sotto il limite di caratteri pubblicato; payload estremamente lunghi si espandono come interi grandi ed è meglio suddividerli offline. Le attività fallite che restituiscono invalid_input non consumano il saldo prepagato, così gli script esplorativi restano economici quando si testano checksum errati. In didattica, mostri lo stesso payload codificato con e senza checksum affinché gli studenti vedano perché le stringhe in stile Bitcoin sono più lunghe e perché un errore di un solo carattere fallisce quasi sempre in modo chiuso invece di aprire il wallet sbagliato.