doc: commando-listrunes & commando-blacklist

Author: ShahanaFarooqui

doc/Makefile

@@ -23,6 +23,8 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-close.7 \
 	doc/lightning-connect.7 \
 	doc/lightning-commando.7 \
+	doc/lightning-commando-blacklist.7 \
+	doc/lightning-commando-listrunes.7 \
 	doc/lightning-commando-rune.7 \
 	doc/lightning-createonion.7 \
 	doc/lightning-createinvoice.7 \

doc/index.rst

@@ -44,6 +44,8 @@ Core Lightning Documentation
    lightning-checkmessage <lightning-checkmessage.7.md>
    lightning-cli <lightning-cli.1.md>
    lightning-close <lightning-close.7.md>
+   lightning-commando-blacklist <lightning-commando-blacklist.7.md>
+   lightning-commando-listrunes <lightning-commando-listrunes.7.md>
    lightning-commando-rune <lightning-commando-rune.7.md>
    lightning-commando <lightning-commando.7.md>
    lightning-connect <lightning-connect.7.md>

doc/lightning-commando-blacklist.7.md

@@ -0,0 +1,42 @@
+lightning-commando-blacklist -- Command to prevent a rune from working
+======================================================================
+
+SYNOPSIS
+--------
+
+**commando-blacklist** [*start* [*end*]]
+
+DESCRIPTION
+-----------
+
+The **commando-blacklist** RPC command allows you to effectively revoke the rune you have created (and any runes derived from that rune with additional restictions). Attempting to use these runes will be resulted in a `Blacklisted rune` error message.
+
+All runes created by commando have a unique sequential id within them and can be blacklisted in ranges for efficiency. The command always returns the blacklisted ranges on success. If no parameters are specified, no changes have been made. If start specified without end, that single rune is blacklisted. If end is also specified, every rune from start till end inclusive is blacklisted.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object containing **blacklist** is returned.  It is an array of objects, where each object contains:
+
+- **start** (u64): Unique id of first rune in this blacklist range
+- **end** (u64): Unique id of last rune in this blacklist range
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-commando-listrunes(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:a165eb0086559c67fd2992bd736450fc5cb60d5607b94b095782e5c43b945e66)

doc/lightning-commando-listrunes.7.md

@@ -0,0 +1,52 @@
+lightning-commando-listrunes -- Command to list previously generated runes
+==========================================================================
+
+SYNOPSIS
+--------
+
+**commando-listrunes** [*rune*]
+
+DESCRIPTION
+-----------
+
+The **commando-listrunes** RPC command either lists runes that we stored as we generate them (see lightning-commando-rune(7)) or decodes the rune given on the command line. 
+
+NOTE: Runes generated prior to v23.05 were not stored, so will not appear in this list.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object containing **runes** is returned.  It is an array of objects, where each object contains:
+
+- **rune** (string): Base64 encoded rune
+- **unique\_id** (string): Unique id assigned when the rune was generated; this is always a u64 for commando runes
+- **restrictions** (array of objects): The restrictions on what commands this rune can authorize:
+  - **alternatives** (array of objects):
+    - **fieldname** (string): The field this restriction applies to; see commando-rune(7)
+    - **value** (string): The value accepted for this field
+    - **condition** (string): The way to compare fieldname and value
+    - **english** (string): English readable description of this alternative
+- **restrictions\_as\_english** (string): English readable description of the restrictions array above
+- **stored** (boolean, optional): This is false if the rune does not appear in our datastore (only possible when `rune` is specified) (always *false*)
+- **blacklisted** (boolean, optional): The rune has been blacklisted; see commando-blacklist(7) (always *true*)
+- **our\_rune** (boolean, optional): This is not a rune for this node (only possible when `rune` is specified) (always *false*)
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-commando-rune(7), lightning-commando-blacklist(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:dd70c3640c0ffcc7e15fb5dc0fbaa7c28a1abcd6bacb46f9b16d94a4b2ec74d0)

doc/lightning-commando-rune.7.md

@@ -14,8 +14,8 @@ The **commando-rune** RPC command creates a base64 string called a
 contains a unique id (a number starting at 0), and can have
 restrictions inside it.  Nobody can remove restrictions from a rune: if
 you try, the rune will be rejected.  There is no limit on how many
-runes you can issue: the node doesn't store them, but simply decodes
-and checks them as they are received.
+runes you can issue; the node simply decodes
+and checks them as they are received (we do store them for lightning-commando-listrunes(7) however).
 
 If *rune* is supplied, the restrictions are simple appended to that
 *rune* (it doesn't need to be a rune belonging to this node).  If no