base58-turbo 0.1.0

A high-performance Base58 encoder/decoder for Rust, optimized for high-throughput systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Base58 Turbo

[![Crates.io](https://img.shields.io/crates/v/base58-turbo.svg)](https://crates.io/crates/base58-turbo)
[![License](https://img.shields.io/crates/l/base58-turbo.svg)](https://crates.io/crates/base58-turbo)
[![MIRI Verified](https://img.shields.io/github/actions/workflow/status/hacer-bark/base58-turbo/miri.yml?label=MIRI%20Verified)](https://github.com/hacer-bark/base58-turbo/actions/workflows/miri.yml)
[![Logic Tests](https://img.shields.io/github/actions/workflow/status/hacer-bark/base58-turbo/tests.yml?label=Logic%20Tests)](https://github.com/hacer-bark/base58-turbo/actions/workflows/tests.yml)

**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

```toml
[dependencies]
base58-turbo = "0.1"
```

### Encoding

```rust
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

```rust
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:

```rust
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

| Operation       | `base58-turbo`                  | `bs58`                        | Speedup    |
|-----------------|---------------------------------|-------------------------------|------------|
| Encode (32B)    | 43.3 ns<br>(705 MiB/s)          | 885 ns<br>(34.5 MiB/s)        | **20.5×**  |
| Decode (32B)    | 38.6 ns<br>(1.06 GiB/s)         | 313 ns<br>(134 MiB/s)         | **8.1×**   |
| Encode (64B)    | 111 ns<br>(550 MiB/s)           | 3.97 µs<br>(15.4 MiB/s)       | **35.8×**  |
| Decode (64B)    | 74.1 ns<br>(1.11 GiB/s)         | 1.25 µs<br>(67.1 MiB/s)       | **16.9×**  |
| Encode (128B)   | 550 ns<br>(222 MiB/s)           | 17.4 µs<br>(7.02 MiB/s)       | **31.6×**  |
| Decode (128B)   | 175 ns<br>(952 MiB/s)           | 5.09 µs<br>(32.8 MiB/s)       | **29.0×**  |

## 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](https://github.com/hacer-bark/base58-turbo/blob/main/docs/verification.md)**

## Feature Flags

| Feature | Default | Description |
| :--- | :---: | :--- |
| `serde` | ❌ | Enables `serde` serialization/deserialization for Config and Engine |
| `std` | ✅ | Enables `String` and `Vec` support. Disable for `no_std` |

## Documentation

*   [**Architecture & Design**](https://github.com/hacer-bark/base58-turbo/blob/main/docs/design.md) - Deep dive into our bignum optimizations.
*   [**Safety & Verification**](https://github.com/hacer-bark/base58-turbo/blob/main/docs/verification.md) - Proofs, MIRI logs, and audit strategy.

## License

This project licensed under either the [MIT License](https://github.com/hacer-bark/base58-turbo/blob/main/LICENSE-MIT) or the [Apache License, Version 2.0](https://github.com/hacer-bark/base58-turbo/blob/main/LICENSE-APACHE) at your option.