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

FreeBSD Manual Pages

  
 
  

home | help 
LIGHTNING-RENEPAY(7)					  LIGHTNING-RENEPAY(7)

NAME
       lightning-renepay -- Command for	sending	a payment to a BOLT11 invoice

SYNOPSIS
       renepay	invstring  [amount_msat]  [maxfee] [maxdelay] [retry_for] [de-
       scription] [label] [exclude]

DESCRIPTION
       Command added in	v23.08.

       renepay is a new	payment	plugin based on	Pickhardt-Richter optimization
       method for Multi-Path-Payments. This implementation has not been	 thor-
       oughly tested and it should be used with	caution.

       The response will occur when the	payment	fails or succeeds. Once	a pay-
       ment  has  succeeded, calls to renepay with the same invstring will not
       lead to a new payment attempt, but instead it will succeed immediately.

       When using $ lightning-cli, you may skip	optional parameters  by	 using
       null. Alternatively, use	-k option to provide parameters	by name.

       •  invstring (string): Bolt11 invoice which the RPC command attempts to
	  pay. Currently, renepay supports bolt11 invoices only.
       •  amount_msat  (msat,  optional): If the invstring does	not contain an
	  amount, amount_msat is required, otherwise if	 it  is	 specified  it
	  must	be  null. in millisatoshi precision; it	can be a whole number,
	  or a whole number with suffix	msat or	sat, or	a three	decimal	 point
	  number  with suffix sat, or an 1 to 11 decimal point number suffixed
	  by btc.
       •  maxfee (msat,	optional): maxfee is a hard bound, in the  sense  that
	  the  command	will never attempt a payment when the fees exceed that
	  value.
       •  maxdelay (u32, optional): Overrides the value	of max-locktime-blocks
	  for this payment. It serves to limit the locktime of	funds  in  the
	  payment HTLC measured	in blocks.
       •  retry_for  (u32,  optional):	Measured in seconds specifies how much
	  time it is allowed for the command to	keep retrying the payment. The
	  default is 60	seconds.
       •  description (string, optional): Only required	 for  bolt11  invoices
	  which	 do  not  contain  a description themselves, but contain a de-
	  scription hash: in this case description is required.	description is
	  then checked against the hash	inside the invoice before it  will  be
	  paid.
       •  label	(string, optional): Used to attach a label to payments,	and is
	  returned in lightning-listpays(7) and	lightning-listsendpays(7).
       •  exclude (array, optional): exclude is	a JSON array of	short-channel-
	  id/direction	(e.g. [	'564334x877x1/0', '564195x1292x0/1' ]) or pub-
	  key which should be excluded from consideration for routing. The de-
	  fault	is not to exclude any channels or nodes. (added	v24.08):

	  •  (short_channel_id_dir)
	  •  (pubkey)

OPTIMALITY
       renepay is based	on the work by Pickhardt-Richter's Optimally  Reliable
       & Cheap Payment Flows on	the Lightning Network. Which means the payment
       command	will  prefer  routes that have a higher	probability of success
       while keeping fees low.

       The algorithm records some partial knowledge of the state of  the  Net-
       work  deduced  from  the	responses obtained after evey payment attempt.
       This knowledge is kept through different	payment	requests,  but	decays
       with  time to account for the dynamics of the Network (after 1 hour all
       previous	knowledge will be erased). Knowledge from previous payment at-
       tempts increases	the reliability	for subsequent ones.

       Higher probabilities of success and lower fees cannot generally by  op-
       timized	at  once.  Hence renepay combines the two in different amounts
       seeking solutions that satisfy maxfee bound and a target	for 90%	proba-
       bility of success. maxfee is a hard bound, in the sense that  the  com-
       mand  will  never  attempt  a  payment when the fees exceed that	value.
       While the probability target is not compulsory (but desirable), i.e. if
       the best	route does not satisfy the 90% probability target it  will  be
       tried anyways.

       When  maxfee and	the 90%	probability bounds are satified, the algorithm
       will optimize the fees to its lowest value.

RANDOMIZATION
       To protect user privacy,	the payment algorithm  performs	 shadow	 route
       randomization.  Which means the payment algorithm will virtually	extend
       the route by adding delays and fees along it, making it appear  to  in-
       termediate  nodes  that	the  route is longer than it actually is. This
       prevents	intermediate nodes from	reliably guessing their	distance  from
       the payee.

       Route randomization will	never exceed maxfee of the payment. Route ran-
       domization  and	shadow	routing	will not take routes that would	exceed
       maxdelay.

RETURN VALUE
       On success, an object is	returned, containing:

       •  payment_preimage (secret): The proof of payment: SHA256 of this pay-
	  ment_hash.
       •  payment_hash (hash): The hash	of  the	 payment_preimage  which  will
	  prove	payment.
       •  created_at  (number):	 The  UNIX timestamp showing when this payment
	  was initiated.
       •  parts	(u32): How many	attempts this took.
       •  amount_msat (msat): Amount the recipient received.
       •  amount_sent_msat (msat): Total amount	we sent	(including fees).
       •  status (string) (one of "complete", "pending", "failed"): Status  of
	  payment.
       •  bolt11 (string, optional): The bolt11	invoice	paid. (added v23.08)
       •  bolt12 (string, optional): The bolt12	invoice	paid. (added v23.08)
       •  groupid  (u64,  optional):  The groupid used for these payment parts
	  (as can be seen in listsendpays) (added v23.08)
       •  destination (pubkey, optional): The final destination	 of  the  pay-
	  ment.

       You  can	monitor	the progress and retries of a payment using the	light-
       ning-renepaystatus(7) command.

ERRORS
       The following error codes may occur:

       •  -1: Catchall nonspecific error.
       •  200: Other payment attempts are in progress.
       •  203: Permanent failure at destination.
       •  205: Unable to find a	route.
       •  206: Payment routes are too expensive.
       •  207: Invoice expired.	Payment	took too long  before  expiration,  or
	  already expired at the time you initiated payment.
       •  210: Payment timed out without a payment in progress.
       •  212: Invoice is invalid.

AUTHOR
       Eduardo Quintana-Miranda	<<eduardo.quintana@pm.me>> is mainly responsi-
       ble.

SEE ALSO
       lightning-renepaystatus(7), lightning-listpays(7), lightning-invoice(7)

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

       Pickhardt  R.  and Richter S., Optimally	Reliable & Cheap Payment Flows
       on the Lightning	Network	<https://arxiv.org/abs/2107.05322>

EXAMPLES
       Example 1:

       Request:

       $ lightning-cli renepay -k "invstring"="lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000" "amount_msat"=400000

       {
	 "id": "example:renepay#1",
	 "method": "renepay",
	 "params": {
	   "invstring":	"lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
	   "amount_msat": 400000
	 }
       }

       Response:

       {
	 "bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
	 "amount_msat":	400000,
	 "payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
	 "destination":	"nodeid020202020202020202020202020202020202020202020202020202020202",
	 "created_at": 1738000000,
	 "groupid": 1,
	 "parts": 2,
	 "status": "complete",
	 "payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
	 "amount_sent_msat": 400000
       }

       Example 2:

       Request:

       $ lightning-cli renepay -k "invstring"="lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000"

       {
	 "id": "example:renepay#2",
	 "method": "renepay",
	 "params": {
	   "invstring":	"lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000"
	 }
       }

       Response:

       {
	 "bolt11": "lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000",
	 "amount_msat":	4000,
	 "payment_hash": "paymenthashinvl0340034003400340034003400340034003400340034003400",
	 "destination":	"nodeid030303030303030303030303030303030303030303030303030303030303",
	 "created_at": 1738000000,
	 "groupid": 1,
	 "parts": 2,
	 "status": "complete",
	 "payment_preimage": "paymentpreimager020202020202020202020202020202020202020202020202",
	 "amount_sent_msat": 4000
       }

Core Lightning v25.02					  LIGHTNING-RENEPAY(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-renepay&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help