mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 22:31:48 +01:00
b803609247
Example usage has been either merged with examples or usage keys. This heading was not required separately. This PR edits & rearranges Examples, Example Notifications and Example Usage data. Changelog-None.
286 lines
10 KiB
JSON
286 lines
10 KiB
JSON
{
|
|
"$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 <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-utxopsbt(7)",
|
|
"lightning-reserveinputs(7)",
|
|
"lightning-unreserveinputs(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
],
|
|
"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
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|