0
# @scure/bip39
1

2
@scure/bip39 is a secure, audited, and minimal implementation of BIP39 mnemonic phrases for cryptocurrency applications. It provides comprehensive functionality for generating cryptographically secure mnemonic phrases, converting between mnemonics and entropy, validating mnemonic phrases, and deriving seed data using key derivation functions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import * as bip39 from '@scure/bip39';
15
import { wordlist } from '@scure/bip39/wordlists/english.js';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const bip39 = require('@scure/bip39');
22
const { wordlist } = require('@scure/bip39/wordlists/english.js');
23
```
24

25
## Basic Usage
26

27
```typescript
28
import * as bip39 from '@scure/bip39';
29
import { wordlist } from '@scure/bip39/wordlists/english.js';
30

31
// Generate a random 12-word mnemonic
32
const mnemonic = bip39.generateMnemonic(wordlist);
33
console.log(mnemonic);
34
// "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
35

36
// Validate the mnemonic
37
const isValid = bip39.validateMnemonic(mnemonic, wordlist);
38
console.log(isValid); // true
39

40
// Convert mnemonic to seed for cryptographic operations
41
const seed = await bip39.mnemonicToSeed(mnemonic, 'optional-passphrase');
42
console.log(seed); // Uint8Array(64) [...]
43

44
// Convert mnemonic to raw entropy (reversible)
45
const entropy = bip39.mnemonicToEntropy(mnemonic, wordlist);
46
// Convert entropy back to mnemonic (reversible)
47
const recreatedMnemonic = bip39.entropyToMnemonic(entropy, wordlist);
48
```
49

50
## Architecture
51

52
@scure/bip39 is built around several key components:
53

54
- **Mnemonic Generation**: Cryptographically secure random mnemonic phrase generation
55
- **Entropy Conversion**: Bidirectional conversion between mnemonics and raw entropy data
56
- **Validation System**: Mnemonic phrase validation against specific wordlists
57
- **Key Derivation**: PBKDF2-based seed derivation with optional passphrase protection
58
- **Multi-language Support**: 10 different language wordlists with proper Unicode handling
59
- **Performance Variants**: Pure JavaScript and WebCrypto API implementations
60

61
## Capabilities
62

63
### Mnemonic Generation
64

65
Generate cryptographically secure random mnemonic phrases using CSPRNG.
66

67
```typescript { .api }
68
/**
69
 * Generate x random words. Uses Cryptographically-Secure Random Number Generator.
70
 * @param wordlist - Array of 2048 words for specific language
71
 * @param strength - Mnemonic strength in bits: 128, 160, 192, 224, or 256 (default: 128)
72
 * @returns Mnemonic string with 12, 15, 18, 21, or 24 words respectively
73
 * @throws TypeError for invalid entropy strength (must be divisible by 32 and ≤256)
74
 */
75
function generateMnemonic(wordlist: string[], strength: number = 128): string;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { generateMnemonic } from '@scure/bip39';
82
import { wordlist } from '@scure/bip39/wordlists/english.js';
83

84
// Generate 12-word mnemonic (128 bits, default)
85
const mnemonic12 = generateMnemonic(wordlist);
86

87
// Generate 24-word mnemonic (256 bits)
88
const mnemonic24 = generateMnemonic(wordlist, 256);
89

90
// Generate 15-word mnemonic (160 bits)
91
const mnemonic15 = generateMnemonic(wordlist, 160);
92

93
// Generate 18-word mnemonic (192 bits)
94
const mnemonic18 = generateMnemonic(wordlist, 192);
95

96
// Generate 21-word mnemonic (224 bits)
97
const mnemonic21 = generateMnemonic(wordlist, 224);
98
```
99

100
### Entropy Conversion
101

102
Convert between mnemonic strings and raw entropy bytes (bidirectional operations).
103

104
```typescript { .api }
105
/**
106
 * Reversible: Converts mnemonic string to raw entropy in form of byte array.
107
 * @param mnemonic - 12-24 word mnemonic string
108
 * @param wordlist - Wordlist array used for mnemonic
109
 * @returns Uint8Array of entropy bytes
110
 * @throws Error for invalid mnemonic or entropy length
111
 */
112
function mnemonicToEntropy(mnemonic: string, wordlist: string[]): Uint8Array;
113

114
/**
115
 * Reversible: Converts raw entropy in form of byte array to mnemonic string.
116
 * @param entropy - Uint8Array of entropy bytes (16, 20, 24, 28, or 32 bytes)
117
 * @param wordlist - Wordlist array for mnemonic generation
118
 * @returns 12-24 word mnemonic string
119
 */
120
function entropyToMnemonic(entropy: Uint8Array, wordlist: string[]): string;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
import { mnemonicToEntropy, entropyToMnemonic } from '@scure/bip39';
127
import { wordlist } from '@scure/bip39/wordlists/english.js';
128

129
const mnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
130

131
// Convert mnemonic to entropy
132
const entropy = mnemonicToEntropy(mnemonic, wordlist);
133
console.log(entropy); // Uint8Array(16) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
134

135
// Convert entropy back to mnemonic
136
const recreatedMnemonic = entropyToMnemonic(entropy, wordlist);
137
console.log(recreatedMnemonic === mnemonic); // true
138

139
// Using custom entropy
140
const customEntropy = new Uint8Array([
141
  0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f,
142
  0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f
143
]);
144
const customMnemonic = entropyToMnemonic(customEntropy, wordlist);
145
```
146

147
### Mnemonic Validation
148

149
Validate mnemonic phrases against specific wordlists.
150

151
```typescript { .api }
152
/**
153
 * Validates mnemonic for being 12-24 words contained in wordlist.
154
 * @param mnemonic - Mnemonic string to validate
155
 * @param wordlist - Wordlist array for validation
156
 * @returns Boolean indicating validity
157
 */
158
function validateMnemonic(mnemonic: string, wordlist: string[]): boolean;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { validateMnemonic } from '@scure/bip39';
165
import { wordlist } from '@scure/bip39/wordlists/english.js';
166

167
const validMnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
168
const invalidMnemonic = 'invalid mnemonic phrase';
169

170
console.log(validateMnemonic(validMnemonic, wordlist)); // true
171
console.log(validateMnemonic(invalidMnemonic, wordlist)); // false
172

173
// Validate against different language
174
import { wordlist as frenchWordlist } from '@scure/bip39/wordlists/french.js';
175
console.log(validateMnemonic(validMnemonic, frenchWordlist)); // false (wrong language)
176
```
177

178
### Seed Derivation
179

180
Derive cryptographic seeds from mnemonic phrases using PBKDF2 with optional passphrase protection.
181

182
```typescript { .api }
183
/**
184
 * Derive 64-byte seed from mnemonic using PBKDF2-SHA512 with 2048 iterations (async, irreversible)
185
 * @param mnemonic - 12-24 word mnemonic string
186
 * @param passphrase - Optional password for additional protection (default: '')
187
 * @returns Promise resolving to 64-byte Uint8Array seed
188
 */
189
function mnemonicToSeed(mnemonic: string, passphrase: string = ''): Promise<Uint8Array>;
190

191
/**
192
 * Derive 64-byte seed from mnemonic using PBKDF2-SHA512 with 2048 iterations (sync, irreversible)
193
 * @param mnemonic - 12-24 word mnemonic string
194
 * @param passphrase - Optional password for additional protection (default: '')
195
 * @returns 64-byte Uint8Array seed
196
 */
197
function mnemonicToSeedSync(mnemonic: string, passphrase: string = ''): Uint8Array;
198

199
/**
200
 * Derive 64-byte seed using native WebCrypto API with PBKDF2-SHA512 and 2048 iterations (async, irreversible)
201
 * @param mnemonic - 12-24 word mnemonic string
202
 * @param passphrase - Optional password for additional protection (default: '')
203
 * @returns Promise resolving to 64-byte Uint8Array seed
204
 */
205
function mnemonicToSeedWebcrypto(mnemonic: string, passphrase: string = ''): Promise<Uint8Array>;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { mnemonicToSeed, mnemonicToSeedSync, mnemonicToSeedWebcrypto } from '@scure/bip39';
212

213
const mnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
214

215
// Async version (recommended)
216
const seed = await mnemonicToSeed(mnemonic);
217
console.log(seed.length); // 64
218

219
// With passphrase for additional security
220
const seedWithPass = await mnemonicToSeed(mnemonic, 'my-secret-passphrase');
221

222
// Synchronous version (blocks execution)
223
const seedSync = mnemonicToSeedSync(mnemonic);
224

225
// WebCrypto version (faster in browsers)
226
const seedWebcrypto = await mnemonicToSeedWebcrypto(mnemonic, 'passphrase');
227
```
228

229
### Wordlist Support
230

231
@scure/bip39 supports 10 different language wordlists, each containing exactly 2048 words.
232

233
```typescript { .api }
234
// All wordlist modules export the same interface
235
interface WordlistModule {
236
  wordlist: string[];
237
}
238
```
239

240
**Available Wordlists:**
241

242
```typescript
243
// English (most commonly used)
244
import { wordlist } from '@scure/bip39/wordlists/english.js';
245

246
// Other supported languages
247
import { wordlist as czech } from '@scure/bip39/wordlists/czech.js';
248
import { wordlist as french } from '@scure/bip39/wordlists/french.js';
249
import { wordlist as italian } from '@scure/bip39/wordlists/italian.js';
250
import { wordlist as japanese } from '@scure/bip39/wordlists/japanese.js';
251
import { wordlist as korean } from '@scure/bip39/wordlists/korean.js';
252
import { wordlist as portuguese } from '@scure/bip39/wordlists/portuguese.js';
253
import { wordlist as simplifiedChinese } from '@scure/bip39/wordlists/simplified-chinese.js';
254
import { wordlist as spanish } from '@scure/bip39/wordlists/spanish.js';
255
import { wordlist as traditionalChinese } from '@scure/bip39/wordlists/traditional-chinese.js';
256
```
257

258
**Usage Examples:**
259

260
```typescript
261
import { generateMnemonic, validateMnemonic } from '@scure/bip39';
262
import { wordlist as english } from '@scure/bip39/wordlists/english.js';
263
import { wordlist as japanese } from '@scure/bip39/wordlists/japanese.js';
264

265
// Generate English mnemonic
266
const englishMnemonic = generateMnemonic(english);
267

268
// Generate Japanese mnemonic (uses ideographic space U+3000 as separator instead of regular space)
269
const japaneseMnemonic = generateMnemonic(japanese);
270
console.log(japaneseMnemonic); // Words separated by　(U+3000) instead of space
271

272
// Validate against specific language
273
const isValidEnglish = validateMnemonic(englishMnemonic, english);
274
const isValidJapanese = validateMnemonic(japaneseMnemonic, japanese);
275

276
// Cross-language validation will fail
277
const crossValidation = validateMnemonic(englishMnemonic, japanese); // false
278
```
279

280
## Types
281

282
```typescript { .api }
283
// All wordlists are arrays of exactly 2048 strings
284
type Wordlist = string[];
285

286
// Entropy byte arrays must be exactly 16, 20, 24, 28, or 32 bytes
287
// corresponding to 128, 160, 192, 224, or 256 bits respectively
288
type EntropyBytes = Uint8Array;
289

290
// Mnemonic strength must be exactly 128, 160, 192, 224, or 256 bits
291
// corresponding to 12, 15, 18, 21, or 24 words respectively
292
type MnemonicStrength = 128 | 160 | 192 | 224 | 256;
293

294
// Seed is always 64 bytes
295
type Seed = Uint8Array;
296
```
297

298
## Error Handling
299

300
The library throws specific errors for various invalid inputs:
301

302
- **TypeError**: 
303
  - "Invalid entropy" - for strength values not divisible by 32 or exceeding 256
304
  - "invalid mnemonic type: [type]" - for non-string mnemonic input
305
- **Error**: 
306
  - "Invalid mnemonic" - for mnemonics that don't have exactly 12, 15, 18, 21, or 24 words
307
  - "invalid entropy length" - for entropy arrays that aren't exactly 16, 20, 24, 28, or 32 bytes
308
  - "Wordlist: expected array of 2048 strings" - for wordlists that aren't arrays of exactly 2048 strings
309
  - "wordlist: non-string element: [element]" - for wordlists containing non-string elements
310

311
## Security Features
312

313
- **NFKD Unicode normalization** for all text inputs
314
- **Cryptographically secure random number generation** via `@noble/hashes`
315
- **Independent security audit** by Cure53 (January 2022)
316
- **Minimal dependency tree** (only 2 audited dependencies by the same author)
317
- **Standard compliance** with BIP39 specification
318
- **PBKDF2-SHA512 with 2048 iterations** for seed derivation (follows BIP39 standard)
319

320
## Performance Considerations
321

322
- **Tree-shakeable**: Unused wordlists are excluded from builds
323
- **WebCrypto variant**: `mnemonicToSeedWebcrypto` uses native browser APIs for better performance
324
- **Bundle size**: 14KB gzipped with one wordlist, 79KB with all wordlists
325
- **No source maps**: Excluded to keep package size minimal