0
# @scure/base
1

2
@scure/base is a secure, audited & 0-dep implementation of base encoding algorithms including base64, bech32, base58, base32 & base16. Designed with security as a priority and zero-dependency principles, it provides tree-shakeable, composable functions written in functional style that match relevant specifications.
3

4
## Package Information
5

6
- **Package Name**: @scure/base
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @scure/base`
10

11
## Core Imports
12

13
```typescript
14
import { base64, base58, base32, base16, hex, utf8 } from "@scure/base";
15
import { bech32, bech32m } from "@scure/base";
16
import { createBase58check, utils } from "@scure/base";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { base64, base58, base32, base16, hex, utf8 } = require("@scure/base");
23
const { bech32, bech32m } = require("@scure/base");
24
const { createBase58check, utils } = require("@scure/base");
25
```
26

27
## Basic Usage
28

29
```typescript
30
import { base64, base58, hex, utf8 } from "@scure/base";
31

32
// Convert string to bytes first
33
const data = utf8.decode("hello world");
34

35
// Encode to different formats
36
const b64 = base64.encode(data);    // "aGVsbG8gd29ybGQ="
37
const b58 = base58.encode(data);    // "StV1zBwJvKJ6JGa"
38
const hexStr = hex.encode(data);    // "68656c6c6f20776f726c64"
39

40
// Decode back to bytes
41
const decoded = base64.decode(b64);
42
const original = utf8.encode(decoded); // "hello world"
43

44
// All encoders have the same API: encode(bytes) -> string, decode(string) -> bytes
45
```
46

47
## Architecture
48

49
@scure/base is built around several key components:
50

51
- **BytesCoder Interface**: Common interface for all encoders with `encode(Uint8Array) -> string` and `decode(string) -> Uint8Array`
52
- **Functional Composition**: Encoders built from small composable functions using `utils.chain()`
53
- **Built-in Optimizations**: Uses native browser APIs when available (base64, hex)
54
- **RFC Compliance**: Matches RFC 4648 for base encodings, BIP 173/350 for bech32
55
- **Security First**: Audited implementation with input validation and error handling
56

57
## Capabilities
58

59
### Base Encodings
60

61
Standard RFC 4648 compliant base encodings including base16 (hex), base32 variants, and base64 variants with optional padding.
62

63
```typescript { .api }
64
// Base16 (hex)
65
const base16: BytesCoder = {
66
  encode: (data: Uint8Array) => string;
67
  decode: (str: string) => Uint8Array;
68
};
69

70
// Base32 variants  
71
const base32: BytesCoder;
72
const base32nopad: BytesCoder;
73
const base32hex: BytesCoder;
74
const base32hexnopad: BytesCoder;
75
const base32crockford: BytesCoder;
76

77
// Base64 variants
78
const base64: BytesCoder;
79
const base64nopad: BytesCoder;
80
const base64url: BytesCoder;
81
const base64urlnopad: BytesCoder;
82
```
83

84
[Base Encodings](./base-encodings.md)
85

86
### Base58 Encodings
87

88
Base58 encodings designed for cryptocurrency applications, including Bitcoin's base58, base58check with checksum validation, and variants like XMR and XRP.
89

90
```typescript { .api }
91
const base58: BytesCoder;
92
const base58flickr: BytesCoder;
93
const base58xrp: BytesCoder;
94
const base58xmr: BytesCoder;
95

96
function createBase58check(
97
  sha256: (data: Uint8Array) => Uint8Array
98
): BytesCoder;
99
```
100

101
[Base58 Encodings](./base58-encodings.md)
102

103
### Bech32 Encodings
104

105
Bitcoin BIP 173/350 compliant bech32 and bech32m encodings with typed prefix support and word-based operations for Bitcoin addresses and Lightning invoices.
106

107
```typescript { .api }
108
interface Bech32 {
109
  encode<Prefix extends string>(
110
    prefix: Prefix,
111
    words: number[] | Uint8Array,
112
    limit?: number | false
113
  ): `${Lowercase<Prefix>}1${string}`;
114
  decode<Prefix extends string>(
115
    str: `${Prefix}1${string}`,
116
    limit?: number | false
117
  ): Bech32Decoded<Prefix>;
118
  encodeFromBytes(prefix: string, bytes: Uint8Array): string;
119
  decodeToBytes(str: string): Bech32DecodedWithArray;
120
  decodeUnsafe(str: string, limit?: number | false): void | Bech32Decoded<string>;
121
  fromWords(to: number[]): Uint8Array;
122
  fromWordsUnsafe(to: number[]): void | Uint8Array;
123
  toWords(from: Uint8Array): number[];
124
}
125

126
const bech32: Bech32;
127
const bech32m: Bech32;
128
```
129

130
[Bech32 Encodings](./bech32-encodings.md)
131

132
### Additional Encoders
133

134
UTF-8 and hexadecimal encoders for common text and binary data operations.
135

136
```typescript { .api }
137
const utf8: BytesCoder = {
138
  encode: (data: Uint8Array) => string;  // bytes to UTF-8 string
139
  decode: (str: string) => Uint8Array;   // UTF-8 string to bytes
140
};
141

142
const hex: BytesCoder = {
143
  encode: (data: Uint8Array) => string;  // bytes to lowercase hex
144
  decode: (str: string) => Uint8Array;   // hex string to bytes
145
};
146
```
147

148
### Utility Functions
149

150
Low-level utility functions for building custom encoders using functional composition, including radix conversion, alphabet mapping, and checksum validation.
151

152
```typescript { .api }
153
const utils: {
154
  alphabet: (letters: string | string[]) => Coder<number[], string[]>;
155
  chain: <T extends Chain>(...args: T) => Coder<Input<First<T>>, Output<Last<T>>>;
156
  checksum: (len: number, fn: (data: Uint8Array) => Uint8Array) => Coder<Uint8Array, Uint8Array>;
157
  radix: (num: number) => Coder<Uint8Array, number[]>;
158
  radix2: (bits: number, revPadding?: boolean) => Coder<Uint8Array, number[]>;
159
  join: (separator?: string) => Coder<string[], string>;
160
  padding: (bits: number, chr?: string) => Coder<string[], string[]>;
161
};
162
```
163

164
[Utility Functions](./utils.md)
165

166
## Types
167

168
```typescript { .api }
169
interface BytesCoder {
170
  encode: (data: Uint8Array) => string;
171
  decode: (str: string) => Uint8Array;
172
}
173

174
interface Coder<F, T> {
175
  encode(from: F): T;
176
  decode(to: T): F;
177
}
178

179
interface Bech32Decoded<Prefix extends string = string> {
180
  prefix: Prefix;
181
  words: number[];
182
}
183

184
interface Bech32DecodedWithArray<Prefix extends string = string> {
185
  prefix: Prefix;
186
  words: number[];
187
  bytes: Uint8Array;
188
}
189

190
type CoderType = 'utf8' | 'hex' | 'base16' | 'base32' | 'base64' | 'base64url' | 'base58' | 'base58xmr';
191

192
interface SomeCoders {
193
  utf8: BytesCoder;
194
  hex: BytesCoder;
195
  base16: BytesCoder;
196
  base32: BytesCoder;
197
  base64: BytesCoder;
198
  base64url: BytesCoder;
199
  base58: BytesCoder;
200
  base58xmr: BytesCoder;
201
}
202
```
203

204
## Deprecated Functions
205

206
The following functions are deprecated but still available for backwards compatibility:
207

208
```typescript { .api }
209
/** @deprecated Use individual encoders directly instead */
210
function bytesToString(type: CoderType, bytes: Uint8Array): string;
211

212
/** @deprecated Alias for bytesToString */
213
const str: (type: CoderType, bytes: Uint8Array) => string;
214

215
/** @deprecated Use individual encoders directly instead */  
216
function stringToBytes(type: CoderType, str: string): Uint8Array;
217

218
/** @deprecated Alias for stringToBytes */
219
const bytes: (type: CoderType, str: string) => Uint8Array;
220
```