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. Extended keys can be used to securely generate as many addresses as needed through key derivation. This allows for long-term, reusable wallet with a single backup.
Moreover, you can use an extended private key to:
generate extended public keys
derive extended keys using standard bip44 or a custom path
restore keys from mnemonic codes, seeds and serialized form
INTERFACE
Attributes
network
Instance of Bitcoin::Crypto::Network - current network for this key. Can be coerced from network id. Default: current default network.
writer: set_network
purpose
BIP44 purpose which was used to obtain this key. Filled automatically when deriving an extended key. If the key was not obtained through BIP44 derivation, this attribute is undef.
writer: set_purpose
clearer: clear_purpose
depth
Integer - depth of derivation. Default: 0 (master key)
parent_fingerprint
Bytestring of length 4 - fingerprint of the parent key. Default: four zero bytes
child_number
Integer - sequence number of the key on the current "depth". Default: 0
chain_code
Bytestring of length 32 - chain code of the extended key.
Methods
new
Constructor is reserved for internal and advanced use only. Use "from_mnemonic", "from_seed" or "from_serialized" instead.
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 want to validate if $mnemonic is a valid mnemonic you must 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.
to_serialized
$serialized = $object->to_serialized()Returns the key serialized in format specified in BIP32 as byte string.
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.
set_network
$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.
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