/ 
Bitcoin-Crypto-4.003
River stage one • 3 direct dependents • 4 total dependents
⭐ Starred 12 GitHub stars
/ Bitcoin::Crypto::Key::Private

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::Internal 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 or should be used with Schnorr signatures. 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.

This method accepts a secret argument. See Bitcoin::Crypto::Secret for details.

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($wif, $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.

This method accepts a secret argument. See Bitcoin::Crypto::Secret for details.

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 instance that represents an output taproot key, or this key if it is marked as "taproot_output". 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". script_tree parameter can be passed if taproot output had a script path.

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_index

    This non-negative integer is the index of the input being signed. Required.

  • redeem_script

    A 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.

  • multisig

    A 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.pl example):

    # 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]);

  • sighash

    The sighash which should be used for the signature. By default "SIGHASH_ALL" in Bitcoin::Crypto::Constants is used for pre-taproot outputs and "SIGHASH_DEFAULT" in Bitcoin::Crypto::Constants for taproot outputs.

  • script_tree

    Bitcoin::Crypto::Script::Tree instance for use in taproot. Same script tree must be passed as used in generation of the address to correctly tweak the key. If the key was already tweaked ("get_taproot_output_key"), this parameter can be skipped, as no double-tweaking will happen.

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:

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);

SEE ALSO

Bitcoin::Crypto::Key::Public
Bitcoin::Crypto::Network