teos.responder

class Responder(db_manager, gatekeeper, carrier, block_processor)

Bases: object

The Responder is in charge of ensuring that channel breaches are dealt with. It does so handling the decrypted penalty_txs handed by the Watcher and ensuring the they make it to the blockchain.

Parameters

• db_manager (AppointmentsDBM) – an instance of the appointment database manager to interact with the database.

• carrier (Carrier) – a carrier instance to send transactions to bitcoind.

• block_processor (BlockProcessor) – a block processor instance to get data from bitcoind.

logger

The logger for this component.

Type

Logger

trackers

A dictionary containing the minimum information about the TransactionTracker required by the Responder (penalty_txid, locator and user_id). Each entry is identified by a uuid.

Type

dict

tx_tracker_map

A penalty_txid:uuid map used to allow the Responder to deal with several trackers triggered by the same penalty_txid.

Type

dict

unconfirmed_txs

A list that keeps track of all unconfirmed penalty_txs.

Type

list

missed_confirmations

A dictionary that keeps count of how many confirmations each penalty_tx has missed. Used to trigger rebroadcast if needed.

Type

dict

block_queue

A queue used by the Responder to receive block hashes from bitcoind. It is populated by the ChainMonitor.

Type

Queue

db_manager

An instance of the appointment database manager to interact with the database.

Type

AppointmentsDBM

gatekeeper

A Gatekeeper instance in charge to control the user access and subscription expiry.

Type

Gatekeeper

carrier

A carrier instance to send transactions to bitcoind.

Type

Carrier

block_processor

A block processor instance to get data from bitcoind.

Type

BlockProcessor

last_known_block

The last block known by the Responder.

Type

str

add_tracker(uuid, locator, dispute_txid, penalty_txid, penalty_rawtx, user_id, confirmations=0)

Creates a TransactionTracker after successfully broadcasting a penalty_tx.

A summary of TransactionTracker is stored in trackers and tx_tracker_map and the penalty_txid added to unconfirmed_txs if confirmations=0. Finally, all the data is stored in the database.

Parameters

• uuid (str) – a unique identifier for the appointment.

• locator (str) – the appointment locator provided by the user (16-byte hex-encoded).

• dispute_txid (str) – the id of the transaction that created the channel breach.

• penalty_txid (str) – the id of the decrypted transaction included in the appointment.

• penalty_rawtx (str) – the raw transaction to be broadcast.

• user_id (str) – the public key that identifies the user (33-bytes hex str).

• confirmations (int) – the confirmation count of the penalty_tx. In normal conditions it will be zero, but if the transaction is already on the blockchain this won’t be the case.

awake()

Starts a new thread to monitor the blockchain to make sure triggered appointments get enough depth. The thread will run until the ChainMonitor adds the "END" message to the queue.

Returns

The thread object that was just created and is already running.

Return type

Thread

check_confirmations(txs)

Checks if any of the monitored penalty_txs has received it’s first confirmation or keeps missing them.

This method manages unconfirmed_txs and missed_confirmations.

Parameters

txs (list) – A list of confirmed tx ids (the list of transactions included in the last received block).

do_watch()

Monitors the blockchain for reorgs and appointment ends.

This is the main method of the Responder and triggers tracker cleaning, rebroadcasting, reorg managing, etc.

get_completed_trackers()

Gets the trackers that has already been fulfilled based on a given height (the justice transaction is irrevocably resolved).

Returns

A list of completed trackers uuids.

Return type

list

get_expired_trackers(height)

Gets trackers than are expired due to the user subscription expiring.

Only gets those trackers which penalty transaction is not going trough (probably because of low fees), the rest will be eventually completed once they are irrevocably resolved.

Parameters

height (int) – the height of the last received block.

Returns

A list of the expired trackers uuids.

Return type

list

get_txs_to_rebroadcast()

Gets the transactions to be rebroadcast based on their missed_confirmation count.

Returns

A list with all the ids of the transaction that have to be rebroadcast.

Return type

list

handle_breach(uuid, locator, dispute_txid, penalty_txid, penalty_rawtx, user_id, block_hash)

Requests the Responder to handle a channel breach. This is the entry point of the Responder.

Parameters

• uuid (str) – a unique identifier for the appointment.

• locator (str) – the appointment locator provided by the user (16-byte hex-encoded).

• dispute_txid (str) – the id of the transaction that created the channel breach.

• penalty_txid (str) – the id of the decrypted transaction included in the appointment.

• penalty_rawtx (str) – the raw transaction to be broadcast in response of the breach.

• user_id (str) – the public key that identifies the user (33-bytes hex str).

• block_hash (str) – the block hash at which the breach was seen (used to see if we are on sync).

Returns

A receipt indicating whether or not the penalty_tx made it into the blockchain.

Return type

Receipt

handle_reorgs(block_hash)

Basic reorg handle. It deals with situations where a reorg has been found but the dispute_tx is still on the chain. If the dispute_tx is reverted, it need to call the ReorgManager (Soon TM).

Parameters

block_hash (str) – the hash of the last block received (which triggered the reorg).

on_sync(block_hash)

Whether the Responder is on sync with bitcoind or not. Used when recovering from a crash.

The Watchtower can be instantiated with fresh or with backed up data. In the later, some triggers may have been missed. In order to go back on sync both the Watcher and the Responder need to perform the state transitions until they catch up.

If a transaction is broadcast by the Responder and it is rejected (due to a double-spending for example) and the Responder is off-sync then the TransactionTracker is abandoned.

This method helps making that decision.

Parameters

block_hash (str) – the block hash passed to the Responder in the handle_breach request.

Returns

Whether or not the Responder and bitcoind are on sync.

Return type

bool

rebroadcast(txs_to_rebroadcast)

Rebroadcasts a penalty_tx that has missed too many confirmations. In the current approach this will loop until the tracker expires if the penalty transactions keeps getting rejected due to fees.

Potentially, the fees could be bumped here if the transaction has some tower dedicated outputs (or allows it trough ANYONECANPAY or something similar).

Parameters

txs_to_rebroadcast (list) – a list of transactions to be rebroadcast.

Returns

A list of Receipts with information about whether or not every transaction made it trough the network.

Return type

list

class TransactionTracker(locator, dispute_txid, penalty_txid, penalty_rawtx, user_id)

Bases: object

A TransactionTracker is used to monitor a penalty_tx. Once the dispute is seen by the Watcher the penalty transaction is decrypted and the relevant appointment data is passed along to the Responder.

Once the Responder has succeeded on broadcasting the penalty transaction it will create a TransactionTracker and monitor the blockchain until the end of the appointment.

Parameters

• locator (str) – a 16-byte hex-encoded value used by the tower to detect channel breaches. It serves as a trigger for the tower to decrypt and broadcast the penalty transaction.

• dispute_txid (str) – the id of the transaction that created the channel breach and triggered the penalty.

• penalty_txid (str) – the id of the transaction that was encrypted under dispute_txid.

• penalty_rawtx (str) – the raw transaction that was broadcast as a consequence of the channel breach.

• user_id (str) – the public key that identifies the user (33-bytes hex str).

classmethod from_dict(tx_tracker_data)

Constructs a TransactionTracker instance from a dictionary. Requires that all the fields are populated (not None).

Useful to load data from the database.

Parameters

tx_tracker_data (dict) – a dictionary with an entry per each field required to create the TransactionTracker.

Returns

A transaction tracker instantiated with the provided data.

Return type

TransactionTracker

Raises

ValueError – if any of the required fields is missing.

get_summary()

Returns the summary of a tracker, consisting on the locator, the user_id and the penalty_txid.

Returns

The appointment summary.

Return type

dict

to_dict()

Encodes a TransactionTracker as a dictionary.

Returns

A dictionary containing the TransactionTracker data.

Return type

dict