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

NAME

Bitcoin::Crypto::Transaction::Signer - Construct a signature for any transaction

SYNOPSIS

# sign a multisignature transaction
$tx->sign(signing_index => 0, script => $p2ms_script, %more_args)
	->add_signature($priv, SIGHASH_ALL)
	->add_signature('bytestring signature')
	->finalize_multisignature
	->finalize;

DESCRIPTION

This class implements a signer for transactions of any complexity. It is best used for custom transactions which cannot be signed by calling "sign_transaction" in Bitcoin::Crypto::Key::Private.

It works by running the script in the background, progressing it with each added signature. Executing the script allows finding the correct signature-checking opcodes to sign by simulating how the script will behave when the transaction is verified. No changes to the underlying transaction are applied until the signature is finalized.

Note that since transactions use stack as a data structure, the order of generated signature will be reversed, which may be surprising when inspecting the transaction. Method calls must be done in order of opcode execution.

INTERFACE

Attributes vary depending on signing output type.

Common attributes

These attributes are common for all output types.

transaction

Mandatory transaction object. No need to include it when calling "sign" in Bitcoin::Crypto::Transaction, because it will be included automatically.

signing_index

The index of input being signed. Required.

script

The script being signed. It is required for script hash output types (P2SH and P2WSH). Otherwise it will be taken from output locking script. In taproot script spends, it will be taken from "script_tree" and "leaf_id".

Taproot attributes

These attributes are only used for taproot outputs.

script_tree

Bitcoin::Crypto::Script::Tree instance with a script tree used when creating the taproot output. Must be passed for script spends or key spends with enabled script path.

leaf_id

Numeric identifier which marks the leaf in "script_tree". Must be passed for script spends.

public_key

A taproot internal key which was used for creating this output. Must be passed for script spends.

taproot_ext_flag

A taproot extension flag for script spends. By default, a value 1 (for tapscript) is used.

Methods

new

$signer = $class->new(%args)

This is a standard Moo constructor, which can be used to create the object. It takes arguments specified in "Common attributes" and "Taproot attributes". Usually, there is no need to call this method directly, as it will be called by "sign" in Bitcoin::Crypto::Transaction on the correct Signer subclass.

Returns class instance.

add_bytes

$signer = $signer->add_bytes($bytestr)

Adds raw bytes from $bytestr into the signature. Note that this should not be used to add signatures - use "add_signature" with bytes instead.

Returns the instance, for chaining.

add_number

$signer = $signer->add_number($num)

Adds a script number $num into the signature.

Returns the instance, for chaining.

add_signature

$signer = $signer->add_signature($bytestr, %args)
$signer = $signer->add_signature($privkey, %args)

Adds a signature to the transaction. If $privkey is passed (Bitcoin::Crypto::Key::Private), then it will be used to sign the next signature-checking opcode in the script. If $bytestr is passed, then it will be used as-is, but unlike "add_bytes", next call to add_signature will correctly target next opcode.

If the next signature-checking opcode is a multisig, then it will not step over it after the call, but wait for a mandatory "finalize_multisignature" call.

%args can be any of:

Returns the instance, for chaining.

finalize_multisignature

$signer = $signer->finalize_multisignature()

Used to finalize signing of multisig opcodes. It is mandatory to call it when signing a multisig transaction.

Returns the instance, for chaining.

finalize

$signer->finalize()

Finalizes the signing process, applying changes on the transaction object. After this call, the $signer object is done and should be discarded as soon as possible.

Returns nothing, as the signing process is done.