teos.chain_monitor¶

class ChainMonitor(receiving_queues, block_processor, bitcoind_feed_params)[source]¶

Bases: object

The ChainMonitor is in charge of monitoring the blockchain (via bitcoind) to detect new blocks on top of the best chain. If a new best block is spotted, the chain monitor will notify the given queues.

The ChainMonitor monitors the chain using two methods: zmq and polling. Blocks are only notified once per queue and the notification is triggered by the method that detects the block faster.

The ChainMonitor lifecycle goes through 4 states: idle, listening, active and terminated. When a ChainMonitor instance is created, it is not yet monitoring the chain and the status attribute is set to ChainMonitorStatus.IDLE. Once the monitor_chain method is called, the chain monitor changes status to ChainMonitorStatus.LISTENING, and starts monitoring the chain for new blocks; it does not yet notify the receiving queues, but keeps the block hashes in the order they where spotted in an internal queue. Once the activate method is called, the status changes to ChainMonitorStatus.ACTIVE, and the receiving queues are notified in order for all the block hashes that are in the internal queue or any new one that is detected. Finally, once the terminate method is called, the status is changed to ChainMonitorStatus.TERMINATED, the chain monitor stops monitoring the chain and no receiving queue will be notified about new blocks (including any block that is currently in the internal queue). A final "END" message is sent to all the subscribers.

Parameters

receiving_queues (list) – a list of Queue objects that will be notified when the chain_monitor is active and it received new blocks hashes.
block_processor (BlockProcessor) – a BlockProcessor instance.
bitcoind_feed_params (dict) – a dict with the feed (ZMQ) connection parameters.

logger¶

The logger for this component.

Type: Logger

last_tips¶

A list of last chain tips. Used as a sliding window to avoid notifying about old tips.

Type: list

check_tip¶

An event that is triggered at fixed time intervals and controls the polling thread.

Type: Event

lock¶

A lock used to protect concurrent access to the queues by the zmq and polling threads.

Type: Condition

zmqSubSocket¶

A socket to connect to bitcoind via zmq.

Type: socket

polling_delta¶

Time between polls (in seconds).

Type: int

max_block_window_size¶

Max size of last_tips.

Type: int

queue¶

A queue where blocks are stored before they are processed.

Type: Queue

status¶

The current status of the monitor, either ChainMonitorStatus.IDLE, ChainMonitorStatus.LISTENING, ChainMonitorStatus.ACTIVE or ChainMonitorStatus.TERMINATED.

Type: ChainMonitorStatus

activate()[source]¶

Changes the status of the ChainMonitor from listening to active. It creates a new thread that runs the notify_subscribers method, which is in charge of notifying the receiving queue for each block hash that is added to the internal queue.

Raises: RuntimeError – if the status was not ChainMonitor.LISTENING when the method was called.

enqueue(block_hash)[source]¶

Adds a new block hash to the internal queue of the ChainMonitor and the internal state. The state contains the list of last_tips to prevent notifying about old blocks. last_tips is bounded to max_block_window_size.

Parameters: block_hash (str) – the new best tip.
Returns: True if the state was successfully updated, False otherwise.
Return type: bool

monitor_chain()[source]¶

Changes the status of the ChainMonitor from idle to listening. It initializes the last_tips list to terminate the current best tip (by querying the BlockProcessor) and creates two threads, one per each monitoring approach (zmq and polling).

Raises: RuntimeError – if the status was not ChainMonitor.IDLE when the method was called.

monitor_chain_polling()[source]¶: Monitors bitcoind via polling. Once the method is fired, it keeps monitoring as long as the status attribute is not ChainMonitorStatus.TERMINATED. Polling is performed once every polling_delta seconds. If a new best tip is found, it is added to the internal queue.

monitor_chain_zmq()[source]¶: Monitors bitcoind via zmq. Once the method is fired, it keeps monitoring as long as the status attribute is not ChainMonitorStatus.TERMINATED. If a new best tip is found, it is added to the internal queue.

notify_subscribers()[source]¶: Once the method is fired, it keeps getting the elements added to the internal queue and notifies the receiving queues about them. It terminates whenever the internal state is set to ChainMonitorStatus.TERMINATED.

terminate()[source]¶: Changes the status of the ChainMonitor to terminated and sends the “END” message to the internal queue. All the threads will stop as soon as possible.

class ChainMonitorStatus(value)[source]¶

Bases: enum.Enum

An enumeration.

ACTIVE = 2¶

IDLE = 0¶

LISTENING = 1¶

TERMINATED = 3¶