From 919f390a93ccd6d65bfc46d6995bfcaed44003aa Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Sat, 23 Feb 2019 13:41:14 +1030 Subject: [PATCH] sendpay: rename 'description' to 'label'. This field was used by `pay` to hold the bolt11 description if the bolt11 string used `h` to hash the description (which nobody ever did). If the `h` field wasn't present, it could contain anything, as it wasn't checked. It's really useful to have a label for payments (eg. '1 Cuban'), but adding yet-another option would be painful, so we simply rename 'description' to 'label' except inside the db. This means we need to do some tricky parameter parsing to handle array and keyword JSON arguments, but only until we remove the old name. Signed-off-by: Rusty Russell --- CHANGELOG.md | 3 ++ doc/lightning-sendpay.7 | 4 +-- doc/lightning-sendpay.7.txt | 4 +-- lightningd/pay.c | 63 +++++++++++++++++++++++++++---------- wallet/db.c | 1 + wallet/wallet.c | 10 +++--- wallet/wallet.h | 4 +-- 7 files changed, 62 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c69beb6bf..429027960 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - pylightning: New class 'Millisatoshi' can be used for JSON API, and new '_msat' fields are turned into this on reading. - 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. ### Changed @@ -38,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - JSON API: `listpeers` now includes `funding_allocation_msat`, which returns a map of the amounts initially funded to the channel by each peer, indexed by channel id. - `option_data_loss_protect` is now enabled by default. - JSON API: `help` with a `command` argument gives a JSON array, like other commands. +- JSON API: `sendpay` `description` parameter is renamed `label`. - build: we'll use the system libbase58 and libsodium if found suitable. ### Deprecated @@ -50,6 +52,7 @@ fields for your own sanity checking, and that you similarly provide appropriate suffixes for JSON input fields. - JSON API: `short_channel_id` fields in JSON commands with `:` separators (use `x` instead). +- JSON API: `sendpay` parameter `description` and `waitsendpay` and `sendpay` output fields `description` (now `label`). ### Removed diff --git a/doc/lightning-sendpay.7 b/doc/lightning-sendpay.7 index d0d3df391..3b1b9e1de 100644 --- a/doc/lightning-sendpay.7 +++ b/doc/lightning-sendpay.7 @@ -31,7 +31,7 @@ lightning-sendpay \- Low\-level command for sending a payment via a route\&. .SH "SYNOPSIS" .sp -\fBsendpay\fR \fIroute\fR \fIpayment_hash\fR [\fIdescription\fR] [\fImsatoshi\fR] [\fIbolt11\fR] +\fBsendpay\fR \fIroute\fR \fIpayment_hash\fR [\fIlabel\fR] [\fImsatoshi\fR] [\fIbolt11\fR] .SH "DESCRIPTION" .sp The \fBsendpay\fR RPC command attempts to send funds associated with the given \fIpayment_hash\fR, along a route to the final destination in the route\&. @@ -40,7 +40,7 @@ Generally, a client would call lightning\-getroute(7) to resolve a route, then u .sp The response will occur when the payment is on its way to the destination\&. The \fBsendpay\fR RPC command does not wait for definite success or definite failure of the payment\&. Instead, use the \fBwaitsendpay\fR RPC command to poll or wait for definite success or definite failure\&. .sp -The \fIdescription\fR and \fIbolt11\fR parameters, if provided, will be returned in \fIwaitsendpay\fR and \fIlistpayments\fR results\&. +The \fIlabel\fR and \fIbolt11\fR parameters, if provided, will be returned in \fIwaitsendpay\fR and \fIlistpayments\fR results\&. .sp The \fImsatoshi\fR amount, if provided, is the amount that will be recorded as the target payment value\&. If not specified, it will be the final amount to the destination\&. If specified, then the final amount at the destination must be from the specified \fImsatoshi\fR to twice the specified \fImsatoshi\fR, inclusive\&. This is intended to obscure payments by overpaying slightly at the destination; the actual target payment is what should be specified as the \fImsatoshi\fR argument\&. \fImsatoshi\fR is in millisatoshi precision; it can be a whole number, or a whole number ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending in \fIsat\fR, or a number with 1 to 11 decimal places ending in \fIbtc\fR\&. .sp diff --git a/doc/lightning-sendpay.7.txt b/doc/lightning-sendpay.7.txt index e83d27abb..72ec862c4 100644 --- a/doc/lightning-sendpay.7.txt +++ b/doc/lightning-sendpay.7.txt @@ -8,7 +8,7 @@ lightning-sendpay - Low-level command for sending a payment via a route. SYNOPSIS -------- -*sendpay* 'route' 'payment_hash' ['description'] ['msatoshi'] ['bolt11'] +*sendpay* 'route' 'payment_hash' ['label'] ['msatoshi'] ['bolt11'] DESCRIPTION ----------- @@ -27,7 +27,7 @@ definite failure of the payment. Instead, use the *waitsendpay* RPC command to poll or wait for definite success or definite failure. -The 'description' and 'bolt11' parameters, if provided, will be returned in +The 'label' and 'bolt11' parameters, if provided, will be returned in 'waitsendpay' and 'listpayments' results. The 'msatoshi' amount, if provided, is the amount that will be diff --git a/lightningd/pay.c b/lightningd/pay.c index 8d18a080a..a3faafbb5 100644 --- a/lightningd/pay.c +++ b/lightningd/pay.c @@ -99,8 +99,11 @@ json_add_payment_fields(struct json_stream *response, json_add_hex(response, "payment_preimage", t->payment_preimage, sizeof(*t->payment_preimage)); - if (t->description) - json_add_string(response, "description", t->description); + if (t->label) { + if (deprecated_apis) + json_add_string(response, "description", t->label); + json_add_string(response, "label", t->label); + } if (t->bolt11) json_add_string(response, "bolt11", t->bolt11); } @@ -582,7 +585,7 @@ send_payment(struct lightningd *ld, const struct sha256 *rhash, const struct route_hop *route, struct amount_msat msat, - const char *description TAKES, + const char *label TAKES, const char *b11str TAKES) { const u8 *onion; @@ -719,10 +722,10 @@ send_payment(struct lightningd *ld, payment->path_secrets = tal_steal(payment, path_secrets); payment->route_nodes = tal_steal(payment, ids); payment->route_channels = tal_steal(payment, channels); - if (description != NULL) - payment->description = tal_strdup(payment, description); + if (label != NULL) + payment->label = tal_strdup(payment, label); else - payment->description = NULL; + payment->label = NULL; if (b11str != NULL) payment->bolt11 = tal_strdup(payment, b11str); else @@ -750,17 +753,45 @@ static struct command_result *json_sendpay(struct command *cmd, struct sha256 *rhash; struct route_hop *route; struct amount_msat *msat; - const char *description, *b11str; + const char *b11str, *label; struct command_result *res; - if (!param(cmd, buffer, params, - p_req("route", param_array, &routetok), - p_req("payment_hash", param_sha256, &rhash), - p_opt("description", param_escaped_string, &description), - p_opt("msatoshi", param_msat, &msat), - p_opt("bolt11", param_string, &b11str), - NULL)) - return command_param_failed(); + /* If by array, or 'check' command, use 'label' as param name */ + if (!params || params->type == JSMN_ARRAY) { + if (!param(cmd, buffer, params, + p_req("route", param_array, &routetok), + p_req("payment_hash", param_sha256, &rhash), + p_opt("label", param_escaped_string, &label), + p_opt("msatoshi", param_msat, &msat), + p_opt("bolt11", param_string, &b11str), + NULL)) + return command_param_failed(); + } else { + const char *description_deprecated; + + /* If by keyword, treat description and label as + * separate parameters. */ + if (!param(cmd, buffer, params, + p_req("route", param_array, &routetok), + p_req("payment_hash", param_sha256, &rhash), + p_opt("label", param_escaped_string, &label), + p_opt("description", param_escaped_string, + &description_deprecated), + p_opt("msatoshi", param_msat, &msat), + p_opt("bolt11", param_string, &b11str), + NULL)) + return command_param_failed(); + + if (description_deprecated) { + if (!deprecated_apis) + return command_fail(cmd, JSONRPC2_INVALID_PARAMS, + "Deprecated parameter description, use label"); + if (label) + return command_fail(cmd, JSONRPC2_INVALID_PARAMS, + "Cannot specify both description and label"); + label = description_deprecated; + } + } if (routetok->size == 0) return command_fail(cmd, JSONRPC2_INVALID_PARAMS, "Empty route"); @@ -844,7 +875,7 @@ static struct command_result *json_sendpay(struct command *cmd, res = send_payment(cmd->ld, cmd, rhash, route, msat ? *msat : route[routetok->size-1].amount, - description, b11str); + label, b11str); if (res) return res; return command_still_pending(cmd); diff --git a/wallet/db.c b/wallet/db.c index 45332c3ec..b9addde3e 100644 --- a/wallet/db.c +++ b/wallet/db.c @@ -334,6 +334,7 @@ char *dbmigrations[] = { "DELETE FROM blocks WHERE height IS NULL;", /* -- End of PR #1398 -- */ "ALTER TABLE invoices ADD description TEXT;", + /* FIXME: payments table 'description' is really a 'label' */ "ALTER TABLE payments ADD description TEXT;", /* future_per_commitment_point if other side proves we're out of date -- */ "ALTER TABLE channels ADD future_per_commitment_point BLOB;", diff --git a/wallet/wallet.c b/wallet/wallet.c index b25652236..0e357ecd7 100644 --- a/wallet/wallet.c +++ b/wallet/wallet.c @@ -1739,9 +1739,9 @@ void wallet_payment_store(struct wallet *wallet, payment->route_channels); sqlite3_bind_amount_msat(stmt, 9, payment->msatoshi_sent); - if (payment->description != NULL) - sqlite3_bind_text(stmt, 10, payment->description, - strlen(payment->description), + if (payment->label != NULL) + sqlite3_bind_text(stmt, 10, payment->label, + strlen(payment->label), SQLITE_TRANSIENT); else sqlite3_bind_null(stmt, 10); @@ -1807,10 +1807,10 @@ static struct wallet_payment *wallet_stmt2payment(const tal_t *ctx, payment->msatoshi_sent = sqlite3_column_amount_msat(stmt, 10); if (sqlite3_column_type(stmt, 11) != SQLITE_NULL) - payment->description = tal_strdup( + payment->label = tal_strdup( payment, (const char *)sqlite3_column_text(stmt, 11)); else - payment->description = NULL; + payment->label = NULL; if (sqlite3_column_type(stmt, 12) != SQLITE_NULL) payment->bolt11 = tal_strdup(payment, diff --git a/wallet/wallet.h b/wallet/wallet.h index 30f45df7b..671a185f2 100644 --- a/wallet/wallet.h +++ b/wallet/wallet.h @@ -227,8 +227,8 @@ struct wallet_payment { /* bolt11 string; NULL for old payments. */ const char *bolt11; - /* The description of the payment. Must support `tal_len` */ - const char *description; + /* The label of the payment. Must support `tal_len` */ + const char *label; }; struct outpoint {