diff --git a/doc/lightning-addgossip.7 b/doc/lightning-addgossip.7 index adac5d48e..a050c3b3e 100644 --- a/doc/lightning-addgossip.7 +++ b/doc/lightning-addgossip.7 @@ -35,4 +35,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:40440e0a1159025d8fac68fc127029bf8539b103c0473d6bfaacd7cef5b56bea +\" SHA256STAMP:dd8b1fd2ffcf7c57629a042f44f2fbc526d8892a2c933de6e82511721a8ffdea diff --git a/doc/lightning-addgossip.7.md b/doc/lightning-addgossip.7.md index 1ff80f997..2bac15884 100644 --- a/doc/lightning-addgossip.7.md +++ b/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: +[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff) diff --git a/doc/lightning-check.7 b/doc/lightning-check.7 index abfa871a3..27dd0e436 100644 --- a/doc/lightning-check.7 +++ b/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 and Rusty Russell @@ -35,4 +39,4 @@ Mark Beckwith \fI and Rusty Russell Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:8ff7c586849eae5646f182b088351b4a5baa61e9e628a31763a6647e74a7fc0a +\" SHA256STAMP:9e78651117d3546edaf5150621630ee5dc4ccefd6e6a17b52b9dc8f86e8ba0c9 diff --git a/doc/lightning-check.7.md b/doc/lightning-check.7.md index a0303c75a..67bd9ecec 100644 --- a/doc/lightning-check.7.md +++ b/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: +[comment]: # ( SHA256STAMP:5b399ee88a5fb6b7eac0e1ac349a68a8715154f8c6468aedf446c703c91ac165) diff --git a/doc/lightning-createinvoice.7 b/doc/lightning-createinvoice.7 index 11ef5c4a4..499537c23 100644 --- a/doc/lightning-createinvoice.7 +++ b/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 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 diff --git a/doc/lightning-createinvoice.7.md b/doc/lightning-createinvoice.7.md index 1f5ee4d0a..99f5ce7ac 100644 --- a/doc/lightning-createinvoice.7.md +++ b/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: +[comment]: # ( SHA256STAMP:95a2fbf9c94fa1e01a322658035473c694bfb93e02d32c2cefafe6ef5b676695) diff --git a/doc/lightning-createonion.7 b/doc/lightning-createonion.7 index 41a0a9dce..2f075852f 100644 --- a/doc/lightning-createonion.7 +++ b/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 is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d32334049025248f8b6088afed4e3322be75815ea6b976f79a007c619518f98a +\" SHA256STAMP:c21aa197637bea17068072cd5907ad3302b48586067a8a5a8d748fd8e7e0a668 diff --git a/doc/lightning-createonion.7.md b/doc/lightning-createonion.7.md index 630f327aa..b10ecfce8 100644 --- a/doc/lightning-createonion.7.md +++ b/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: [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md +[comment]: # ( SHA256STAMP:a5a64325f4232f27bccbbe1c9fc62bfb602ba60c81f46a1ef2df25b06dac807e) diff --git a/doc/schemas/addgossip.schema.json b/doc/schemas/addgossip.schema.json new file mode 100644 index 000000000..b797a82c2 --- /dev/null +++ b/doc/schemas/addgossip.schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "properties": { + } +} diff --git a/doc/schemas/check.schema.json b/doc/schemas/check.schema.json new file mode 100644 index 000000000..faecc7d78 --- /dev/null +++ b/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" ] +} diff --git a/doc/schemas/createinvoice.schema.json b/doc/schemas/createinvoice.schema.json new file mode 100644 index 000000000..b1e6aa131 --- /dev/null +++ b/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 + } + } +} diff --git a/doc/schemas/createonion.schema.json b/doc/schemas/createonion.schema.json new file mode 100644 index 000000000..7917163e1 --- /dev/null +++ b/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 + } + } + } +}