Base16, Base32, Base45, Base58, Base62, Base85 encoding/decoding library
$ dotnet add package SimpleBaseThis is my own take for exotic base encodings like Base32, Base58 and Base85. I started to write it in 2013 as coding practice and kept it as a small pet project. I suggest anyone who wants to brush up their coding skills to give those encoding problems a shot. They turned out to be more challenging than I expected. To grasp the algorithms I had to get a pen and paper to see how the math worked.
SoapHexBinary.Parse although
.NET has method since .NET 5.Convert.FromHexString()To install it from NuGet:
Install-Package SimpleBase
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 flavorsDecode a Base32-encoded string:
using SimpleBase;
string myText = ...
byte[] result = Base32.Crockford.Decode(myText);Encode a byte array:
byte[] myBuffer = ...
string result = Base58.Bitcoin.Encode(myBuffer);
// you can also use "Ripple" or "Flickr" as encoder flavorsDecode 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 bufferAvalanche 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 bufferEncode a byte array to Ascii85 string:
byte[] myBuffer = ...
string result = Base85.Ascii85.Encode(myBuffer);
// you can also use Z85 as a flavorDecode 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.
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 lowercaseTo decode a valid hex string:
string text = ...
byte[] result = Base16.Decode(text); // decodes both upper and lowercaseMost 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);
}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);
}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!
}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!
}Small buffer sizes are used (64 characters). They are closer to real life applications. Base58 performs really bad in decoding of larger buffer sizes, due to polynomial complexity of numeric base conversions.
BenchmarkDotNet v0.14.0, Windows 11 (10.0.26100.3915) AMD Ryzen 9 5950X, 1 CPU, 32 logical and 16 physical cores .NET SDK 9.0.203 [Host] : .NET 8.0.15 (8.0.1525.16413), X64 RyuJIT AVX2 DefaultJob : .NET 8.0.15 (8.0.1525.16413), X64 RyuJIT AVX2
Encoding (64 byte buffer)
| Method | Mean | Error | StdDev | Gen0 | Allocated |
|---|---|---|---|---|---|
| DotNet_Base64 | 28.04 ns | 0.592 ns | 0.810 ns | 0.0120 | 200 B |
| SimpleBase_Base16_UpperCase | 85.42 ns | 1.732 ns | 1.779 ns | 0.0167 | 280 B |
| SimpleBase_Base32_CrockfordWithPadding | 153.34 ns | 2.456 ns | 2.297 ns | 0.0138 | 232 B |
| SimpleBase_Base85_Z85 | 149.08 ns | 1.747 ns | 1.548 ns | 0.0110 | 184 B |
| SimpleBase_Base58_Bitcoin | 46.40 ns | 0.975 ns | 1.302 ns | 0.0091 | 152 B |
| SimpleBase_Base58_Monero | 207.05 ns | 1.854 ns | 1.644 ns | 0.0119 | 200 B |
| SimpleBase_Base62_Default | 43.44 ns | 0.041 ns | 0.032 ns | - | - |
| SimpleBase_Base45_Default | 119.97 ns | 0.585 ns | 0.519 ns | 0.0129 | 216 B |
| SimpleBase_Multibase_Base16_UpperCase | 108.30 ns | 2.170 ns | 3.685 ns | 0.0334 | 560 B |
Decoding (80 character string, except Base45 which must use an 81 character string)
| Method | Mean | Error | StdDev | Gen0 | Gen1 | Allocated |
|---|---|---|---|---|---|---|
| DotNet_Base64 | 103.61 ns | 0.225 ns | 0.188 ns | 0.0052 | - | 88 B |
| SimpleBase_Base16_UpperCase | 49.80 ns | 0.564 ns | 0.527 ns | 0.0038 | - | 64 B |
| SimpleBase_Base16_UpperCase_TextReader | 269.54 ns | 5.402 ns | 12.081 ns | 0.5007 | 0.0153 | 8376 B |
| SimpleBase_Base32_Crockford | 126.17 ns | 0.489 ns | 0.433 ns | 0.0048 | - | 80 B |
| SimpleBase_Base85_Z85 | 253.58 ns | 0.982 ns | 0.871 ns | 0.0052 | - | 88 B |
| SimpleBase_Base58_Bitcoin | 4,499.65 ns | 2.306 ns | 2.044 ns | - | - | 88 B |
| SimpleBase_Base58_Monero | 99.93 ns | 0.444 ns | 0.415 ns | 0.0052 | - | 88 B |
| SimpleBase_Base62_Default | 4,672.89 ns | 6.044 ns | 5.358 ns | - | - | 88 B |
| SimpleBase_Base45_Default | 87.79 ns | 0.935 ns | 0.874 ns | 0.0048 | - | 80 B |
| SimpleBase_Multibase_Base16_UpperCase | 51.84 ns | 0.764 ns | 0.677 ns | 0.0038 | - | 64 B |
| SimpleBase_Multibase_TryDecode_Base16_UpperCase | 55.87 ns | 0.111 ns | 0.099 ns | - | - | - |
I'm sure there are areas for improvement. I didn't want to go further in optimizations which would hurt readability and extensibility. I might experiment on them in the future.
Test suite for Base32 isn't complete, I took most of it from RFC4648. Base58 really lacks a good spec or test vectors needed. I had to resort to using online converters to generate preliminary test vectors.
Base85 tests are also makseshift tests based on what output Cryptii produces. Contribution to missing test cases are greatly appreciated.
It's interesting that I wasn't able to reach .NET Base64's performance with Base16 with a straightforward managed code despite that it's much simpler. I was only able to match it after I converted Base16 to unsafe code with good independent interleaving so CPU pipeline optimizations could take place. Still not satisfied though. Is .NET's Base64 implementation native? Perhaps.
Thanks to all contributors (most up to date is on the GitHub sidebar) who provided patches, and reported bugs.