eclair/docs/Tor.md

## How to Use Tor with Eclair

Current supported version of Tor is 0.3.3.6 or higher.

### Installing Tor on your node

#### Linux:

```shell
sudo apt install tor
```

#### Mac OS X:

```shell
brew install tor
```

#### Windows:
  
[Download the "Expert Bundle"](https://www.torproject.org/download/tor/) from Tor's website and extract it to `C:\tor`.

### Configuring Tor

#### Linux and Max OS X:

Eclair requires safe cookie authentication as well as SOCKS5 and control connections to be enabled.

Edit Tor configuration file `/etc/tor/torrc` (Linux) or `/usr/local/etc/tor/torrc` (Mac OS X).

```
SOCKSPort 9050
ControlPort 9051
CookieAuthentication 1
ExitPolicy reject *:* # don't change this unless you really know what you are doing
```

Make sure eclair is allowed to read Tor's cookie file (typically `/var/run/tor/control.authcookie`).

#### Windows:

On Windows, it is easier to use the password authentication mechanism.

First pick a password and hash it with this command:

```shell
$ cd c:\tor\Tor
$ tor --hash-password this-is-an-example-password-change-it
16:94A50709CAA98333602756426F43E6AC6760B9ADEF217F58219E639E5A
```

Create a Tor configuration file (`C:\tor\Conf\torrc`), edit it and replace the value for `HashedControlPassword` with the result of the command above.

```
SOCKSPort 9050
ControlPort 9051
HashedControlPassword 16:--REPLACE--THIS--WITH--THE--HASH--OF--YOUR--PASSWORD--
ExitPolicy reject *:* # don't change this unless you really know what you are doing
```

### Start Tor

#### Linux:

```shell
sudo systemctl start tor
```

#### Mac OS X:

```shell
brew services start tor
```

#### Windows:

Open a CMD with administrator access

```shell
cd c:\tor\Tor
tor --service install -options -f "c:\tor\Conf\torrc"
```

### Configure Tor hidden service

To create a Tor hidden service endpoint simply set the `eclair.tor.enabled` parameter in `eclair.conf` to true.
```
eclair.tor.enabled = true
```

Next set the TOR authentication method. The choices are `safecookie` or `password`.  
```
eclair.tor.auth = safecookie
# eclair.tor.password = ""      # Needed if you set auth to password
```

Eclair will automatically set up a hidden service endpoint and add its onion address to the `server.public-ips` list.
You can see what onion address is assigned using `eclair-cli`:

```shell
eclair-cli getinfo
```
Eclair saves the Tor endpoint's private key in `~/.eclair/tor.dat`, so that it can recreate the endpoint address after 
a restart. If you remove the private key Eclair will regenerate the endpoint address.   
 
For increased privacy do not advertise your IP address in the `server.public-ips` list, and set your binding IP to `localhost`:
```
eclair.server.binding-ip = "127.0.0.1"
```

By default, the onion address generated by the hidden service will be added to the list of the node's public addresses.
If you want to keep it private use this config parameter:
```
eclair.tor.publish-onion-address = false
```

You can always see your node's onion address using `getinfo` CLI command.

### Configure SOCKS5 proxy

By default, all incoming connections will be established via Tor network, but all outgoing will be created via the 
clearnet. To route them through Tor you can use Tor's SOCKS5 proxy. Add this line in your `eclair.conf`:
```
eclair.socks5.enabled = true
```
You can use SOCKS5 proxy only for specific types of addresses. Use `eclair.socks5.use-for-ipv4`, `eclair.socks5.use-for-ipv6`
or `eclair.socks5.use-for-tor` for fine-tuning.

To create a new Tor circuit for every connection, use `randomize-credentials` parameter:

```
eclair.socks5.randomize-credentials = true
```

:warning: Tor hidden service and SOCKS5 are independent options. You can use just one of them, but if you want to get most privacy 
features from using Tor, use both.

Note, that bitcoind should be configured to use Tor as well (https://en.bitcoin.it/wiki/Setting_up_a_Tor_hidden_service).

### Blockchain watchdogs

Eclair version 0.5.0 introduced blockchain watchdogs, that fetch bitcoin headers from various sources in 
order to detect whether the node is being eclipsed. Eclair supports four sources at the moment:

* blockchainheaders.net
* blockcypher.com
* blockstream.info
* mempool.space

Once `eclair.socks5.enabled` is set to `true` blockchain watchdogs connect to their respective sources over Tor.

The most Tor-friendly sources are `blockstream.info` and `mempool.space` since they have native onion endpoints for their APIs.

Tor support for `blockchainheaders.net` is not implemented (yet), so it gets automatically disabled when `eclair.socks5.enabled = true` to protect user's privacy.

`blockcypher.com` can be flaky when used over Tor. It imposes rate limits and sometimes (rather often in fact) requires solving CAPTCHA.
If you experience similar troubles with `blockcypher.com` use this config parameter to disable it:

```
eclair.blockchain-watchdog.sources = [
  "bitcoinheaders.net",
  "blockstream.info",
  "mempool.space"
]
```

Also, you can disable Tor for all watchdog sources altogether using:

```s
eclair.socks5.use-for-watchdogs = false
```