diff --git a/doc/Makefile b/doc/Makefile index 7e5efb7fc..fe57a92a9 100644 --- a/doc/Makefile +++ b/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 diff --git a/doc/lightning-decodepay.7 b/doc/lightning-decodepay.7 new file mode 100644 index 000000000..7bf86d97b --- /dev/null +++ b/doc/lightning-decodepay.7 @@ -0,0 +1,197 @@ +'\" t +.\" Title: lightning-decodepay +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" 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 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 diff --git a/doc/lightning-decodepay.7.txt b/doc/lightning-decodepay.7.txt new file mode 100644 index 000000000..d990b9a9c --- /dev/null +++ b/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 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 diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 index 9c7644424..2543cd6de 100644 --- a/doc/lightning-getroute.7 +++ b/doc/lightning-getroute.7 @@ -2,12 +2,12 @@ .\" Title: lightning-getroute .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" 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 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 diff --git a/doc/lightning-getroute.7.txt b/doc/lightning-getroute.7.txt index a886ec3b4..905b319bf 100644 --- a/doc/lightning-getroute.7.txt +++ b/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 is mainly responsible. SEE ALSO -------- -lightning-listinvoice(7), lightning-delinvoice(7), -lightning-getroute(7), lightning-sendpay(7). +lightning-pay(7), lightning-sendpay(7). RESOURCES --------- diff --git a/doc/lightning-listpayments.7 b/doc/lightning-listpayments.7 new file mode 100644 index 000000000..e69de29bb diff --git a/doc/lightning-listpayments.7.txt b/doc/lightning-listpayments.7.txt new file mode 100644 index 000000000..26b0145f4 --- /dev/null +++ b/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 is mainly responsible. + +SEE ALSO +-------- +lightning-pay(7), ligthning-sendpay(7), lightning-listinvoice(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 new file mode 100644 index 000000000..85ad95b3e --- /dev/null +++ b/doc/lightning-pay.7 @@ -0,0 +1,51 @@ +'\" t +.\" Title: lightning-pay +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" 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 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 diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt new file mode 100644 index 000000000..5f3bb2ba9 --- /dev/null +++ b/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 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 diff --git a/lightningd/invoice.c b/lightningd/invoice.c index dbf7b5d7c..d4b5ff220 100644 --- a/lightningd/invoice.c +++ b/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); diff --git a/lightningd/pay.c b/lightningd/pay.c index 5d6fc7bb1..f5fb902a5 100644 --- a/lightningd/pay.c +++ b/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);