doc: Annotate secrets and hashes in the JSON Schemas

ElementsProject · rustyrussell · Apr 1, 2022 · Apr 1, 2022 · Apr 1, 2022 · Apr 1, 2022
commit 8c9572adb0eb60963487d246290e6e831aad9ee1
diff --git a/doc/lightning-createinvoice.7.md b/doc/lightning-createinvoice.7.md
@@ -33,7 +33,7 @@ RETURN VALUE
 [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)
+- **payment_hash** (hash): 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)
@@ -43,7 +43,7 @@ On success, an object is returned, containing:
 - **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)
+- **payment_preimage** (secret, 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)
 - **payer_note** (string, optional): the optional *payer_note* from invoice_request which created this invoice (**experimental-offers** only).
 
@@ -74,4 +74,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:ea89ed849c8ad6cac8e1e136999046d1f7589bf176be0e65438174357f87ed11)
+[comment]: # ( SHA256STAMP:b07a315a6460449b64ab848ce9fc4cfe6ac862d63c8ab922434238a2b83d7902)
diff --git a/doc/lightning-createonion.7.md b/doc/lightning-createonion.7.md
@@ -92,7 +92,7 @@ RETURN VALUE
 [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:
+- **shared_secrets** (array of secrets): one shared secret for each node in the *hops* parameter:
   - the shared secret with this hop (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
@@ -133,4 +133,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:23e999fedfde74a200c0e6626fa828548b3b60952de30c5885cd63b1922f4508)
+[comment]: # ( SHA256STAMP:eabebca3c38ac8e01fb9a0891bde7913ce2832b7ee179c0b4617d104a0e6c009)
diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md
@@ -27,7 +27,7 @@ Note: The return is the same as an object from lightning-listinvoice(7).
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **label** (string): Unique label given at creation time
-- **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 (always 64 characters)
 - **status** (string): State of invoice (one of "paid", "expired", "unpaid")
 - **expires_at** (u64): UNIX timestamp when invoice expires (or expired)
 - **bolt11** (string, optional): BOLT11 string
@@ -43,7 +43,7 @@ If **status** is "paid":
   - **pay_index** (u64): unique index for this invoice payment
   - **amount_received_msat** (msat): how much was actually received
   - **paid_at** (u64): UNIX timestamp of when payment was received
-  - **payment_preimage** (hex): SHA256 of this is the *payment_hash* offered in the invoice (always 64 characters)
+  - **payment_preimage** (secret): SHA256 of this is the *payment_hash* offered in the invoice (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -78,4 +78,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:73d9097734e85d438de90844ab78bdd737e6df53620542887170c7564a86b90b)
+[comment]: # ( SHA256STAMP:407d741b622621da127dc1e55c98c299ace970f8244bc14574dddcafbf9aa1fc)
diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md
@@ -78,8 +78,8 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **bolt11** (string): the bolt11 string
-- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
-- **payment_secret** (hex): the *payment_secret* to place in the onion (always 64 characters)
+- **payment_hash** (hash): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **payment_secret** (secret): the *payment_secret* to place in the onion (always 64 characters)
 - **expires_at** (u64): UNIX timestamp of when invoice expires
 
 The following warnings may also be returned:
@@ -117,4 +117,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:f7d82473482e5454fc03641fddcfa97984e6a597e7ad377ced2cbed1512e91ed)
+[comment]: # ( SHA256STAMP:834b9d7b84845d423a677662b66b9109b3b8c4b7219a91d98f2817561d68a8cd)
diff --git a/doc/lightning-keysend.7.md b/doc/lightning-keysend.7.md
@@ -67,8 +67,8 @@ RETURN VALUE
 
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
-- **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
-- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+- **payment_hash** (hash): the hash of the *payment_preimage* which will prove payment (always 64 characters)
 - **created_at** (number): the UNIX timestamp showing when this payment was initiated
 - **parts** (u32): how many attempts this took
 - **amount_msat** (msat): Amount the recipient received
@@ -114,4 +114,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:bf507985544575c4ef2fe194fda6a693378cb8ab3bfb30ca7a7c066be271be29)
+[comment]: # ( SHA256STAMP:449315de94f49452c3d485775dd97bc2517763be420ebc74024914680359d1ff)
diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md
@@ -23,7 +23,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object containing **invoices** is returned.  It is an array of objects, where each object contains:
 - **label** (string): unique label supplied at invoice creation
-- **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 (always 64 characters)
 - **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
 - **description** (string, optional): description used in the invoice
@@ -37,7 +37,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 (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -56,4 +56,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:d1328ecc2a4e76ede8c9adc3a63d18ce36be305ddcee7cf717039f79642cfd41)
+[comment]: # ( SHA256STAMP:1178a5178a20b2aca9c52fe39e332bd1d6c4f20fa302639bed0fbfc6eb348c40)
diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md
@@ -53,7 +53,7 @@ On success, an object containing **peers** is returned.  It is an array of objec
     - **perkb** (u32): Feerate per 1000 virtual bytes
   - **owner** (string, optional): The current subdaemon controlling this connection
   - **short_channel_id** (short_channel_id, optional): The short_channel_id (once locked in)
-  - **channel_id** (hex, optional): The full channel_id (always 64 characters)
+  - **channel_id** (hash, optional): The full channel_id (always 64 characters)
   - **funding_txid** (txid, optional): ID of the funding transaction
   - **funding_outnum** (u32, optional): The 0-based output number of the funding transaction which opens the channel
   - **initial_feerate** (string, optional): For inflight opens, the first feerate used to initiate the channel open
@@ -113,7 +113,7 @@ On success, an object containing **peers** is returned.  It is an array of objec
     - **id** (u64): Unique ID for this htlc on this channel in this direction
     - **amount_msat** (msat): Amount send/received for this HTLC
     - **expiry** (u32): Block this HTLC expires at
-    - **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 (always 64 characters)
     - **local_trimmed** (boolean, optional): if this is too small to enforce onchain (always *true*)
     - **status** (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin)
 
@@ -380,4 +380,4 @@ Main web site: <https://github.com/ElementsProject/lightning> Lightning
 RFC site (BOLT \#9):
 <https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md>
 
-[comment]: # ( SHA256STAMP:147b7008c8f4acb031df625e0731614339a75ee5861cb9f40cd542b1017e3660)
+[comment]: # ( SHA256STAMP:6b0ec5c899c8685487190209f594635030205a275e1dc6d61a7b057adbf66192)
diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md
@@ -25,7 +25,7 @@ Note that the returned array is ordered by increasing *id*.
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 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 (always 64 characters)
 - **status** (string): status of the payment (one of "pending", "failed", "complete")
 - **created_at** (u64): the UNIX timestamp showing when this payment was initiated
 - **amount_sent_msat** (msat): The amount sent
@@ -37,7 +37,7 @@ On success, an object containing **payments** is returned.  It is an array of ob
 - **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
 
 If **status** is "complete":
-  - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+  - **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
 
 If **status** is "failed":
   - **erroronion** (hex, optional): the onion message returned
@@ -60,4 +60,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:1dfcb495e0004b9dadffd7f69b58275bf9168c9f4007675b390ebbaea07ffde6)
+[comment]: # ( SHA256STAMP:b03c2f306bafb1919f0933ebc695657bd691591484ddcb39b1e8706335593cd2)
diff --git a/doc/lightning-pay.7.md b/doc/lightning-pay.7.md
@@ -78,8 +78,8 @@ RETURN VALUE
 
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
-- **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
-- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+- **payment_hash** (hash): the hash of the *payment_preimage* which will prove payment (always 64 characters)
 - **created_at** (number): the UNIX timestamp showing when this payment was initiated
 - **parts** (u32): how many attempts this took
 - **amount_msat** (msat): Amount the recipient received
@@ -149,4 +149,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:e537b9c74918559db99e673fac63cfa43a347ab80c32f33012ab3655b9edc45e)
+[comment]: # ( SHA256STAMP:b8ff255c1f4d284535d70f13d3bd85c3d20ef8fdee081835a57fb04528311db6)
diff --git a/doc/lightning-sendonion.7.md b/doc/lightning-sendonion.7.md
@@ -89,7 +89,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **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 (always 64 characters)
 - **status** (string): status of the payment (could be complete if already sent previously) (one of "pending", "complete")
 - **created_at** (u64): the UNIX timestamp showing when this payment was initiated
 - **amount_sent_msat** (msat): The amount sent
@@ -101,7 +101,7 @@ On success, an object is returned, containing:
 - **partid** (u64, optional): the partid (if supplied) to sendonion/sendpay
 
 If **status** is "complete":
-  - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+  - **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
 
 If **status** is "pending":
   - **message** (string, optional): Monitor status with listpays or waitsendpay
@@ -128,4 +128,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:b8fd5d1c31eb2db10b2f32960752ae1c90150ffeb470c5ea635cb1034e8b1438)
+[comment]: # ( SHA256STAMP:d2f4991d271147dd8c13859376f36f2d8843a96034e818a434555a09bf6fd003)
diff --git a/doc/lightning-sendpay.7.md b/doc/lightning-sendpay.7.md
@@ -57,7 +57,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **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 (always 64 characters)
 - **status** (string): status of the payment (could be complete if already sent previously) (one of "pending", "complete")
 - **created_at** (u64): the UNIX timestamp showing when this payment was initiated
 - **amount_sent_msat** (msat): The amount sent
@@ -70,7 +70,7 @@ On success, an object is returned, containing:
 - **bolt12** (string, optional): the bolt12 string (if supplied: **experimental-offers** only).
 
 If **status** is "complete":
-  - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+  - **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
 
 If **status** is "pending":
   - **message** (string): Monitor status with listpays or waitsendpay
@@ -127,4 +127,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:44540ace609ccfa7b023526d7a92ba7cf4a6058f3ae2124c20fa65b92137e41b)
+[comment]: # ( SHA256STAMP:a7f55104f3bdb21057a410a33902b92aca38aaa83b1e0e7e6876a911316132ed)
diff --git a/doc/lightning-waitanyinvoice.7.md b/doc/lightning-waitanyinvoice.7.md
@@ -37,7 +37,7 @@ RETURN VALUE
 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 (always 64 characters)
 - **status** (string): Whether it's paid or expired (one of "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
@@ -48,7 +48,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 (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -73,4 +73,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:33df5fb9bcbcb6d2240d0d18b970b2300414aae36b81fb276fcedfc21480d22f)
+[comment]: # ( SHA256STAMP:6c4df3bb97df9f87583725ef31e803900ac548e17506692f9da365a3e4bbf18f)
diff --git a/doc/lightning-waitinvoice.7.md b/doc/lightning-waitinvoice.7.md
@@ -19,7 +19,7 @@ RETURN VALUE
 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 (always 64 characters)
 - **status** (string): Whether it's paid or expired (one of "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
@@ -30,7 +30,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 (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -58,4 +58,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:33df5fb9bcbcb6d2240d0d18b970b2300414aae36b81fb276fcedfc21480d22f)
+[comment]: # ( SHA256STAMP:6c4df3bb97df9f87583725ef31e803900ac548e17506692f9da365a3e4bbf18f)
diff --git a/doc/lightning-waitsendpay.7.md b/doc/lightning-waitsendpay.7.md
@@ -35,7 +35,7 @@ RETURN VALUE
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **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 (always 64 characters)
 - **status** (string): status of the payment (always "complete")
 - **created_at** (u64): the UNIX timestamp showing when this payment was initiated
 - **amount_sent_msat** (msat): The amount sent
@@ -48,7 +48,7 @@ On success, an object is returned, containing:
 - **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
 
 If **status** is "complete":
-  - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+  - **payment_preimage** (secret): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
 
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
@@ -101,4 +101,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:3f89cf80acc1e9363509f0a053a617f8b381790823f8cd05fa6c708eb72fcc7e)
+[comment]: # ( SHA256STAMP:96e5cfd0bd6f2d6b7a25a60f846283592404cee07ef142e58cd56929cc6923c9)
diff --git a/doc/schemas/createinvoice.schema.json b/doc/schemas/createinvoice.schema.json
@@ -23,7 +23,7 @@
       "description": "the bolt12 string instead of **bolt11** (**experimental-offers** only)"
     },
     "payment_hash": {
-      "type": "hex",
+      "type": "hash",
       "description": "the hash of the *payment_preimage* which will prove payment",
       "maxLength": 64,
       "minLength": 64
@@ -62,7 +62,7 @@
       "description": "UNIX timestamp of when invoice was paid (**status** *paid* only)"
     },
     "payment_preimage": {
-      "type": "hex",
+      "type": "secret",
       "description": "the proof of payment: SHA256 of this **payment_hash**",
       "maxLength": 64,
       "minLength": 64

diff --git a/doc/schemas/createonion.request.json b/doc/schemas/createonion.request.json
@@ -32,7 +32,7 @@
       "description": ""
     },
     "session_key": {
-      "type": "hex"
+      "type": "secret"
     },
     "onion_size": {
       "type": "u16"