0
# Mnemonic Management
1

2
BIP39-compatible mnemonic generation, validation, and seed derivation for creating human-readable backup phrases for cryptographic keys.
3

4
## Capabilities
5

6
### Mnemonic Generation
7

8
Generate cryptographically secure BIP39-compatible mnemonic phrases.
9

10
```typescript { .api }
11
/**
12
 * Generate a BIP39 mnemonic phrase
13
 * @param numWords - Number of words (12, 15, 18, 21, or 24)
14
 * @param wordlist - Optional custom wordlist (defaults to English)
15
 * @returns BIP39 mnemonic string
16
 */
17
function mnemonicGenerate(numWords?: 12 | 15 | 18 | 21 | 24, wordlist?: string[]): string;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { mnemonicGenerate } from "@polkadot/util-crypto";
24

25
// Generate 12-word mnemonic (default)
26
const mnemonic12 = mnemonicGenerate();
27
console.log(mnemonic12); // "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
28

29
// Generate 24-word mnemonic for higher security
30
const mnemonic24 = mnemonicGenerate(24);
31
console.log(mnemonic24.split(' ').length); // 24
32

33
// Generate 15-word mnemonic
34
const mnemonic15 = mnemonicGenerate(15);
35
```
36

37
### Mnemonic Validation
38

39
Validate BIP39 mnemonic phrases for correctness.
40

41
```typescript { .api }
42
/**
43
 * Validate a BIP39 mnemonic phrase
44
 * @param mnemonic - Mnemonic string to validate
45
 * @param wordlist - Optional custom wordlist
46
 * @returns true if mnemonic is valid
47
 */
48
function mnemonicValidate(mnemonic: string, wordlist?: string[]): boolean;
49
```
50

51
**Usage Example:**
52

53
```typescript
54
import { mnemonicGenerate, mnemonicValidate } from "@polkadot/util-crypto";
55

56
const mnemonic = mnemonicGenerate();
57
const isValid = mnemonicValidate(mnemonic);
58
console.log("Valid mnemonic:", isValid); // true
59

60
// Test invalid mnemonic
61
const invalid = "invalid mnemonic phrase here";
62
const isInvalid = mnemonicValidate(invalid);
63
console.log("Invalid mnemonic:", isInvalid); // false
64
```
65

66
### Mnemonic to Mini Secret
67

68
Convert mnemonic to mini secret for sr25519 key derivation.
69

70
```typescript { .api }
71
/**
72
 * Convert mnemonic to mini secret (32 bytes)
73
 * @param mnemonic - BIP39 mnemonic phrase
74
 * @param password - Optional password for additional security
75
 * @returns 32-byte mini secret for sr25519
76
 */
77
function mnemonicToMiniSecret(mnemonic: string, password?: string): Uint8Array;
78
```
79

80
**Usage Example:**
81

82
```typescript
83
import { 
84
  mnemonicGenerate, 
85
  mnemonicToMiniSecret, 
86
  sr25519PairFromSeed 
87
} from "@polkadot/util-crypto";
88

89
const mnemonic = mnemonicGenerate();
90

91
// Without password
92
const seed = mnemonicToMiniSecret(mnemonic);
93
const pair = sr25519PairFromSeed(seed);
94

95
// With password for additional security
96
const seedWithPassword = mnemonicToMiniSecret(mnemonic, "my-secure-password");
97
const pairWithPassword = sr25519PairFromSeed(seedWithPassword);
98
```
99

100
### Mnemonic to Legacy Seed
101

102
Convert mnemonic to legacy seed format for backward compatibility.
103

104
```typescript { .api }
105
/**
106
 * Convert mnemonic to BIP39-compatible seed (deprecated - use mnemonicToMiniSecret for new projects)
107
 * @param mnemonic - BIP39 mnemonic phrase
108
 * @param password - Optional password for seed derivation (default: '')
109
 * @param onlyJs - Optional: force JavaScript implementation (default: false)
110
 * @param byteLength - Optional: seed length 32 or 64 bytes (default: 32)
111
 * @param rounds - Optional: PBKDF2 iterations (default: 2048)
112
 * @returns Seed bytes for compatibility with Bitcoin/Ethereum wallets
113
 */
114
function mnemonicToLegacySeed(mnemonic: string, password?: string, onlyJs?: boolean, byteLength?: 32 | 64, rounds?: number): Uint8Array;
115
```
116

117
**Usage Example:**
118

119
```typescript
120
import { mnemonicToLegacySeed, ed25519PairFromSeed } from "@polkadot/util-crypto";
121

122
const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
123
const legacySeed = mnemonicToLegacySeed(mnemonic);
124

125
// Use first 32 bytes for ed25519
126
const pair = ed25519PairFromSeed(legacySeed.slice(0, 32));
127
```
128

129
### Mnemonic to Entropy
130

131
Extract entropy from a BIP39 mnemonic phrase.
132

133
```typescript { .api }
134
/**
135
 * Convert mnemonic to entropy bytes
136
 * @param mnemonic - BIP39 mnemonic phrase
137
 * @param wordlist - Optional custom wordlist
138
 * @returns Entropy bytes (16, 20, 24, 28, or 32 bytes)
139
 */
140
function mnemonicToEntropy(mnemonic: string, wordlist?: string[]): Uint8Array;
141
```
142

143
**Usage Example:**
144

145
```typescript
146
import { mnemonicGenerate, mnemonicToEntropy } from "@polkadot/util-crypto";
147

148
const mnemonic = mnemonicGenerate(12);
149
const entropy = mnemonicToEntropy(mnemonic);
150
console.log(entropy.length); // 16 bytes for 12-word mnemonic
151

152
const mnemonic24 = mnemonicGenerate(24);
153
const entropy24 = mnemonicToEntropy(mnemonic24);
154
console.log(entropy24.length); // 32 bytes for 24-word mnemonic
155
```
156

157
## Complete Workflow Example
158

159
```typescript
160
import { 
161
  cryptoWaitReady,
162
  mnemonicGenerate,
163
  mnemonicValidate,
164
  mnemonicToMiniSecret,
165
  sr25519PairFromSeed,
166
  encodeAddress
167
} from "@polkadot/util-crypto";
168

169
async function createAccount() {
170
  // Initialize crypto
171
  await cryptoWaitReady();
172
  
173
  // Generate mnemonic
174
  const mnemonic = mnemonicGenerate(24);
175
  console.log("Mnemonic:", mnemonic);
176
  
177
  // Validate mnemonic
178
  if (!mnemonicValidate(mnemonic)) {
179
    throw new Error("Invalid mnemonic generated");
180
  }
181
  
182
  // Convert to seed with password
183
  const password = "my-secure-password";
184
  const seed = mnemonicToMiniSecret(mnemonic, password);
185
  
186
  // Generate key pair
187
  const pair = sr25519PairFromSeed(seed);
188
  
189
  // Generate address
190
  const address = encodeAddress(pair.publicKey, 0); // Polkadot network
191
  
192
  return {
193
    mnemonic,
194
    address,
195
    publicKey: pair.publicKey
196
  };
197
}
198
```
199

200
## Security Best Practices
201

202
### Mnemonic Storage
203
- Store mnemonics securely offline (paper backup, hardware wallet)
204
- Never store mnemonics in plain text files or databases
205
- Consider splitting mnemonics using Shamir's Secret Sharing
206
- Use strong passwords when deriving seeds
207

208
### Entropy Quality
209
- Use system random number generator for mnemonic generation
210
- Verify entropy quality in production environments
211
- Consider hardware random number generators for high-security applications
212

213
### Password Protection
214
- Use strong, unique passwords for mnemonic-to-seed conversion
215
- Store passwords separately from mnemonics
216
- Consider using key stretching for password-based derivation
217

218
## Mnemonic Word Counts and Security
219

220
| Words | Entropy | Security Level |
221
|-------|---------|----------------|
222
| 12    | 128 bits | Standard      |
223
| 15    | 160 bits | Enhanced      |
224
| 18    | 192 bits | High          |
225
| 21    | 224 bits | Very High     |
226
| 24    | 256 bits | Maximum       |
227
228
## BIP39 Compliance
229

230
- Fully compatible with BIP39 standard
231
- Supports English wordlist by default
232
- Checksum validation prevents typos
233
- Compatible with hardware wallets and other BIP39 implementations