listhtlcs

listhtlcs -- Command for querying HTLCs

SYNOPSIS

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

DESCRIPTION

The listhtlcs RPC command gets all HTLCs (which, generally, we remember for as long as a channel is open, even if they've completed long ago).

  • id (string, optional): A short channel id (e.g. 1x2x3) or full 64-byte hex channel id, it will only list htlcs for that channel (which must be known).
  • 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)

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 in, the next 10 are for out.
  • updated_index (u64, optional): 1-based index indicating order this htlc was changed (only present if it has changed since creation). (added v25.05)

AUTHOR

Rusty Russell <[email protected]> is mainly responsible.

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": 136,
      "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"
    }
  ]
}

Core Lightning (previously c-lightning) is a lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol.

© 2023 Core Lightning
All rights reserved.

Discussion Forum

The official Core Lightning forum is hosted at discuss.corelightning.org

BuildonL2 Community

The official BuildOnL2 community lives at community.corelightning.org. Join us and build the future of bitcoin on lightning.

Mailing List

For general discussions about CLN implementation, use [email protected]. For the Lightning Network, use [email protected]

Telegram

Community-driven telegram group where most of the node operators hang out. Go to https://t.me/lightningd to join.

Discord

Community-driven discord server where the devs flock together. Go to https://discord.gg/w27fMFESMN to join.

Internet Relay Chat

Don't hesitate to reach out to us on IRC at #lightning-dev @ libera.chat, #c-lightning @ libera.chat.