NAME
Bitcoin::Crypto::Transaction::UTXO - Unspent transaction output instance
SYNOPSIS
use Bitcoin::Crypto qw(btc_utxo);
# register the utxos automatically from the serialized transaction
btc_utxo->extract($serialized_tx);
# create the utxo manually
my $utxo = btc_utxo->new(
txid => [hex => '94e519b9c0f43228e3dc841d838fc7372de95345206ef936ac6020889abe0457'],
output_index => 1,
output => {
locking_script => [P2PKH => '1HrfeGdVP4d1uAdbSknzeaFpDFQVJyVpLu'],
value => 1_02119131,
}
);
# register
$utxo->register;
# find the utxo
btc_utxo->get([hex => '94e519b9c0f43228e3dc841d838fc7372de95345206ef936ac6020889abe0457'], 1);
# unregister
$utxo->unregister;DESCRIPTION
UTXO is a transaction output which hasn't been spent yet. All transaction inputs must be UTXOs. You need to register UTXOs before you can fully utilize a transaction. If a transaction has its UTXOs unregistered, its methods may raise an exception if they require full UTXO data.
This module keeps an internal register of all valid UTXOs. You can add or remove UTXOs from this register, and they are accessed using two characteristics: transaction ID and output number (counted from 0).
INTERFACE
Attributes
txid
A bytestring - id of the source transaction.
Available in the constructor.
output_index
A positive or zero integer which is the index of the output in the source transaction.
Available in the constructor.
block
Optional instance of Bitcoin::Crypto::Block.
Available in the constructor.
output
Instance of Bitcoin::Crypto::Transaction::Output. A hash reference will be coerced into an object by passing it to the constructor.
Available in the constructor.
Methods
new
$utxo = $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.
register
$object = $object->register()Registers the given UTXO. It will be held in memory and will be available to fetch using "get".
unregister
$object = $object->unregister()Does the opposite of "register".
get
$utxo = $class->get($txid, $output_index);Returns the UTXO registered with given txid and output index. Throws an exception if it cannot be found or loaded.
set_loader
$class->set_loader(sub { ... })
$class->set_loader(undef)Replaces an UTXO loader.
The subroutine should accept the same parameters as "get" and return a constructed UTXO object. If possible, the loader should not return the same UTXO twice in a single runtime of the script. It will be not informed of UTXOs being spent, so it should "hand over" UTXOs while marking them as spent in its source.
Returns nothing. Passing undef disables the custom loader.
unload
\@utxos = $class->unload()Removes all UTXOs from the perl memory and returns them as an array reference. Returned UTXOs will no longer be visible to "get" calls.
This may be useful to move the UTXOs gathered in Perl memory to some other medium, for example a database. "set_loader" could be set to load UTXOs from a database, and the script could periodically clear them from its memory to store them in a persistent storage for later.
registered_count
$count = $class->registered_count()Returns the number of UTXOS currently present in internal perl memory. This can be used to decide whether a call to "unload" is needed or not.
extract
$class->extract($serialized_tx)Extracts all outputs from the $serialized_tx (a bytestring). Same can be achieved by calling update_utxos on a transaction object.
Returns nothing. All $serialized_tx outputs will be added to the register as new UTXO instances.