mirrors/eclair
1
0
Fork 0
mirror of https://github.com/ACINQ/eclair.git synced 2025-02-23 14:40:34 +01:00
Code Issues Projects Releases Wiki Activity

Move path-finding examples to documentation (#1983)

Browse source 
Having basic documentation in-place by providing examples in
`eclair.conf` is great and very convenient, but in the case of
path-finding, defining experiments take so much space that it makes
the whole configuration file actually more complicated to understand.
And since we don't want to enable experiments by default, the user still
has to figure out what to change to actually enable AB-testing.

Co-authored-by: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
This commit is contained in:
Pierre-Marie Padiou 2021-10-04 10:29:27 +02:00 • committed by GitHub
parent 3295881e48
commit 73744ee440
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 158 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

146
docs/Configure.md
View file

@ -1,20 +1,48 @@
# Configuring Eclair
Eclair reads its configuration file, and writes its logs, to `~/.eclair` by default.
You can change this behavior with the `eclair.datadir` parameter:
---
* [Configuration file](#configuration-file)
* [Changing the data directory](#changing-the-data-directory)
* [Splitting the configuration](#splitting-the-configuration)
* [Options reference](#options-reference)
* [Customize features](#customize-features)
* [Customize feerate tolerance](#customize-feerate-tolerance)
* [Examples](#examples)
* [Basic configuration](#basic-configuration)
* [Regtest mode](#regtest-mode)
* [Public node](#public-node)
* [AB-testing for path-finding](#ab-testing-for-path-finding)
---
## Configuration file
The configuration file for eclair is named `eclair.conf`. It is located in the data directory, which is `~/.eclair` by
default. Note that eclair won't create a configuration file by itself: if you want to change eclair's configuration, you
need to **actually create the configuration file first**. The encoding must be UTF-8.
```sh
# this is the default data directory, it will be created at eclair first startup
mkdir ~/.eclair
vi ~/.eclair/eclair.conf
```
Options are set as key-value pairs and follow the [HOCON syntax](https://github.com/lightbend/config/blob/master/HOCON.md).
Values do not need to be surrounded by quotes, except if they contain special characters.
### Changing the data directory
You can change the data directory with the `eclair.datadir` parameter:
```sh
eclair-node.sh -Declair.datadir="/path/to/custom/eclair/data/folder"
```
## Change your node's configuration
### Splitting the configuration
The first step is to **actually create the configuration file**.
Go to `eclair.datadir` and create a file named `eclair.conf`.
The encoding should be UTF-8.
Options are set as key-value pairs and follow the [HOCON syntax](https://github.com/lightbend/config/blob/master/HOCON.md).
Values do not need to be surrounded by quotes, except if they contain special characters.
Note that HOCON allows you to have files include other files. This allows you to split your configuration file into
several logical files, for easier management. For example, you could define a file `routing.conf` file with parameters
related to routing configuration, and include it from `eclair.conf`.
## Options reference
@ -174,3 +202,103 @@ eclair.server.public-ips=[x.x.x.x]
```
You'll also have to make sure the node is accessible from the outside world (port forwarding, firewall,...).
### AB-testing for path-finding
The following configuration enables AB-testing by defining a set of `experiments`, and assigning a percentage of the
traffic to each experiment. The `control` experiment doesn't override any parameter, it uses the defaults.
Note that the percentages of all experiments sum to 100 %.
```conf
eclair {
router {
path-finding {
experiments {
control = ${eclair.router.path-finding.default} {
percentage = 50
}
// alternative routing heuristics (replaces ratios)
test-failure-cost = ${eclair.router.path-finding.default} {
use-ratios = false
locked-funds-risk = 1e-8 // msat per msat locked per block. It should be your expected interest rate per block multiplied by the probability that something goes wrong and your funds stay locked.
// 1e-8 corresponds to an interest rate of ~5% per year (1e-6 per block) and a probability of 1% that the channel will fail and our funds will be locked.
// Virtual fee for failed payments
// Corresponds to how much you are willing to pay to get one less failed payment attempt
failure-cost {
fee-base-msat = 2000
fee-proportional-millionths = 500
}
percentage = 10
}
// To optimize for fees only:
test-fees-only = ${eclair.router.path-finding.default} {
ratios {
base = 1
cltv = 0
channel-age = 0
channel-capacity = 0
}
hop-cost {
fee-base-msat = 0
fee-proportional-millionths = 0
}
percentage = 10
}
// To optimize for shorter paths:
test-short-paths = ${eclair.router.path-finding.default} {
ratios {
base = 1
cltv = 0
channel-age = 0
channel-capacity = 0
}
hop-cost {
// High hop cost penalizes strongly longer paths
fee-base-msat = 10000
fee-proportional-millionths = 10000
}
percentage = 10
}
// To optimize for successful payments:
test-pay-safe = ${eclair.router.path-finding.default} {
ratios {
base = 0
cltv = 0
channel-age = 0.5 // Old channels should have less risk of failures
channel-capacity = 0.5 // High capacity channels are more likely to have enough liquidity to relay our payment
}
hop-cost {
// Less hops means less chances of failures
fee-base-msat = 1000
fee-proportional-millionths = 1000
}
percentage = 10
}
// To optimize for fast payments:
test-pay-fast = ${eclair.router.path-finding.default} {
ratios {
base = 0.2
cltv = 0.5 // In case of failure we want our funds back as fast as possible
channel-age = 0.3 // Older channels are more likely to run smoothly
channel-capacity = 0
}
hop-cost {
// Shorter paths should be faster
fee-base-msat = 10000
fee-proportional-millionths = 10000
}
percentage = 10
}
}
}
}
}
```

110
eclair-core/src/main/resources/reference.conf
View file

@ -93,7 +93,8 @@ eclair {
max-block-processing-delay = 30 seconds // we add a random delay before processing blocks, capped at this value, to prevent herd effect
max-tx-publish-retry-delay = 60 seconds // we add a random delay before retrying failed transaction publication
relay.fees {
relay {
fees {
// Fees for public channels
public-channels {
fee-base-msat = 1000
@ -109,7 +110,8 @@ eclair {
fee-base-msat = 1000
fee-proportional-millionths = 100
}
}
}
}
on-chain-fees {
min-feerate = 1 // minimum feerate in satoshis per byte
@ -194,7 +196,6 @@ eclair {
channel-query-chunk-size = 100 // max number of short_channel_ids in query_short_channel_ids *do not change this unless you know what you are doing*
}
// The values below will be used to perform route searching
path-finding {
default {
randomize-route-selection = true // when computing a route for a payment we randomize the final selection
@ -207,6 +208,7 @@ eclair {
max-fee-proportional-percent = 3 // that's 3%
}
use-ratios = true // if false, will use failure-cost
// channel 'weight' is computed with the following formula: (channelFee + hop-cost) * (ratio-base + cltvDelta * ratio-cltv + channelAge * ratio-channel-age + channelCapacity * ratio-channel-capacity)
// the following parameters can be used to ask the router to use heuristics to find i.e: 'cltv-optimized' routes, **the sum of the four ratios must be 1**
ratios {
@ -215,11 +217,15 @@ eclair {
channel-age = 0.4 // when computing the weight for a channel, consider its AGE in this proportion
channel-capacity = 0.55 // when computing the weight for a channel, consider its CAPACITY in this proportion
}
use-ratios = true
// Virtual fee for additional hops
// Corresponds to how much you are willing to pay to get one less hop in the payment path
locked-funds-risk = 1e-8 // msat per msat locked per block. It should be your expected interest rate per block multiplied by the probability that something goes wrong and your funds stay locked.
// 1e-8 corresponds to an interest rate of ~5% per year (1e-6 per block) and a probability of 1% that the channel will fail and our funds will be locked.
// virtual fee for failed payments: how much you are willing to pay to get one less failed payment attempt
failure-cost {
fee-base-msat = 2000
fee-proportional-millionths = 500
}
hop-cost {
// virtual fee for additional hops: how much you are willing to pay to get one less hop in the payment path
fee-base-msat = 500
fee-proportional-millionths = 200
}
@ -228,94 +234,20 @@ eclair {
min-amount-satoshis = 15000 // minimum amount sent via partial HTLCs
max-parts = 5 // maximum number of HTLCs sent per payment: increasing this value will impact performance
}
percentage = 0 // set all experiments to 0% of the traffic by default
}
// One section per experiment
// The percentages of the traffic for different experiments must sum to 100.
// After starting an experiment, if you want to modify it you should give it a new name. If you don't, then you'll
// end up with metrics for different sets of parameters under the same name.
// The path-finding algo uses one or more sets of parameters named experiments. Each experiment has a percentage
// assigned, allowing AB-testing. By default, there is a single 'control' experiment with a percentage of 100 %.
//
// To enable AB-testing, you need to define experiments below. Note that:
// - each experiment must have a unique name, may override the default parameters, and must provide a percentage
// - the percentages for all experiments must sum to 100
// - experiments should be immutable; if you alter parameters of an experiment, you should also rename it
// - for a complete example, refer to the documentation.
experiments {
control = ${eclair.router.path-finding.default} {
percentage = 100 // 100% of the traffic use the default configuration
}
// alternative routing heuristics (replaces ratios)
test-failure-cost = ${eclair.router.path-finding.default} {
use-ratios = false
locked-funds-risk = 1e-8 // msat per msat locked per block. It should be your expected interest rate per block multiplied by the probability that something goes wrong and your funds stay locked.
// 1e-8 corresponds to an interest rate of ~5% per year (1e-6 per block) and a probability of 1% that the channel will fail and our funds will be locked.
// Virtual fee for failed payments
// Corresponds to how much you are willing to pay to get one less failed payment attempt
failure-cost {
fee-base-msat = 2000
fee-proportional-millionths = 500
}
}
// Examples of other configs as 0% experiments:
// To optimize for fees only:
test-fees-only = ${eclair.router.path-finding.default} {
ratios {
base = 1
cltv = 0
channel-age = 0
channel-capacity = 0
}
hop-cost {
fee-base-msat = 0
fee-proportional-millionths = 0
}
}
// To optimize for shorter paths:
test-short-paths = ${eclair.router.path-finding.default} {
ratios {
base = 1
cltv = 0
channel-age = 0
channel-capacity = 0
}
hop-cost {
// High hop cost penalizes strongly longer paths
fee-base-msat = 10000
fee-proportional-millionths = 10000
}
}
// To optimize for successful payments:
test-pay-safe = ${eclair.router.path-finding.default} {
ratios {
base = 0
cltv = 0
channel-age = 0.5 // Old channels should have less risk of failures
channel-capacity = 0.5 // High capacity channels are more likely to have enough liquidity to relay our payment
}
hop-cost {
// Less hops means less chances of failures
fee-base-msat = 1000
fee-proportional-millionths = 1000
}
}
// To optimize for fast payments:
test-pay-fast = ${eclair.router.path-finding.default} {
ratios {
base = 0.2
cltv = 0.5 // In case of failure we want our funds back as fast as possible
channel-age = 0.3 // Older channels are more likely to run smoothly
channel-capacity = 0
}
hop-cost {
// Shorter paths should be faster
fee-base-msat = 10000
fee-proportional-millionths = 10000
}
}
}
}
}