Add docs to each transaction example, add note to Manual::Transactions

Perl-Bitcoin · Oct 13, 2023 · 01d7ee5 · 01d7ee5
1 parent 24ad16e
commit 01d7ee5
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 19 deletions.
diff --git a/ex/tx/multisig_compat_create.pl b/ex/tx/multisig_compat_create.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/4cb7af0ac5c964ebe2bc6aa0bcf2b96193d8cfa2fd6a77c0a5f0f3276f3c3f69
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -50,3 +47,13 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 P2MS in compat SegWit create transaction example
+
+This is the same as transaction showcased in C<tx/multisig_create.pl> example,
+but it uses P2SH(P2WSH) output instead of native P2WSH.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/4cb7af0ac5c964ebe2bc6aa0bcf2b96193d8cfa2fd6a77c0a5f0f3276f3c3f69>
+
diff --git a/ex/tx/multisig_compat_redeem.pl b/ex/tx/multisig_compat_redeem.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/59eb3933d805ca4d75f0ffcf9323a4588903d8d11d9942ed6d5f7e1298621518
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -26,7 +23,8 @@
 
 btc_utxo->extract(
 	[
-		hex => '0100000000010118156298127e5f6ded42991dd1d8038958a42393cffff0754dca05d83339eb590000000000fdffffff014b3a020000000000160014446d69dd4e2223d460ce72c75aac59ed5eca51fd0400483045022100af107ba43245f68f8c9e91b72d5abc96b8cfc50282658e5a120cf3f86df2f0cf02203c091bb66dddeda66c990c564e5bbf62464815b2bfdc2c839aaa22969a34b75801473044022056297a7026395f7684106a72ce147965d91800f79b526c29cd2435899064fbe80220756d591bdd0ba9acce4adfc6d4a8b767b85eea4f098f933ac864f5e339a84d2e016952210351d02712ec3702786bb1deb2e56417ecef2bd358090c9636f73a0e651153ac602103ec1449d401d94b78dc0127aa4eaed6a2e7a6a6b11fb9243e97b38373a8ded90d21028875dc1d1d3f672543bb75c320e29b7bbc103329f44064b2d47a3cddc757c18453ae00000000'
+		hex =>
+			'0100000000010118156298127e5f6ded42991dd1d8038958a42393cffff0754dca05d83339eb590000000000fdffffff014b3a020000000000160014446d69dd4e2223d460ce72c75aac59ed5eca51fd0400483045022100af107ba43245f68f8c9e91b72d5abc96b8cfc50282658e5a120cf3f86df2f0cf02203c091bb66dddeda66c990c564e5bbf62464815b2bfdc2c839aaa22969a34b75801473044022056297a7026395f7684106a72ce147965d91800f79b526c29cd2435899064fbe80220756d591bdd0ba9acce4adfc6d4a8b767b85eea4f098f933ac864f5e339a84d2e016952210351d02712ec3702786bb1deb2e56417ecef2bd358090c9636f73a0e651153ac602103ec1449d401d94b78dc0127aa4eaed6a2e7a6a6b11fb9243e97b38373a8ded90d21028875dc1d1d3f672543bb75c320e29b7bbc103329f44064b2d47a3cddc757c18453ae00000000'
 	]
 );
 
@@ -70,3 +68,14 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 P2MS redeem in compat SegWit transaction example
+
+This is the similar to transaction showcased in C<tx/multisig_redeem.pl>
+example, but it uses P2SH(P2WSH) output instead of native P2WSH. In addition,
+it introduces a second P2WPKH input.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/f5ee861935e8b675f25c8f976ad747478c8185d06cb632d79550d9c58c0350a2>
+
diff --git a/ex/tx/multisig_create.pl b/ex/tx/multisig_create.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/59eb3933d805ca4d75f0ffcf9323a4588903d8d11d9942ed6d5f7e1298621518
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -50,3 +47,13 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 P2MS create transaction example
+
+This transaction creates P2WSH output locking coins in a 2-out-of-3 multisignature script.
+See C<tx/multisig_redeem.pl> example for spending script.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/59eb3933d805ca4d75f0ffcf9323a4588903d8d11d9942ed6d5f7e1298621518>
+
diff --git a/ex/tx/multisig_redeem.pl b/ex/tx/multisig_redeem.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/8077dbb8ee049a5a754ad5e681310c1ee192e9be44a3b76d1182b41f1d39c2f5
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -58,3 +55,19 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 P2MS redeem transaction example
+
+This transaction redeems coins locked in P2WSH output produced in
+C<tx/multisig_create.pl> example. The exact redeem script must be provided and
+two out of three private keys must be used to sign.
+
+Signing requires providing C<redeem_script> argument with the script object, as
+well as C<multisig> argument in format C<[$this_signature, $total_signatures]>.
+Both private keys are used to sign the same C<signing_index>, but with
+different C<multisig> argument.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/8077dbb8ee049a5a754ad5e681310c1ee192e9be44a3b76d1182b41f1d39c2f5>
+
diff --git a/ex/tx/nulldata.pl b/ex/tx/nulldata.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/11cca738065ca9172394f800bab3f997698851fd0245848ec491b2744d1807e8
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -24,11 +21,13 @@
 	utxo => [[hex => 'f8990964483b62a86ad1a5ae445b2d5b3ccd74c3611a857dc794a37eb5c62e3f'], 0],
 );
 
+# send all the coins to this address. The value will be adjusted to total minus fee
 $tx->add_output(
 	locking_script => [P2WPKH => 'tb1qprasdghq2svf5hmta98zf93aj6z36ep7cpkj68'],
 	value => 0,
 );
 
+# this is the OP_RETURN output - the value will stay 0
 $tx->add_output(
 	locking_script => [NULLDATA => 'Have fun with Perl, use Bitcoin::Crypto!'],
 	value => 0,
@@ -46,3 +45,14 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 NULLDATA transaction example
+
+This transaction uses NULLDATA outputs (with C<OP_RETURN>) to create provably
+unspendable outputs on the blockchain. These outputs are allowed to contain up
+to 80 bytes of custom data. The coins are sent back to (a new) P2WPKH address.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/11cca738065ca9172394f800bab3f997698851fd0245848ec491b2744d1807e8>
+
diff --git a/ex/tx/segwit.pl b/ex/tx/segwit.pl
@@ -6,9 +6,6 @@
 use Bitcoin::Crypto::Util qw(to_format);
 use Bitcoin::Crypto::Network;
 
-# This code was used to produce this testnet transaction:
-# https://mempool.space/testnet/tx/f8990964483b62a86ad1a5ae445b2d5b3ccd74c3611a857dc794a37eb5c62e3f
-
 Bitcoin::Crypto::Network->get('bitcoin_testnet')->set_default;
 
 my $tx = btc_transaction->new;
@@ -75,3 +72,17 @@
 say $tx->dump;
 say to_format [hex => $tx->to_serialized];
 
+__END__
+
+=head1 P2WPKH transaction example
+
+A simple transaction spending four P2WPKH inputs and produces a single P2WPKH
+output, effectively aggregating the coins from all inputs.
+
+Fee rate is (inaccurately) approximated. To set exact fee rate sign the
+transaction, calculate fee based on its virtual size and then sign again
+- changing the value of the output invalidates previous signatures.
+
+This code was used to produce testnet transaction:
+L<https://mempool.space/testnet/tx/f8990964483b62a86ad1a5ae445b2d5b3ccd74c3611a857dc794a37eb5c62e3f>
+
diff --git a/lib/Bitcoin/Crypto/Manual/Transactions.pod b/lib/Bitcoin/Crypto/Manual/Transactions.pod
@@ -90,6 +90,18 @@ Bitcoin::Crypto test suite contains pretty thorough testing of following transac
 
 =back
 
+=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