Skip to content

Commit

Permalink
Add Bitcoin::Crypto::Manual with moved main docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@bbrtj
bbrtj committed Oct 6, 2023
1 parent c4094cf commit e063a9d
Show file tree
Hide file tree
Showing 3 changed files with 137 additions and 132 deletions.
139 changes: 8 additions & 131 deletions lib/Bitcoin/Crypto.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,128 +76,31 @@ Bitcoin::Crypto - Bitcoin cryptography in Perl
use Bitcoin::Crypto qw(btc_extprv);
use Bitcoin::Crypto::Util qw(generate_mnemonic to_format);
use Bitcoin::Crypto::Constants;
# extended keys are used for mnemonic generation and key derivation
my $mnemonic = generate_mnemonic;
say "your mnemonic code is: $mnemonic";
my $master_key = btc_extprv->from_mnemonic($mnemonic);
my $derived_key = $master_key->derive_key("m/0'");
my $derived_key = $master_key->derive_key_bip44(
purpose => Bitcoin::Crypto::Constants::bip44_segwit_purpose,
index => 0,
);
# basic keys are used for signatures and addresses
# basic keys can be 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: ' . to_format [hex => $pub->to_serialized];
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: ' . to_format [hex => $signature];
}
say 'address: ' . $pub->get_address;
=head1 DESCRIPTION
Cryptographic module for common Bitcoin-related tasks.
=head1 SCOPE
This module allows you to perform low-level tasks for Bitcoin such as:
=over
=item * creating extended keys and utilizing bip32 key derivation
=item * creating private key / public key pairs
=item * building, serializing and running transaction scripts
=item * address generation (in legacy, compatibility and segwit formats)
=item * signature generation and verification
=item * importing / exporting using popular mediums (WIF, mnemonic, hex)
=item * using custom (non-Bitcoin) networks
=back
This module won't help you with:
=over
=item * serializing transactions
=item * using any Bitcoin CLI tools / clients
=item * connecting to Bitcoin network
=back
=head1 WHERE TO START?
Documentation and examples in this module assume you're already familiar with
the basics of Bitcoin protocol and asymmetric cryptography. If that's not the
case, start with reading about those topics.
If you like to learn by example, dive right into the examples directory.
There are many goals which you may want to achieve with this module. Common
topics include:
=over
=item * create a key pair for signature or address generation
Start with L<Bitcoin::Crypto::Key::Private> if you already have some data you
want to use as a private key entropy (like Bitcoin's C<WIF> format or hex
data). If you'd like to generate list of words (a mnemonic) instead, see
L<Bitcoin::Crypto::Util/generate_mnemonic> and
L<Bitcoin::Crypto::Key::ExtPrivate/from_mnemonic>.
=item * generate many keys at once
L<Bitcoin::Crypto::Key::ExtPrivate> allows you to derive multiple keys from a
master key, so you don't have to store multiple private keys.
L<Bitcoin::Crypto::Key::ExtPublic> can be then used to derive public keys
lazily. I<(Note: storing extended public keys together with private keys in a
hot storage will put your extended private key at risk!)>
=item * 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
L<Bitcoin::Crypto::Network> first, with the protocol data valid for your
cryptocurrency.
=item * utilize Bitcoin Script
L<Bitcoin::Crypto::Script> will help you build, de/serialize and run a script.
L<Bitcoin::Crypto::Script::Runner> gives you more control over script execution,
including running the script step by step, stopping after each opcode.
=item * work with Bitcoin-related encodings
See L<Bitcoin::Crypto::Base58> and L<Bitcoin::Crypto::Bech32>.
=back
=head1 HOW TO READ THE DOCUMENTATION?
Most functions in this documentation have a code line showcasing the arguments
used by the function. These lines are not meant to be valid perl. They're there
for you to understand what arguments the function expects.
Most packages in this module have the types of their thrown exceptions
documented near the bottom of the document. The exceptions section may be
useful to understand which types of exceptions can be thrown when using
functions or methods from the package and what they mean. It is not meant to be
a full list of exceptions a function can throw and unblessed errors may still
be raised.
See L<Bitcoin::Crypto::Manual> for an overview of the module.
=head1 SHORTCUT FUNCTIONS
Expand Down Expand Up @@ -243,32 +146,6 @@ Loads L<Bitcoin::Crypto::Transaction>
Loads L<Bitcoin::Crypto::Transaction::UTXO>
=head1 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. 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.
=head1 TODO
I will gladly accept help working on these:
=over 2
=item * Taproot compatibility
=item * Better error checking (edge cases etc.)
=item * Detailed manual
=item * Better test coverage
=back
=head1 SEE ALSO
L<Bitcoin::RPC::Client>
Expand Down
129 changes: 129 additions & 0 deletions lib/Bitcoin/Crypto/Manual.pod
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
=head1 NAME

Bitcoin::Crypto::Manual - Module overview

=head1 DESCRIPTION

This module allows you to perform low-level tasks for Bitcoin such as:

=over

=item * creating extended keys and utilizing bip32 key derivation

=item * creating private key / public key pairs

=item * address generation (in legacy, compatibility and segwit formats)

=item * importing / exporting using popular mediums (WIF, mnemonic, hex)

=item * building, serializing and running transaction scripts

=item * serializing, signing and verifying transactions

=back

This module won't help you with:

=over

=item * handling Bitcoin blocks and the blockchain

=item * using any Bitcoin CLI tools / clients

=item * connecting to Bitcoin network

=back

=head1 WHERE TO START?

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

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

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

=over

=item * create a key pair for signature or address generation

Start with L<Bitcoin::Crypto::Key::Private> if you already have some data you
want to use as a private key entropy (like Bitcoin's C<WIF> format or hex
data). If you'd like to generate list of words (a mnemonic) instead, see
L<Bitcoin::Crypto::Util/generate_mnemonic> and
L<Bitcoin::Crypto::Key::ExtPrivate/from_mnemonic>.

=item * generate many keys at once

L<Bitcoin::Crypto::Key::ExtPrivate> allows you to derive multiple keys from a
master key, so you don't have to store multiple private keys.
L<Bitcoin::Crypto::Key::ExtPublic> can be then used to derive public keys
lazily. I<(Note: storing extended public keys together with private keys in a
hot storage will put your extended private key at risk!)>

=item * create a transaction object from scratch or from serialized transaction data

See L<Bitcoin::Crypto::Manual::Transactions>.

=item * utilize Bitcoin Script

L<Bitcoin::Crypto::Script> will help you build, de/serialize and run a script.
L<Bitcoin::Crypto::Script::Runner> gives you more control over script execution,
including running the script step by step, stopping after each opcode.

=item * work with Bitcoin-related encodings

See L<Bitcoin::Crypto::Base58> and L<Bitcoin::Crypto::Bech32>.

=item * 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
L<Bitcoin::Crypto::Network> first, with the protocol data valid for your
cryptocurrency.

=back

=head1 HOW TO READ THE DOCUMENTATION?

Most functions in this documentation have a code line showcasing the arguments
used by the function. These lines are not meant to be valid perl. They're there
for you to understand what arguments the function expects.

Most packages in this module have the types of their thrown exceptions
documented near the bottom of the document. The exceptions section may be
useful to understand which types of exceptions can be thrown when using
functions or methods from the package and what they mean. It is not meant to be
a full list of exceptions a function can throw and unblessed errors may still
be raised.

=head1 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. Suggestions for
improvements and more edge cases to test will be gladly accepted, but there is
B<no warranty on your funds being manipulated by this module>.

=head1 TODO

I will gladly accept help working on these:

=over 2

=item * All listed in L<Bitcoin::Crypto::Manual::Transactions/Current known problems with transactions>

=item * Taproot compatibility

=item * Better error checking (edge cases etc.)

=item * Better test coverage

=back

=cut

1 change: 0 additions & 1 deletion lib/Bitcoin/Crypto/Manual/Transactions.pod
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
__END__
=head1 NAME

Bitcoin::Crypto::Manual::Transactions - Transaction support details
Expand Down

0 comments on commit e063a9d

Please sign in to comment.