The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Bitcoin-Crypto-2.004
River stage one • 3 direct dependents • 5 total dependents
5 ++
/ Bitcoin::Crypto::Transaction

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 and P2MS are thoroughly tested and should be safe to use. Still, before putting any real money on the line, make sure to check the serialized transactions in other tools and review that its contents are correct. There is absolutely no guarantee!

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.

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)

Deserializes the bytestring $data into a transaction object.

Keep in mind deserialization requires a full set of UTXO to be registered. If they are not, an exception will be raised with missing 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 preimage of the transaction. It is a bytestring against which the input signature is created (after hashing it with hash256).

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

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.

fee_rate

        $fee_rate = $object->fee_rate()

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

NOTE: since weight of the transaction changes after signing it, 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:

  • block

    Optional instance of Bitcoin::Crypto::Block - used for locktime and sequence 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.

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

SEE ALSO

Bitcoin::Crypto::Transaction::Input
Bitcoin::Crypto::Transaction::Output
Bitcoin::Crypto::Transaction::UTXO
Bitcoin::Crypto::Script