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 Bitcoin::Crypto::Manual::Transactions 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

$txid = $object->get_hash()

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

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.

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.

%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.
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.
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).

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 "Current known problems with transactions" in Bitcoin::Crypto::Manual::Transactions.

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

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

dump

$text = $object->dump()

Returns a readable description of the transaction.

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:

Transaction - general error with transaction
TransactionScript - error during transaction scripts execution

	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

get_digest

get_digest_object

fee

fee_rate

set_rbf

has_rbf

virtual_size

weight

update_utxos

verify

is_coinbase

dump

EXCEPTIONS

SEE ALSO

Module Install Instructions