LIGHTNING-LISTHTLCS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 lightning-listhtlcs(7) — ok bestie, let's talk HTLCs

So this is the manual page for lightning-listhtlcs, and no cap, it's lowkey one of the most useful little query commands in Core Lightning. Sit down, grab a boba, we're gonna go through it together 🍓

✨ NAME ✨

listhtlcs — the command for querying HTLCs. That's it, that's the vibe 💅

🎀 SYNOPSIS 🎀

listhtlcs [id] [index] [start] [limit]

🌸 DESCRIPTION 🌸

Okay so first things first: this command was added in v22.11. Iconic behavior honestly.

The listhtlcs RPC command gets all the HTLCs. And when I say all, I mean — generally, we remember them for as long as a channel is open, even if they completed long ago. So yeah, it's giving "archive that never forgets" 😭

Here's what you can pass in, bestie:

  • id (string, optional): a short channel id (like 1x2x3) or a full 64-byte hex channel id. If you give it one, it will only list htlcs for that channel (which must be known — no guessing games, she has to actually know it).
  • index (string, optional) (one of "created", "updated"): this controls the ordering of results. The default is created. (added v25.05)
  • start (u64, optional): if index is specified, start may be specified to start from that value, which is generally returned from lightning-wait(7). (added v25.05)
  • limit (u32, optional): if index is specified, limit can be used to specify the maximum number of entries to return. (added v25.05)

Periodt. Those three new ones all landed in v25.05, so if you're on something older, that's why they're not vibing with you 🙈

👑 RETURN VALUE 👑

On success, an object containing htlcs is returned. It is an array of objects, where each object contains:

  • short_channel_id (short_channel_id): the channel that contains/contained the HTLC.
  • created_index (u64): 1-based index indicating order this htlc was created in. (added v25.05)
  • id (u64): the unique, incrementing HTLC id the creator gave this.
  • expiry (u32): the block number where this HTLC expires/expired.
  • amount_msat (msat): the value of the HTLC.
  • direction (string) (one of "out", "in"): out if we offered this to the peer, in if they offered it.
  • payment_hash (hash): payment hash sought by HTLC.
  • state (string) (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION", "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION"): the first 10 states are for out, the next 10 are for in.
  • updated_index (u64, optional): 1-based index indicating order this htlc was changed (only present if it has changed since creation). (added v25.05)
🧚 Friendly reminder on state: literally ten of those are for out and the next ten are for in. Count them if you must, it's fine, I did too.

🦋 AUTHOR 🦋

Rusty Russell rusty@rustcorp.com.au is mainly responsible. Main character energy, honestly 🔥

🌈 SEE ALSO 🌈

lightning-listforwards(7)

⭐ RESOURCES ⭐

Main web site: https://github.com/ElementsProject/lightning

💜 EXAMPLES 💜

Example 1:

Request:

$ lightning-cli listhtlcs "109x1x1"

{
  "id": "example:listhtlcs#1",
  "method": "listhtlcs",
  "params": [
    "109x1x1"
  ]
}

Response:

{
  "htlcs": [
    {
      "created_index": 1,
      "updated_index": 9,
      "short_channel_id": "109x1x1",
      "id": 0,
      "expiry": 126,
      "direction": "out",
      "amount_msat": 500000000,
      "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    },
    {
      "created_index": 2,
      "updated_index": 18,
      "short_channel_id": "109x1x1",
      "id": 1,
      "expiry": 135,
      "direction": "out",
      "amount_msat": 10001,
      "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    },
    {
      "created_index": 3,
      "updated_index": 27,
      "short_channel_id": "109x1x1",
      "id": 2,
      "expiry": 149,
      "direction": "out",
      "amount_msat": 10001,
      "payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    },
    {
      "created_index": 4,
      "updated_index": 36,
      "short_channel_id": "109x1x1",
      "id": 3,
      "expiry": 155,
      "direction": "out",
      "amount_msat": 10000202,
      "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    },
    {
      "created_index": 5,
      "updated_index": 44,
      "short_channel_id": "109x1x1",
      "id": 4,
      "expiry": 152,
      "direction": "out",
      "amount_msat": 10001,
      "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    }
  ]
}

Example 2:

Request:

$ lightning-cli listhtlcs -k "index"="created" "start"=4 "limit"=1

{
  "id": "example:listhtlcs#2",
  "method": "listhtlcs",
  "params": {
    "index": "created",
    "start": 4,
    "limit": 1
  }
}

Response:

{
  "htlcs": [
    {
      "created_index": 4,
      "updated_index": 36,
      "short_channel_id": "109x1x1",
      "id": 3,
      "expiry": 155,
      "direction": "out",
      "amount_msat": 10000202,
      "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
      "state": "RCVD_REMOVE_ACK_REVOCATION"
    }
  ]
}

Anyway, that's the whole page 🫶 go query your HTLCs, bestie, you've got this. This little love letter is from Core Lightning v26.06.9, and it's the LIGHTNING-LISTHTLCS(7) page — slay, bye 💖

📦 where this page comes from