HTLC Intercept HTLC 攔截

HTLC Intercept Flow:

Normal HTLC Forwarding (no intercept):

  Incoming HTLC
       |
       v
  +----------+
  |   Node   |-------> Outgoing HTLC (auto forward)
  +----------+

With HTLC Intercept:

  Incoming HTLC
       |
       v
  +----------+      +------------------+
  |   Node   |----->|   Interceptor    |
  +----------+      | (external app)   |
       ^            +------------------+
       |                    |
       |                    v
       |            +------------------+
       |            | Decision Logic   |
       |            |  - Forward?      |
       |            |  - Reject?       |
       |            |  - Settle?       |
       |            |  - Modify?       |
       |            +------------------+
       |                    |
       +--------------------+
          InterceptResponse

LND HTLC Interceptor API:

Enabling Intercept:

# gRPC streaming API
rpc HtlcInterceptor(stream ForwardHtlcInterceptResponse)
    returns (stream ForwardHtlcInterceptRequest);

Once connected, all forwarding HTLCs will be intercepted

InterceptRequest Structure:

message ForwardHtlcInterceptRequest {
    bytes incoming_circuit_key = 1;   // Unique identifier
    uint64 incoming_chan_id = 2;      // Inbound channel ID
    uint64 incoming_htlc_id = 3;      // HTLC ID
    uint64 outgoing_requested_chan_id = 4;  // Outbound channel (if known)
    uint64 incoming_amount_msat = 5;  // Payment amount
    uint64 outgoing_amount_msat = 6;
    uint32 incoming_expiry = 7;       // Timelock
    uint32 outgoing_expiry = 8;
    bytes payment_hash = 9;           // Payment hash
    bytes onion_blob = 10;            // Onion data (TLV format)
    map<uint64, bytes> custom_records = 11;  // Custom records
}

InterceptResponse Options:

message ForwardHtlcInterceptResponse {
    bytes incoming_circuit_key = 1;

    ResolveHoldForwardAction action = 2;
    // RESUME: Continue normal forwarding
    // FAIL: Reject and return error
    // SETTLE: Settle directly (provide preimage)

    bytes preimage = 3;  // For SETTLE

    // Failure reason
    FailureCode failure_code = 4;
    bytes failure_message = 5;
}

HTLC Intercept Use Cases:

1. JIT (Just-In-Time) Channels:

Scenario: User lacks sufficient inbound capacity to receive payment

Flow:
  1. Payer -> LSP (HTLC intercepted)
  2. Interceptor detects: Target user has no channel
  3. LSP opens new channel to user (deducting fee)
  4. After channel confirms, RESUME to forward HTLC
  5. User receives payment

Result: User gets new channel + payment (no pre-opened channel needed)

2. Dynamic Fee Adjustment:

Scenario: Dynamically adjust routing fees based on network conditions

Implementation:
  incoming_fee = incoming_amount - outgoing_amount

  if network_congestion > threshold:
      if incoming_fee < dynamic_fee:
          FAIL(FEE_INSUFFICIENT)
      else:
          RESUME

3. Payment Validation/Filtering:

Scenario: Only accept payments meeting specific criteria

Checks:
  • payment_hash in whitelist?
  • Amount within allowed range?
  • Source channel trusted?
  • custom_records contain required info?

  if not validate(htlc):
      FAIL(INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS)

4. Virtual Channel Routing:

Scenario: Route to target without direct channel

Implementation:
  1. Intercept HTLC
  2. Identify real target (from custom_records)
  3. Forward via other path
  4. SETTLE after receiving preimage

This enables "virtual SCID" and flexible routing strategies

CLN HTLC Hook:

htlc_accepted hook:

{
  "onion": {
    "payload": "<hex>",
    "type": "tlv",
    "forward_amount": "1000msat",
    "outgoing_cltv_value": 800100,
    "next_channel": "123x456x0",
    "custom_records": { ... }
  },
  "htlc": {
    "amount": "1010msat",
    "cltv_expiry": 800140,
    "cltv_expiry_relative": 40,
    "payment_hash": "<hex>"
  },
  "forward_to": "<node_id>"
}

Hook Response Options:

Continue processing:
  { "result": "continue" }

Reject:
  {
    "result": "fail",
    "failure_message": "<onion_failure_message>"
  }

Settle:
  {
    "result": "resolve",
    "payment_key": "<preimage_hex>"
  }

HTLC Intercept Security Considerations:

Timeout Risk:

WARNING: HTLCs have expiration times!

If Interceptor:
  • Processes too slowly
  • Crashes without responding
  • Takes too long to decide

Consequences:
  • HTLC expires, upstream node force-closes channel
  • Funds may be lost
  • Node reputation damaged

Countermeasures:
  • Set Interceptor timeout
  • Auto RESUME or FAIL on timeout
  • Monitor HTLC remaining time

Disconnection Handling:

If Interceptor connection drops:

LND behavior (configurable):
  • Auto FAIL all pending HTLCs
  • Or auto RESUME all pending HTLCs

Recommendations:
  • Use high-availability architecture
  • Fast reconnection mechanism
  • Monitor Interceptor health

Malicious Interceptor Protection:

Interceptor has full control, could:
  • Delay payments (griefing)
  • Selectively reject
  • Analyze payment patterns (privacy risk)

Only run Interceptor programs you trust