README
¶
base58
A fast, zero-dependency Base58 encoding library for Go with support for both standard and chunked encoding.
Features
- Standard Base58 — variable-length encoding commonly used for Bitcoin addresses
- Chunked Base58 — fixed-block encoding that splits input into 8-byte chunks, providing O(n) performance instead of O(n²) for large payloads
- Buffer reuse —
EncodeToallows encoding into a caller-provided buffer with zero allocations - Custom alphabets — includes Bitcoin and Flickr alphabets, or create your own with
NewEncoding
Install
go get github.com/KarpelesLab/base58
Usage
Standard encoding
// Encode
encoded := base58.Bitcoin.Encode(data)
// Decode
decoded, err := base58.Bitcoin.Decode(encoded)
// Encode with buffer reuse (zero allocations)
buf := make([]byte, base58.EncodedMaxLen(len(data)))
result := base58.Bitcoin.EncodeTo(buf[:0], data)
Chunked encoding
Chunked encoding processes data in independent 8-byte blocks, making it significantly faster for larger payloads at the cost of a slightly longer output.
// Encode
encoded := base58.Bitcoin.EncodeChunked(data)
// Decode
decoded, err := base58.Bitcoin.DecodeChunked(encoded)
Custom alphabet
enc := base58.NewEncoding("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")
encoded := enc.Encode(data)
Predefined alphabets
| Name | Alphabet |
|---|---|
Bitcoin |
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz |
Flickr |
123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ |
Performance
Standard base58 is O(n²) due to full-buffer carry propagation. Chunked encoding is O(n) since each 8-byte block is encoded independently. Benchmarks on an Intel i9-14900K:
| Size | Encode | EncodeChunked | Decode | DecodeChunked |
|---|---|---|---|---|
| 25 B | 403 ns | 181 ns | 199 ns | 159 ns |
| 64 B | 2.66 µs | 338 ns | 991 ns | 327 ns |
| 256 B | 45.5 µs | 1.25 µs | 11.9 µs | 1.27 µs |
| 1024 B | 679 µs | 4.93 µs | 191 µs | 5.40 µs |
Run benchmarks yourself:
go test -bench=. -benchmem
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( Bitcoin = NewEncoding("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz") Flickr = NewEncoding("123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ") )
var ( ErrZeroLength = errors.New("base58: cannot decode zero length string") ErrNonAscii = errors.New("base58: cannot decode non-ASCII input") ErrBadDigit = errors.New("base58: cannot decode unsupported digit") ErrInvalidBlockLength = errors.New("base58: invalid block length") ErrOverflow = errors.New("base58: decoded value overflows block size") )
Functions ¶
func EncodedLen ¶
EncodedLen returns the encoded len for a given buffer, checking it for initial zeroes. It can be higher than needed.
func EncodedMaxLen ¶
EncodedMaxLen return the maximum encoded len for an input of ln bytes. If it starts with zeroes the actual len will be shorter
Types ¶
type Encoding ¶
type Encoding struct {
// contains filtered or unexported fields
}
func NewEncoding ¶
NewEncoding returns a encoding structure initialized for decoding/encoding using the passed parameter
It panics if the passed string is not 58 bytes long or isn't valid ASCII.
func (*Encoding) Decode ¶
Decode will decode the provided string using the current encoding and return a byte array of the value, or an error if the input was not valid
func (*Encoding) Encode ¶
Encode will encode the provided byte array into a base58 encoded string using the current encoding.
Source Files