The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

SYNOPSIS

        use Bitcoin::Crypto qw(btc_extprv);
        use Bitcoin::Crypto::Util qw(generate_mnemonic to_format)

        # generate mnemonic words first
        my $mnemonic = generate_mnemonic;
        print "Your mnemonic is: $mnemonic";

        # create ExtPrivateKey from mnemonic (without password)
        my $key = btc_extprv->from_mnemonic($mnemonic);
        my $ser_key = to_format [base58 => $key->to_serialized];
        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 = to_format [base58 => $child_key->to_serialized];
        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

new

Constructor is reserved for internal and advanced use only. Use "from_mnemonic", "from_seed" or "from_serialized" instead.

generate_mnemonic

        $mnemonic = $class->generate_mnemonic($len = 128, $lang = 'en')

Deprecated - see "generate_mnemonic" in Bitcoin::Crypto::Util.

mnemonic_from_entropy

        $mnemonic = $class->mnemonic_from_entropy($bytes, $lang = 'en')

Deprecated - see "mnemonic_from_entropy" in Bitcoin::Crypto::Util.

from_mnemonic

        $key_object = $class->from_mnemonic($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'. It will also get rid of any extra whitespace before / after / in between words.

If no $lang is given then any string passed as $mnemonic will produce a valid key. This means even adding whitespace (eg. trailing newline) will produce a different key. Be careful when using this method without $lang argument as you can easily create keys incompatible with other software due to these whitespace problems.

Returns a new instance of this class.

Important note about unicode: this function only accepts UTF8-decoded strings (both $mnemonic and $password), but can't detect whether it got it or not. This will only become a problem if you use non-ascii mnemonic and/or password. If there's a possibility of non-ascii, always use utf8 and set binmodes to get decoded (wide) characters to avoid problems recovering your wallet.

from_seed

        $key_object = $class->from_seed($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

Deprecated. Use $class->from_seed([hex => $seed]) instead.

to_serialized

        $serialized = $object->to_serialized()

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

to_serialized_base58

Deprecated. Use to_format [base58 => $key->to_serialized] instead.

from_serialized

        $key_object = $class->from_serialized($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

Deprecated. Use $class->from_serialized([base58 => $base58]) instead.

set_network

        $key_object = $object->set_network($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

        $public_key_object = $object->get_public_key()

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

get_basic_key

        $basic_key_object = $object->get_basic_key()

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

derive_key

        $derived_key_object = $object->derive_key($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.

derive_key_bip44

        $derived_key_object = $object->derive_key_bip44(%data)

A helper that constructs a Bitcoin::Crypto::BIP44 path from %data and calls "derive_key" with it. Refer to "Attributes" in Bitcoin::Crypto::BIP44 to see what you can include in %data.

Using this method instead of specifying BIP44 path yourself will make sure all features of BIP44 derivation will be enabled, like different prefixes for extended keys (xprv / yprv / zprv) and address type generation checking.

Note: coin_type parameter will be ignored, and the current network configuration set in the extended key will be used.

get_fingerprint

        $fingerprint = $object->get_fingerprint($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