Base58 Class

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

Base58.BclAliases.cs

Provides Base58 encoding and decoding of binary data using the Bitcoin/Flickr or Ripple alphabets.

public static class Base58

Inheritance

object

Base58

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Bitcoin/Flickr Base58 (default) - leading zero bytes encode as leading '1' characters.
byte[] data = { 0x00, 0xDE, 0xAD, 0xBE, 0xEF };
string encoded = Base58.Encode(data);

// Ripple alphabet - a permutation used by the XRP ledger.
string ripple = Base58.Encode(data, Base58Variant.Ripple);

// Round-trip.
byte[] roundtrip = Base58.Decode(encoded);

Remarks

Base58 is a non-power-of-two radix (radix 58) used by Bitcoin addresses, IPFS CIDs, Solana, and similar protocols. Because the radix is not a power of two, encoding is performed using big-integer arithmetic rather than the bit-stream technique used by Base16, Base32, and Base64.

Leading zero bytes in the input are encoded as leading alphabet[0] characters (typically 1 in the Bitcoin/Flickr alphabet) so that the byte-level and character-level forms preserve a meaningful prefix.

Base58 has no padding character and no standard decorations. The UpperCase, IncludePrefix, InsertSpacing, InsertLineBreaks, and OmitPadding flags are no-ops. The AllowPrefix and AllowMissingPadding flags are likewise ignored; only IgnoreWhitespace has an effect on decode.

Methods

Decode(char[], int, int, Base58Variant, BaseFormatStyles)

Decodes a portion of a character array into a byte array.

public static byte[] Decode(char[] chars, int offset, int count, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars char[]

The character array.

offset int

The starting offset.

count int

The number of characters.

variant Base58Variant

The Base58 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

The decoded byte array.

Exceptions

ArgumentNullException

Thrown when chars is null.

ArgumentOutOfRangeException

Thrown when offset, count, or variant is out of range.

ArgumentException

Thrown when the segment defined by offset and count exceeds the available range of chars.

FormatException

Thrown when the input is not valid Base58.

Decode(ReadOnlySpan<char>, Base58Variant, BaseFormatStyles)

Decodes a Base58 character span into a byte array.

public static byte[] Decode(ReadOnlySpan<char> chars, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars ReadOnlySpan<char>

The Base58 character span.

variant Base58Variant

The Base58 variant.

style BaseFormatStyles

Parsing styles.

Returns

byte[]

The decoded byte array. Returns Empty<T>() for empty input.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

Thrown when the input is not valid Base58.

Decode(string, Base58Variant, BaseFormatStyles)

Decodes a Base58 string into a byte array using the supplied variant.

public static byte[] Decode(string s, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

s string

The Base58 input.

variant Base58Variant

The Base58 variant.

style BaseFormatStyles

Parsing styles. Only IgnoreWhitespace has effect.

Returns

byte[]

The decoded byte array.

Exceptions

ArgumentNullException

Thrown when s is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

FormatException

Thrown when the input contains characters outside the variant alphabet.

DecodeFromUtf8(ReadOnlySpan<byte>, Span<byte>, out int, out int, Base58Variant, BaseFormatStyles)

Decodes UTF-8 Base58 bytes into a byte span using the OperationStatus return convention.

public static OperationStatus DecodeFromUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesConsumed, out int bytesWritten, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<byte>

The UTF-8 Base58 source.

destination Span<byte>

The destination byte span.

bytesConsumed int

When this method returns, contains the number of source bytes consumed.

bytesWritten int

When this method returns, contains the number of bytes written.

variant Base58Variant

The variant.

styles BaseFormatStyles

Parsing styles.

Returns

OperationStatus

An OperationStatus describing the outcome.

Remarks

Base58 is not a streamable encoding; this overload always treats source as a complete input. NeedMoreData is never returned.

DecodeGuid(ReadOnlySpan<char>, Base58Variant, BaseFormatStyles)

Decodes a Base58 representation of a Guid.

public static Guid DecodeGuid(ReadOnlySpan<char> source, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The Base58 characters.

variant Base58Variant

The Base58 variant.

styles BaseFormatStyles

Parsing styles.

Returns

Guid

The decoded Guid.

Exceptions

FormatException

Thrown when the input does not decode to exactly 16 bytes.

Encode(byte[], Base58Variant)

Encodes bytes into a Base58 string using the supplied variant.

public static string Encode(byte[] bytes, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

bytes byte[]

The bytes to encode.

variant Base58Variant

The Base58 variant.

Returns

string

A Base58 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

Encode(byte[], int, int, Base58Variant)

Encodes a portion of bytes into a Base58 string.

public static string Encode(byte[] bytes, int offset, int count, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

bytes byte[]

The byte array to encode.

offset int

The starting offset.

count int

The number of bytes to encode.

variant Base58Variant

The Base58 variant.

Returns

string

A Base58 string.

Exceptions

ArgumentNullException

Thrown when bytes is null.

ArgumentOutOfRangeException

Thrown when offset, count, or variant is out of range.

ArgumentException

Thrown when the segment defined by offset and count exceeds the available range of bytes.

Encode(Guid, Base58Variant)

Encodes the byte representation of value as a Base58 string. Typical output is 22 characters (radix-58 representation of 16 bytes), though leading zero bytes inflate the count slightly.

public static string Encode(Guid value, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

value Guid

The Guid to encode.

variant Base58Variant

The Base58 variant.

Returns

string

A Base58 string of the GUID bytes (mixed-endian, matching TryWriteBytes(Span<byte>)).

Encode(ReadOnlySpan<byte>, Base58Variant)

Encodes a span of bytes into a Base58 string.

public static string Encode(ReadOnlySpan<byte> bytes, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

variant Base58Variant

The Base58 variant.

Returns

string

A Base58 string. Returns Empty for empty input.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

Encode(ReadOnlySpan<byte>, IBufferWriter<char>, Base58Variant)

Encodes source as Base58 characters into writer, suitable for use in pipelines and other IBufferWriter<T>-based scenarios.

public static int Encode(ReadOnlySpan<byte> source, IBufferWriter<char> writer, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<char>

The buffer writer that receives the encoded characters.

variant Base58Variant

The Base58 variant.

Returns

int

The number of characters written.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

Encode(ReadOnlySpan<byte>, Span<char>, Base58Variant)

Encodes a span of bytes directly into a destination character span.

public static int Encode(ReadOnlySpan<byte> bytes, Span<char> destination, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination span. Must be at least GetMaxEncodedLength(int) characters in size for safe sizing.

variant Base58Variant

The Base58 variant.

Returns

int

The number of characters written.

Exceptions

ArgumentException

Thrown when destination is too small.

ArgumentOutOfRangeException

Thrown when variant is undefined.

EncodeToUtf8(ReadOnlySpan<byte>, Base58Variant)

Encodes source into a UTF-8 Base58 byte array using the supplied variant.

public static byte[] EncodeToUtf8(ReadOnlySpan<byte> source, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

variant Base58Variant

The Base58 variant.

Returns

byte[]

The UTF-8 encoded Base58 bytes.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

EncodeToUtf8(ReadOnlySpan<byte>, IBufferWriter<byte>, Base58Variant)

Encodes source as UTF-8 Base58 bytes into writer, suitable for use in pipelines and other IBufferWriter<T>-based scenarios.

public static int EncodeToUtf8(ReadOnlySpan<byte> source, IBufferWriter<byte> writer, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

writer IBufferWriter<byte>

The buffer writer that receives the UTF-8 bytes.

variant Base58Variant

The Base58 variant.

Returns

int

The number of UTF-8 bytes written.

Exceptions

ArgumentNullException

Thrown when writer is null.

ArgumentOutOfRangeException

Thrown when variant is undefined.

FromBase58String(ReadOnlySpan<byte>)

Decodes UTF-8 Base58 bytes into a byte array using the Bitcoin/Flickr alphabet.

public static byte[] FromBase58String(ReadOnlySpan<byte> utf8Source)

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 Base58 source.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not valid Bitcoin/Flickr Base58.

FromBase58String(ReadOnlySpan<byte>, Span<byte>, out int, out int)

Strict Bitcoin/Flickr Base58 decode from a UTF-8 byte span using the OperationStatus return convention.

public static OperationStatus FromBase58String(ReadOnlySpan<byte> utf8Source, Span<byte> destination, out int bytesConsumed, out int bytesWritten)

Parameters

utf8Source ReadOnlySpan<byte>

The UTF-8 Base58 source.

destination Span<byte>

The destination byte span.

bytesConsumed int

When this method returns, contains the number of source bytes consumed.

bytesWritten int

When this method returns, contains the number of bytes written.

Returns

OperationStatus

An OperationStatus describing the outcome.

FromBase58String(ReadOnlySpan<char>)

Decodes a Base58 character span using the Bitcoin/Flickr alphabet.

public static byte[] FromBase58String(ReadOnlySpan<char> chars)

Parameters

chars ReadOnlySpan<char>

The input span.

Returns

byte[]

The decoded byte array.

Exceptions

FormatException

Thrown when the input is not valid Bitcoin/Flickr Base58.

FromBase58String(ReadOnlySpan<char>, Span<byte>, out int, out int)

Strict Bitcoin/Flickr Base58 decode from a character span using the OperationStatus return convention.

public static OperationStatus FromBase58String(ReadOnlySpan<char> source, Span<byte> destination, out int charsConsumed, out int bytesWritten)

Parameters

source ReadOnlySpan<char>

The character span.

destination Span<byte>

The destination byte span.

charsConsumed int

When this method returns, contains the number of characters consumed.

bytesWritten int

When this method returns, contains the number of bytes written.

Returns

OperationStatus

An OperationStatus describing the outcome.

Remarks

Base58 is not a streamable encoding: isFinalBlock = false would have no useful effect, so the decoder always treats the input as complete and never returns NeedMoreData.

FromBase58String(string)

Decodes s as Bitcoin/Flickr Base58 into a byte array.

public static byte[] FromBase58String(string s)

Parameters

s string

The input.

Returns

byte[]

The decoded byte array.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the input is not valid Bitcoin/Flickr Base58.

GetMaxDecodedLength(int)

Returns an upper bound on the number of bytes that decoding charCount characters can produce.

public static int GetMaxDecodedLength(int charCount)

Parameters

charCount int

The input character count.

Returns

int

An upper bound on the decoded byte count.

Exceptions

ArgumentOutOfRangeException

Thrown when charCount is negative.

GetMaxEncodedLength(int)

Returns an upper bound on the number of characters required to encode byteCount bytes.

public static int GetMaxEncodedLength(int byteCount)

Parameters

byteCount int

The input byte count.

Returns

int

An upper bound on the encoded character count.

Remarks

Because Base58 is a non-power-of-two radix and the exact encoded length depends on the leading-zero count of the input data, this overload returns a worst-case upper bound suitable for buffer sizing. The actual output length is the result of Encode(ReadOnlySpan<byte>, Base58Variant) on the specific data.

Exceptions

ArgumentOutOfRangeException

Thrown when byteCount is negative.

IsBase58Digit(char, Base58Variant)

Indicates whether value is a valid digit for the supplied Base58 variant.

public static bool IsBase58Digit(char value, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

value char

The character to test.

variant Base58Variant

The variant.

Returns

bool

true when the character belongs to the variant alphabet.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

IsValid(ReadOnlySpan<char>, Base58Variant, BaseFormatStyles)

Indicates whether source is a valid Base58 input under the supplied variant.

public static bool IsValid(ReadOnlySpan<char> source, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The character span.

variant Base58Variant

The variant.

styles BaseFormatStyles

Parsing styles. Only IgnoreWhitespace has effect.

Returns

bool

true when the input is no longer than Bodu.Text.Encoding.Base58.MaxDecodeInputLength and every retained character is in the variant alphabet; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

ToBase58String(byte[])

Encodes inArray into a Base58 string using the Bitcoin/Flickr alphabet.

public static string ToBase58String(byte[] inArray)

Parameters

inArray byte[]

The byte array to encode.

Returns

string

A Base58 (Bitcoin/Flickr) string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ToBase58String(byte[], int, int)

Encodes a portion of inArray into a Base58 string using the Bitcoin/Flickr alphabet.

public static string ToBase58String(byte[] inArray, int offset, int length)

Parameters

inArray byte[]

The byte array.

offset int

The starting offset.

length int

The number of bytes to encode.

Returns

string

A Base58 string.

Exceptions

ArgumentNullException

Thrown when inArray is null.

ArgumentOutOfRangeException

Thrown when offset or length is out of range.

ArgumentException

Thrown when the segment defined by offset and length exceeds the available range of inArray.

ToBase58String(ReadOnlySpan<byte>)

Encodes bytes into a Base58 string using the Bitcoin/Flickr alphabet.

public static string ToBase58String(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes.

Returns

string

A Base58 string.

TryDecode(ReadOnlySpan<char>, Span<byte>, out int, Base58Variant, BaseFormatStyles)

Attempts to decode a Base58 character span into a destination byte span.

public static bool TryDecode(ReadOnlySpan<char> chars, Span<byte> destination, out int bytesWritten, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles style = BaseFormatStyles.None)

Parameters

chars ReadOnlySpan<char>

The Base58 character span.

destination Span<byte>

The destination byte span.

bytesWritten int

When this method returns, contains the number of bytes written, or 0 on failure.

variant Base58Variant

The Base58 variant.

style BaseFormatStyles

Parsing styles.

Returns

bool

true on success; false when the input is malformed or the destination is too small.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

TryDecodeGuid(ReadOnlySpan<char>, out Guid, Base58Variant, BaseFormatStyles)

Attempts to decode a Base58 representation of a Guid.

public static bool TryDecodeGuid(ReadOnlySpan<char> source, out Guid value, Base58Variant variant = Base58Variant.BitcoinFlickr, BaseFormatStyles styles = BaseFormatStyles.None)

Parameters

source ReadOnlySpan<char>

The Base58 characters.

value Guid

When this method returns, contains the decoded Guid or Empty.

variant Base58Variant

The Base58 variant.

styles BaseFormatStyles

Parsing styles.

Returns

bool

true when decoding succeeds; otherwise false.

TryEncode(ReadOnlySpan<byte>, Span<char>, out int, Base58Variant)

Attempts to encode a span of bytes into a destination character span.

public static bool TryEncode(ReadOnlySpan<byte> bytes, Span<char> destination, out int charsWritten, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

bytes ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination span.

charsWritten int

When this method returns, contains the number of characters written.

variant Base58Variant

The Base58 variant.

Returns

bool

true when the destination is large enough; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

TryEncodeToUtf8(ReadOnlySpan<byte>, Span<byte>, out int, Base58Variant)

Attempts to encode source as UTF-8 Base58 bytes into destination.

public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, Base58Variant variant = Base58Variant.BitcoinFlickr)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<byte>

The destination UTF-8 byte span.

bytesWritten int

When this method returns, contains the number of bytes written.

variant Base58Variant

The Base58 variant.

Returns

bool

true on success; false when the destination is too small.

Exceptions

ArgumentOutOfRangeException

Thrown when variant is undefined.

TryToBase58String(ReadOnlySpan<byte>, Span<byte>, out int)

Attempts to encode source as a Bitcoin/Flickr Base58 UTF-8 byte span.

public static bool TryToBase58String(ReadOnlySpan<byte> source, Span<byte> utf8Destination, out int bytesWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

utf8Destination Span<byte>

The UTF-8 destination span.

bytesWritten int

When this method returns, contains the number of bytes written.

Returns

bool

true on success; false when the destination is too small.

TryToBase58String(ReadOnlySpan<byte>, Span<char>, out int)

Attempts to encode source as a Bitcoin/Flickr Base58 character span.

public static bool TryToBase58String(ReadOnlySpan<byte> source, Span<char> destination, out int charsWritten)

Parameters

source ReadOnlySpan<byte>

The bytes to encode.

destination Span<char>

The destination character span.

charsWritten int

When this method returns, contains the number of characters written.

Returns

bool

true on success; false when the destination is too small.

Applies to

Product	Versions
.NET	8, 10