BaseX

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

GitHub GitHub tag (latest SemVer) GitHub Workflow Status

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 32 | 0123456789ABCDEFGHJKMNPQRSTVWXYZ 32 | ybndrfg8ejkmcpqxot1uwisza345h769 (z-base-32) 36 | 0123456789abcdefghijklmnopqrstuvwxyz 45 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./: 58 | 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz (bitcoin) 58 | 123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ (flickr) 58 | rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz (ripple) 62 | 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ 67 | ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.!~

Installation

Add the dependency to your shard.yml:

dependencies:
  base_x:
    github: wout/base_x

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

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

Contributors

Wout - creator and maintainer

Acknowledgments

This shard pulls inspiration from the following projects:

CrystalDoc.info

base_x