doc: fix listnodes schema, doc.

Shows the dangers of "additionalProperties": true. We didn't have an else clause, so our incorrect (and, with DF, incomplete!) schema was accepted. I despair of getting anyone else to write a decent schema with these semantics :( Changelog-Fixed: doc: listnodes fields now correctly documented. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
ElementsProject · Sep 1, 2021 · 91eee17 · 91eee17
1 parent 2770bcb
commit 91eee17
Show file tree

Hide file tree

Showing 3 changed files with 98 additions and 10 deletions.
diff --git a/doc/lightning-listnodes.7 b/doc/lightning-listnodes.7
diff --git a/doc/lightning-listnodes.7.md b/doc/lightning-listnodes.7.md
@@ -29,16 +29,25 @@ RETURN VALUE
 [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)
+- **last_timestamp** (u32, optional): A node_announcement has been received for this node (UNIX timestamp)
 
-If **last_update** is present:
+If **last_timestamp** is present:
   - **alias** (string): The fun alias this node advertized (up to 32 characters)
   - **color** (hex): The favorite RGB color this node advertized (always 6 characters)
   - **features** (hex): BOLT #9 features bitmap this node advertized
   - **addresses** (array of objects): The addresses this node advertized:
     - **type** (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3")
     - **address** (string): address in expected format for *type*
     - **port** (u16): port number
+
+If **option_will_fund** is present:
+  - **option_will_fund** (object):
+    - **lease_fee_base_msat** (msat): the fixed fee for a lease (whole number of satoshis)
+    - **lease_fee_basis** (u32): the proportional fee in basis points (parts per 10,000) for a lease
+    - **funding_weight** (u32): the onchain weight you'll have to pay for a lease
+    - **channel_fee_max_base_msat** (msat): the maximum base routing fee this node will charge during the lease
+    - **channel_fee_max_proportional_thousandths** (u32): the maximum proportional routing fee this node will charge during the lease (in thousandths, not millionths like channel_update)
+    - **compact_lease** (hex): the lease as represented in the node_announcement
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
 On failure, one of the following error codes may be returned:
@@ -83,4 +92,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
-[comment]: # ( SHA256STAMP:2f644d55512f5c03e3894341fb039fc1b7d2ebc5f210547fdb324d2f23689b37)
+[comment]: # ( SHA256STAMP:08959d1bce493b3d3c28fcc4b54e492feecc1062d960ea685899213327c8e768)
diff --git a/doc/schemas/listnodes.schema.json b/doc/schemas/listnodes.schema.json
@@ -15,21 +15,23 @@
 			"type": "pubkey",
 			"description": "the public key of the node"
 		    },
-		    "last_update": {
+		    "last_timestamp": {
 			"type": "u32",
 			"description": "A node_announcement has been received for this node (UNIX timestamp)"
 		    }
 		},
 		"allOf": [
 		    {
 			"if": {
-			    "required": [ "last_update" ]
+			    "required": [ "last_timestamp" ]
 			},
 			"then": {
 			    "additionalProperties": false,
-			    "required": [ "last_update", "alias", "color", "features", "addresses" ],
+			    "required": [ "nodeid", "last_timestamp", "alias", "color", "features", "addresses" ],
 			    "properties": {
-				"last_update": { },
+				"nodeid": { },
+				"last_timestamp": { },
+				"option_will_fund": { },
 				"alias": {
 				    "type": "string",
 				    "description": "The fun alias this node advertized",
@@ -70,6 +72,59 @@
 				    }
 				}
 			    }
+			},
+			"else": {
+			    "additionalProperties": false,
+			    "properties": {
+				"node_id": { }
+			    }
+			}
+		    },
+		    {
+			"if": {
+			    "required": [ "option_will_fund" ]
+			},
+			"then": {
+			    "additionalProperties": true,
+			    "required": [ "option_will_fund" ],
+			    "properties": {
+				"option_will_fund": {
+				    "type": "object",
+				    "additionalProperties": false,
+				    "required": [ "lease_fee_base_msat",
+						  "lease_fee_basis",
+						  "funding_weight",
+						  "channel_fee_max_base_msat",
+						  "channel_fee_max_proportional_thousandths",
+						  "compact_lease" ],
+				    "properties": {
+					"lease_fee_base_msat": {
+					    "type": "msat",
+					    "description": "the fixed fee for a lease (whole number of satoshis)"
+					},
+					"lease_fee_basis": {
+					    "type": "u32",
+					    "description": "the proportional fee in basis points (parts per 10,000) for a lease"
+					},
+					"funding_weight": {
+					    "type": "u32",
+					    "description": "the onchain weight you'll have to pay for a lease"
+					},
+					"channel_fee_max_base_msat": {
+					    "type": "msat",
+					    "description": "the maximum base routing fee this node will charge during the lease"
+					},
+					"channel_fee_max_proportional_thousandths": {
+					    "type": "u32",
+					    "description": "the maximum proportional routing fee this node will charge during the lease (in thousandths, not millionths like channel_update)"
+					},
+					"compact_lease": {
+					    "type": "hex",
+					    "description": "the lease as represented in the node_announcement"
+					}
+				    }
+				}
+			    }
 			}
 		    }
 		]