# Module BSV::Primitives::Base58 <a id="module-BSV-Primitives-Base58"></a>

Base58 and Base58Check encoding/decoding.

Implements the Base58 alphabet used throughout Bitcoin for addresses, WIF
keys, and extended keys. Base58Check adds a 4-byte double-SHA-256 checksum for
error detection.

**@example Encode and decode an address payload**
```ruby
encoded = BSV::Primitives::Base58.check_encode(payload)
decoded = BSV::Primitives::Base58.check_decode(encoded)
```

## Constants
### `ALPHABET` <a id="constant-ALPHABET"></a> <a id="ALPHABET-constant"></a>
The Base58 alphabet (no 0, O, I, l to avoid visual ambiguity).

### `BASE` <a id="constant-BASE"></a> <a id="BASE-constant"></a>
The base (58).

### `DECODE_MAP` <a id="constant-DECODE_MAP"></a> <a id="DECODE_MAP-constant"></a>
Reverse lookup table mapping ASCII byte values to Base58 digit indices.

## Public Class Methods
### `check_decode(string, prefix_length: = 0)` <a id="method-c-check_decode"></a> <a id="check_decode-class_method"></a>
Decode a Base58Check string and verify its checksum.

When `prefix_length` is greater than zero, the decoded payload is split into a
prefix and data portion. The returned value is then a Hash with
<code>:prefix</code> and <code>:data</code> keys. When `prefix_length` is zero
(default), the raw payload is returned unchanged for backwards compatibility.
- **@param** `string` [String] Base58Check-encoded string
- **@param** `prefix_length` [Integer] number of leading bytes to treat as a prefix (default: 0)
- **@raise** [ChecksumError] if the checksum does not match or input is too short
- **@return** [String, Hash] decoded payload, or +{ prefix:, data: }+ when prefix_length > 0

### `check_encode(payload, prefix: = nil)` <a id="method-c-check_encode"></a> <a id="check_encode-class_method"></a>
Encode binary data with a 4-byte double-SHA-256 checksum appended.

When `prefix` is given, it is prepended to the payload before checksumming.
The checksum covers the full +prefix + payload+ concatenation.
- **@param** `payload` [String] binary data to encode
- **@param** `prefix` [String, nil] optional version prefix to prepend (binary string)
- **@return** [String] Base58Check-encoded string

### `decode(string)` <a id="method-c-decode"></a> <a id="decode-class_method"></a>
Decode a Base58 string to binary data.

Leading +'1'+ characters are decoded as zero bytes.
- **@param** `string` [String] Base58-encoded string
- **@raise** [ArgumentError] if the string is empty or contains invalid Base58 characters
- **@return** [String] decoded binary data

### `encode(bytes)` <a id="method-c-encode"></a> <a id="encode-class_method"></a>
Encode binary data as a Base58 string.

Leading zero bytes are preserved as +'1'+ characters.
- **@param** `bytes` [String] binary data to encode
- **@return** [String] Base58-encoded string