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

FreeBSD Manual Pages

  
 
  

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

NAME
       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] [total_amount_msat]

DESCRIPTION
       Note:  you probably want	to use the more	modern and flexible injectpay-
       mentonion command instead of this.  The sendonion RPC  command  can  be
       used  to	 initiate  a  payment  attempt with a custom onion packet. The
       onion packet is used to deliver instructions for	hops along  the	 route
       on  how to behave. Normally these instructions are indications on where
       to forward a payment and	what parameters	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	exten-
       sions that are not directly supported 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)
       •  total_amount_msat  (msat,  optional):	 This  is  the full amount re-
	  quested by the destination in	the invoice. It	is  needed  internally
	  for  multi-part payments.  Its default value is 0 msat for backwards
	  compatibility. The default is	0. (added v25.05)

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-injectpaymentonion(7),	 lightning-createonion(7),  lightning-
       sendpay(7), lightning-listsendpays(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.09					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+15.0>

home | help