Skip to content

Query listpays by label #9441

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ErikDeSmedt wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Query listpays by label #9441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
58ab04f
lightningd: Allow to query `listpays` by label
ErikDeSmedt Aug 19, 2026
f8b9fc4
msggen: regenerate for `label` parameter in `listpays`/`listsendpays`
ErikDeSmedt Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .msggen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3276,6 +3276,7 @@
"ListpaysRequest": {
"ListPays.bolt11": 1,
"ListPays.index": 4,
"ListPays.label": 7,
"ListPays.limit": 6,
"ListPays.payment_hash": 2,
"ListPays.start": 5,
Expand Down Expand Up @@ -3570,6 +3571,7 @@
"ListsendpaysRequest": {
"ListSendPays.bolt11": 1,
"ListSendPays.index": 4,
"ListSendPays.label": 7,
"ListSendPays.limit": 6,
"ListSendPays.payment_hash": 2,
"ListSendPays.start": 5,
Expand Down Expand Up @@ -11728,6 +11730,10 @@
"added": "v24.11",
"deprecated": null
},
"ListPays.label": {
"added": "v26.09",
"deprecated": null
},
"ListPays.limit": {
"added": "v24.11",
"deprecated": null
Expand Down Expand Up @@ -12668,6 +12674,10 @@
"added": "v23.11",
"deprecated": null
},
"ListSendPays.label": {
"added": "v26.09",
"deprecated": null
},
"ListSendPays.limit": {
"added": "v23.11",
"deprecated": null
Expand Down
2 changes: 2 additions & 0 deletions cln-grpc/proto/node.proto
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions cln-grpc/src/convert.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 5 additions & 1 deletion cln-rpc/src/model.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 16 additions & 2 deletions contrib/msggen/msggen/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26239,7 +26239,7 @@
"rpc": "listpays",
"title": "Command for querying payment status",
"description": [
"The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if either *bolt11* or *payment_hash* was specified."
"The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if *bolt11*, *payment_hash* or *label* was specified."
],
"categories": [
"readonly"
Expand Down Expand Up @@ -26298,6 +26298,13 @@
"NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered",
"NOTE: the actual number returned may be less than the limit, as individual payment parts are combined together"
]
},
"label": {
"type": "string",
"added": "v26.09",
"description": [
"Limits results to payments with this label (as given to pay or sendpay). Cannot be used with *bolt11* or *payment_hash*."
]
}
}
},
Expand Down Expand Up @@ -29006,7 +29013,7 @@
"rpc": "listsendpays",
"title": "Low-level command for querying sendpay status",
"description": [
"The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11* or *payment_hash* limits results to that specific payment. You cannot specify both. It is possible to filter the payments also by *status*.",
"The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11*, *payment_hash* or *label* limits results to that specific payment. You can only specify one of them. It is possible to filter the payments also by *status*.",
"",
"Note that there may be more than one concurrent *sendpay* command per *pay*, so this command should be used with caution."
],
Expand Down Expand Up @@ -29064,6 +29071,13 @@
"description": [
"If `index` is specified, `limit` can be used to specify the maximum number of entries to return."
]
},
"label": {
"type": "string",
"added": "v26.09",
"description": [
"Limits results to payments with this label (as given to sendpay). Cannot be used with *bolt11* or *payment_hash*."
]
}
},
"dependentUpon": {
Expand Down
14 changes: 8 additions & 6 deletions contrib/pyln-client/pyln/client/lightning.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1043,17 +1043,18 @@ def listoffers(self, offer_id=None, active_only=None):
}
return self.call("listoffers", payload)

def listpays(self, bolt11=None, payment_hash=None, status=None, index=None, start=None, limit=None):
def listpays(self, bolt11=None, payment_hash=None, status=None, index=None, start=None, limit=None, label=None):
"""
Show outgoing payments, regarding {bolt11} or {payment_hash} if set
Can only specify one of {bolt11} or {payment_hash}. It is possible
filter the payments by {status}.
Show outgoing payments, regarding {bolt11}, {payment_hash} or
{label} if set. Can only specify one of {bolt11}, {payment_hash}
or {label}. It is possible filter the payments by {status}.
"""
assert not (bolt11 and payment_hash)
payload = {
"bolt11": bolt11,
"payment_hash": payment_hash,
"status": status,
"label": label,
"index": index,
"start": start,
"limit": limit,
Expand Down Expand Up @@ -1083,12 +1084,13 @@ def listpeerchannels(self, peer_id=None, short_channel_id=None, channel_id=None)
}
return self.call("listpeerchannels", payload)

def listsendpays(self, bolt11=None, payment_hash=None, status=None, index=None, start=None, limit=None):
"""Show all sendpays results, or only for `bolt11` or `payment_hash`."""
def listsendpays(self, bolt11=None, payment_hash=None, status=None, index=None, start=None, limit=None, label=None):
"""Show all sendpays results, or only for `bolt11`, `payment_hash` or `label`."""
payload = {
"bolt11": bolt11,
"payment_hash": payment_hash,
"status": status,
"label": label,
"index": index,
"start": start,
"limit": limit,
Expand Down
2,308 changes: 1,154 additions & 1,154 deletions contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py
View file
Open in desktop

Large diffs are not rendered by default.

9 changes: 8 additions & 1 deletion doc/schemas/listpays.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"rpc": "listpays",
"title": "Command for querying payment status",
"description": [
"The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if either *bolt11* or *payment_hash* was specified."
"The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if *bolt11*, *payment_hash* or *label* was specified."
],
"categories": [
"readonly"
Expand Down Expand Up @@ -63,6 +63,13 @@
"NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered",
"NOTE: the actual number returned may be less than the limit, as individual payment parts are combined together"
]
},
"label": {
"type": "string",
"added": "v26.09",
"description": [
"Limits results to payments with this label (as given to pay or sendpay). Cannot be used with *bolt11* or *payment_hash*."
]
}
}
},
Expand Down
9 changes: 8 additions & 1 deletion doc/schemas/listsendpays.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"rpc": "listsendpays",
"title": "Low-level command for querying sendpay status",
"description": [
"The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11* or *payment_hash* limits results to that specific payment. You cannot specify both. It is possible to filter the payments also by *status*.",
"The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11*, *payment_hash* or *label* limits results to that specific payment. You can only specify one of them. It is possible to filter the payments also by *status*.",
"",
"Note that there may be more than one concurrent *sendpay* command per *pay*, so this command should be used with caution."
],
Expand Down Expand Up @@ -62,6 +62,13 @@
"description": [
"If `index` is specified, `limit` can be used to specify the maximum number of entries to return."
]
},
"label": {
"type": "string",
"added": "v26.09",
"description": [
"Limits results to payments with this label (as given to sendpay). Cannot be used with *bolt11* or *payment_hash*."
]
}
},
"dependentUpon": {
Expand Down
13 changes: 9 additions & 4 deletions lightningd/pay.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2211,6 +2211,7 @@ static struct command_result *json_listsendpays(struct command *cmd,
struct json_stream *response;
struct sha256 *rhash;
const char *invstring;
struct json_escape *label;
enum payment_status *status;
struct db_stmt *stmt;
enum wait_index *listindex;
Expand All @@ -2225,13 +2226,15 @@ static struct command_result *json_listsendpays(struct command *cmd,
p_opt("index", param_index, &listindex),
p_opt_def("start", param_u64, &liststart, 0),
p_opt("limit", param_u32, &listlimit),
p_opt("label", param_label, &label),
NULL))
return command_param_failed();

if (rhash && invstring) {
if ((rhash != NULL) + (invstring != NULL) + (label != NULL) > 1) {
return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
"Can only specify one of"
" {bolt11} or {payment_hash}");
" {bolt11}, {payment_hash}"
" or {label}");
}

if (*liststart != 0 && !listindex) {
Expand All @@ -2243,9 +2246,9 @@ static struct command_result *json_listsendpays(struct command *cmd,
"Can only specify {limit} with {index}");
}

if ((rhash || invstring) && *liststart != 0) {
if ((rhash || invstring || label) && *liststart != 0) {
return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
"Cannot use start with bolt11 or payment_hash");
"Cannot use start with bolt11, payment_hash or label");
}

if (invstring) {
Expand Down Expand Up @@ -2278,6 +2281,8 @@ static struct command_result *json_listsendpays(struct command *cmd,
json_array_start(response, "payments");
if (rhash)
stmt = payments_by_hash(cmd->ld->wallet, rhash);
else if (label)
stmt = payments_by_label(cmd->ld->wallet, label);
else if (status)
stmt = payments_by_status(cmd->ld->wallet, *status,
listindex, *liststart, listlimit);
Expand Down
6 changes: 5 additions & 1 deletion plugins/xpay/listpays.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,7 +340,7 @@ struct command_result *json_listpays(struct command *cmd,
const char *buf,
const jsmntok_t *params)
{
const char *invstring, *status_str;
const char *invstring, *status_str, *label;
struct sha256 *payment_hash;
struct out_req *req;
const char *listindex;
Expand All @@ -356,6 +356,7 @@ struct command_result *json_listpays(struct command *cmd,
p_opt("index", param_string, &listindex),
p_opt_def("start", param_u64, &liststart, 0),
p_opt("limit", param_u32, &listlimit),
p_opt("label", param_string, &label),
NULL))
return command_param_failed();

Expand All @@ -380,6 +381,9 @@ struct command_result *json_listpays(struct command *cmd,
if (status_str)
json_add_string(req->js, "status", status_str);

if (label)
json_add_string(req->js, "label", label);

if (listindex){
json_add_string(req->js, "index", listindex);
if (liststart)
Expand Down
12 changes: 12 additions & 0 deletions tests/test_pay.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,18 @@ def test_pay_optional_args(node_factory):
# Should see 3 completed transactions
assert len(l1.rpc.listsendpays()['payments']) == 3

# Can filter by label.
assert len(l1.rpc.listsendpays(label='desc')['payments']) == 2
assert l1.rpc.listsendpays(label='no-such-label')['payments'] == []
pays = l1.rpc.listpays(label='desc')['pays']
assert len(pays) == 2
assert all(p['label'] == 'desc' for p in pays)
assert l1.rpc.listpays(label='no-such-label')['pays'] == []

# But not by label and bolt11/payment_hash at the same time.
with pytest.raises(RpcError, match=r'Can only specify one of'):
l1.rpc.listsendpays(bolt11=inv1, label='desc')


@pytest.mark.openchannel('v1')
@pytest.mark.openchannel('v2')
Expand Down
Loading