home | help 
LIGHTNING-HOOK-HTLC_ACCEPTED(7) 		 LIGHTNING-HOOK-HTLC_ACCEPTED(7)

NAME
     htlc_accepted -- Hook for handling incoming HTLCs

DESCRIPTION
     The htlc_accepted hook is called whenever an incoming HTLC is accepted.

     The plugin can inspect the HTLC and decide to continue processing, fail it,
     or resolve it.

     lightningd  will replay the HTLCs for which it doesn't have a final verdict
     during startup.  This means that, if the plugin response  wasn't  processed
     before the HTLC was forwarded, failed, or resolved, then the plugin may see
     the same HTLC again during startup. It is therefore paramount that the plu-
     gin is idempotent if it talks to an external system.

     This is a chained hook: plugins are called in order until one returns a re-
     sult  other  than continue.  After this the event is considered handled and
     the remaining plugins are skipped.

HOOK PAYLOAD
     *	onion (object):
	*  payload (hex): The raw  unparsed  onion  payload  received  from  the
	   sender.
	*  next_onion (hex): The fully processed onion that we should be sending
	   to the next hop as part of the outgoing HTLC.  Processed in this case
	   means  that	we  took the incoming onion, decrypted it, extracted the
	   payload destined for us, and serialised the resulting onion again.
	*  shared_secret (secret): The shared secret used to decrypt the  incom-
	   ing onion.  It is shared with the sender that constructed the onion.
	*  type (string, optional) (always "tlv"): Indicates that the payload is
	   TLV formatted.  Only present if the payload was successfully parsed.
	*  short_channel_id (short_channel_id, optional): Determines the channel
	   that  the sender is hinting should be used next.  Not present if this
	   node is the final destination.
	*  next_node_id (pubkey, optional): The node_id of the next  hop.   Only
	   present if specified in the onion payload.
	*  forward_msat (msat, optional): The amount to forward to the next hop.
	*  outgoing_cltv_value	(u32,  optional): Determines what the CLTV value
	   for the HTLC that we forward to the next hop should be.
	*  total_msat (msat, optional): The total payment amount.  Only  present
	   for final recipients using modern TLV payloads.
	*  payment_secret  (secret,  optional):  The  payment  secret (which the
	   payer should have obtained from the invoice) provided by the  sender.
	   Only present for final recipients.
	*  payment_metadata (hex, optional): Additional metadata provided in the
	   onion payload.  Only present if included by the sender.
     *	htlc (object):
	*  short_channel_id  (short_channel_id): The channel this HTLC is coming
	   from. (added v0.12.0)
	*  id (u64): The unique HTLC identifier assigned by  the  channel  peer.
	   (added v0.12.0)
	*  amount_msat	(msat):  The  amount received in this HTLC.  This amount
	   minus the forward_msat amount is the fee  that  will  stay  with  us.
	   (added v0.12.0)
	*  cltv_expiry	(u32):	Determines  when  the  HTLC  reverts back to the
	   sender.  cltv_expiry minus outgoing_cltv_value  should  be  equal  or
	   larger than our cltv_delta setting.
	*  cltv_expiry_relative  (u32):  Hints	how  much  time we still have to
	   claim the HTLC.  It is the cltv_expiry minus the current  blockheight
	   and	is passed along mainly to avoid the plugin having to look up the
	   current blockheight.
	*  payment_hash (hash): The payment hash used to identify the payment.
	*  extra_tlvs (hex, optional): Optional TLV stream attached to the HTLC.
	   (added v25.09)
     *	peer_id (pubkey, optional): The node_id of the peer  that  offered  this
	HTLC.  This field may be absent if the peer is unknown. (added v25.12)
     *	forward_to  (hash,  optional):	The  channel_id we intend to forward the
	HTLC to.  Will not be present if the short_channel_id was invalid or  we
	were the final destination.

HOOK RETURN
     *	result	(string)  (one of "continue", "fail", "resolve"): Determines how
	the HTLC should be handled.

	continue means that the plugin does not want to do anything special  and
	lightningd  should  continue  processing  it normally, i.e., resolve the
	payment if we're the recipient, or attempt to forward it otherwise.  No-
	tice  that  the usual checks such as sufficient fees and CLTV deltas are
	still enforced.

	It can also replace the onion.payload by specifying a payload in the re-
	sponse. Note  that  this  is  always  a  TLV-style  payload,  so  unlike
	onion.payload  there  is no length prefix (and it must be at least 4 hex
	digits long). This will be re-parsed; it's  useful  for  removing  onion
	fields which a plugin doesn't want lightningd to consider.

	It  can  also specify forward_to in the response, replacing the destina-
	tion.  This usually only makes sense if it wants to choose an  alternate
	channel  to the same next peer, but is useful if the payload is also re-
	placed.

	Also, it can specify extra_tlvs in the response. This will  replace  the
	TLV-stream  update_add_htlc_tlvs in the update_add_htlc message for for-
	warded htlcs.

	If the node is the final destination, the plugin can  also  replace  the
	amount of the invoice that belongs to the payment_hash by specifying in-
	voice_msat.

	fail  will  tell  lightningd  to  fail the HTLC with a given hex-encoded
	failure_message (please refer to BOLT #4 for  details:	incorrect_or_un-
	known_payment_details is the most common).

	Instead  of failure_message the response can contain a hex-encoded fail-
	ure_onion that will be used instead (please refer to the BOLT #4 for de-
	tails).  This can be used, for example, if you're writing a  bridge  be-
	tween two Lightning Networks. Note that lightningd will apply the obfus-
	cation	step  to the value returned here with its own shared secret (and
	key type ammag) before returning it to the previous hop.

	resolve instructs lightningd to claim the HTLC by providing the preimage
	matching the payment_hash presented in the call.  Notice that the plugin
	must ensure that the payment_key really matches the  payment_hash  since
	lightningd  will not check and the wrong value could result in the chan-
	nel being closed.

     *	payload (hex, optional): Replacement TLV payload to use instead  of  the
	original onion payload.

     *	forward_to (hash, optional): Overrides the forwarding destination.

     *	extra_tlvs  (hex, optional): Replacement TLV stream for forwarded HTLCs.
	(added v25.09)

     *	invoice_msat (msat, optional): Overrides the invoice  amount  for  final
	destination checks. (added v25.12)

     *	failure_message  (hex, optional): Failure message to return if result is
	fail.

     *	failure_onion (hex, optional): Serialized failure onion to return if re-
	sult is fail.

     *	payment_key (secret, optional): Preimage used to resolve the HTLC if re-
	sult is resolve.

Core Lightning v26.06.1 			 LIGHTNING-HOOK-HTLC_ACCEPTED(7)
home | help