2020-08-08 16:47:53 +01:00
lightning-delpay -- Command for removing a completed or failed payment
============================================================
SYNOPSIS
--------
2022-09-19 01:54:26 +01:00
**delpay** *payment\_hash* *status* [*partid* *groupid* ]
2020-08-08 16:47:53 +01:00
DESCRIPTION
-----------
delpay: delete the payment by status from the db
There are cases (difficult to reproduce with a test) where
a payment will fail one time and succeed later.
As far I understand in this case the groupid field of the payment
is the same, and the only thing that change is the status, so
our logic inside the delpay is ambiguous where it is not
possible to delete a payment as described in https://github.com/ElementsProject/lightning/issues/6114
A sequence of commands that explain the problem is
```
$ lc -k listpays payment_hash=H
{
"pays": [
{
"bolt11": "I",
"destination": "redacted",
"payment_hash": "H",
"status": "complete",
"created_at": redacted,
"completed_at": redacted,
"preimage": "P",
"amount_msat": "redacted",
"amount_sent_msat": "redacted"
}
]
}
$ lc delpay H complete
{
"code": 211,
"message": "Payment with hash H has failed status but it should be complete"
}
```
In this case, the delpay is not able to delete a payment because the
listpays is returning only the succeeded one, so by running the
listsendpays we may see the following result where our delpay logic
will be stuck because it works to ensure that all the payments stored
in the database has the status specified by the user
```
➜ VincentSSD clightning --testnet listsendpays -k payment_hash=7fc74bedbb78f2f3330155d919a54e730cf19c11bc73e96c027f5cd4a34e53f4
{
"payments": [
{
"id": 322,
"payment_hash": "7fc74bedbb78f2f3330155d919a54e730cf19c11bc73e96c027f5cd4a34e53f4",
"groupid": 1,
"partid": 1,
"destination": "030b686a163aa2bba03cebb8bab7778fac251536498141df0a436d688352d426f6",
"amount_msat": 300,
"amount_sent_msat": 1664,
"created_at": 1679510203,
"completed_at": 1679510205,
"status": "failed",
"bolt11": "lntb1pjpkj4xsp52trda39rfpe7qtqahx8jjplhnj3tatxy8rh6sc6afgvmdz7n0llspp50lr5hmdm0re0xvcp2hv3nf2wwvx0r8q3h3e7jmqz0awdfg6w206qdp0w3jhxarfdenjqargv5sxgetvwpshjgrzw4njqun9wphhyaqxqyjw5qcqp2rzjqtp28uqy77te96ylt7ek703h4ayldljsf8rnlztgf3p8mg7pd0qzwf8a3yqqpdqqqyqqqqt2qqqqqqgqqc9qxpqysgqgeya2lguaj6sflc4hx2d89jvah8mw9uax4j77d8rzkut3rkm0554x37fc7gy92ws9l76yprdva2lalrs7fqjp9lcx40zuty8gca0g5spme3dup"
},
{
"id": 323,
"payment_hash": "7fc74bedbb78f2f3330155d919a54e730cf19c11bc73e96c027f5cd4a34e53f4",
"groupid": 1,
"partid": 2,
"destination": "030b686a163aa2bba03cebb8bab7778fac251536498141df0a436d688352d426f6",
"amount_msat": 300,
"amount_sent_msat": 3663,
"created_at": 1679510205,
"completed_at": 1679510207,
"status": "failed"
},
{
"id": 324,
"payment_hash": "7fc74bedbb78f2f3330155d919a54e730cf19c11bc73e96c027f5cd4a34e53f4",
"groupid": 1,
"partid": 3,
"destination": "030b686a163aa2bba03cebb8bab7778fac251536498141df0a436d688352d426f6",
"amount_msat": 300,
"amount_sent_msat": 3663,
"created_at": 1679510207,
"completed_at": 1679510209,
"status": "failed"
},
{
"id": 325,
"payment_hash": "7fc74bedbb78f2f3330155d919a54e730cf19c11bc73e96c027f5cd4a34e53f4",
"groupid": 1,
"partid": 4,
"destination": "030b686a163aa2bba03cebb8bab7778fac251536498141df0a436d688352d426f6",
"amount_msat": 300,
"amount_sent_msat": 4663,
"created_at": 1679510209,
"completed_at": 1679510221,
"status": "complete",
"payment_preimage": "43f746f2d28d4902489cbde9b3b8f3d04db5db7e973f8a55b7229ce774bf33a7"
}
]
}
```
This commit solves the problem by forcing the delete query in the
database to specify status too, and work around this kind of
ambiguous case.
Fixes: f52ff07558709bd1f7ed0cdca65c891d80b1a785 (lightningd: allow delpay to delete a specific payment.)
Reported-by: Antoine Poinsot <darosior@protonmail.com>
Link: https://github.com/ElementsProject/lightning/issues/6114
Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
Co-Developed-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Fixed: delpay be more pedantic about delete logic by allowing
delete payments by status directly on the database.
2023-03-22 19:22:25 +00:00
The **delpay** RPC command deletes a payment with the given `payment_hash` if its status is either `complete` or `failed` . Deleting a `pending` payment is an error. If *partid* and *groupid* are not specified, all payment parts with matchin status are deleted.
2020-08-08 16:47:53 +01:00
2020-08-19 11:38:50 +01:00
- *payment\_hash*: The unique identifier of a payment.
2022-12-09 07:10:12 +00:00
- *status*: Expected status of the payment.
2022-09-19 01:54:26 +01:00
- *partid*: Specific partid to delete (must be paired with *groupid* )
- *groupid*: Specific groupid to delete (must be paired with *partid* )
2020-08-19 11:38:50 +01:00
Only deletes if the payment status matches.
2020-08-08 16:47:53 +01:00
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
"method": "delpay",
"params": {
"payment_hash": "4fa2f1b001067ec06d7f95b8695b8acd9ef04c1b4d1110e3b94e1fa0687bb1e0",
"status": "complete"
}
}
```
RETURN VALUE
------------
2021-05-26 06:55:01 +01:00
The returned format is the same as lightning-listsendpays(7). If the
payment is a multi-part payment (MPP) the command return a list of
payments will be returned -- one payment object for each partid.
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **payments** is returned. It is an array of objects, where each object contains:
2022-09-05 22:33:09 +01:00
2021-05-26 06:55:01 +01:00
- **id** (u64): unique ID for this payment attempt
2023-01-30 06:24:17 +00:00
- **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
2021-05-26 06:55:01 +01:00
- **status** (string): status of the payment (one of "pending", "failed", "complete")
2022-09-05 22:45:06 +01:00
- **amount\_sent\_msat** (msat): the amount we actually sent, including fees
- **created\_at** (u64): the UNIX timestamp showing when this payment was initiated
2021-05-26 06:55:01 +01:00
- **partid** (u64, optional): unique ID within this (multi-part) payment
- **destination** (pubkey, optional): the final destination of the payment if known
2022-09-05 22:45:06 +01:00
- **amount\_msat** (msat, optional): the amount the destination received, if known
2022-06-09 17:36:00 +01:00
- **completed\_at** (u64, optional): the UNIX timestamp showing when this payment was completed
2022-11-11 02:03:13 +00:00
- **groupid** (u64, optional): Grouping key to disambiguate multiple attempts to pay an invoice or the same payment\_hash
2023-01-30 06:24:17 +00:00
- **payment\_preimage** (secret, optional): proof of payment
2021-05-26 06:55:01 +01:00
- **label** (string, optional): the label, if given to sendpay
- **bolt11** (string, optional): the bolt11 string (if pay supplied one)
- **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
- **erroronion** (hex, optional): the error onion returned on failure, if any.
2021-09-03 11:07:59 +01:00
2021-05-26 06:55:01 +01:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
2020-08-08 16:47:53 +01:00
2020-08-19 11:38:50 +01:00
On failure, an error is returned. If the lightning process fails before responding, the
2020-08-08 16:47:53 +01:00
caller should use lightning-listsentpays(7) or lightning-listpays(7) to query whether this payment was deleted or not.
The following error codes may occur:
2020-08-19 11:38:50 +01:00
- -32602: Parameter missed or malformed;
- 211: Payment status mismatch. Check the correct status via **paystatus** ;
2020-08-08 16:47:53 +01:00
- 208: Payment with payment\_hash not found.
EXAMPLE JSON RESPONSE
-----
```json
{
"payments": [
{
"id": 2,
"payment_hash": "8dfd6538eeb33811c9114a75f792a143728d7f05643f38c3d574d3097e8910c0",
"destination": "0219f8900ee78a89f050c24d8b69492954f9fdbabed753710845eb75d3a75a5880",
"msatoshi": 1000,
"amount_msat": "1000msat",
"msatoshi_sent": 1000,
"amount_sent_msat": "1000msat",
"created_at": 1596224858,
"status": "complete",
"payment_preimage": "35bd4e2b481a1a84a22215b5372672cf81460a671816960ddb206464359e1822",
"bolt11": "lntb10n1p0jga20pp53h7k2w8wkvuprjg3ff6l0y4pgdeg6lc9vsln3s74wnfsjl5fzrqqdqdw3jhxazldahx2xqyjw5qcqp2sp5wut5jnhr6n7jd5747ky2g5flmw7hgx9yjnqzu60ps2jf6f7tc0us9qy9qsqu2a0k37nckl62005p69xavlkydkvhnypk4dphffy4x09zltwh9437ad7xkl83tefdarzhu5t30ju5s56wlrg97qkx404pq3srfc425cq3ke9af"
}
]
}
```
AUTHOR
------
Vincenzo Palazzo < < vincenzo.palazzo @ protonmail . com > > is mainly responsible.
SEE ALSO
--------
lightning-listpays(7), lightning-listsendpays(7), lightning-paystatus(7).
RESOURCES
---------
Main web site: < https: / / github . com / ElementsProject / lightning >
2022-12-09 07:10:12 +00:00
2023-01-30 06:24:18 +00:00
[comment]: # ( SHA256STAMP:a7736b0f340fce7c02a7bdfeb2c5321656c490a5046129895d6689c2d82cc431)
