mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-20 13:54:36 +01:00
Code Issues Projects Releases Wiki Activity

listpays: new command to summarize pay commands.

Browse source 
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: #2372
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2019-02-23 15:30:04 +10:30
parent e0605466bf
commit 56dfbec6bd
7 changed files with 255 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
CHANGELOG.md
View file

@ -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

2
doc/Makefile
View file

@ -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)

108
doc/lightning-listpays.7 Normal file
View file

@ -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

49
doc/lightning-listpays.7.txt Normal file
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-pay(7), lightning-paystatus(7), lightning-listpayments(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

8
doc/lightning-pay.7
View file

@ -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

7
doc/lightning-pay.7.txt
View file

@ -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 <rusty@rustcorp.com.au> 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).

90
plugins/pay.c
View file

@ -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
}
};