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

And a new "u8" type.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

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

@@ -232,6 +232,12 @@ def _extra_validator():
             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 _extra_validator():
         "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

@@ -14,13 +14,13 @@ key DER-encoding of the SECP256K1 point\.
 
 .SH RETURN VALUE
 
-On success, \fBgetsharedsecret\fR returns a field \fIshared_secret\fR,
+On success, an object is returned, containing:
-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)\.
 
+.RS
+.IP \[bu]
+\fBshared_secret\fR (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters)
+
+.RE
 
 This command may fail if communications with the HSM has a
 problem;
@@ -94,4 +94,4 @@ SECG SEC-1 ECIES: \fIhttps://secg.org/sec1-v2.pdf\fR
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
 .RE
-\" SHA256STAMP:695c9ea03a16c6698806f3b288c0b7163a112b19791fd81bf7b3f9b032804ca3
+\" SHA256STAMP:c0cd7eab8f5114c3b7532b68861767df729757a1af9331330134d956db23e0a4

doc/lightning-getsharedsecret.7.md

@@ -17,12 +17,10 @@ key DER-encoding of the SECP256K1 point.
 RETURN VALUE
 ------------
 
-On success, **getsharedsecret** returns a field *shared\_secret*,
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-which is a hexadecimal string of the 256-bit SHA-2 of the
+On success, an object is returned, containing:
-compressed public key DER-encoding of the SECP256K1 point
+- **shared_secret** (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters)
-that is the shared secret generated using the
+[comment]: # (GENERATE-FROM-SCHEMA-END)
-Elliptic Curve Diffie-Hellman algorithm.
-This field is 32 bytes (64 hexadecimal characters in a string).
 
 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-help.7

@@ -27,17 +27,23 @@ page is not found\.
 .fi
 .SH RETURN VALUE
 
-On success, a object will be return with the following proprieties:
+On success, an object is returned, containing:
 
 .RS
 .IP \[bu]
-\fIcommand\fR: A string that represents the stucture of the command\.
+\fBhelp\fR (array of objects):
+.RS
 .IP \[bu]
-\fIcategory\fR: A string that represents the category\.
+\fBcommand\fR (string): the command
 .IP \[bu]
-\fIdescription\fR: A string that represents the description\.
+\fBcategory\fR (string): the category for this command (useful for grouping)
 .IP \[bu]
-\fIverbose\fR: A string that represents the verbode description\.
+\fBdescription\fR (string): a one-line description of the purpose of this command
+.IP \[bu]
+\fBverbose\fR (string): a full description of this command (including whether it's deprecated)
+
+.RE
+
 
 .RE
 
@@ -72,4 +78,4 @@ Vincenzo Palazzo \fI<vincenzo.palazzo@protonmail.com\fR> wrote the initial versi
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:cbd027bd9117d2e71167ab1c9d95a63c90b8e9c556dd75e951d4913a2891cb37
+\" SHA256STAMP:e162d82c81f6a121839d2dfa1658014867f058fe52a100a885956f566a211a8e

doc/lightning-help.7.md

@@ -28,12 +28,14 @@ EXAMPLE JSON REQUEST
 RETURN VALUE
 ------------
 
-On success, a object will be return with the following proprieties:
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-
+On success, an object is returned, containing:
-- *command*: A string that represents the stucture of the command.
+- **help** (array of objects):
-- *category*: A string that represents the category.
+  - **command** (string): the command
-- *description*: A string that represents the description.
+  - **category** (string): the category for this command (useful for grouping)
-- *verbose*: A string that represents the verbode description.
+  - **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-invoice.7

@@ -77,14 +77,37 @@ Otherwise, it's set to the parameter \fBcltv-final\fR\.
 
 .SH RETURN VALUE
 
-On success, a hash is returned as \fIpayment_hash\fR to be given to the
+On success, an object is returned, containing:
-payer, and the \fIexpiry_time\fR as a UNIX timestamp\. It also returns a
-BOLT11 invoice as \fIbolt11\fR to be given to the payer\.
 
+.RS
+.IP \[bu]
+\fBbolt11\fR (string): the bolt11 string
+.IP \[bu]
+\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
+.IP \[bu]
+\fBexpires_at\fR (u64): UNIX timestamp of when invoice expires
+
+.RE
+
+The following warnings may also be returned:
+
+.RS
+.IP \[bu]
+\fBwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\.
+.IP \[bu]
+\fBwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\.
+.IP \[bu]
+\fBwarning_deadends\fR: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't\.
+.IP \[bu]
+\fBwarning_private_unused\fR: there would be enough incoming capacity, but some channels are unannounced and \fIexposeprivatechannels\fR is \fIfalse\fR, so there isn't\.
+.IP \[bu]
+\fBwarning_mpp\fR: there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments\.
+
+.RE
 
 On failure, an error is returned and no invoice is created\. If the
 lightning process fails before responding, the caller should use
-\fBlightning-listinvoice\fR(7) to query whether this invoice was created or
+\fBlightning-listinvoices\fR(7) to query whether this invoice was created or
 not\.
 
 
@@ -100,23 +123,6 @@ The following error codes may occur:
 .IP \[bu]
 902: None of the specified \fIexposeprivatechannels\fR were usable\.
 
-.RE
-
-One of the following warnings may occur (on success):
-
-.RS
-.IP \[bu]
-\fIwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\.
-.IP \[bu]
-\fIwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\.
-.IP \[bu]
-\fIwarning_deadends\fR: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't\.
-.IP \[bu]
-\fIwarning_private_unused\fR: there would be enough incoming capacity, but some channels are unannounced and \fIexposeprivatechannels\fR is \fIfalse\fR, so there isn't\.
-.IP \[bu]
-\fIwarning_mpp\fR if there is sufficient capacity, but not in a single channel,
-  so the payer will have to use multi-part payments\.
-
 .RE
 .SH AUTHOR
 
@@ -124,11 +130,10 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 
 .SH SEE ALSO
 
-\fBlightning-listinvoice\fR(7), \fBlightning-delinvoice\fR(7),
+\fBlightning-listinvoices\fR(7), \fBlightning-delinvoice\fR(7), \fBlightning-pay\fR(7)\.
-\fBlightning-getroute\fR(7), \fBlightning-sendpay\fR(7)\.
 
 .SH RESOURCES
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:d53ec67cd81a41c7218e282c3d7662933868b25190334e9322de8a90ab99d603
+\" SHA256STAMP:69f1d573c0f7afe0cd63e2975d4a8e33d8a1acd2aabb6922b878d55c58731d72

doc/lightning-invoice.7.md

@@ -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
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-payer, and the *expiry\_time* as a UNIX timestamp. It also returns a
+On success, an object is returned, containing:
-BOLT11 invoice as *bolt11* to be given to the payer.
+- **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 <<rusty@rustcorp.com.au>> is mainly responsible.
 SEE ALSO
 --------
 
-lightning-listinvoice(7), lightning-delinvoice(7),
+lightning-listinvoices(7), lightning-delinvoice(7), lightning-pay(7).
-lightning-getroute(7), lightning-sendpay(7).
 
 RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:71eeaa119c355874d52c511e09816291e296b0709dc6acb6cefd5614bdc20fd2)

doc/lightning-listchannels.7

@@ -26,61 +26,37 @@ broadcast on the gossip network\.
 
 .SH RETURN VALUE
 
-On success, an object with a "channels" key is returned containing a
+On success, an object containing \fBchannels\fR is returned\.  It is an array of objects, where each object contains:
-list of 0 or more objects\.
-
-
-Each object in the list contains the following data:
 
 .RS
 .IP \[bu]
-\fIsource\fR : The node providing entry to the channel, specifying the
+\fBsource\fR (pubkey): the source node
-fees charged for using the channel in that direction\.
 .IP \[bu]
-\fIdestination\fR : The node providing the exit point for the channel\.
+\fBdestination\fR (pubkey): the destination node
 .IP \[bu]
-\fIshort_channel_id\fR : The channel identifier\.
+\fBpublic\fR (boolean): true if this is announced (otherwise it must be our channel)
 .IP \[bu]
-\fIpublic\fR : Boolean value, is publicly available\. Non-local channels
+\fBamount_msat\fR (msat): the total capacity of this channel (always a whole number of satoshis)
-will only ever have this value set to true\. Local channels are
-side-loaded by this node, rather than obtained through the gossip
-network, and so may have this value set to false\.
 .IP \[bu]
-\fIsatoshis\fR : Funds available in the channel\.
+\fBmessage_flags\fR (u8): as defined by BOLT #7
 .IP \[bu]
-\fIamount_sat\fR : Same as above, but ending in \fIsat\fR\.
+\fBchannel_flags\fR (u8): as defined by BOLT #7
 .IP \[bu]
-\fImessage_flags\fR : Bitfield showing the presence of optional fields
+\fBactive\fR (boolean): true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing
-in the \fIchannel_update\fR message (BOLT #7)\.
 .IP \[bu]
-\fIchannel_flags\fR : Bitfields indicating the direction of the channel
+\fBlast_update\fR (u32): UNIX timestamp on the last channel_update from \fIsource\fR
-and signaling various options concerning the channel\. (BOLT #7)\.
 .IP \[bu]
-\fIactive\fR : Boolean value, is available for routing\. This is linked
+\fBbase_fee_millisatoshi\fR (u32): Base fee changed by \fIsource\fR to use this channel
-to the channel flags data, where if the second bit is set, signals a
-channels temporary unavailability (due to loss of connectivity) OR
-permanent unavailability where the channel has been closed but not
-settlement on-chain\.
 .IP \[bu]
-\fIlast_update\fR : Unix timestamp (seconds) showing when the last
+\fBfee_per_millionth\fR (u32): Proportional fee changed by \fIsource\fR to use this channel, in parts-per-million
-channel_update message was received\.
 .IP \[bu]
-\fIbase_fee_millisatoshi\fR : The base fee (in millisatoshi) charged
+\fBdelay\fR (u32): The number of blocks delay required by \fIsource\fR to use this channel
-for the HTLC (BOLT #7; equivalent to \fBfee_base_msat\fR)\.
 .IP \[bu]
-\fIfee_per_millionth\fR : The amount (in millionths of a satoshi)
+\fBhtlc_minimum_msat\fR (msat): The smallest payment \fIsource\fR will allow via this channel
-charged per transferred satoshi (BOLT #7; equivalent to
-\fBfee_proportional_millionths\fR)\.
 .IP \[bu]
-\fIdelay\fR : The number of blocks of additional delay required when
+\fBfeatures\fR (hex): BOLT #9 features bitmap for this channel
-forwarding an HTLC in this direction\. (BOLT #7; equivalent to
-\fBcltv_expiry_delta\fR)\.
 .IP \[bu]
-\fIhtlc_minimum_msat\fR : The minimum payment which can be sent
+\fBhtlc_maximum_msat\fR (msat, optional): The largest payment \fIsource\fR will allow via this channel
-through this channel\.
-.IP \[bu]
-\fIhtlc_maximum_msat\fR : The maximum payment which can be sent
-through this channel\.
 
 .RE
 
@@ -117,4 +93,4 @@ BOLT #7:
 \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md\fR
 
 .RE
-\" SHA256STAMP:c7c5d846dc08733728bbc358394da54c2d90b0d31633bdd2df48e89d46c359c0
+\" SHA256STAMP:4f6181982e495f601d20c33f827a48f6f80c7f268f30b8e73b0a3e9ae2790838

doc/lightning-listchannels.7.md

@@ -26,43 +26,23 @@ broadcast on the gossip network.
 RETURN VALUE
 ------------
 
-On success, an object with a "channels" key is returned containing a
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-list of 0 or more objects.
+On success, an object containing **channels** is returned.  It is an array of objects, where each object contains:
-
+- **source** (pubkey): the source node
-Each object in the list contains the following data:
+- **destination** (pubkey): the destination node
-- *source* : The node providing entry to the channel, specifying the
+- **public** (boolean): true if this is announced (otherwise it must be our channel)
-fees charged for using the channel in that direction.
+- **amount_msat** (msat): the total capacity of this channel (always a whole number of satoshis)
-- *destination* : The node providing the exit point for the channel.
+- **message_flags** (u8): as defined by BOLT #7
-- *short\_channel\_id* : The channel identifier.
+- **channel_flags** (u8): as defined by BOLT #7
-- *public* : Boolean value, is publicly available. Non-local channels
+- **active** (boolean): true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing
-will only ever have this value set to true. Local channels are
+- **last_update** (u32): UNIX timestamp on the last channel_update from *source*
-side-loaded by this node, rather than obtained through the gossip
+- **base_fee_millisatoshi** (u32): Base fee changed by *source* to use this channel
-network, and so may have this value set to false.
+- **fee_per_millionth** (u32): Proportional fee changed by *source* to use this channel, in parts-per-million
-- *satoshis* : Funds available in the channel.
+- **delay** (u32): The number of blocks delay required by *source* to use this channel
-- *amount\_sat* : Same as above, but ending in *sat*.
+- **htlc_minimum_msat** (msat): The smallest payment *source* will allow via this channel
-- *message\_flags* : Bitfield showing the presence of optional fields
+- **features** (hex): BOLT #9 features bitmap for this channel
-in the *channel\_update* message (BOLT \#7).
+- **htlc_maximum_msat** (msat, optional): The largest payment *source* will allow via this channel
-- *channel\_flags* : Bitfields indicating the direction of the channel
+[comment]: # (GENERATE-FROM-SCHEMA-END)
-and signaling various options concerning the channel. (BOLT \#7).
-- *active* : Boolean value, is available for routing. This is linked
-to the channel flags data, where if the second bit is set, signals a
-channels temporary unavailability (due to loss of connectivity) OR
-permanent unavailability where the channel has been closed but not
-settlement on-chain.
-- *last\_update* : Unix timestamp (seconds) showing when the last
-channel\_update message was received.
-- *base\_fee\_millisatoshi* : The base fee (in millisatoshi) charged
-for the HTLC (BOLT \#7; equivalent to `fee_base_msat`).
-- *fee\_per\_millionth* : The amount (in millionths of a satoshi)
-charged per transferred satoshi (BOLT \#7; equivalent to
-`fee_proportional_millionths`).
-- *delay* : The number of blocks of additional delay required when
-forwarding an HTLC in this direction. (BOLT \#7; equivalent to
-`cltv_expiry_delta`).
-- *htlc\_minimum\_msat* : The minimum payment which can be sent
-through this channel.
-- *htlc\_maximum\_msat* : The maximum payment which can be sent
-through this channel.
 
 If *short\_channel\_id* or *source* is supplied and no matching channels
 are found, a "channels" object with an empty list is returned.
@@ -92,3 +72,4 @@ Lightning RFC site
 -   BOLT \#7:
     <https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md>
 
+[comment]: # ( SHA256STAMP:b14e060fc39b569657050d5bb894c22c0dc575593804248746323b803053b57b)

doc/lightning-listforwards.7

@@ -20,51 +20,49 @@ on the given in/out channel are returned\.
 
 .SH RETURN VALUE
 
-On success one array will be returned: \fIforwards\fR with htlcs that have
+On success, an object containing \fBforwards\fR is returned\.  It is an array of objects, where each object contains:
-been processed
-
-
-Each entry in \fIforwards\fR will include:
 
 .RS
 .IP \[bu]
-\fIin_channel\fR: the short_channel_id of the channel that recieved the incoming htlc\.
+\fBin_channel\fR (short_channel_id): the channel that received the HTLC
 .IP \[bu]
-\fIin_msatoshi\fR, \fIin_msat\fR - amount of msatoshis that are forwarded to this node\.
+\fBin_msat\fR (msat): the value of the incoming HTLC
 .IP \[bu]
-\fIstatus\fR: status can be either \fIoffered\fR if the routing process is still ongoing,
+\fBstatus\fR (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed")
-\fIsettled\fR if the routing process is completed or \fIfailed\fR if the routing process could not be completed\.
 .IP \[bu]
-\fIreceived_time\fR: timestamp when incoming htlc was received\.
+\fBreceived_time\fR (number): the UNIX timestamp when this was received
+.IP \[bu]
+\fBout_channel\fR (short_channel_id, optional): the channel that the HTLC was forwarded to
+.IP \[bu]
+\fBpayment_hash\fR (hex, optional): payment hash sought by HTLC (always 64 characters)
 
 .RE
 
-The following additional fields are usually present, but will not be for some
+If \fBout_channel\fR is present:
-variants of status \fIlocal_failed\fR (if it failed before we determined these):
 
 .RS
 .IP \[bu]
-\fIout_channel\fR: the short_channel_id of to which the outgoing htlc is supposed to be forwarded\.
+\fBfee_msat\fR (msat): the amount this paid in fees
 .IP \[bu]
-\fIfee\fR, \fIfee_msat\fR: fee offered for forwarding the htlc in msatoshi\.
+\fBout_msat\fR (msat): the amount we sent out the \fIout_channel\fR
-.IP \[bu]
-\fIout_msatoshi\fR, \fIout_msat\fR - amount of msatoshis to be forwarded\.
 
 .RE
 
-The following fields may be offered, but for old forgotten HTLCs they will be omitted:
+If \fBstatus\fR is "settled" or "failed":
 
 .RS
 .IP \[bu]
-\fIpayment_hash\fR - the payment_hash belonging to the HTLC\.
+\fBresolved_time\fR (number): the UNIX timestamp when this was resolved
 
 .RE
 
-If the status is not 'offered', the following additional fields are present:
+If \fBstatus\fR is "local_failed" or "failed":
 
 .RS
 .IP \[bu]
-\fIresolved_time\fR - timestamp when htlc was resolved (settled or failed)\.
+\fBfailcode\fR (u32, optional): the numeric onion code returned
+.IP \[bu]
+\fBfailreason\fR (string, optional): the name of the onion code returned
 
 .RE
 .SH AUTHOR
@@ -79,4 +77,4 @@ Rene Pickhardt \fI<r.pickhardt@gmail.com\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:b374dbf5f639ad8782b4ad2ff515f25b22a4407ef77f2e0904c975d1a7ccfbe4
+\" SHA256STAMP:c2fd8db0d86c538202c27c14bbfbbca7319d1664d22290d6ac7605d1b3160cb9

doc/lightning-listforwards.7.md

@@ -21,30 +21,26 @@ on the given in/out channel are returned.
 RETURN VALUE
 ------------
 
-On success one array will be returned: *forwards* with htlcs that have
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-been processed
+On success, an object containing **forwards** is returned.  It is an array of objects, where each object contains:
+- **in_channel** (short_channel_id): the channel that received the HTLC
+- **in_msat** (msat): the value of the incoming HTLC
+- **status** (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed")
+- **received_time** (number): the UNIX timestamp when this was received
+- **out_channel** (short_channel_id, optional): the channel that the HTLC was forwarded to
+- **payment_hash** (hex, optional): payment hash sought by HTLC (always 64 characters)
 
-Each entry in *forwards* will include:
+If **out_channel** is present:
-- *in\_channel*: the short\_channel\_id of the channel that recieved the incoming htlc.
+  - **fee_msat** (msat): the amount this paid in fees
-- *in\_msatoshi*, *in\_msat* - amount of msatoshis that are forwarded to this node.
+  - **out_msat** (msat): the amount we sent out the *out_channel*
-- *status*: status can be either *offered* if the routing process is still ongoing,
-*settled* if the routing process is completed or *failed* if the routing process could not be completed.
-- *received\_time*: timestamp when incoming htlc was received.
 
-The following additional fields are usually present, but will not be for some
+If **status** is "settled" or "failed":
-variants of status *local\_failed* (if it failed before we determined these):
+  - **resolved_time** (number): the UNIX timestamp when this was resolved
 
-- *out\_channel*: the short\_channel\_id of to which the outgoing htlc is supposed to be forwarded.
+If **status** is "local_failed" or "failed":
-- *fee*, *fee\_msat*: fee offered for forwarding the htlc in msatoshi.
+  - **failcode** (u32, optional): the numeric onion code returned
-- *out\_msatoshi*, *out\_msat* - amount of msatoshis to be forwarded.
+  - **failreason** (string, optional): the name of the onion code returned
-
+[comment]: # (GENERATE-FROM-SCHEMA-END)
-The following fields may be offered, but for old forgotten HTLCs they will be omitted:
-
-- *payment\_hash* - the payment_hash belonging to the HTLC.
-
-If the status is not 'offered', the following additional fields are present:
-
-- *resolved\_time* - timestamp when htlc was resolved (settled or failed).
 
 AUTHOR
 ------
@@ -61,3 +57,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:4d4179b29525707c4c1a22aa56dc46c0875562a43f5bc7d2b7d3838b32b5bad0)

doc/schemas/getsharedsecret.schema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [ "shared_secret" ],
+    "properties": {
+	"shared_secret": {
+	    "type": "hex",
+	    "description": "the SHA-2 of the compressed encoding of the shared secp256k1 point",
+	    "maxLength": 64,
+	    "minLength": 64
+	}
+    }
+}

doc/schemas/help.schema.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "help" ],
+    "properties": {
+	"help": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": true,
+		"required": [ "command", "category", "description", "verbose" ],
+		"properties": {
+		    "command": {
+			"type": "string",
+			"description": "the command"
+		    },
+		    "category": {
+			"type": "string",
+			"description": "the category for this command (useful for grouping)"
+		    },
+		    "description": {
+			"type": "string",
+			"description": "a one-line description of the purpose of this command"
+		    },
+		    "verbose": {
+			"type": "string",
+			"description": "a full description of this command (including whether it's deprecated)"
+		    }
+		}
+	    }
+	},
+	"format-hint": { }
+    }
+}

doc/schemas/invoice.schema.json

@@ -0,0 +1,42 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "payment_hash", "expires_at", "bolt11" ],
+    "properties": {
+	"bolt11": {
+	    "type": "string",
+	    "description": "the bolt11 string"
+	},
+	"payment_hash": {
+	    "type": "hex",
+	    "description": "the hash of the *payment_preimage* which will prove payment",
+	    "maxLength": 64,
+	    "minLength": 64
+	},
+	"expires_at": {
+	    "type": "u64",
+	    "description": "UNIX timestamp of when invoice expires"
+	},
+	"warning_capacity": {
+	    "type": "string",
+	    "description": "even using all possible channels, there's not enough incoming capacity to pay this invoice."
+	},
+	"warning_offline": {
+	    "type": "string",
+	    "description": "there would be enough incoming capacity, but some channels are offline, so there isn't."
+	},
+	"warning_deadends": {
+	    "type": "string",
+	    "description": "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": {
+	    "type": "string",
+	    "description": "there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't."
+	},
+	"warning_mpp": {
+	    "type": "string",
+	    "description": "there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments."
+	}
+    }
+}

doc/schemas/listchannels.schema.json

@@ -0,0 +1,77 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "channels" ],
+    "properties": {
+	"channels": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": true,
+		"required": [ "source", "destination", "short_channel_id", "public", "amount_msat", "message_flags", "channel_flags", "active", "last_update", "base_fee_millisatoshi", "fee_per_millionth", "delay", "htlc_minimum_msat", "features" ],
+		"properties": {
+		    "source": {
+			"type": "pubkey",
+			"description": "the source node"
+		    },
+		    "destination": {
+			"type": "pubkey",
+			"description": "the destination node"
+		    },
+		    "public": {
+			"type": "boolean",
+			"description": "true if this is announced (otherwise it must be our channel)"
+		    },
+		    "amount_msat": {
+			"type": "msat",
+			"description": "the total capacity of this channel (always a whole number of satoshis)"
+		    },
+		    "message_flags": {
+			"type": "u8",
+			"description": "as defined by BOLT #7"
+		    },
+		    "channel_flags": {
+			"type": "u8",
+			"description": "as defined by BOLT #7"
+		    },
+		    "active": {
+			"type": "boolean",
+			"description": "true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing"
+		    },
+		    "last_update": {
+			"type": "u32",
+			"description": "UNIX timestamp on the last channel_update from *source*"
+		    },
+		    "base_fee_millisatoshi": {
+			"type": "u32",
+			"description": "Base fee changed by *source* to use this channel"
+		    },
+		    "fee_per_millionth": {
+			"type": "u32",
+			"description": "Proportional fee changed by *source* to use this channel, in parts-per-million"
+		    },
+		    "delay": {
+			"type": "u32",
+			"description": "The number of blocks delay required by *source* to use this channel"
+		    },
+		    "htlc_minimum_msat": {
+			"type": "msat",
+			"description": "The smallest payment *source* will allow via this channel"
+		    },
+		    "satoshis": {
+			"deprecated": true
+		    },
+		    "htlc_maximum_msat": {
+			"type": "msat",
+			"description": "The largest payment *source* will allow via this channel"
+		    },
+		    "features": {
+			"type": "hex",
+			"description": "BOLT #9 features bitmap for this channel"
+		    }
+		}
+	    }
+	}
+    }
+}

doc/schemas/listforwards.schema.json

@@ -0,0 +1,205 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "forwards" ],
+    "properties": {
+	"forwards": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": true,
+		"required": [ "in_channel", "in_msat", "status", "received_time" ],
+		"properties": {
+		    "in_channel": {
+			"type": "short_channel_id",
+			"description": "the channel that received the HTLC"
+		    },
+		    "in_msatoshi": {
+			"deprecated": true
+		    },
+		    "in_msat": {
+			"type": "msat",
+			"description": "the value of the incoming HTLC"
+		    },
+		    "status": {
+			"type": "string",
+			"enum": [ "offered", "settled", "local_failed", "failed" ],
+			"description": "still ongoing, completed, failed locally, or failed after forwarding"
+		    },
+		    "received_time": {
+			"type": "number",
+			"description": "the UNIX timestamp when this was received"
+		    },
+		    "out_channel": {
+			"type": "short_channel_id",
+			"description": "the channel that the HTLC was forwarded to"
+		    },
+		    "payment_hash": {
+			"type": "hex",
+			"description": "payment hash sought by HTLC",
+			"maxLength": 64,
+			"minLength": 64
+		    }
+		},
+		"allOf": [
+		    {
+			"if": {
+			    "required": [ "out_channel" ]
+			},
+			"then": {
+			    "additionalProperties": false,
+			    "required": [ "fee_msat", "out_msat" ],
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"resolved_time": { },
+				"out_channel": { },
+				"payment_hash": { },
+				"failcode": { },
+				"failreason": { },
+				"fee": {
+				    "deprecated": true
+				},
+				"fee_msat": {
+				    "type": "msat",
+				    "description": "the amount this paid in fees"
+				},
+				"out_msatoshi": {
+				    "deprecated": true
+				},
+				"out_msat": {
+				    "type": "msat",
+				    "description": "the amount we sent out the *out_channel*"
+				}
+			    }
+			},
+			"else": {
+			    "additionalProperties": false,
+			    "required": [ ],
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"resolved_time": { },
+				"payment_hash": { },
+				"failcode": { },
+				"failreason": { }
+			    }
+			}
+		    },
+		    {
+			"if": {
+			    "properties": {
+				"status": {
+				    "type": "string",
+				    "enum": [ "settled", "failed" ]
+				}
+			    }
+			},
+			"then": {
+			    "additionalProperties": false,
+			    "required": [ "resolved_time" ],
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"out_channel": { },
+				"payment_hash": { },
+				"fee": { },
+				"fee_msat": { },
+				"out_msatoshi": { },
+				"out_msat": { },
+				"failcode": { },
+				"failreason": { },
+				"resolved_time": {
+				    "type": "number",
+				    "description": "the UNIX timestamp when this was resolved"
+				}
+			    }
+			},
+			"else": {
+			    "additionalProperties": false,
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"out_channel": { },
+				"payment_hash": { },
+				"fee": { },
+				"fee_msat": { },
+				"failcode": { },
+				"failreason": { },
+				"out_msatoshi": { },
+				"out_msat": { }
+			    }
+			}
+		    },
+		    {
+			"if": {
+			    "properties": {
+				"status": {
+				    "type": "string",
+				    "enum": [ "local_failed", "failed" ]
+				}
+			    }
+			},
+			"then": {
+			    "additionalProperties": false,
+			    "required": [ ],
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"out_channel": { },
+				"payment_hash": { },
+				"fee": { },
+				"fee_msat": { },
+				"out_msatoshi": { },
+				"out_msat": { },
+				"resolved_time": { },
+				"failcode": {
+				    "type": "u32",
+				    "description": "the numeric onion code returned"
+				},
+				"failreason": {
+				    "type": "string",
+				    "description": "the name of the onion code returned"
+				}
+			    }
+			},
+			"else": {
+			    "additionalProperties": false,
+			    "required": [ ],
+			    "properties": {
+				"in_channel": { },
+				"in_msatoshi": { },
+				"in_msat": { },
+				"status": { },
+				"received_time": { },
+				"out_channel": { },
+				"payment_hash": { },
+				"fee": { },
+				"fee_msat": { },
+				"out_msatoshi": { },
+				"out_msat": { },
+				"resolved_time": { }
+			    }
+			}
+		    }
+		]
+	    }
+	}
+    }
+}