doc: Add documentation for new RPCs and a FIXME: in fromschema.py

doc/Makefile

@@ -24,6 +24,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-delpay.7 \
 	doc/lightning-disableoffer.7 \
 	doc/lightning-disconnect.7 \
+	doc/lightning-emergencyrecover.7 \
 	doc/lightning-feerates.7 \
 	doc/lightning-fetchinvoice.7 \
 	doc/lightning-fundchannel.7 \
@@ -46,6 +47,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-listpays.7 \
 	doc/lightning-listpeers.7 \
 	doc/lightning-listsendpays.7 \
+	doc/lightning-makesecret.7 \
 	doc/lightning-multifundchannel.7 \
 	doc/lightning-multiwithdraw.7 \
 	doc/lightning-newaddr.7 \
@@ -60,6 +62,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-pay.7 \
 	doc/lightning-parsefeerate.7 \
 	doc/lightning-plugin.7 \
+	doc/lightning-recoverchannel.7 \
 	doc/lightning-reserveinputs.7 \
 	doc/lightning-sendinvoice.7 \
 	doc/lightning-sendonion.7 \
@@ -69,6 +72,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-setchannelfee.7 \
 	doc/lightning-sendcustommsg.7 \
 	doc/lightning-signmessage.7 \
+	doc/lightning-staticbackup.7 \
 	doc/lightning-txprepare.7 \
 	doc/lightning-txdiscard.7 \
 	doc/lightning-txsend.7 \

doc/index.rst

@@ -47,6 +47,7 @@ Core Lightning Documentation
    lightning-delpay <lightning-delpay.7.md>
    lightning-disableoffer <lightning-disableoffer.7.md>
    lightning-disconnect <lightning-disconnect.7.md>
+   lightning-emergencyrecover <lightning-emergencyrecover.7.md>
    lightning-feerates <lightning-feerates.7.md>
    lightning-fetchinvoice <lightning-fetchinvoice.7.md>
    lightning-fundchannel <lightning-fundchannel.7.md>
@@ -75,6 +76,7 @@ Core Lightning Documentation
    lightning-listpeers <lightning-listpeers.7.md>
    lightning-listsendpays <lightning-listsendpays.7.md>
    lightning-listtransactions <lightning-listtransactions.7.md>
+   lightning-makesecret <lightning-makesecret.7.md>
    lightning-multifundchannel <lightning-multifundchannel.7.md>
    lightning-multiwithdraw <lightning-multiwithdraw.7.md>
    lightning-newaddr <lightning-newaddr.7.md>
@@ -90,6 +92,7 @@ Core Lightning Documentation
    lightning-pay <lightning-pay.7.md>
    lightning-ping <lightning-ping.7.md>
    lightning-plugin <lightning-plugin.7.md>
+   lightning-recoverchannel <lightning-recoverchannel.7.md>
    lightning-reserveinputs <lightning-reserveinputs.7.md>
    lightning-sendcustommsg <lightning-sendcustommsg.7.md>
    lightning-sendinvoice <lightning-sendinvoice.7.md>
@@ -101,6 +104,7 @@ Core Lightning Documentation
    lightning-setchannelfee <lightning-setchannelfee.7.md>
    lightning-signmessage <lightning-signmessage.7.md>
    lightning-signpsbt <lightning-signpsbt.7.md>
+   lightning-staticbackup <lightning-staticbackup.7.md>
    lightning-stop <lightning-stop.7.md>
    lightning-txdiscard <lightning-txdiscard.7.md>
    lightning-txprepare <lightning-txprepare.7.md>

doc/lightning-emergencyrecover.7.md

@@ -0,0 +1,43 @@
+lightning-emergencyrecover -- Command for recovering channels from the emergency.recovery file in the lightning directory
+=========================================================================================================================
+
+SYNOPSIS
+--------
+
+**emergencyrecover**
+
+DESCRIPTION
+-----------
+
+The **emergencyrecover** RPC command fetches data from the emergency.recover
+file and tries to reconnect to the peer and force him to close the channel.
+The data in this file has enough information to reconnect and sweep the funds.
+
+This recovery method is not spontaneous and it depends on the peer, so it should
+be used as a last resort to recover the funds stored in a channel in case of severe
+data loss.
+
+RETURN VALUE
+------------
+
+On success, an object is returned, containing:
+- **stubs** (array of hexs):
+  - Each item is the channel ID of the channel successfully inserted
+
+
+AUTHOR
+------
+
+Aditya <<aditya.sharma20111@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-getsharedsecret(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:9cfaa9eb4609b36accc3e3b12a352c00ddd402307e4461f4df274146d12f6eb0)

doc/lightning-makesecret.7.md

@@ -0,0 +1,44 @@
+lightning-makesecret -- Command for deriving pseudorandom key from HSM
+=====================================================================
+
+SYNOPSIS
+--------
+
+**makesecret** *info_hex*
+
+DESCRIPTION
+-----------
+
+The **makesecret** RPC command derives a secret key from the HSM_secret.
+
+The *info_hex* can be any hex data.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **secret** (secret): the pseudorandom key derived from HSM_secret (always 64 characters)
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+
+The following error codes may occur:
+- -1: Catchall nonspecific error.
+
+AUTHOR
+------
+
+Aditya <<aditya.sharma20111@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-getsharedsecret(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:1bd94ffa8440041efafe93440d9828be6baca199b0f5cb73220e4482582bf01d)

doc/lightning-recoverchannel.7.md

@@ -0,0 +1,45 @@
+lightning-recoverchannel -- Command for recovering channels bundeled in an array in the form of *Static Backup*
+===============================================================================================================
+
+SYNOPSIS
+--------
+
+**recoverchannel** *scb*
+
+DESCRIPTION
+-----------
+
+The **recoverchannel** RPC command tries to force the peer (with whom you
+already had a channel) to close the channel and sweeps on-chain fund. This
+method is not spontaneous and depends on the peer, so use it in case of
+severe data loss.
+
+The *scb* parameter is an array containing minimum required info to
+reconnect and sweep funds. You can get the scb for already stored channels
+by using the RPC command 'staticbackup'
+
+
+RETURN VALUE
+------------
+
+On success, an object is returned, containing:
+- **stubs** (array of hexs):
+  - Each item is the channel ID of the channel successfully inserted
+
+
+AUTHOR
+------
+
+Aditya <<aditya.sharma20111@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-getsharedsecret(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:9cfaa9eb4609b36accc3e3b12a352c00ddd402307e4461f4df274146d12f6eb0)

doc/lightning-staticbackup.7.md

@@ -0,0 +1,38 @@
+lightning-staticbacup -- Command for deriving getting SCB of all the existing channels
+======================================================================================
+
+SYNOPSIS
+--------
+
+**staticbackup**
+
+DESCRIPTION
+-----------
+
+The **staticbackup** RPC command returns an object with SCB of all the channels in an array.
+
+
+RETURN VALUE
+------------
+
+On success, an object is returned, containing:
+- **scb** (array of hexs):
+  - Each item is SCB of a channel in TLV format
+
+
+AUTHOR
+------
+
+Aditya <<aditya.sharma20111@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-getsharedsecret(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:9cfaa9eb4609b36accc3e3b12a352c00ddd402307e4461f4df274146d12f6eb0)

doc/schemas/emergencyrecover.request.json

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

doc/schemas/emergencyrecover.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "stubs"
+  ],
+  "properties": {
+    "stubs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "description": "Channel IDs of channels successfully inserted."
+      }
+    }
+  }
+}

doc/schemas/makesecret.request.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "info_hex"
+  ],
+  "properties": {
+    "info": {
+      "type": "hex",
+      "description": "This will be used for deriving the secret"
+    }
+  }
+}

doc/schemas/makesecret.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "secret"
+  ],
+  "properties": {
+    "secret": {
+      "type": "secret",
+      "description": "the pseudorandom key derived from HSM_secret",
+      "maxLength": 64,
+      "minLength": 64
+    }
+  }
+}

doc/schemas/recoverchannel.request.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scb"
+  ],
+  "scb": {
+    "type": "array",
+    "description": "SCB of the channels in an array",
+    "items": {
+      "type": "hexstr"
+    }
+  }
+}

doc/schemas/recoverchannel.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "stubs"
+  ],
+  "properties": {
+    "stubs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "description": "Channel IDs of channels successfully inserted."
+      }
+    }
+  }
+}

doc/schemas/staticbackup.request.json

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

doc/schemas/staticbackup.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scb"
+  ],
+  "properties": {
+    "scb": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "description": "SCB of a channel in TLV format"
+      }
+    }
+  }
+}

tools/fromschema.py

@@ -127,6 +127,17 @@ def output_members(sub, indent=''):
 
     # Remove deprecated and stub properties, collect warnings
     # (Stubs required to keep additionalProperties: false happy)
+
+    # FIXME: It fails for schemas which have only an array type with
+    # no properties, ex:
+    # "abcd": {
+    #  "type": "array",
+    #   "items": {
+    #    "type": "whatever",
+    #    "description": "efgh"
+    #   }
+    # }
+    # Checkout the schema of `staticbackup`.
     for p in list(sub['properties'].keys()):
         if len(sub['properties'][p]) == 0 or 'deprecated' in sub['properties'][p]:
             del sub['properties'][p]