Home

Welcome to the SimpleBase wiki!

See full API documentation for details.

Basic encoding/decoding

Here are a few simple usage scenarios:

Base32

Encode a byte array:

using SimpleBase;

byte[] myBuffer;
string result = Base32.Crockford.Encode(myBuffer, padding: true);
// you can also use "ExtendedHex" or "Rfc4648" as encoder flavors

Decode a Base32-encoded string:

using SimpleBase;

string myText = ...
byte[] result = Base32.Crockford.Decode(myText);

Base58

Encode a byte array:

byte[] myBuffer = ...
string result = Base58.Bitcoin.Encode(myBuffer);
// you can also use "Ripple" or "Flickr" as encoder flavors

Decode a Base58-encoded string:

string myText = ...
byte[] result = Base58.Bitcoin.Decode(myText);

Encode a Base58Check address:

byte[] address = ...
byte version = 1; // P2PKH address
string result = Base58.Bitcoin.EncodeCheck(address, version);

Decode a Base58Check address:

string address = ...
Span<byte> buffer = new byte[maxAddressLength];
if (Base58.Bitcoin.TryDecodeCheck(address, buffer, out byte version, out int bytesWritten));
buffer = buffer[..bytesWritten]; // use only the written portion of the buffer

Avalanche CB58 usage is pretty much the same except it doesn't have a separate version field. Just use EncodeCb58 and TryDecodeCb58 methods instead. For encoding:

byte[] address = ...
byte version = 1;
string result = Base58.Bitcoin.EncodeCb58(address);

For decoding:

string address = ...
Span<byte> buffer = new byte[maxAddressLength];
if (Base58.Bitcoin.TryDecodeCb58(address, buffer, out int bytesWritten));
buffer = buffer[..bytesWritten]; // use only the written portion of the buffer

Base85

Encode a byte array to Ascii85 string:

byte[] myBuffer = ...
string result = Base85.Ascii85.Encode(myBuffer);
// you can also use Z85 as a flavor

Decode an encoded Ascii85 string:

string encodedString = ...
byte[] result = Base85.Ascii85.Decode(encodedString);

Both "zero" and "space" shortcuts are supported for Ascii85. Z85 is still vanilla.

Base16

Encode a byte array to hex string:

byte[] myBuffer = ...
string result = Base16.EncodeUpper(myBuffer); // encode to uppercase
// or 
string result = Base16.EncodeLower(myBuffer); // encode to lowercase

To decode a valid hex string:

string text = ...
byte[] result = Base16.Decode(text); // decodes both upper and lowercase

Stream Mode

Most encoding classes also support a stream mode that can work on streams, be it a network connection, a file or whatever you want. They are ideal for handling arbitrarily large data as they don't consume memory other than a small buffer when encoding or decoding. Their syntaxes are mostly identical. Text encoding decoding is done through a TextReader/TextWriter and the rest is read through a Stream interface. Here is a simple code that encodes a file to another file using Base85 encoding:

using (var input = File.Open("somefile.bin"))
using (var output = File.Create("somefile.ascii85"))
using (var writer = new TextWriter(output)) // you can specify encoding here
{
  Base85.Ascii85.Encode(input, writer);
}

Decode works similarly. Here is a Base32 file decoder:

using (var input = File.Open("somefile.b32"))
using (var output = File.Create("somefile.bin"))
using (var reader = new TextReader(input)) // specify encoding here
{
	Base32.Crockford.Decode(reader, output);
}

Asynchronous Stream Mode

You can also encode/decode streams in asynchronous fashion:

using (var input = File.Open("somefile.bin"))
using (var output = File.Create("somefile.ascii85"))
using (var writer = new TextWriter(output)) // you can specify encoding here
{
  await Base85.Ascii85.EncodeAsync(input, writer);
}

And the decode:

using (var input = File.Open("somefile.b32"))
using (var output = File.Create("somefile.bin"))
using (var reader = new TextReader(input)) // specify encoding here
{
	await Base32.Crockford.DecodeAsync(reader, output);
}

TryEncode/TryDecode

If you want to use an existing pre-allocated buffer to encode or decode without causing a GC allocation every time, you can make use of TryEncode/TryDecode methods which receive input, output buffers as parameters.

Encoding is like this:

byte[] input = [1, 2, 3, 4, 5];
int outputBufferSize = Base58.Bitcoin.GetSafeCharCountForEncoding(input);
var output = new char[outputBufferSize];

if (Base58.Bitcoin.TryEncode(input, output, out int numCharsWritten))
{
   // there you go
}

and decoding:

string input = "... some bitcoin address ...";
int outputBufferSize = Base58.Bitcoin.GetSafeByteCountForDecoding(output);
var output = new byte[outputBufferSize];

if (Base58.Bitcoin.TryDecode(input, output, out int bytesWritten))
{
    // et voila!
}

Multibase

In order to encode a Multibase string just specify the encoding you want to use:

byte[] input = [1, 2, 3, 4, 5];
string result = Multibase.Encode(input, MultibaseEncoding.Base32);

When decoding a multibase string, the encoding is automatically detected:

string input = "... some encoded multibase string ...";
byte[] result = Multibase.Decode(input);

If you don't want decoding to raise an exception, use TryDecode() method instead:

string input = "... some encoded multibase string ...";
byte[] output = new byte[outputBufferSize]; // enough the fit the decoded buffer
if (Multibase.TryDecode(input, output, out int bytesWritten))
{
    // et voila!
}