mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 14:24:09 +01:00
04884ca664
Merge information from `*.request.json` & `*.schema.json`. Also consolidate remaining details from `*.md` files and create a single file in schemas folder.
271 lines
9.8 KiB
JSON
271 lines
9.8 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"rpc": "utxopsbt",
|
|
"title": "Command to populate PSBT inputs from given UTXOs",
|
|
"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 outputs from the wallet, it takes a compulsory list of outputs to use."
|
|
],
|
|
"request": {
|
|
"required": [
|
|
"satoshi",
|
|
"feerate",
|
|
"startweight",
|
|
"utxos"
|
|
],
|
|
"properties": {
|
|
"satoshi": {
|
|
"type": "msat_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."
|
|
]
|
|
},
|
|
"utxos": {
|
|
"type": "array",
|
|
"description": [
|
|
"An array of `txid:vout`, each of which must be reserved or available."
|
|
],
|
|
"items": {
|
|
"type": "outpoint"
|
|
}
|
|
},
|
|
"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"
|
|
},
|
|
"reservedok": {
|
|
"type": "boolean",
|
|
"description": [
|
|
"If set to true, it will also fail if any of the *utxos* are already reserved."
|
|
],
|
|
"default": "false"
|
|
},
|
|
"locktime": {
|
|
"type": "u32",
|
|
"description": [
|
|
"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."
|
|
]
|
|
},
|
|
"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",
|
|
"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": [
|
|
"On success, returns the *psbt* it created, containing the inputs, *feerate_per_kw* showing the exact numeric feerate it used, *estimated_final_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 returned, 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 returned 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."
|
|
],
|
|
"example_json_request": [
|
|
{
|
|
"id": "example:utxopsbt#1",
|
|
"method": "utxopsbt",
|
|
"params": {
|
|
"satoshi": 0,
|
|
"feerate": "253perkw",
|
|
"startweight": 0,
|
|
"utxos": [
|
|
"d82a99192fb333106ea8d08f5231ed45f2ed5b1ef9eb81b0fef8f9ea354d2637:1"
|
|
],
|
|
"reserve": 0,
|
|
"reservedok": true,
|
|
"locktime": null,
|
|
"min_witness_weight": null,
|
|
"excess_as_change": false
|
|
}
|
|
},
|
|
{
|
|
"id": "example:utxopsbt#2",
|
|
"method": "utxopsbt",
|
|
"params": {
|
|
"satoshi": 1000000,
|
|
"feerate": "7500perkw",
|
|
"startweight": 0,
|
|
"utxos": [
|
|
"2fc3b9f8d4aed120f6d9a6f206f07c35ef4d518ec0305d1d974873d256e38ca7:1",
|
|
"2f669f6a605ee5c7ddd2abb753bc64b1a90bd1b7448264f5d78a7ca823c00a1b:1"
|
|
],
|
|
"reserve": null,
|
|
"reservedok": true,
|
|
"locktime": null,
|
|
"min_witness_weight": null,
|
|
"excess_as_change": false
|
|
}
|
|
}
|
|
],
|
|
"example_json_response": [
|
|
{
|
|
"psbt": "cHNidP8BADMCAAAAATcmTTXq+fj+sIHr+R5b7fJF7TFSj9CobhAzsy8ZmSrYAQAAAAD9////AGYAAAAAAQDeAgAAAAABAWQACJva49ga8OCYXvPRWQRhoXndrJykwjgXbwT251dEAAAAAAD9////AiOI9ikBAAAAFgAU3gClv/YpAKRpfDuiFu6mIL2E4+5QaQ8AAAAAABYAFAH62Qq81maX4lkhZHIt5KlevuFlAkcwRAIgUXIQFs7oRkorVThUn3sLj7WI7g8c8RHai4ChoCvIkWsCICp1CqHl4BlMJCKFHRWHXhhekaj0r1EFSNrh8UnvysQPASEDqHIAEdaH3H6pb3VJzbJNDG4lL8PTfsheL+h2p6baK3JlAAAAAQEfUGkPAAAAAAAWABQB+tkKvNZml+JZIWRyLeSpXr7hZQA=",
|
|
"feerate_per_kw": 253,
|
|
"estimated_final_weight": 271,
|
|
"excess_msat": 1009932000
|
|
},
|
|
{
|
|
"psbt": "cHNidP8BAFwCAAAAAqeM41bSc0iXHV0wwI5RTe81fPAG8qbZ9iDRrtT4ucMvAQAAAAD9////GwrAI6h8itf1ZIJEt9ELqbFkvFO3q9Ldx+VeYGqfZi8BAAAAAP3///8AZgAAAAABAN4CAAAAAAEBEaK0TQ97IsrzuO1gLt+vYbvLBG90NrCOZp7SCgrRknYAAAAAAP3///8CM6/2KQEAAAAWABQ1B/KkIVbg7yFRcCEN/VOptfOX/EBCDwAAAAAAFgAUAfrZCrzWZpfiWSFkci3kqV6+4WUCRzBEAiA1oI1us81XEa/DRlvcP2qnbWLsV5pZcRfvj9MLyT202gIgb7noMqHYWMmm7H7VNEfWa29jjtuV9yrrSc9ui11ECQ0BIQKhZOHR4gFKMu2EKKgZ/7qnhzq9PvhtnAW2sxPZ4c9RIWUAAAABAR9AQg8AAAAAABYAFAH62Qq81maX4lkhZHIt5KlevuFlAAEA3gIAAAAAAQGnjONW0nNIlx1dMMCOUU3vNXzwBvKm2fYg0a7U+LnDLwAAAAAA/f///wJmbOcpAQAAABYAFOwPo5eUrDF7UgZBFQLRHOeX6PiGQEIPAAAAAAAWABTCzKsXHCpb6dq1LsQbglhjAkxUZgJHMEQCICgjGlauGj2eiMS4MWUK6zAWqMe1OuidQR+Hy9ZgSTuzAiA8JTb9OrLqS3hiWtT+TQ/NBsKJ2hhHLDaKUUNdgi4OkAEhA9g3oH5ejmGIqUY2ZWxc8YWF2+T+XpE/6oC40Cx3+e97ZQAAAAEBH0BCDwAAAAAAFgAUwsyrFxwqW+natS7EG4JYYwJMVGYA",
|
|
"feerate_per_kw": 7500,
|
|
"estimated_final_weight": 542,
|
|
"excess_msat": 995935000,
|
|
"reservations": [
|
|
{
|
|
"txid": "2fc3b9f8d4aed120f6d9a6f206f07c35ef4d518ec0305d1d974873d256e38ca7",
|
|
"vout": 1,
|
|
"was_reserved": true,
|
|
"reserved": true,
|
|
"reserved_to_block": 246
|
|
},
|
|
{
|
|
"txid": "2f669f6a605ee5c7ddd2abb753bc64b1a90bd1b7448264f5d78a7ca823c00a1b",
|
|
"vout": 1,
|
|
"was_reserved": true,
|
|
"reserved": true,
|
|
"reserved_to_block": 246
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-fundpsbt(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
]
|
|
}
|