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 is mainly responsible. SEE ALSO -------- lightning-pay(7), lightning-sendpay(7). RESOURCES --------- Main web site: https://github.com/ElementsProject/lightning