Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIGHTNING-GETROUTE(7)	      lightning-getroute	 LIGHTNING-GETROUTE(7)

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

SYNOPSIS
       getroute	id msatoshi riskfactor [cltv] [fromid] [fuzzpercent] [exclude]
       [maxhops]

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

       msatoshi	is in millisatoshi precision; it can be	a whole	number,	 or  a
       whole  number  ending  in  msat	or sat,	or a number with three decimal
       places ending in	sat, or	a number with 1	to 11 decimal places ending in
       btc.

       There  are two considerations for how good a route is: how low the fees
       are, and	how long your payment will get stuck in	a delayed output if  a
       node  goes  down	during the process. The	riskfactor non-negative	float-
       ing-point field controls	this tradeoff; it is the annual	cost  of  your
       funds being stuck (as a percentage).

       For  example, if	you thought the	convenience of keeping your funds liq-
       uid (not	stuck) was worth 20% per annum interest, riskfactor  would  be
       20.

       If you didnat care about	risk, riskfactor would be zero.

       fromid is the node to start the route from: default is this node.

       The fuzzpercent is a non-negative floating-point	number,	representing a
       percentage of the actual	fee. The fuzzpercent is	used to	 distort  com-
       puted  fees  along  each	 channel, to provide some randomization	to the
       route generated.	0.0 means the exact fee	of that	channel	is used, while
       100.0  means  the fee used might	be from	0 to twice the actual fee. The
       default is 5.0, or up to	5% fee distortion.

       exclude	is  a  JSON  array  of	short-channel-id/direction   (e.g.   [
       "564334x877x1/0",  "564195x1292x0/1"  ])	or node-id which should	be ex-
       cluded from consideration for routing. The default is  not  to  exclude
       any  channels  or nodes.	Note if	the source or destination is excluded,
       the command result is undefined.

       maxhops is the maximum number of	channels to return; default is 20.

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:

	      risk-fee = amount	x blocks-timeout x per-block-cost

       We  are	given  a riskfactor expressed as a percentage. There are 52596
       blocks  per  year,  thus	 per-block-cost	 is  riskfactor	  divided   by
       5,259,600.

       The final result	is:

	      risk-fee = amount	x blocks-timeout x riskfactor /	5259600

       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  to_self_delay values on the network at 14 and 144
       blocks.

RECOMMENDED RISKFACTOR VALUES
       The default fuzz	factor is 5%, so as you	can see	from the table	above,
       that tends to overwhelm the effect of riskfactor	less than about	5.

       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.

       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.

RETURN VALUE
       On success, a "route" array is returned.	Each array element contains id
       (the  node  being  routed  through), msatoshi (the millisatoshis	sent),
       amount_msat (the	same, with msat	appended), delay (the number of	blocks
       to  timeout at this node), and style (indicating	the features which can
       be used for this	hop).

       The final id will be the	destination id given in	the input. The differ-
       ence  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 pay-
       ment failure, in	blocks.

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

							 LIGHTNING-GETROUTE(7)

NAME | SYNOPSIS | DESCRIPTION | RISKFACTOR EFFECT ON ROUTING | RECOMMENDED RISKFACTOR VALUES | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lightning-getroute&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help