This module provides Base58 and Base58Check data encoding and decoding functions.

The following alphabets are supported for encoding and decoding, for both Base58 and Base58Check:

• Bitcoin
• Flickr

• Ripple

  Note that IPFS uses the same alphabet as Bitcoin. Since this alphabet appeared in Bitcoin first, it will be referred to hereafter as Bitcoin, though it can be used for encoding and decoding data from IPFS without issue.

Overview

Base58 is a Base58 and Base58Check library that tries to make pragmatic compromises, while maintaining best practices with regard to Elixir and BEAM performance. It has no external dependencies and supports adding additional values with a simple update of an internal map.

Additionally, B58 encodes and decodes data in a consistent manner - plain binary in, plain binary out. No additional steps, clever hacks, or assumptions are made with regard to input and output. Furthermore, the library is relatively consistent with the approach taken in the Elixir core Base library.

In cases where exceptions may be more common, ! suffixed functions are provided, ex: base58_decode vs base58_decode!.

Base58Check data also supports two versions of encoding and decoding respectively. Version binaries are assumed to be input and output via functions prefixed with version, ex: version_encode58_check!/2. A versioned binary can also be created using version_binary/2. Version arguments are also consistently arranged so that they may be easily piped using Elixir. Unversioned binaries may also be encoded and decoded and simply use the same pattern of functions without the version prefix in the name, ex: encode58_check!.

Ensure that when encoding and decoding, you use the appropriate alphabet. For example, if you encode using the Flickr alphabet, decode using the same alphabet. If you do not control encoding, ensure you know up-front what alphabet is used. Base58 will often decode using the incorrect alphabet without an error, but produce wrong results. Base58Check on the other hand will typically fail up-front due to the checksum being incorrect. It is thus possible, but not advisable to try to brute-force detect the alphabet for Base58Check using the alphabets/0 function with a reduce_while/3 function as a last resort.

Ensure the Erlang “crypto” module is installed. There are some OS distributions that do not include this.

Why Base58 Encoding

The most compelling reason to use Base58 is if you are using or interfacing any technology that already uses it. This includes various crypto-currencies such as Bitcoin, Blockchain-based experiments, various distributed systems, IPFS, Flickr URLs, and many more.

Generally, you can also decide to use Base58 if you want an unambiguous encoding that is less prone to errors when read by a human. Moreover, you can use Base58Check when you need to checksum and/or version your data.

Taken from the original Bitcoin source code:

Why base-58 instead of standard base-64 encoding?
  - Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking account numbers.
  - A string with non-alphanumeric characters is not as easily accepted as an account number.
  - E-mail usually won't line-break if there's no punctuation to break at.
  - Double-clicking selects the whole number as one word if it's all alphanumeric.

Base58Check Encoding

The following features are outlined per the bitcoin wiki regarding Base58Check:

  * An arbitrarily sized payload.
  * A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
  * One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
  * Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
  * An extra step for preservation of leading zeroes in the data.

## Base58Check vs Base58 Encoding

You should use Base58Check over Base58 encoding if any of the features it presents are appealing to you. Perhaps the most compelling reason to use Base58Check, however, is the ability to version data and embed a checksum.

Generally, Base58 should perform better as Base58Check is a layer on top of Base58. The checksum in Base58Check, however, will usually prevent accidental decoding using the wrong alphabet.

Why Not Base58 or Base58Check

Base58 and Base58Check are suitable and desirable for many reasons ranging from protection from character ambiguity to checksums to real-world software usage. Nevertheless, there are several considerations you should evaluate before selecting Base58 or Base58Check.

Among the reasons not to use Base58 or Base58Check include:

• Speed

  • Usage of div and mod. Both these operations are slow, especially in Elixir. Many other encodings are not performance limited by these operations and thus faster.
  • It may be possible to gain more speed using a technique where div and mod (divmod) together are replaced with a CRC + table approach to avoid the overhead. This is more readily doable in C or C++. It is not clear whether doing this in Elixir has benefits nor if it is worth it in terms of stability and performance doing so via a NIF.
  • Base58Check introduces additional overhead via sha-256, extra binary manipulation, and checksum verification during decoding.

• Dynamic alphabets

  • Base58 is not as amenable to dynamic alphabets. This library also intentionally ignores this constraint. The main reason is that there are some characters that are counter to the goals of Base58.
  • Losing performance to support a dynamic alphabet is probably not a tradeoff you should be making. Note that dynamic alphabets that follow the guidelines of existing alphabets can be added with a simple compile-time updates of this library.

• Payload size

  • Some encodings may produce a smaller payload size relative to the source data.
  • You can compress a Base58 payload, but it is not an inherent goal of the algorithm itself.

Selecting an Alphabet

You should select an alphabet that aligns with your inteded use-cases. If in doubt, start with the bitcoin (:btc) alphabet. For usage with URLs such as shorteners or parameters, the Flickr (:flickr) alphabet has seen some real-world usage and is thus worth considering.

If you need to add an alphabet, it is suggested to do so at compile time by updating the alphabet_meta map found in the source. It is strongly advised to use an existing alphabet, however.

Base58 Bitcoin Alphabet

| Value | Encoding | Value | Encoding | Value | Encoding | Value | Encoding |
|------:|---------:|------:|---------:|------:|---------:|------:|---------:|
|      0|         1|     17|         J|     34|         b|     51|         t|
|      1|         2|     18|         K|     35|         c|     52|         u|
|      2|         3|     19|         L|     36|         d|     53|         v|
|      3|         4|     20|         M|     37|         e|     54|         w|
|      4|         5|     21|         N|     38|         f|     55|         x|
|      5|         6|     22|         P|     39|         g|     56|         y|
|      6|         7|     23|         Q|     40|         h|     57|         z|
|      7|         8|     24|         R|     41|         i|       |          |
|      8|         9|     25|         S|     42|         j|       |          |
|      9|         A|     26|         T|     43|         k|       |          |
|     10|         B|     27|         U|     44|         m|       |          |
|     11|         C|     28|         V|     45|         n|       |          |
|     12|         D|     29|         W|     46|         o|       |          |
|     13|         E|     30|         X|     47|         p|       |          |
|     14|         F|     31|         Y|     48|         q|       |          |
|     15|         G|     32|         Z|     49|         r|       |          |
|     16|         H|     33|         a|     50|         s|       |          |

Base58 Flickr Alphabet

| Value | Encoding | Value | Encoding | Value | Encoding | Value | Encoding |
|------:|---------:|------:|---------:|------:|---------:|------:|---------:|
|      0|         1|     17|         i|     34|         A|     51|         T|
|      1|         2|     18|         j|     35|         B|     52|         U|
|      2|         3|     19|         k|     36|         C|     53|         V|
|      3|         4|     20|         m|     37|         D|     54|         W|
|      4|         5|     21|         n|     38|         E|     55|         X|
|      5|         6|     22|         o|     39|         F|     56|         Y|
|      6|         7|     23|         p|     40|         G|     57|         Z|
|      7|         8|     24|         q|     41|         H|       |          |
|      8|         9|     25|         r|     42|         J|       |          |
|      9|         a|     26|         s|     43|         K|       |          |
|     10|         b|     27|         t|     44|         L|       |          |
|     11|         c|     28|         u|     45|         M|       |          |
|     12|         d|     29|         v|     46|         N|       |          |
|     13|         e|     30|         w|     47|         P|       |          |
|     14|         f|     31|         x|     48|         Q|       |          |
|     15|         g|     32|         y|     49|         R|       |          |
|     16|         h|     33|         z|     50|         S|       |          |

Base58 Ripple Alphabet

| Value | Encoding | Value | Encoding | Value | Encoding | Value | Encoding |
|------:|---------:|------:|---------:|------:|---------:|------:|---------:|
|      0|         r|     17|         J|     34|         b|     51|         t|
|      1|         p|     18|         K|     35|         c|     52|         u|
|      2|         s|     19|         L|     36|         d|     53|         v|
|      3|         h|     20|         M|     37|         e|     54|         A|
|      4|         n|     21|         4|     38|         C|     55|         x|
|      5|         a|     22|         P|     39|         g|     56|         y|
|      6|         f|     23|         Q|     40|         6|     57|         z|
|      7|         3|     24|         R|     41|         5|       |          |
|      8|         9|     25|         S|     42|         j|       |          |
|      9|         w|     26|         T|     43|         k|       |          |
|     10|         B|     27|         7|     44|         m|       |          |
|     11|         U|     28|         V|     45|         8|       |          |
|     12|         D|     29|         W|     46|         o|       |          |
|     13|         N|     30|         X|     47|         F|       |          |
|     14|         E|     31|         Y|     48|         q|       |          |
|     15|         G|     32|         Z|     49|         i|       |          |
|     16|         H|     33|         2|     50|         1|       |          |

References

• Base58
• Base58Check
• Base58 Flickr
• Elixir Base Module
• Ripple Github
• Bitcoin Base58 Implementation
• Erlang Crypto Module