[#79] Refund transaction documentation

docs/source/refund.md

@@ -0,0 +1,86 @@
+# Transaction refunds
+
+The beauty of the atomic swaps is hidden in the possibility of refunding transaction,
+if the second side of the exchange is delaying in the coin contribution.
+
+#### Here are some examples of transaction refunds.
+
+## 1. Initial transaction refund
+
+Alice created and published such transaction:
+
+    {'contract': '63a820ce4209765f76e8c29bbcdc26c33746a0dc6feebe986444f8326008808ece2c338876a91485c0522f6e23beb11cc3d066cd20ed732648a4e667046948a15ab17576a914621f617c765c3caa5ce1bb67f6a3e51382b8da296888ac',
+    'contract_transaction': '0100000001222d497dd12edf372cd814bb0f09b958a511e002838343af8891f86ab758542e010000008a473044022057ea78a85400c041abef6bea3d3248f50980254a2faa204ba044303abd1d5eb402202de66193a69ed213f1be7f3fa541073c6ebe7be85667fd912916449d0f4888d301410431ab07973bbb5dbc6b7422fc7322abb5df15f77694c0b15b09a325996af47ddd887c7eaa72c656a71fcb333068956de7b3e2f15deaafc1d9285d779ca1b6a3f6000000000240420f000000000017a9145d8c62f002fa64587fdc82d61da9a7216c9079c287ad9a2700000000001976a914621f617c765c3caa5ce1bb67f6a3e51382b8da2988ac00000000',
+    'fee': 0.00064899,
+    'fee_per_kb': 0.00253511,
+    'fee_per_kb_text': '0.00253511 LTC / 1 kB',
+    'fee_text': '0.00064899 LTC',
+    'locktime': datetime.datetime(2018, 3, 8, 15, 27, 53, 796094),
+    'recipient_address': 'LXRAXRgPo84p58746zaBXUFFevCTYBPxgb',
+    'refund_address': 'LUAn5PWmsPavgz32mGkqsUuAKncftS37Jq',
+    'secret': '5a6d4a7664394d704769784553524841476976586d45595362475a676e77623435476376514677696f7353764f6d464c6c36565a376c59555a48386d31534f68',
+    'secret_hash': 'ce4209765f76e8c29bbcdc26c33746a0dc6feebe986444f8326008808ece2c33',
+    'size': 255,
+    'size_text': '255 bytes',
+    'transaction_hash': 'cc37c5a6f66f24b33e85c5ac2210488873ac61dad4e3098d7a6b35f7f55ff579',
+    'value': 0.01,
+    'value_text': '0.01000000 LTC'}
+
+She was waiting for the response from Bob for a day but she did not receive any,
+so she decided to refund the money from the blockchain:
+
+### 1. Get a wallet from the newtork
+
+    from clove.network import Litecoin
+
+    alice_ltc_wallet = Litecoin.get_wallet(private_key='aliceprivatekey') # provide real key
+    alice_ltc_wallet.address
+    'LUAn5PWmsPavgz32mGkqsUuAKncftS37Jq'
+
+### 2. Create refund transaction
+
+    from clove.network.bitcoin.contract import BitcoinContract
+
+    ltc_network = Litecoin()
+
+    alice_contract = BitcoinContract(
+        network=ltc_network,
+        contract='63a820ce4209765f76e8c29bbcdc26c33746a0dc6feebe986444f8326008808ece2c338876a91485c0522f6e23beb11cc3d066cd20ed732648a4e667046948a15ab17576a914621f617c765c3caa5ce1bb67f6a3e51382b8da296888ac',
+        raw_transaction='0100000001222d497dd12edf372cd814bb0f09b958a511e002838343af8891f86ab758542e010000008a473044022057ea78a85400c041abef6bea3d3248f50980254a2faa204ba044303abd1d5eb402202de66193a69ed213f1be7f3fa541073c6ebe7be85667fd912916449d0f4888d301410431ab07973bbb5dbc6b7422fc7322abb5df15f77694c0b15b09a325996af47ddd887c7eaa72c656a71fcb333068956de7b3e2f15deaafc1d9285d779ca1b6a3f6000000000240420f000000000017a9145d8c62f002fa64587fdc82d61da9a7216c9079c287ad9a2700000000001976a914621f617c765c3caa5ce1bb67f6a3e51382b8da2988ac00000000'
+    )
+
+    refund_transaction = alice_contract.refund(alice_ltc_wallet)
+    RuntimeError: This contract is still valid! It can't be refunded until 2018-03-07 15:40:48.
+
+Oops! Something wen wrong! Contract is still valid! Alice was a bit impatient, wasn't she?
+
+Initial transaction contract is set to be valid for 48 hours.
+
+Okey! It is past 2018-03-07 15:40:48, so Alice is free to create a refund transaction!
+
+    refund_transaction = alice_contract.refund(alice_ltc_wallet)
+
+### 3. Sign and publish refund transaction
+
+    refund_transaction.add_fee_and_sign()
+
+    refund_transaction.show_details()
+    {'fee': 0.00087597,
+     'fee_per_kb': 0.00273742,
+     'fee_per_kb_text': '0.00273742 LTC / 1 kB',
+     'fee_text': '0.00087597 LTC',
+     'recipient_address': 'LUAn5PWmsPavgz32mGkqsUuAKncftS37Jq',
+     'size': 320,
+     'size_text': '320 bytes',
+     'transaction': '010000000179f55ff5f7356b7a8d09e3d4da61ac7388481022acc5853eb3246ff6a6c537cc00000000eb483045022100a87fb31ef3f12e61e8947c6df844269996e45db0022600aac6ba4e28f5d85a5802206b6f921cf6d09ffaf1584d7b6f463ceecb48ae2ad4ba8d0e59f18bda6c3781f901410431ab07973bbb5dbc6b7422fc7322abb5df15f77694c0b15b09a325996af47ddd887c7eaa72c656a71fcb333068956de7b3e2f15deaafc1d9285d779ca1b6a3f6004c5d63a820ce4209765f76e8c29bbcdc26c33746a0dc6feebe986444f8326008808ece2c338876a91485c0522f6e23beb11cc3d066cd20ed732648a4e667046948a15ab17576a914621f617c765c3caa5ce1bb67f6a3e51382b8da296888ac000000000113ec0d00000000001976a914621f617c765c3caa5ce1bb67f6a3e51382b8da2988ac6948a15a',
+     'transaction_hash': '07dfb64b8f9fd0b7835fa11014fe3299e6ce3e3ffc3bfc585d1636b1ab8d4c66',
+     'value': 0.01,
+     'value_text': '0.01000000 LTC'}
+
+     refund_transaction.publish()
+
+### 4. Voilà! Alice should get her litecoins back. You can check it for example in a blockcypher.
+
+
+## 2. Participate transaction refund
+