API: txprepare for multiple outputs

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- JSON API: `txprepare` now uses `outputs` as parameter other than `destination` and `satoshi`
+
 ### Deprecated
 
 Note: You should always set `allow-deprecated-apis=false` to test for

bitcoin/tx.c

@@ -30,6 +30,16 @@ int bitcoin_tx_add_output(struct bitcoin_tx *tx, const u8 *script,
 	return i;
 }
 
+int bitcoin_tx_add_multi_outputs(struct bitcoin_tx *tx,
+				 struct bitcoin_tx_output **outputs)
+{
+	for (size_t j = 0; j < tal_count(outputs); j++)
+		bitcoin_tx_add_output(tx, outputs[j]->script,
+				      outputs[j]->amount);
+
+	return tx->wtx->num_outputs;
+}
+
 int bitcoin_tx_add_input(struct bitcoin_tx *tx, const struct bitcoin_txid *txid,
 			 u32 outnum, u32 sequence,
 			 struct amount_sat amount, u8 *script)

bitcoin/tx.h

@@ -74,10 +74,14 @@ bool bitcoin_txid_to_hex(const struct bitcoin_txid *txid,
 /* Internal de-linearization functions. */
 struct bitcoin_tx *pull_bitcoin_tx(const tal_t *ctx,
 				   const u8 **cursor, size_t *max);
-
+/* Add one output to tx. */
 int bitcoin_tx_add_output(struct bitcoin_tx *tx, const u8 *script,
 			  struct amount_sat amount);
 
+/* Add mutiple output to tx. */
+int bitcoin_tx_add_multi_outputs(struct bitcoin_tx *tx,
+				 struct bitcoin_tx_output **outputs);
+
 int bitcoin_tx_add_input(struct bitcoin_tx *tx, const struct bitcoin_txid *txid,
 			 u32 outnum, u32 sequence,
 			 struct amount_sat amount, u8 *script);

common/funding_tx.c

@@ -26,7 +26,7 @@ struct bitcoin_tx *funding_tx(const tal_t *ctx,
 	struct bitcoin_tx *tx;
 	bool has_change = !amount_sat_eq(change, AMOUNT_SAT(0));
 
-	tx = tx_spending_utxos(ctx, chainparams, utxomap, bip32_base, has_change);
+	tx = tx_spending_utxos(ctx, chainparams, utxomap, bip32_base, has_change, 1);
 
 
 	wscript = bitcoin_redeem_2of2(tx, local_fundingkey, remote_fundingkey);

common/json_helpers.c

@@ -60,6 +60,16 @@ bool json_to_sat(const char *buffer, const jsmntok_t *tok,
 	return parse_amount_sat(sat, buffer + tok->start, tok->end - tok->start);
 }
 
+bool json_to_sat_or_all(const char *buffer, const jsmntok_t *tok,
+			struct amount_sat *sat)
+{
+	if (json_tok_streq(buffer, tok, "all")) {
+		*sat = AMOUNT_SAT(-1ULL);
+		return true;
+	}
+	return json_to_sat(buffer, tok, sat);
+}
+
 bool json_to_short_channel_id(const char *buffer, const jsmntok_t *tok,
 			      struct short_channel_id *scid,
 			      bool may_be_deprecated_form)

common/json_helpers.h

@@ -32,6 +32,11 @@ bool json_to_short_channel_id(const char *buffer, const jsmntok_t *tok,
 bool json_to_sat(const char *buffer, const jsmntok_t *tok,
 		 struct amount_sat *sat);
 
+/* Extract a satoshis amount from this */
+/* If the string is "all", set amonut as AMOUNT_SAT(-1ULL). */
+bool json_to_sat_or_all(const char *buffer, const jsmntok_t *tok,
+			struct amount_sat *sat);
+
 /* Extract a millisatoshis amount from this */
 bool json_to_msat(const char *buffer, const jsmntok_t *tok,
 		  struct amount_msat *msat);

common/json_tok.c

@@ -183,7 +183,19 @@ struct command_result *param_sat(struct command *cmd, const char *name,
 		return NULL;
 
 	return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
-			    "'%s' should be a satoshi amount, not '%.*s'",
-			    name, tok->end - tok->start, buffer + tok->start);
+			    "%s should be a satoshi amount, not '%.*s'",
+			    name ? name : "amount field",
+			    tok->end - tok->start, buffer + tok->start);
 }
 
+struct command_result *param_sat_or_all(struct command *cmd, const char *name,
+					const char *buffer, const jsmntok_t *tok,
+					struct amount_sat **sat)
+{
+	if (json_tok_streq(buffer, tok, "all")) {
+		*sat = tal(cmd, struct amount_sat);
+		**sat = AMOUNT_SAT(-1ULL);
+		return NULL;
+	}
+	return param_sat(cmd, name, buffer, tok, sat);
+}

common/json_tok.h

@@ -74,6 +74,12 @@ struct command_result *param_sat(struct command *cmd, const char *name,
 				 const char *buffer, const jsmntok_t *tok,
 				 struct amount_sat **sat);
 
+/* Extract satoshi amount from this string. */
+/* If the string is "all", set amonut as AMOUNT_SAT(-1ULL). */
+struct command_result *param_sat_or_all(struct command *cmd, const char *name,
+					const char *buffer, const jsmntok_t *tok,
+					struct amount_sat **sat);
+
 /*
  * Set the address of @out to @tok.  Used as a callback by handlers that
  * want to unmarshal @tok themselves.

common/utxo.c

@@ -1,3 +1,4 @@
+#include <assert.h>
 #include <bitcoin/script.h>
 #include <common/key_derive.h>
 #include <common/utils.h>
@@ -52,11 +53,14 @@ struct bitcoin_tx *tx_spending_utxos(const tal_t *ctx,
 				     const struct chainparams *chainparams,
 				     const struct utxo **utxos,
 				     const struct ext_key *bip32_base,
-				     bool add_change_output)
+				     bool add_change_output,
+				     size_t num_output)
 {
 	struct pubkey key;
 	u8 *script;
-	size_t outcount = add_change_output ? 2 : 1;
+
+	assert(num_output);
+	size_t outcount = add_change_output ? 1 + num_output : num_output;
 	struct bitcoin_tx *tx = bitcoin_tx(ctx, chainparams, tal_count(utxos), outcount);
 
 	for (size_t i = 0; i < tal_count(utxos); i++) {

common/utxo.h

@@ -50,6 +50,7 @@ struct bitcoin_tx *tx_spending_utxos(const tal_t *ctx,
 				     const struct chainparams *chainparams,
 				     const struct utxo **utxos,
 				     const struct ext_key *bip32_base,
-				     bool add_change_output);
+				     bool add_change_output,
+				     size_t num_output);
 
 #endif /* LIGHTNING_COMMON_UTXO_H */

common/withdraw_tx.c

@@ -4,15 +4,15 @@
 #include <bitcoin/script.h>
 #include <ccan/ptrint/ptrint.h>
 #include <common/permute_tx.h>
+#include <common/utils.h>
 #include <common/utxo.h>
 #include <string.h>
 #include <wally_bip32.h>
 
 struct bitcoin_tx *withdraw_tx(const tal_t *ctx,
 			       const struct chainparams *chainparams,
 			       const struct utxo **utxos,
-			       const u8 *destination,
-			       struct amount_sat withdraw_amount,
+			       struct bitcoin_tx_output **outputs,
 			       const struct pubkey *changekey,
 			       struct amount_sat change,
 			       const struct ext_key *bip32_base,
@@ -21,15 +21,16 @@ struct bitcoin_tx *withdraw_tx(const tal_t *ctx,
 	struct bitcoin_tx *tx;
 
 	tx = tx_spending_utxos(ctx, chainparams, utxos, bip32_base,
-			       !amount_sat_eq(change, AMOUNT_SAT(0)));
+			       !amount_sat_eq(change, AMOUNT_SAT(0)),
+			       tal_count(outputs));
 
-	bitcoin_tx_add_output(tx, destination, withdraw_amount);
+	bitcoin_tx_add_multi_outputs(tx, outputs);
 
 	if (!amount_sat_eq(change, AMOUNT_SAT(0))) {
 		const void *map[2];
 		map[0] = int2ptr(0);
 		map[1] = int2ptr(1);
-		bitcoin_tx_add_output(tx, scriptpubkey_p2wpkh(tx, changekey),
+		bitcoin_tx_add_output(tx, scriptpubkey_p2wpkh(tmpctx, changekey),
 				      change);
 		permute_outputs(tx, NULL, map);
 		if (change_outnum)

common/withdraw_tx.h

@@ -2,6 +2,7 @@
 #define LIGHTNING_COMMON_WITHDRAW_TX_H
 #include "config.h"
 #include <bitcoin/chainparams.h>
+#include <bitcoin/tx.h>
 #include <ccan/short_types/short_types.h>
 #include <ccan/tal/tal.h>
 #include <common/amount.h>
@@ -19,8 +20,7 @@ struct utxo;
  * @ctx: context to tal from.
  * @chainparams: (in) the params for the created transaction.
  * @utxos: (in/out) tal_arr of UTXO pointers to spend (permuted to match)
- * @destination: (in) tal_arr of u8, scriptPubKey to send to.
- * @amount: (in) satoshis to send to the destination
+ * @outputs: (in) tal_arr of bitcoin_tx_output, scriptPubKeys with amount to send to.
  * @changekey: (in) key to send change to (only used if change_satoshis != 0).
  * @change: (in) amount to send as change.
  * @bip32_base: (in) bip32 base for key derivation, or NULL.
@@ -29,8 +29,7 @@ struct utxo;
 struct bitcoin_tx *withdraw_tx(const tal_t *ctx,
 			       const struct chainparams *chainparams,
 			       const struct utxo **utxos,
-			       const u8 *destination,
-			       struct amount_sat withdraw_amount,
+			       struct bitcoin_tx_output **outputs,
 			       const struct pubkey *changekey,
 			       struct amount_sat change,
 			       const struct ext_key *bip32_base,

contrib/pylightning/lightning/lightning.py

@@ -875,18 +875,18 @@ def withdraw(self, destination, satoshi, feerate=None, minconf=None):
         }
         return self.call("withdraw", payload)
 
-    def txprepare(self, destination, satoshi, feerate=None, minconf=None):
+    def txprepare(self, outputs, feerate=None, minconf=None):
         """
-        Prepare a bitcoin transaction which sends to {destination} address
-        {satoshi} (or "all") amount via Bitcoin transaction. Only select outputs
-        with {minconf} confirmations.
+        Prepare a bitcoin transaction which sends to [outputs].
+        The format of output is like [{address1: amount1},
+        {address2: amount2}], or [{address: "all"}]).
+        Only select outputs with {minconf} confirmations.
 
         Outputs will be reserved until you call txdiscard or txsend, or
         lightningd restarts.
         """
         payload = {
-            "destination": destination,
-            "satoshi": satoshi,
+            "outputs": outputs,
             "feerate": feerate,
             "minconf": minconf,
         }

doc/lightning-txprepare.7

@@ -7,17 +7,33 @@ internal wallet\.
 
 .SH SYNOPSIS
 
-\fBtxprepare\fR \fIdestination\fR \fIsatoshi\fR [\fIfeerate\fR] [\fIminconf\fR]
+\fBtxprepare\fR \fIoutputs\fR [\fIfeerate\fR] [\fIminconf\fR]
 
 .SH DESCRIPTION
 
 The \fBtxprepare\fR RPC command creates an unsigned transaction which
-spends funds from c-lightning’s internal wallet to the address specified
-in \fIdestination\fR\.
-
-
-Effectively, it is the first part of a \fBwithdraw\fR command, and uses
-the same parameters\. The second part is provided by \fBtxsend\fR\.
+spends funds from c-lightning’s internal wallet to the outputs specified
+in \fIoutputs\fR\.
+
+The \fIoutputs\fR is the array of output that include \fIdestination\fR
+and \fIamount\fR({\fIdestination\fR: \fIamount\fR})\. Its format is like:
+[{address1: amount1}, {address2: amount2}]
+or
+[{address: \fIall\fR}]\.
+It supports the any number of outputs\.
+
+The \fIdestination\fR of output is the address which can be of any Bitcoin accepted
+type, including bech32\.
+
+The \fIamount\fR of output is the amount to be sent from the internal wallet
+(expressed, as name suggests, in amount)\. The string \fIall\fR can be used to specify
+all available funds\. Otherwise, it is in amount precision; it can be a whole
+number, a whole number ending in \fIsat\fR, a whole number ending in \fI000msat\fR,
+or a number with 1 to 8 decimal places ending in \fI000msat\fR\.
+
+\fBtxprepare\fR is similar to the first part of a \fBwithdraw\fR command, but
+supports multiple outputs and uses \fIoutputs\fR as parameter\. The second part
+is provided by \fBtxsend\fR\.
 
 .SH RETURN VALUE
 

doc/lightning-txprepare.7.md

@@ -6,17 +6,34 @@ internal wallet.
 SYNOPSIS
 --------
 
-**txprepare** *destination* *satoshi* \[*feerate*\] \[*minconf*\]
+**txprepare** *outputs* \[*feerate*\] \[*minconf*\]
 
 DESCRIPTION
 -----------
 
 The **txprepare** RPC command creates an unsigned transaction which
-spends funds from c-lightning’s internal wallet to the address specified
-in *destination*.
-
-Effectively, it is the first part of a **withdraw** command, and uses
-the same parameters. The second part is provided by **txsend**.
+spends funds from c-lightning’s internal wallet to the outputs specified
+in *outputs*.
+
+The *outputs* is the array of output that include *destination*
+and *amount*(\{*destination*: *amount*\}). Its format is like:
+\[\{address1: amount1\}, \{address2: amount2\}\]
+or
+\[\{address: *all*\}\].
+It supports the any number of outputs.
+
+The *destination* of output is the address which can be of any Bitcoin accepted
+type, including bech32.
+
+The *amount* of output is the amount to be sent from the internal wallet
+(expressed, as name suggests, in amount). The string *all* can be used to specify
+all available funds. Otherwise, it is in amount precision; it can be a whole
+number, a whole number ending in *sat*, a whole number ending in *000msat*,
+or a number with 1 to 8 decimal places ending in *btc*.
+
+**txprepare** is similar to the first part of a **withdraw** command, but
+supports multiple outputs and uses *outputs* as parameter. The second part
+is provided by **txsend**.
 
 RETURN VALUE
 ------------

hsmd/hsm_wire.csv

@@ -69,8 +69,8 @@ msgtype,hsm_sign_withdrawal,7
 msgdata,hsm_sign_withdrawal,satoshi_out,amount_sat,
 msgdata,hsm_sign_withdrawal,change_out,amount_sat,
 msgdata,hsm_sign_withdrawal,change_keyindex,u32,
-msgdata,hsm_sign_withdrawal,scriptpubkey_len,u16,
-msgdata,hsm_sign_withdrawal,scriptpubkey,u8,scriptpubkey_len
+msgdata,hsm_sign_withdrawal,num_outputs,u16,
+msgdata,hsm_sign_withdrawal,outputs,bitcoin_tx_output,num_outputs
 msgdata,hsm_sign_withdrawal,num_inputs,u16,
 msgdata,hsm_sign_withdrawal,inputs,utxo,num_inputs
 

hsmd/hsmd.c

@@ -1514,20 +1514,20 @@ static struct io_plan *handle_sign_withdrawal_tx(struct io_conn *conn,
 	struct utxo **utxos;
 	struct bitcoin_tx *tx;
 	struct pubkey changekey;
-	u8 *scriptpubkey;
+	struct bitcoin_tx_output **outputs;
 
 	if (!fromwire_hsm_sign_withdrawal(tmpctx, msg_in, &satoshi_out,
 					  &change_out, &change_keyindex,
-					  &scriptpubkey, &utxos))
+					  &outputs, &utxos))
 		return bad_req(conn, c, msg_in);
 
 	if (!bip32_pubkey(&secretstuff.bip32, &changekey, change_keyindex))
 		return bad_req_fmt(conn, c, msg_in,
 				   "Failed to get key %u", change_keyindex);
 
 	tx = withdraw_tx(tmpctx, c->chainparams,
-			 cast_const2(const struct utxo **, utxos), scriptpubkey,
-			 satoshi_out, &changekey, change_out, NULL, NULL);
+			 cast_const2(const struct utxo **, utxos), outputs,
+			 &changekey, change_out, NULL, NULL);
 
 	sign_all_inputs(tx, utxos);