doc: use specific types in schema rather than "hex".

We have "secret" and "hash" types which are often more appropriate. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
ElementsProject · endothermicdev · Jan 30, 2023 · Jan 30, 2023 · Jan 30, 2023 · Jan 30, 2023
commit f1efb6589815e1bc393f340475f85182f50a1c5e
diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md
@@ -32,8 +32,8 @@ If **type** is "bolt12 offer", and **valid** is *true*:
   - **offer\_id** (hex): the id we use to identify this offer (always 64 characters)
   - **offer\_description** (string): the description of the purpose of the offer
   - **offer\_node\_id** (pubkey): public key of the offering node
-  - **offer\_chains** (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
-    - the genesis blockhash (always 64 characters)
+  - **offer\_chains** (array of hashs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
+    - the genesis blockhash
   - **offer\_metadata** (hex, optional): any metadata the creater of the offer includes
   - **offer\_currency** (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)
   - **currency\_minor\_unit** (u32, optional): the number of decimal places to apply to amount (if currency known)
@@ -239,13 +239,13 @@ If **type** is "bolt11 invoice", and **valid** is *true*:
   - **created\_at** (u64): the UNIX-style timestamp of the invoice
   - **expiry** (u64): the number of seconds this is valid after `created_at`
   - **payee** (pubkey): the public key of the recipient
-  - **payment\_hash** (hex): the hash of the *payment\_preimage* (always 64 characters)
+  - **payment\_hash** (hash): the hash of the *payment\_preimage*
   - **signature** (signature): signature of the *payee* on this invoice
   - **min\_final\_cltv\_expiry** (u32): the minimum CLTV delay for the final node
   - **amount\_msat** (msat, optional): Amount the invoice asked for
   - **description** (string, optional): the description of the purpose of the purchase
-  - **description\_hash** (hex, optional): the hash of the description, in place of *description* (always 64 characters)
-  - **payment\_secret** (hex, optional): the secret to hand to the payee node (always 64 characters)
+  - **description\_hash** (hash, optional): the hash of the description, in place of *description*
+  - **payment\_secret** (secret, optional): the secret to hand to the payee node
   - **features** (hex, optional): the features bitmap for this invoice
   - **payment\_metadata** (hex, optional): the payment\_metadata to put in the payment
   - **fallbacks** (array of objects, optional): onchain addresses:
@@ -303,4 +303,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:25247da6ea63f7fa229b7d25afd8cc2558ded16219c4a49ca3567dbb522f0153)
+[comment]: # ( SHA256STAMP:ba144aad8e34d9a8581161be01fa9a5e0107d068ad35411a278539503446768b)
diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md
@@ -22,13 +22,13 @@ On success, an object is returned, containing:
 - **created\_at** (u64): the UNIX-style timestamp of the invoice
 - **expiry** (u64): the number of seconds this is valid after *timestamp*
 - **payee** (pubkey): the public key of the recipient
-- **payment\_hash** (hex): the hash of the *payment\_preimage* (always 64 characters)
+- **payment\_hash** (hash): the hash of the *payment\_preimage*
 - **signature** (signature): signature of the *payee* on this invoice
 - **min\_final\_cltv\_expiry** (u32): the minimum CLTV delay for the final node
 - **amount\_msat** (msat, optional): Amount the invoice asked for
 - **description** (string, optional): the description of the purpose of the purchase
-- **description\_hash** (hex, optional): the hash of the description, in place of *description* (always 64 characters)
-- **payment\_secret** (hex, optional): the secret to hand to the payee node (always 64 characters)
+- **description\_hash** (hash, optional): the hash of the description, in place of *description*
+- **payment\_secret** (hash, optional): the secret to hand to the payee node
 - **features** (hex, optional): the features bitmap for this invoice
 - **payment\_metadata** (hex, optional): the payment\_metadata to put in the payment
 - **fallbacks** (array of objects, optional): onchain addresses:
@@ -71,4 +71,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:1d4a7f4577ffa26f34da9ea3a0ed2f7da26f86a4ce554b8bf20785a3de20fdfe)
+[comment]: # ( SHA256STAMP:d287a96b5495b4be07d8a20633b9a6d5179ef74fc33b1b517c1b201e1b86e9aa)
diff --git a/doc/lightning-delpay.7.md b/doc/lightning-delpay.7.md
@@ -42,7 +42,7 @@ payments will be returned -- one payment object for each partid.
 On success, an object containing **payments** is returned.  It is an array of objects, where each object contains:
 
 - **id** (u64): unique ID for this payment attempt
-- **payment\_hash** (hex): the hash of the *payment\_preimage* which will prove payment (always 64 characters)
+- **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): status of the payment (one of "pending", "failed", "complete")
 - **amount\_sent\_msat** (msat): the amount we actually sent, including fees
 - **created\_at** (u64): the UNIX timestamp showing when this payment was initiated
@@ -51,7 +51,7 @@ On success, an object containing **payments** is returned.  It is an array of ob
 - **amount\_msat** (msat, optional): the amount the destination received, if known
 - **completed\_at** (u64, optional): the UNIX timestamp showing when this payment was completed
 - **groupid** (u64, optional): Grouping key to disambiguate multiple attempts to pay an invoice or the same payment\_hash
-- **payment\_preimage** (hex, optional): proof of payment (always 64 characters)
+- **payment\_preimage** (secret, optional): proof of payment
 - **label** (string, optional): the label, if given to sendpay
 - **bolt11** (string, optional): the bolt11 string (if pay supplied one)
 - **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
@@ -107,4 +107,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:c6d248396e04a0ef3506dbd5319231cf8d4cb2522a4e039d5e3622aed5ab4496)
+[comment]: # ( SHA256STAMP:04fdf8931ea040a3433df9e25b1db1e808e733ad3a5b2586f6edd030ae6f165a)
diff --git a/doc/lightning-disableoffer.7.md b/doc/lightning-disableoffer.7.md
@@ -36,7 +36,7 @@ Note: the returned object is the same format as **listoffers**.
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 
-- **offer\_id** (hex): the merkle hash of the offer (always 64 characters)
+- **offer\_id** (hash): the merkle hash of the offer
 - **active** (boolean): Whether the offer can produce invoices/payments (always *false*)
 - **single\_use** (boolean): Whether the offer is disabled after first successful use
 - **bolt12** (string): The bolt12 string representing this offer
@@ -74,4 +74,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:339f2e5a5a587414ba6ad3e312c6cff5525bae86addb76bb5656665eeeef3dd6)
+[comment]: # ( SHA256STAMP:e03f739fb57f18205421785604ea542e931db42b1accfcb196dfc147a7c8bf75)
diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md
@@ -31,7 +31,7 @@ On success, an object containing **invoices** is returned.  It is an array of ob
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is)
 - **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is)
-- **local\_offer\_id** (hex, optional): the *id* of our offer which created this invoice (**experimental-offers** only). (always 64 characters)
+- **local\_offer\_id** (hash, optional): the *id* of our offer which created this invoice (**experimental-offers** only).
 - **invreq\_payer\_note** (string, optional): the optional *invreq\_payer\_note* from invoice\_request which created this invoice (**experimental-offers** only).
 
 If **status** is "paid":
@@ -58,4 +58,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:258d690221dce5a8811f361e59a5c0059190f140e420c65cd37cfd0987efea3a)
+[comment]: # ( SHA256STAMP:1b31938109207decabf1e0f25cc9607dc03de7f043f4e5fcfbfb8c85ffacec8c)
diff --git a/doc/lightning-listoffers.7.md b/doc/lightning-listoffers.7.md
@@ -32,7 +32,7 @@ RETURN VALUE
 [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** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
+- **offer\_id** (hash): the id of this offer (merkle hash of non-signature fields)
 - **active** (boolean): whether this can still be used
 - **single\_use** (boolean): whether this expires as soon as it's paid
 - **bolt12** (string): the bolt12 encoding of the offer
@@ -81,4 +81,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:b968ff5dd2eb57cb030c7a9fb73d3d305e69f23dc2ccd599573fb345e0f58385)
+[comment]: # ( SHA256STAMP:863d9f666cbbbd013b86b4075a7c8b7e7bda47049c562cba080d0a88626636a1)
diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md
@@ -19,7 +19,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object containing **pays** is returned.  It is an array of objects, where each object contains:
 
-- **payment\_hash** (hex): the hash of the *payment\_preimage* which will prove payment (always 64 characters)
+- **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): status of the payment (one of "pending", "failed", "complete")
 - **created\_at** (u64): the UNIX timestamp showing when this payment was initiated
 - **destination** (pubkey, optional): the final destination of the payment if known
@@ -31,7 +31,7 @@ On success, an object containing **pays** is returned.  It is an array of object
 
 If **status** is "complete":
 
-  - **preimage** (hex): proof of payment (always 64 characters)
+  - **preimage** (secret): proof of payment
   - **number\_of\_parts** (u64, optional): the number of parts for a successful payment (only if more than one).
 
 If **status** is "failed":
@@ -57,4 +57,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:adf164794675b251cbef10f5c40dd2e05812fc681641e0631126bae2a8bc8883)
+[comment]: # ( SHA256STAMP:716bcbf01d946c6e4da0bd2f6817c34e6471a1fcd2f0f388ce47984271285c72)
diff --git a/doc/lightning-offer.7.md b/doc/lightning-offer.7.md
@@ -94,7 +94,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 
-- **offer\_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
+- **offer\_id** (hash): the id of this offer (merkle hash of non-signature fields)
 - **active** (boolean): whether this can still be used (always *true*)
 - **single\_use** (boolean): whether this expires as soon as it's paid (reflects the *single\_use* parameter)
 - **bolt12** (string): the bolt12 encoding of the offer
@@ -131,4 +131,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:46e6bfcfe48f709e2f2068250e28b53bedafb782db42791e722d301515fce070)
+[comment]: # ( SHA256STAMP:3ad09aed48fb17db5fae6d401f21e50a4479e970199bd039b453868057829653)
diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md
@@ -43,7 +43,7 @@ On success, an object is returned, containing:
 
 - **label** (string): unique label supplied at invoice creation
 - **description** (string): description used in the invoice
-- **payment\_hash** (hex): the hash of the *payment\_preimage* which will prove payment (always 64 characters)
+- **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
 - **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
@@ -54,7 +54,7 @@ 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)
+  - **payment\_preimage** (secret): proof of payment
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -80,4 +80,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:a088e5202cb822518a2214b485083edf0a929290b17beb9a3930dd93d97411d0)
+[comment]: # ( SHA256STAMP:7646a92936e1e79dbefe9cacf418ee15f148db467d780a9b39b90d46ca522539)
diff --git a/doc/schemas/decode.schema.json b/doc/schemas/decode.schema.json
@@ -60,10 +60,8 @@
             "type": "array",
             "description": "which blockchains this offer is for (missing implies bitcoin mainnet only)",
             "items": {
-              "type": "hex",
-              "description": "the genesis blockhash",
-              "maxLength": 64,
-              "minLength": 64
+              "type": "hash",
+              "description": "the genesis blockhash"
             }
           },
           "offer_metadata": {
@@ -1270,10 +1268,8 @@
             "description": "Amount the invoice asked for"
           },
           "payment_hash": {
-            "type": "hex",
-            "description": "the hash of the *payment_preimage*",
-            "maxLength": 64,
-            "minLength": 64
+            "type": "hash",
+            "description": "the hash of the *payment_preimage*"
           },
           "signature": {
             "type": "signature",
@@ -1284,20 +1280,16 @@
             "description": "the description of the purpose of the purchase"
           },
           "description_hash": {
-            "type": "hex",
-            "description": "the hash of the description, in place of *description*",
-            "maxLength": 64,
-            "minLength": 64
+            "type": "hash",
+            "description": "the hash of the description, in place of *description*"
           },
           "min_final_cltv_expiry": {
             "type": "u32",
             "description": "the minimum CLTV delay for the final node"
           },
           "payment_secret": {
-            "type": "hex",
-            "description": "the secret to hand to the payee node",
-            "maxLength": 64,
-            "minLength": 64
+            "type": "secret",
+            "description": "the secret to hand to the payee node"
           },
           "features": {
             "type": "hex",

diff --git a/doc/schemas/decodepay.schema.json b/doc/schemas/decodepay.schema.json
@@ -37,10 +37,8 @@
       "description": "Amount the invoice asked for"
     },
     "payment_hash": {
-      "type": "hex",
-      "description": "the hash of the *payment_preimage*",
-      "maxLength": 64,
-      "minLength": 64
+      "type": "hash",
+      "description": "the hash of the *payment_preimage*"
     },
     "signature": {
       "type": "signature",
@@ -51,20 +49,16 @@
       "description": "the description of the purpose of the purchase"
     },
     "description_hash": {
-      "type": "hex",
-      "description": "the hash of the description, in place of *description*",
-      "maxLength": 64,
-      "minLength": 64
+      "type": "hash",
+      "description": "the hash of the description, in place of *description*"
     },
     "min_final_cltv_expiry": {
       "type": "u32",
       "description": "the minimum CLTV delay for the final node"
     },
     "payment_secret": {
-      "type": "hex",
-      "description": "the secret to hand to the payee node",
-      "maxLength": 64,
-      "minLength": 64
+      "type": "hash",
+      "description": "the secret to hand to the payee node"
     },
     "features": {
       "type": "hex",

diff --git a/doc/schemas/delpay.request.json b/doc/schemas/delpay.request.json
@@ -8,10 +8,8 @@
   "additionalProperties": false,
   "properties": {
     "payment_hash": {
-      "type": "hex",
-      "description": "the hash of the *payment_preimage* which will prove payment",
-      "maxLength": 64,
-      "minLength": 64
+      "type": "hash",
+      "description": "the hash of the *payment_preimage* which will prove payment"
     },
     "status": {
       "type": "string",

diff --git a/doc/schemas/delpay.schema.json b/doc/schemas/delpay.schema.json
@@ -24,10 +24,8 @@
             "description": "unique ID for this payment attempt"
           },
           "payment_hash": {
-            "type": "hex",
-            "description": "the hash of the *payment_preimage* which will prove payment",
-            "maxLength": 64,
-            "minLength": 64
+            "type": "hash",
+            "description": "the hash of the *payment_preimage* which will prove payment"
           },
           "status": {
             "type": "string",
@@ -73,10 +71,8 @@
             "description": "Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash"
           },
           "payment_preimage": {
-            "type": "hex",
-            "description": "proof of payment",
-            "maxLength": 64,
-            "minLength": 64
+            "type": "secret",
+            "description": "proof of payment"
           },
           "label": {
             "type": "string",

diff --git a/doc/schemas/disableoffer.schema.json b/doc/schemas/disableoffer.schema.json
@@ -11,10 +11,8 @@
   "additionalProperties": false,
   "properties": {
     "offer_id": {
-      "type": "hex",
-      "description": "the merkle hash of the offer",
-      "maxLength": 64,
-      "minLength": 64
+      "type": "hash",
+      "description": "the merkle hash of the offer"
     },
     "active": {
       "type": "boolean",