lightning-utxopsbt -- Command to populate PSBT inputs from given UTXOs

SYNOPSIS

utxopsbt satoshi feerate startweight utxos [reserve] [reservedok] [locktime] [min_witness_weight] [excess_as_change] [opening_anchor_channel]

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.

satoshi (sat_or_all): 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.
feerate (feerate): Used for the transaction as initial feerate. The default is normal.
startweight (u32): The weight of the transaction before fundpsbt has added any inputs.
utxos (array of outpoints): An array of txid:vout, each of which must be reserved or available.:
- (outpoint, optional)
reserve (u32, optional): If not zero, then reserveinputs is called (successfully, with exclusive true) on the returned PSBT for this number of blocks. The default is 72 blocks.
reservedok (boolean, optional): If set to true, it will also fail if any of the utxos are already reserved. The default is false.
locktime (u32, optional): If not set, it is set to a recent block height.
min_witness_weight (u32, 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.
excess_as_change (boolean, optional): Flag to add a change output for the excess sats.
opening_anchor_channel (boolean, optional): To signel that it needs emergency reserve for anchors so that we can lowball our commitment tx fees, and min-emergency-msat for reserving some sats for closing anchor channels. (added v23.08)

RETURN VALUE

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) (always true): Whether this output is now reserved.
- reserved_to_block (u32): The blockheight the reservation will expire.

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, then excess_msat is the entire amount once fees are subtracted for the weights of the inputs and startweight.

If reserve was true or a non-zero number, then a reservations array is returned, exactly like reserveinputs.

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.

ERRORS

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 <[email protected]> is mainly responsible.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

lightning-cli utxopsbt -k "satoshi"=0 "feerate"="253perkw" "startweight"=0 "utxos"='["d82a99192fb333106ea8d08f5231ed45f2ed5b1ef9eb81b0fef8f9ea354d2637:1"]' "reserve"=0 "reservedok"=True "excess_as_change"=False

{
  "id": "example:utxopsbt#1",
  "method": "utxopsbt",
  "params": {
    "satoshi": 0,
    "feerate": "253perkw",
    "startweight": 0,
    "utxos": [
      "d82a99192fb333106ea8d08f5231ed45f2ed5b1ef9eb81b0fef8f9ea354d2637:1"
    ],
    "reserve": 0,
    "reservedok": true,
    "excess_as_change": false
  }
}

Response:

{
  "psbt": "cHNidP8BADMCAAAAATcmTTXq+fj+sIHr+R5b7fJF7TFSj9CobhAzsy8ZmSrYAQAAAAD9////AGYAAAAAAQDeAgAAAAABAWQACJva49ga8OCYXvPRWQRhoXndrJykwjgXbwT251dEAAAAAAD9////AiOI9ikBAAAAFgAU3gClv/YpAKRpfDuiFu6mIL2E4+5QaQ8AAAAAABYAFAH62Qq81maX4lkhZHIt5KlevuFlAkcwRAIgUXIQFs7oRkorVThUn3sLj7WI7g8c8RHai4ChoCvIkWsCICp1CqHl4BlMJCKFHRWHXhhekaj0r1EFSNrh8UnvysQPASEDqHIAEdaH3H6pb3VJzbJNDG4lL8PTfsheL+h2p6baK3JlAAAAAQEfUGkPAAAAAAAWABQB+tkKvNZml+JZIWRyLeSpXr7hZQA=",
  "feerate_per_kw": 253,
  "estimated_final_weight": 271,
  "excess_msat": 1009932000
}

Example 2: