=head1 NAME

Bitcoin::Crypto::Manual::Transactions - Transaction support details

=head1 SYNOPSIS

See L<Bitcoin::Crypto::Transaction/SYNOPSIS>

=head1 DESCRIPTION

This page contains a set of general guidelines for creating and manipulating
transactions using Bitcoin::Crypto. For API documentation, see the link above.

First and foremost, understand that in its nature Bitcoin::Crypto transaction
system is B<incomplete>. A full reimplementation would not only be very hard to
achieve but also very likely insecure (see
L<https://bitcointalk.org/index.php?topic=260595.0>). In addition, it would be
very ineffective to verify the entire blockchain using Perl + XS code. Instead,
we focus on support for standard transaction types (see below) under today's
consensus rules (without much regard to transactions' backward compatibility
quirks). Keep L<Bitcoin::Crypto::Manual/DISCLAIMER> in mind.

=head2 How transactions work and how we handle the outputs

Each transaction in Bitcoin is basically just a set of sources (inputs) and
destinations (outputs). You specify where the coins come from and where they
should go. Each transaction output has a locking script (also called
C<ScriptPubKey>), and each of the inputs spends one output using signature
script (also called C<ScriptSig>). Locking script is (usually) a cryptographic
riddle solvable only by the owner of the private key, and signature script is a
proof of ownership.

Normally, when using software which is working as a full node (such as Bitcoin
Core) the blockchain history can be accessed without any extra steps.
Bitcoin::Crypto does not do that and depend on you to provide valid Unspent
Transaction Outputs (UTXOs) before adding inputs to the transaction (or
deserializing a transaction). You can get transaction data from your own
Bitcoin full node or from external sources such as L<mempool.space>. UTXO data
is necessary for performing many tasks on transactions, like calculating the
fee, signing or verifying.

You can register UTXOs manually using C<< btc_utxo->new(...)->register >> or
automatically from a serialized transaction using C<< btc_utxo->extract >>. See
L<Bitcoin::Crypto::Transaction::UTXO/register> and
L<Bitcoin::Crypto::Transaction::UTXO/extract> for details. The process of
getting transaction data can be automated using the
L<Bitcoin::Crypto::Transaction::UTXO/set_loader> hook (for example, call some
API to get the serialized transaction and use C<extract> on it).

This means you can create valid transactions without the need to download,
store and verify the entire Bitcoin blockchain. You only need to know which
UTXOs belong to you. Once you have created a transaction and it got validated
in the blockchain, you can call C<< $tx->update_utxos >> on it, which will
invalidate the UTXOs it used and register its outputs as new UTXOs, which will
reflect the changes that happened on the chain. This way you can chain your own
transactions in a Perl script.

While transactions don't usually care about blocks at all, Bitcoin::Crypto
implements them in L<Bitcoin::Crypto::Block>. Blocks can be used partially
(without transactions) for the purpose of checking locktime or sequence of a
transaction. Block object can be passed as C<block> parameter to
L<Bitcoin::Crypto::Transaction/verify> and
L<Bitcoin::Crypto::Transaction::UTXO/new>.

There is no way to set network (L<Bitcoin::Crypto::Network>) on
per-transaction-object basis like you can do with keys. Most of transaction
functionality is not network-dependent, but some addresses will be encoded
using given network settings, which will be pulled from the default network.
Note that only networks which use the B<exact> consensus rules of Bitcoin can
be used successfully. No special cases for other networks will be implemented.

=head2 Protocol vs standard

Bitcoin validation rules are either enforced on protocol level (transaction is
invalid if violated) or standard/policy level (transaction is rejected by
mempool when violated). Transactions which follow the protocol but not the
standard would still be valid if they were inserted into the block directly by
the miner (skipping the mempool).

Bitcoin::Crypto currently has no way of validating transactions based on
policies. L<Bitcoin::Crypto::Transaction/verify> only checks protocol rules, so
that old or special transactions will verify successfully. However, it should
always generate addresses and transactions which are in line with the standard.
For example, it will always generate non-malleable signatures.

=head2 Which types of transactions are supported?

Bitcoin::Crypto test suite contains pretty thorough testing of the following
output types:

=over

=item * P2PK (pay to public key - obsolete)

=item * P2PKH (pay to public key hash - legacy)

=item * P2SH (pay to script hash - legacy)

=item * P2WPKH (pay to witness public key hash)

=item * P2WSH (pay to witness script hash)

=item * P2SH(P2WPKH) (P2WPKH inside P2SH)

=item * P2SH(P2WSH) (P2WSH inside P2SH)

=item * P2MS (pay to multisig, usually nested inside P2SH or P2WSH)

=item * P2TR (pay to taproot, both key and script path spends)

=item * NULLDATA (provably unspendable outputs with OP_RETURN)

=back

=head2 Coin values

All the value fields used by this module are in the smallest unit (satoshi) and
are BigInt objects. This is to ensure 32-bit compatibility of 64-bit
value fields. There are type coercions implemented to make it as opaque as
possible, but you may sometimes bump into issues with these objects when doing
value calculations. Refer to L<Math::BigInt> documentation when required.

If you need to calculate full coin value, you may use
C<Bitcoin::Crypto::Constants::units_per_coin> constant.

=head2 Transaction examples

Bundled directory C<ex/tx/> contains scripts with transactions which were
published to the testnet chain. These scripts should provide a convenient
starting base for anyone interested in hacking Bitcoin using Bitcoin::Crypto.

Each example contains a short description and a link to the transaction in the
blockchain explorer. The fact that these were successfully processed by the
network is a good testament to module's faithfulness to consensus rules.
However, we still strongly encourage using other tools or otherwise testing the
transactions before broadcasting them to the network.

=head2 Current known problems with transactions

Some problems are listed below. They are not considered critical to
Bitcoin::Crypto operation, since it is not trying to be capable of running a
full node (able to 100% reproduce validation rules of Bitcoin Core).

Contributions sorting out any of those are welcome!

=over

=item * Transaction malleability is not fully solved

Some details like enforcing minimal push opcodes are not implemented.

=item * P2SH timestamp threshold is not checked

BIP16 provides a timestamp value which sets a block time from which a certain
script contents should be treated as standard P2SH transactions. This is not
currently checked at all - all scripts which look like P2SH are treated as
P2SH, even if they were mined before the timestamp. If you need the timestamp
value, you can get it from
C<Bitcoin::Crypto::Constants::p2sh_timestamp_threshold>.

=item * Non-standard transactions may not work as intended

Bitcoin::Crypto may not handle some funky transactions correctly. Most notably,
it does not delete the signature from the script before using it for digesting
(known as C<FindAndDelete> in Bitcoin Core). In addition, its
C<OP_CODESEPARATOR> handling is not well-tested and any non-standard
transaction will require you to manually provide a script for digesting (as
C<signing_subscript>) and do manual insertion of the signature.

=back

=cut

