README

PHP implementation of BIP-0039 supporting:

Generate mnemonic (12–24 words) from secure random entropy
Convert provided entropy (hex) to mnemonic
Convert mnemonic back to original entropy (checksum verified)
Derive seed (512-bit) from mnemonic + optional passphrase (PBKDF2-HMAC-SHA512 / 2048 rounds)
Validate mnemonics
All official BIP-39 wordlists (English, Chinese (Simplified & Traditional), Czech, French, Italian, Japanese, Korean, Portuguese, Spanish)
Unicode NFKD normalization (when ext-intl is available)

Installation

composer require nyra/bip39

(For development / running tests clone the repo and run composer install.)

Optional: install ext-intl for full Unicode NFKD normalization; a graceful fallback is used if missing.

Usage

<?php
require __DIR__ . '/vendor/autoload.php';

use Nyra\Bip39\Bip39;

// 1. Generate a random 12-word mnemonic (128 bits entropy, English)
$mnemonic = Bip39::generateMnemonic();

// 2. Generate with different entropy (e.g. 256 bits => 24 words)
$mnemonic24 = Bip39::generateMnemonic(256);

// 3. Convert existing entropy (hex) to mnemonic
$entropyHex = '00000000000000000000000000000000';
$mnemonicFromEntropy = Bip39::entropyToMnemonic($entropyHex);

// 4. Convert mnemonic back to entropy
$roundTripEntropy = Bip39::mnemonicToEntropy($mnemonicFromEntropy); // == $entropyHex

// 5. Derive seed (binary or hex) with passphrase (e.g. official test vectors use "TREZOR")
$seedBin = Bip39::mnemonicToSeed($mnemonic, 'TREZOR');
$seedHex = Bip39::mnemonicToSeedHex($mnemonic, 'TREZOR');

// 6. Validate mnemonic
if (!Bip39::isValidMnemonic($mnemonic)) {
    throw new RuntimeException('Invalid mnemonic');
}

// 7. List supported languages
$languages = Bip39::languages(); // [ 'chinese_simplified', 'chinese_traditional', 'czech', ... ]

// 8. Generate mnemonics in other languages
$frenchMnemonic = Bip39::generateMnemonic(128, 'french');
$koreanMnemonic = Bip39::generateMnemonic(256, 'korean');

// 9. Work with Japanese (uses full-width ideographic separator U+3000 between words)
$japaneseEntropy = '00000000000000000000000000000000';
$japaneseMnemonic = Bip39::entropyToMnemonic($japaneseEntropy, 'japanese');
// Example (fragment): "あいこくしん　あいこくしん　..."
$back = Bip39::mnemonicToEntropy($japaneseMnemonic, 'japanese');

Multi-language Notes

Pass the language identifier as the second argument to generateMnemonic, entropyToMnemonic, mnemonicToEntropy, mnemonicToSeed, and mnemonicToSeedHex.
Language identifiers correspond to the .txt filenames in resources/wordlist/ (without extension).
Japanese mnemonics are serialized with an ideographic space (U+3000) between words per BIP-39. This library:
- Uses the proper full-width space when generating Japanese mnemonics.
- Accepts input containing only ASCII spaces OR only full-width spaces, but rejects mixed usage to avoid ambiguous normalization.
- Normalizes ASCII spaces to the full-width separator internally.
All other languages use a standard ASCII space.

API Summary

Method	Description
`Bip39::generateMnemonic(int $entropyBits = 128, string $language = 'english')`	Secure random mnemonic (entropy bits: 128,160,192,224,256) in given language
`Bip39::entropyToMnemonic(string $entropyHex, string $language = 'english')`	Hex entropy to mnemonic
`Bip39::mnemonicToEntropy(string $mnemonic, string $language = 'english')`	Mnemonic back to entropy hex (validates checksum)
`Bip39::mnemonicToSeed(string $mnemonic, string $passphrase = '', string $lang='english')`	64-byte binary seed
`Bip39::mnemonicToSeedHex(string $mnemonic, string $passphrase = '', string $lang='english')`	Seed as hex
`Bip39::isValidMnemonic(string $mnemonic, string $language = 'english')`	Quick validation helper
`Bip39::languages(): array`	List of supported language identifiers

Testing

composer install
composer test

Security Notes

Only the checksum distinguishes valid from invalid mnemonics with same word count; always validate before using.
A wrong passphrase yields a different (valid) seed (plausible deniability).
Keep entropy and mnemonic generation on secure / trusted systems.

Normalization & Unicode

If ext-intl is installed, both mnemonic and passphrase are normalized with Unicode NFKD before seed derivation. This ensures canonically equivalent sequences (e.g. composed vs decomposed accents) produce identical seeds.

License

MIT

Acknowledgements

Wordlists & reference vectors: Trezor team & BIP authors. This implementation reuses the publicly specified word lists ( MIT License).

nyra / bip39

Maintainers

Details