Base58 encode and decode

Why Base58 exists

Base58 was written for Bitcoin, to show addresses and keys to people. It is Base64's 64 characters minus six: the look-alikes 0 (zero), O (capital o), I (capital i) and l (small L), and the symbols + and /. What is left is letters and digits only, so a string can be read off a screen without confusing two characters, a double click selects the whole of it, and an email program finds no punctuation to break a line at. Besides Bitcoin, IPFS uses it for its original content identifiers, the ones starting with Qm.

The order is digits, capitals, then small letters, as in ASCII, minus the four look-alikes. So 1 is 0, 9 is 8, A is 9 and z is 57.

How Base58 works: one big number, divided by 58

Base64 and Base32 regroup bits, because 64 and 32 are powers of two. 58 is not, so a Base58 character does not stand for any fixed group of bits. Instead the bytes are read as one large number and written in base 58, by the same repeated division that turns decimal into hex. Here is "Hi":

Because every character depends on the whole number, changing one byte can change characters all through the result. "Hello World!" and "Jello World!" differ only in their first byte:

15 of the 17 Base58 characters differ (underlined), against 1 of the Base64 ones. Dividing a long number again and again also takes time that grows with the square of its length, which is why Base58 is used for short things like addresses and keys, not for files.

Base58Check: the checksum in Bitcoin addresses

A mistyped address must not quietly send money to the wrong place, so Bitcoin adds a checksum before encoding. The bytes are a version byte, the payload, and the first 4 bytes of SHA-256 applied twice to those two. This is the address 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2 taken apart:

SHA-256 of SHA-256 of the version and payload is F415766B5F558AAD59E37332E5C3143402C089A886F1585EE25EC20383F12CD5. Its first 4 bytes, F4 15 76 6B, are the checksum. Change any one character of the address and the number changes, so the checksum no longer matches; a random mistake gets through only about once in 2³² (4.3 billion) tries. Try a one-character mistake.

Version bytes and the first character

The version byte is the most significant part of the number, so it decides which character or two the result can start with (a version byte of 0 is the exception: it is a leading zero byte, so it becomes a 1). These are the common Bitcoin prefixes, with the first characters worked out by encoding the smallest and largest value of each kind:

How long Base58 is

Each character carries log₂ 58 ≈ 5.86 bits, so n bytes need up to about 1.37 × n characters, a little more than Base64's 1.33 × n. The exact length depends on the number, so the table gives the most, for bytes that are all FF.

Common mistakes

• Encoding in pieces, as if it were Base64. Base64 can be cut into groups of 3 bytes and the pieces joined; Base58 cannot, because it is one number. "Hello " and "World!" are d3yC1LKq and kYLPNvXS, but "Hello World!" is 2NEpo7TZRRrLZSi2U. The same reason means one changed byte can change the whole string.
• Dropping the leading zero bytes. The bytes 00 00 48 69 and 48 69 are the same number. Only the leading 1s, 116Wc against 6Wc, tell them apart, so an encoder or decoder that skips them changes the data, and a Bitcoin address loses its version byte.
• Typing 0, O, I or l. They are not in the alphabet, so a string that seems to contain one has been misread. Change the last character of 2NEpo7TZRRrLZSi2U to a capital O and this decoder says: "O" (character 17) is not in the Base58 alphabet. Base58 leaves out 0, O, I and l because they are easy to mistake for each other; did you mean o?
• Confusing Base58 with Base58Check. Plain Base58 has no checksum: a mistyped character still decodes, to different bytes. Only Base58Check, as used for addresses, catches it. Decoding an address with plain Base58 also gives 25 bytes, not the 20-byte payload: the version byte comes first and the 4 checksum bytes last.