recvpsbt: New onchain command for PSBT output

ChangeLog-Added: New `recvpsbt` command for creating a PSBT that can receive funds to the on-chain wallet.

Author: ddustin

doc/index.rst

@@ -100,6 +100,7 @@ Core Lightning Documentation
    lightning-preapproveinvoice <lightning-preapproveinvoice.7.md>
    lightning-preapprovekeysend <lightning-preapprovekeysend.7.md>
    lightning-recoverchannel <lightning-recoverchannel.7.md>
+   lightning-recvpsbt <lightning-recvpsbt.7.md>
    lightning-renepay <lightning-renepay.7.md>
    lightning-renepaystatus <lightning-renepaystatus.7.md>
    lightning-reserveinputs <lightning-reserveinputs.7.md>

doc/lightning-recvpsbt.7.md

@@ -0,0 +1,65 @@
+lightning-recvpsbt -- Command to populate PSBT outputs from the wallet
+================================================================
+
+SYNOPSIS
+--------
+
+**recvpsbt** *satoshi* [*initialpsbt*] [*locktime*]
+
+DESCRIPTION
+-----------
+
+`recvpsbt` is a low-level RPC command which creates or modifies a PSBT
+by adding a single output of amount *satoshi*.
+
+This is used to receive funds into the on-chain wallet interactively
+using PSBTs.
+
+*satoshi* is the satoshi value of the output. 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*.
+
+*initialpsbt* is a PSBT to add the output to. If not speciifed, a PSBt
+will be created automatically.
+
+*locktime* is an optional locktime: if not set, it is set to a recent
+block height (if no initial psbt is specified).
+
+EXAMPLE USAGE
+-------------
+
+Here is a command to make a PSBT with a 100,000 sat output that leads
+to the on-chain wallet.
+```shell
+lightning-cli recvpsbt 100000sat
+```
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+
+- **psbt** (string): Unsigned PSBT which fulfills the parameters given
+- **estimated\_added\_weight** (u32): The estimated weight of the added output
+- **outnum** (u32): The 0-based number where the output was placed
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+@dusty\_daemon
+
+SEE ALSO
+--------
+
+lightning-fundpsbt(7), lightning-utxopsbt(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:fad04aa277b18392570cc1ba6302506dadc71d1e3844720cb5c1b74812d731f2)

doc/schemas/recvpsbt.request.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "satoshi"
+  ],
+  "added": "v23.08.1",
+  "properties": {
+    "satoshi": {
+      "type": "msat"
+    },
+    "locktime": {
+      "type": "u32"
+    },
+    "initialpsbt": {
+      "type": "string",
+      "description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically"
+    }
+  }
+}

doc/schemas/recvpsbt.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "psbt",
+    "estimated_added_weight",
+    "outnum"
+  ],
+  "added": "v23.08.1",
+  "properties": {
+    "psbt": {
+      "type": "string",
+      "description": "Unsigned PSBT which fulfills the parameters given"
+    },
+    "estimated_added_weight": {
+      "type": "u32",
+      "description": "The estimated weight of the added output"
+    },
+    "outnum": {
+      "type": "u32",
+      "description": "The 0-based number where the output was placed"
+    }
+  }
+}