NAME

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.:

• 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).:

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 <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO

lightning-fundpsbt(7)

RESOURCES

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

EXAMPLES

Example 1:

Request:

$ lightning-cli utxopsbt "1000000" "15000perkw" "214" "['utxo010101010101010101010101010101010101010101010101010101010101:1']" "None" "True" "None" "None" "True"

{


  "id": "example:utxopsbt#1",


  "method": "utxopsbt",


  "params": [


    1000000,


    "15000perkw",


    214,


    [


      "utxo010101010101010101010101010101010101010101010101010101010101:1"


    ],


    null,


    true,


    null,


    null,


    true


  ]
}

Response:

{


  "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000",


  "feerate_per_kw": 15000,


  "estimated_final_weight": 657,


  "excess_msat": 0,


  "change_outnum": 0,


  "reservations": [


    {


      "txid": "utxo010101010101010101010101010101010101010101010101010101010101",


      "vout": 1,


      "was_reserved": true,


      "reserved": true,


      "reserved_to_block": 2240


    }


  ]
}

Example 2:

Request:

$ lightning-cli utxopsbt -k "satoshi"=2000000 "feerate"="18750perkw" "startweight"=214 "utxos"='["utxo010101010101010101010101010101010101010101010101010101010101:1"]' "reservedok"=True "excess_as_change"=True

{


  "id": "example:utxopsbt#2",


  "method": "utxopsbt",


  "params": {


    "satoshi": 2000000,


    "feerate": "18750perkw",


    "startweight": 214,


    "utxos": [


      "utxo010101010101010101010101010101010101010101010101010101010101:1"


    ],


    "reservedok": true,


    "excess_as_change": true


  }
}

Response:

{


  "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000",


  "feerate_per_kw": 18750,


  "estimated_final_weight": 657,


  "excess_msat": 0,


  "change_outnum": 0,


  "reservations": [


    {


      "txid": "utxo010101010101010101010101010101010101010101010101010101010101",


      "vout": 1,


      "was_reserved": true,


      "reserved": true,


      "reserved_to_block": 2312


    }


  ]
}