/ 
Bitcoin-Crypto-4.002
River stage one • 3 direct dependents • 4 total dependents
⭐ Starred 12 GitHub stars
/ Bitcoin::Crypto::Manual::Transactions

NAME

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

SYNOPSIS

See "SYNOPSIS" in Bitcoin::Crypto::Transaction

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 incomplete. A full reimplementation would not only be very hard to achieve but also very likely insecure to be used as a null node (see https://bitcointalk.org/index.php?topic=260595.0). In addition, it would be rather ineffective to verify the entire blockchain using Perl + XS code. We focus on support for standard transaction types (see below) under most recent consensus rules. While this status may change in the future, it's good to be realistic about capabilities of this module in real-life scenarios. Keep "DISCLAIMER" in Bitcoin::Crypto::Manual in mind.

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 ScriptPubKey), and each of the inputs spends one output using signature script (also called 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 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 btc_utxo->new(...)->register or automatically from a serialized transaction using btc_utxo->extract. See "register" in Bitcoin::Crypto::Transaction::UTXO and "extract" in Bitcoin::Crypto::Transaction::UTXO for details. The process of getting transaction data can be automated using the "set_loader" in Bitcoin::Crypto::Transaction::UTXO hook (for example, call some API to get the serialized transaction and use 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 $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 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 block parameter to "verify" in Bitcoin::Crypto::Transaction and "new" in Bitcoin::Crypto::Transaction::UTXO.

There is no way to set network (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 exact consensus rules of Bitcoin can be used successfully. No special cases for other networks will be implemented.

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. "verify" in Bitcoin::Crypto::Transaction 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.

Which types of transactions are supported?

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

  • P2PK (pay to public key - obsolete)

  • P2PKH (pay to public key hash - legacy)

  • P2SH (pay to script hash - legacy)

  • P2WPKH (pay to witness public key hash)

  • P2WSH (pay to witness script hash)

  • P2SH(P2WPKH) (P2WPKH inside P2SH)

  • P2SH(P2WSH) (P2WSH inside P2SH)

  • P2MS (pay to multisig, usually nested inside P2SH or P2WSH)

  • P2TR (pay to taproot, both key and script path spends)

  • NULLDATA (provably unspendable outputs with OP_RETURN)

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 Math::BigInt documentation when required.

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

Transaction examples

Bundled directory 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.

Current known problems with transactions

Some problems are listed below. They are not considered critical to Bitcoin::Crypto operation, since it is not currently 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!

  • Transaction malleability is not fully solved

    Some details like enforcing minimal push opcodes are not implemented.

  • 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 FindAndDelete in Bitcoin Core). In addition, its OP_CODESEPARATOR handling is not well-tested and any non-standard transaction will require you to manually provide a script for digesting (as signing_subscript) and do manual insertion of the signature.