aljaz/python-teos
1
0
Fork 0
mirror of https://github.com/aljazceru/python-teos.git synced 2025-12-18 06:34:19 +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.
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:
tuple: A tuple containing the response (json) and response code (`int:rcode`). For accepted appointments, the
`rcode` is always 0 and the response contains the signed receipt. For rejected appointments, the `rcode` is a
negative value and the response contains the error message. Error messages can be found at
(errors.py)[./errors.py]
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 negative value and the response contains the error message. Error messages can be found at
:mod:`Errors <pisa.errors>`.
"""
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.
The information is requested by locator.
The information is requested by ``locator``.
Returns:
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
of the appointment. Appointments hold by the `Watcher` are flagged as `being_watched` whereas appointments that
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`.
A ``status`` flag is added to the data provided by either the :mod:`Watcher <pisa.watcher>` or the
:mod:`Responder <pisa.responder>` that signals the status of the appointment.
- 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")
@@ -141,8 +143,8 @@ def get_all_appointments():
This endpoint should only be accessible by the administrator. Requests are only allowed from localhost.
Returns:
dict: a json formatted dictionary containing all the appointments hold by the `Watcher` (`watcher_appointments)`
and by the `Responder` (`responder_jobs`).
dict: a json formatted dictionary containing all the appointments hold by the :mod:`Watcher <pisa.watcher>`
(``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.
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:
"""
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:
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.
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.
dispute_delta (int): The `to_self_delay` encoded in the CSV of the HTLC that this appointment is covering.
encrypted_blob (EncryptedBlob): An `EncryptedBlob` object containing an encrypted penalty transaction.
The tower will decrypt it and broadcast the penalty transaction upon seeing a breach on the blockchain.
dispute_delta (int): The ``to_self_delay`` encoded in the ``csv`` of the ``htlc`` that this appointment is
covering.
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
@@ -34,13 +36,13 @@ class Appointment:
Args:
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:
Appointment: An appointment initialized using the provided data.
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")
@@ -59,10 +61,10 @@ class Appointment:
def to_dict(self):
"""
Exports an `Appointment` as a dictionary.
Exports an appointment as a dictionary.
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):
"""
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
to store appointments in the database.
Args:
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
DB flagged as triggered. This aims to ease handling block reorgs in the future.
:mod:`Watcher <pisa.watcher>` to the :mod:`Responder <pisa.responder>` it is not deleted straightaway.
Instead, the appointment is stored in the DB flagged as ``triggered``. This aims to ease handling block
reorgs in the future.
Returns:
appointment (str): A json-encoded str representing the appointment.