df-doc: add docs for openchannel_bump, more checks for valid psbt

Add docs for openchannel_bump, plus some checks that were missed for
verifying the amount is valid.
This commit is contained in:
niftynei 2021-03-10 22:33:47 -06:00 committed by Rusty Russell
parent a648ec827a
commit fc9e72b62b
15 changed files with 251 additions and 34 deletions

View file

@ -49,6 +49,7 @@ MANPAGES := doc/lightning-cli.1 \
doc/lightning-notifications.7 \
doc/lightning-offer.7 \
doc/lightning-offerout.7 \
doc/lightning-openchannel_bump.7 \
doc/lightning-openchannel_init.7 \
doc/lightning-openchannel_signed.7 \
doc/lightning-openchannel_update.7 \

View file

@ -78,6 +78,7 @@ c-lightning Documentation
lightning-notifications <lightning-notifications.7.md>
lightning-offer <lightning-offer.7.md>
lightning-offerout <lightning-offerout.7.md>
lightning-openchannel_bump <lightning-openchannel_bump.7.md>
lightning-openchannel_init <lightning-openchannel_init.7.md>
lightning-openchannel_signed <lightning-openchannel_signed.7.md>
lightning-openchannel_update <lightning-openchannel_update.7.md>

View file

@ -52,11 +52,13 @@ Lisa Neigut \fI<niftynei@gmail.com\fR> is mainly responsible\.
.SH SEE ALSO
\fBlightning-connect\fR(7), \fBlightning-fundchannel\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcancel\fR(7)
\fBlightning-connect\fR(7), \fBlightning-fundchannel\fR(7), \fBlightning-multifundchannel\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcancel\fR(7),
lightning-openchannel_\fBinit\fR(7), lightning-openchannel_\fBupdate\fR(7),
lightning-openchannel_\fBsigned\fR(7), lightning-openchannel_\fBbump\fR(7)
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:74e310642983fa941af1d8cb5b7e0b49d5d14b585fb35f2d192c356ef49af830
\" SHA256STAMP:eea98ffd2086403dd7257878427fa9f3cf4bc9983579d097ee3b65e77760a071

View file

@ -46,8 +46,10 @@ Lisa Neigut <<niftynei@gmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-connect(7), lightning-fundchannel(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_cancel(7)
lightning-connect(7), lightning-fundchannel(7), lightning-multifundchannel(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_cancel(7),
lightning-openchannel\_init(7), lightning-openchannel\_update(7),
lightning-openchannel\_signed(7), lightning-openchannel\_bump(7)
RESOURCES
---------

View file

@ -78,9 +78,11 @@ Lisa Neigut \fI<niftynei@gmail.com\fR> is mainly responsible\.
\fBlightning-connect\fR(7), \fBlightning-fundchannel\fR(7),
lightning-fundchannel_\fBcomplete\fR(7), lightning-fundchannel_\fBcancel\fR(7)
lightning-openchannel_\fBinit\fR(7), lightning-openchannel_\fBupdate\fR(7),
lightning-openchannel_\fBsigned\fR(7), lightning-openchannel_\fBbump\fR(7)
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:8921d89eeebc02d2350608096a8dd0b4108c17f795f1369cdb43bd74d7fb4630
\" SHA256STAMP:6bb2a0765fba65c7c7cac11d34221c6c2ed28fe812f058268cd150cd81719977

View file

@ -66,6 +66,8 @@ SEE ALSO
lightning-connect(7), lightning-fundchannel(7),
lightning-fundchannel\_complete(7), lightning-fundchannel\_cancel(7)
lightning-openchannel\_init(7), lightning-openchannel\_update(7),
lightning-openchannel\_signed(7), lightning-openchannel\_bump(7)
RESOURCES
---------

86
doc/lightning-openchannel_bump.7 generated Normal file
View file

@ -0,0 +1,86 @@
.TH "LIGHTNING-OPENCHANNEL_BUMP" "7" "" "" "lightning-openchannel_bump"
.SH NAME
lightning-openchannel_bump - Command to initiate a channel RBF
.SH SYNOPSIS
\fBopenchannel_bump\fR \fIchannel_id\fR \fIamount\fR \fIinitalpsbt\fR
.SH DESCRIPTION
\fBopenchannel_bump\fR is a RPC command which initiates a channel
RBF (Replace-By-Fee) for the specified channel\. It uses the openchannel protocol
which allows for interactive transaction construction\.
\fIid\fR is the id of the channel to RBF\.
\fIamount\fR is the satoshi value that we will contribute to the channel\.
This value will be \fIadded\fR to the provided PSBT in the output which is
encumbered by the 2-of-2 script for this channel\.
\fIinitialpsbt\fR is the funded, incomplete PSBT that specifies the UTXOs and
change output for our channel contribution\. It can be updated,
see \fBopenchannel_update\fR; \fIinitialpsbt\fR must have at least one input\.
Must have the Non-Witness UTXO (PSBT_IN_NON_WITNESS_UTXO) set for
every input\. An error (code 309) will be returned if this requirement
is not met\.
.SH RETURN VALUE
On success, returns the \fIchannel_id\fR for this channel; an updated
incomplete \fIinitialpsbt\fR for this funding transaction; and the flag
\fIcommitments_secured\fR, which indiciates the completeness of the
passed back \fIpsbt\fR\. (Will always be false)\. Also returns the
\fIfunding_serial\fR, indicating the serial_id of the funding output
in the \fIpsbt\fR\.
If the peer does not support \fBoption_dual_fund\fR, this command
will return an error\.
If the channel is not in a state that is eligible for RBF, this command
will return an error\.
On error the returned object will contain \fBcode\fR and \fBmessage\fR properties,
with \fBcode\fR being one of the following:
.RS
.IP \[bu]
-32602: If the given parameters are wrong\.
.IP \[bu]
-1: Catchall nonspecific error\.
.IP \[bu]
300: The amount exceeded the maximum configured funding amount\.
.IP \[bu]
301: The provided PSBT cannot afford the funding amount\.
.IP \[bu]
305: Peer is not connected\.
.IP \[bu]
309: PSBT missing required fields
.IP \[bu]
311: Unknown channel id\.
.IP \[bu]
312: Channel in an invalid state
.RE
.SH SEE ALSO
lightning-openchannel_\fBinit\fR(7), lightning-openchannel_\fBupdate\fR(7),
lightning-openchannel_\fBsigned\fR(7), lightning-openchannel_\fBabort\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
\fBlightning-fundchannel\fR(7), \fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7),
\fBlightning-multifundchannel\fR(7)
.SH AUTHOR
@niftynei \fI<niftynei@gmail.com\fR> is mainly responsible\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:3a1f4ea363bae832e6c100bfb4a015223c2225d1eb8c0497e71e844df1bb9a99

View file

@ -0,0 +1,74 @@
lightning-openchannel\_bump -- Command to initiate a channel RBF
=====================================================================
SYNOPSIS
--------
**openchannel_bump** *channel_id* *amount* *initalpsbt*
DESCRIPTION
-----------
`openchannel_bump` is a RPC command which initiates a channel
RBF (Replace-By-Fee) for the specified channel. It uses the openchannel protocol
which allows for interactive transaction construction.
*id* is the id of the channel to RBF.
*amount* is the satoshi value that we will contribute to the channel.
This value will be _added_ to the provided PSBT in the output which is
encumbered by the 2-of-2 script for this channel.
*initialpsbt* is the funded, incomplete PSBT that specifies the UTXOs and
change output for our channel contribution. It can be updated,
see `openchannel_update`; *initialpsbt* must have at least one input.
Must have the Non-Witness UTXO (PSBT\_IN\_NON\_WITNESS\_UTXO) set for
every input. An error (code 309) will be returned if this requirement
is not met.
RETURN VALUE
------------
On success, returns the *channel_id* for this channel; an updated
incomplete *initialpsbt* for this funding transaction; and the flag
*commitments_secured*, which indiciates the completeness of the
passed back *psbt*. (Will always be false). Also returns the
*funding_serial*, indicating the serial\_id of the funding output
in the *psbt*.
If the peer does not support `option_dual_fund`, this command
will return an error.
If the channel is not in a state that is eligible for RBF, this command
will return an error.
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:
- -32602: If the given parameters are wrong.
- -1: Catchall nonspecific error.
- 300: The amount exceeded the maximum configured funding amount.
- 301: The provided PSBT cannot afford the funding amount.
- 305: Peer is not connected.
- 309: PSBT missing required fields
- 311: Unknown channel id.
- 312: Channel in an invalid state
SEE ALSO
--------
lightning-openchannel\_init(7), lightning-openchannel\_update(7),
lightning-openchannel\_signed(7), lightning-openchannel\_abort(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7),
lightning-fundchannel(7), lightning-fundpsbt(7), lightning-utxopsbt(7),
lightning-multifundchannel(7)
AUTHOR
------
@niftynei <<niftynei@gmail.com>> is mainly responsible.
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>

View file

@ -86,9 +86,9 @@ with \fBcode\fR being one of the following:
.SH SEE ALSO
lightning-openchannel_\fBupdate\fR(7), lightning-openchannel_\fBsigned\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
\fBlightning-fundchannel\fR(7), \fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7),
\fBlightning-multifundchannel\fR(7)
lightning-openchannel_\fBbump\fR(7) lightning-fundchannel_\fBstart\fR(7),
lightning-fundchannel_\fBcomplete\fR(7), \fBlightning-fundchannel\fR(7),
\fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7), \fBlightning-multifundchannel\fR(7)
.SH AUTHOR
@ -98,4 +98,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:d36c10e11609777d0d2523660dab776eb60e739bfadea5db18285cbb002ca91e
\" SHA256STAMP:0db7db257671eb7ea20ee3fafd43ba75902cde08942815e0bb99703114b121e7

View file

@ -70,9 +70,9 @@ SEE ALSO
--------
lightning-openchannel\_update(7), lightning-openchannel\_signed(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7),
lightning-fundchannel(7), lightning-fundpsbt(7), lightning-utxopsbt(7),
lightning-multifundchannel(7)
lightning-openchannel\_bump(7) lightning-fundchannel\_start(7),
lightning-fundchannel\_complete(7), lightning-fundchannel(7),
lightning-fundpsbt(7), lightning-utxopsbt(7), lightning-multifundchannel(7)
AUTHOR
------

View file

@ -56,10 +56,11 @@ with \fBcode\fR being one of the following:
.RE
.SH SEE ALSO
lightning-openchannel_\fBupdate\fR(7), lightning-openchannel_\fBsigned\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
\fBlightning-fundchannel\fR(7), \fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7),
\fBlightning-multifundchannel\fR(7)
=======
lightning-openchannel_\fBinit\fR(7), lightning-openchannel_\fBupdate\fR(7),
lightning-openchannel_\fBbump\fR(7), lightning-fundchannel_\fBstart\fR(7),
lightning-fundchannel_\fBcomplete\fR(7), \fBlightning-fundchannel\fR(7),
\fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7), \fBlightning-multifundchannel\fR(7)
.SH AUTHOR
@ -69,4 +70,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:1b4fe213f82746ac5773903dfef1bb84d5d80a8c9fdbf5dfc4c02ab2d84164a4
\" SHA256STAMP:3004ce5963d892d4828b11d3e5daedb59f780f98485098eba0e46b3e835e759d

View file

@ -46,10 +46,11 @@ with `code` being one of the following:
SEE ALSO
--------
lightning-openchannel\_update(7), lightning-openchannel\_signed(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7),
lightning-fundchannel(7), lightning-fundpsbt(7), lightning-utxopsbt(7),
lightning-multifundchannel(7)
=======
lightning-openchannel\_init(7), lightning-openchannel\_update(7),
lightning-openchannel\_bump(7), lightning-fundchannel\_start(7),
lightning-fundchannel\_complete(7), lightning-fundchannel(7),
lightning-fundpsbt(7), lightning-utxopsbt(7), lightning-multifundchannel(7)
AUTHOR
------

View file

@ -66,10 +66,10 @@ in the funding transaction\.
.RE
.SH SEE ALSO
lightning-openchannel_\fBupdate\fR(7), lightning-openchannel_\fBsigned\fR(7),
lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
\fBlightning-fundchannel\fR(7), \fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7),
\fBlightning-multifundchannel\fR(7)
lightning-openchannel_\fBinit\fR(7), lightning-openchannel_\fBsigned\fR(7),
lightning-openchannel_\fBbump\fR(7), lightning-fundchannel_\fBstart\fR(7),
lightning-fundchannel_\fBcomplete\fR(7), \fBlightning-fundchannel\fR(7),
\fBlightning-fundpsbt\fR(7), \fBlightning-utxopsbt\fR(7), \fBlightning-multifundchannel\fR(7)
.SH AUTHOR
@ -79,4 +79,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7),
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:1da10d582896fe537c439b6a479fc9d8b440a43e6848b21a68b223a0ddaab24b
\" SHA256STAMP:93c15eb807f3ee413ebc1eae0cb10970f23fd63ecdae4d31a2f3dce90b5c0b1a

View file

@ -52,10 +52,10 @@ If *commitments_secured* is true, will also return:
SEE ALSO
--------
lightning-openchannel\_update(7), lightning-openchannel\_signed(7),
lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7),
lightning-fundchannel(7), lightning-fundpsbt(7), lightning-utxopsbt(7),
lightning-multifundchannel(7)
lightning-openchannel\_init(7), lightning-openchannel\_signed(7),
lightning-openchannel\_bump(7), lightning-fundchannel\_start(7),
lightning-fundchannel\_complete(7), lightning-fundchannel(7),
lightning-fundpsbt(7), lightning-utxopsbt(7), lightning-multifundchannel(7)
AUTHOR
------

View file

@ -1880,7 +1880,7 @@ json_openchannel_bump(struct command *cmd,
{
struct channel_id *cid;
struct channel *channel;
struct amount_sat *amount;
struct amount_sat *amount, psbt_val;
struct wally_psbt *psbt;
struct open_attempt *oa;
@ -1891,6 +1891,36 @@ json_openchannel_bump(struct command *cmd,
NULL))
return command_param_failed();
psbt_val = AMOUNT_SAT(0);
for (size_t i = 0; i < psbt->num_inputs; i++) {
struct amount_sat in_amt = psbt_input_get_amount(psbt, i);
if (!amount_sat_add(&psbt_val, psbt_val, in_amt))
return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
"Overflow in adding PSBT input"
" values. %s",
type_to_string(tmpctx,
struct wally_psbt,
psbt));
}
/* If they don't pass in at least enough in the PSBT to cover
* their amount, nope */
if (!amount_sat_greater(psbt_val, *amount))
return command_fail(cmd, FUND_CANNOT_AFFORD,
"Provided PSBT cannot afford funding of "
"amount %s. %s",
type_to_string(tmpctx,
struct amount_sat,
amount),
type_to_string(tmpctx,
struct wally_psbt,
psbt));
if (!topology_synced(cmd->ld->topology)) {
return command_fail(cmd, FUNDING_STILL_SYNCING_BITCOIN,
"Still syncing with bitcoin network");
}
/* Are we in a state where we can attempt an RBF? */
channel = channel_by_cid(cmd->ld, cid);
if (!channel)
@ -1899,12 +1929,27 @@ json_openchannel_bump(struct command *cmd,
type_to_string(tmpctx, struct channel_id,
cid));
/* BOLT #2:
* - if both nodes advertised `option_support_large_channel`:
* - MAY set `funding_satoshis` greater than or equal to 2^24 satoshi.
* - otherwise:
* - MUST set `funding_satoshis` to less than 2^24 satoshi.
*/
if (!feature_negotiated(cmd->ld->our_features,
channel->peer->their_features,
OPT_LARGE_CHANNELS)
&& amount_sat_greater(*amount, chainparams->max_funding))
return command_fail(cmd, FUND_MAX_EXCEEDED,
"Amount exceeded %s",
type_to_string(tmpctx, struct amount_sat,
&chainparams->max_funding));
if (!channel->owner)
return command_fail(cmd, LIGHTNINGD,
return command_fail(cmd, FUNDING_PEER_NOT_CONNECTED,
"Peer not connected.");
if (channel->open_attempt)
return command_fail(cmd, LIGHTNINGD,
return command_fail(cmd, FUNDING_STATE_INVALID,
"Commitments for this channel not "
"secured, see `openchannel_update`");