or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-base58

Base58 and Base58Check implementation compatible with the Bitcoin network with support for custom alphabets

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/base58@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-base58@2.1.0

index.mddocs/

Base58

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.

Package Information

  • Package Name: base58
  • Language: Python
  • Installation: pip install base58
  • Version: 2.1.1
  • License: MIT

Core Imports

import base58

For specific functions:

from base58 import b58encode, b58decode, b58encode_check, b58decode_check

For alphabets:

from base58 import BITCOIN_ALPHABET, XRP_ALPHABET, RIPPLE_ALPHABET

Basic Usage

import base58

# Basic encoding and decoding
data = b'hello world'
encoded = base58.b58encode(data)
print(encoded)  # b'StV1DL6CwTryKyV'

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

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

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

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

decoded_xrp = base58.b58decode(encoded_xrp, alphabet=base58.XRP_ALPHABET)
print(decoded_xrp)  # b'hello world'

Command Line Usage

# Encode data from stdin
echo "hello world" | base58
# Output: StV1DL6CwTryKyV

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

# Decode data
echo "StV1DL6CwTryKyV" | base58 -d
# Output: hello world

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

# Decode with invalid checksum (raises error)
echo "4vQB7B6MrGQZaxCuFg4oh" | base58 -dc
# Output: Invalid checksum

Capabilities

Basic Encoding

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

def b58encode(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
    """
    Encode a string using Base58.
    
    Parameters:
    - v: Input data to encode (string or bytes)
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
    
    Returns:
    bytes: Base58 encoded data
    """

Basic Decoding

Decodes Base58 encoded strings back to original bytes.

def b58decode(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> bytes:
    """
    Decode a Base58 encoded string.
    
    Parameters:
    - v: Base58 encoded string to decode (string or bytes)
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)  
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
    
    Returns:
    bytes: Decoded data
    
    Raises:
    ValueError: Invalid character in encoded string
    """

Checksum Encoding

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

def b58encode_check(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
    """
    Encode a string using Base58 with a 4 character checksum.
    
    Parameters:
    - v: Input data to encode (string or bytes)
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
    
    Returns:
    bytes: Base58 encoded data with checksum
    """

Checksum Decoding

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

def b58decode_check(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> bytes:
    """
    Decode and verify the checksum of a Base58 encoded string.
    
    Parameters:
    - v: Base58 encoded string with checksum to decode (string or bytes)
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
    
    Returns:
    bytes: Decoded data without checksum
    
    Raises:
    ValueError: Invalid checksum or invalid character
    """

Integer Encoding

Encodes integers directly using Base58 algorithm.

def b58encode_int(i: int, default_one: bool = True, alphabet: bytes = BITCOIN_ALPHABET) -> bytes:
    """
    Encode an integer using Base58.
    
    Parameters:
    - i: Integer to encode
    - default_one: Return first alphabet character for zero when True
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
    
    Returns:
    bytes: Base58 encoded integer
    """

Integer Decoding

Decodes Base58 encoded strings as integers.

def b58decode_int(v: Union[str, bytes], alphabet: bytes = BITCOIN_ALPHABET, *, autofix: bool = False) -> int:
    """
    Decode a Base58 encoded string as an integer.
    
    Parameters:
    - v: Base58 encoded string to decode (string or bytes)
    - alphabet: Base58 alphabet to use (default: BITCOIN_ALPHABET)
    - autofix: Attempt to fix common character substitutions (0/O, I/l/1)
    
    Returns:
    int: Decoded integer
    
    Raises:
    ValueError: Invalid character in encoded string
    """

Command Line Interface

Main entry point for the base58 command-line tool.

def main() -> None:
    """
    Base58 encode or decode FILE, or standard input, to standard output.
    
    Command line arguments:
    - FILE: Input file (optional, defaults to stdin)
    - -d, --decode: Decode data instead of encoding
    - -c, --check: Append/verify checksum
    
    The function processes data from specified file or stdin and outputs
    the result to stdout. Exits with error message on invalid data.
    """

Constants and Alphabets

__version__: str = "2.1.1"

# Base58 alphabets
BITCOIN_ALPHABET: bytes = b'123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
RIPPLE_ALPHABET: bytes = b'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz'  
XRP_ALPHABET: bytes = RIPPLE_ALPHABET  # Recommended alias

# Legacy compatibility
alphabet: bytes = BITCOIN_ALPHABET

Error Handling

The library raises ValueError in the following scenarios:

  • Invalid checksum: When b58decode_check() detects checksum mismatch
  • Invalid character: When decoding encounters characters not in the specified alphabet
  • General encoding/decoding errors: For malformed input data
import base58

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

# Handle invalid character errors
try:
    result = base58.b58decode('invalid#character')
except ValueError as e:
    print(f"Decoding error: {e}")

Advanced Usage Examples

Custom Alphabet Usage

import base58

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

data = b'test data'
encoded = base58.b58encode(data, alphabet=CUSTOM_ALPHABET)
decoded = base58.b58decode(encoded, alphabet=CUSTOM_ALPHABET)
assert decoded == data

Autofix Feature

import base58

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

Integer Operations

import base58

# Encode large integers directly
large_number = 123456789012345678901234567890
encoded_int = base58.b58encode_int(large_number)
decoded_int = base58.b58decode_int(encoded_int)
assert decoded_int == large_number

Cross-Platform Compatibility

import base58

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

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

# Both use same algorithm, different character sets