NAME
Bitcoin::Crypto::Key::Private - Bitcoin private keys
SYNOPSIS
use Bitcoin::Crypto::Key::Private;
# get Bitcoin::Crypto::Key::Public instance from private key
my $pub = $priv->get_public_key();
# automatically sign standard transactions
$priv->sign_transaction($tx, signing_index => $n);
# create signature for custom message (hash256)
my $sig = $priv->sign_message('Hello world');
# signature is returned as byte string
# use to_format to get the representation you need
use Bitcoin::Crypto::Util qw(to_format);
my $sig_hex = to_format [hex => $sig];
# signature verification
$priv->verify_message('Hello world', $sig);DESCRIPTION
This class allows you to create a private key instance.
You can use a private key to get public keys and sign or verify transactions.
INTERFACE
Attributes
compressed
Boolean value indicating if this ECC key should be compressed. Default: true.
writer: set_compressed
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
taproot_output
Boolean value indicating if this key was obtained through taproot tweaking. Taproot output keys are used to sign and verify schnorr signatures in P2TR outputs. Default: false
writer: set_taproot_output
Methods
new
Constructor is reserved for internal and advanced use only. Use "from_serialized" or "from_wif" instead.
from_serialized
$key_object = $class->from_serialized($serialized)This creates a new key from string data. Argument $serialized is a formatable bytestring containing the private key entropy.
Returns a new key object instance.
to_serialized
$serialized = $key_object->to_serialized()This returns a private key as a sequence of bytes. The result is a bytestring which can be further formated with to_format utility.
from_wif
$key_object = $class->from_wif($str, $network = undef)Creates a new private key from Wallet Import Format string.
Takes an additional optional argument, which is network name. It may be useful if you use many networks and some have the same WIF byte.
This method will change compression and network states of the created private key, as this data is included in WIF format.
Returns class instance.
to_wif
$wif_string = $object->to_wif()Does the opposite of from_wif on a target object
get_public_key
$public_key_object = $object->get_public_key()Returns instance of Bitcoin::Crypto::Key::Public generated from the private key.
get_taproot_output_key
$prv = $object->get_taproot_output_key($tweak_suffix = undef)Returns a new private key object that represents an output taproot key. Optional $tweak_suffix can be passed as bytestring.
sign_message
$signature = $object->sign_message($message)Signs a digest of $message (digesting it with double sha256) with a private key.
Returns a byte string containing signature.
Character encoding note: $message should be encoded in the proper encoding before passing it to this method. Passing Unicode string will cause the function to fail. You can encode like this (for UTF-8):
use Encode qw(encode);
$message = encode('UTF-8', $message);sign_transaction
$object->sign_transaction($tx, %params)Signs the transaction $tx using this private key. This automatic signing only works for standard script types, if your script is non-standard then you will have to sign manually.
For taproot, this signs using key path spending. Spending with script path needs a custom solution using "sign_message".
Note that the module will let you sign any transaction with any private key. You have to manually run "verify" in Bitcoin::Crypto::Transaction to ensure you used the right private key and the signature is correct for the corresponding locking script.
Returns nothing - the result of the function is the modification of transaction $tx.
%params can contain:
signing_indexThis non-negative integer is the index of the input being signed. Required.
redeem_scriptA Bitcoin::Crypto::Script instance or something which can be turned into a script, used for specifying a payout script when redeeming P2SH and P2WSH outputs.
multisigA representation of the multisig signing stage. It is an array reference with exactly two elements. The first element is the number (1-based, not the index!) of the currently signed multisig. The second element is the total number of signatures required for the multisig. For example, signing 2-out-of-3 multisig can look like this (taken from
ex/tx/multisig_redeem.plexample):# sign using the private key belonging to the first pubkey btc_prv->from_wif('cScAuqNfiNR7mq61QGW3LtokKAwzBzs4rbCz4Uff1NA15ysEij2i') ->sign_transaction($tx, signing_index => 0, redeem_script => $redeem_script, multisig => [1, 2]); # sign using the private key belonging to the third pubkey btc_prv->from_wif('cQsSKWrBLXNY1oSZbLcJf4HF5vnKGgKko533LnkTmqRdS9Fx4SGH') ->sign_transaction($tx, signing_index => 0, redeem_script => $redeem_script, multisig => [2, 2]);sighashThe sighash which should be used for the signature. By default
SIGHASH_ALLis used.
verify_message
$signature_valid = $object->verify_message($message, $signature, %params)Verifies $signature against digest of $message (digesting it with double sha256) using private key.
%params can be any of:
flagsAn instance of Bitcoin::Crypto::Transaction::Flags. If not passed, full set of consensus flags will be assumed (same as calling "new" in Bitcoin::Crypto::Transaction::Flags with no arguments).
Returns boolean.
Character encoding note: $message should be encoded in the proper encoding before passing it to this method. Passing Unicode string will cause the function to fail. You can encode like this (for UTF-8):
use Encode qw(encode);
$message = encode('UTF-8', $message);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:
Sign - couldn't sign the message correctly
ScriptType - couldn't automatically sign the given script type
Verify - couldn't verify the message correctly
KeyCreate - key couldn't be created correctly
NetworkConfig - incomplete or corrupted network configuration