07caee2dbd
- Updates `Retrier::run` to return more meaningful errors. `Retrier::run` used to simply return a message, revamps it to return RetryError variants so we can handle return cases better. - Adds an additional state to `RetrierStatus`: Idle. Retries that fail due to an accumulation of transient errors will be flagged as Idle instead of Failed and retried later on (based on `auto_retry_delay`). Notice Retrier data is not kept in memory while a retrier is Idle. Instead, data is cleared and loaded again from the database when the `Retrier` is ready to run again. - Revamps how revocation data is sent to the `RetryManager`: The RetrierManager used to received locators one by one via unreachable_towers. This is due to them being mainly fed by `on_commitment_revocation`, which generates them one by one. However, both when manually retrying or when bootstrapping from an already populated database, multiple appointments may be pending for the same tower, hence needing to call `unreachable_towers.send` multiple times for the same tower. This itself was not a big deal, given we didn't really needed to differentiate between the cases. We do now though. In order to implement periodic retries while allowing manual retries we need to be able to signal the state transition to the `Retrier` without providing any new data: - If a Retrier is idle and we receive data trough `on_commitment_revocation` we need to append that data to the `Retrier`. - If a Retrier is iddle and we receive data trough a manual retry, we need to change the state of the `Retrier` without adding any new data to it. In order to implement this we've added an additional map to `WTClient` that reports the state of the active retriers. Retriers are active only if they are running or idle. - Also reworks `WTClient::set_tower_status` to update the status only if the new one does not match the old one. This is simply to reduce the boiler plate of having to perform this check in other pats of the plugin codebase. |
||
|---|---|---|
| .github/workflows | ||
| teos | ||
| teos-common | ||
| watchtower-plugin | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CONTRIBUTING.md | ||
| DEPENDENCIES.md | ||
| INSTALL.md | ||
| LICENSE | ||
| README.md | ||
THIS IS CURRENTLY WIP
The Eye of Satoshi (rust-teos)
The Eye of Satoshi is a Lightning watchtower compliant with BOLT13, written in Rust.
rust-teos consists of two main crates:
teos: including the tower's main functionality (server-side) and a CLI. Compiling this crate will generate two binaries:teosdandteos-cli.teos-common: including shared functionality between server and client-side (useful to build a client).
Dependencies
Refer to DEPENDENCIES.md
Installation
Refer to INSTALL.md
Running TEOS
Make sure bitcoind is running before running teosd (it will fail at startup if it cannot connect to bitcoind). Here you can find a sample bitcoin.conf.
Starting the tower daemon ♖
Once installed, you can start the tower by running:
teosd
Configuration file and command line parameters
teosd comes with a default configuration that can be found at teos/src/config.rs.
The configuration includes, amongst others, where your data folder is placed, what network it connects to, etc.
To change the configuration defaults you can:
- Define a configuration file named
teos.tomlfollowing the template (check conf_template.toml) and place it in thedata_dir(that defaults to~/.teos/).
and/or
- Add some global options when running the daemon (run
teosd -hfor more info).
Passing command-line options to teosd
Some configuration options can also be specified when running teosd. We can, for instance, change the tower data directory as follows:
teosd --datadir=<path_to_dir>
Running teosd in another network
By default, teosd runs on mainnet. In order to run it on another network, you need to change the network parameter in the configuration file or pass the network parameter as a command-line option. Notice that if teosd does not find a bitcoind node running in the same network that it is set to run, it will refuse to run.
The configuration file option to change the network where teosd will run is btc_network:
btc_network = mainnet
For regtest, it should look like:
btc_network = regtest
Running teosd with tor
This requires a Tor daemon running on the same machine as teosd and a control port open on that daemon.
Download Tor from the torproject site.
To open tor's control port, you add the following to the Tor config file (source):
## The port on which Tor will listen for local connections from Tor
## controller applications, as documented in control-spec.txt.
ControlPort 9051
## If you enable the controlport, be sure to enable one of these
## authentication methods, to prevent attackers from accessing it.
CookieAuthentication 1
CookieAuthFileGroupReadable 1
Once the Tor daemon is running, and the control port is open, make sure to enable --torsupport when running teosd.
Tower id and signing key
teosd needs a pair of keys that will serve as tower id and signing key. The former can be used by users to identify the tower, whereas the latter is used by the tower to sign responses. These keys are automatically generated on the first run and can be refreshed by running teosd with the --overwritekey flag. Notice that once a key is overwritten you won't be able to use the previous key again*.
* Old keys are actually kept in the tower's database as a fail-safe in case you overwrite them by mistake. However, there is no automated way of switching back to an old key. Feel free to open an issue if you overwrote your key by mistake and need support to recover it.
Interacting with a TEOS instance
You can interact with a teosd instance (either run by yourself or someone else) by using teos-cli. This is an admin tool that has privileged access to the watchtower, and it should therefore only be used within a trusted environment (for example, the same machine).
While teos-cli works independently of teosd, it shares the same configuration file by default, of which it only uses a subset of its settings. The folder can be changed using the --datadir command-line argument if desired.
For help on the available arguments and commands, you can run:
teos-cli -h
Running teos-cli remotely
To run teos-cli remotely, you'll need to take one extra step. When teosd is started up, self-signed certificates are automatically generated for a user to make a secure connection to the remote TEOS watchtower. When the CLI is run locally, it knows where to find these files. But if run remotely, these files need to be copied over to the machine where the CLI is being run.
The files are generated to the data directory (by default stored at ~/.teos/). To run remotely, users need to copy the client.pem, client-key.pem, and ca.pem files to the corresponding watchtower data directory on the machine where the CLI is being run. That is, by default, to ~/.teos/ on the remote machine.
Interacting with TEOS as a client
TEOS clients
Here is a list of the available clients for teos:
Contributing
Refer to CONTRIBUTING.md