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

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
 

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

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

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

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;",

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,

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 {