splicing: Update documentation

Added documentation for splice_update & splice_signed and tweaked splice_init.

Added corresponding schemas for splice_* commands

Changelog-None

doc/Makefile

@@ -98,6 +98,9 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-sendcustommsg.7 \
 	doc/lightning-signinvoice.7 \
 	doc/lightning-signmessage.7 \
+	doc/lightning-splice_init.7 \
+	doc/lightning-splice_update.7 \
+	doc/lightning-splice_signed.7 \
 	doc/lightning-staticbackup.7 \
 	doc/lightning-txprepare.7 \
 	doc/lightning-txdiscard.7 \

doc/index.rst

@@ -114,6 +114,8 @@ Core Lightning Documentation
    lightning-signmessage <lightning-signmessage.7.md>
    lightning-signpsbt <lightning-signpsbt.7.md>
    lightning-splice_init <lightning-splice_init.7.md>
+   lightning-splice_signed <lightning-splice_signed.7.md>
+   lightning-splice_update <lightning-splice_update.7.md>
    lightning-sql <lightning-sql.7.md>
    lightning-staticbackup <lightning-staticbackup.7.md>
    lightning-stop <lightning-stop.7.md>

doc/lightning-splice_init.7.md

@@ -49,7 +49,7 @@ RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)
 PSBT=$(echo $RESULT | jq -r ".psbt")
 echo $RESULT
 
-RESULT=$(lightning-cli signpsbt $PSBT)
+RESULT=$(lightning-cli signpsbt -k psbt="$PSBT")
 PSBT=$(echo $RESULT | jq -r ".signed_psbt")
 echo $RESULT
 
@@ -79,4 +79,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:40121e2e7b0db8c99de12b4fd086f58f63e0d6643b9da1c1697a34dd5057454e)
+[comment]: # ( SHA256STAMP:28e857bb214a084bb638c7db3e7277291b7d60d78360fb8603423bc4d1d427a1)

doc/lightning-splice_signed.7.md

@@ -0,0 +1,93 @@
+lightning-splice\_signed -- Command to initiate a channel to a peer
+=====================================================================
+
+SYNOPSIS
+--------
+**(WARNING: experimental-splicing only)**
+
+**splice\_signed** *channel\_id* *psbt* [*sign\_first*]
+
+DESCRIPTION
+-----------
+
+`splice_signed` is a low level RPC command which finishes the active channel
+splice associated with `channel_id`.
+
+*channel\_id* is the channel id of the channel being spliced.
+
+*psbt* is the final version of the psbt to complete the splice with.
+
+*sign\_first* is a flag that makes our node offer the final splice signature
+first (defaults to false). When false, the node will calculate who should
+sign first based off who is adding inputting the least sats to the splice as per
+spec.
+
+The *psbt* must have all signatures attached to all inputs that you have added
+to it or it will fail.
+
+In this example we funded the psbt from our lightning node, so we can use the
+lightning node to sign for its funds.
+```shell
+RESULT=$(lightning-cli signpsbt $PSBT)
+PSBT=$(echo $RESULT | jq -r ".signed_psbt")
+echo $RESULT
+
+lightning-cli splice_signed $CHANNEL_ID $PSBT
+```
+
+Here is a full example set of splice commands that will splice in 100,000 sats
+to the first channel that comes out of `listpeerchannels`. The example assumes
+you already have at least one confirmed channel.
+```shell
+RESULT=$(lightning-cli listpeerchannels)
+CHANNEL_ID=$(echo $RESULT| jq -r ".channels[0].channel_id")
+echo $RESULT
+
+RESULT=$(lightning-cli fundpsbt -k satoshi=100000sat feerate=urgent startweight=800 excess_as_change=true)
+INITIALPSBT=$(echo $RESULT | jq -r ".psbt")
+echo $RESULT
+
+RESULT=$(lightning-cli splice_init $CHANNEL_ID 100000 $INITIALPSBT)
+PSBT=$(echo $RESULT | jq -r ".psbt")
+echo $RESULT
+
+RESULT="{\"commitments_secured\":false}"
+while [[ $(echo $RESULT | jq -r ".commitments_secured") == "false" ]]
+do
+	RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)
+	PSBT=$(echo $RESULT | jq -r ".psbt")
+	echo $RESULT
+done
+
+RESULT=$(lightning-cli signpsbt -k psbt="$PSBT")
+PSBT=$(echo $RESULT | jq -r ".signed_psbt")
+echo $RESULT
+
+lightning-cli splice_signed $CHANNEL_ID $PSBT
+```
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+
+- **tx** (hex): The hex representation of the final transaction that is published
+- **txid** (txid): The txid is of the final transaction
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+SEE ALSO
+--------
+
+AUTHOR
+------
+
+@dusty\_daemon
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:c084b5d6ce24db28226d5f37176f339009f4a2a761104404e7a41ed32cb2664c)

doc/lightning-splice_update.7.md

@@ -0,0 +1,106 @@
+lightning-splice\_update -- Command to initiate a channel to a peer
+=====================================================================
+
+SYNOPSIS
+--------
+**(WARNING: experimental-splicing only)**
+
+**splice\_update** *channel\_id* *psbt*
+
+DESCRIPTION
+-----------
+
+`splice_update` is a low level RPC command which updates the active channel
+splice associated with `channel_id`.
+
+*channel\_id* is the channel id of the channel being spliced.
+
+*psbt* is the base 64 encoded PSBT returned from `splice_init` with any changes
+added by the user.
+
+`splice_update` must be called repeatidly until the result `commitments_secured`
+is `true`. Each time `splice_update` is called, it will return a new PSBT that
+may have changes. In the simplest case, you take the returned `psbt` and pass
+it back into `splice_update` for the incoming `psbt` field.
+
+For more complex use cases, you may modify the `psbt` both before calling
+`splice_update` and inbetween subsequent calls until  `commitments_secured` is
+`true`. After which point you can no long make modifications to the PSBT (beyond
+signing, which comes later with `splice_signed`).
+
+Each `splice_update` result may include changes to the PSBT specified by your
+channel peer. You can review these changes between calls to `splice_update` to
+perform additional validation or strategy adjustment.
+
+Typically, `splice_update` will return `commitments_secured` true after one call
+but you should assume it will need multiple calls. Here is an example way to
+call `splice_update`
+```shell
+RESULT="{\"commitments_secured\":false}"
+while [[ $(echo $RESULT | jq -r ".commitments_secured") == "false" ]]
+do
+	RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)
+	PSBT=$(echo $RESULT | jq -r ".psbt")
+	echo $RESULT
+done
+```
+
+Before each call to `splice_update` you have the opportunity
+to make additional changes.
+
+Here is a full example set of splice commands that will splice in 100,000 sats
+to the first channel that comes out of `listpeerchannels`. The example assumes
+you already have at least one confirmed channel.
+```shell
+RESULT=$(lightning-cli listpeerchannels)
+CHANNEL_ID=$(echo $RESULT| jq -r ".channels[0].channel_id")
+echo $RESULT
+
+RESULT=$(lightning-cli fundpsbt -k satoshi=100000sat feerate=urgent startweight=800 excess_as_change=true)
+INITIALPSBT=$(echo $RESULT | jq -r ".psbt")
+echo $RESULT
+
+RESULT=$(lightning-cli splice_init $CHANNEL_ID 100000 $INITIALPSBT)
+PSBT=$(echo $RESULT | jq -r ".psbt")
+echo $RESULT
+
+RESULT="{\"commitments_secured\":false}"
+while [[ $(echo $RESULT | jq -r ".commitments_secured") == "false" ]]
+do
+	RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)
+	PSBT=$(echo $RESULT | jq -r ".psbt")
+	echo $RESULT
+done
+
+RESULT=$(lightning-cli signpsbt -k psbt="$PSBT")
+PSBT=$(echo $RESULT | jq -r ".signed_psbt")
+echo $RESULT
+
+lightning-cli splice_signed $CHANNEL_ID $PSBT
+```
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+
+- **psbt** (string): the (incomplete) PSBT of the splice transaction
+- **commitments\_secured** (boolean): whether or not the commitments were secured
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+SEE ALSO
+--------
+
+AUTHOR
+------
+
+@dusty\_daemon
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:e7f65170f8d32eb56b327a4eae0b5978517aba8e4f12e8271e71481afc33e0f3)

doc/schemas/splice_init.request.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "channel_id",
+    "relative_amount"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "channel_id": {
+      "type": "string",
+      "description": "the channel id of the channel to be spliced"
+    },
+    "relative_amount": {
+      "type": "integer",
+      "description": "a positive or negative amount of satoshis to add or subtract from the channel"
+    },
+    "initialpsbt": {
+      "type": "string",
+      "description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically"
+    },
+    "feerate_per_kw": {
+      "type": "u32",
+      "description": "the miner fee we promise our peer to pay for our side of the splice transaction. It is calculated by `feerate_per_kw` * our_bytes_in_splice_tx / 1000"
+    },
+    "force_feerate": {
+      "type": "boolean",
+      "description": "By default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check"
+    }
+  }
+}

doc/schemas/splice_init.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "psbt"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "psbt": {
+      "type": "string",
+      "description": "the (incomplete) PSBT of the splice transaction"
+    }
+  }
+}

doc/schemas/splice_signed.request.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "channel_id",
+    "psbt"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "channel_id": {
+      "type": "string",
+      "description": "the channel id of the channel to be spliced"
+    },
+    "psbt": {
+      "type": "string",
+      "description": "the final version of the psbt to complete the splice with"
+    },
+    "sign_first": {
+      "type": "boolean",
+      "description": "a flag that makes our node offer the final splice signature first (defaults to false). When false, the node will calculate who should sign first based off who is adding inputting the least sats to the splice as per spec"
+    }
+  }
+}

doc/schemas/splice_signed.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tx",
+    "txid"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "tx": {
+      "type": "hex",
+      "description": "The hex representation of the final transaction that is published"
+    },
+    "txid": {
+      "type": "txid",
+      "description": "The txid is of the final transaction"
+    }
+  }
+}

doc/schemas/splice_update.request.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "channel_id",
+    "psbt"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "channel_id": {
+      "type": "string",
+      "description": "the channel id of the channel to be spliced"
+    },
+    "psbt": {
+      "type": "string",
+      "description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically"
+    }
+  }
+}

doc/schemas/splice_update.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "psbt",
+    "commitments_secured"
+  ],
+  "added": "v23.08",
+  "properties": {
+    "psbt": {
+      "type": "string",
+      "description": "the (incomplete) PSBT of the splice transaction"
+    },
+    "commitments_secured": {
+      "type": "boolean",
+      "description": "whether or not the commitments were secured"
+    }
+  }
+}