doc/schemas: listfunds, listinvoices, listnodes, listoffers

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

doc/lightning-listinvoices.7

@@ -18,19 +18,41 @@ query parameters can be used at once\.
 
 .SH RETURN VALUE
 
-On success, an array \fIinvoices\fR of objects is returned\. Each object contains
+On success, an object containing \fBinvoices\fR is returned\.  It is an array of objects, where each object contains:
-\fIlabel\fR, \fIdescription\fR, \fIpayment_hash\fR, \fIstatus\fR (one of \fIunpaid\fR, \fIpaid\fR or \fIexpired\fR),
-\fIpayment_preimage\fR (for paid invoices), and \fIexpires_at\fR (a UNIX
-timestamp)\.  If the \fImsatoshi\fR argument to \fBlightning-invoice\fR(7) was not "any",
-there will be an \fImsatoshi\fR field as a number, and \fIamount_msat\fR as the same
-number ending in \fImsat\fR\.  If the invoice was created with a bolt11 string,
-there will be a \fIbolt11\fR field\.
-If the invoice \fIstatus\fR is \fIpaid\fR, there will be a
-\fIpay_index\fR field and an \fImsatoshi_received\fR field (which may be slightly
-greater than \fImsatoshi\fR as some overpaying is permitted to allow clients to
-obscure payment paths); there will also be an \fIamount_received_msat\fR field
-with the same number as \fImsatoshi_received\fR but ending in \fImsat\fR\.
 
+.RS
+.IP \[bu]
+\fBlabel\fR (string): unique label supplied at invoice creation
+.IP \[bu]
+\fBdescription\fR (string): description used in 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's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
+.IP \[bu]
+\fBexpires_at\fR (u64): UNIX timestamp of when it will become / became unpayable
+.IP \[bu]
+\fBamount_msat\fR (msat, optional): the amount required to pay this invoice
+.IP \[bu]
+\fBbolt11\fR (string, optional): the BOLT11 string (always present unless \fIbolt12\fR is)
+.IP \[bu]
+\fBbolt12\fR (string, optional): the BOLT12 string (always present unless \fIbolt11\fR is)
+
+.RE
+
+If \fBstatus\fR is "paid":
+
+.RS
+.IP \[bu]
+\fBpay_index\fR (u64): Unique incrementing index for this payment
+.IP \[bu]
+\fBamount_received_msat\fR (msat): the amount actually received (could be slightly greater than \fIamount_msat\fR, since clients may overpay)
+.IP \[bu]
+\fBpaid_at\fR (u64): UNIX timestamp of when it was paid
+.IP \[bu]
+\fBpayment_preimage\fR (hex): proof of payment (always 64 characters)
+
+.RE
 .SH AUTHOR
 
 Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
@@ -43,4 +65,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:3d3cef4fa52635fa5c515959718e017173c3fffdc32ca7066fea3b82cf93758d
+\" SHA256STAMP:9567c510a5ab2fd47149c7f6e213c65eaa0ab5f29adbe649838986d70049b56b

doc/lightning-listinvoices.7.md

@@ -20,18 +20,23 @@ query parameters can be used at once.
 RETURN VALUE
 ------------
 
-On success, an array *invoices* of objects is returned. Each object contains
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-*label*, *description*, *payment\_hash*, *status* (one of *unpaid*, *paid* or *expired*),
+On success, an object containing **invoices** is returned.  It is an array of objects, where each object contains:
-*payment\_preimage* (for paid invoices), and *expires\_at* (a UNIX
+- **label** (string): unique label supplied at invoice creation
-timestamp).  If the *msatoshi* argument to lightning-invoice(7) was not "any",
+- **description** (string): description used in the invoice
-there will be an *msatoshi* field as a number, and *amount\_msat* as the same
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
-number ending in *msat*.  If the invoice was created with a bolt11 string,
+- **status** (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
-there will be a *bolt11* field.
+- **expires_at** (u64): UNIX timestamp of when it will become / became unpayable
-If the invoice *status* is *paid*, there will be a
+- **amount_msat** (msat, optional): the amount required to pay this invoice
-*pay\_index* field and an *msatoshi\_received* field (which may be slightly
+- **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is)
-greater than *msatoshi* as some overpaying is permitted to allow clients to
+- **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is)
-obscure payment paths); there will also be an *amount\_received\_msat* field
+
-with the same number as *msatoshi\_received* but ending in *msat*.
+If **status** is "paid":
+  - **pay_index** (u64): Unique incrementing index for this payment
+  - **amount_received_msat** (msat): the amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)
+  - **paid_at** (u64): UNIX timestamp of when it was paid
+  - **payment_preimage** (hex): proof of payment (always 64 characters)
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
 ------
@@ -48,3 +53,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:912e82238ba0d47bae3ce8f8e16f22cf5f2c62936efb150092f17766abdb4455)

doc/lightning-listnodes.7

@@ -24,35 +24,34 @@ The \fBlistnodes\fR command returns nodes the node has learned about via gossip
 .fi
 .SH RETURN VALUE
 
-On success, the command will return a list of nodes, each object represents a node, with the following details:
+On success, an object containing \fBnodes\fR is returned\.  It is an array of objects, where each object contains:
 
 .RS
 .IP \[bu]
-\fInodeid\fR: A string that represents the node id\.
+\fBnodeid\fR (pubkey): the public key of the node
+.IP \[bu]
+\fBlast_update\fR (u32, optional): A node_announcement has been received for this node (UNIX timestamp)
 
 .RE
 
-For nodes which have sent a node_announcement message, the following
+If \fBlast_update\fR is present:
-are also returned:
 
 .RS
 .IP \[bu]
-\fIalias\fR: A string that represents alias of the node on the network\.
+\fBalias\fR (string): The fun alias this node advertized (up to 32 characters)
 .IP \[bu]
-\fIcolor\fR: A string that represents the personal color of the node\.
+\fBcolor\fR (hex): The favorite RGB color this node advertized (always 6 characters)
 .IP \[bu]
-\fIlast_timestamp\fR: An integer that represents the timestamp of the last-received node_announcement message\.
+\fBfeatures\fR (hex): BOLT #9 features bitmap this node advertized
 .IP \[bu]
-\fIfeatures\fR: A string that represents the features value\.
+\fBaddresses\fR (array of objects): The addresses this node advertized:
-.IP \[bu]
-\fIaddresses\fR: An array that represents the addreses avaible\. Each address is represented with an object with the following properties:
 .RS
 .IP \[bu]
-\fItype\fR: A string that represents the address type (ipv4 or ipv6)\.
+\fBtype\fR (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3")
 .IP \[bu]
-\fIaddress\fR: A string that represents the address value\.
+\fBaddress\fR (string): address in expected format for \fItype\fR
 .IP \[bu]
-\fIport\fR: An integer that represents the port number where the node are listening\.
+\fBport\fR (u16): port number
 
 .RE
 
@@ -102,4 +101,4 @@ FIXME:
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:901b147ccbfe0a18310a44ca848b623e83fa3c68912dacadefd045d4a2095523
+\" SHA256STAMP:ab3ff8fd9153e01f861080fade794a4899397fbcca65d0c3af69b9bb5f1144fb

doc/lightning-listnodes.7.md

@@ -26,21 +26,20 @@ EXAMPLE JSON REQUEST
 RETURN VALUE
 ------------
 
-On success, the command will return a list of nodes, each object represents a node, with the following details:
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object containing **nodes** is returned.  It is an array of objects, where each object contains:
+- **nodeid** (pubkey): the public key of the node
+- **last_update** (u32, optional): A node_announcement has been received for this node (UNIX timestamp)
 
-- *nodeid*: A string that represents the node id.
+If **last_update** is present:
-
+  - **alias** (string): The fun alias this node advertized (up to 32 characters)
-For nodes which have sent a node_announcement message, the following
+  - **color** (hex): The favorite RGB color this node advertized (always 6 characters)
-are also returned:
+  - **features** (hex): BOLT #9 features bitmap this node advertized
-
+  - **addresses** (array of objects): The addresses this node advertized:
-- *alias*: A string that represents alias of the node on the network.
+    - **type** (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3")
-- *color*: A string that represents the personal color of the node.
+    - **address** (string): address in expected format for *type*
-- *last_timestamp*: An integer that represents the timestamp of the last-received node_announcement message.
+    - **port** (u16): port number
-- *features*: A string that represents the features value.
+[comment]: # (GENERATE-FROM-SCHEMA-END)
-- *addresses*: An array that represents the addreses avaible. Each address is represented with an object with the following properties:
-  - *type*: A string that represents the address type (ipv4 or ipv6).
-  - *address*: A string that represents the address value.
-  - *port*: An integer that represents the port number where the node are listening.
   
 On failure, one of the following error codes may be returned:
  
@@ -84,3 +83,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
+[comment]: # ( SHA256STAMP:8c35b13edbb60a3403da9317b3177c0a5b9826cf0f06077424e94b1ddb7f1697)

doc/lightning-listoffers.7

@@ -29,27 +29,21 @@ set and is true, only offers with \fBactive\fR true are returned\.
 .fi
 .SH RETURN VALUE
 
-On success, an array \fIoffers\fR of objects is returned\. Each object contains:
+On success, an object containing \fBoffers\fR is returned\.  It is an array of objects, where each object contains:
 
 .RS
 .IP \[bu]
-\fIoffer_id\fR: the hash of the offer\.
+\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
 .IP \[bu]
-\fIactive\fR: true
+\fBactive\fR (boolean): whether this can still be used
 .IP \[bu]
-\fIsingle_use\fR: true if \fIsingle_use\fR was specified\.
+\fBsingle_use\fR (boolean): whether this expires as soon as it's paid
 .IP \[bu]
-\fIbolt12\fR: the bolt12 offer, starting with "lno1"
+\fBbolt12\fR (string): the bolt12 encoding of the offer
 .IP \[bu]
-\fIused\fR: true if an associated invoice has been paid\.
+\fBused\fR (boolean): True if an associated invoice has been paid
-
-.RE
-
-Optionally:
-
-.RS
 .IP \[bu]
-\fIlabel\fR: the user-specified label\.
+\fBlabel\fR (string, optional): the (optional) user-specified label
 
 .RE
 .SH EXAMPLE JSON RESPONSE
@@ -88,4 +82,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:bc4abe90e5475a272c61af45e4f00be9f3fab89d3adca767b577b46d70d33726
+\" SHA256STAMP:919c848c1d8fa62be1d6c9453c90073306bc168a6969afd836a00861b61b0367

doc/lightning-listoffers.7.md

@@ -29,17 +29,15 @@ EXAMPLE JSON REQUEST
 RETURN VALUE
 ------------
 
-On success, an array *offers* of objects is returned. Each object contains:
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-
+On success, an object containing **offers** is returned.  It is an array of objects, where each object contains:
-* *offer_id*: the hash of the offer.
+- **offer_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
-* *active*: true
+- **active** (boolean): whether this can still be used
-* *single_use*: true if *single_use* was specified.
+- **single_use** (boolean): whether this expires as soon as it's paid
-* *bolt12*: the bolt12 offer, starting with "lno1"
+- **bolt12** (string): the bolt12 encoding of the offer
-* *used*: true if an associated invoice has been paid.
+- **used** (boolean): True if an associated invoice has been paid
-
+- **label** (string, optional): the (optional) user-specified label
-Optionally:
+[comment]: # (GENERATE-FROM-SCHEMA-END)
-* *label*: the user-specified label.
-
 
 EXAMPLE JSON RESPONSE
 -----
@@ -80,3 +78,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
+[comment]: # ( SHA256STAMP:94ee9c8562d592be0a15805fb3883ffff44d7e3319f58537fdeb30e5c3d5b9e7)

doc/schemas/listinvoices.schema.json

@@ -0,0 +1,118 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "invoices" ],
+    "properties": {
+	"invoices": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": true,
+		"required": [ "label", "description", "payment_hash", "status", "expires_at" ],
+		"properties": {
+		    "label": {
+			"type": "string",
+			"description": "unique label supplied at invoice creation"
+		    },
+		    "description": {
+			"type": "string",
+			"description": "description used in the invoice"
+		    },
+		    "payment_hash": {
+			"type": "hex",
+			"description": "the hash of the *payment_preimage* which will prove payment",
+			"maxLength": 64,
+			"minLength": 64
+		    },
+		    "status": {
+			"type": "string",
+			"enum": [ "unpaid", "paid", "expired" ],
+			"description": "Whether it's paid, unpaid or unpayable"
+		    },
+		    "expires_at": {
+			"type": "u64",
+			"description": "UNIX timestamp of when it will become / became unpayable"
+		    },
+		    "msatoshi": {
+			"deprecated": "true"
+		    },
+		    "amount_msat": {
+			"type": "msat",
+			"description": "the amount required to pay this invoice"
+		    },
+		    "bolt11": {
+			"type": "string",
+			"description": "the BOLT11 string (always present unless *bolt12* is)"
+		    },
+		    "bolt12": {
+			"type": "string",
+			"description": "the BOLT12 string (always present unless *bolt11* is)"
+		    }
+		},
+		"allOf": [
+		    {
+			"if": {
+			    "properties": {
+				"status": {
+				    "type": "string",
+				    "enum": [ "paid" ]
+				}
+			    }
+			},
+			"then": {
+			    "additionalProperties": false,
+			    "required": [ "pay_index", "amount_received_msat", "paid_at", "payment_preimage" ],
+			    "properties": {
+				"label": { },
+				"description": { },
+				"payment_hash": { },
+				"status": { },
+				"msatoshi": { },
+				"amount_msat": { },
+				"bolt11": { },
+				"bolt12": { },
+				"expires_at": { },
+				"pay_index": {
+				    "type": "u64",
+				    "description": "Unique incrementing index for this payment"
+				},
+				"msatoshi_received": {
+				    "deprecated": true
+				},
+				"amount_received_msat": {
+				    "type": "msat",
+				    "description": "the amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)"
+				},
+				"paid_at": {
+				    "type": "u64",
+				    "description": "UNIX timestamp of when it was paid"
+				},
+				"payment_preimage": {
+				    "type": "hex",
+				    "description": "proof of payment",
+				    "maxLength": 64,
+				    "minLength": 64
+				}
+			    }
+			},
+			"else": {
+			    "additionalProperties": false,
+			    "properties": {
+				"label": { },
+				"description": { },
+				"payment_hash": { },
+				"status": { },
+				"msatoshi": { },
+				"amount_msat": { },
+				"bolt11": { },
+				"bolt12": { },
+				"expires_at": { }
+			    }
+			}
+		    }
+		]
+	    }
+	}
+    }
+}

doc/schemas/listnodes.schema.json

@@ -0,0 +1,79 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "nodes" ],
+    "properties": {
+	"nodes": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": true,
+		"required": [ "nodeid" ],
+		"properties": {
+		    "nodeid": {
+			"type": "pubkey",
+			"description": "the public key of the node"
+		    },
+		    "last_update": {
+			"type": "u32",
+			"description": "A node_announcement has been received for this node (UNIX timestamp)"
+		    }
+		},
+		"allOf": [
+		    {
+			"if": {
+			    "required": [ "last_update" ]
+			},
+			"then": {
+			    "additionalProperties": false,
+			    "required": [ "last_update", "alias", "color", "features", "addresses" ],
+			    "properties": {
+				"last_update": { },
+				"alias": {
+				    "type": "string",
+				    "description": "The fun alias this node advertized",
+				    "maxLength": 32
+				},
+				"color": {
+				    "type": "hex",
+				    "description": "The favorite RGB color this node advertized",
+				    "minLength": 6,
+				    "maxLength": 6
+				},
+				"features": {
+				    "type": "hex",
+				    "description": "BOLT #9 features bitmap this node advertized"
+				},
+				"addresses": {
+				    "type": "array",
+				    "description": "The addresses this node advertized",
+				    "items": {
+					"type": "object",
+					"required": [ "type", "address", "port" ],
+					"additionalProperties": false,
+					"properties": {
+					    "type": {
+						"type": "string",
+						"enum": [ "ipv4", "ipv6", "torv2", "torv3" ],
+						"description": "Type of connection"
+					    },
+					    "address": {
+						"type": "string",
+						"description": "address in expected format for *type*"
+					    },
+					    "port": {
+						"type": "u16",
+						"description": "port number"
+					    }
+					}
+				    }
+				}
+			    }
+			}
+		    }
+		]
+	    }
+	}
+    }
+}

doc/schemas/listoffers.schema.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "offers" ],
+    "properties": {
+	"offers": {
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"additionalProperties": false,
+		"required": [ "offer_id", "active", "single_use", "bolt12", "used" ],
+		"properties": {
+		    "offer_id": {
+			"type": "hex",
+			"description": "the id of this offer (merkle hash of non-signature fields)",
+			"maxLength": 64,
+			"minLength": 64
+		    },
+		    "active": {
+			"type": "boolean",
+			"description": "whether this can still be used"
+		    },
+		    "single_use": {
+			"type": "boolean",
+			"description": "whether this expires as soon as it's paid"
+		    },
+		    "bolt12": {
+			"type": "string",
+			"description": "the bolt12 encoding of the offer"
+		    },
+		    "used": {
+			"type": "boolean",
+			"description": "True if an associated invoice has been paid"
+		    },
+		    "label": {
+			"type": "string",
+			"description": "the (optional) user-specified label"
+		    }
+		}
+	    }
+	}
+    }
+}

tests/test_plugin.py

@@ -1385,6 +1385,9 @@ def test_rpc_command_hook(node_factory):
     assert decoded["description"] == "rpc_command_1 modified this description"
     l1.daemon.wait_for_log("rpc_command hook 'invoice' already modified, ignoring.")
 
+    # Disable schema checking here!
+    schemas = l1.rpc.jsonschemas
+    l1.rpc.jsonschemas = {}
     # rpc_command_1 plugin sends a custom response to "listfunds"
     funds = l1.rpc.listfunds()
     assert funds[0] == "Custom rpc_command_1 result"
@@ -1404,6 +1407,8 @@ def test_rpc_command_hook(node_factory):
         l1.rpc.plugin_stop('rpc_command_1.py')
         l1.rpc.plugin_stop('rpc_command_2.py')
 
+    l1.rpc.jsonschemas = schemas
+
 
 def test_libplugin(node_factory):
     """Sanity checks for plugins made with libplugin"""