Adds some examples the library needed for a long time. Still more to come

Author: sr-gi

bitcoin_tools/utxo_dump.py

@@ -77,7 +77,7 @@ def get_min_input_size(out, height, count_p2sh=False):
             scriptSig = 1 + (req_sigs * 72)  # OP_0 (1 byte) + 72 bytes per sig (PUSH sig (1 byte) + sig (71 bytes))
             scriptSig_len = int(ceil(scriptSig / float(256)))
         else:
-            # All other types (including non standard P2MS, OP_Return and non-standard outs)
+            # All other types (non-standard outs)
             scriptSig = -fixed_size - 1  # Those scripts are marked with length -1 and skipped in dust calculation.
             scriptSig_len = 0
 

example.py

@@ -0,0 +1,46 @@
+from bitcoin_tools.keys import load_keys
+from bitcoin_tools.transaction import TX
+
+#################################################
+#       Advanced Raw transaction building       #
+#                 P2MS -> P2MS                  #
+#################################################
+# ---------------------------------------------------------------------------------------------------------------------
+# The following piece of code serves as an example of how to build a P2MS transaction. Funds will be redeemed from a
+# Pay-to-multisig address, and m-out of-n signatures will be required from different keys.
+# - The library store keys using a Bitcoin address as an identifier. If you need more information about generating and
+# storing / loading keys, refer to key_management.py / basic_raw_tx_creation.py examples.
+# - First of all we will select an unspent transaction output (UTXO) of type P2MS, by choosing the proper prev_tx_id and
+# index.
+# - Then we should define the amount to be transferred and the fees.
+# - Now we are ready to build the transaction. We can use the input/output constructor to do so.
+# - Finally, we should sign the transaction using all m-out of-n required private keys. Notice that the order of the in
+# which the keys are provided must match with the order in which the public keys where defined in the previous tx output
+# script.
+# - Finally we can serialize the transaction and display it to check that all worked!
+# ---------------------------------------------------------------------------------------------------------------------
+
+# Reference to the previous transaction output that will be used to redeem and spend the funds, consisting on an id and
+# an output index.
+prev_tx_id = "adcd6d269d5e0713fa9650099e9ab54ebf845a0d95f3740b44361bdb287959a7"
+prev_out_index = 0
+
+# Amount to be spent, in Satoshis, and the fee to be deduced (should be calculated).
+value = 6163910
+fee = 230 * 240
+
+# Destination Bitcoin address where the value in bitcoins will be sent and locked until the owner redeems it.
+destination_btc_addr = "mwryy9YdVezq2Wo1DukA5ADhrNemqCKTmy"
+
+# First, we  build our transaction from io (input/output) using the previous transaction references, the value, and the
+# destination.
+tx = TX.build_from_io(prev_tx_id, prev_out_index, value - fee, destination_btc_addr)
+# Finally, the transaction is signed using the private key associated with the Bitcoin address from each input.
+# Input 0 will be signed, since we have only created one.
+tx.sign(sk, 0)
+
+# Once created we can display the serialized transaction. Transaction is now ready to be broadcast.
+print "hex: " + tx.serialize()
+
+# Finally, we can analyze each field of the transaction.
+tx.display()

examples/__init__.py

@@ -0,0 +1,56 @@
+from bitcoin_tools.keys import load_keys
+from bitcoin_tools.transaction import TX
+
+#################################################
+#               Key loading                     #
+#################################################
+# ---------------------------------------------------------------------------------------------------------------------
+# The following piece of code loads an already generated ECDSA key pair from disk (check key_management.py if you
+# haven't generated a key pair yet).
+# - You should replace the Bitcoin address for the one that matches yours.
+# ---------------------------------------------------------------------------------------------------------------------
+
+btc_addr = "mwryy9YdVezq2Wo1DukA5ADhrNemqCKTmy"
+sk, pk = load_keys(btc_addr)
+
+#################################################
+#        Basic Raw transaction building         #
+#               P2PKH -> P2PKH                  #
+#################################################
+# ---------------------------------------------------------------------------------------------------------------------
+# The following piece of code serves as an example of how to build a P2PKH transaction. Funds will be redeemed from the
+# already loaded Bitcoin address (Notice that, in order to work, there should be funds hold by the address).
+# - You will build a transaction that spends from a P2PKH output and generates a new P2PKH output.
+# - You should change prev_tx_id, prev_out_index and value for the ones who match with an unspent transaction output
+# from your recently generated address.
+# - Choose a fee big enough to pay for the transaction inclusion into a block. You can use https://bitcoinfees.21.co/ to
+# figure out the current fee-per-byte ratio.
+# - Choose the transaction destination address.
+# - Build the transaction using the basic constructor.
+# - Sign and broadcast the transaction.
+# ---------------------------------------------------------------------------------------------------------------------
+
+# Reference to the previous transaction output that will be used to redeem and spend the funds, consisting on an id and
+# an output index.
+prev_tx_id = "7767a9eb2c8adda3ffce86c06689007a903b6f7e78dbc049ef0dbaf9eeebe075"
+prev_out_index = 0
+
+# Amount to be spent, in Satoshis, and the fee to be deduced (should be calculated).
+value = 6163910
+fee = 230 * 240
+
+# Destination Bitcoin address where the value in bitcoins will be sent and locked until the owner redeems it.
+destination_btc_addr = "mwryy9YdVezq2Wo1DukA5ADhrNemqCKTmy"
+
+# First, we  build our transaction from io (input/output) using the previous transaction references, the value, and the
+# destination.
+tx = TX.build_from_io(prev_tx_id, prev_out_index, value - fee, destination_btc_addr)
+# Finally, the transaction is signed using the private key associated with the Bitcoin address from each input.
+# Input 0 will be signed, since we have only created one.
+tx.sign(sk, 0)
+
+# Once created we can display the serialized transaction. Transaction is now ready to be broadcast.
+print "hex: " + tx.serialize()
+
+# Finally, we can analyze each field of the transaction.
+tx.display()

examples/advanced_raw_tx_creation.py

@@ -0,0 +1,27 @@
+from bitcoin_tools.keys import generate_keys, store_keys
+from bitcoin_tools.wallet import generate_wif, generate_btc_addr
+
+#################################################
+# Key management and Bitcoin address generation #
+#################################################
+# ---------------------------------------------------------------------------------------------------------------------
+# The following piece of code generates fresh keys and Bitcoin address.
+# - Both mainnet and testnet addresses can be generated. Tesnet are generated by default.
+# - Keys are stored in the folder defined in conf.py.
+# - WIF can be stored as a qr image or text. Image is set by default.
+# ---------------------------------------------------------------------------------------------------------------------
+
+# First of all the ECDSA keys are generated.
+sk, pk = generate_keys()
+# Then, the Bitcoin address is derived from the public key created above.
+btc_addr = generate_btc_addr(pk)
+# Both the public and private key are stored in disk in pem format. The Bitcoin address is used as an identifier in the
+# name of the folder that contains both keys.
+store_keys(sk.to_pem(), pk.to_pem(), btc_addr)
+# Finally, the private key is encoded as WIF and also stored in disk, ready to be imported in a wallet.
+generate_wif(btc_addr, sk)
+
+print "Keys for address " + btc_addr + " properly generated and stored."
+
+
+

examples/basic_raw_tx_creation.py

@@ -0,0 +1,23 @@
+from bitcoin_tools.transaction import TX
+
+#################################################
+#           Hex transaction analysis            #
+#################################################
+
+# ---------------------------------------------------------------------------------------------------------------------
+# The following piece of code parses a serialized transaction (hex encoded) transaction and displays all the information
+#  related to it.
+# - Leftmost displayed transaction shows data as should be interpreted (human-readable), while rightmost
+# (surrounded by parenthesis) shows it as it is in the serialize transaction (can be used to identify it inside the
+# transaction)
+# - You should change the hex_tx for the one you'd like to deserialize. Serialized transaction can be obtain though
+# block explorers such as blockchyper or blockr.io, or by building a transaction using some of the library tools.
+# ---------------------------------------------------------------------------------------------------------------------
+
+# First a transaction object is created (through the deserialize constructor) by deserializing the hex transaction we
+# have selected.
+hex_tx = "01000000013ca58d2f6fac36602d831ee0cf2bc80031c7472e80a322b57f614c5ce9142b71000000006b483045022100f0331d85cb7f7ec1bedc41f50c695d654489458e88aec0076fbad5d8aeda1673022009e8ca2dda1d6a16bfd7133b0008720145dacccb35c0d5c9fc567e52f26ca5f7012103a164209a7c23227fcd6a71c51efc5b6eb25407f4faf06890f57908425255e42bffffffff0241a20000000000001976a914e44839239ab36f5bc67b2079de00ecf587233ebe88ac74630000000000001976a914dc7016484646168d99e49f907c86c271299441c088ac00000000"
+tx = TX.deserialize(hex_tx)
+
+# Then, the transaction can be displayed using the display method to analyze how it's been constructed.
+tx.display()