LIGHTNING-LISTFORWARDS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 lightning-listforwards(7) — the manual, bestie edition 🎀

okay so this is lightning-listforwards(7), a Core Lightning manpage, and it's genuinely one of the most useful little commands ever. it's literally the receipts page for your node ✨

🌸 NAME 🌸

listforwards — the command that shows you all your HTLCs and all their info. every single one. no cap.

🦋 SYNOPSIS 🦋

listforwards [status] [in_channel] [out_channel] [index [start] [limit]]

✨ DESCRIPTION ✨

so the listforwards RPC command displays all htlcs that have been attempted to be forwarded by the Core Lightning node. attempted, bestie — not just the ones that worked. we're seeing the whole story here 💅

  • status (string, optional) (one of "offered", "settled", "local_failed", "failed") — if you specify this, then only the forwards with the given status come back. filter era 🔥
  • in_channel (short_channel_id, optional) — only the matching forwards on the given inbound channel are returned.
  • out_channel (short_channel_id, optional) — only the matching forwards on the given outbount channel are returned. (yes, the manpage really says "outbount" and honestly? iconic typo, we keep it 🫶)
  • index (string, optional) (one of "created", "updated") — if neither in_channel nor out_channel is specified, it controls ordering. the default is created. (added v23.11)
  • 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 v23.11)
  • limit (u32, optional) — if index is specified, limit can be used to specify the maximum number of entries to return. (added v23.11)

👑 RETURN VALUE 👑

on success, an object containing forwards is returned. it's an array of objects, and every object contains:

  • created_index (u64) — 1-based index indicating order this forward was created in. (added v23.11)
  • in_channel (short_channel_id) — the channel that received the HTLC.
  • in_msat (msat) — the value of the incoming HTLC.
  • status (string) (one of "offered", "settled", "local_failed", "failed") — still ongoing, completed, failed locally, or failed after forwarding.
  • received_time (number) — the UNIX timestamp when this was received (may be zero for old forwards).
  • in_htlc_id (u64, optional) — the unique HTLC id the sender gave this (not present if incoming channel was closed before upgrade to v22.11).
  • out_channel (short_channel_id, optional) — the channel that the HTLC (trying to) forward to.
  • out_htlc_id (u64, optional) — the unique HTLC id we gave this when sending (may be missing even if out_channel is present, for old forwards before v22.11).
  • updated_index (u64, optional) — 1-based index indicating order this forward was changed (only present if it has changed since creation). (added v23.11)
  • style (string, optional) (one of "legacy", "tlv") — either a legacy onion format or a modern tlv format.

🧚 conditional fields, iykyk

if out_msat is present:

  • fee_msat (msat) — the amount this paid in fees.
  • out_msat (msat) — the amount we sent out the out_channel.

if status is "settled" or "failed":

  • resolved_time (number) — the UNIX timestamp when this was resolved.

if status is "local_failed" or "failed":

  • failcode (u32, optional) — the numeric onion code returned.
  • failreason (string, optional) — the name of the onion code returned.

🫶 AUTHOR 🫶

Rene Pickhardt r.pickhardt@gmail.com is mainly responsible. ty for your service king 👑

🌈 SEE ALSO 🌈

⭐ RESOURCES ⭐

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

💖 EXAMPLES 💖

example 1

request:

$ lightning-cli listforwards -k "in_channel"="109x1x1" "out_channel"="123x1x1" "status"="settled"
{
  "id": "example:listforwards#1",
  "method": "listforwards",
  "params": {
    "in_channel": "109x1x1",
    "out_channel": "123x1x1",
    "status": "settled"
  }
}

response:

{
  "forwards": [
    {
      "created_index": 12,
      "updated_index": 7,
      "in_channel": "109x1x1",
      "in_htlc_id": 19,
      "out_channel": "123x1x1",
      "out_htlc_id": 2,
      "in_msat": 50000501,
      "out_msat": 50000000,
      "fee_msat": 501,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738000000,
      "resolved_time": 1738500000
    },
    {
      "created_index": 13,
      "updated_index": 8,
      "in_channel": "109x1x1",
      "in_htlc_id": 20,
      "out_channel": "123x1x1",
      "out_htlc_id": 3,
      "in_msat": 50000501,
      "out_msat": 50000000,
      "fee_msat": 501,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738010000,
      "resolved_time": 1738510000
    }
  ]
}

example 2

request:

$ lightning-cli listforwards
{
  "id": "example:listforwards#2",
  "method": "listforwards",
  "params": {}
}

response:

{
  "forwards": [
    {
      "created_index": 1,
      "updated_index": 1,
      "in_channel": "109x1x1",
      "in_htlc_id": 1,
      "out_channel": "111x1x1",
      "out_htlc_id": 1,
      "in_msat": 10001,
      "out_msat": 10000,
      "fee_msat": 1,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738000000,
      "resolved_time": 1738500000
    },
    {
      "created_index": 2,
      "updated_index": 2,
      "in_channel": "109x1x1",
      "in_htlc_id": 2,
      "out_channel": "111x1x1",
      "out_htlc_id": 2,
      "in_msat": 10001,
      "out_msat": 10000,
      "fee_msat": 1,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738010000,
      "resolved_time": 1738510000
    },
    {
      "created_index": 3,
      "updated_index": 3,
      "in_channel": "109x1x1",
      "in_htlc_id": 3,
      "out_channel": "111x1x1",
      "out_htlc_id": 3,
      "in_msat": 10000202,
      "out_msat": 10000101,
      "fee_msat": 101,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738020000,
      "resolved_time": 1738520000
    },
    {
      "created_index": 5,
      "updated_index": 4,
      "in_channel": "109x1x1",
      "in_htlc_id": 5,
      "out_channel": "111x1x1",
      "out_htlc_id": 4,
      "in_msat": 10001,
      "out_msat": 10000,
      "fee_msat": 1,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738030000,
      "resolved_time": 1738530000
    },
    {
      "created_index": 6,
      "updated_index": 5,
      "in_channel": "109x1x1",
      "in_htlc_id": 6,
      "out_channel": "111x1x1",
      "out_htlc_id": 5,
      "in_msat": 50001,
      "out_msat": 50000,
      "fee_msat": 1,
      "status": "settled",
      "style": "tlv",
      "received_time": 1738040000,
      "resolved_time": 1738540000
    }
  ]
}
ngl bestie, notice how created_index skips 4 in example 2? that's just what the manpage shows, don't come for me 💀

🌸 okay that's the whole page!! this one's from Core Lightning v26.06.9, and it's the LIGHTNING-LISTFORWARDS(7) manpage — go check your forwards, they're giving main character energy 🌈💜

📦 where this page comes from