LIGHTNING-FUNDPSBT(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

, in nixpkgs unstable

💖 `LIGHTNING-FUNDPSBT(7)` — `fundpsbt` 💖

manual name: LIGHTNING-FUNDPSBT(7) · command: fundpsbt · group-chat mode: on 💅

💖 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_channel]

🫶 DESCRIPTION 🫶

okay so fundpsbt is a low-level RPC command that creates a PSBT using unreserved inputs in the wallet, and it can optionally reserve them too. literally the wallet-to-PSBT pipeline, bestie 🫶

satoshi (sat_or_all) — the minimum satoshi value of the output(s) needed, or the string all meaning use all unreserved inputs. If it’s 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.
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 (successfully, 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 minimum, 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 signal 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 💸

slay, 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) (always false) — 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.

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 😭

ngl, 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. main character energy 👑

🌈 RESOURCES 🌈

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

🧚 USAGE 🧚

Let's assume the caller is trying to produce a 100,000 satoshi output. okay so, here’s the vibe:

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 excess_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": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000310000",
  "feerate_per_kw": 253,
  "estimated_final_weight": 652,
  "excess_msat": 196962518000,
  "change_outnum": 0
}

💅 Example 2: