The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Bitcoin-Crypto-0.995
River stage one • 2 direct dependents • 3 total dependents
5 ++
/ Bitcoin::Crypto

NAME

Bitcoin::Crypto - Bitcoin cryptography in Perl

SYNOPSIS

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

        # extended keys are used for mnemonic generation and key derivation
        my $mnemonic = Bitcoin::Crypto::Key::ExtPrivate->generate_mnemonic();
        say "your mnemonic code is: $mnemonic";

        my $master_key = Bitcoin::Crypto::Key::ExtPrivate->from_mnemonic($mnemonic);
        my $derived_key = $master_key->derive_key("m/0'");

        # basic keys are used for signatures and addresses
        my $priv = $derived_key->get_basic_key();
        my $pub = $priv->get_public_key();

        say "private key: " . $priv->to_wif();
        say "public key: " . $pub->to_hex();
        say "address: " . $pub->get_segwit_address();

        my $message = "Hello CPAN";
        my $signature = $priv->sign_message($message);

        if ($pub->verify_message($message, $signature)) {
                say "successfully signed message '$message'";
                say "signature: " . unpack "H*", $signature;
        }

DESCRIPTION

Cryptographic module for common Bitcoin-related tasks and key pair management.

SCOPE

This module allows you to do basic tasks for Bitcoin such as:

  • creating extended keys and utilizing bip32 key derivation

  • creating private key / public key pairs

  • address generation (in legacy, compatibility and segwit formats)

  • signature generation and verification

  • importing / exporting using popular mediums (WIF, mnemonic, hex)

  • using custom (non-Bitcoin) networks

This package won't help you with:

  • serializing transactions

  • using any Bitcoin CLI tools / clients

  • connecting to Bitcoin network

WHERE TO START?

Documentation and examples in this module assump that you're already familiar with the basics of Bitcoin protocol and asymmetric cryptography. If that's not the case, start with learning about those topics.

If you like to learn by example, dive right into the examples directory.

There are many things that you may want to achieve with this module. Common topics include:

  • create a key pair for signature or address generation

    Start with Bitcoin::Crypto::Key::Private if you already have some data you want to use as a private key entropy (like Bitcoin's WIF format or hex data). If you'd like to generate a key and get a list of words, Bitcoin::Crypto::Key::ExtPrivate is what you want.

  • generate many keys at once

    Bitcoin::Crypto::Key::ExtPrivate will allow you to derive as many keys as you want from a master key, so you won't have to store multiple private key seeds. Bitcoin::Crypto::Key::ExtPublic can be stored in a "hot" storage - a place which can be hacked into, like a website's database - and used to derive public keys lazily.

  • work with other cryptocurrencies

    You can work with any cryptocurrency as long as it is based on the same fundamentals as Bitcoin. You have to register a network in Bitcoin::Crypto::Network first, with the protocol data valid for your cryptocurrency.

  • serialize a Bitcoin script

    Bitcoin::Crypto::Script will help you build and serialize a script, but not run it.

  • work with Bitcoin-related encodings

    See Bitcoin::Crypto::Base58 and Bitcoin::Crypto::Bech32.

HOW TO READ THE DOCUMENTATION?

Most functions in this documentation have a code line starting with sig:. These lines are there to inform you about the expected arguments on input.

The first argument is usually an object instance (denoted as $self) or just a class name ($class). Optional arguments are followed by the equal sign and their default value, like $lang = "en". Argument names are often mentioned in function's description with some additional info.

Signature lines are not meant to be valid perl. They're there for you to understand what arguments the function expects.

SHORTCUT FUNCTIONS

This package exports the following function when asked for them. They are shourtcut functions and will load needed packages and return their names. You can then use names of loaded packages to instantiate them however you want. You can also load all of them with the :all tag in import. These functions can be used as follows:

        use Bitcoin::Crypto qw(btc_extprv);

        # loads Bitcoin::Crypto::Key::ExtPrivate and returns package name
        # we can now use it to run methods
        my $mnemonic = btc_extprv->generate_mnemonic();

btc_extprv

Loads Bitcoin::Crypto::Key::ExtPrivate

btc_prv

Loads Bitcoin::Crypto::Key::Private

btc_extpub

Loads Bitcoin::Crypto::Key::ExtPublic

btc_pub

Loads Bitcoin::Crypto::Key::Public

btc_script

Loads Bitcoin::Crypto::Script

BETA INFORMATION

The module is currently consided to be in a beta phase.

  • beta will end with version 1.00, which will be released after enough live testing

  • current release is considered stable, but may have some rough edges

  • currently existing API will stay mostly the same (minor modifications are possible)

  • let me know if you are using the module so that I can guess the users to issues ratio

DISCLAIMER

Although the module was written with an extra care and appropriate tests are in place asserting compatibility with many Bitcoin standards, due to complexity of the subject some bugs may still be present. In the world of digital money, a single bug may lead to losing funds. I encourage anyone to test the module themselves, review the test cases and use the module with care, espetially in the beta phase. Suggestions for improvements and more edge cases to test will be gladly accepted, but there is no warranty on your funds being manipulated by this module.

SPEED

Since most of the calculations are delegated to the XS (and further to libtomcrypt or GMP) most tasks should be fairly quick to finish, in Perl definition of quick. The module have a little bit of startup time because of Moo and Type::Tiny, measured in miliseconds. The biggest runtime bottleneck seem to be the key derivation mechanism, which imports a key once for every derivation path part. Some tasks, like signature generation and verification, should be very fast thanks to libtomcrypt doing all the heavy lifting. All in all, the module should be able to handle any task which does not require brute forcing (like vanity address generation).

TODO

  • Live testing

  • Better test coverage

AUTHOR

Bartosz Jarzyna <brtastic.dev@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2018 - 2021 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.