diff --git a/pisa/carrier.py b/pisa/carrier.py index 627b917..9ba69e5 100644 --- a/pisa/carrier.py +++ b/pisa/carrier.py @@ -10,6 +10,23 @@ logger = Logger("Carrier") class Receipt: + """ + The ``Receipt`` class represent the interaction between the ``Carrier`` and ``bitcoind`` when broadcasting + transactions. It is used to signal whether or not a transaction has been successfully broadcast and why. + + Args: + delivered (bool): whether or not the transaction has been successfully broadcast. + confirmations (int): the number of confirmations of the transaction to broadcast. In certain situations the + ``Carrier`` may fail to broadcast a transaction because it was already in the blockchain. This attribute + signals those situations. + reason (int): an error code describing why the transaction broadcast failed. + + Returns: + ``Receipt``: A receipt describing whether or not the transaction was delivered. Notice that transactions + that are already on chain are flagged as delivered with a ``confirmations > 0`` whereas new transactions are so + with ``confirmations = 0``. + """ + def __init__(self, delivered, confirmations=0, reason=None): self.delivered = delivered self.confirmations = confirmations @@ -17,8 +34,24 @@ class Receipt: class Carrier: + """ + The ``Carrier`` is the class in charge of interacting with ``bitcoind`` to send/get transactions. It uses + ``Receipt`` objects to report about sending transactions. + """ + # NOTCOVERED def send_transaction(self, rawtx, txid): + """ + Tries to send a given raw transaction to the Bitcoin network using ``bitcoind``. + + Args: + rawtx (str): a (potentially) signed raw transaction ready to be broadcast. + txid (str): the transaction id corresponding to ``rawtx``. + + Returns: + ``Receipt``: A receipt reporting whether the transaction was successfully delivered or not and why. + """ + try: logger.info("Pushing transaction to the network", txid=txid, rawtx=rawtx) bitcoin_cli().sendrawtransaction(rawtx) @@ -71,6 +104,17 @@ class Carrier: @staticmethod def get_transaction(txid): + """ + Queries transaction data to ``bitcoind`` given a transaction id. + + Args: + txid (str): a 32-byte hex-formatted string representing the transaction id. + + Returns: + ``dict`` or ``None``: A dictionary with the transaction data if the transaction can be found on the chain. + Returns ``None`` otherwise. + """ + try: tx_info = bitcoin_cli().getrawtransaction(txid, 1)