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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       injectpaymentonion onion	payment_hash  amount_msat  cltv_expiry	partid
       groupid [label] [invstring] [localinvreqid] [destination_msat]

DESCRIPTION
       The injectpaymentonion RPC command causes the node to receive a payment
       attempt	similar	to the way it would receive one	from a peer. The onion
       packet is unwrapped, then handled normally: either as a local  payment,
       or forwarded to the next	peer.  Compared	to lightning-sendonion(7): the
       handling	 of blinded paths and self-payments is trivial,	and the	inter-
       face blocks until the payment succeeds or fails.	 The call  also	 fails
       if this payment_hash has	already	been successfully paid.

       •  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.
       •  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.
       •  amount_msat (msat): The amount for the first HTLC in	millisatoshis.
	  This	is  also  the amount which will	be forwarded to	the first peer
	  (if any) as we do not	charge fees on our own payments.   Note:  this
	  is shown in listsendpays as amount_sent_msat.
       •  cltv_expiry  (u16):  The  cltv_expiry	 for the first HTLC in blocks.
	  This must be greater than the	current	blockheight.
       •  partid (u64):	The non-zero identifier	for multiple parallel  partial
	  payments with	the same payment_hash.
       •  groupid (u64): Grouping key to disambiguate multiple attempts	to pay
	  the  same  payment_hash.   All payments in other groups must be com-
	  pleted before	starting a new group.
       •  label	(string, optional): Can	be used	to provide  a  human  readable
	  reference to retrieve	the payment at a later time.
       •  invstring  (string,  optional):  Usually  a bolt11 or	bolt12 string,
	  which, it will be returned in	waitsendpay and	listsendpays results.
       •  localinvreqid	(hash, optional): localinvreqid	is used	by  offers  to
	  link	a  payment attempt to a	local invoice_request offer created by
	  lightningd-invoicerequest(7).
       •  destination_msat (msat, optional): Amount that is actually delivered
	  to the destination (i.e. amount_msat minus  fees),  for  showing  in
	  listsendpays (confusingly, as	amount_msat). (added v24.11.1)

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

       •  created_at  (u64):  The UNIX timestamp showing when this payment was
	  initiated.
       •  completed_at (u64): The UNIX timestamp showing when this payment was
	  completed.
       •  created_index	(u64): 1-based index indicating	order this payment was
	  created in.
       •  payment_preimage (secret): The proof of payment: SHA256 of  this  is
	  the invoice's	payment_hash. (added v24.11)

ERRORS
       The following error codes may occur:

       •  218: injectpaymentonion failed

       The onionreply is returned in the error data, which can be unwrapped to
       discover	the error

       •  219: injectpaymentonion already succeeded

       The  data  object contains the previous success,	as per lightning-send-
       pay.

AUTHOR
       Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.

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

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

EXAMPLES
       Example 1:

       Request:

       $ lightning-cli injectpaymentonion -k "onion"="onion30303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030" "payment_hash"="paymenthashinvl0270027002700270027002700270027002700270027002700" "amount_msat"=1000	"cltv_expiry"=144 "partid"=1 "groupid"=0

       {
	 "id": "example:injectpaymentonion#1",
	 "method": "injectpaymentonion",
	 "params": {
	   "onion": "onion30303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030",
	   "payment_hash": "paymenthashinvl0270027002700270027002700270027002700270027002700",
	   "amount_msat": 1000,
	   "cltv_expiry": 144,
	   "partid": 1,
	   "groupid": 0
	 }
       }

       Response:

       {
	 "created_index": 12,
	 "created_at": 1738000000,
	 "completed_at": 1739000000,
	 "payment_preimage": "paymentpreimgio1030303030303030303030303030303030303030303030303"
       }

Core Lightning v25.02			       LIGHTNING-INJECTPAYMENTONION(7)

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

home | help