mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 18:11:28 +01:00
Code Issues Projects Releases Wiki Activity
3c3f4731bd
core-lightning/doc/lightning-utxopsbt.7.md

103 lines
4.1 KiB
Markdown
Raw Normal View History

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 -- Command to populate PSBT inputs from given UTXOs
================================================================
SYNOPSIS
--------
Remove useless \
2022-01-26 18:18:49 +01:00
**utxopsbt** *satoshi* *feerate* *startweight* *utxos* [*reserve*] [*reservedok*] [*locktime*] [*min_witness_weight*] [*excess_as_change*]
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
DESCRIPTION
-----------
*utxopsbt* is a low-level RPC command which creates a PSBT using unreserved
inputs in the wallet, optionally reserving them as well.
It deliberately mirrors the parameters and output of
lightning-fundpsbt(7) except instead of an optional *minconf*
parameter to select unreserved outputs from the wallet, it takes a
compulsory list of outputs to use.
*utxos* must be an array of "txid:vout", each of which must be
reserved or available: the total amount must be sufficient to pay for
the resulting transaction plus *startweight* at the given *feerate*,
with at least *satoshi* left over (unless *satoshi* is **all**, which
is equivalent to setting it to zero).
utxopsbt: make default to only allow unreserved utxos. This more closely mirrors fundpsbt (which will only select unreserved ones) but you can turn it off if you want to e.g. rbf in future. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: New low-level command `utxopsbt` to create PSBT from existing utxos.
2020-08-18 04:22:55 +02:00
fundpsbt: deprecate reserve=true/false usage. Make it always a number; this makes the JSON request specification simpler. We allowed a number since v0.10.1. (reserve=True is the default anyway, so usually it can be omitted: reserve=False becomes reserve=0). Changelog-Deprecated: JSON-RPC: `fundpsbt`/`utxopsbt` `reserve` must be a number, not bool (for `true` use 72/don't specify, for `false` use 0). Numbers have been allowed since v0.10.1.
2022-04-01 06:12:45 +02:00
If *reserve* if not zero, then *reserveinputs* is called (successfully, with
*exclusive* true) on the returned PSBT for this number of blocks (default
72 blocks if unspecified).
sendpsbt, fundpsbt, utxopsbt, reserveinputs, unreserveinputs: allow custom number of blocks to reserve. Not an API break: reserve=true|false still works for fundpsbt and utxopsbt, but we also allow a raw number in there. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 03:19:37 +02:00
utxopsbt: make default to only allow unreserved utxos. This more closely mirrors fundpsbt (which will only select unreserved ones) but you can turn it off if you want to e.g. rbf in future. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: New low-level command `utxopsbt` to create PSBT from existing utxos.
2020-08-18 04:22:55 +02:00
Unless *reservedok* is set to true (default is false) it will also fail
if any of the *utxos* are already reserved.
utxopsbt: let caller specify locktime, add tests and python binding. Changelog-Added: JSON-RPC: `utxopsbt` takes a new `locktime` parameter Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-08-18 06:25:52 +02:00
*locktime* is an optional locktime: if not set, it is set to a recent
block height.
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
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.
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
RETURN VALUE
------------
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
- **psbt** (string): Unsigned PSBT which fulfills the parameters given
- **feerate_per_kw** (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight
- **estimated_final_weight** (u32): The estimated weight of the transaction once fully signed
- **excess_msat** (msat): The amount above *satoshi* which is available. This could be zero, or dust; it will be zero if *change_outnum* is also returned
- **change_outnum** (u32, optional): The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds)
- **reservations** (array of objects, optional): If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7):
- **txid** (txid): The txid of the transaction
- **vout** (u32): The 0-based output number
- **was_reserved** (boolean): Whether this output was previously reserved
- **reserved** (boolean): Whether this output is now reserved (always *true*)
- **reserved_to_block** (u32): The blockheight the reservation will expire
doc: fix GH/readthedocs rendering of manual pages. They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-09-03 12:07:59 +02:00
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
Clearer RETURN VALUE When I read the RETURN VALUE the first time, I didn't realize this command produces (or recreates) the psbt that I need. The change I made makes that more obvious when it's presented as a hit by GH for a search for psbt. [ Generated man page --RR ]
2021-05-10 19:47:27 +02:00
On success, returns the *psbt* it created, 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 *excess_msat* containing the amount above *satoshi*
which is available. This could be zero, or dust. If *satoshi* was "all",
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
then *excess_msat* is the entire amount once fees are subtracted
for the weights of the inputs and *startweight*.
sendpsbt, fundpsbt, utxopsbt, reserveinputs, unreserveinputs: allow custom number of blocks to reserve. Not an API break: reserve=true|false still works for fundpsbt and utxopsbt, but we also allow a raw number in there. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 03:19:37 +02:00
If *reserve* was *true* or a non-zero number, then a *reservations*
array is returned, exactly like *reserveinputs*.
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
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.
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
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
--------
lightning-fundpsbt(7).
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
make-schema: don't include tools/fromschema.py in SHASUMS We were including the entire list of prerequisites when generating a shastamp, which for schemas includes the `tools/fromschema.py` doc. This meant all of our shasums were updating anytime this tool file changed. Instead, we just include the first prerequisite. See: https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html#Automatic-Variables
2022-07-13 17:45:39 +02:00
[comment]: # ( SHA256STAMP:5037d26b92d3481a9eac98f509ac2dcee3f3185d6783f3a549d06a9e2e5e1a5f)
Reference in New Issue Copy Permalink