# Class BSV::Primitives::Mnemonic <a id="class-BSV-Primitives-Mnemonic"></a>

**Inherits:** `Object`

BIP-39 mnemonic phrase generation and seed derivation.

Generates human-readable mnemonic phrases from random entropy, validates
existing phrases (word count, vocabulary, checksum), and derives 512-bit seeds
for HD key generation via PBKDF2.

**@example Generate a mnemonic and derive a master key**
```ruby
mnemonic = BSV::Primitives::Mnemonic.generate
mnemonic.phrase #=> "abandon ability able ..."
master = mnemonic.to_extended_key
master.derive_path("m/44'/0'/0'/0/0")
```

**@example Import an existing mnemonic phrase**
```ruby
mnemonic = BSV::Primitives::Mnemonic.from_phrase('zoo zoo ... wrong')
mnemonic.valid? #=> true
```

## Constants
### `ENGLISH_WORDLIST` <a id="constant-ENGLISH_WORDLIST"></a> <a id="ENGLISH_WORDLIST-constant"></a>
rubocop:disable Metrics/CollectionLiteralLength

### `ENGLISH_WORD_MAP` <a id="constant-ENGLISH_WORD_MAP"></a> <a id="ENGLISH_WORD_MAP-constant"></a>
rubocop:enable Metrics/CollectionLiteralLength

### `PBKDF2_ITERATIONS` <a id="constant-PBKDF2_ITERATIONS"></a> <a id="PBKDF2_ITERATIONS-constant"></a>
PBKDF2 iteration count per BIP-39 specification.

### `PBKDF2_KEY_LENGTH` <a id="constant-PBKDF2_KEY_LENGTH"></a> <a id="PBKDF2_KEY_LENGTH-constant"></a>
Output key length in bytes for PBKDF2 (512 bits).

### `VALID_STRENGTHS` <a id="constant-VALID_STRENGTHS"></a> <a id="VALID_STRENGTHS-constant"></a>
Valid entropy strengths in bits (128 = 12 words, 256 = 24 words).

## Attributes
### `phrase` [R] <a id="attribute-i-phrase"></a> <a id="phrase-instance_method"></a>
- **@return** [String] the space-separated mnemonic phrase

### `words` [R] <a id="attribute-i-words"></a> <a id="words-instance_method"></a>
- **@return** [Array<String>] the individual mnemonic words

## Public Class Methods
### `from_entropy(entropy)` <a id="method-c-from_entropy"></a> <a id="from_entropy-class_method"></a>
Create a mnemonic from raw entropy bytes.
- **@param** `entropy` [String] 16, 20, 24, 28, or 32 bytes of entropy
- **@raise** [ArgumentError] if entropy length is invalid
- **@return** [Mnemonic]

### `from_phrase(phrase)` <a id="method-c-from_phrase"></a> <a id="from_phrase-class_method"></a>
Import and validate an existing mnemonic phrase.

Normalises the phrase (NFKD, whitespace), validates word count, vocabulary,
and checksum.
- **@param** `phrase` [String] space-separated mnemonic words
- **@raise** [ArgumentError] if word count, vocabulary, or checksum is invalid
- **@return** [Mnemonic]

### `generate(strength: = 128)` <a id="method-c-generate"></a> <a id="generate-class_method"></a>
Generate a new random mnemonic phrase.
- **@param** `strength` [Integer] entropy bits (128, 160, 192, 224, or 256)
- **@raise** [ArgumentError] if strength is not a valid value
- **@return** [Mnemonic] a new mnemonic with valid checksum

## Public Instance Methods
### `==(other)` <a id="method-i--3D-3D"></a> <a id="==-instance_method"></a>
- **@param** `other` [Object] the object to compare
- **@return** [Boolean] +true+ if both mnemonics have the same phrase

### `to_entropy()` <a id="method-i-to_entropy"></a> <a id="to_entropy-instance_method"></a>
Extract the original entropy bytes from this mnemonic.
- **@return** [String] the entropy bytes

### `to_extended_key(passphrase: = '', network: = :mainnet)` <a id="method-i-to_extended_key"></a> <a id="to_extended_key-instance_method"></a>
Derive a BIP-32 master extended key from this mnemonic.

Convenience method equivalent to +ExtendedKey.from_seed(to_seed)+.
- **@param** `passphrase` [String] optional BIP-39 passphrase
- **@param** `network` [Symbol] +:mainnet+ or +:testnet+
- **@return** [ExtendedKey] the master private extended key

### `to_s()` <a id="method-i-to_s"></a> <a id="to_s-instance_method"></a>
- **@return** [String] the mnemonic phrase

### `to_seed(passphrase: = '')` <a id="method-i-to_seed"></a> <a id="to_seed-instance_method"></a>
Derive a 512-bit seed from this mnemonic using PBKDF2-HMAC-SHA-512.
- **@param** `passphrase` [String] optional passphrase (default: empty string)
- **@return** [String] 64-byte seed

### `valid?()` <a id="method-i-valid-3F"></a> <a id="valid?-instance_method"></a>
Validate the mnemonic's word count, vocabulary, and checksum.
- **@return** [Boolean] +true+ if the mnemonic is valid