doc/schemas: getsharedsecret, help, invoice, listchannels, listforwards

And a new "u8" type.

Signed-off-by: Rusty Russell <[email protected]>

Author: rustyrussell

contrib/pyln-testing/pyln/testing/fixtures.py

@@ -232,6 +232,12 @@ def is_u16(checker, instance):
             return False
         return instance >= 0 and instance < 2**16
 
+    def is_u8(checker, instance):
+        """8-bit integer"""
+        if not checker.is_type(instance, "integer"):
+            return False
+        return instance >= 0 and instance < 2**8
+
     def is_short_channel_id(checker, instance):
         """Short channel id"""
         if not checker.is_type(instance, "string"):
@@ -307,6 +313,7 @@ def is_txid(checker, instance):
         "u64": is_u64,
         "u32": is_u32,
         "u16": is_u16,
+        "u8": is_u8,
         "pubkey": is_pubkey,
         "msat": is_msat,
         "txid": is_txid,

doc/lightning-getsharedsecret.7

@@ -17,12 +17,10 @@ key DER-encoding of the SECP256K1 point.
 RETURN VALUE
 ------------
 
-On success, **getsharedsecret** returns a field *shared\_secret*,
-which is a hexadecimal string of the 256-bit SHA-2 of the
-compressed public key DER-encoding of the SECP256K1 point
-that is the shared secret generated using the
-Elliptic Curve Diffie-Hellman algorithm.
-This field is 32 bytes (64 hexadecimal characters in a string).
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **shared_secret** (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters)
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 This command may fail if communications with the HSM has a
 problem;
@@ -92,3 +90,4 @@ RESOURCES
 * Main web site: <https://github.com/ElementsProject/lightning>
 
 
+[comment]: # ( SHA256STAMP:23508d8a2af693bf5a6b4de2a3d2c4527b3fb8502fb775f06cfe84bf3a5aedbe)

doc/lightning-getsharedsecret.7.md

@@ -28,12 +28,14 @@ EXAMPLE JSON REQUEST
 RETURN VALUE
 ------------
 
-On success, a object will be return with the following proprieties:
-
-- *command*: A string that represents the stucture of the command.
-- *category*: A string that represents the category.
-- *description*: A string that represents the description.
-- *verbose*: A string that represents the verbode description.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **help** (array of objects):
+  - **command** (string): the command
+  - **category** (string): the category for this command (useful for grouping)
+  - **description** (string): a one-line description of the purpose of this command
+  - **verbose** (string): a full description of this command (including whether it's deprecated)
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 On failure, one of the following error codes may be returned:
 
@@ -64,3 +66,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
+[comment]: # ( SHA256STAMP:29119344d1800c7020c96a10ed94bfbf3c57491cc30e9b1f847facbdf0249aba)

doc/lightning-help.7

@@ -71,13 +71,23 @@ Otherwise, it's set to the parameter **cltv-final**.
 RETURN VALUE
 ------------
 
-On success, a hash is returned as *payment\_hash* to be given to the
-payer, and the *expiry\_time* as a UNIX timestamp. It also returns a
-BOLT11 invoice as *bolt11* to be given to the payer.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **bolt11** (string): the bolt11 string
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **expires_at** (u64): UNIX timestamp of when invoice expires
+
+The following warnings may also be returned:
+- **warning_capacity**: even using all possible channels, there's not enough incoming capacity to pay this invoice.
+- **warning_offline**: there would be enough incoming capacity, but some channels are offline, so there isn't.
+- **warning_deadends**: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't.
+- **warning_private_unused**: there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't.
+- **warning_mpp**: there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments.
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 On failure, an error is returned and no invoice is created. If the
 lightning process fails before responding, the caller should use
-lightning-listinvoice(7) to query whether this invoice was created or
+lightning-listinvoices(7) to query whether this invoice was created or
 not.
 
 The following error codes may occur:
@@ -86,14 +96,6 @@ The following error codes may occur:
 - 901: An invoice with the given *preimage* already exists.
 - 902: None of the specified *exposeprivatechannels* were usable.
 
-One of the following warnings may occur (on success):
-- *warning_capacity*: even using all possible channels, there's not enough incoming capacity to pay this invoice.
-- *warning_offline*: there would be enough incoming capacity, but some channels are offline, so there isn't.
-- *warning_deadends*: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't.
-- *warning_private_unused*: there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't.
-- *warning_mpp* if there is sufficient capacity, but not in a single channel,
-    so the payer will have to use multi-part payments.
-
 AUTHOR
 ------
 
@@ -102,11 +104,11 @@ Rusty Russell <<[email protected]>> is mainly responsible.
 SEE ALSO
 --------
 
-lightning-listinvoice(7), lightning-delinvoice(7),
-lightning-getroute(7), lightning-sendpay(7).
+lightning-listinvoices(7), lightning-delinvoice(7), lightning-pay(7).
 
 RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:71eeaa119c355874d52c511e09816291e296b0709dc6acb6cefd5614bdc20fd2)