Base58 Turbo

The fastest memory-safe Base58 implementation.

base58-turbo is a production-grade library engineered for High Frequency Trading (HFT), Blockchain Nodes, and Mission-Critical Servers where CPU cycles are scarce and Undefined Behavior (UB) is unacceptable.

It aligns with modern hardware reality without sacrificing portability, utilizing optimized scalar kernels, matrix multiplication arithmetic, and vectorized zero handling.

Quick Start

Installation

[dependencies]
base58-turbo = "0.1"

Encoding

use base58_turbo::BITCOIN;

fn main() {
    let data = b"Hello World";

    // Returns Result<String, Error>
    let encoded = BITCOIN.encode(data).unwrap();

    assert_eq!(encoded, "JxF12TrwUP45BMd");
}

Decoding

use base58_turbo::BITCOIN;

fn main() {
    let encoded = "JxF12TrwUP45BMd";

    // Returns Result<Vec<u8>, Error>
    let decoded = BITCOIN.decode(encoded).unwrap();

    assert_eq!(decoded, b"Hello World");
}

Zero-Allocation (Stack)

For scenarios where heap allocation is too slow (e.g., hot paths), write directly to stack buffers:

use base58_turbo::BITCOIN;

fn main() {
    let input = b"Hello World";
    let mut output = [0u8; 64];

    // Returns Result<usize, Error>
    let len = BITCOIN.encode_into(input, &mut output).unwrap();
    let encoded = std::str::from_utf8(&output[..len]).unwrap();

    assert_eq!(encoded, "JxF12TrwUP45BMd");
}

Engines

Supports multiple Base58 alphabets:

• BITCOIN: Standard Bitcoin alphabet.
• MONERO: Monero alphabet.
• RIPPLE: Ripple alphabet.
• FLICKR: Flickr alphabet.
• Engine::new(&[u8; 58]): Custom alphabets.

Compatibility & Stability

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.86.0 or newer. We utilize modern Rust features to guarantee safety and performance.

Public API Stability

The public API (traits, structs, and error types) is considered Stable.

• We adhere to Semantic Versioning.
• The current API surface will remain valid and backward-compatible throughout the 0.1.x lifecycle.

Performance

base58-turbo is designed for maximum throughput, utilizing:

• Matrix Multiplication Arithmetic: Converts large chunks (25, 32, 64 bytes) using precomputed weights and 128-bit accumulation.
• Vectorized Zero Handling: Rapidly processes leading zeros using 64-bit SIMD patterns even in scalar code.
• 2-Byte Lookup Tables (LUT): Emits two characters at a time during encoding to reduce branch pressure.
• High-Radix Processing: Processes input in Base 58^{10 (decoding) and Base 58}5 (encoding) to minimize bignum divisions.

Benchmarks

Safety & Verification

Achieving maximum throughput must not cost memory safety. While we leverage unsafe intrinsics and pointer arithmetic, we guarantee the absence of bugs using a "Swiss Cheese" model of verification layers.

• MIRI Verified: Validates that no Undefined Behavior (UB) occurs during execution.
• MSan Audited: MemorySanitizer confirms no logic is ever performed on uninitialized memory.
• Fuzz Tested: Continuous fuzzing with zero failures.

Read the Verification Audit

Feature Flags

Documentation

• Architecture & Design - Deep dive into our bignum optimizations.
• Safety & Verification - Proofs, MIRI logs, and audit strategy.

License

This project licensed under either the MIT License or the Apache License, Version 2.0 at your option.