Skip to content
/ base_x Public

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

License

Notifications You must be signed in to change notification settings

wout/base_x

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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
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
  1. 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: