doc: manpages for pay, listpayments and decodepay.

Also contains some help message clarifications.

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

doc/Makefile

@@ -5,10 +5,13 @@ doc-wrongdir:
 	$(MAKE) -C .. doc-all
 
 MANPAGES := doc/lightning-cli.1 \
+	doc/lightning-decodepay.7 \
 	doc/lightning-delinvoice.7 \
 	doc/lightning-getroute.7 \
 	doc/lightning-invoice.7 \
 	doc/lightning-listinvoice.7 \
+	doc/lightning-listpayments.7 \
+	doc/lightning-pay.7 \
 	doc/lightning-sendpay.7 \
 	doc/lightning-waitinvoice.7 \
 	doc/lightning-waitanyinvoice.7

doc/lightning-decodepay.7

@@ -0,0 +1,197 @@
+'\" t
+.\"     Title: lightning-decodepay
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 01/13/2018
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-DECODEPAY" "7" "01/13/2018" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+lightning-decodepay \- Protocol for decoding a bolt11 string (low\-level)
+.SH "SYNOPSIS"
+.sp
+\fBdecodepay\fR \fIbolt11\fR [\fIdescription\fR]
+.SH "DESCRIPTION"
+.sp
+The \fBdecodepay\fR RPC command checks and parses a \fIbolt11\fR string as specfied by the BOLT 11 specification\&.
+.SH "RETURN VALUE"
+.sp
+On success, an object is returned with the following fields, as specified by BOLT11:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIcurrency\fR: the BIP173 name for the currency\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fItimestamp\fR: the UNIX\-style timestamp of the invoice\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIexpiry\fR: the number of seconds this is valid after
+\fItimestamp\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIpayee\fR: the public key of the recipient\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIpayment_hash\fR: the payment hash of the request\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIsignature\fR: the DER\-encoded signature\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdescription\fR: the description of the purpose of the purchase (see below)
+.RE
+.sp
+The following fields are optional:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fImsatoshi\fR: the number of millisatoshi requested (if any)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIfallback\fR: fallback address object containing a
+\fIhex\fR
+string, and both
+\fItype\fR
+and
+\fIaddr\fR
+if it is recognized as one of
+\fIP2PKH\fR,
+\fIP2SH\fR,
+\fIP2WPKH\fR, or
+\fIP2WSH\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIroutes\fR: an array of routes\&. Each route is an arrays of objects, each containing
+\fIpubkey\fR,
+\fIshort_channel_id\fR,
+\fIfee_base_msat\fR,
+\fIfee_proportional_millionths\fR
+and
+\fIcltv_expiry_delta\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIextra\fR: an array of objects representing unknown fields, each with one\-character
+\fItag\fR
+and a
+\fIdata\fR
+bech32 string\&.
+.RE
+.sp
+Technically, the \fIdescription\fR field is optional if a \fIdescription_hash\fR field is given, but in this case \fBdecodepay\fR will only succeed if the optional \fIdescription\fR field is passed and matches the \fIdescription_hash\fR\&. In practice, these are currently unused\&.
+.SH "AUTHOR"
+.sp
+Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-pay(7), lightning\-getroute(7), lightning\-sendpay(7)\&.
+.sp
+BOLT #11\&.
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-decodepay.7.txt

@@ -0,0 +1,60 @@
+LIGHTNING-DECODEPAY(7)
+======================
+:doctype: manpage
+
+NAME
+----
+lightning-decodepay - Protocol for decoding a bolt11 string (low-level)
+
+
+SYNOPSIS
+--------
+*decodepay* 'bolt11' ['description']
+
+DESCRIPTION
+-----------
+The *decodepay* RPC command checks and parses a 'bolt11' string as specfied
+by the BOLT 11 specification.
+
+RETURN VALUE
+------------
+
+On success, an object is returned with the following fields, as specified
+by BOLT11:
+
+- 'currency': the BIP173 name for the currency.
+- 'timestamp': the UNIX-style timestamp of the invoice.
+- 'expiry': the number of seconds this is valid after 'timestamp'.
+- 'payee': the public key of the recipient.
+- 'payment_hash': the payment hash of the request.
+- 'signature': the DER-encoded signature.
+- 'description': the description of the purpose of the purchase (see below)
+
+The following fields are optional:
+
+- 'msatoshi': the number of millisatoshi requested (if any).
+- 'fallback': fallback address object containing a 'hex' string, and
+  both 'type' and 'addr' if it is recognized as one of 'P2PKH', 'P2SH', 'P2WPKH', or 'P2WSH'.
+- 'routes':  an array of routes.  Each route is an arrays of objects, each containing 'pubkey', 'short_channel_id', 'fee_base_msat', 'fee_proportional_millionths' and 'cltv_expiry_delta'.
+- 'extra': an array of objects representing unknown fields, each with one-character 'tag' and a 'data' bech32 string.
+
+Technically, the 'description' field is optional if a
+'description_hash' field is given, but in this case *decodepay* will
+only succeed if the optional 'description' field is passed and matches
+the 'description_hash'.  In practice, these are currently unused.
+
+//FIXME:Enumerate errors
+
+AUTHOR
+------
+Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-pay(7), lightning-getroute(7), lightning-sendpay(7).
+
+https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md[BOLT #11].
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightning-getroute.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-getroute
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 02/27/2017
+.\"      Date: 01/13/2018
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-GETROUTE" "7" "02/27/2017" "\ \&" "\ \&"
+.TH "LIGHTNING\-GETROUTE" "7" "01/13/2018" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -28,7 +28,7 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-lightning-getroute \- Protocol for routing a payment\&.
+lightning-getroute \- Protocol for routing a payment (low\-level)\&.
 .SH "SYNOPSIS"
 .sp
 \fBgetroute\fR \fIid\fR \fImsatoshi\fR \fIriskfactor\fR
@@ -261,7 +261,7 @@ timeout for the payment failure, in blocks\&.
 Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
 .SH "SEE ALSO"
 .sp
-lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-sendpay(7)\&.
+lightning\-pay(7), lightning\-sendpay(7)\&.
 .SH "RESOURCES"
 .sp
 Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-getroute.7.txt

@@ -4,7 +4,7 @@ LIGHTNING-GETROUTE(7)
 
 NAME
 ----
-lightning-getroute - Protocol for routing a payment.
+lightning-getroute - Protocol for routing a payment (low-level).
 
 
 SYNOPSIS
@@ -101,8 +101,7 @@ Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
 
 SEE ALSO
 --------
-lightning-listinvoice(7), lightning-delinvoice(7),
+lightning-pay(7), lightning-sendpay(7).
-lightning-getroute(7), lightning-sendpay(7).
 
 RESOURCES
 ---------

doc/lightning-listpayments.7.txt

@@ -0,0 +1,35 @@
+LIGHTNING-LISTPAYMENTS(7)
+========================
+:doctype: manpage
+
+NAME
+----
+lightning-listpayments - Protocol for querying payment status
+
+SYNOPSIS
+--------
+*listpayments*
+
+DESCRIPTION
+-----------
+
+The *listpayments* RPC command gets the status of all 'pay' and
+'sendpay' commands.
+
+RETURN VALUE
+------------
+On success, an array of objects is returned.  Each object contains an 'id' (unique internal value assigned at creation), 'payment_hash', 'destination', 'msatoshi' and 'timestamp' (UNIX timestamp indicating when it was initiated), and a 'status' which is one of 'pending' (in progress), 'complete' (successfully paid) or 'failed'.
+
+//FIXME:Enumerate errors
+
+AUTHOR
+------
+Christian Decker <decker.christian@gmail.com> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-pay(7), ligthning-sendpay(7), lightning-listinvoice(7).
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightning-pay.7

@@ -0,0 +1,51 @@
+'\" t
+.\"     Title: lightning-pay
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 01/13/2018
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-PAY" "7" "01/13/2018" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+lightning-pay \- Protocol for sending a payment to a BOLT11 invoice
+.SH "SYNOPSIS"
+.sp
+\fBpay\fR \fIbolt11\fR [\fImsatoshi\fR] [\fIdescription\fR] [\fIriskfactor\fR]
+.SH "DESCRIPTION"
+.sp
+The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 1\&.0\&.
+.sp
+The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
+.SH "RETURN VALUE"
+.sp
+On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&.
+.SH "AUTHOR"
+.sp
+Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-listpayments(7), lightning\-decodepay(7), lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-invoice(7)\&.
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-pay.7.txt

@@ -0,0 +1,47 @@
+LIGHTNING-PAY(7)
+================
+:doctype: manpage
+
+NAME
+----
+lightning-pay - Protocol for sending a payment to a BOLT11 invoice
+
+SYNOPSIS
+--------
+*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor']
+
+DESCRIPTION
+-----------
+
+The *pay* RPC command attempts to find a route to the given destination,
+and send the funds it asks for.  If the 'bolt11' does not contain an amount,
+'msatoshi' is required, otherwise if it is specified it must be 'null'.  If
+'bolt11' contains a description hash ('h' field) 'description' is
+required, otherwise it is unused.  The 'riskfactor' is described in detail
+in lightning-getroute(7), and defaults to 1.0.
+
+The response will occur when the payment fails or succeeds.  Once a
+payment has succeeded, calls to *pay* with the same 'bolt11' will
+succeed immediately.
+
+RETURN VALUE
+------------
+
+On success, this returns the payment 'preimage' which hashes to the
+'payment_hash' to prove that the payment was successful.
+
+//FIXME:Enumerate errors
+
+AUTHOR
+------
+Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-listpayments(7), lightning-decodepay(7),
+lightning-listinvoice(7), lightning-delinvoice(7),
+lightning-getroute(7), lightning-invoice(7).
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

lightningd/invoice.c

@@ -656,7 +656,7 @@ static void json_decodepay(struct command *cmd,
 static const struct json_command decodepay_command = {
 	"decodepay",
 	json_decodepay,
-	"Parse and decode {bolt11} if possible",
+	"Parse and decode {bolt11} if possible, using {description} if necessary",
 	"Returns a verbose description on success"
 };
 AUTODATA(json_command, &decodepay_command);

lightningd/pay.c

@@ -482,7 +482,7 @@ static void json_pay(struct command *cmd,
 static const struct json_command pay_command = {
 	"pay",
 	json_pay,
-	"Send payment in {bolt11} with optional {msatoshi}, {description} and {riskfactor}",
+	"Send payment specified by {bolt11} with optional {msatoshi} (iff {bolt11} does not have amount), {description} (required if {bolt11} uses description hash) and {riskfactor} (default 1.0)",
 	"Returns the {preimage} on success"
 };
 AUTODATA(json_command, &pay_command);