NAME

Bitcoin::Crypto::Transaction - Bitcoin transaction instance

SYNOPSIS

use Bitcoin::Crypto qw(btc_utxo btc_transaction);

# extract unspent transaction outputs from the previous transaction
btc_utxo->extract([hex => $serialized_previous_tx]);

# create transaction from its serialized form
my $tx = btc_transaction->from_serialized([hex => $serialized_this_tx]);

# this will verify the transaction and throw an exception if it is not correct
$tx->verify;

# dump the transaction in readable format
print $tx->dump;

DESCRIPTION

Transaction support in Bitcoin::Crypto is provided on best-effort basis. The goal is not to reimplement Bitcoin Core, which would most likely lead to security issues, but rather to provide means to manipulate a set of well-known standard transaction types. Widely used P2PKH, P2SH, their SegWit counterparts, P2TR and P2MS are thoroughly tested and should be safe to use. Still, keep "DISCLAIMER" in Bitcoin::Crypto::Manual in mind.

See "Transactions" in Bitcoin::Crypto::Manual for details and guidelines.

INTERFACE

Attributes

version

Integer containing version of the transaction. By default 1.

Available in the constructor.

inputs

The array reference of transaction inputs (Bitcoin::Crypto::Transaction::Input).

It's better to use "add_input" instead of pushing directly to this array.

outputs

The array reference of transaction outputs (Bitcoin::Crypto::Transaction::Output).

It's better to use "add_output" instead of pushing directly to this array.

locktime

Integer containing locktime of the transaction. By default 0.

Available in the constructor.

block

An optional instance of Bitcoin::Crypto::Block. This reference is weakened. Block may be required to do some validations when calling "verify".

Available in the constructor.

writer: set_block

predicate: has_block

Methods

new

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

This is a standard Moo constructor, which can be used to create the object. It takes arguments specified in "Attributes".

Returns class instance.

add_input

$object = $object->add_input($input_object)
$object = $object->add_input(%args)

Adds a new input to the transaction.

If a single scalar is passed, it must be a constructed object of Bitcoin::Crypto::Transaction::Input.

Otherwise expects a hash of arguments passed to "new" in Bitcoin::Crypto::Transaction::Input.

Returns itself (for chaining).

add_output

$object = $object->add_output($output_object)
$object = $object->add_output(%args)

Same as "add_input", but adds an output (Bitcoin::Crypto::Transaction::Output).

to_serialized

$serialized = $object->to_serialized(%params)

Serializes a transaction into a bytestring.

%params can be any of:

witness

Boolean, default 1. If 0 is passed, forces serialization without witness data. Note that this is a no-op in non-segwit transactions.

from_serialized

$object = $class->from_serialized($data, %params)

Deserializes the bytestring $data into a transaction object.

%params can be any of:

pos

Position for partial string decoding. Optional. If passed, must be a scalar reference to an integer value.

This integer will mark the starting position of $bytestring from which to start decoding. It will be set to the next byte after end of transaction stream.

Keep in mind it's best to have a full set of UTXOs registered. If they are not, an exception may be raised if a function requires full UTXO data. That exception will contain transaction ID and output index, which should help you fill in the blanks. See Bitcoin::Crypto::Transaction::UTXO for details.

get_hash

$hash = $object->get_hash(%params)

Returns the hash of the transaction, also used as its id. The return value is a bytestring.

%params can be any of:

witness

Whether witness data should be included in the hash. Default: false

NOTE: this method returns the hash in big endian, which is not suitable for serialized transactions. If you want to manually encode the hash into the transaction, you should first scalar reverse it.

txid

$txid = $object->txid()

Returns the transaction id as a bytestring. Same as calling "get_hash" but always with witness => 0.

wtxid

$wtxid = $object->wtxid()

Returns the transaction witness id as a bytestring. Same as calling "get_hash" but always with witness => 1.

get_digest

$digest = $object->get_digest(%params)

This method produces the digest of the transaction. The result is an object of Bitcoin::Crypto::Transaction::Digest::Result class. Transaction digests can be signed by "sign_message" in Bitcoin::Crypto::Key::Private, but for standard transactions "sign_transaction" in Bitcoin::Crypto::Key::Private can be used instead to skip manual work.

It always returns digest as if all verification flags were activated. Pre-SegWit scripts that look like SegWit (and should produce different digests) can't contain any signature operations, so flags would not change the behavior of signature checking.

%params can be any of:

signing_index

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

The subscript used in digesting. It is only required for P2SH, P2WSH and custom scripts.
sighash

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

Taproot extension flag defined by BIP341 (integer). 0 (no extension) by default.
taproot_ext

Taproot extension as a bytestring. No extension by default.
taproot_annex

Taproot annex defined by BIP341 as a bytestring. No annex by default.

Caution: BIP341 warns to not use annex until the meaning of this field is defined by a softfork.

Note that digest is implemented as a persistent object associated with the transaction which may hold some data cached for reuse. Adding inputs and outputs through "add_input" and "add_output" will cause this object to be recreated, since the cache must be invalidated. If you change transaction in a way that won't clear this cache and you call get_digest repeatedly, you may force this by calling clear_digest_object.

get_digest_object

$digest_object = $object->get_digest_object(%params)

Same as "get_digest", but returns an object of Bitcoin::Crypto::Transaction::Digest instead of a bytestring. Advanced use only.

fee

$fee = $object->fee()

Returns the fee - the difference between sum of input values and the sum of output values. The fee is always zero or positive integer, but can be undefined if the UTXOs were not registered.

fee_rate

$fee_rate = $object->fee_rate()

Returns the fee rate - the amount of satoshi per virtual byte (a floating point value) or undef if fee is undef.

NOTE: since weight of the transaction changes after signing it (due to added signature / witness data), it is not possible to accurately measure fee rate prior to signing.

set_rbf

$object = $object->set_rbf()

Sets replace-by-fee for the transaction according to BIP125. The modification of sequence number is always done on the first input. Has no effect if the transaction already has the RBF rule.

has_rbf

$bool = $object->has_rbf()

Returns true if the transaction is subject to replace-by-fee.

virtual_size

my $vB_size = $object->virtual_size()

Returns the virtual size of the transaction (in vBytes).

virtual_size is used for fee calculations. Normal transaction data is calculated as 1 vByte per byte and witness data is calculated as 0.25 vByte per byte.

weight

my $WU_size = $object->weight()

Returns the weight of the transaction (in weight units).

Similar to "virtual_size", but normal transaction data is calculated as 4 WU per byte and witness data is calculated as 1 WU per byte.

update_utxos

$object = $object->update_utxos()

This method accepts the transaction as confirmed by the network. It unregisters all UTXOs it consumed and registers its own outputs as new UTXOs. This means new transactions can be created without the need to register the new UTXOs manually.

NOTE: it does not verify the transaction by itself.

verify

$object->verify(%params)

Verifies the transaction according to the Bitcoin consensus rules. Returns nothing, but will throw an exception if the verification failed.

See "Known problems with transactions" in Bitcoin::Crypto::Manual.

%params can be any of:

flags

An 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).
block

Optional instance of Bitcoin::Crypto::Block - used for locktime, sequence and coinbase verification. If it is not passed and the transaction includes these checks, it will still verify without an exception but a warning will be issued.

Including this parameter is deprecated - call set_block before verifying instead.

verify_standard

$object->verify_standard(%params)

Same as "verify", but assumes a full set of verification flags. This can be useful to determine whether the transaction is standard and will be relayed, as opposed to default set of flags which only validates the consensus layer (whether the transaction can be included in a block).

is_coinbase

$bool = $object->is_coinbase()

Returns true if this transaction is coinbase: its first input has an empty previous transaction hash. Does not check any further - actual validation of coinbase is done in "verify".

sign

$signer = $object->sign(%args)

This method creates a new instance of Bitcoin::Crypto::Transaction::Signer, which can be used to build a signature for any transaction regardless of complexity. It requires user to know what type of output you are signing, and what the operations of the script are. For signing simple, standard transactions, "sign_transaction" in Bitcoin::Crypto::Key::Private should be used to sign automatically (which uses the signer class under the hood).

To understand what %args can be passed to the method, see "Common attributes" in Bitcoin::Crypto::Transaction::Signer and "Taproot attributes" in Bitcoin::Crypto::Transaction::Signer. In addition to those attributes, a compat key can be specified as a true value if a compat segwit output is being signed (as there is no way to detect it by looking at the transaction).

dump

$text = $object->dump()

Returns a readable description of the transaction.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

INTERFACE

Attributes

version

inputs

outputs

locktime

block

Methods

new

add_input

add_output

to_serialized

from_serialized

get_hash

txid

wtxid

get_digest

get_digest_object

fee

fee_rate

set_rbf

has_rbf

virtual_size

weight

update_utxos

verify

verify_standard

is_coinbase

sign

dump

SEE ALSO

Module Install Instructions