{ "$schema": "../rpc-schema-draft.json", "type": "object", "additionalProperties": false, "rpc": "fundpsbt", "title": "Command to populate PSBT inputs from the wallet", "description": [ "`fundpsbt` is a low-level RPC command which creates a PSBT using unreserved inputs in the wallet, optionally reserving them as well." ], "request": { "required": [ "satoshi", "feerate", "startweight" ], "properties": { "satoshi": { "type": "sat_or_all", "description": [ "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": { "type": "feerate", "description": [ "Used for the transaction as initial feerate." ], "default": "*normal*" }, "startweight": { "type": "u32", "description": [ "The weight of the transaction before *fundpsbt* has added any inputs." ] }, "minconf": { "type": "u32", "description": [ "The minimum number of confirmations that used outputs should have." ], "default": "1" }, "reserve": { "type": "u32", "description": [ "If not zero, then *reserveinputs* is called (successfully, with *exclusive* true) on the returned PSBT for this number of blocks." ], "default": "72 blocks" }, "locktime": { "type": "u32", "description": [ "The locktime of the transaction. if not set, it is set to a recent block height." ] }, "min_witness_weight": { "type": "u32", "description": [ "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": { "type": "boolean", "description": [ "Flag to add a change output for the excess sats." ] }, "nonwrapped": { "added": "v23.02", "type": "boolean", "description": [ "To signal to filter out any p2sh-wrapped inputs from funding this PSBT." ] }, "opening_anchor_channel": { "added": "v23.08", "type": "boolean", "description": [ "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." ] } } }, "response": { "required": [ "psbt", "feerate_per_kw", "estimated_final_weight", "excess_msat" ], "properties": { "psbt": { "type": "string", "description": [ "Unsigned PSBT which fulfills the parameters given." ] }, "feerate_per_kw": { "type": "u32", "description": [ "The feerate used to create the PSBT, in satoshis-per-kiloweight." ] }, "estimated_final_weight": { "type": "u32", "description": [ "The estimated weight of the transaction once fully signed." ] }, "excess_msat": { "type": "msat", "description": [ "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": { "type": "u32", "description": [ "The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds)." ] }, "reservations": { "type": "array", "description": [ "If *reserve* was true or a non-zero number, just as per lightning- reserveinputs(7)." ], "items": { "type": "object", "required": [ "txid", "vout", "was_reserved", "reserved", "reserved_to_block" ], "additionalProperties": false, "properties": { "txid": { "type": "txid", "description": [ "The txid of the transaction." ] }, "vout": { "type": "u32", "description": [ "The 0-based output number." ] }, "was_reserved": { "type": "boolean", "enum": [ false ], "description": [ "Whether this output was previously reserved." ] }, "reserved": { "type": "boolean", "enum": [ true ], "description": [ "Whether this output is now reserved." ] }, "reserved_to_block": { "type": "u32", "description": [ "The blockheight the reservation will expire." ] } } } } }, "post_return_value_notes": [ "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." ] }, "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 *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." ], "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 <> is mainly responsible." ], "see_also": [ "lightning-utxopsbt(7)", "lightning-reserveinputs(7)", "lightning-unreserveinputs(7)" ], "resources": [ "Main web site: " ], "examples": [ { "request": { "id": "example:fundpsbt#1", "method": "fundpsbt", "params": { "satoshi": 16777216, "feerate": "253perkw", "startweight": 250, "reserve": 0, "excess_as_change": false } }, "response": { "psbt": "cHNidP8BADMCAAAAAWzmSFzhTtXBnQewytc32WaMwJSunScwsYndBNdU80JqAAAAAAD9////AGYAAAAAAQDeAgAAAAABAU1MpIJeOOzqAYVkZaytJCmzUadBVltKar8kWtzKSVeYAAAAAAD9////AoCWmAEAAAAAFgAUAfrZCrzWZpfiWSFkci3kqV6+4WXzWm0oAQAAABYAFD8W5uBNZAxN6n1jqU62dxWQbyGAAkcwRAIgUK+vMOeWiDPiJM8fpgKCjjwXog4yfWPvtKES1ZZPaM8CIB3cgouGpV6Gc7nEvAu28Mg9tkAWt/Xl5FDOseEyeZqHASECTwjR0I3gLHdSW7jRmnVXdm0+MgJ1hihnqEfXYeFWA/NlAAAAAQEfgJaYAQAAAAAWABQB+tkKvNZml+JZIWRyLeSpXr7hZQA=", "feerate_per_kw": 253, "estimated_final_weight": 521, "excess_msat": 9999869000 } }, { "request": { "id": "example:fundpsbt#2", "method": "fundpsbt", "params": { "satoshi": "all", "feerate": "1000perkw", "startweight": 1000, "excess_as_change": false } }, "response": { "psbt": "cHNidP8BAF4CAAAAAfwbEpvpi6D14YV4VLnuVB47Y0uF41kXEyJRL4IusySSAQAAAAD9////ASICAAAAAAAAIlEgeDY1X9yKgtxMsAp3LFVUFR0GOEpN1l6NP2isCFZrhL5nAAAAAAEA9gIAAAAAAQFEkxvLatohY6mw5gr5qG1aiArSrziFPR2YoqD21Hv+RAAAAAAA/f///wJAQg8AAAAAACIAIFuM07kUz2fN2Ppic8kwNT3TZHZzT72WIQLC31O5CIDNrz8PAAAAAAAiUSBj/+5Op9UebK35CG4oaiUnkiqqJbjFOuvzL6MqCmJ/WgJHMEQCIEu1nfVRt9i+rFM219mwhMqdwJsqygWSWTFUS+cemdh6AiBG3Qo8g9J/aAMO2RHDsIBScscj6pTTIwZp7Gw8G3EOKAEhA9dFRFyTYmZfIuDZbp52byc/MmDeo5yKdr+gXdJoTdzPZgAAAAEBK68/DwAAAAAAIlEgY//uTqfVHmyt+QhuKGolJ5IqqiW4xTrr8y+jKgpif1oAAA==", "feerate_per_kw": 1000, "estimated_final_weight": 1443, "excess_msat": 997354000, "change_outnum": 0, "reservations": [ { "txid": "9224b32e822f5122131759e3854b633b1e54eeb9547885e1f5a08be99b121bfc", "vout": 1, "was_reserved": false, "reserved": true, "reserved_to_block": 175 } ] } }, { "request": { "id": "example:fundpsbt#3", "method": "fundpsbt", "params": { "satoshi": "109000sat", "feerate": "slow", "startweight": 166, "excess_as_change": true } }, "response": { "psbt": "cHNidP8BAF4CAAAAAbEf44mT/BPDxLkUjKy1byWksyLyuM6hbe8shzEbbXhGAQAAAAD9////AU58DQAAAAAAIlEgeDY1X9yKgtxMsAp3LFVUFR0GOEpN1l6NP2isCFZrhL5sAAAAAAEA9gIAAAAAAQEV9Sj1wfHqO/ECZeHp/u7cFL5eRaa1Vu4hXWbwH72pxgEAAAAA/f///wJAQg8AAAAAACIAIFuM07kUz2fN2Ppic8kwNT3TZHZzT72WIQLC31O5CIDNAS8PAAAAAAAiUSBj/+5Op9UebK35CG4oaiUnkiqqJbjFOuvzL6MqCmJ/WgJHMEQCIGILT3DrcNn6/WKOhsxxKq7lDWq47dV0IjRhj0bYHs4yAiApzODtmrz7ifK32G81A2XbBxWboFk2vN4T3ng/hYmb1wEhA9dFRFyTYmZfIuDZbp52byc/MmDeo5yKdr+gXdJoTdzPZgAAAAEBKwEvDwAAAAAAIlEgY//uTqfVHmyt+QhuKGolJ5IqqiW4xTrr8y+jKgpif1oAAA==", "feerate_per_kw": 3750, "estimated_final_weight": 609, "excess_msat": 0, "change_outnum": 0, "reservations": [ { "txid": "46786d1b31872cef6da1ceb8f222b3a4256fb5ac8c14b9c4c313fc9389e31fb1", "vout": 1, "was_reserved": false, "reserved": true, "reserved_to_block": 180 } ] } } ] }