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

plugin - Improves README and defaults misbehaving_proof to empty dict

Browse Source
This commit is contained in:
Sergi Delgado Segura
2020-05-08 19:42:39 +02:00
parent 445d4c0aca
commit f2162b6add
2 changed files with 22 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
watchtower-plugin/README.md
View File

@@ -1,34 +1,34 @@
# Watchtower client
This is a Watchtower client plugin to interact with an [Eye of Satoshi tower](https://github.com/talaia-labs/python-teos),
and eventually to any [BOLT13](https://github.com/sr-gi/bolt13/blob/master/13-watchtowers.md) compliant Watchtower.
and eventually with any [BOLT13](https://github.com/sr-gi/bolt13/blob/master/13-watchtowers.md) compliant Watchtower.
The plugin manages all the client-side logic to send appointment to a number of registered towers every time a new
commitment transaction is generated. It also keeps track of a summary of what has been sent and what the tower has responded.
commitment transaction is generated. It also keeps a summary of the messages sent to the towers and their responses.
The plugin has the following methods:
- `registertower tower_id` : registers the user id (compressed public key) with a given tower.
- `list_towers`: lists all the registered towers.
- `list_towers`: lists all registered towers.
- `gettowerinfo tower_id`: gets all the locally stored data about a given tower.
- `retrytower tower_id`: tries to send pending appointment to a (previously) unreachable tower.
- `getappointment tower_id locator`: queries an appointment to a given tower.
The plugin also has an implicit `add_appointment` method triggered via the `commitment_revocation` hook.
The plugin also has an implicit method to send appointments to the registered towers for every new commitment transaction.
# Config file, data folder and first bootstrap
The plugin will create a data folder under the user's home directory (`~/.watchtower`). All the plugin's data will be stored in the data folder. A config file (`watchtower.conf`) can be placed in the data folder to modify some of the configuration defaults (check [template.conf](template.conf)).
The plugin creates a data folder under the user's home folder (`~/.watchtower`), where all the plugin's data is stored. A config file (`watchtower.conf`) can be placed in the data folder to modify some of the configuration defaults (check [template.conf](template.conf)).
On first bootstrap, the plugin will generate a key pair that will be used as the user identifier. All request from the user will be signed using that the secret key, so the tower can authenticate the user after the registration process (`registertower`).
On first bootstrap, the plugin generates a key pair that is used as the user identifier. All requests from the user are signed using the secret key, so the tower can authenticate the user after the registration process (`registertower`).
All the appointments generated by the tower, as well as all the registered towers data, are stored on a `leveldb` under `~/.watchtower/towers`.
All the appointments generated by the tower, as well as all the registered towers' data, are stored on a `leveldb` under `~/.watchtower/towers`.
# Getting started
## Registering with a tower
Once the plugin is loaded in your node, the first step will be to register your node with a active tower. You can do so by running:
Once the plugin is loaded in your node, the first step is to register your node with an active tower. You can do so by running:
```
lightning-cli registertower tower_id [host, port]
@@ -52,18 +52,16 @@ If the tower is online, you should get back a response similar to this:
}
```
Where `available_slots` is the amount of free slots the user has available in the tower, `public_key` is the user's public key (`user_id` for now on) and `subscription_expiry` is the block height when the subscription will expire. In this example, the user has **10000** slots to use in, roughly, **the next month**.
Where `available_slots` is the amount of free slots the user has available in the tower, `public_key` is the user's public key (`user_id` for now on) and `subscription_expiry` is the block height when the subscription expires. Generally speaking, a slot fits an appointment, so in this example the user can send **10000** appointments in roughly **one month**.
Notice that, ideally, the client and the tower will agree on the **subscription details** (`available_slots` and `subscription_expiry`). Currently, those depend only on the tower, since it is offering the service for free. However, in the current state, hitting `registertower` again will add another `10000` slots and reset the time to `current_height + roughtly_one_mont_in_blocks`.
Notice that, ideally, the client and the tower have to agree on the **subscription details** (`available_slots` and `subscription_expiry`). Currently, those depend only on the tower, since it is offering the service for free. However, in the current state, hitting `registertower` again will add another `10000` slots and reset the time to `current_height + roughtly_one_mont_in_blocks`.
## Sending data to the tower
Once your node is registered with at least one tower it will start sending appointments to the tower for every commitment transaction update on any of your channels. In the current version of the plugin, everything is sent to every register tower (**full replication**). There's nothing to be done here, under normal conditions, the plugin takes care of it.
Once your node is registered with at least one tower it will start sending appointments to the tower for every commitment transaction update on any of your channels. In the current version of the plugin, everything is sent to every registered tower (**full replication**). There is nothing to be done here, under normal conditions, the plugin takes care of it.
## Checking the state of the towers
There are two commands you can run to check what is going on with the towers you are sending data to `list_towers` and `gettowerinfo`.
`listtowers` will simply give you an overview of what towers you are registered with and what the current state of them:
To find out more information about registered towers, you can use `list_towers` and `gettowerinfo`:
```
lightning-cli listtowers
@@ -88,23 +86,23 @@ lightning-cli listtowers
The overview contains the `id` and network address of the tower (`netaddr`), as well as the current `status` and two list of appointments: **pending** and **invalid**.
The tower can be in 5 status:
The tower has 5 differents states:
- `reachable`: the tower is reachable at the given network address.
- `temporarily unreachable`: the tower is temporarily unreachable, meaning that one of the last requests sent to it has failed.
- `unreachable`: the tower has been unreachable for a while.
- `misbehaving`: the tower has send us incorrect data.
- `misbehaving`: the tower has sent us incorrect data.
- `subscription_error`: the subscription with the tower has expired or run out of slots.
The main difference between `temporarily unreachable` and `unreachable` is has much time has passed. If a tower is temporarily unreachable, a backoff strategy will be triggered and all the appointments that cannot be delivered will be stored under `pending_appointments`. If the tower comes back online within the retry strategy, every pending appointment will be sent trough and the tower will be flagged back as `reachable`. However, if the backoff strategy ends up giving up, the tower will be flagged as `unreachable`.
The main difference between `temporarily unreachable` and `unreachable` is the amount of time that has passed since we last received a response. If a tower is temporarily unreachable, a backoff strategy is triggered and all the appointments that cannot be delivered are stored under `pending_appointments`. If the tower comes back online within the retry strategy, every pending appointment is sent through and the tower is flagged back as `reachable`. However, if the backoff strategy ends up giving up, the tower is flagged as `unreachable`.
If the client receives data from a tower that it is not properly signed, the tower is flagged as `misbehaving` and it is abandoned, meaning that no more appointments will be sent to it. This state should never be reached by honest towers.
If the client receives data from a tower that is not properly signed, the tower is flagged as `misbehaving` and it is abandoned, meaning that no more appointments are sent to it. This state should never be reached by honest towers.
A `subscription error` means that the subscription needs to be renewed (hit `registertower` again).
Regarding `pending_appointments` and `invalid_appointments` they store the data that is pending to be sent to the tower (for unreachable towers) and the appointments that have been rejected by the tower for being invalid, respectively. The later should never get populated for honest clients.
Regarding `pending_appointments` and `invalid_appointments` they store the data that is pending to be sent to the tower (for unreachable towers) and the appointments that have been rejected by the tower for being invalid, respectively. The latter should never get populated for honest clients.
`gettowerinfo` will give us more detailed information about the tower:
`gettowerinfo` provides more detailed information about the tower:
**Usage**
@@ -149,7 +147,7 @@ lightning-cli gettowerinfo 0230053e39c53b8bcb43354a4ed886b8082af1d1e8fc14956e60a
}
],
"invalid_appointments": [],
"misbehaving_proof": null
"misbehaving_proof": {}
}
```
@@ -157,7 +155,7 @@ Notice that there are two new fields in this report: `appointments` and `misbeha
`appointments` contains a collection of `locator:tower_signature` pairs of all the appointments sent and accepted by the tower.
`misbehaving_proof` contains a proof of misbehaviour of the tower in the form of an `appointment:wrong_signature` pair. In this case the tower has not misbehaved, so it is set to `null`.
`misbehaving_proof` contains a proof of misbehaviour of the tower in the form of an `appointment:wrong_signature` pair. In this case the tower has not misbehaved, so it is empty.
Finally, notice how `pending_appointments` now contains all the data about the pending appointments (**the full appointment plus the signature**). The same applies to `invalid_appointments`.
@@ -181,8 +179,7 @@ lightning-cli retrytower 03623859b406e83ec7fab195cd67f1ba9e6d46bc07fac3e900351d6
03623859b406e83ec7fab195cd67f1ba9e6d46bc07fac3e900351d657dd8ad05aa"
```
Notice that this will only work provided the tower is in **unreachable** or **subscription error** state. A tower cannot be retried if it is already being retried (**temporarily unreachable**), or if it is **misbehaving**.
Notice that this only works if the tower is in **unreachable** or **subscription error** state. A tower cannot be retried if it is already being retried (**temporarily unreachable**), or if it has **misbehaved**.
## Query data from a tower
Data can be queried from a tower to check, for instance, that the tower is keeping it or that it is correct. This can be done using the `getappointment` command:

2
watchtower-plugin/tower_info.py
View File

@@ -29,7 +29,7 @@ class TowerInfo:
self.appointments = {}
self.pending_appointments = []
self.invalid_appointments = []
self.misbehaving_proof = None
self.misbehaving_proof = {}
@classmethod
def from_dict(cls, tower_data):