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
/ 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 (see 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).

By using the transaction system of this module you take full responsibility for any funds lost doing so. We don't give any warranty, so please review the code, review the test cases and most importantly review the generated transactions before sending them to the network!

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.

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. This way you can chain your own transactions in a Perl script.

Transactions usually don't care about blocks at all and so Bitcoin::Crypto does not implement them. There's currently no way to serialize transactions into a block, but for the purpose of checking locktime or sequence the very incomplete Bitcoin::Crypto::Block class can be instantiated and passed as block parameter to $tx->verify and btc_utxo->new constructor.

Which types of transactions are supported?

Bitcoin::Crypto test suite contains pretty thorough testing of 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 - work in progress, can't sign and dummy verification)

  • 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 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

    Strict DER signatures (BIP66) are not checked explicitly (CryptX may check them while verifying the signature though). Low S signatures mentioned in BIP62 are generated, but not verified. Some others like minimal push opcodes and OP_PUSHDATA 520 byte push limit are not implemented.

  • Only the default network is used for transactions

    There is currently 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.

  • legacy SIGHASH_SINGLE with more inputs than outputs

    It should result in the transaction digest of static value (value 1 encoded on 32 bits), but this edge case is not handled currently and an exception is thrown instead.

  • 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. If you need the timestamp value, you can get it from Bitcoin::Crypto::Constants::p2sh_timestamp_threshold.

  • Coinbase transactions are not supported

    To properly validate coinbase transactions some special cases must be introduced, which are not implemented right now.

  • PSBT (BIP174) is not supported

    It would be very nice to have the format implemented, but currently it's not.

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