rgb-cln/doc/lightning-getroute.7.txt

LIGHTNING-GETROUTE(7)
=====================
:doctype: manpage

NAME
----
lightning-getroute - Protocol for routing a payment (low-level).


SYNOPSIS
--------
*getroute* 'id' 'msatoshi' 'riskfactor' ['cltv']

DESCRIPTION
-----------
The *getroute* RPC command attempts to find the best route for the payment
of 'msatoshi' to lightning node 'id', such that the payment will arrive
at 'id' with 'cltv'-blocks to spare (default 9).

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 'riskfactor' 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.

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,
'riskfactor' would be 20.

If you didn't care about risk, 'riskfactor' would be zero.

RISKFACTOR EFFECT ON ROUTING
----------------------------
The risk factor is treated as if it were an additional fee on the route,
for the purposes of comparing routes.

The formula used is the following approximation:
----
hop-risk = num-hops x per-hop-risk
timeout-cost = blocks-timeout x per-block-cost
risk-fee = amount x hop-risk x timeout-cost
----

We are given a 'riskfactor'; expressed as two multiplied percentages
is the same as fractions multiplied by 10000.  There are 52596 blocks
per year, thus 'per-block-cost' x 'per-hop-risk' is riskfactor'
divided by 5,259,600,000.

The final result is:
----
risk-fee = amount x num-hops x blocks-timeout x riskfactor / 5259600000
----

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%:

[options="header"]
|=======================
|Riskfactor	|Nodes | Delay per node        |Risk Fee %	|Route fee %
|0.001          |5	| 6			|0		|0.25
|1		|5	| 6			|0		|0.25
|1000	        |5	| 6			|0.0029		|0.25

|0.001		|10	| 72			|0		|0.5
|1	        |10	| 72			|0.0001		|0.5
|1000		|10	| 72			|0.1369		|0.5

|0.001		|20	| 1008			|0		|1.0
|1		|20	| 1008			|0.0077		|1.0
|1000		|20	| 1008			|7.6660		|1.0
|=======================

RECOMMENDED RISKFACTOR VALUES
-----------------------------
0.001 is a value for tie-breaking in favor of shorter routes, but not really
costing in any risk.

1 is a conservative value for a stable lightning network with very few
failures.

1000 is an aggressive value for trying to minimize timeouts at all
costs.

RETURN VALUE
------------

On success, a "route" array is returned.  Each array element contains
{id} (the node being routed through), {msatoshi} (the millisatoshis
sent), and {delay} (the number of blocks to timeout at this node).

The final {id} will be the destination {id} given in the input.  The
difference between the first {msatoshi} minus the {msatoshi} given in
the input is the fee.  The first {delay} is the very worst case
timeout for the payment failure, in blocks.

//FIXME:Enumerate errors

AUTHOR
------
Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO
--------
lightning-pay(7), lightning-sendpay(7).

RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning