2019-08-31 13:30:56 +01:00
lightning-listforwards -- Command showing all htlcs and their information
=========================================================================
2019-08-10 00:54:18 +01:00
SYNOPSIS
--------
2023-10-28 04:12:11 +01:00
**listforwards** [*status*] [*in\_channel*] [*out\_channel*] [*index* [*start*] [*limit*]]
2019-08-10 00:54:18 +01:00
DESCRIPTION
-----------
The **listforwards** RPC command displays all htlcs that have been
2022-04-06 06:09:48 +01:00
attempted to be forwarded by the Core Lightning node.
2019-08-10 00:54:18 +01:00
2021-01-26 08:27:42 +00:00
If *status* is specified, then only the forwards with the given status are returned.
2022-11-11 01:44:56 +00:00
*status* can be either *offered* or *settled* or *failed* or *local\_failed*
2021-01-26 08:27:42 +00:00
2022-11-11 01:44:56 +00:00
If *in\_channel* or *out\_channel* is specified, then only the matching forwards
2021-01-26 08:27:42 +00:00
on the given in/out channel are returned.
2023-10-28 04:12:11 +01:00
If neither *in\_channel* or *out\_channel* is specified,
`index` controls ordering, by `created` (default) or `updated` . If
`index` is specified, `start` may be specified to start from that
value, which is generally returned from lightning-wait(7), and `limit`
can be used to specify the maximum number of entries to return.
2019-08-10 00:54:18 +01:00
RETURN VALUE
------------
2021-06-16 02:05:17 +01:00
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **forwards** is returned. It is an array of objects, where each object contains:
2022-09-05 22:33:09 +01:00
2023-10-28 04:12:06 +01:00
- **created\_index** (u64): 1-based index indicating order this forward was created in *(added v23.11)*
2022-09-08 02:08:00 +01:00
- **in\_channel** (short\_channel\_id): the channel that received the HTLC
2022-09-05 22:45:06 +01:00
- **in\_msat** (msat): the value of the incoming HTLC
2022-11-11 02:03:13 +00:00
- **status** (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local\_failed", "failed")
2022-09-05 22:45:06 +01:00
- **received\_time** (number): the UNIX timestamp when this was received
2022-09-27 00:43:35 +01:00
- **in\_htlc\_id** (u64, optional): the unique HTLC id the sender gave this (not present if incoming channel was closed before ugprade to v22.11)
2022-09-08 02:08:00 +01:00
- **out\_channel** (short\_channel\_id, optional): the channel that the HTLC (trying to) forward to
2022-11-11 02:03:13 +00:00
- **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)
2023-10-28 04:12:06 +01:00
- **updated\_index** (u64, optional): 1-based index indicating order this forward was changed (only present if it has changed since creation) *(added v23.11)*
2022-03-31 04:14:27 +01:00
- **style** (string, optional): Either a legacy onion format or a modern tlv format (one of "legacy", "tlv")
2021-06-16 02:05:17 +01:00
2022-09-05 22:45:06 +01:00
If **out\_msat** is present:
2022-09-05 22:33:09 +01:00
2022-09-05 22:45:06 +01:00
- **fee\_msat** (msat): the amount this paid in fees
2022-11-11 02:03:13 +00:00
- **out\_msat** (msat): the amount we sent out the *out\_channel*
2021-06-16 02:05:17 +01:00
If **status** is "settled" or "failed":
2022-09-05 22:33:09 +01:00
2022-09-05 22:45:06 +01:00
- **resolved\_time** (number): the UNIX timestamp when this was resolved
2021-06-16 02:05:17 +01:00
2022-11-11 02:03:13 +00:00
If **status** is "local\_failed" or "failed":
2022-09-05 22:33:09 +01:00
2021-06-16 02:05:17 +01:00
- **failcode** (u32, optional): the numeric onion code returned
- **failreason** (string, optional): the name of the onion code returned
2021-09-03 11:07:59 +01:00
2021-06-16 02:05:17 +01:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
2019-08-10 00:54:18 +01:00
AUTHOR
------
Rene Pickhardt < < r.pickhardt @ gmail . com > > is mainly responsible.
SEE ALSO
--------
2022-09-19 01:53:00 +01:00
lightning-autoclean-status(7), lightning-getinfo(7)
2019-08-10 00:54:18 +01:00
RESOURCES
---------
Main web site: < https: / / github . com / ElementsProject / lightning >
2020-08-25 02:33:16 +01:00
2023-10-28 04:12:06 +01:00
[comment]: # ( SHA256STAMP:b08957fa97a9e574ea80570518551577e272552a29b60d5b1620f00bdfdfe225)