hsmd: add hsmd_preapprove_keysend and check_preapprovekeysend pay modifier

Changelog-added: hsmd: A new message `hsmd_preapprove_keysend` is added.
Changelog-added: JSON-RPC: A new command `preapprovekeysend` is added.

doc/Makefile

@@ -76,6 +76,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-parsefeerate.7 \
 	doc/lightning-plugin.7 \
 	doc/lightning-preapproveinvoice.7 \
+	doc/lightning-preapprovekeysend.7 \
 	doc/lightning-recoverchannel.7 \
 	doc/lightning-reserveinputs.7 \
 	doc/lightning-sendinvoice.7 \

doc/index.rst

@@ -106,6 +106,7 @@ Core Lightning Documentation
    lightning-ping <lightning-ping.7.md>
    lightning-plugin <lightning-plugin.7.md>
    lightning-preapproveinvoice <lightning-preapproveinvoice.7.md>
+   lightning-preapprovekeysend <lightning-preapprovekeysend.7.md>
    lightning-recoverchannel <lightning-recoverchannel.7.md>
    lightning-reserveinputs <lightning-reserveinputs.7.md>
    lightning-sendcustommsg <lightning-sendcustommsg.7.md>

doc/lightning-preapprovekeysend.7.md

@@ -0,0 +1,61 @@
+lightning-preapprovekeysend -- Ask the HSM to preapprove a keysend payment (low-level)
+==================================================================
+
+SYNOPSIS
+--------
+
+**preapprovekeysend** *destination* *payment\_hash* *amount\_msat*
+
+DESCRIPTION
+-----------
+
+The **preapprovekeysend** RPC command submits the *destination*, *payment\_hash*,
+and *amount\_msat* parameters to the HSM to check that they are approved as a
+keysend payment.
+
+*destination* is a 33 byte, hex-encoded, node ID of the node that the payment should go to.
+
+*payment\_hash* is the unique identifier of a payment.
+
+*amount\_msat* is the amount to send in millisatoshi precision; it can
+be a whole number, or a whole number with suffix `msat` or `sat`, or a
+three decimal point number with suffix `sat`, or an 1 to 11 decimal
+point number suffixed by `btc`.
+
+Generally the **preapprovekeysend** request does not need to be made
+explicitly, it is automatically generated as part of a **keysend** request.
+
+By default, the HSM will approve all **preapprovekeysend** requests.
+
+If a remote signer is being used it might decline an **preapprovekeysend**
+request because it would exceed velocity controls, is not covered by
+allowlist controls, was declined manually, or other reasons.
+
+If a remote signer declines a **preapprovekeysend** request a subsequent
+attempt to pay the keysend anyway will fail; the signer will refuse to sign
+the commitment.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an empty object is returned.
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Ken Sedgwick <<ken@bonsai.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-keysend(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:735dd61146b04745f1e884037ead662a386fec2c41e2de1a8698d6bb03f63540)

doc/schemas/preapproveinvoice.request.json

@@ -7,7 +7,8 @@
   ],
   "properties": {
     "bolt11": {
-      "type": "string"
+      "type": "string",
+      "added": "v23.02"
     }
   }
 }

doc/schemas/preapprovekeysend.request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "destination",
+    "payment_hash",
+    "amount_msat"
+  ],
+  "properties": {
+    "destination": {
+      "type": "pubkey",
+      "added": "v23.02"
+    },
+    "payment_hash": {
+      "type": "hex",
+      "added": "v23.02",
+      "description": "the hash of the *payment_preimage* which will prove payment",
+      "maxLength": 64,
+      "minLength": 64
+    },
+    "amount_msat": {
+      "type": "msat",
+      "added": "v23.02"
+    }
+  }
+}

doc/schemas/preapprovekeysend.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {}
+}