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

NAME
     fundpsbt -- Command to populate PSBT inputs from the wallet

SYNOPSIS
     fundpsbt	satoshi   feerate  startweight	[minconf]  [reserve]  [locktime]
     [min_witness_weight] [excess_as_change] [nonwrapped]  [opening_anchor_chan-
     nel]

DESCRIPTION
     fundpsbt  is  a low-level RPC command which creates a PSBT using unreserved
     inputs in the wallet, optionally reserving them as well.

     *	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.
     *	minconf (u32, optional): The minimum number of confirmations  that  used
	outputs should have. The default is 1.
     *	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.
     *	locktime (u32, optional): The locktime of the transaction. 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.
     *	nonwrapped (boolean, optional): To signal to filter out any p2sh-wrapped
	inputs from funding this PSBT. (added v23.02)
     *	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) (always false): Whether this output was previ-
	   ously reserved.
	*  reserved (boolean) (always true): Whether  this  output  is	now  re-
	   served.
	*  reserved_to_block (u32): The blockheight the reservation will expire.

     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-utxopsbt(7),  lightning-reserveinputs(7),  lightning-unreservein-
     puts(7)

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

USAGE
     Let's assume the caller is trying to produce a 100,000 satoshi output.

     First, the caller estimates the weight of the core (typically 42) and known
     outputs of the transaction (typically (9 + scriptlen) * 4).  For  a  simple
     P2WPKH it's a 22 byte scriptpubkey, so that's 124 weight.

     It  calls	"fundpsbt  100000sat  slow 166", which succeeds, and returns the
     psbt and feerate_per_kw it used, the  estimated_final_weight  and	any  ex-
     cess_msat.

     If  excess_msat  is  greater  than  the cost of adding a change output, the
     caller adds a change output randomly to position 0 or 1 in  the  PSBT.  Say
     feerate_per_kw  is 253, and the change output is a P2WPKH (weight 124), the
     cost is around 31 sats. With the dust limit disallowing payments below  546
     satoshis,	we  would only create a change output if excess_msat was greater
     or equal to 31 + 546.

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli fundpsbt -k "satoshi"=1000000 "feerate"="253perkw" "startweight"=250 "reserve"=0

     {
       "id": "example:fundpsbt#1",
       "method": "fundpsbt",
       "params": {
	 "satoshi": 1000000,
	 "feerate": "253perkw",
	 "startweight": 250,
	 "reserve": 0
       }
     }

     Response:

     {
       "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000",
       "feerate_per_kw": 253,
       "estimated_final_weight": 652,
       "excess_msat": 196962518000,
       "change_outnum": 0
     }

     Example 2:

     Request:

     $ lightning-cli fundpsbt -k "satoshi"=500000 "feerate"="urgent" "startweight"=166 "reserve"=0 "excess_as_change"=True "min_witness_weight"=110

     {
       "id": "example:fundpsbt#2",
       "method": "fundpsbt",
       "params": {
	 "satoshi": 500000,
	 "feerate": "urgent",
	 "startweight": 166,
	 "reserve": 0,
	 "excess_as_change": true,
	 "min_witness_weight": 110
       }
     }

     Response:

     {
       "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000410000",
       "feerate_per_kw": 11000,
       "estimated_final_weight": 613,
       "excess_msat": 0,
       "change_outnum": 0
     }

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