furqansiddiqui/bip39-mnemonic-php

BIP39 Mnemonics implementation in PHP

0.2.1 2024-08-04 14:24 UTC

Requires

• php-64bit: ^8.2
• ext-mbstring: *
• charcoal-dev/buffers: ^0.1.0

MIT

• mnemonics
• bip39
• BIP-0039

README

Mnemonic BIP39 implementation in PHP

Installation

Prerequisite

• PHP ^8.2
• ext-mbstring (MultiByte string PHP ext. for non-english wordlist)

Composer

composer require furqansiddiqui/bip39-mnemonic-php

Generating a Secure Mnemonic

Generate a mnemonic using a secure PRNG implementation.

BIP39::fromRandom

Returns instance of Mnemonic class.

Example:

// Generate entropy using PRNG
$mnemonic = \FurqanSiddiqui\BIP39\BIP39::fromRandom(
    \FurqanSiddiqui\BIP39\Language\English::getInstance(),
    wordCount: 12
);

# array(12) { [0]=> string(4) "tape" [1]=> string(8) "solution" ... [10]=> string(6) "border" [11]=> string(6) "sample" }
var_dump($mnemonic->words);
# string(32) "ddd9dbcd1b07a09c16f080637818675f"
var_dump($mnemonic->entropy);

Entropy to Mnemonic

Generate mnemonic codes from given entropy

BIP39::fromRandom

Returns instance of Mnemonic class.

Example:

$mnemonic = \FurqanSiddiqui\BIP39\BIP39::fromEntropy(
    \Charcoal\Buffers\Buffer::fromBase16("ddd9dbcd1b07a09c16f080637818675f"),
    \FurqanSiddiqui\BIP39\Language\English::getInstance()
);

# array(12) { [0]=> string(4) "tape" [1]=> string(8) "solution" ... [10]=> string(6) "border" [11]=> string(6) "sample" }
var_dump($mnemonic->words);

Mnemonic sentence/Words to Mnemonic

Generate entropy from mnemonic codes

BIP39::fromWords

Returns instance of Mnemonic class.

Example:

$mnemonic = \FurqanSiddiqui\BIP39\BIP39::fromWords(
    ["tape", "solution", "viable", "current", "key",
        "evoke", "forward", "avoid", "gloom", "school", "border", "sample"],
    \FurqanSiddiqui\BIP39\Language\English::getInstance()
);

#string(32) "ddd9dbcd1b07a09c16f080637818675f"
var_dump($mnemonic->entropy);

Mnemonic Class

readonly class Mnemonic

This lib will create this Mnemonic object as a result:

Generating Seed with Passphrase

Mnemonic->generateSeed

Generates seed from a mnemonic as per BIP39 specifications.

Returns:

Generate non-english mnemonic codes

Check AbstractLanguage and AbstractLanguageFile classes. English class has all 2048 words pre-loaded instead of reading from a local file every time. To implement other languages or custom set of 2048 words, check ChineseWords.php file in tests directory for example of implementation.

class CustomWords extends \FurqanSiddiqui\BIP39\Language\AbstractLanguageFile
{
    /**
     * @return static
     */
    protected static function constructor(): static
    {
        return new static(
            language: "some_language",
            words: static::wordsFromFile(
                pathToFile: "/path/to/wordlist.txt",
                eolChar: PHP_EOL
            ),
            mbEncoding: "UTF-8"
        );
    }
}

and then use in place of AbstractLanguage where required:

CustomWords::getInstance()

Test Vectors

Include PHPUnit tests for all test vectors mentioned in official BIP-0039 specification. Use following command to execute all tests using phpunit.phar

php phpunit.phar --bootstrap vendor/autoload.php tests/