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 plugin is idempotent if it talks to an external system.

This is a chained hook: plugins are called in order until one returns a result 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 incoming 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. Notice 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 response. 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 destination.
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 replaced.

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 forwarded 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 invoice_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_unknown_payment_details is the most common).

Instead of failure_message the response can contain a hex-encoded failure_onion that will be used instead (please refer to the BOLT #4 for details).
This can be used, for example, if you're writing a bridge between two Lightning Networks. Note that lightningd will apply the obfuscation 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 channel 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 result is fail.
• payment_key (secret, optional): Preimage used to resolve the HTLC if result is resolve.