mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-12-29 10:04:41 +01:00
Code Issues Projects Releases Wiki Activity
95f77f119b
core-lightning/doc/lightning-fundpsbt.7.md

111 lines
4.1 KiB
Markdown
Raw Normal View History

doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
lightning-fundpsbt -- Command to populate PSBT inputs from the wallet
================================================================
SYNOPSIS
--------
fund/utxopsbt: flag 'excess_as_change' to add a change output for excess In the case where you want a PSBT and also want the output to be added as a change address, use `excess_as_change` = true. Generates a change address to use. If you want to pay the excess elsewhere, you will have to add separately. Changelog-Added: JSON-RPC: Add new parameter `excess_as_change` to fundpsbt+utxopsbt
2021-02-02 20:43:15 +01:00
**fundpsbt** *satoshi* *feerate* *startweight* \[*minconf*\] \[*reserve*\] \[*locktime*\] \[*min_witness_weight*\] \[*excess_as_change*\]
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
DESCRIPTION
-----------
`fundpsbt` is a low-level RPC command which creates a PSBT using unreserved
inputs in the wallet, optionally reserving them as well.
*satoshi* is the minimum satoshi value of the output(s) needed (or the
string "all" meaning use all unreserved inputs). If a value, 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*.
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
*feerate* can be one of the feerates listed in lightning-feerates(7),
or one of the strings *urgent* (aim for next block), *normal* (next 4
blocks or so) or *slow* (next 100 blocks or so) to use lightningd’s
internal estimates. It can also be a *feerate* is a number, with an
optional suffix: *perkw* means the number is interpreted as
satoshi-per-kilosipa (weight), and *perkb* means it is interpreted
bitcoind-style as satoshi-per-kilobyte. Omitting the suffix is
equivalent to *perkb*.
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
*startweight* is the weight of the transaction before *fundpsbt* has
added any inputs.
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
*minconf* specifies the minimum number of confirmations that used
outputs should have. Default is 1.
*reserve* is a boolean: if true (the default), then *reserveinputs* is
called (successfully, with *exclusive* true) on the returned PSBT.
fundpsbt: let caller specify locktime. Required for dual funding where the opener sets it. Changelog-Added: JSON-RPC: `fundpsbt` takes a new `locktime` parameter Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-08-18 06:24:39 +02:00
*locktime* is an optional locktime: if not set, it is set to a recent
block height.
fundpsbt/utxopsbt: new `min_witness_weight` param Needed for v2 of channel opens, where the minimum weight is 110; a 'simple utxo' (sig + key) weighs in at 107, so we a need a way to establish a floor for this case. Changelog-Added: JSON-RPC: fundpsbt/utxopsbt have new param, `min_witness_utxo`, which sets a floor for the weight calculation of an added input
2020-11-18 02:45:23 +01:00
*min_witness_weight* is an optional minimum weight to use for a UTXO's
witness. If the actual witness weight is greater than the provided minimum,
the actual witness weight will be used.
fund/utxopsbt: flag 'excess_as_change' to add a change output for excess In the case where you want a PSBT and also want the output to be added as a change address, use `excess_as_change` = true. Generates a change address to use. If you want to pay the excess elsewhere, you will have to add separately. Changelog-Added: JSON-RPC: Add new parameter `excess_as_change` to fundpsbt+utxopsbt
2021-02-02 20:43:15 +01:00
*excess_as_change* is an optional boolean to flag to add a change output
for the excess sats.
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
EXAMPLE USAGE
-------------
Let's assume the caller is trying to produce a 100,000 satoshi output.
First, the caller estimates the weight of the core (typically 42) and
known outputs of the transaction (typically (9 + scriptlen) * 4). For
doc: correct weight numbers for fundpsbt
2020-09-14 21:56:17 +02:00
a simple P2WPKH it's a 22 byte scriptpubkey, so that's 124 weight.
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
doc: correct weight numbers for fundpsbt
2020-09-14 21:56:17 +02:00
It calls "*fundpsbt* 100000sat slow 166", which succeeds, and returns
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
the *psbt* and *feerate_per_kw* it used, the *estimated_final_weight*
and any *excess_msat*.
If *excess_msat* is greater than the cost of adding a change output,
the caller adds a change output randomly to position 0 or 1 in the
PSBT. Say *feerate_per_kw* is 253, and the change output is a P2WPKH
doc: correct weight numbers for fundpsbt
2020-09-14 21:56:17 +02:00
(weight 124), the cost is around 31 sats. With the dust limit disallowing
payments below 546 satoshis, we would only create a change output
if *excess_msat* was greater or equal to 31 + 546.
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
RETURN VALUE
------------
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
On success, returns the *psbt* containing the inputs, *feerate_per_kw*
showing the exact numeric feerate it used, *estimated_final_weight* for
the estimated weight of the transaction once fully signed, and
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
*excess_msat* containing the amount above *satoshi* which is
available. This could be zero, or dust. If *satoshi* was "all",
then *excess_msat* is the entire amount once fees are subtracted
fundpsbt: make parameters more usable. fundpsbt forces the caller to manually add their weight * feerate to the satoshis they ask for. That means no named feerates. Instead, create a startweight parameter and do the calc for them internally, and return the feerate we used (and, while we're at it, the estimated final weight). This API change is best done now, as it would otherwise have to be appended as a parameter. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-17 07:45:57 +02:00
for the weights of the inputs and startweight.
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
If *reserve* was true, then a *reservations* array is returned,
exactly like *reserveinputs*.
fund/utxopsbt: flag 'excess_as_change' to add a change output for excess In the case where you want a PSBT and also want the output to be added as a change address, use `excess_as_change` = true. Generates a change address to use. If you want to pay the excess elsewhere, you will have to add separately. Changelog-Added: JSON-RPC: Add new parameter `excess_as_change` to fundpsbt+utxopsbt
2021-02-02 20:43:15 +01:00
If *excess_as_change* is true and the excess is enough to cover
an additional output above the `dust_limit`, then an output is
added to the PSBT for the excess amount. The *excess_msat* will
be zero. A *change_outnum* will be returned with the index of
the change output.
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
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.
- 301: Insufficient UTXOs to meet *satoshi* value.
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
utxopsbt: new command to create PSBT from given utxos. It's *possible* to do this using various RPC calls, but it's unfriendly: 1. Call getinfo to get the current block height. 2. Call listfunds to map the UTXOs. 3. Create the PSBT and hope you get all the fields correct. Instead, this presents an interface just like `fundpsbt`, with identical returns. I think it's different enough to justify a new command (though it shares much internally, of course). In particular, it's now quite simple to create a command which uses specified utxos, and then adds more to meet any shortfall. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-08-18 04:22:53 +02:00
lightning-utxopsbt(7), lightning-reserveinputs(7), lightning-unreserveinputs(7).
doc: document fundpsbt. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-07-15 07:39:47 +02:00
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
doc: force refresh of all manpages. The idea is that you regenerate the man pages in the same commit you alter them: that's how we know whether to try regenerating them or not (git doesn't store timestamps, so it can't really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-08-25 03:33:16 +02:00
Reference in New Issue Copy Permalink