home | help 
LIGHTNING-UTXOPSBT(7)					   LIGHTNING-UTXOPSBT(7)

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

SYNOPSIS
     utxopsbt  satoshi	feerate  startweight utxos [reserve] [reservedok] [lock-
     time] [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  out-
     puts 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 end-
	ing in 000msat, or a number with 1 to 8 decimal places ending in btc.
     *	feerate  (feerate): Used for the transaction as initial feerate. The de-
	fault 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 (suc-
	cessfully,  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 mini-
	mum, 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 re-
	turned.
     *	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  re-
	   served.
	*  reserved_to_block (u32): The blockheight the reservation will expire.

     On  success,  returns  the  psbt  it  created, containing the inputs, feer-
     ate_per_kw  showing  the  exact  numeric  feerate	it  used,  estimated_fi-
     nal_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 re-
     turned, 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 re-
     turned 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
	 }
       ]
     }

Core Lightning v26.06.1 				   LIGHTNING-UTXOPSBT(7)
home | help