aljaz/python-teos
1
0
Fork 0
mirror of https://github.com/aljazceru/python-teos.git synced 2025-12-18 14:44:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Further improvements, including references

Browse Source
This commit is contained in:
Sergi Delgado Segura
2019-12-09 20:08:05 +01:00
parent 6a5a23a1d6
commit 05dad7d38b
2 changed files with 29 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
pisa/api.py
View File

@@ -23,13 +23,13 @@ def add_appointment():
Add appointment endpoint, it is used as the main endpoint of the Watchtower. Add appointment endpoint, it is used as the main endpoint of the Watchtower.
The client sends requests (appointments) to this endpoint to request a job to the Watchtower. Requests must be json The client sends requests (appointments) to this endpoint to request a job to the Watchtower. Requests must be json
encoded and contain an appointment field and optionally a signature and public_key fields. encoded and contain an ``appointment`` field and optionally a ``signature`` and ``public_key`` fields.
Returns: Returns:
tuple: A tuple containing the response (json) and response code (`int:rcode`). For accepted appointments, the tuple: A tuple containing the response (``json``) and response code (``int``). For accepted appointments, the
`rcode` is always 0 and the response contains the signed receipt. For rejected appointments, the `rcode` is a ``rcode`` is always 0 and the response contains the signed receipt. For rejected appointments, the ``rcode`` is
negative value and the response contains the error message. Error messages can be found at a negative value and the response contains the error message. Error messages can be found at
(errors.py)[./errors.py] :mod:`Errors <pisa.errors>`.
""" """
remote_addr = request.environ.get("REMOTE_ADDR") remote_addr = request.environ.get("REMOTE_ADDR")
@@ -87,15 +87,17 @@ def get_appointment():
""" """
Get appointment endpoint, it gives information about a given appointment state in the Watchtower. Get appointment endpoint, it gives information about a given appointment state in the Watchtower.
The information is requested by locator. The information is requested by ``locator``.
Returns: Returns:
dict: A json formatted dictionary containing information about the requested appointment. dict: A json formatted dictionary containing information about the requested appointment.
A `status` flag is added to the data provided by either the `Watcher` or the `Responder` that signals the status A ``status`` flag is added to the data provided by either the :mod:`Watcher <pisa.watcher>` or the
of the appointment. Appointments hold by the `Watcher` are flagged as `being_watched` whereas appointments that :mod:`Responder <pisa.responder>` that signals the status of the appointment.
has already been triggered, and are therefore hold by the responder, are flagged as `dispute_responded`.
An special flag is raise for unknown appoints: `not_found`. - Appointments hold by the :mod:`Watcher <pisa.watcher>` are flagged as ``being_watched``.
- Appointments hold by the :mod:`Responder <pisa.responder>` are flagged as ``dispute_triggered``.
- Unknown appointments are flagged as ``not_found``.
""" """
locator = request.args.get("locator") locator = request.args.get("locator")
@@ -141,8 +143,8 @@ def get_all_appointments():
This endpoint should only be accessible by the administrator. Requests are only allowed from localhost. This endpoint should only be accessible by the administrator. Requests are only allowed from localhost.
Returns: Returns:
dict: a json formatted dictionary containing all the appointments hold by the `Watcher` (`watcher_appointments)` dict: a json formatted dictionary containing all the appointments hold by the :mod:`Watcher <pisa.watcher>`
and by the `Responder` (`responder_jobs`). (``watcher_appointments``) and by the :mod:`Responder <pisa.responder>` (``responder_jobs``).
""" """
@@ -182,7 +184,7 @@ def start_api(w):
This function starts the Flask server used to run the API. This function starts the Flask server used to run the API.
Args: Args:
w (Watcher): a `Watcher` object. w (Watcher): a :mod:`Watcher <pisa.watcher>` object.
""" """

25
pisa/appointment.py
View File

@@ -5,16 +5,18 @@ from pisa.encrypted_blob import EncryptedBlob
class Appointment: class Appointment:
""" """
The Appointment class contains the information regarding an appointment between a client and the Watchtower. The ``Appointment`` contains the information regarding an appointment between a client and the Watchtower.
Args: Args:
locator (str): A 16-byte hex-encoded value used by the tower to detect channel breaches. It serves as a trigger 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. for the tower to decrypt and broadcast the penalty transaction.
start_time (int): The block height at which the tower is hired to start watching for breaches. start_time (int): The block height at which the tower is hired to start watching for breaches.
end_time (int): The block height at which the tower will stop watching for breaches. end_time (int): The block height at which the tower will stop watching for breaches.
dispute_delta (int): The `to_self_delay` encoded in the CSV of the HTLC that this appointment is covering. dispute_delta (int): The ``to_self_delay`` encoded in the ``csv`` of the ``htlc`` that this appointment is
encrypted_blob (EncryptedBlob): An `EncryptedBlob` object containing an encrypted penalty transaction. covering.
The tower will decrypt it and broadcast the penalty transaction upon seeing a breach on the blockchain. encrypted_blob (EncryptedBlob): An :mod:`EncryptedBlob <pisa.encrypted_blob>` object containing an encrypted
penalty transaction. The tower will decrypt it and broadcast the penalty transaction upon seeing a breach on
the blockchain.
""" """
# DISCUSS: 35-appointment-checks # DISCUSS: 35-appointment-checks
@@ -34,13 +36,13 @@ class Appointment:
Args: Args:
appointment_data (dict): a dictionary containing the following keys: appointment_data (dict): a dictionary containing the following keys:
`{locator, start_time, end_time, dispute_delta, encrypted_blob}` ``{locator, start_time, end_time, dispute_delta, encrypted_blob}``
Returns: Returns:
Appointment: An appointment initialized using the provided data. Appointment: An appointment initialized using the provided data.
Raises: Raises:
ValueError: If one of the mandatory keys is missing in `appointment_data`. ValueError: If one of the mandatory keys is missing in ``appointment_data``.
""" """
locator = appointment_data.get("locator") locator = appointment_data.get("locator")
@@ -59,10 +61,10 @@ class Appointment:
def to_dict(self): def to_dict(self):
""" """
Exports an `Appointment` as a dictionary. Exports an appointment as a dictionary.
Returns: Returns:
appointment (dict): A dictionary containing the `Appointment` attributes. appointment (dict): A dictionary containing the appointment attributes.
""" """
@@ -79,15 +81,16 @@ class Appointment:
def to_json(self, triggered=False): def to_json(self, triggered=False):
""" """
Exports an `Appointment` as a deterministic json encoded string. Exports an appointment as a deterministic json encoded string.
This method ensures that multiple invocations with the same data yield the same value. This is the format used This method ensures that multiple invocations with the same data yield the same value. This is the format used
to store appointments in the database. to store appointments in the database.
Args: Args:
triggered (bool): Whether the dispute has been triggered or not. When an appointment passes from the triggered (bool): Whether the dispute has been triggered or not. When an appointment passes from the
`Watcher` to the `Responder` it is not deleted straightaway. Instead, the appointment is stored in the :mod:`Watcher <pisa.watcher>` to the :mod:`Responder <pisa.responder>` it is not deleted straightaway.
DB flagged as triggered. This aims to ease handling block reorgs in the future. Instead, the appointment is stored in the DB flagged as ``triggered``. This aims to ease handling block
reorgs in the future.
Returns: Returns:
appointment (str): A json-encoded str representing the appointment. appointment (str): A json-encoded str representing the appointment.