0
# Base58 Encodings
1

2
Base58 encodings designed primarily for cryptocurrency applications. Base58 eliminates ambiguous characters (0, O, I, l) and offers various alphabet variants for different systems. Note that base58 has O(n^2) complexity and should only be used with small, constant-sized inputs.
3

4
## Capabilities
5

6
### Base58 Standard
7

8
Standard base58 encoding using Bitcoin's alphabet.
9

10
```typescript { .api }
11
/**
12
 * base58: base64 without ambiguous characters +, /, 0, O, I, l
13
 * Uses Bitcoin alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
14
 * Quadratic O(n^2) complexity - use only with small inputs
15
 */
16
const base58: BytesCoder = {
17
  encode: (data: Uint8Array) => string;
18
  decode: (str: string) => Uint8Array;
19
};
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import { base58 } from "@scure/base";
26

27
const data = new Uint8Array([0x01, 0xab, 0xcd, 0xef]);
28
const encoded = base58.encode(data);    // "3UhJW"
29
const decoded = base58.decode("3UhJW"); // Uint8Array([0x01, 0xab, 0xcd, 0xef])
30
```
31

32
### Base58 Flickr
33

34
Flickr variant of base58 with case-swapped alphabet.
35

36
```typescript { .api }
37
/**
38
 * base58: flickr version with different alphabet
39
 * Uses Flickr alphabet: 123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ
40
 * Quadratic O(n^2) complexity - use only with small inputs
41
 */
42
const base58flickr: BytesCoder = {
43
  encode: (data: Uint8Array) => string;
44
  decode: (str: string) => Uint8Array;
45
};
46
```
47

48
### Base58 XRP
49

50
XRP (Ripple) variant of base58 with custom alphabet.
51

52
```typescript { .api }
53
/**
54
 * base58: XRP version with custom alphabet
55
 * Uses XRP alphabet: rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz
56
 * Quadratic O(n^2) complexity - use only with small inputs
57
 */
58
const base58xrp: BytesCoder = {
59
  encode: (data: Uint8Array) => string;
60
  decode: (str: string) => Uint8Array;
61
};
62
```
63

64
### Base58 XMR (Monero)
65

66
Monero variant of base58 with optimized block processing to reduce quadratic complexity.
67

68
```typescript { .api }
69
/**
70
 * base58: XMR (Monero) version with block processing optimization
71
 * Processes data in 8-byte blocks (11 chars in decoding)
72
 * Block encoding significantly reduces quadratic complexity
73
 * Last non-full block padded with '1' to appropriate size
74
 */
75
const base58xmr: BytesCoder = {
76
  encode: (data: Uint8Array) => string;
77
  decode: (str: string) => Uint8Array;
78
};
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { base58xmr } from "@scure/base";
85

86
// More efficient for longer data due to block processing
87
const data = new Uint8Array(32); // 32 bytes of data
88
const encoded = base58xmr.encode(data);
89
const decoded = base58xmr.decode(encoded);
90
```
91

92
### Base58Check
93

94
Base58 with double SHA-256 checksum validation. Requires providing a SHA-256 hash function.
95

96
```typescript { .api }
97
/**
98
 * Creates base58check encoder with SHA-256 checksum validation
99
 * Appends 4-byte double SHA-256 checksum for error detection
100
 * @param sha256 - SHA-256 hash function
101
 * @returns BytesCoder with checksum validation
102
 */
103
function createBase58check(
104
  sha256: (data: Uint8Array) => Uint8Array
105
): BytesCoder;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
import { createBase58check } from "@scure/base";
112
import { sha256 } from "@noble/hashes/sha2";
113

114
const base58check = createBase58check(sha256);
115

116
const data = new Uint8Array([0x12, 0x34, 0x56]);
117
const encoded = base58check.encode(data);
118
const decoded = base58check.decode(encoded);
119

120
// Checksum validation happens automatically during decode
121
try {
122
  base58check.decode("invalid_checksum"); // Throws error
123
} catch (error) {
124
  console.log("Invalid checksum detected");
125
}
126
```
127

128
**Advanced Usage with Bitcoin Addresses:**
129

130
```typescript
131
import { createBase58check } from "@scure/base";
132
import { sha256 } from "@noble/hashes/sha2";
133

134
const base58check = createBase58check(sha256);
135

136
// Example: Bitcoin address creation (simplified)
137
function createBitcoinAddress(publicKeyHash: Uint8Array): string {
138
  // Add version byte (0x00 for mainnet)
139
  const payload = new Uint8Array([0x00, ...publicKeyHash]);
140
  return base58check.encode(payload);
141
}
142

143
function decodeBitcoinAddress(address: string): { version: number; hash: Uint8Array } {
144
  const decoded = base58check.decode(address);
145
  return {
146
    version: decoded[0],
147
    hash: decoded.slice(1)
148
  };
149
}
150
```
151

152
### Legacy Base58Check (Deprecated)
153

154
Deprecated alias for createBase58check.
155

156
```typescript { .api }
157
/**
158
 * @deprecated Use createBase58check instead
159
 * Legacy alias for createBase58check function
160
 */
161
const base58check: (sha256: (data: Uint8Array) => Uint8Array) => BytesCoder;
162
```
163

164
## Performance Considerations
165

166
Base58 encodings have quadratic O(n^2) time complexity due to arbitrary radix conversion. This can cause performance issues or DoS attacks with large variable-length inputs.
167

168
**Recommendations:**
169

170
- Use only with small, constant-sized inputs (like hashes, keys)
171
- For large data, prefer base64 or other power-of-2 base encodings
172
- Base58XMR uses block processing to partially mitigate complexity issues
173
- Consider input size limits in production applications
174

175
```typescript
176
import { base58, base64 } from "@scure/base";
177

178
// Good: Small, constant-sized data (32 bytes)
179
const hash = new Uint8Array(32);
180
const encoded = base58.encode(hash); // Fast
181

182
// Avoid: Large variable-length data
183
const largeData = new Uint8Array(10000); // This will be slow!
184
const encoded = base64.encode(largeData); // Use base64 instead
185
```
186

187
## Error Handling
188

189
Base58 encoders validate input and provide detailed error messages:
190

191
```typescript
192
import { base58, createBase58check } from "@scure/base";
193
import { sha256 } from "@noble/hashes/sha2";
194

195
try {
196
  base58.decode("0OIl"); // Contains ambiguous characters
197
} catch (error) {
198
  console.log(error.message); // "Unknown letter: ..."
199
}
200

201
const base58check = createBase58check(sha256);
202
try {
203
  base58check.decode("corrupted_data"); // Invalid checksum
204
} catch (error) {
205
  console.log(error.message); // "Invalid checksum"
206
}
207
```