doc/schemas: add some simple schemas and generate manpages from them

addgossip, check, createinvoice, createonion.

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

doc/lightning-addgossip.7

@@ -35,4 +35,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:40440e0a1159025d8fac68fc127029bf8539b103c0473d6bfaacd7cef5b56bea
+\" SHA256STAMP:dd8b1fd2ffcf7c57629a042f44f2fbc526d8892a2c933de6e82511721a8ffdea

doc/lightning-addgossip.7.md

@@ -22,7 +22,9 @@ messages within error replies.
 RETURN VALUE
 ------------
 
+[comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an empty object is returned.
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
 ------
@@ -39,3 +41,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff)

doc/lightning-check.7

@@ -23,9 +23,13 @@ find a route even if checking the parameters succeeds\.
 
 .SH RETURN VALUE
 
-On success, the \fIcommand_to_check\fR is returned\. On failure, the
-relevant RPC error is returned\.
+On success, an object is returned, containing:
 
+.RS
+.IP \[bu]
+\fBcommand_to_check\fR (string): the \fIcommand_to_check\fR argument
+
+.RE
 .SH AUTHOR
 
 Mark Beckwith \fI<wythe@intrig.com\fR> and Rusty Russell
@@ -35,4 +39,4 @@ Mark Beckwith \fI<wythe@intrig.com\fR> and Rusty Russell
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:8ff7c586849eae5646f182b088351b4a5baa61e9e628a31763a6647e74a7fc0a
+\" SHA256STAMP:9e78651117d3546edaf5150621630ee5dc4ccefd6e6a17b52b9dc8f86e8ba0c9

doc/lightning-check.7.md

@@ -23,8 +23,10 @@ find a route even if checking the parameters succeeds.
 RETURN VALUE
 ------------
 
-On success, the *command\_to\_check* is returned. On failure, the
-relevant RPC error is returned.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **command_to_check** (string): the *command_to_check* argument
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
 ------
@@ -37,3 +39,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:5b399ee88a5fb6b7eac0e1ac349a68a8715154f8c6468aedf446c703c91ac165)

doc/lightning-createinvoice.7

@@ -28,9 +28,41 @@ the invoice\.
 
 .SH RETURN VALUE
 
-On success, an invoice object is returned, as per \fBlistinvoices\fR(7)\.
+(Note: the return format is the same as \fBlightning-listinvoices\fR(7))\.
 
 
+On success, an object is returned, containing:
+
+.RS
+.IP \[bu]
+\fBlabel\fR (string): the label for the invoice
+.IP \[bu]
+\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
+.IP \[bu]
+\fBstatus\fR (string): Whether it has been paid, or can no longer be paid (one of "paid", "expired", "unpaid")
+.IP \[bu]
+\fBdescription\fR (string): Description extracted from \fBbolt11\fR or \fBbolt12\fR
+.IP \[bu]
+\fBexpires_at\fR (u64): UNIX timestamp of when invoice expires (or expired)
+.IP \[bu]
+\fBbolt11\fR (string, optional): the bolt11 string (always present unless \fBbolt12\fR is)
+.IP \[bu]
+\fBbolt12\fR (string, optional): the bolt12 string instead of \fBbolt11\fR (\fBexperimental-offers\fR only)
+.IP \[bu]
+\fBamount_msat\fR (msat, optional): The amount of the invoice (if it has one)
+.IP \[bu]
+\fBpay_index\fR (u64, optional): Incrementing id for when this was paid (\fBstatus\fR \fIpaid\fR only)
+.IP \[bu]
+\fBamount_received_msat\fR (msat, optional): Amount actually received (\fBstatus\fR \fIpaid\fR only)
+.IP \[bu]
+\fBpaid_at\fR (u64, optional): UNIX timestamp of when invoice was paid (\fBstatus\fR \fIpaid\fR only)
+.IP \[bu]
+\fBpayment_preimage\fR (hex, optional): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters)
+.IP \[bu]
+\fBlocal_offer_id\fR (hex, optional): the \fIid\fR of our offer which created this invoice (\fBexperimental-offers\fR only)\. (always 64 characters)
+
+.RE
+
 On failure, an error is returned and no invoice is created\. If the
 lightning process fails before responding, the caller should use
 \fBlightning-listinvoices\fR(7) to query whether this invoice was created or
@@ -53,10 +85,10 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 .SH SEE ALSO
 
 \fBlightning-invoice\fR(7), \fBlightning-listinvoices\fR(7), \fBlightning-delinvoice\fR(7),
-\fBlightning-getroute\fR(7), \fBlightning-sendpay\fR(7)\.
+\fBlightning-getroute\fR(7), \fBlightning-sendpay\fR(7), \fBlightning-offer\fR(7)\.
 
 .SH RESOURCES
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:155724c3e3130ed7f96d50a37dff99711dfcb4056c57d7eeb488fdb2b7925839
+\" SHA256STAMP:2d654675f966516a0fb0553f66e5bacd3ab96482d20cd9701a84e15ae49a4d92

doc/lightning-createinvoice.7.md

@@ -28,7 +28,24 @@ the invoice.
 RETURN VALUE
 ------------
 
-On success, an invoice object is returned, as per listinvoices(7).
+(Note: the return format is the same as lightning-listinvoices(7)).
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **label** (string): the label for the invoice
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **status** (string): Whether it has been paid, or can no longer be paid (one of "paid", "expired", "unpaid")
+- **description** (string): Description extracted from **bolt11** or **bolt12**
+- **expires_at** (u64): UNIX timestamp of when invoice expires (or expired)
+- **bolt11** (string, optional): the bolt11 string (always present unless **bolt12** is)
+- **bolt12** (string, optional): the bolt12 string instead of **bolt11** (**experimental-offers** only)
+- **amount_msat** (msat, optional): The amount of the invoice (if it has one)
+- **pay_index** (u64, optional): Incrementing id for when this was paid (**status** *paid* only)
+- **amount_received_msat** (msat, optional): Amount actually received (**status** *paid* only)
+- **paid_at** (u64, optional): UNIX timestamp of when invoice was paid (**status** *paid* only)
+- **payment_preimage** (hex, optional): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+- **local_offer_id** (hex, optional): the *id* of our offer which created this invoice (**experimental-offers** only). (always 64 characters)
+[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
@@ -48,10 +65,11 @@ SEE ALSO
 --------
 
 lightning-invoice(7), lightning-listinvoices(7), lightning-delinvoice(7),
-lightning-getroute(7), lightning-sendpay(7).
+lightning-getroute(7), lightning-sendpay(7), lightning-offer(7).
 
 RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:95a2fbf9c94fa1e01a322658035473c694bfb93e02d32c2cefafe6ef5b676695)

doc/lightning-createonion.7

@@ -104,9 +104,25 @@ routing\.
 
 .SH RETURN VALUE
 
-On success, an object containing the onion and the shared secrets will be
-returned\. Otherwise an error will be reported\. The following example is the
-result of calling \fIcreateonion\fR with the above hops parameter:
+On success, an object is returned, containing:
+
+.RS
+.IP \[bu]
+\fBonion\fR (hex): the onion packet (\fIonion_size\fR bytes)
+.IP \[bu]
+\fBshared_secrets\fR (array of hexs): one shared secret for each node in the \fIhops\fR parameter:
+.RS
+.IP \[bu]
+the shared secret with this hop (always 64 characters)
+
+.RE
+
+
+.RE
+.SH EXAMPLE
+
+The following example is the result of calling \fIcreateonion\fR with the
+above hops parameter:
 
 .nf
 .RS
@@ -137,4 +153,4 @@ Christian Decker \fI<decker.christian@gmail.com\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:d32334049025248f8b6088afed4e3322be75815ea6b976f79a007c619518f98a
+\" SHA256STAMP:c21aa197637bea17068072cd5907ad3302b48586067a8a5a8d748fd8e7e0a668

doc/lightning-createonion.7.md

@@ -92,9 +92,18 @@ routing.
 RETURN VALUE
 ------------
 
-On success, an object containing the onion and the shared secrets will be
-returned. Otherwise an error will be reported. The following example is the
-result of calling *createonion* with the above hops parameter:
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **onion** (hex): the onion packet (*onion_size* bytes)
+- **shared_secrets** (array of hexs): one shared secret for each node in the *hops* parameter:
+  - the shared secret with this hop (always 64 characters)
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+EXAMPLE
+-------
+
+The following example is the result of calling *createonion* with the
+above hops parameter:
 
 ```json
 {
@@ -126,3 +135,4 @@ RESOURCES
 Main web site: <https://github.com/ElementsProject/lightning>
 
 [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md
+[comment]: # ( SHA256STAMP:a5a64325f4232f27bccbbe1c9fc62bfb602ba60c81f46a1ef2df25b06dac807e)

doc/schemas/addgossip.schema.json

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

doc/schemas/check.schema.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+	"command_to_check": {
+	    "type": "string",
+	    "description": "the *command_to_check* argument"
+	}
+    },
+    "required": [ "command_to_check" ]
+}

doc/schemas/createinvoice.schema.json

@@ -0,0 +1,67 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "label", "payment_hash", "status", "description", "expires_at" ],
+    "properties": {
+	"label": {
+	    "type": "string",
+	    "description": "the label for the invoice"
+	},
+	"bolt11": {
+	    "type": "string",
+	    "description": "the bolt11 string (always present unless **bolt12** is)"
+	},
+	"bolt12": {
+	    "type": "string",
+	    "description": "the bolt12 string instead of **bolt11** (**experimental-offers** only)"
+	},
+	"payment_hash": {
+	    "type": "hex",
+	    "description": "the hash of the *payment_preimage* which will prove payment",
+	    "maxLength": 64,
+	    "minLength": 64
+	},
+	"amount_msat": {
+	    "type": "msat",
+	    "description": "The amount of the invoice (if it has one)"
+	},
+	"status": {
+	    "type": "string",
+	    "enum": [ "paid", "expired", "unpaid" ],
+	    "description": "Whether it has been paid, or can no longer be paid"
+	},
+	"description": {
+	    "type": "string",
+	    "description": "Description extracted from **bolt11** or **bolt12**"
+	},
+	"expires_at": {
+	    "type": "u64",
+	    "description": "UNIX timestamp of when invoice expires (or expired)"
+	},
+	"pay_index": {
+	    "type": "u64",
+	    "description": "Incrementing id for when this was paid (**status** *paid* only)"
+	},
+	"amount_received_msat": {
+	    "type": "msat",
+	    "description": "Amount actually received (**status** *paid* only)"
+	},
+	"paid_at": {
+	    "type": "u64",
+	    "description": "UNIX timestamp of when invoice was paid (**status** *paid* only)"
+	},
+	"payment_preimage": {
+	    "type": "hex",
+	    "description": "the proof of payment: SHA256 of this **payment_hash**",
+	    "maxLength": 64,
+	    "minLength": 64
+	},
+	"local_offer_id": {
+	    "type": "hex",
+	    "description": "the *id* of our offer which created this invoice (**experimental-offers** only).",
+	    "maxLength": 64,
+	    "minLength": 64
+	}
+    }
+}

doc/schemas/createonion.schema.json

@@ -0,0 +1,22 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "onion", "shared_secrets" ],
+    "properties": {
+	"onion": {
+	    "type": "hex",
+	    "description": "the onion packet (*onion_size* bytes)"
+	},
+	"shared_secrets": {
+	    "type": "array",
+	    "description": "one shared secret for each node in the *hops* parameter",
+	    "items": {
+		"type": "hex",
+		"description": "the shared secret with this hop",
+		"maxLength": 64,
+		"minLength": 64
+	    }
+	}
+    }
+}