getroute: change definition (and pay default) for riskfactor.
Up until now, riskfactor was useless due to implementation bugs, and
also the default setting is wrong (too low to have an effect on
reasonable payment scenarios).
Let's simplify the definition (by assuming that P(failure) of a node
is 1), to make it a simple percentage. I examined the current network
fees to see what would work, and under this definition, a default of
10 seems reasonable (equivalent to 1000 under the old definition).
It is *this* change which finally fixes our test case! The riskfactor
is now 40msat (1500000 * 14 * 10 / 5259600 = 39.9), comparable with
worst-case fuzz is 50msat (1001 * 0.05 = 50).
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@ -36,9 +36,9 @@ lightning-getroute \- Command for routing a payment (low\-level)\&.
.sp
.sp
The \fBgetroute\fR RPC command attempts to find the best route for the payment of \fImsatoshi\fR to lightning node \fIid\fR, such that the payment will arrive at \fIid\fR with \fIcltv\fR\-blocks to spare (default 9)\&.
The \fBgetroute\fR RPC command attempts to find the best route for the payment of \fImsatoshi\fR to lightning node \fIid\fR, such that the payment will arrive at \fIid\fR with \fIcltv\fR\-blocks to spare (default 9)\&.
.sp
.sp
There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck if a node goes down during the process\&. The \fIriskfactor\fR floating\-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage), multiplied by the percentage chance of each node failing\&.
There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck if a node goes down during the process\&. The \fIriskfactor\fR floating\-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage)\&.
.sp
.sp
For example, if you thought there was a 1% chance that a node would fail, and it would cost you 20% per annum if that happened, \fIriskfactor\fR would be 20\&.
For example, if you thought the inconvenience of having funds stuck was worth 20% per annum interest, \fIriskfactor\fR would be 20\&.
.sp
.sp
If you didn\(cqt care about risk, \fIriskfactor\fR would be zero\&.
If you didn\(cqt care about risk, \fIriskfactor\fR would be zero\&.
.sp
.sp
@ -55,15 +55,13 @@ The formula used is the following approximation:
.RS4
.RS4
.\}
.\}
.nf
.nf
hop\-risk = num\-hops x per\-hop\-risk
risk\-fee = amount x blocks\-timeout x per\-block\-cost
timeout\-cost = blocks\-timeout x per\-block\-cost
risk\-fee = amount x hop\-risk x timeout\-cost
.fi
.fi
.ifn\{\
.ifn\{\
.RE
.RE
.\}
.\}
.sp
.sp
We are given a \fIriskfactor\fR; expressed as two multiplied percentages is the same as fractions multiplied by 10000\&. There are 52596 blocks per year, thus \fIper\-block\-cost\fRx \fIper\-hop\-risk\fR is riskfactor\*(Aq divided by 5,259,600,000\&.
We are given a \fIriskfactor\fR expressed as a percentage\&. There are 52596 blocks per year, thus \fIper\-block\-cost\fRis \fIriskfactor\fR divided by 5,259,600\&.
.sp
.sp
The final result is:
The final result is:
.sp
.sp
@ -71,26 +69,26 @@ The final result is:
.RS4
.RS4
.\}
.\}
.nf
.nf
risk\-fee = amount x num\-hops x blocks\-timeout x riskfactor / 5259600000
risk\-fee = amount x blocks\-timeout x riskfactor / 5259600
.fi
.fi
.ifn\{\
.ifn\{\
.RE
.RE
.\}
.\}
.sp
.sp
Here are the risk fees as a percentage of the amount sent, using various parameters\&. For comparison with actual fees, we assume nodes charge 0\&.05%:
Here are the risk fees in millisatoshis, using various parameters\&. I assume a channel charges the default of 1000 millisatoshis plus 1 part\-per\-million\&. Common delay values on the network at 14 and 144\&.
.TS
.TS
allbox tab(:);
allbox tab(:);
ltB ltB ltB ltB ltB.
ltB ltB ltB ltB ltB.
T{
T{
Riskfactor
Amount (msat)
T}:T{
T}:T{
Nodes
Riskfactor
T}:T{
T}:T{
Delay per node
Delay
T}:T{
T}:T{
Risk Fee %
Risk Fee
T}:T{
T}:T{
Route fee %
Route fee
T}
T}
.T&
.T&
lt lt lt lt lt
lt lt lt lt lt
@ -101,160 +99,417 @@ lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt
lt lt lt lt lt.
lt lt lt lt lt.
T{
T{
.sp
.sp
0\&.001
10,000
T}:T{
T}:T{
.sp
.sp
5
1
T}:T{
T}:T{
.sp
.sp
6
14
T}:T{
T}:T{
.sp
.sp
0
0
T}:T{
T}:T{
.sp
.sp
0\&.25
1001
T}
T}
T{
T{
.sp
.sp
1
10,000
T}:T{
T}:T{
.sp
.sp
5
10
T}:T{
T}:T{
.sp
.sp
6
14
T}:T{
T}:T{
.sp
.sp
0
0
T}:T{
T}:T{
.sp
.sp
0\&.25
1001
T}
T{
.sp
10,000
T}:T{
.sp
100
T}:T{
.sp
14
T}:T{
.sp
2
T}:T{
.sp
1001
T}
T}
T{
T{
.sp
.sp
10,000
T}:T{
.sp
1000
1000
T}:T{
T}:T{
.sp
.sp
5
14
T}:T{
T}:T{
.sp
.sp
6
26
T}:T{
T}:T{
.sp
.sp
0\&.0029
1001
T}
T{
.sp
1,000,000
T}:T{
T}:T{
.sp
.sp
0\&.25
1
T}:T{
.sp
14
T}:T{
.sp
2
T}:T{
.sp
1001
T}
T}
T{
T{
.sp
.sp
0\&.001
1,000,000
T}:T{
T}:T{
.sp
.sp
10
10
T}:T{
T}:T{
.sp
.sp
72
14
T}:T{
T}:T{
.sp
.sp
0
26
T}:T{
T}:T{
.sp
.sp
0\&.5
1001
T}
T}
T{
T{
.sp
.sp
1,000,000
T}:T{
.sp
100
T}:T{
.sp
14
T}:T{
.sp
266
T}:T{
.sp
1001
T}
T{
.sp
1,000,000
T}:T{
.sp
1000
T}:T{
.sp
14
T}:T{
.sp
2661
T}:T{
.sp
1001
T}
T{
.sp
100,000,000
T}:T{
.sp
1
1
T}:T{
T}:T{
.sp
.sp
14
T}:T{
.sp
266
T}:T{
.sp
1100
T}
T{
.sp
100,000,000
T}:T{
.sp
10
10
T}:T{
T}:T{
.sp
.sp
72
14
T}:T{
.sp
2661
T}:T{
.sp
1100
T}
T{
.sp
100,000,000
T}:T{
.sp
100
T}:T{
T}:T{
.sp
.sp
0\&.0001
14
T}:T{
T}:T{
.sp
.sp
0\&.5
26617
T}:T{
.sp
1100
T}
T}
T{
T{
.sp
.sp
100,000,000
T}:T{
.sp
1000
1000
T}:T{
T}:T{
.sp
.sp
14
T}:T{
.sp
266179
T}:T{
.sp
1100
T}
T{
.sp
10,000
T}:T{
.sp
1
T}:T{
.sp
144
T}:T{
.sp
0
T}:T{
.sp
1001
T}
T{
.sp
10,000
T}:T{
.sp
10
10
T}:T{
T}:T{
.sp
.sp
72
144
T}:T{
T}:T{
.sp
.sp
0\&.1369
2
T}:T{
T}:T{
.sp
.sp
0\&.5
1001
T}
T}
T{
T{
.sp
.sp
0\&.001
10,000
T}:T{
T}:T{
.sp
.sp
20
100
T}:T{
T}:T{
.sp
.sp
1008
144
T}:T{
T}:T{
.sp
.sp
0
27
T}:T{
T}:T{
.sp
.sp
1\&.0
1001
T}
T}
T{
T{
.sp
.sp
10,000
T}:T{
.sp
1000
T}:T{
.sp
144
T}:T{
.sp
273
T}:T{
.sp
1001
T}
T{
.sp
1,000,000
T}:T{
.sp
1
1
T}:T{
T}:T{
.sp
.sp
20
144
T}:T{
.sp
27
T}:T{
.sp
1001
T}
T{
.sp
1,000,000
T}:T{
.sp
10
T}:T{
.sp
144
T}:T{
.sp
273
T}:T{
.sp
1001
T}
T{
.sp
1,000,000
T}:T{
.sp
100
T}:T{
T}:T{
.sp
.sp
1008
144
T}:T{
T}:T{
.sp
.sp
0\&.0077
2737
T}:T{
T}:T{
.sp
.sp
1\&.0
1001
T}
T}
T{
T{
.sp
.sp
1,000,000
T}:T{
.sp
1000
1000
T}:T{
T}:T{
.sp
.sp
20
144
T}:T{
.sp
27378
T}:T{
.sp
1001
T}
T{
.sp
100,000,000
T}:T{
.sp
1
T}:T{
.sp
144
T}:T{
.sp
2737
T}:T{
.sp
1100
T}
T{
.sp
100,000,000
T}:T{
.sp
10
T}:T{
T}:T{
.sp
.sp
1008
144
T}:T{
T}:T{
.sp
.sp
7\&.6660
27378
T}:T{
T}:T{
.sp
.sp
1\&.0
1100
T}
T{
.sp
100,000,000
T}:T{
.sp
100
T}:T{
.sp
144
T}:T{
.sp
273785
T}:T{
.sp
1100
T}
T{
.sp
100,000,000
T}:T{
.sp
1000
T}:T{
.sp
144
T}:T{
.sp
2737850
T}:T{
.sp
1100
T}
T}
.TE
.TE
.sp1
.sp1
.SH"RECOMMENDED RISKFACTOR VALUES"
.SH"RECOMMENDED RISKFACTOR VALUES"
.sp
.sp
0\&.001 is a value for tie\-breaking in favor of shorter routes, but not really costing in any risk\&.
The default \fIfuzz\fR factor is 5%, so as you can see from the table above, that tends to overwhelm the effect of \fIriskfactor\fR less than about 5\&.
.sp
.sp
1 is a conservative value for a stable lightning network with very few failures\&.
1 is a conservative value for a stable lightning network with very few failures\&.
.sp
.sp
1000 is an aggressive value for trying to minimize timeouts at all costs\&.
1000 is an aggressive value for trying to minimize timeouts at all costs\&.
.sp
The default for lightning\-pay(7) is 10, which starts to become a major factor for larger amounts, and is basically ignored for tiny ones\&.
.SH"RETURN VALUE"
.SH"RETURN VALUE"
.sp
.sp
On success, a "route" array is returned\&. Each array element contains \fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis sent), and \fIdelay\fR (the number of blocks to timeout at this node)\&.
On success, a "route" array is returned\&. Each array element contains \fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis sent), and \fIdelay\fR (the number of blocks to timeout at this node)\&.
The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 1\&.0\&. The \fImaxfeepercent\fR limits the money paid in fees, and defaults to 0\&.5\&. The maxfeepercent\*(Aq is a percentage of the amount that is to be paid\&. The `exemptfee option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes\&. Setting exemptfee allows the maxfeepercent check to be skipped on fees that are smaller than exemptfee (default: 5000 millisatoshi)\&.
The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 10\&. The \fImaxfeepercent\fR limits the money paid in fees, and defaults to 0\&.5\&. The maxfeepercent\*(Aq is a percentage of the amount that is to be paid\&. The `exemptfee option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes\&. Setting exemptfee allows the maxfeepercent check to be skipped on fees that are smaller than exemptfee (default: 5000 millisatoshi)\&.
.sp
.sp
The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
Rusty Russell
6 years ago
Christian Decker