BaseX

A Crystal shard for base encoding/decoding of any given alphabet with optional bitcoin-style leading zero compression.

A note on performance

Because this library also decodes to integers, it relies on BigInt, which implies a significant performance impact. If you are looking to decode/encode base58 and you don't need to decode to integers, wyhaines/base58.cr is a better alternative as it's a lot faster.

Supported alphabets

Base	Alphabet
2	01
8	01234567
11	0123456789a
26	ABCDEFGHIJKLMNOPQRSTUVWXYZ
26	abcdefghijklmnopqrstuvwxyz (lowercase)
32	ybndrfg8ejkmcpqxot1uwisza345h769 (z-base-32)
36	0123456789abcdefghijklmnopqrstuvwxyz
45	0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:
52	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
58	123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz (bitcoin)
58	123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ (flickr)
58	rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz (ripple)
62	0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
67	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.!~

Installation

1. Add the dependency to your shard.yml:

dependencies:
  base_x:
    github: wout/base_x

2. Run shards install

Usage

require "base_x"

Converting bytes

BaseX::Base58.decode("6hKMCS")
# => Bytes[206, 233, 57, 134]
BaseX::Base58.encode(Bytes[206, 233, 57, 134])
# => "6hKMCS"

or:

BaseX::Base45.decode("5R%/+F5SZ6LLW+J60D")
# => Bytes[231, 5, 88, 240, 215, 89, 21, 180, 87, 179, 227, 86]
BaseX::Base45.encode(Bytes[231, 5, 88, 240, 215, 89, 21, 180, 87, 179, 227, 86])
# => "5R%/+F5SZ6LLW+J60D"

Note: BaseX::BaseXX.decode is the same as BaseX::BaseXX.decode_bytes.

Converting integers

BaseX::Base58.decode_int("6hKMCS")
# => 3471391110
BaseX::Base58.encode(3471391110)
# => "6hKMCS"

Using other alphabets

base_16_alphabet = "0123456789abcdef"
BaseX.decode("ff3300", base_16_alphabet)
# => Bytes[255, 51, 0]
BaseX.encode(Bytes[255, 51, 0], base_16_alphabet)
# => "ff3300"

Leading zeroes

Some protocols, such as Bitcoin, require leading zeros to be encoded. Passing true to the third argument of BaseX::Base58.encode will enable this behaviour.

bitcoin_address_hex = "00000000000000000000123456789ABCDEF0"
bitcoin_address_bytes = String.new(bitcoin_address_hex.hexbytes)

BaseX::Base58.encode(bitcoin_address_bytes, leading_zeroes: true)
# => 111111111143c9JGph3DZ

Development

Make sure you have Guardian.cr installed. Then run:

$ guardian

This will automatically:

• run ameba for src and spec files
• run the relevant spec for any file in the src dir
• run spec a file whenever it's saved

Contributing

1. Fork it (https://github.com/wout/base_x/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Wout - creator and maintainer

Acknowledgments

This shard pulls inspiration from the following projects:

• cryptocoinjs/base-x
• dougal/base58
• russ/base58