core-lightning/doc/lightning-listforwards.7.md

lightning-listforwards -- Command showing all htlcs and their information
=========================================================================

SYNOPSIS
--------

**listforwards** \[*status*\] \[*in_channel*\] \[*out_channel*\]

DESCRIPTION
-----------

The **listforwards** RPC command displays all htlcs that have been
attempted to be forwarded by the c-lightning node.

If *status* is specified, then only the forwards with the given status are returned.
*status* can be either *offered* or *settled* or *failed* or *local_failed*

If *in_channel* or *out_channel* is specified, then only the matching forwards
on the given in/out channel are returned.

RETURN VALUE
------------

[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **forwards** is returned.  It is an array of objects, where each object contains:
- **in_channel** (short_channel_id): the channel that received the HTLC
- **in_msat** (msat): the value of the incoming HTLC
- **status** (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed")
- **received_time** (number): the UNIX timestamp when this was received
- **out_channel** (short_channel_id, optional): the channel that the HTLC was forwarded to
- **payment_hash** (hex, optional): payment hash sought by HTLC (always 64 characters)

If **out_channel** 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
[comment]: # (GENERATE-FROM-SCHEMA-END)

AUTHOR
------

Rene Pickhardt <<r.pickhardt@gmail.com>> is mainly responsible.

SEE ALSO
--------

lightning-getinfo(7)

RESOURCES
---------

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

[comment]: # ( SHA256STAMP:d2fe60f5039f5ad4682c88ce88d513c0ad74d8d4967dd233b399a19e27aac2ee)
docs: Update manpages to be recognized correctly by mrkd mrkd started enforcing the `name -- short description` style of top-level headings somewhere, and was thus failing to build the man-pages. I swapped the title and with the existing short description to make it work again. `mrkd` will automatically infer the section from the filename so no need to put it in the title as well. In addition I removed the "last updated" lines at the bottom since they are out of date at best, and misleading at the worst. If we want to keep them, I'd suggest generating them from the commit that last touched them. 2019-08-31 14:30:56 +02:00			`lightning-listforwards -- Command showing all htlcs and their information`
			`=========================================================================`
doc/manpages: replace asciidoc by markdown 2019-08-10 01:54:18 +02:00
			`SYNOPSIS`
			`--------`

Updated listforwards doc with new parameters Changelog-Added: JSON-RPC: `listforwards` can now filter by status, in and out channel. 2021-01-26 09:27:42 +01:00			`listforwards \[status\] \[in_channel\] \[out_channel\]`
doc/manpages: replace asciidoc by markdown 2019-08-10 01:54:18 +02:00
			`DESCRIPTION`
			`-----------`

			`The listforwards RPC command displays all htlcs that have been`
			`attempted to be forwarded by the c-lightning node.`

Updated listforwards doc with new parameters Changelog-Added: JSON-RPC: `listforwards` can now filter by status, in and out channel. 2021-01-26 09:27:42 +01:00			`If status is specified, then only the forwards with the given status are returned.`
			`status can be either offered or settled or failed or local_failed`

			`If in_channel or out_channel is specified, then only the matching forwards`
			`on the given in/out channel are returned.`

doc/manpages: replace asciidoc by markdown 2019-08-10 01:54:18 +02:00			`RETURN VALUE`
			`------------`

doc/schemas: getsharedsecret, help, invoice, listchannels, listforwards And a new "u8" type. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> 2021-06-16 03:05:17 +02:00			`[comment]: # (GENERATE-FROM-SCHEMA-START)`
			`On success, an object containing forwards is returned. It is an array of objects, where each object contains:`
			`- in_channel (short_channel_id): the channel that received the HTLC`
			`- in_msat (msat): the value of the incoming HTLC`
			`- status (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed")`
			`- received_time (number): the UNIX timestamp when this was received`
			`- out_channel (short_channel_id, optional): the channel that the HTLC was forwarded to`
			`- payment_hash (hex, optional): payment hash sought by HTLC (always 64 characters)`

			`If out_channel 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`
			`[comment]: # (GENERATE-FROM-SCHEMA-END)`
doc/manpages: replace asciidoc by markdown 2019-08-10 01:54:18 +02:00
			`AUTHOR`
			`------`

			`Rene Pickhardt <<r.pickhardt@gmail.com>> is mainly responsible.`

			`SEE ALSO`
			`--------`

			`lightning-getinfo(7)`

			`RESOURCES`
			`---------`

			`Main web site: <https://github.com/ElementsProject/lightning>`
doc: force refresh of all manpages. The idea is that you regenerate the man pages in the same commit you alter them: that's how we know whether to try regenerating them or not (git doesn't store timestamps, so it can't really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> 2020-08-25 03:33:16 +02:00
tools/fromschema.py: handle deprecated null field, don't create empty lists. 1. listpeers has a deprecated `"closer": null`, which we need to handle in the schema, while trying not to damage our documentation too much. 2. Don't print a condition if there are no fields to print. 3. Allow a special "untyped" marker for multifundchannel which returns arbitrary JSON in a field. 4. Allow a single field return (for 'stop'). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> 2021-06-16 03:08:17 +02:00			`[comment]: # ( SHA256STAMP:d2fe60f5039f5ad4682c88ce88d513c0ad74d8d4967dd233b399a19e27aac2ee)`