NAME
Bitcoin::Crypto::Network - Network management class
SYNOPSIS
use Bitcoin::Crypto::Network;
# the default network is Bitcoin Mainnet
# get() without arguments returns default network
Bitcoin::Crypto::Network->get->name; # 'Bitcoin Mainnet'
# by default there are two networks specified
# find() without arguments returns a list of all network ids
Bitcoin::Crypto::Network->find; # list of strings
# you can get full network configuration with get() using network id
Bitcoin::Crypto::Network->get('bitcoin_testnet')->name; # 'Bitcoin Testnet'
# search for network and get array of keys in return
# there will be multiple results if your search is matched
# by multiple networks
Bitcoin::Crypto::Network->find(sub { shift->name eq 'Bitcoin Mainnet' }); # ('bitcoin')
Bitcoin::Crypto::Network->find(sub { shift->p2pkh_byte eq "\x6f" }); # ('bitcoin_testnet')
# if you're working with cryptocurrency other than Bitcoin you need to add a new network
# network configuration is important for importing WIF private keys (network
# recognition), generating addresses and serializing extended keys.
# It may also hold other data specific to a network
# register() can be used to create a network
my $litecoin = Bitcoin::Crypto::Network->register(
id => 'litecoin',
name => 'Litecoin Mainnet',
p2pkh_byte => "\x30",
wif_byte => "\xb0",
);
# after you've added a new network you can set it as a default. This means that
# all extended keys generated by other means than importing serialized key and
# all private keys generated by other means than importing WIF / extended keys
# will use that configuration.
$litecoin->set_default;DESCRIPTION
This package allows you to manage non-bitcoin cryptocurrencies or chains other than mainnet. Before you start producing keys and addresses for your favorite crypto you have to configure its network first.
PREDEFINED NETWORKS
Here is a list of networks that are already defined and can be used out of the box.
If you want to see more predefined networks added and you're willing to make some research to find out the correct values for the configuration fields, consider opening a pull request on Github.
Bitcoin Mainnet
defined with id: bitcoin
Bitcoin Testnet
defined with id: bitcoin_testnet
Dogecoin Mainnet
defined with id: dogecoin
Dogecoin Testnet
defined with id: dogecoin_testnet
CONFIGURATION
Configuration fields marked with (*) are required. The rest are optional, but some functions of the system will refuse to work without them.
my %config = (
id => "(*) string identifier for the network, eg. 'bitcoin'",
name => "(*) human-readable network name, eg. 'Bitcoin Mainnet'",
p2pkh_byte => "(*) p2pkh address prefix byte, eg. 0x00",
wif_byte => "(*) WIF private key prefix byte, eg. 0x80",
p2sh_byte => "p2sh address prefix byte, eg. 0x05",
segwit_hrp => "segwit native address human readable part, eg. 'bc'",
extprv_version => "version prefix of serialized extended private keys, eg. 0x0488ade4",
extpub_version => "version prefix of serialized extended public keys, eg. 0x0488b21e",
extprv_compat_version => "same as extprv_version, but for BIP49",
extpub_compat_version => "same as extpub_version, but for BIP49",
extprv_segwit_version => "same as extprv_version, but for BIP84",
extpub_segwit_version => "same as extpub_version, but for BIP84",
bip44_coin => "bip44 coin number, eg. 0",
);You can then register this network:
Bitcoin::Crypto::Network->register(%config);Your program will now be able to import keys for that network but all keys created from other sources will be treated as the default (Bitcoin). You need to set_default to make all new keys use it. If your usage is not restrained to a single network, it might be better to set a network manually to a single key with its set_network method:
$priv->set_network('network_id');Remember that if you don't specify network field for some feature you won't be able to use it. For example, the module will complain if you try to generate segwit address without segwit_hrp field set.
METHODS
single_network
$boolean = $class->single_network()Returns a boolean indicating whether the module is operating in a single-network mode. In this mode, creation of objects with any other network than default is disallowed and will raise an exception. If any keys already exist and they have a different network set, they will continue to work but it will become impossible to alter them or get any kind of derived keys from them.
This mode may be useful to make sure you are not importing keys with unwanted networks. By default, the module operates in multi-network mode and allows each key and script to set its own network, which can sometimes yield surprising results.
See "set_single".
register
$network_object = $class->register(%config)
$network_object = $object->register()Adds a network instance to a list of known networks.
Calls "new" with keys present in %config hash when called in class context.
Returns the network instance.
unregister
my $network_object = $object->unregister()Does the opposite of "register". The network object will no longer be stored in the module, so it will be destroyed if you let go of its reference.
Can be useful if some of the default networks are interferring with your use case.
set_default
$network_object = $object->set_default()Sets a network as the default one. All newly created private and public keys will be bound to this network.
Returns the network instance.
set_single
$network_object = $object->set_single()Same as "set_default", but makes the module go into single-network mode. To go back from this mode, call "set_default" on any Network object.
supports_segwit
$bool = $object->supports_segwit()Returns a boolean which can be used to determine whether a given network has SegWit configured.
new
$network_object = $class->new(%config)Creates a new network instance. See "CONFIGURATION" for a list of possible %config keys.
get
$network_object = $class->get($id = undef)Without arguments, returns the default network configuration as the Bitcoin::Crypto::Network instance.
With the $id argument (string), returns the instance of a configuration matching the id.
Throws an exception if network doesn't exist.
find
@network_objects = $class->find($sub = undef)Without arguments, returns a list of all registered network identifiers.
With the $sub argument (coderef), searches for all networks that pass the criteria and returns their ids. The $sub will be passed all the instances of registered networks, one at a time. If must perform required checks and return a boolean value. All the networks that pass this test will be returned. Example:
sub {
my $instance = shift;
return $instance->name eq 'Some name';
}Returns a list of network instance ids (strings).