BlockProcessor docstrings

pisa/block_processor.py

@@ -6,8 +6,24 @@ logger = Logger("BlockProcessor")
 
 
 class BlockProcessor:
+    """
+    The ``BlockProcessor`` contains methods related to the blockchain. Most of its methods required communication with
+    ``bitcoind``.
+    """
+
     @staticmethod
     def get_block(block_hash):
+        """
+        Gives a block given a block hash by querying ``bitcoind``.
+
+        Args:
+            block_hash (str): The block hash to be queried.
+
+        Returns:
+            block (dict): A dictionary containing the requested block data if the block is found.
+
+            Returns ``None`` otherwise.
+        """
 
         try:
             block = bitcoin_cli().getblock(block_hash)
@@ -20,6 +36,14 @@ class BlockProcessor:
 
     @staticmethod
     def get_best_block_hash():
+        """
+        Returns the hash of the current best chain tip.
+
+        Returns:
+            block_hash (str): The hash of the block if it can be found.
+
+            Returns ``None`` otherwise (not even sure this can actually happen).
+        """
 
         try:
             block_hash = bitcoin_cli().getbestblockhash()
@@ -32,6 +56,14 @@ class BlockProcessor:
 
     @staticmethod
     def get_block_count():
+        """
+        Returns the block height of the best chain.
+
+        Returns:
+            block_count (int): The block height if it can be computed.
+
+            Returns ``None`` otherwise (not even sure this can actually happen).
+        """
 
         try:
             block_count = bitcoin_cli().getblockcount()
@@ -44,6 +76,18 @@ class BlockProcessor:
 
     @staticmethod
     def decode_raw_transaction(raw_tx):
+        """
+        Deserializes a given raw transaction (hex encoded) and builds a dictionary representing it with all the
+        associated metadata given by ``bitcoind`` (e.g. confirmation count).
+
+        Args:
+            raw_tx (str): The hex representation of the transaction.
+
+        Returns:
+            tx (dict): The decoding of the given ``raw_tx`` if the transaction is well formaed.
+
+            Returns ``None`` otherwise.
+        """
 
         try:
             tx = bitcoin_cli().decoderawtransaction(raw_tx)
@@ -55,6 +99,22 @@ class BlockProcessor:
         return tx
 
     def get_missed_blocks(self, last_know_block_hash):
+        """
+        Compute the blocks between the current best chain tip and a given block hash (``last_know_block_hash``).
+
+        This method is used to fetch all the missed information when recovering from a crash. Note that if the two
+        blocks are not part of the same chain, it would return all the blocks up to genesis.
+
+        FIXME: This needs to be integrated with the ChainMaester (soon TM) to allow dealing with forks.
+
+        Args:
+            last_know_block_hash (hex): the hash of the last known block.
+
+        Returns:
+            missed_blocks (list): A list of blocks between the last given block and the current best chain tip, starting
+            from the child of ``last_know_block_hash``.
+        """
+
         current_block_hash = self.get_best_block_hash()
         missed_blocks = []
 
@@ -67,6 +127,19 @@ class BlockProcessor:
         return missed_blocks[::-1]
 
     def get_distance_to_tip(self, target_block_hash):
+        """
+        Compute the distance between a given block hash and the best chain tip.
+
+        Args:
+            target_block_hash (str): the hash of the target block (the one to compute the distance form the tip).
+
+        Returns:
+            distance (int): The distance between the target and the best chain tip is the target block can be found on
+            the blockchain.
+
+            Returns ``None`` otherwise.
+        """
+
         distance = None
 
         chain_tip = self.get_best_block_hash()