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

FreeBSD Manual Pages

  
 
  

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

NAME
       lightning-sendonion -- Send a payment with a custom onion packet

SYNOPSIS
       sendonion  onion	 first_hop payment_hash	[label]	[shared_secrets] [par-
       tid] [bolt11]  [amount_msat]  [destination]  [localinvreqid]  [groupid]
       [description]

DESCRIPTION
       The  sendonion  RPC  command  can be used to initiate a payment attempt
       with a custom onion packet. The onion packet is	used  to  deliver  in-
       structions  for	hops  along the	route on how to	behave.	Normally these
       instructions are	indications on where to	forward	a payment and what pa-
       rameters	to use,	or contain details of the payment for the  final  hop.
       However,	 it  is	 possible to add arbitrary information for hops	in the
       custom onion, allowing for custom extensions that are not directly sup-
       ported by Core Lightning.

       If the first element of route does not have "channel" set,  a  suitable
       channel (if any)	will be	chosen,	otherwise that specific	short-channel-
       id is used. The following is an example of a 3 hop onion:

       [
	 "298606954e9de3e9d938d18a74fed794c440e8eda82e52dc08600953c8acf9c4",
	 "2dc094de72adb03b90894192edf9f67919cb2691b37b1f7d4a2f4f31c108b087",
	 "a7b82b240dbd77a4ac8ea07709b1395d8c510c73c17b4b392bb1f0605d989c85"
       ]

       •  onion	 (hex):	 Hex-encoded 1366 bytes	long blob that was returned by
	  either of the	tools that can generate	onions.	It contains  the  pay-
	  loads	 destined for each hop and some	metadata. Please refer to BOLT
	  04	     <https://github.com/lightning/bolts/blob/master/04-onion-
	  routing.md> for further details. If is specific to the route that is
	  being	 used  and  the	 payment_hash used to construct, and therefore
	  cannot be reused for other payments or to attempt a separate	route.
	  The  custom  onion can generally be created using the	devtools/onion
	  CLI tool, or the createonion RPC command.
       •  first_hop (object): Instructs	Core Lightning which peer to send  the
	  onion	to. It is a JSON dictionary that corresponds to	the first ele-
	  ment	of  the	 route	array returned by getroute (so fields not men-
	  tioned here are ignored).:

	  •  id	(pubkey): Node id for the  peer.  Use  any  available  channel
	     available to this peer.
	  •  amount_msat (msat): The amount to add an HTLC for millisatoshis.
	  •  delay  (u16):  The	number of blocks delay of blocks on top	of the
	     current blockheight.
       •  payment_hash (hash): Specifies the 32	byte hex-encoded hash  to  use
	  as  a	 challenge  to the HTLC	that we	are sending. It	is specific to
	  the onion and	has to match the one the onion was created with.
       •  label	(string, optional): Can	be used	to provide  a  human  readable
	  reference to retrieve	the payment at a later time.
       •  shared_secrets  (array of secrets, optional):	A JSON list of 32 byte
	  hex-encoded secrets that were	used when  creating  the  onion.  Core
	  Lightning  can send a	payment	with a custom onion without the	knowl-
	  edge of these	secrets, however it will not be	able to	parse an even-
	  tual error message since that	is encrypted with the  shared  secrets
	  used in the onion. If	shared_secrets is provided Core	Lightning will
	  decrypt  the	error, act accordingly,	e.g., add a channel_update in-
	  cluded in the	error to its network view,  and	 set  the  details  in
	  listsendpays	correctly.  If	it is not provided Core	Lightning will
	  store	the encrypted onion, and expose	it  in	listsendpays  allowing
	  the  caller to decrypt it externally.	If it is not provided the Core
	  Lightning node does not know how long	the route is,  which  channels
	  or  nodes  are involved, and what an eventual	error could have been.
	  It can therefore be used for oblivious payments.:

	  •  (secret, optional)
       •  partid (u16, optional): If provided and non-zero, allows for	multi-
	  ple parallel partial payments	with the same payment_hash.
       •  bolt11 (string, optional): If	provided, it will be returned in wait-
	  sendpay and listsendpays results.
       •  amount_msat  (msat,  optional): Used to annotate the payment,	and is
	  returned by waitsendpay and listsendpays.
       •  destination (pubkey, optional): If provided, it will be returned  in
	  listpays result.
       •  localinvreqid	 (hash,	 optional): localinvreqid is used by offers to
	  link a payment attempt to a local invoice_request offer  created  by
	  lightningd-invoicerequest(7).
       •  groupid  (u64,  optional): Grouping key to disambiguate multiple at-
	  tempts to pay	an invoice or the same payment_hash.
       •  description (string, optional): If provided, it will be returned  in
	  waitsendpay and listsendpays results.	(added v0.11.0)

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

       •  created_index	(u64): 1-based index indicating	order this payment was
	  created in. (added v23.11)
       •  id (u64): Old	synonym	for created_index.
       •  payment_hash	(hash):	 The  hash  of the payment_preimage which will
	  prove	payment.
       •  status (string) (one of "pending", "complete"): Status of  the  pay-
	  ment (could be complete if already sent previously).
       •  created_at  (u64):  The UNIX timestamp showing when this payment was
	  initiated.
       •  amount_sent_msat (msat): The amount sent.
       •  amount_msat (msat, optional):	The amount  delivered  to  destination
	  (if known).
       •  destination (pubkey, optional): The final destination	of the payment
	  if known.
       •  label	(string, optional): The	label, if given	to sendpay.
       •  bolt11 (string, optional): The bolt11	string (if supplied).
       •  bolt12 (string, optional): The bolt12	string (if supplied).
       •  partid  (u64,	optional): The partid (if supplied) to sendonion/send-
	  pay.

       If status is "complete":	- payment_preimage (secret): The proof of pay-
       ment: SHA256 of this payment_hash.  -  updated_index  (u64,  optional):
       1-based index indicating	order this payment was changed.	(added v23.11)

       If  status  is  "pending": - message (string, optional):	Monitor	status
       with listpays or	waitsendpay.

ERRORS
       The following error codes may occur:

       •  202: an parseable onion

       the error details are decrypted and presented here,  if	shared_secrets
       was provided and	an error was returned by one of	the intermediate nodes

AUTHOR
       Christian Decker	<<decker.christian@gmail.com>> is mainly responsible.

SEE ALSO
       lightning-createonion(7),   lightning-sendpay(7),   lightning-listsend-
       pays(7)

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

EXAMPLES
       Example 1:

       Request:

       $ lightning-cli sendonion -k "onion"="onion10101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010" "first_hop"='{"id": "nodeid020202020202020202020202020202020202020202020202020202020202", "channel": "109x1x1", "direction": 1, "amount_msat": 1002, "delay":	21, "style": "tlv"}' "payment_hash"="assocdata0010101010101010101010101010101010101010101010101010101"

       {
	 "id": "example:sendonion#1",
	 "method": "sendonion",
	 "params": {
	   "onion": "onion10101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010",
	   "first_hop":	{
	     "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
	     "channel":	"109x1x1",
	     "direction": 1,
	     "amount_msat": 1002,
	     "delay": 21,
	     "style": "tlv"
	   },
	   "payment_hash": "assocdata0010101010101010101010101010101010101010101010101010101"
	 }
       }

       Response:

       {
	 "message": "Monitor status with listpays or waitsendpay",
	 "created_index": 10,
	 "id": 10,
	 "payment_hash": "assocdata0010101010101010101010101010101010101010101010101010101",
	 "groupid": 1,
	 "amount_sent_msat": 1002,
	 "created_at": 1738000000,
	 "status": "pending"
       }

Core Lightning v25.02					LIGHTNING-SENDONION(7)

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

home | help