0
# Base58
1

2
Base58 and Base58Check implementation compatible with the Bitcoin network with support for custom alphabets including XRP/Ripple. Provides both programmatic API for encoding and decoding data, as well as a command-line interface for terminal usage.
3

4
## Package Information
5

6
- **Package Name**: base58
7
- **Language**: Python
8
- **Installation**: `pip install base58`
9
- **Version**: 2.1.1
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import base58
16
```
17

18
For specific functions:
19

20
```python
21
from base58 import b58encode, b58decode, b58encode_check, b58decode_check
22
```
23

24
For alphabets:
25

26
```python
27
from base58 import BITCOIN_ALPHABET, XRP_ALPHABET, RIPPLE_ALPHABET
28
```
29

30
## Basic Usage
31

32
```python
33
import base58
34

35
# Basic encoding and decoding
36
data = b'hello world'
37
encoded = base58.b58encode(data)
38
print(encoded)  # b'StV1DL6CwTryKyV'
39

40
decoded = base58.b58decode(encoded)
41
print(decoded)  # b'hello world'
42

43
# Encoding and decoding with checksum
44
encoded_check = base58.b58encode_check(data)
45
print(encoded_check)  # b'3vQB7B6MrGQZaxCuFg4oh'
46

47
decoded_check = base58.b58decode_check(encoded_check)
48
print(decoded_check)  # b'hello world'
49

50
# Using custom alphabet (XRP/Ripple)
51
encoded_xrp = base58.b58encode(data, alphabet=base58.XRP_ALPHABET)
52
print(encoded_xrp)  # b'StVrDLaUATiyKyV'
53

54
decoded_xrp = base58.b58decode(encoded_xrp, alphabet=base58.XRP_ALPHABET)
55
print(decoded_xrp)  # b'hello world'
56
```
57

58
## Command Line Usage
59

60
```bash
61
# Encode data from stdin
62
echo "hello world" | base58
63
# Output: StV1DL6CwTryKyV
64

65
# Encode with checksum
66
echo "hello world" | base58 -c
67
# Output: 3vQB7B6MrGQZaxCuFg4oh
68

69
# Decode data
70
echo "StV1DL6CwTryKyV" | base58 -d
71
# Output: hello world
72

73
# Decode with checksum verification
74
echo "3vQB7B6MrGQZaxCuFg4oh" | base58 -dc
75
# Output: hello world
76

77
# Decode with invalid checksum (raises error)
78
echo "4vQB7B6MrGQZaxCuFg4oh" | base58 -dc
79
# Output: Invalid checksum
80
```
81

82
## Capabilities
83

84
### Basic Encoding
85

86
Encodes bytes or strings using Base58 algorithm compatible with Bitcoin network standard.
87

88
```python { .api }
89
def b58encode(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
90
    """
91
    Encode a string using Base58.
92
    
93
    Parameters:
94
    - v: Input data to encode (string or bytes)
95
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
96
    
97
    Returns:
98
    bytes: Base58 encoded data
99
    """
100
```
101

102
### Basic Decoding
103

104
Decodes Base58 encoded strings back to original bytes.
105

106
```python { .api }
107
def b58decode(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> bytes:
108
    """
109
    Decode a Base58 encoded string.
110
    
111
    Parameters:
112
    - v: Base58 encoded string to decode (string or bytes)
113
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)  
114
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
115
    
116
    Returns:
117
    bytes: Decoded data
118
    
119
    Raises:
120
    ValueError: Invalid character in encoded string
121
    """
122
```
123

124
### Checksum Encoding
125

126
Encodes data with SHA256-based checksum for data integrity verification, compatible with Bitcoin network.
127

128
```python { .api }
129
def b58encode_check(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
130
    """
131
    Encode a string using Base58 with a 4 character checksum.
132
    
133
    Parameters:
134
    - v: Input data to encode (string or bytes)
135
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
136
    
137
    Returns:
138
    bytes: Base58 encoded data with checksum
139
    """
140
```
141

142
### Checksum Decoding
143

144
Decodes Base58 encoded data and verifies the checksum for data integrity.
145

146
```python { .api }
147
def b58decode_check(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> bytes:
148
    """
149
    Decode and verify the checksum of a Base58 encoded string.
150
    
151
    Parameters:
152
    - v: Base58 encoded string with checksum to decode (string or bytes)
153
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
154
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
155
    
156
    Returns:
157
    bytes: Decoded data without checksum
158
    
159
    Raises:
160
    ValueError: Invalid checksum or invalid character
161
    """
162
```
163

164
### Integer Encoding
165

166
Encodes integers directly using Base58 algorithm.
167

168
```python { .api }
169
def b58encode_int(i: int, default_one: bool = True, alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
170
    """
171
    Encode an integer using Base58.
172
    
173
    Parameters:
174
    - i: Integer to encode
175
    - default_one: Return first alphabet character for zero when True
176
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
177
    
178
    Returns:
179
    bytes: Base58 encoded integer
180
    """
181
```
182

183
### Integer Decoding
184

185
Decodes Base58 encoded strings as integers.
186

187
```python { .api }
188
def b58decode_int(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> int:
189
    """
190
    Decode a Base58 encoded string as an integer.
191
    
192
    Parameters:
193
    - v: Base58 encoded string to decode (string or bytes)
194
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
195
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
196
    
197
    Returns:
198
    int: Decoded integer
199
    
200
    Raises:
201
    ValueError: Invalid character in encoded string
202
    """
203
```
204

205
### Command Line Interface
206

207
Main entry point for the base58 command-line tool.
208

209
```python { .api }
210
def main() -> None:
211
    """
212
    Base58 encode or decode FILE, or standard input, to standard output.
213
    
214
    Command line arguments:
215
    - FILE: Input file (optional, defaults to stdin)
216
    - -d, --decode: Decode data instead of encoding
217
    - -c, --check: Append/verify checksum
218
    
219
    The function processes data from specified file or stdin and outputs
220
    the result to stdout. Exits with error message on invalid data.
221
    """
222
```
223

224
## Constants and Alphabets
225

226
```python { .api }
227
__version__: str = "2.1.1"
228

229
# Base58 alphabets
230
BITCOIN_ALPHABET: bytes = b'123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
231
RIPPLE_ALPHABET: bytes = b'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz'  
232
XRP_ALPHABET: bytes = RIPPLE_ALPHABET  # Recommended alias
233

234
# Legacy compatibility
235
alphabet: bytes = BITCOIN_ALPHABET
236
```
237

238
## Error Handling
239

240
The library raises `ValueError` in the following scenarios:
241

242
- **Invalid checksum**: When `b58decode_check()` detects checksum mismatch
243
- **Invalid character**: When decoding encounters characters not in the specified alphabet
244
- **General encoding/decoding errors**: For malformed input data
245

246
```python
247
import base58
248

249
# Handle checksum verification errors
250
try:
251
    result = base58.b58decode_check('invalid_checksum_data')
252
except ValueError as e:
253
    print(f"Checksum error: {e}")
254

255
# Handle invalid character errors
256
try:
257
    result = base58.b58decode('invalid#character')
258
except ValueError as e:
259
    print(f"Decoding error: {e}")
260
```
261

262
## Advanced Usage Examples
263

264
### Custom Alphabet Usage
265

266
```python
267
import base58
268

269
# Define custom alphabet (must be 58 unique characters)
270
CUSTOM_ALPHABET = b'abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ123456789'
271

272
data = b'test data'
273
encoded = base58.b58encode(data, alphabet=CUSTOM_ALPHABET)
274
decoded = base58.b58decode(encoded, alphabet=CUSTOM_ALPHABET)
275
assert decoded == data
276
```
277

278
### Autofix Feature
279

280
```python
281
import base58
282

283
# Autofix handles common character confusions
284
encoded_with_errors = 'StVlDL6CwTryKyV'  # 'l' instead of '1'
285
correct_data = base58.b58decode(encoded_with_errors, autofix=True)
286
# Automatically converts: 0→O, I→1, l→1 when only one variant exists in alphabet
287
```
288

289
### Integer Operations
290

291
```python
292
import base58
293

294
# Encode large integers directly
295
large_number = 123456789012345678901234567890
296
encoded_int = base58.b58encode_int(large_number)
297
decoded_int = base58.b58decode_int(encoded_int)
298
assert decoded_int == large_number
299
```
300

301
### Cross-Platform Compatibility
302

303
```python
304
import base58
305

306
# Bitcoin-compatible encoding
307
btc_encoded = base58.b58encode(b'bitcoin_data', alphabet=base58.BITCOIN_ALPHABET)
308

309
# XRP/Ripple-compatible encoding  
310
xrp_encoded = base58.b58encode(b'ripple_data', alphabet=base58.XRP_ALPHABET)
311

312
# Both use same algorithm, different character sets
313
```