NAME

Bitcoin::Crypto::Key::ExtPrivate - class for Bitcoin extended private keys

SYNOPSIS

        use Bitcoin::Crypto::Key::ExtPrivate;

        # generate mnemonic words first
        my $mnemonic = Bitcoin::Crypto::Key::ExtPrivate->generate_mnemonic;
        print "Your mnemonic is: $mnemonic";

        # create ExtPrivateKey from mnemonic (without password)
        my $key = Bitcoin::Crypto::Key::ExtPrivate->from_mnemonic($mnemonic);
        my $ser_key = $key->to_serialized_base58;
        print "Your exported master key is: $ser_key";

        # derive child private key
        my $path = "m/0'";
        my $child_key = $key->derive_key($path);
        my $ser_child_key = $child_key->to_serialized_base58;
        print "Your exported $path child key is: $ser_child_key";

        # create basic keypair
        my $basic_private = $child_key->get_basic_key;
        my $basic_public = $child_key->get_public_key->get_basic_key;

DESCRIPTION

This class allows you to create an extended private key instance.

You can use an extended private key to:

  • generate extended public keys

  • derive extended keys using a path

  • restore keys from mnemonic codes, seeds and base58 format

see Bitcoin::Crypto::Network if you want to work with other networks than Bitcoin Mainnet.

METHODS

generate_mnemonic

        sig: generate_mnemonic($class, $len = 128, $lang = "en")

Generates a new mnemonic code. Default entropy is 128 bits. With $len this can be changed to up to 256 bits with 32 bit step.

Other languages than english require additional modules for Bitcoin::BIP39.

Dies when $len is invalid (under 128, above 256 or not divisible by 32). Returns newly generated BIP39 mnemonic string.

In some environments a problem may be encountered that causes the secure random bytes generator to block the program execution (See "BLOCKING ENTROPY SOURCE" in Bytes::Random::Secure). In this case you can use mnemonic_from_entropy and pass in entropy generated by Bytes::Random::Secure in non-blocking mode (via the OO interface).

mnemonic_from_entropy

        sig: mnemonic_from_entropy($class, $bytes, $lang = "en")

Generates a new mnemonic code from custom entropy given in $bytes (a bytestring). This entropy should be of the same bit size as in "generate_mnemonic". Returns newly generated BIP39 mnemonic string.

This can be useful to avoid relying on the underlying implementation of Bitcoin::BIP39.

Another use would be implementing one's own entropy source that can be truly random, not just cryptographically-secure. A popular example would be capturing user's mouse movements.

Be aware that the method you use to generate a mnemonic will be a very important factor in your key's security. If possible, use real sources of randomness (not pseudo-random) or a cryptographically secure pseduo-random number generator like the one used by Bytes::Random::Secure.

from_mnemonic

        sig: from_mnemonic($class, $mnemonic, $password = "", $lang = undef)

Creates a new key from given mnemonic and password.

Note that technically any password is correct and there's no way to tell if it was mistaken.

If you need to validate if $mnemonic is a valid mnemonic you should specify $lang, e.g. "en".

If no $lang is given then any string passed as $mnemonic will produce a valid key.

Returns a new instance of this class.

from_seed

        sig: from_seed($class, $seed)

Creates and returns a new key from seed, which can be any data of any length. $seed is expected to be a byte string.

from_hex_seed

        sig: from_hex_seed($class, $seed)

Same as from_seed, but $seed is treated as hex string.

to_serialized

        sig: to_serialized($self)

Returns the key serialized in format specified in BIP32 as byte string.

to_serialized_base58

        sig: to_serialized_base58($self)

Behaves the same as to_serialized(), but performs Base58Check encoding on the resulting byte string.

from_serialized

        sig: from_serialized($class, $serialized, $network = undef)

Tries to unserialize byte string $serialized with format specified in BIP32.

Dies on errors. If multiple networks match serialized data specify $network manually (id of the network) to avoid exception.

from_serialized_base58

        sig: from_serialized_base58($class, $base58, $network = undef)

Same as from_serialized, but performs Base58Check decoding on $base58 argument.

set_network

        sig: set_network($self, $val)

Change key's network state to $val. It can be either network name present in Bitcoin::Crypto::Network package or an instance of this class.

Returns current key instance.

get_public_key

        sig: get_public_key($self)

Returns instance of Bitcoin::Crypto::Key::ExtPublic generated from the private key.

get_basic_key

        sig: get_basic_key($self)

Returns the key in basic format: Bitcoin::Crypto::Key::Private

derive_key

        sig: derive_key($self, $path)

Performs extended key derivation as specified in BIP32 on the current key with $path. Dies on error.

See BIP32 document for details on derivation paths and methods.

Returns a new extended key instance - result of a derivation.

get_fingerprint

        sig: get_fingerprint($self, $len = 4)

Returns a fingerprint of the extended key of $len length (byte string)

EXCEPTIONS

This module throws an instance of Bitcoin::Crypto::Exception if it encounters an error. It can produce the following error types from the Bitcoin::Crypto::Exception namespace:

  • MnemonicGenerate - mnemonic couldn't be generated correctly

  • MnemonicCheck - mnemonic didn't pass the validity check

  • KeyDerive - key couldn't be derived correctly

  • KeyCreate - key couldn't be created correctly

  • NetworkConfig - incomplete or corrupted network configuration

SEE ALSO

Bitcoin::Crypto::Key::ExtPublic
Bitcoin::Crypto::Network