doc: update lightning-listforwards(7)

It didn't have the new payment_hash field in it, and needed updating to
list optional fields.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/lightning-listforwards.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-listforwards
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 07/15/2019
+.\"      Date: 08/15/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-LISTFORWA" "7" "07/15/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-LISTFORWA" "7" "08/15/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -61,8 +61,9 @@ Each entry in \fIforwards\fR will include:
 .sp -1
 .IP \(bu 2.3
 .\}
-\fIout_channel\fR
+\fIin_msatoshi\fR,
-\- the short_channel_id of to which the outgoing htlc is supposed to be forwarded\&.
+\fIin_msat\fR
+\- amount of msatoshis that are forwarded to this node\&.
 .RE
 .sp
 .RS 4
@@ -73,9 +74,16 @@ Each entry in \fIforwards\fR will include:
 .sp -1
 .IP \(bu 2.3
 .\}
-\fIin_msatoshi\fR,
+\fIstatus\fR
-\fIin_msat\fR
+\- status can be either
-\- amount of msatoshis that are forwarded to this node\&.
+\fIoffered\fR
+if the routing process is still ongoing,
+\fIsettled\fR
+if the routing process is completed,
+\fIfailed\fR
+if the routing process could not be completed, or
+\fIlocal_failed\fR
+if the node failed the forward itself\&.
 .RE
 .sp
 .RS 4
@@ -86,11 +94,12 @@ Each entry in \fIforwards\fR will include:
 .sp -1
 .IP \(bu 2.3
 .\}
-\fIout_msatoshi\fR,
+\fIreceived_time\fR
-\fIout_msat\fR
+\- timestamp when incoming htlc was received\&.
-\- amount of msatoshis to be forwarded\&.
 .RE
 .sp
+The following additional fields are usually present, but will not be for some variants of status \fIlocal_failed\fR (if it failed before we determined these):
+.sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
@@ -112,14 +121,8 @@ Each entry in \fIforwards\fR will include:
 .sp -1
 .IP \(bu 2.3
 .\}
-\fIstatus\fR
+\fIout_channel\fR
-\- status can be either
+\- the short_channel_id of to which the outgoing htlc is supposed to be forwarded\&.
-\fIoffered\fR
-if the routing process is still ongoing,
-\fIsettled\fR
-if the routing process is completed or
-\fIfailed\fR
-if the routing process could not be completed\&.
 .RE
 .sp
 .RS 4
@@ -130,10 +133,27 @@ if the routing process could not be completed\&.
 .sp -1
 .IP \(bu 2.3
 .\}
-\fIreceived_time\fR
+\fIout_msatoshi\fR,
-\- timestamp when incoming htlc was received\&.
+\fIout_msat\fR
+\- amount of msatoshis to be forwarded\&.
+.RE
+.sp
+The following fields may be offered, but for old forgotten HTLCs they will be omitted:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIpayment_hash\fR
+\- the payment_hash belonging to the HTLC\&.
 .RE
 .sp
+If the status is not \fIoffered\fR, the following additional fields are present:
+.sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c

doc/lightning-listforwards.7.txt

@@ -22,17 +22,26 @@ Each entry in 'forwards' will include:
 
 - 'in_channel' - the short_channel_id of the channel that recieved the incoming htlc.
 
-- 'out_channel' - the short_channel_id of to which the outgoing htlc is supposed to be forwarded.
-
 - 'in_msatoshi', 'in_msat' - amount of msatoshis that are forwarded to this node.
 
-- 'out_msatoshi', 'out_msat' - amount of msatoshis to be forwarded.
+- 'status' - status can be either 'offered' if the routing process is still ongoing, 'settled' if the routing process is completed, 'failed' if the routing process could not be completed, or 'local_failed' if the node failed the forward itself.
+
+- 'received_time' - timestamp when incoming htlc was received.
+
+The following additional fields are usually present, but will not be for some
+variants of status 'local_failed' (if it failed before we determined these):
 
 - 'fee', 'fee_msat' - fee offered for forwarding the htlc in msatoshi.
 
-- 'status' - status can be either 'offered' if the routing process is still ongoing, 'settled' if the routing process is completed or 'failed' if the routing process could not be completed.
+- 'out_channel' - the short_channel_id of to which the outgoing htlc is supposed to be forwarded.
 
-- 'received_time' - timestamp when incoming htlc was received.
+- 'out_msatoshi', 'out_msat' - amount of msatoshis to be forwarded.
+
+The following fields may be offered, but for old forgotten HTLCs they will be omitted:
+
+- 'payment_hash' - the payment_hash belonging to the HTLC.
+
+If the status is not 'offered', the following additional fields are present:
 
 - 'resolved_time' - timestamp when htlc was resolved (settled or failed).