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 "1000000" "15000perkw" "214" "['bffbd4f5f789765823b7c1c12151797898702c7fe52f1d08ea644308d33c05b3:1']" "None" "True" "None" "None" "True"

{
  "id": "example:utxopsbt#1",
  "method": "utxopsbt",
  "params": [
    1000000,
    "15000perkw",
    214,
    [
      "bffbd4f5f789765823b7c1c12151797898702c7fe52f1d08ea644308d33c05b3:1"
    ],
    null,
    true,
    null,
    null,
    true
  ]
}

Response:

{
  "psbt": "cHNidP8BAF4CAAAAAbMFPNMIQ2TqCB0v5X8scJh4eVEhwcG3I1h2iff11Pu/AQAAAAD9////AUFZ3AsAAAAAIlEgO+E35aPNS3YQRaiMByjTJDUYNvBO1Z39o3m42EZGUreYAAAAAAEAcQIAAAABl0vCMXO3vKmwYNrBKr0bsVjo7Wmj501PavWRmxX1dywAAAAAAP3///8Ceh/00gAAAAAWABSauB3UBW2CVXly9l1sU6aMmVAq+ADC6wsAAAAAFgAUA8/shxXh9ASjbsAR5COPhjKfkJyXAAAAAQEfAMLrCwAAAAAWABQDz+yHFeH0BKNuwBHkI4+GMp+QnAAA",
  "feerate_per_kw": 15000,
  "estimated_final_weight": 657,
  "excess_msat": 0,
  "change_outnum": 0,
  "reservations": [
    {
      "txid": "bffbd4f5f789765823b7c1c12151797898702c7fe52f1d08ea644308d33c05b3",
      "vout": 1,
      "was_reserved": true,
      "reserved": true,
      "reserved_to_block": 2240
    }
  ]
}

Example 2: