diff --git a/pisa/api.py b/pisa/api.py index 780a1a9..b5445e0 100644 --- a/pisa/api.py +++ b/pisa/api.py @@ -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 `. """ 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 ` or the + :mod:`Responder ` that signals the status of the appointment. + + - Appointments hold by the :mod:`Watcher ` are flagged as ``being_watched``. + - Appointments hold by the :mod:`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 ` + (``watcher_appointments``) and by the :mod:`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 ` object. """ diff --git a/pisa/appointment.py b/pisa/appointment.py index bb125cd..bf3510e 100644 --- a/pisa/appointment.py +++ b/pisa/appointment.py @@ -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 ` 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 ` to the :mod:`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.