listpays: new command to summarize pay commands.

This is to future-proof against multi-part-payments: the low-level commands
will start returning multiple results once we have that, so prepare
transition plan now.

Closes: ElementsProject#2372
Signed-off-by: Rusty Russell <[email protected]>

CHANGELOG.md

@@ -32,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - JSON API: `fundchannel` and `withdraw` now have a new parameter `minconf` that limits coinselection to outputs that have at least `minconf` confirmations (default 1). (#2380)
 - JSON API: `listfunds` now displays addresses for all outputs owned by the wallet (#2387)
 - JSON API: `waitsendpay` and `sendpay` output field `label` as specified by `sendpay` call.
+- JSON API: `listpays` command for higher-level payment view than `listpayments`, especially important with multi-part-payments coming.
 
 ### Changed
 

doc/Makefile

@@ -21,6 +21,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-listfunds.7 \
 	doc/lightning-listinvoices.7 \
 	doc/lightning-listpayments.7 \
+	doc/lightning-listpays.7 \
 	doc/lightning-listpeers.7 \
 	doc/lightning-newaddr.7 \
 	doc/lightning-pay.7 \
@@ -29,7 +30,6 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-waitanyinvoice.7 \
 	doc/lightning-waitsendpay.7 \
 	doc/lightning-withdraw.7 
-
 
 doc-all: $(MANPAGES)
 

doc/lightning-listpays.7

@@ -0,0 +1,108 @@
+'\" t
+.\"     Title: lightning-listpays
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 02/23/2019
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-LISTPAYS" "7" "02/23/2019" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * 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-listpays \- Command for querying payment status
+.SH "SYNOPSIS"
+.sp
+\fBlistpays\fR [bolt11]
+.SH "DESCRIPTION"
+.sp
+The \fBlistpay\fR RPC command gets the status of all \fIpay\fR commands, or a single one if \fIbolt11\fR is specified\&.
+.SH "RETURN VALUE"
+.sp
+On success, an array of objects is returned\&. Each object contains:
+.PP
+\fIbolt11\fR
+.RS 4
+the
+\fIbolt11\fR
+argument given to
+\fIpay\fR
+(see below for exceptions)\&.
+.RE
+.PP
+\fIstatus\fR
+.RS 4
+one of
+\fIcomplete\fR,
+\fIfailed\fR
+or
+\fIpending\fR\&.
+.RE
+.PP
+\fIpayment_preimage\fR
+.RS 4
+(if
+\fIstatus\fR
+is
+\fIcomplete\fR) proves payment was received\&.
+.RE
+.PP
+\fIlabel\fR
+.RS 4
+optional
+\fIlabel\fR, if provided to
+\fIpay\fR\&.
+.RE
+.PP
+\fIamount_sent_msat\fR
+.RS 4
+total amount sent, in "NNNmsat" format\&.
+.RE
+.sp
+For old payments (pre\-0\&.7) we didn\(cqt save the \fIbolt11\fR string, so in its place are three other fields:
+.PP
+\fIpayment_hash\fR
+.RS 4
+the hash of the
+\fIpayment_preimage\fR
+which will prove payment\&.
+.RE
+.PP
+\fIdestination\fR
+.RS 4
+the final destination of the payment\&.
+.RE
+.PP
+\fIamount_msat\fR
+.RS 4
+the amount the destination received, in "NNNmsat" format\&.
+.RE
+.sp
+These three can all be extracted from \fIbolt11\fR, hence are obsolete\&.
+.SH "AUTHOR"
+.sp
+Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-pay(7), lightning\-paystatus(7), lightning\-listpayments(7)\&.
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-listpays.7.txt

@@ -0,0 +1,49 @@
+LIGHTNING-LISTPAYS(7)
+=====================
+:doctype: manpage
+
+NAME
+----
+lightning-listpays - Command for querying payment status
+
+SYNOPSIS
+--------
+*listpays* [bolt11]
+
+DESCRIPTION
+-----------
+
+The *listpay* RPC command gets the status of all 'pay' commands, or a single
+one if 'bolt11' is specified.
+
+RETURN VALUE
+------------
+On success, an array of objects is returned.  Each object contains:
+
+'bolt11':: the 'bolt11' argument given to 'pay' (see below for exceptions).
+'status':: one of 'complete', 'failed' or 'pending'.
+'payment_preimage':: (if 'status' is 'complete') proves payment was received.
+'label':: optional 'label', if provided to 'pay'.
+'amount_sent_msat':: total amount sent, in "NNNmsat" format.
+
+For old payments (pre-0.7) we didn't save the 'bolt11' string, so in
+its place are three other fields:
+
+'payment_hash':: the hash of the 'payment_preimage' which will prove payment.
+'destination':: the final destination of the payment.
+'amount_msat':: the amount the destination received, in "NNNmsat" format.
+
+These three can all be extracted from 'bolt11', hence are obsolete.
+//FIXME:Enumerate errors
+
+AUTHOR
+------
+Rusty Russell <[email protected]> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-pay(7), lightning-paystatus(7), lightning-listpayments(7).
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightning-pay.7

@@ -40,7 +40,7 @@ The \fIlabel\fR field is used to attach a label to payments, and is returned in
 .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\&.
 .sp
-The command will keep finding routes and retrying the payment until it succeeds, or the given \fIretry_for\fR seconds passes\&. Note that the command may stop retrying while a pending payment is ongoing, which you need to monitor with \fBlistpayments\fR or \fBwaitsendpay\fR\&. \fIretry_for\fR defaults to 60 seconds and can only be an integer\&.
+The command will keep finding routes and retrying the payment until it succeeds, or the given \fIretry_for\fR seconds passes\&. Note that the command may stop retrying while a pending payment is ongoing, which you need to monitor with \fBlistpays\fR\&. \fIretry_for\fR defaults to 60 seconds and can only be an integer\&.
 .sp
 When using \fIlightning\-cli\fR, you may skip optional parameters by using \fInull\fR\&. Alternatively, use \fB\-k\fR option to provide parameters by name\&.
 .SH "RANDOMIZATION"
@@ -102,9 +102,7 @@ The following error codes may occur:
 .IP \(bu 2.3
 .\}
 200\&. Payment timed out while a payment is in progress\&. Monitor the status of that payment with
-\fIlistpayments\fR
-command, or wait for that payment to complete with
-\fIpay\fR
+\fIlistpays\fR
 command\&.
 .RE
 .sp
@@ -267,7 +265,7 @@ The \fIdata\fR field of errors will include statistics \fIgetroute_tries\fR and
 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)\&.
+lightning\-listpays(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

@@ -40,7 +40,7 @@ succeed immediately.
 The command will keep finding routes and retrying the payment until
 it succeeds, or the given 'retry_for' seconds passes.
 Note that the command may stop retrying while a pending payment is
-ongoing, which you need to monitor with *listpayments* or *waitsendpay*.
+ongoing, which you need to monitor with *listpays*.
 'retry_for' defaults to 60 seconds and can only be an integer.
 
 When using 'lightning-cli', you may skip optional parameters by using
@@ -91,8 +91,7 @@ The following error codes may occur:
 
 * -1. Catchall nonspecific error.
 * 200. Payment timed out while a payment is in progress. Monitor
-  the status of that payment with 'listpayments' command, or
-  wait for that payment to complete with 'pay' command.
+  the status of that payment with 'listpays' command.
 * 201. Already paid with this 'hash' using different amount or
   destination.
 * 203. Permanent failure at destination. The 'data' field of
@@ -145,7 +144,7 @@ Rusty Russell <[email protected]> is mainly responsible.
 
 SEE ALSO
 --------
-lightning-listpayments(7), lightning-decodepay(7),
+lightning-listpays(7), lightning-decodepay(7),
 lightning-listinvoice(7), lightning-delinvoice(7),
 lightning-getroute(7), lightning-invoice(7).
 

plugins/pay.c

@@ -1,4 +1,5 @@
 #include <ccan/array_size/array_size.h>
+#include <ccan/cast/cast.h>
 #include <ccan/intmap/intmap.h>
 #include <ccan/tal/str/str.h>
 #include <ccan/time/time.h>
@@ -1093,6 +1094,90 @@ static struct command_result *handle_paystatus(struct command *cmd,
 	return command_success(cmd, ret);
 }
 
+static const jsmntok_t *copy_member(char **ret,
+				    const char *buf,
+				    const jsmntok_t *result,
+				    const char *membername,
+				    const char *term)
+{
+	const jsmntok_t *m = json_get_member(buf, result, membername);
+	if (m)
+		tal_append_fmt(ret, "'%s': %.*s%s",
+			       membername,
+			       json_tok_full_len(m), json_tok_full(buf, m),
+			       term);
+	return m;
+}
+
+static struct command_result *listpayments_done(struct command *cmd,
+						const char *buf,
+						const jsmntok_t *result,
+						char *b11str)
+{
+	size_t i;
+	const jsmntok_t *t, *arr;
+	char *ret;
+	bool some = false;
+
+	arr = json_get_member(buf, result, "payments");
+	if (!arr || arr->type != JSMN_ARRAY)
+		return command_fail(cmd, LIGHTNINGD,
+				    "Unexpected non-array result from listpayments");
+
+	ret = tal_fmt(cmd, "{ 'pays': [");
+	json_for_each_arr(i, t, arr) {
+		const jsmntok_t *status;
+
+		if (some)
+			tal_append_fmt(&ret, ",\n");
+		some = true;
+
+		tal_append_fmt(&ret, "{");
+		/* Old payments didn't have bolt11 field */
+		if (!copy_member(&ret, buf, t, "bolt11", ",")) {
+			if (b11str) {
+				/* If it's a single query, we can fake it */
+				tal_append_fmt(&ret, "'bolt11': '%s',", b11str);
+			} else {
+				copy_member(&ret, buf, t, "payment_hash", ",");
+				copy_member(&ret, buf, t, "destination", ",");
+				copy_member(&ret, buf, t, "amount_msat", ",");
+			}
+		}
+
+		status = copy_member(&ret, buf, t, "status", ",");
+		if (status && json_tok_streq(buf, status, "complete"))
+			copy_member(&ret, buf, t, "payment_preimage", ",");
+		copy_member(&ret, buf, t, "label", ",");
+		copy_member(&ret, buf, t, "amount_sent_msat", "");
+		tal_append_fmt(&ret, "}");
+	}
+	tal_append_fmt(&ret, "] }");
+	return command_success(cmd, ret);
+}
+
+static struct command_result *handle_listpays(struct command *cmd,
+					      const char *buf,
+					      const jsmntok_t *params)
+{
+	const char *b11str, *paramstr;
+
+	/* FIXME: would be nice to parse as a bolt11 so check worked in future */
+	if (!param(cmd, buf, params,
+		   p_opt("bolt11", param_string, &b11str),
+		   NULL))
+		return NULL;
+
+	if (b11str)
+		paramstr = tal_fmt(tmpctx, "'bolt11' : '%s'", b11str);
+	else
+		paramstr = "";
+	return send_outreq(cmd, "listpayments",
+			   listpayments_done, forward_error,
+			   cast_const(char *, b11str),
+			   "%s", paramstr);
+}
+
 static void init(struct plugin_conn *rpc)
 {
 	const char *field;
@@ -1117,6 +1202,11 @@ static const struct plugin_command commands[] = { {
 		"Detail status of attempts to pay {bolt11}, or all",
 		"Covers both old payments and current ones.",
 		handle_paystatus
+	}, {
+		"listpays",
+		"List result of payment {bolt11}, or all",
+		"Covers old payments (failed and succeeded) and current ones.",
+		handle_listpays
 	}
 };