From 2ddecdc95a40f4be24acfb6e2f9db48ce6dc9f71 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 16 Jun 2021 10:40:17 +0930 Subject: [PATCH] doc: schemas for everything else. Signed-off-by: Rusty Russell Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite. --- doc/lightning-dev-sendcustommsg.7 | 10 +- doc/lightning-dev-sendcustommsg.7.md | 6 + doc/lightning-fundpsbt.7 | 41 ++++-- doc/lightning-fundpsbt.7.md | 26 ++-- doc/lightning-keysend.7 | 31 +++- doc/lightning-keysend.7.md | 16 +- doc/lightning-listsendpays.7 | 70 ++++----- doc/lightning-listsendpays.7.md | 49 +++---- doc/lightning-listtransactions.7 | 50 +++++-- doc/lightning-listtransactions.7.md | 41 ++++-- doc/lightning-multifundchannel.7 | 59 ++++++-- doc/lightning-multifundchannel.7.md | 34 +++-- doc/lightning-multiwithdraw.7 | 13 +- doc/lightning-multiwithdraw.7.md | 10 +- doc/lightning-newaddr.7 | 12 +- doc/lightning-newaddr.7.md | 8 +- doc/lightning-notifications.7 | 9 +- doc/lightning-notifications.7.md | 9 +- doc/lightning-offer.7 | 19 ++- doc/lightning-offer.7.md | 11 +- doc/lightning-offerout.7 | 22 ++- doc/lightning-offerout.7.md | 19 +-- doc/lightning-openchannel_abort.7 | 15 +- doc/lightning-openchannel_abort.7.md | 10 +- doc/lightning-openchannel_bump.7 | 20 ++- doc/lightning-openchannel_bump.7.md | 14 +- doc/lightning-openchannel_init.7 | 20 ++- doc/lightning-openchannel_init.7.md | 14 +- doc/lightning-openchannel_signed.7 | 14 +- doc/lightning-openchannel_signed.7.md | 9 +- doc/lightning-openchannel_update.7 | 17 ++- doc/lightning-openchannel_update.7.md | 12 +- doc/lightning-pay.7 | 34 ++++- doc/lightning-pay.7.md | 19 ++- doc/lightning-ping.7 | 6 +- doc/lightning-ping.7.md | 8 +- doc/lightning-plugin.7 | 37 ++++- doc/lightning-plugin.7.md | 18 ++- doc/lightning-reserveinputs.7 | 18 ++- doc/lightning-reserveinputs.7.md | 10 ++ doc/lightning-sendinvoice.7 | 35 ++++- doc/lightning-sendinvoice.7.md | 18 ++- doc/lightning-sendonion.7 | 46 +++++- doc/lightning-sendonion.7.md | 24 ++- doc/lightning-sendonionmessage.7 | 4 +- doc/lightning-sendonionmessage.7.md | 5 +- doc/lightning-sendpay.7 | 48 +++++- doc/lightning-sendpay.7.md | 25 +++- doc/lightning-sendpsbt.7 | 8 +- doc/lightning-sendpsbt.7.md | 10 +- doc/lightning-setchannelfee.7 | 25 +++- doc/lightning-setchannelfee.7.md | 13 +- doc/lightning-signmessage.7 | 15 +- doc/lightning-signmessage.7.md | 10 +- doc/lightning-signpsbt.7 | 6 +- doc/lightning-signpsbt.7.md | 8 +- doc/lightning-stop.7 | 9 +- doc/lightning-stop.7.md | 9 +- doc/lightning-txdiscard.7 | 17 ++- doc/lightning-txdiscard.7.md | 13 +- doc/lightning-txprepare.7 | 18 ++- doc/lightning-txprepare.7.md | 14 +- doc/lightning-txsend.7 | 15 +- doc/lightning-txsend.7.md | 11 +- doc/lightning-unreserveinputs.7 | 21 ++- doc/lightning-unreserveinputs.7.md | 17 ++- doc/lightning-utxopsbt.7 | 34 ++++- doc/lightning-utxopsbt.7.md | 17 +++ doc/lightning-waitanyinvoice.7 | 38 ++++- doc/lightning-waitanyinvoice.7.md | 20 ++- doc/lightning-waitblockheight.7 | 11 +- doc/lightning-waitblockheight.7.md | 8 +- doc/lightning-waitinvoice.7 | 38 ++++- doc/lightning-waitinvoice.7.md | 20 ++- doc/lightning-waitsendpay.7 | 39 ++++- doc/lightning-waitsendpay.7.md | 21 ++- doc/lightning-withdraw.7 | 15 +- doc/lightning-withdraw.7.md | 11 +- doc/schemas/checkmessage.schema.json | 56 +++++++ doc/schemas/dev-sendcustommsg.schema.json | 11 ++ doc/schemas/fundpsbt.schema.json | 2 +- doc/schemas/keysend.schema.json | 55 +++++++ doc/schemas/listsendpays.schema.json | 163 +++++++++++++++++++++ doc/schemas/listtransactions.schema.json | 121 +++++++++++++++ doc/schemas/multifundchannel.schema.json | 83 +++++++++++ doc/schemas/multiwithdraw.schema.json | 16 ++ doc/schemas/newaddr.schema.json | 16 ++ doc/schemas/notifications.schema.json | 7 + doc/schemas/offer.schema.json | 36 +++++ doc/schemas/offerout.schema.json | 37 +++++ doc/schemas/openchannel_abort.schema.json | 22 +++ doc/schemas/openchannel_bump.schema.json | 27 ++++ doc/schemas/openchannel_init.schema.json | 27 ++++ doc/schemas/openchannel_signed.schema.json | 22 +++ doc/schemas/openchannel_update.schema.json | 22 +++ doc/schemas/pay.schema.json | 55 +++++++ doc/schemas/ping.schema.json | 12 ++ doc/schemas/plugin.schema.json | 71 +++++++++ doc/schemas/reserveinputs.schema.json | 39 +++++ doc/schemas/sendinvoice.schema.json | 89 +++++++++++ doc/schemas/sendonion.schema.json | 125 ++++++++++++++++ doc/schemas/sendonionmessage.schema.json | 8 + doc/schemas/sendpay.schema.json | 131 +++++++++++++++++ doc/schemas/sendpsbt.schema.json | 16 ++ doc/schemas/setchannelfee.schema.json | 41 ++++++ doc/schemas/signmessage.schema.json | 24 +++ doc/schemas/signpsbt.schema.json | 12 ++ doc/schemas/stop.schema.json | 5 + doc/schemas/txdiscard.schema.json | 15 ++ doc/schemas/txprepare.schema.json | 19 +++ doc/schemas/txsend.schema.json | 19 +++ doc/schemas/unreserveinputs.schema.json | 59 ++++++++ doc/schemas/utxopsbt.schema.json | 60 ++++++++ doc/schemas/waitanyinvoice.schema.json | 108 ++++++++++++++ doc/schemas/waitblockheight.schema.json | 11 ++ doc/schemas/waitinvoice.schema.json | 108 ++++++++++++++ doc/schemas/waitsendpay.schema.json | 98 +++++++++++++ doc/schemas/withdraw.schema.json | 19 +++ 118 files changed, 3026 insertions(+), 417 deletions(-) create mode 100644 doc/schemas/checkmessage.schema.json create mode 100644 doc/schemas/dev-sendcustommsg.schema.json create mode 100644 doc/schemas/keysend.schema.json create mode 100644 doc/schemas/listsendpays.schema.json create mode 100644 doc/schemas/listtransactions.schema.json create mode 100644 doc/schemas/multifundchannel.schema.json create mode 100644 doc/schemas/multiwithdraw.schema.json create mode 100644 doc/schemas/newaddr.schema.json create mode 100644 doc/schemas/notifications.schema.json create mode 100644 doc/schemas/offer.schema.json create mode 100644 doc/schemas/offerout.schema.json create mode 100644 doc/schemas/openchannel_abort.schema.json create mode 100644 doc/schemas/openchannel_bump.schema.json create mode 100644 doc/schemas/openchannel_init.schema.json create mode 100644 doc/schemas/openchannel_signed.schema.json create mode 100644 doc/schemas/openchannel_update.schema.json create mode 100644 doc/schemas/pay.schema.json create mode 100644 doc/schemas/ping.schema.json create mode 100644 doc/schemas/plugin.schema.json create mode 100644 doc/schemas/reserveinputs.schema.json create mode 100644 doc/schemas/sendinvoice.schema.json create mode 100644 doc/schemas/sendonion.schema.json create mode 100644 doc/schemas/sendonionmessage.schema.json create mode 100644 doc/schemas/sendpay.schema.json create mode 100644 doc/schemas/sendpsbt.schema.json create mode 100644 doc/schemas/setchannelfee.schema.json create mode 100644 doc/schemas/signmessage.schema.json create mode 100644 doc/schemas/signpsbt.schema.json create mode 100644 doc/schemas/stop.schema.json create mode 100644 doc/schemas/txdiscard.schema.json create mode 100644 doc/schemas/txprepare.schema.json create mode 100644 doc/schemas/txsend.schema.json create mode 100644 doc/schemas/unreserveinputs.schema.json create mode 100644 doc/schemas/utxopsbt.schema.json create mode 100644 doc/schemas/waitanyinvoice.schema.json create mode 100644 doc/schemas/waitblockheight.schema.json create mode 100644 doc/schemas/waitinvoice.schema.json create mode 100644 doc/schemas/waitsendpay.schema.json create mode 100644 doc/schemas/withdraw.schema.json diff --git a/doc/lightning-dev-sendcustommsg.7 b/doc/lightning-dev-sendcustommsg.7 index d8efec500..654640226 100644 --- a/doc/lightning-dev-sendcustommsg.7 +++ b/doc/lightning-dev-sendcustommsg.7 @@ -48,6 +48,14 @@ as the message is queued\. If any of the above limitations is not respected the method returns an explicit error message stating the issue\. + +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBstatus\fR (string): Information about where message was queued + +.RE .SH AUTHOR Christian Decker \fI is mainly responsible\. @@ -60,4 +68,4 @@ Christian Decker \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:0dc60e560dcea0ba037fa9b254faaa680f80c9a5239e695341c3182672ccc0a3 +\" SHA256STAMP:facefdc47adcbf0342f6e359d4752b8ab1b9a7ed2d6b466c9d202939fae5019e diff --git a/doc/lightning-dev-sendcustommsg.7.md b/doc/lightning-dev-sendcustommsg.7.md index d4b73f349..1b78a156c 100644 --- a/doc/lightning-dev-sendcustommsg.7.md +++ b/doc/lightning-dev-sendcustommsg.7.md @@ -47,6 +47,11 @@ as the message is queued. If any of the above limitations is not respected the method returns an explicit error message stating the issue. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **status** (string): Information about where message was queued +[comment]: # (GENERATE-FROM-SCHEMA-END) + AUTHOR ------ @@ -62,3 +67,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:28ff2cdde9b35e81ceec3b1860facb1b2f91c5049ce33776b3c992621aba475d) diff --git a/doc/lightning-fundpsbt.7 b/doc/lightning-fundpsbt.7 index b7c12cc51..0a001fad4 100644 --- a/doc/lightning-fundpsbt.7 +++ b/doc/lightning-fundpsbt.7 @@ -78,18 +78,37 @@ if \fIexcess_msat\fR was greater or equal to 31 + 546\. .SH RETURN VALUE -On success, returns the \fIpsbt\fR containing the inputs, \fIfeerate_per_kw\fR -showing the exact numeric feerate it used, \fIestimated_final_weight\fR for -the estimated weight of the transaction once fully signed, and -\fIexcess_msat\fR containing the amount above \fIsatoshi\fR which is -available\. This could be zero, or dust\. If \fIsatoshi\fR was "all", -then \fIexcess_msat\fR is the entire amount once fees are subtracted -for the weights of the inputs and startweight\. +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBpsbt\fR (string): Unsigned PSBT which fulfills the parameters given +.IP \[bu] +\fBfeerate_per_kw\fR (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight +.IP \[bu] +\fBestimated_final_weight\fR (u32): The estimated weight of the transaction once fully signed +.IP \[bu] +\fBexcess_msat\fR (msat): The amount above \fIsatoshi\fR which is available\. This could be zero, or dust; it will be zero if \fIchange_outnum\fR is also returned +.IP \[bu] +\fBchange_outnum\fR (u32, optional): The 0-based output number where change was placed (only if parameter \fIexcess_as_change\fR was true and there was sufficient funds) +.IP \[bu] +\fBreservations\fR (array of objects, optional): If \fIreserve\fR was true or a non-zero number, just as per \fBlightning-reserveinputs\fR(7): +.RS +.IP \[bu] +\fBtxid\fR (txid): The txid of the transaction +.IP \[bu] +\fBvout\fR (u32): The 0-based output number +.IP \[bu] +\fBwas_reserved\fR (boolean): Whether this output was previously reserved (always \fIfalse\fR) +.IP \[bu] +\fBreserved\fR (boolean): Whether this output is now reserved (always \fItrue\fR) +.IP \[bu] +\fBreserved_to_block\fR (u32): The blockheight the reservation will expire + +.RE -If \fIreserve\fR was \fItrue\fR or a non-zero number, then a \fIreservations\fR -array is returned, exactly like \fIreserveinputs\fR\. - +.RE If \fIexcess_as_change\fR is true and the excess is enough to cover an additional output above the \fBdust_limit\fR, then an output is @@ -122,4 +141,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:b02d5c31f0fe6b5423871f4f5859519b41a882388d17f460bd7331f714880126 +\" SHA256STAMP:91af62e37e674390ba68863ac7d788740f2eb61cbf8ed61465751fcfd9ad4e6a diff --git a/doc/lightning-fundpsbt.7.md b/doc/lightning-fundpsbt.7.md index ae5bde389..d97e101a9 100644 --- a/doc/lightning-fundpsbt.7.md +++ b/doc/lightning-fundpsbt.7.md @@ -71,16 +71,20 @@ if *excess_msat* was greater or equal to 31 + 546. RETURN VALUE ------------ -On success, returns the *psbt* containing the inputs, *feerate_per_kw* -showing the exact numeric feerate it used, *estimated_final_weight* for -the estimated weight of the transaction once fully signed, and -*excess_msat* containing the amount above *satoshi* which is -available. This could be zero, or dust. If *satoshi* was "all", -then *excess_msat* is the entire amount once fees are subtracted -for the weights of the inputs and startweight. - -If *reserve* was *true* or a non-zero number, then a *reservations* -array is returned, exactly like *reserveinputs*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **psbt** (string): Unsigned PSBT which fulfills the parameters given +- **feerate_per_kw** (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight +- **estimated_final_weight** (u32): The estimated weight of the transaction once fully signed +- **excess_msat** (msat): The amount above *satoshi* which is available. This could be zero, or dust; it will be zero if *change_outnum* is also returned +- **change_outnum** (u32, optional): The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds) +- **reservations** (array of objects, optional): If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7): + - **txid** (txid): The txid of the transaction + - **vout** (u32): The 0-based output number + - **was_reserved** (boolean): Whether this output was previously reserved (always *false*) + - **reserved** (boolean): Whether this output is now reserved (always *true*) + - **reserved_to_block** (u32): The blockheight the reservation will expire +[comment]: # (GENERATE-FROM-SCHEMA-END) If *excess_as_change* is true and the excess is enough to cover an additional output above the `dust_limit`, then an output is @@ -110,4 +114,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:25b32367f5bbf6f1e53036c38b7b7d19eebf62fa749a3ab580e4093eedc88584) +[comment]: # ( SHA256STAMP:4b3ea2f97eb94e65c752f165a989d99afee0eb8453178bf6a23e4a662fb6abf3) diff --git a/doc/lightning-keysend.7 b/doc/lightning-keysend.7 index 8a54be1cd..479be5596 100644 --- a/doc/lightning-keysend.7 +++ b/doc/lightning-keysend.7 @@ -72,8 +72,35 @@ exceed \fImaxdelay\fR\. .SH RETURN VALUE -On success, \fBkeysend\fR will return a number of internal statistics and details of the attempts to reach the \fIdestination\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters) +.IP \[bu] +\fBcreated_at\fR (number): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBparts\fR (u32): how many attempts this took +.IP \[bu] +\fBamount_msat\fR (msat): Amount the recipient received +.IP \[bu] +\fBamount_sent_msat\fR (msat): Total amount we sent (including fees) +.IP \[bu] +\fBstatus\fR (string): status of payment (always "complete") +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment + +.RE + +The following warnings may also be returned: + +.RS +.IP \[bu] +\fBwarning_partial_completion\fR: Not all parts of a multi-part payment have completed + +.RE You can monitor the progress and retries of a payment using the \fBlightning-paystatus\fR(7) command\. @@ -122,4 +149,4 @@ Christian Decker \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:8d26499787c316e9b75ad304ffc1c872af523564750558ba986c2ccde63294c7 +\" SHA256STAMP:254e1c9b650b8224720894a9fe6c7a0687c77972ec8c67c8b62b3a8e22e095b6 diff --git a/doc/lightning-keysend.7.md b/doc/lightning-keysend.7.md index e2a54df5d..aee67662e 100644 --- a/doc/lightning-keysend.7.md +++ b/doc/lightning-keysend.7.md @@ -65,7 +65,20 @@ exceed *maxdelay*. RETURN VALUE ------------ -On success, `keysend` will return a number of internal statistics and details of the attempts to reach the *destination*. +[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) +- **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 +- **amount_sent_msat** (msat): Total amount we sent (including fees) +- **status** (string): status of payment (always "complete") +- **destination** (pubkey, optional): the final destination of the payment + +The following warnings may also be returned: +- **warning_partial_completion**: Not all parts of a multi-part payment have completed +[comment]: # (GENERATE-FROM-SCHEMA-END) You can monitor the progress and retries of a payment using the lightning-paystatus(7) command. @@ -100,3 +113,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:787ea6ae933da77756aca49aee68ba996cd54aea53b85ce2e5fcc85841022241) diff --git a/doc/lightning-listsendpays.7 b/doc/lightning-listsendpays.7 index 8f594c82c..93b9834fb 100644 --- a/doc/lightning-listsendpays.7 +++ b/doc/lightning-listsendpays.7 @@ -18,50 +18,50 @@ command per \fIpay\fR, so this command should be used with caution\. .SH RETURN VALUE -On success, an array of objects is returned, ordered by increasing \fIid\fR\. Each object contains: +Note that the returned array is ordered by increasing \fIid\fR\. - \fIid\fR -unique internal value assigned at creation +On success, an object containing \fBpayments\fR is returned\. It is an array of objects, where each object contains: +.RS +.IP \[bu] +\fBid\fR (u64): unique ID for this payment attempt +.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): status of the payment (one of "pending", "failed", "complete") +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBamount_sent_msat\fR (msat): The amount sent +.IP \[bu] +\fBamount_msat\fR (msat, optional): The amount delivered to destination (if known) +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment if known +.IP \[bu] +\fBlabel\fR (string, optional): the label, if given to sendpay +.IP \[bu] +\fBbolt11\fR (string, optional): the bolt11 string (if pay supplied one) +.IP \[bu] +\fBbolt12\fR (string, optional): the bolt12 string (if supplied for pay: \fBexperimental-offers\fR only)\. - \fIpayment_hash\fR -the hash of the \fIpayment_preimage\fR which will prove payment\. +.RE +If \fBstatus\fR is "complete": - \fIdestination\fR -the final destination of the payment\. +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) +.RE - \fIamount_msat\fR -the amount the destination received, in "NNNmsat" format\. +If \fBstatus\fR is "failed": +.RS +.IP \[bu] +\fBerroronion\fR (hex, optional): the onion message returned - \fIcreated_at\fR -the UNIX timestamp showing when this payment was initiated\. - - - \fIstatus\fR -one of \fIcomplete\fR, \fIfailed\fR or \fIpending\fR\. - - - \fIpayment_preimage\fR -(if \fIstatus\fR is \fIcomplete\fR) proves payment was received\. - - - \fIlabel\fR -optional \fIlabel\fR, if provided to \fIsendpay\fR\. - - - \fIbolt11\fR -the \fIbolt11\fR argument given to \fIpay\fR (may be missing for pre-0\.7 -payments)\. - - - \fIbolt12\fR -if \fBexperimental-offers\fR is enabled, and \fBpay\fR was a given a bolt12 -invoice, this field will appear instead of \fIbolt11\fR\. - +.RE .SH AUTHOR Christian Decker \fI is mainly @@ -75,4 +75,4 @@ responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:c6b36205c8067723bb9edc20f3645754faa9c9d26568d6c899721b43a1e99812 +\" SHA256STAMP:01f2a7682c9af98704b04b2b5efe695ae6abc0cf41e13a4bc36c14e8b9662822 diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md index 7752b7e73..bf0960f1c 100644 --- a/doc/lightning-listsendpays.7.md +++ b/doc/lightning-listsendpays.7.md @@ -20,39 +20,27 @@ command per *pay*, so this command should be used with caution. RETURN VALUE ------------ -On success, an array of objects is returned, ordered by increasing *id*. Each object contains: +Note that the returned array is ordered by increasing *id*. - *id* -unique internal value assigned at creation +[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) +- **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 +- **amount_msat** (msat, optional): The amount delivered to destination (if known) +- **destination** (pubkey, optional): the final destination of the payment if known +- **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). - *payment\_hash* -the hash of the *payment\_preimage* which will prove payment. +If **status** is "complete": + - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters) - *destination* -the final destination of the payment. - - *amount\_msat* -the amount the destination received, in "NNNmsat" format. - - *created\_at* -the UNIX timestamp showing when this payment was initiated. - - *status* -one of *complete*, *failed* or *pending*. - - *payment\_preimage* -(if *status* is *complete*) proves payment was received. - - *label* -optional *label*, if provided to *sendpay*. - - *bolt11* -the *bolt11* argument given to *pay* (may be missing for pre-0.7 -payments). - - *bolt12* -if **experimental-offers** is enabled, and `pay` was a given a bolt12 -invoice, this field will appear instead of *bolt11*. +If **status** is "failed": + - **erroronion** (hex, optional): the onion message returned +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -70,3 +58,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:db8e97cc84246f4e836ac7b2f39e265deb51cb0adacfcca8e05bb7cb9c3480de) diff --git a/doc/lightning-listtransactions.7 b/doc/lightning-listtransactions.7 index f87ff7b9c..128e33732 100644 --- a/doc/lightning-listtransactions.7 +++ b/doc/lightning-listtransactions.7 @@ -22,45 +22,63 @@ The \fBlisttransactions\fR command returns transactions tracked in the wallet\. .fi .SH RETURN VALUE -On success, the command will return a list of transactions, each object represents a transaction, with the following details: +On success, an object containing \fBtransactions\fR is returned\. It is an array of objects, where each object contains: .RS .IP \[bu] -\fIhash\fR: A string that represents the hash of transaction, which the caller can use to find it on the blockchain\. +\fBhash\fR (txid): the transaction id .IP \[bu] -\fIrawtx\fR: A string that represents the hexadecimal dump of the transaction\. +\fBrawtx\fR (hex): the raw transaction .IP \[bu] -\fIblockheight\fR: An integer that represents the block height that contains the transaction on the blockchain\. +\fBblockheight\fR (u32): the block height of this tx .IP \[bu] -\fItxindex\fR: An integer that represents the transaction index inside the block\. +\fBtxindex\fR (u32): the transaction number within the block .IP \[bu] -\fIlocktime\fR: An integer that represents the nLocktime field\. +\fBlocktime\fR (u32): The nLocktime for this tx .IP \[bu] -\fIversion\fR: An integer that represents the nVersion field\. +\fBversion\fR (u32): The nVersion for this tx .IP \[bu] -\fIinputs\fR: A list of spent transaction outputs, each spent transaction output is represented with an object with the following properties: +\fBinputs\fR (array of objects): Each input, in order: .RS .IP \[bu] -\fItxid\fR: A string that represents the hash of transaction\. This is the output index of the transaction output being spent\. +\fBtxid\fR (txid): the transaction id spent .IP \[bu] -\fIindex\fR: An integer that represents the index of transaction\. +\fBindex\fR (u32): the output spent .IP \[bu] -\fIsequence\fR: An integer that represents the nSequence field\. +\fBsequence\fR (u32): the nSequence value +.IP \[bu] +\fBtype\fR (string, optional): the purpose of this input (\fIEXPERIMENTAL_FEATURES\fR only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") +.IP \[bu] +\fBchannel\fR (short_channel_id, optional): the channel this input is associated with (\fIEXPERIMENTAL_FEATURES\fR only) .RE .IP \[bu] -\fIoutputs\fR: A list of transactions, each transaction is represented with an object with the following proprieties: +\fBoutputs\fR (array of objects): Each output, in order: .RS .IP \[bu] -\fIindex\fR: An integer that represents the index of transaction\. +\fBindex\fR (u32): the 0-based output number .IP \[bu] -\fIsatoshis\fR: A string that represents the amount in millisatoshi\. +\fBmsat\fR (msat): the amount of the output .IP \[bu] -\fIscriptPubKey\fR: A string that contains the lock script in hexadecimal dump form\. +\fBscriptPubKey\fR (hex): the scriptPubKey +.IP \[bu] +\fBtype\fR (string, optional): the purpose of this output (\fIEXPERIMENTAL_FEATURES\fR only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") +.IP \[bu] +\fBchannel\fR (short_channel_id, optional): the channel this output is associated with (\fIEXPERIMENTAL_FEATURES\fR only) .RE +.IP \[bu] +\fBtype\fR (array of strings, optional): +.RS +.IP \[bu] +Reason we care about this transaction (\fIEXPERIMENTAL_FEATURES\fR only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") + +.RE + +.IP \[bu] +\fBchannel\fR (short_channel_id, optional): the channel this transaction is associated with (\fIEXPERIMENTAL_FEATURES\fR only) .RE @@ -120,4 +138,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:88c68faf136cd7ce305bab0b89813d1c0122b8f31688a2dc9c064f7cba480a1d +\" SHA256STAMP:85b8fd1df3815845e8418d142a0e62589fd386784dc6fe90150db1e43519c4ce diff --git a/doc/lightning-listtransactions.7.md b/doc/lightning-listtransactions.7.md index cf8b47d20..b0c7bfdcd 100644 --- a/doc/lightning-listtransactions.7.md +++ b/doc/lightning-listtransactions.7.md @@ -24,22 +24,30 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, the command will return a list of transactions, each object represents a transaction, with the following details: - -- *hash*: A string that represents the hash of transaction, which the caller can use to find it on the blockchain. -- *rawtx*: A string that represents the hexadecimal dump of the transaction. -- *blockheight*: An integer that represents the block height that contains the transaction on the blockchain. -- *txindex*: An integer that represents the transaction index inside the block. -- *locktime*: An integer that represents the nLocktime field. -- *version*: An integer that represents the nVersion field. -- *inputs*: A list of spent transaction outputs, each spent transaction output is represented with an object with the following properties: - - *txid*: A string that represents the hash of transaction. This is the output index of the transaction output being spent. - - *index*: An integer that represents the index of transaction. - - *sequence*: An integer that represents the nSequence field. -- *outputs*: A list of transactions, each transaction is represented with an object with the following proprieties: - - *index*: An integer that represents the index of transaction. - - *satoshis*: A string that represents the amount in millisatoshi. - - *scriptPubKey*: A string that contains the lock script in hexadecimal dump form. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **transactions** is returned. It is an array of objects, where each object contains: +- **hash** (txid): the transaction id +- **rawtx** (hex): the raw transaction +- **blockheight** (u32): the block height of this tx +- **txindex** (u32): the transaction number within the block +- **locktime** (u32): The nLocktime for this tx +- **version** (u32): The nVersion for this tx +- **inputs** (array of objects): Each input, in order: + - **txid** (txid): the transaction id spent + - **index** (u32): the output spent + - **sequence** (u32): the nSequence value + - **type** (string, optional): the purpose of this input (*EXPERIMENTAL_FEATURES* only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") + - **channel** (short_channel_id, optional): the channel this input is associated with (*EXPERIMENTAL_FEATURES* only) +- **outputs** (array of objects): Each output, in order: + - **index** (u32): the 0-based output number + - **msat** (msat): the amount of the output + - **scriptPubKey** (hex): the scriptPubKey + - **type** (string, optional): the purpose of this output (*EXPERIMENTAL_FEATURES* only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") + - **channel** (short_channel_id, optional): the channel this output is associated with (*EXPERIMENTAL_FEATURES* only) +- **type** (array of strings, optional): + - Reason we care about this transaction (*EXPERIMENTAL_FEATURES* only) (one of "theirs", "deposit", "withdraw", "channel_funding", "channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat") +- **channel** (short_channel_id, optional): the channel this transaction is associated with (*EXPERIMENTAL_FEATURES* only) +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: - -32602: Error in given parameters. @@ -95,3 +103,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:33483dcd0b98f2e10aa030080f8367fb814c510b601fc8ff396d0122236d750e) diff --git a/doc/lightning-multifundchannel.7 b/doc/lightning-multifundchannel.7 index a626ef63f..7c1e7e23f 100644 --- a/doc/lightning-multifundchannel.7 +++ b/doc/lightning-multifundchannel.7 @@ -98,8 +98,6 @@ transactions\. See \fIfeerate\fR for valid values\. .SH RETURN VALUE -On success, the \fItx\fR and \fItxid\fR of the signed and broadcsted funding -transaction is returned\. This command opens multiple channels with a single large transaction, thus only one transaction is returned\. @@ -109,23 +107,52 @@ then it is possible that one or more of the destinations do not have a channel even if \fBmultifundchannel\fR succeeded\. -An array of \fIchannel_ids\fR is returned; -each entry of the array is an object, - with an \fIid\fR field being the node ID of the peer, - an \fIoutnum\fR field being the output number of the transaction - that anchors this channel, - and \fIchannel_id\fR field being the channel ID with that peer\. +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBtx\fR (hex): The raw transaction which funded the channel +.IP \[bu] +\fBtxid\fR (txid): The txid of the transaction which funded the channel +.IP \[bu] +\fBchannel_ids\fR (array of objects): +.RS +.IP \[bu] +\fBid\fR (pubkey): The peer we opened the channel with +.IP \[bu] +\fBoutnum\fR (u32): The 0-based output index showing which output funded the channel +.IP \[bu] +\fBchannel_id\fR (hex): The channel_id of the resulting channel (always 64 characters) +.IP \[bu] +\fBclose_to\fR (hex, optional): The raw scriptPubkey which mutual close will go to; only present if \fIclose_to\fR parameter was specified and peer supports \fBoption_upfront_shutdown_script\fR + +.RE + +.IP \[bu] +\fBfailed\fR (array of objects, optional): any peers we failed to open with (if \fIminchannels\fR was specified less than the number of destinations): +.RS +.IP \[bu] +\fBid\fR (pubkey): The peer we failed to open the channel with +.IP \[bu] +\fBmethod\fR (string): What stage we failed at (one of "connect", "openchannel_init", "fundchannel_start", "fundchannel_complete") +.IP \[bu] +\fBerror\fR (object): +.RS +.IP \[bu] +\fBcode\fR (integer): JSON error code from failing stage +.IP \[bu] +\fBmessage\fR (string): Message from stage +.IP \[bu] +\fBdata\fR: Additional error data + +.RE -An array of \fIfailed\fR is returned, -which contains the destinations that were removed -due to failures (this can only happen on success if \fIminchannels\fR was specified)\. -Each entry of the array is an object, - with an \fIid\fR field being the node ID of the removed peer, - \fImethod\fR field describing what phase of funding the peer failed, - and \fIerror\fR field of the exact error returned by the method\. +.RE +.RE + On failure, none of the channels are created\. @@ -177,4 +204,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:45015c53c73dc4d84850c84cb753d62739288365746b47f0403fb67e5f65d582 +\" SHA256STAMP:86b05635f6d0d55dc3771779237bf1046b52f8cd290f16cccc5656cb94f2863a diff --git a/doc/lightning-multifundchannel.7.md b/doc/lightning-multifundchannel.7.md index 07b7307c8..4f6c43b1e 100644 --- a/doc/lightning-multifundchannel.7.md +++ b/doc/lightning-multifundchannel.7.md @@ -84,8 +84,6 @@ transactions. See *feerate* for valid values. RETURN VALUE ------------ -On success, the *tx* and *txid* of the signed and broadcsted funding -transaction is returned. This command opens multiple channels with a single large transaction, thus only one transaction is returned. @@ -93,20 +91,23 @@ If *minchannels* was specified and is less than the number of destinations, then it is possible that one or more of the destinations do not have a channel even if **multifundchannel** succeeded. -An array of *channel\_ids* is returned; -each entry of the array is an object, - with an *id* field being the node ID of the peer, - an *outnum* field being the output number of the transaction - that anchors this channel, - and *channel_id* field being the channel ID with that peer. - -An array of *failed* is returned, -which contains the destinations that were removed -due to failures (this can only happen on success if *minchannels* was specified). -Each entry of the array is an object, - with an *id* field being the node ID of the removed peer, - *method* field describing what phase of funding the peer failed, - and *error* field of the exact error returned by the method. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **tx** (hex): The raw transaction which funded the channel +- **txid** (txid): The txid of the transaction which funded the channel +- **channel_ids** (array of objects): + - **id** (pubkey): The peer we opened the channel with + - **outnum** (u32): The 0-based output index showing which output funded the channel + - **channel_id** (hex): The channel_id of the resulting channel (always 64 characters) + - **close_to** (hex, optional): The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script` +- **failed** (array of objects, optional): any peers we failed to open with (if *minchannels* was specified less than the number of destinations): + - **id** (pubkey): The peer we failed to open the channel with + - **method** (string): What stage we failed at (one of "connect", "openchannel_init", "fundchannel_start", "fundchannel_complete") + - **error** (object): + - **code** (integer): JSON error code from failing stage + - **message** (string): Message from stage + - **data**: Additional error data +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, none of the channels are created. @@ -150,3 +151,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:96f061609558a3baa93a2d212ef9de0d5a3cf3217504ddd42b99bf2bf2249e2c) diff --git a/doc/lightning-multiwithdraw.7 b/doc/lightning-multiwithdraw.7 index 85cab4c42..c674ebbe6 100644 --- a/doc/lightning-multiwithdraw.7 +++ b/doc/lightning-multiwithdraw.7 @@ -41,12 +41,15 @@ of "txid:vout"\. These must be drawn from the node's available UTXO set\. .SH RETURN VALUE -On success, an object with attributes \fItx\fR and \fItxid\fR will be returned\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBtx\fR (hex): The raw transaction which was sent +.IP \[bu] +\fBtxid\fR (txid): The txid of the \fBtx\fR -\fItx\fR represents the raw bitcoin, fully signed, transaction and \fItxid\fR -represent the bitcoin transaction id\. - +.RE On failure, an error is reported and the withdrawal transaction is not created\. @@ -77,4 +80,4 @@ ZmnSCPxj < \fIZmnSCPxj@protonmail.com\fR > is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:2781b462676e158a5532e71259155324a8fd3ee79fcbb2cc7a467948e61b1c1b +\" SHA256STAMP:afa116f6c9b71fb0940eb70b541fc32fd6fc4773b13cd023c32549ebd54e9e03 diff --git a/doc/lightning-multiwithdraw.7.md b/doc/lightning-multiwithdraw.7.md index 9425aec05..a8d85a603 100644 --- a/doc/lightning-multiwithdraw.7.md +++ b/doc/lightning-multiwithdraw.7.md @@ -40,10 +40,11 @@ of "txid:vout". These must be drawn from the node's available UTXO set. RETURN VALUE ------------ -On success, an object with attributes *tx* and *txid* will be returned. - -*tx* represents the raw bitcoin, fully signed, transaction and *txid* -represent the bitcoin transaction id. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **tx** (hex): The raw transaction which was sent +- **txid** (txid): The txid of the **tx** +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is reported and the withdrawal transaction is not created. @@ -69,3 +70,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:5f289ef109eba26ca686ca0ebde3fed38cd52240ad3ee30e373719872927cfe6) diff --git a/doc/lightning-newaddr.7 b/doc/lightning-newaddr.7 index dd6493f79..76a01c5a4 100644 --- a/doc/lightning-newaddr.7 +++ b/doc/lightning-newaddr.7 @@ -27,9 +27,15 @@ If no \fIaddresstype\fR is specified the address generated is a \fIbech32\fR add .SH RETURN VALUE -On success, a \fIbech32\fR address and/or a \fIp2sh-segwit\fR address will be -returned\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBbech32\fR (string, optional): The bech32 (native segwit) address +.IP \[bu] +\fBp2sh-segwit\fR (string, optional): The p2sh-wrapped address + +.RE .SH ERRORS If an unrecognized address type is requested an error message will be @@ -47,4 +53,4 @@ Felix \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:627e85582c687ee97dea1dd1df6b3eb23000058626ab71bc4883dd1441595772 +\" SHA256STAMP:4e2f3697f7a6841d28997583e5fc4b709533b7be73c72428e1af361d0022cb1a diff --git a/doc/lightning-newaddr.7.md b/doc/lightning-newaddr.7.md index 63dc74020..c099ab4e9 100644 --- a/doc/lightning-newaddr.7.md +++ b/doc/lightning-newaddr.7.md @@ -27,8 +27,11 @@ If no *addresstype* is specified the address generated is a *bech32* address. RETURN VALUE ------------ -On success, a *bech32* address and/or a *p2sh-segwit* address will be -returned. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **bech32** (string, optional): The bech32 (native segwit) address +- **p2sh-segwit** (string, optional): The p2sh-wrapped address +[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -51,3 +54,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:44731ac3afb4fc3982dff2ae94e360f9addc5712e36b021c880180c68e3ed476) diff --git a/doc/lightning-notifications.7 b/doc/lightning-notifications.7 index 704682c52..252abf628 100644 --- a/doc/lightning-notifications.7 +++ b/doc/lightning-notifications.7 @@ -59,8 +59,11 @@ indicating what stage we are progressing through\. .RE .SH RETURN VALUE -On success, an empty object will be returned, and if the level was -\fItrue\fR, notifications will be forwarded from then on\. +On success, an empty object is returned\. + + +On success, if \fIenable\fR was \fItrue\fR, notifications will be forwarded +from then on\. On failure, one of the following error codes may be returned: @@ -109,4 +112,4 @@ Rusty Russell \fI wrote the initial version of this ma Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:2b6e9c8a814cb8de7b15e70de3563be5311e232e974f546d79c546aec641c3fe +\" SHA256STAMP:bc568c59f4cccbd3f8de1a2c57309b3b07deeabe1dabf1bfbe289973ede7921b diff --git a/doc/lightning-notifications.7.md b/doc/lightning-notifications.7.md index 02086d390..776be84bb 100644 --- a/doc/lightning-notifications.7.md +++ b/doc/lightning-notifications.7.md @@ -52,8 +52,12 @@ Common *method*s include: RETURN VALUE ------------ -On success, an empty object will be returned, and if the level was -*true*, notifications will be forwarded from then on. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an empty object is returned. +[comment]: # (GENERATE-FROM-SCHEMA-END) + +On success, if *enable* was *true*, notifications will be forwarded +from then on. On failure, one of the following error codes may be returned: @@ -97,3 +101,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:f807f98a54c194fab710f8a3393e96685fdbd0efa5e178cca54507a70a7a5c20) diff --git a/doc/lightning-offer.7 b/doc/lightning-offer.7 index a09f6d0aa..eae6ebb78 100644 --- a/doc/lightning-offer.7 +++ b/doc/lightning-offer.7 @@ -100,8 +100,23 @@ invoices will be expired (i\.e\. only one person can pay this offer)\. .SH RETURN VALUE -On success, an object as follows is returned as per \fBlightning-listoffers\fR(7)\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) +.IP \[bu] +\fBactive\fR (boolean): whether this can still be used (always \fItrue\fR) +.IP \[bu] +\fBsingle_use\fR (boolean): whether this expires as soon as it's paid (reflects the \fIsingle_use\fR parameter) +.IP \[bu] +\fBbolt12\fR (string): the bolt12 encoding of the offer +.IP \[bu] +\fBused\fR (boolean): True if an associated invoice has been paid (always \fIfalse\fR) +.IP \[bu] +\fBlabel\fR (string, optional): the (optional) user-specified label + +.RE On failure, an error is returned and no offer is created\. If the lightning process fails before responding, the caller should use @@ -130,4 +145,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:32c3f313b94ca968683060c9b8ba81c76b610b3b0f0c604a24a2f88bb8130c2c +\" SHA256STAMP:fdc65b544ee660ef7afafb13bc727b859411df072739c4b22973fbc870d785f2 diff --git a/doc/lightning-offer.7.md b/doc/lightning-offer.7.md index 1de0fb6ad..b223c8130 100644 --- a/doc/lightning-offer.7.md +++ b/doc/lightning-offer.7.md @@ -89,7 +89,15 @@ invoices will be expired (i.e. only one person can pay this offer). RETURN VALUE ------------ -On success, an object as follows is returned as per lightning-listoffers(7). +[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) +- **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 +- **used** (boolean): True if an associated invoice has been paid (always *false*) +- **label** (string, optional): the (optional) user-specified label +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is returned and no offer is created. If the lightning process fails before responding, the caller should use @@ -115,3 +123,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:20c0be7bad73fcf71ccae61c2c5a112c8602216d9d2e9f647f8273fdf4e3ed8b) diff --git a/doc/lightning-offerout.7 b/doc/lightning-offerout.7 index edc2ec9c9..ec7823234 100644 --- a/doc/lightning-offerout.7 +++ b/doc/lightning-offerout.7 @@ -52,25 +52,21 @@ that previous \fBpayer_key\fR\. .SH RETURN VALUE -On success, an object as follows is returned: +On success, an object is returned, containing: .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 will pay a matching incoming invoice (always \fItrue\fR) .IP \[bu] -\fIsingle_use\fR: true +\fBsingle_use\fR (boolean): whether this expires as soon as it's paid out (always \fItrue\fR) .IP \[bu] -\fIbolt12\fR: the bolt12 offer, starting with "lno1" - -.RE - -Optionally: - -.RS +\fBbolt12\fR (string): the bolt12 encoding of the offer .IP \[bu] -\fIlabel\fR: the user-specified label\. +\fBused\fR (boolean): True if an incoming invoice has been paid (always \fIfalse\fR) +.IP \[bu] +\fBlabel\fR (string, optional): the (optional) user-specified label .RE @@ -110,4 +106,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:87487dd8a47b745a98d107e1de7cb3eac0421f3ccaf44a4d2a938fa19f6261c0 +\" SHA256STAMP:ccf9c53e1189ef9138954beed8fe5e5318e2dfebb53fde2ee20a8777aff255b5 diff --git a/doc/lightning-offerout.7.md b/doc/lightning-offerout.7.md index 8b7266a60..aa3c1439d 100644 --- a/doc/lightning-offerout.7.md +++ b/doc/lightning-offerout.7.md @@ -49,15 +49,15 @@ that previous `payer_key`. RETURN VALUE ------------ -On success, an object as follows is returned: - -* *offer_id*: the hash of the offer. -* *active*: true -* *single_use*: true -* *bolt12*: the bolt12 offer, starting with "lno1" - -Optionally: -* *label*: the user-specified label. +[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) +- **active** (boolean): whether this will pay a matching incoming invoice (always *true*) +- **single_use** (boolean): whether this expires as soon as it's paid out (always *true*) +- **bolt12** (string): the bolt12 encoding of the offer +- **used** (boolean): True if an incoming invoice has been paid (always *false*) +- **label** (string, optional): the (optional) user-specified label +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is returned and no offer is created. If the lightning process fails before responding, the caller should use @@ -92,3 +92,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:6db3fdba07f376e697326b3bf1bd74c013084a459cb9f4fe76d23fce58bd58fe) diff --git a/doc/lightning-openchannel_abort.7 b/doc/lightning-openchannel_abort.7 index 7dd3d105a..32be871a1 100644 --- a/doc/lightning-openchannel_abort.7 +++ b/doc/lightning-openchannel_abort.7 @@ -16,10 +16,17 @@ which allows for interactive transaction construction\. .SH RETURN VALUE -On success, returns the \fIchannel_id\fR for this channel; an boolean indicating -if the channel has been successfully canceled, \fIchannel_canceled\fR; -a reason for the cancellation, \fIreason\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): the channel id of the aborted channel (always 64 characters) +.IP \[bu] +\fBreason\fR (string): usually "Abort requested", but if it happened to fail at the same time it could be different +.IP \[bu] +\fBchannel_canceled\fR (boolean, optional): whether this is completely canceled (there may be remaining in-flight transactions) + +.RE On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -53,4 +60,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7), Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:3c6aa3f2359134f7468facf69f3f6b925334117079a46ada88ec9b6b8cdd3f0a +\" SHA256STAMP:d2ed75d41e90988cf4a1919afb443e7a8f4b9c52fb8aa404af16d6feb44cacc8 diff --git a/doc/lightning-openchannel_abort.7.md b/doc/lightning-openchannel_abort.7.md index cbca56165..ab7b602e5 100644 --- a/doc/lightning-openchannel_abort.7.md +++ b/doc/lightning-openchannel_abort.7.md @@ -19,9 +19,12 @@ which allows for interactive transaction construction. RETURN VALUE ------------ -On success, returns the *channel_id* for this channel; an boolean indicating -if the channel has been successfully canceled, *channel_canceled*; -a reason for the cancellation, *reason*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): the channel id of the aborted channel (always 64 characters) +- **reason** (string): usually "Abort requested", but if it happened to fail at the same time it could be different +- **channel_canceled** (boolean, optional): whether this is completely canceled (there may be remaining in-flight transactions) +[comment]: # (GENERATE-FROM-SCHEMA-END) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -50,3 +53,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:01188472cb94be6d8a69372b8fc6c77e0176aac6234a0ae2332906d2176f820d) diff --git a/doc/lightning-openchannel_bump.7 b/doc/lightning-openchannel_bump.7 index fc3dd74c5..6af9927cb 100644 --- a/doc/lightning-openchannel_bump.7 +++ b/doc/lightning-openchannel_bump.7 @@ -29,13 +29,19 @@ is not met\. .SH RETURN VALUE -On success, returns the \fIchannel_id\fR for this channel; an updated -incomplete \fIinitialpsbt\fR for this funding transaction; and the flag -\fIcommitments_secured\fR, which indiciates the completeness of the -passed back \fIpsbt\fR\. (Will always be false)\. Also returns the -\fIfunding_serial\fR, indicating the serial_id of the funding output -in the \fIpsbt\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): the channel id of the channel (always 64 characters) +.IP \[bu] +\fBpsbt\fR (string): the (incomplete) PSBT of the RBF transaction +.IP \[bu] +\fBcommitments_secured\fR (boolean): whether the \fIpsbt\fR is complete (always \fIfalse\fR) +.IP \[bu] +\fBfunding_serial\fR (u64): the serial_id of the funding output in the \fIpsbt\fR + +.RE If the peer does not support \fBoption_dual_fund\fR, this command will return an error\. @@ -83,4 +89,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7), Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:3a1f4ea363bae832e6c100bfb4a015223c2225d1eb8c0497e71e844df1bb9a99 +\" SHA256STAMP:53b3a3b647564ae97a249226271642dc775985dce376065dd95d332d9f60dd95 diff --git a/doc/lightning-openchannel_bump.7.md b/doc/lightning-openchannel_bump.7.md index 9f8646802..d2a29363f 100644 --- a/doc/lightning-openchannel_bump.7.md +++ b/doc/lightning-openchannel_bump.7.md @@ -29,12 +29,13 @@ is not met. RETURN VALUE ------------ -On success, returns the *channel_id* for this channel; an updated -incomplete *initialpsbt* for this funding transaction; and the flag -*commitments_secured*, which indiciates the completeness of the -passed back *psbt*. (Will always be false). Also returns the -*funding_serial*, indicating the serial\_id of the funding output -in the *psbt*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): the channel id of the channel (always 64 characters) +- **psbt** (string): the (incomplete) PSBT of the RBF transaction +- **commitments_secured** (boolean): whether the *psbt* is complete (always *false*) +- **funding_serial** (u64): the serial_id of the funding output in the *psbt* +[comment]: # (GENERATE-FROM-SCHEMA-END) If the peer does not support `option_dual_fund`, this command will return an error. @@ -72,3 +73,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:51eff069a2fa8a2695cd613514f9562d3b636e451a62e7344194b7f25f06709a) diff --git a/doc/lightning-openchannel_init.7 b/doc/lightning-openchannel_init.7 index a92edbb7b..0e236b7a9 100644 --- a/doc/lightning-openchannel_init.7 +++ b/doc/lightning-openchannel_init.7 @@ -45,13 +45,19 @@ sent on close\. Only valid if both peers have negotiated .SH RETURN VALUE -On success, returns the \fIchannel_id\fR for this channel; an updated -incomplete \fIinitialpsbt\fR for this funding transaction; and the flag -\fIcommitments_secured\fR, which indiciates the completeness of the -passed back \fIpsbt\fR\. (Will always be false)\. Also returns the -\fIfunding_serial\fR, indicating the serial_id of the funding output -in the \fIpsbt\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): the channel id of the channel (always 64 characters) +.IP \[bu] +\fBcommitments_secured\fR (boolean): whether the \fIpsbt\fR is complete (always \fIfalse\fR) +.IP \[bu] +\fBfunding_serial\fR (u64): the serial_id of the funding output in the \fIpsbt\fR +.IP \[bu] +\fBintiialpsbt\fR (string, optional): the (incomplete) PSBT of the funding transaction + +.RE If the peer does not support \fBoption_dual_fund\fR, this command will return an error\. @@ -99,4 +105,4 @@ lightning-fundchannel_\fBcomplete\fR(7), \fBlightning-fundchannel\fR(7), Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:8e37cb8813751e06f59b108e8a335b5b5269e5764c346838a6ddf79138ccea6e +\" SHA256STAMP:4663cea3fc74a8e91e7a3de6997a7b5a236bacf84dda3ed826cbbd7d544c39e8 diff --git a/doc/lightning-openchannel_init.7.md b/doc/lightning-openchannel_init.7.md index 0385e1acb..7bb95f95c 100644 --- a/doc/lightning-openchannel_init.7.md +++ b/doc/lightning-openchannel_init.7.md @@ -42,12 +42,13 @@ sent on close. Only valid if both peers have negotiated RETURN VALUE ------------ -On success, returns the *channel_id* for this channel; an updated -incomplete *initialpsbt* for this funding transaction; and the flag -*commitments_secured*, which indiciates the completeness of the -passed back *psbt*. (Will always be false). Also returns the -*funding_serial*, indicating the serial\_id of the funding output -in the *psbt*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): the channel id of the channel (always 64 characters) +- **commitments_secured** (boolean): whether the *psbt* is complete (always *false*) +- **funding_serial** (u64): the serial_id of the funding output in the *psbt* +- **intiialpsbt** (string, optional): the (incomplete) PSBT of the funding transaction +[comment]: # (GENERATE-FROM-SCHEMA-END) If the peer does not support `option_dual_fund`, this command will return an error. @@ -84,3 +85,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:a633941043ea5882c89e444cd1e41cb7040716c092b4b5e8aaf6ddafbbcf1a5d) diff --git a/doc/lightning-openchannel_signed.7 b/doc/lightning-openchannel_signed.7 index d32063dfa..c428e3ffa 100644 --- a/doc/lightning-openchannel_signed.7 +++ b/doc/lightning-openchannel_signed.7 @@ -30,9 +30,17 @@ PSBT\. .SH RETURN VALUE -On success, returns the \fIchannel_id\fR for this channel; hex \fItx\fR of the -published funding transaction; and \fItxid\fR of the funding transaction\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): the channel id of the channel (always 64 characters) +.IP \[bu] +\fBtx\fR (hex): the funding transaction +.IP \[bu] +\fBtxid\fR (txid): The txid of the \fBtx\fR + +.RE On error, the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -70,4 +78,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7), Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:bd874415c73718a0a16c37c9d8cf6fec2944a491b05f2632b1ea2ff35c7a50ae +\" SHA256STAMP:efb7b828948c079a668fec715e380df4d8e81e2c1cf9f243f00afbc155abf8e5 diff --git a/doc/lightning-openchannel_signed.7.md b/doc/lightning-openchannel_signed.7.md index d16ba2318..049fd1b31 100644 --- a/doc/lightning-openchannel_signed.7.md +++ b/doc/lightning-openchannel_signed.7.md @@ -29,8 +29,12 @@ PSBT. RETURN VALUE ------------ -On success, returns the *channel_id* for this channel; hex *tx* of the -published funding transaction; and *txid* of the funding transaction. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): the channel id of the channel (always 64 characters) +- **tx** (hex): the funding transaction +- **txid** (txid): The txid of the **tx** +[comment]: # (GENERATE-FROM-SCHEMA-END) On error, the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -61,3 +65,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:ec0d412cdcbc4adea1c6e5a56d527c21894f4a36cd0dc49e858163d0a9221368) diff --git a/doc/lightning-openchannel_update.7 b/doc/lightning-openchannel_update.7 index 7e702ec7f..18c2aec4d 100644 --- a/doc/lightning-openchannel_update.7 +++ b/doc/lightning-openchannel_update.7 @@ -29,12 +29,17 @@ the PSBT last returned by either \fBopenchannel_init\fR or \fBopenchannel_update .SH RETURN VALUE -On success, returns the \fIchannel_id\fR for this channel; an updated, potentially -complete \fIpsbt\fR for this channel's funding transaction; and the flag -\fIcommitments_secured\fR, which indicates the completeness of the returned \fIpsbt\fR\. -If \fIcommitments_secured\fR is true, caller should proceed with signing the -returned PSBT and calling \fBopenchannel_signed\fR to complete the channel open\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): the channel id of the channel (always 64 characters) +.IP \[bu] +\fBpsbt\fR (string): the PSBT of the funding transaction +.IP \[bu] +\fBcommitments_secured\fR (boolean): whether the \fIpsbt\fR is complete (if true, sign \fIpsbt\fR and call \fBopenchannel_signed\fR to complete the channel open) + +.RE If \fIcommitments_secured\fR is true, will also return: @@ -80,4 +85,4 @@ lightning-fundchannel_\fBstart\fR(7), lightning-fundchannel_\fBcomplete\fR(7), Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:bc76c4c09f0c4c9c9f1e6b78f9ca495042076abac00c06309a94957646f07974 +\" SHA256STAMP:e363c79e7b56230752d8e1612ae1587501d1376c7b2b18dd647baaf25303372b diff --git a/doc/lightning-openchannel_update.7.md b/doc/lightning-openchannel_update.7.md index db52d3964..ed09a5f1e 100644 --- a/doc/lightning-openchannel_update.7.md +++ b/doc/lightning-openchannel_update.7.md @@ -28,11 +28,12 @@ the PSBT last returned by either `openchannel_init` or `openchannel_update`. RETURN VALUE ------------ -On success, returns the *channel_id* for this channel; an updated, potentially -complete *psbt* for this channel's funding transaction; and the flag -*commitments_secured*, which indicates the completeness of the returned *psbt*. -If *commitments_secured* is true, caller should proceed with signing the -returned PSBT and calling `openchannel_signed` to complete the channel open. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): the channel id of the channel (always 64 characters) +- **psbt** (string): the PSBT of the funding transaction +- **commitments_secured** (boolean): whether the *psbt* is complete (if true, sign *psbt* and call `openchannel_signed` to complete the channel open) +[comment]: # (GENERATE-FROM-SCHEMA-END) If *commitments_secured* is true, will also return: - The derived *channel_id*. @@ -67,3 +68,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:7e6db299a5b5bbbd3561c69153ea6444d51850a814a8bec58e433fa7be97949c) diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index b7acf0b6b..ddc3e8e8a 100644 --- a/doc/lightning-pay.7 +++ b/doc/lightning-pay.7 @@ -76,11 +76,35 @@ exceed \fImaxdelay\fR\. .SH RETURN VALUE -On success, this returns the \fIpayment_preimage\fR which hashes to the -\fIpayment_hash\fR to prove that the payment was successful\. It will also -return, a \fIgetroute_tries\fR and a \fIsendpay_tries\fR statistics for the -number of times it internally called \fBgetroute\fR and \fBsendpay\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters) +.IP \[bu] +\fBcreated_at\fR (number): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBparts\fR (u32): how many attempts this took +.IP \[bu] +\fBamount_msat\fR (msat): Amount the recipient received +.IP \[bu] +\fBamount_sent_msat\fR (msat): Total amount we sent (including fees) +.IP \[bu] +\fBstatus\fR (string): status of payment (always "complete") +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment + +.RE + +The following warnings may also be returned: + +.RS +.IP \[bu] +\fBwarning_partial_completion\fR: Not all parts of a multi-part payment have completed + +.RE You can monitor the progress and retries of a payment using the \fBlightning-paystatus\fR(7) command\. @@ -158,4 +182,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:c33dee8ebd5fd5b764f81ceb777a59c5b0c1162f6fc1ae1fba8b38f5215e2e13 +\" SHA256STAMP:ef0d5186428437104bb2f9c5449a37fc2fc5b1438633259ee7d2915dc07d3dc5 diff --git a/doc/lightning-pay.7.md b/doc/lightning-pay.7.md index 03f746a67..e7a0c5272 100644 --- a/doc/lightning-pay.7.md +++ b/doc/lightning-pay.7.md @@ -70,10 +70,20 @@ exceed *maxdelay*. RETURN VALUE ------------ -On success, this returns the *payment\_preimage* which hashes to the -*payment\_hash* to prove that the payment was successful. It will also -return, a *getroute\_tries* and a *sendpay\_tries* statistics for the -number of times it internally called **getroute** and **sendpay**. +[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) +- **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 +- **amount_sent_msat** (msat): Total amount we sent (including fees) +- **status** (string): status of payment (always "complete") +- **destination** (pubkey, optional): the final destination of the payment + +The following warnings may also be returned: +- **warning_partial_completion**: Not all parts of a multi-part payment have completed +[comment]: # (GENERATE-FROM-SCHEMA-END) You can monitor the progress and retries of a payment using the lightning-paystatus(7) command. @@ -132,3 +142,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:787ea6ae933da77756aca49aee68ba996cd54aea53b85ce2e5fcc85841022241) diff --git a/doc/lightning-ping.7 b/doc/lightning-ping.7 index aca80e7b2..4988cf586 100644 --- a/doc/lightning-ping.7 +++ b/doc/lightning-ping.7 @@ -34,11 +34,11 @@ The \fBping\fR command checks if the node with \fIid\fR is ready to talk\. It ac .fi .SH RETURN VALUE -On success, the command will return an object with a single string\. +On success, an object is returned, containing: .RS .IP \[bu] -\fItotlen\fR: A string that represents the answer length of the reply message (including header) +\fBtotlen\fR (u16): the answer length of the reply message (including header: 0 means no reply expected) .RE @@ -70,4 +70,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:eac5506bc761a2a9570a92c7e533b4c6ba72c56c4d69dce773887a9f88ea7ac2 +\" SHA256STAMP:78bf096eeb9c1d5f6734486cd9d925f3dc58ca8dfe0f54be0a5369242fbc3b7d diff --git a/doc/lightning-ping.7.md b/doc/lightning-ping.7.md index 9f2e0bf30..9081e2218 100644 --- a/doc/lightning-ping.7.md +++ b/doc/lightning-ping.7.md @@ -31,9 +31,10 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, the command will return an object with a single string. - -- *totlen*: A string that represents the answer length of the reply message (including header) +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **totlen** (u16): the answer length of the reply message (including header: 0 means no reply expected) +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -63,3 +64,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:56bf89ba67c8e1db1bf3c2cf793d59eecd0c5c23012ffb66fe3f8fa8f7d9007c) diff --git a/doc/lightning-plugin.7 b/doc/lightning-plugin.7 index de27fddee..01a696f7f 100644 --- a/doc/lightning-plugin.7 +++ b/doc/lightning-plugin.7 @@ -37,12 +37,37 @@ The \fIlist\fR command will return all the active plugins\. .SH RETURN VALUE -On success, all subcommands but \fIstop\fR return an array \fIplugins\fR of -objects, one by plugin\. -Each object contains the name of the plugin (\fIname\fR field) and its -status (\fIactive\fR boolean field)\. Since plugins are configured -asynchronously, a freshly started plugin may not appear immediately\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBcommand\fR (string): the subcommand this is responding to (one of "start", "stop", "rescan", "startdir", "list") + +.RE + +If \fBcommand\fR is "start", "startdir", "rescan" or "list": + +.RS +.IP \[bu] +\fBplugins\fR (array of objects): +.RS +.IP \[bu] +\fBname\fR (string): full pathname of the plugin +.IP \[bu] +\fBactive\fR (boolean): status; since plugins are configured asynchronously, a freshly started plugin may not appear immediately\. + +.RE + + +.RE + +If \fBcommand\fR is "stop": + +.RS +.IP \[bu] +\fBresult\fR (string): A message saying it successfully stopped + +.RE On error, the reason why the action could not be taken upon the plugin is returned\. @@ -55,4 +80,4 @@ Antoine Poinsot \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:f4b405aa5a5bb8dde3b8947b7d6152ba5ac88108cde43c1375121e5c24555d30 +\" SHA256STAMP:281abf9aa97a3cb1204adc209541c3cfdcb1ca0126f62a126338dcd2fcd0bc8e diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md index e0b91426e..d4b26ae21 100644 --- a/doc/lightning-plugin.7.md +++ b/doc/lightning-plugin.7.md @@ -35,11 +35,18 @@ The *list* command will return all the active plugins. RETURN VALUE ------------ -On success, all subcommands but *stop* return an array *plugins* of -objects, one by plugin. -Each object contains the name of the plugin (*name* field) and its -status (*active* boolean field). Since plugins are configured -asynchronously, a freshly started plugin may not appear immediately. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **command** (string): the subcommand this is responding to (one of "start", "stop", "rescan", "startdir", "list") + +If **command** is "start", "startdir", "rescan" or "list": + - **plugins** (array of objects): + - **name** (string): full pathname of the plugin + - **active** (boolean): status; since plugins are configured asynchronously, a freshly started plugin may not appear immediately. + +If **command** is "stop": + - **result** (string): A message saying it successfully stopped +[comment]: # (GENERATE-FROM-SCHEMA-END) On error, the reason why the action could not be taken upon the plugin is returned. @@ -54,3 +61,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:a14192d703b99bb39ed7a297bcee462a51b9728ad6d6477dd65ad636c0c87c02) diff --git a/doc/lightning-reserveinputs.7 b/doc/lightning-reserveinputs.7 index 7a80c59ab..21bca8370 100644 --- a/doc/lightning-reserveinputs.7 +++ b/doc/lightning-reserveinputs.7 @@ -23,6 +23,22 @@ hours), but this can be changed by setting \fIreserve\fR\. .SH RETURN VALUE +On success, an object containing \fBreservations\fR is returned\. It is an array of objects, where each object contains: + +.RS +.IP \[bu] +\fBtxid\fR (txid): the transaction id +.IP \[bu] +\fBvout\fR (u32): the output number which was reserved +.IP \[bu] +\fBwas_reserved\fR (boolean): whether the input was already reserved +.IP \[bu] +\fBreserved\fR (boolean): whether the input is now reserved (always \fItrue\fR) +.IP \[bu] +\fBreserved_to_block\fR (u32): what blockheight the reservation will expire + +.RE + On success, a \fIreservations\fR array is returned, with an entry for each input which was reserved: @@ -62,4 +78,4 @@ niftynei \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:81be9e3af4075dd3bd24c6461861ee067b435654d88817afd0c49d37e85768a3 +\" SHA256STAMP:57c1d91f48a095284bb62ef36d88cce487c44759f4ead192ebe9a97d084d028d diff --git a/doc/lightning-reserveinputs.7.md b/doc/lightning-reserveinputs.7.md index d8b1b7b69..425fc25c3 100644 --- a/doc/lightning-reserveinputs.7.md +++ b/doc/lightning-reserveinputs.7.md @@ -24,6 +24,15 @@ hours), but this can be changed by setting *reserve*. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **reservations** is returned. It is an array of objects, where each object contains: +- **txid** (txid): the transaction id +- **vout** (u32): the output number which was reserved +- **was_reserved** (boolean): whether the input was already reserved +- **reserved** (boolean): whether the input is now reserved (always *true*) +- **reserved_to_block** (u32): what blockheight the reservation will expire +[comment]: # (GENERATE-FROM-SCHEMA-END) + On success, a *reservations* array is returned, with an entry for each input which was reserved: @@ -53,3 +62,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:bf45dfdf5c5c3a47e6e9ded7f42260ee07b1e6d02e84f39f2bce809650ed19b3) diff --git a/doc/lightning-sendinvoice.7 b/doc/lightning-sendinvoice.7 index d636395d7..c00d1e107 100644 --- a/doc/lightning-sendinvoice.7 +++ b/doc/lightning-sendinvoice.7 @@ -37,8 +37,39 @@ timeout on the invoice that is sent\. .SH RETURN VALUE -On success, an object as per \fBlightning-waitinvoice\fR(7)\. +On success, an object is returned, containing: +.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] +\fBbolt12\fR (string, optional): the BOLT12 string + +.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 The following error codes may occur: @@ -67,4 +98,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:25da409961f77393d1af898e5ddf7757c4ed14c1a4eea58264c969924259ab1e +\" SHA256STAMP:de314ada333bec6eb2bad2ad1410201c8c99c492203cf178dfacd95d7b74c0f9 diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md index 64561f3f7..df5727e3f 100644 --- a/doc/lightning-sendinvoice.7.md +++ b/doc/lightning-sendinvoice.7.md @@ -34,7 +34,22 @@ timeout on the invoice that is sent. RETURN VALUE ------------ -On success, an object as per lightning-waitinvoice(7). +[comment]: # (GENERATE-FROM-SCHEMA-START) +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) +- **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 +- **bolt12** (string, optional): the BOLT12 string + +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) The following error codes may occur: - -1: Catchall nonspecific error. @@ -58,3 +73,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:8e245f0780b07e68f4b76989c0fbd00ad088f4f4c832b9f05b69ba037ba16df9) diff --git a/doc/lightning-sendonion.7 b/doc/lightning-sendonion.7 index da3f8fe4a..232d6b1da 100644 --- a/doc/lightning-sendonion.7 +++ b/doc/lightning-sendonion.7 @@ -98,11 +98,47 @@ The \fImsatoshi\fR parameter is used to annotate the payment, and is returned by .SH RETURN VALUE -On success, an object similar to the output of \fBsendpay\fR will be -returned\. This object will have a \fIstatus\fR field that is typically the string -\fI"pending"\fR, but may be \fI"complete"\fR if the payment was already performed -successfully\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBid\fR (u64): unique ID for this payment attempt +.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): status of the payment (could be complete if already sent previously) (one of "pending", "complete") +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBamount_sent_msat\fR (msat): The amount sent +.IP \[bu] +\fBamount_msat\fR (msat, optional): The amount delivered to destination (if known) +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment if known +.IP \[bu] +\fBlabel\fR (string, optional): the label, if given to sendpay +.IP \[bu] +\fBbolt11\fR (string, optional): the bolt11 string (if supplied) +.IP \[bu] +\fBbolt12\fR (string, optional): the bolt12 string (if supplied: \fBexperimental-offers\fR only)\. + +.RE + +If \fBstatus\fR is "complete": + +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) + +.RE + +If \fBstatus\fR is "pending": + +.RS +.IP \[bu] +\fBmessage\fR (string, optional): Monitor status with listpays or waitsendpay + +.RE If \fIshared_secrets\fR was provided and an error was returned by one of the intermediate nodes the error details are decrypted and presented @@ -120,4 +156,4 @@ Christian Decker \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:1d7ceae27ac4ac51597b92de50cf7bc917c59bdf59f3280efc06491ed4efaffc +\" SHA256STAMP:5d91baad544b373c2df39220b6928d292a72239c8e41ae4ec428fdfb46727c8e diff --git a/doc/lightning-sendonion.7.md b/doc/lightning-sendonion.7.md index 29c26d9a1..3ea209579 100644 --- a/doc/lightning-sendonion.7.md +++ b/doc/lightning-sendonion.7.md @@ -86,10 +86,25 @@ The *msatoshi* parameter is used to annotate the payment, and is returned by RETURN VALUE ------------ -On success, an object similar to the output of **sendpay** will be -returned. This object will have a *status* field that is typically the string -*"pending"*, but may be *"complete"* if the payment was already performed -successfully. +[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) +- **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 +- **amount_msat** (msat, optional): The amount delivered to destination (if known) +- **destination** (pubkey, optional): the final destination of the payment if known +- **label** (string, optional): the label, if given to sendpay +- **bolt11** (string, optional): the bolt11 string (if supplied) +- **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) + +If **status** is "pending": + - **message** (string, optional): Monitor status with listpays or waitsendpay +[comment]: # (GENERATE-FROM-SCHEMA-END) If *shared_secrets* was provided and an error was returned by one of the intermediate nodes the error details are decrypted and presented @@ -111,3 +126,4 @@ RESOURCES Main web site: [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md +[comment]: # ( SHA256STAMP:2cc04261aaff4e8a3fc5e20628dd74c0cc5d511e64e85435a10f56fcec3d70f7) diff --git a/doc/lightning-sendonionmessage.7 b/doc/lightning-sendonionmessage.7 index 089eab827..c27dade85 100644 --- a/doc/lightning-sendonionmessage.7 +++ b/doc/lightning-sendonionmessage.7 @@ -28,7 +28,7 @@ value, optional for final element)\. .SH RETURN VALUE -On success, an empty JSON object is returned\. +On success, an empty object is returned\. .SH AUTHOR @@ -42,4 +42,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:680e0897d06c217e868bbc5b3985dec975d1af37dfd9fd0b91f5e1d9c651b687 +\" SHA256STAMP:c792b84bb590ab7ec719c75db1c54a5147688688b10dd4cd01b10bf3f4e5f357 diff --git a/doc/lightning-sendonionmessage.7.md b/doc/lightning-sendonionmessage.7.md index 7fa4b8785..f5599f9ab 100644 --- a/doc/lightning-sendonionmessage.7.md +++ b/doc/lightning-sendonionmessage.7.md @@ -28,7 +28,9 @@ value, optional for final element). RETURN VALUE ------------ -On success, an empty JSON object is returned. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an empty object is returned. +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -47,3 +49,4 @@ Main web site: [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md +[comment]: # ( SHA256STAMP:b4538602c664359160562ea32ca71a350926201c2001272ac3eba57a32d21040) diff --git a/doc/lightning-sendpay.7 b/doc/lightning-sendpay.7 index 05d77098a..943bfa689 100644 --- a/doc/lightning-sendpay.7 +++ b/doc/lightning-sendpay.7 @@ -58,11 +58,49 @@ with success\. .SH RETURN VALUE -On success, an object similar to the output of \fBlistsendpays\fR will be -returned\. This object will have a \fIstatus\fR field that is typically the -string \fI"pending"\fR, but may be \fI"complete"\fR if the payment was already -performed successfully\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBid\fR (u64): unique ID for this payment attempt +.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): status of the payment (could be complete if already sent previously) (one of "pending", "complete") +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBamount_sent_msat\fR (msat): The amount sent +.IP \[bu] +\fBamount_msat\fR (msat, optional): The amount delivered to destination (if known) +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment if known +.IP \[bu] +\fBlabel\fR (string, optional): the \fIlabel\fR, if given to sendpay +.IP \[bu] +\fBpartid\fR (u64, optional): the \fIpartid\fR, if given to sendpay +.IP \[bu] +\fBbolt11\fR (string, optional): the bolt11 string (if supplied) +.IP \[bu] +\fBbolt12\fR (string, optional): the bolt12 string (if supplied: \fBexperimental-offers\fR only)\. + +.RE + +If \fBstatus\fR is "complete": + +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) + +.RE + +If \fBstatus\fR is "pending": + +.RS +.IP \[bu] +\fBmessage\fR (string): Monitor status with listpays or waitsendpay + +.RE On error, if the error occurred from a node other than the final destination, the route table will be updated so that @@ -129,4 +167,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:4ba54086e62a5f3ee820d71fdd07c66c084a8921c370e470139d81f501e6bf2f +\" SHA256STAMP:5c4bdb9ff7afe78a304d6f999a489210c86f9280592ae49c8ec2d6aa0dc1fc05 diff --git a/doc/lightning-sendpay.7.md b/doc/lightning-sendpay.7.md index d1b20ae31..7ee8cdd2c 100644 --- a/doc/lightning-sendpay.7.md +++ b/doc/lightning-sendpay.7.md @@ -54,10 +54,26 @@ with success. RETURN VALUE ------------ -On success, an object similar to the output of **listsendpays** will be -returned. This object will have a *status* field that is typically the -string *"pending"*, but may be *"complete"* if the payment was already -performed successfully. +[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) +- **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 +- **amount_msat** (msat, optional): The amount delivered to destination (if known) +- **destination** (pubkey, optional): the final destination of the payment if known +- **label** (string, optional): the *label*, if given to sendpay +- **partid** (u64, optional): the *partid*, if given to sendpay +- **bolt11** (string, optional): the bolt11 string (if supplied) +- **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) + +If **status** is "pending": + - **message** (string): Monitor status with listpays or waitsendpay +[comment]: # (GENERATE-FROM-SCHEMA-END) On error, if the error occurred from a node other than the final destination, the route table will be updated so that @@ -109,3 +125,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:96f73baefe7add38af6b6b4618848eff41bbbb1d1c31a0f668611216e4860dd1) diff --git a/doc/lightning-sendpsbt.7 b/doc/lightning-sendpsbt.7 index cd78284da..053d9ed65 100644 --- a/doc/lightning-sendpsbt.7 +++ b/doc/lightning-sendpsbt.7 @@ -31,13 +31,13 @@ The \fBsendpsbt\fR is a low-level RPC command which sends a fully-signed PSBT\. .fi .SH RETURN VALUE -On success, the tx and txid of the transaction are returned\. +On success, an object is returned, containing: .RS .IP \[bu] -\fItxid\fR: A string that represents the hash of transaction\. +\fBtx\fR (hex): The raw transaction which was sent .IP \[bu] -\fItx\fR: A string that represents the hexadecimal dump of the transaction\. +\fBtxid\fR (txid): The txid of the \fBtx\fR .RE @@ -70,4 +70,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:9241e9fa18b3a39ab64bfdfb875dc82ad5ccc242411ad265026005e69f29c2e0 +\" SHA256STAMP:2898a8e7624568fda9d0839758029f42ae9102da4fb85f8e3f9d92bfc82f77bb diff --git a/doc/lightning-sendpsbt.7.md b/doc/lightning-sendpsbt.7.md index 448be84b8..ca4e12b6a 100644 --- a/doc/lightning-sendpsbt.7.md +++ b/doc/lightning-sendpsbt.7.md @@ -30,10 +30,11 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, the tx and txid of the transaction are returned. - -- *txid*: A string that represents the hash of transaction. -- *tx*: A string that represents the hexadecimal dump of the transaction. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **tx** (hex): The raw transaction which was sent +- **txid** (txid): The txid of the **tx** +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -63,3 +64,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:5f289ef109eba26ca686ca0ebde3fed38cd52240ad3ee30e373719872927cfe6) diff --git a/doc/lightning-setchannelfee.7 b/doc/lightning-setchannelfee.7 index 721186d95..c4da7b927 100644 --- a/doc/lightning-setchannelfee.7 +++ b/doc/lightning-setchannelfee.7 @@ -35,10 +35,27 @@ the parameter is left out, the global config value will be used again\. .SH RETURN VALUE -On success, an object with the new values \fIbase\fR and \fIppm\fR along with an -array \fIchannels\fR which contains objects with fields \fIpeer_id\fR, -\fIchannel_id\fR and \fIshort_channel_id\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBbase\fR (u32): The fee_base_msat value +.IP \[bu] +\fBppm\fR (u32): The fee_proportional_millionths value +.IP \[bu] +\fBchannels\fR (array of objects): channel(s) whose rate is now set: +.RS +.IP \[bu] +\fBpeer_id\fR (pubkey): The node_id of the peer +.IP \[bu] +\fBchannel_id\fR (hex): The channel_id of the channel (always 64 characters) +.IP \[bu] +\fBshort_channel_id\fR (short_channel_id, optional): the short_channel_id (if locked in) + +.RE + + +.RE .SH ERRORS The following error codes may occur: @@ -66,4 +83,4 @@ responsible for the c-lightning project\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:c430b82472ac16532cb9997013e4bc85c6aed4cd8baa6bdf881bd2fcd90b9eca +\" SHA256STAMP:91eb0f47428ff356360672487d51db1570b8e344ebc9aea4fe0426d86bae36d8 diff --git a/doc/lightning-setchannelfee.7.md b/doc/lightning-setchannelfee.7.md index 04dff47c5..abbdcbf17 100644 --- a/doc/lightning-setchannelfee.7.md +++ b/doc/lightning-setchannelfee.7.md @@ -35,9 +35,15 @@ the parameter is left out, the global config value will be used again. RETURN VALUE ------------ -On success, an object with the new values *base* and *ppm* along with an -array *channels* which contains objects with fields *peer\_id*, -*channel\_id* and *short\_channel\_id*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **base** (u32): The fee_base_msat value +- **ppm** (u32): The fee_proportional_millionths value +- **channels** (array of objects): channel(s) whose rate is now set: + - **peer_id** (pubkey): The node_id of the peer + - **channel_id** (hex): The channel_id of the channel (always 64 characters) + - **short_channel_id** (short_channel_id, optional): the short_channel_id (if locked in) +[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -65,3 +71,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:6cd332e8d04e65b37bce7365c681ebb28d757f0e75881b3627395ba3e948dc8a) diff --git a/doc/lightning-signmessage.7 b/doc/lightning-signmessage.7 index 7b09bce18..6fd837094 100644 --- a/doc/lightning-signmessage.7 +++ b/doc/lightning-signmessage.7 @@ -17,10 +17,17 @@ only be created by something with access to this node's secret key\. .SH RETURN VALUE -An object with attributes \fIsignature\fR, \fIrecid\fR and \fIzbase\fR is -returned\. \fIzbase\fR is the result of \fIsignature\fR and \fIrecid\fR encoded in -a style compatible with \fBlnd\fR's \fBSignMessageRequest\fR (\fIhttps://api.lightning.community/#grpc-request-signmessagerequest\fR)\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBsignature\fR (hex): The signature (always 128 characters) +.IP \[bu] +\fBrecid\fR (hex): The recovery id (0, 1, 2 or 3) (always 2 characters) +.IP \[bu] +\fBzbase\fR (string): \fIsignature\fR and \fIrecid\fR encoded in a style compatible with \fBlnd\fR's \fBSignMessageRequest\fR (\fIhttps://api.lightning.community/#grpc-request-signmessagerequest\fR) + +.RE .SH AUTHOR Rusty Russell \fI is mainly responsible\. @@ -33,4 +40,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:e3565afa7011460ae5add0bd230b95699dadd1625ccb38bae02bc71136f468be +\" SHA256STAMP:9b93ee7140ffee478035e0b2a13a71dc3797bb65e04aaed4f2caa95043f39614 diff --git a/doc/lightning-signmessage.7.md b/doc/lightning-signmessage.7.md index 3ba01d9ab..c453d38d9 100644 --- a/doc/lightning-signmessage.7.md +++ b/doc/lightning-signmessage.7.md @@ -18,9 +18,12 @@ only be created by something with access to this node's secret key. RETURN VALUE ------------ -An object with attributes *signature*, *recid* and *zbase* is -returned. *zbase* is the result of *signature* and *recid* encoded in -a style compatible with **lnd**'s [SignMessageRequest](https://api.lightning.community/#grpc-request-signmessagerequest). +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **signature** (hex): The signature (always 128 characters) +- **recid** (hex): The recovery id (0, 1, 2 or 3) (always 2 characters) +- **zbase** (string): *signature* and *recid* encoded in a style compatible with **lnd**'s [SignMessageRequest](https://api.lightning.community/#grpc-request-signmessagerequest) +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -37,3 +40,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:b52d27220550c5b9742fc6f9fb876a458007c9832e83572309e7b19900852133) diff --git a/doc/lightning-signpsbt.7 b/doc/lightning-signpsbt.7 index 0f5641c9f..2ef29c351 100644 --- a/doc/lightning-signpsbt.7 +++ b/doc/lightning-signpsbt.7 @@ -41,11 +41,11 @@ if the inputs to be signed were not previously reserved\. .fi .SH RETURN VALUE -On success, a object will be returned with a string\. +On success, an object is returned, containing: .RS .IP \[bu] -\fIpsbt\fR: A string that represents the psbt value with all inputs signed transaction\. +\fBsigned_psbt\fR (string): The fully signed PSBT .RE @@ -77,4 +77,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:5d7f12bed20a73dabf41d219ccd960e4e36a4674e8528d95ef26f7c8c55b1a0f +\" SHA256STAMP:e6c554936e7bf7c4937db4a1e98e47486540948505bc0b8021a33b2c805cbaf6 diff --git a/doc/lightning-signpsbt.7.md b/doc/lightning-signpsbt.7.md index 7c3ae9490..9dcd86629 100644 --- a/doc/lightning-signpsbt.7.md +++ b/doc/lightning-signpsbt.7.md @@ -38,9 +38,10 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, a object will be returned with a string. - -- *psbt*: A string that represents the psbt value with all inputs signed transaction. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **signed_psbt** (string): The fully signed PSBT +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -69,3 +70,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:0273c699d75773d0806e6718e7073f5fc84302028bad6877fd7d318fa6c35720) diff --git a/doc/lightning-stop.7 b/doc/lightning-stop.7 index c5a1f9053..0c2060ff7 100644 --- a/doc/lightning-stop.7 +++ b/doc/lightning-stop.7 @@ -22,8 +22,11 @@ The \fBstop\fR is a RPC command to shut off the c-lightning node\. .fi .SH RETURN VALUE -On success, the command will return a empty object\. Once it has returned, -the daemon has cleaned up completely, and if desired may be restarted\. +On success, returns a single element (string) (always "Shutdown complete") + + +Once it has returned, the daemon has cleaned up completely, and if +desired may be restarted immediately\. .SH AUTHOR @@ -33,4 +36,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:b080fabf70873cb5383ea28d79fba5be5abe1a60ebd9bf280419d2e590dfb762 +\" SHA256STAMP:49b081bfb49823c2db676705681eec32721a9fd62629f97b1749bf20a264fead diff --git a/doc/lightning-stop.7.md b/doc/lightning-stop.7.md index 36b64adf9..16996fcac 100644 --- a/doc/lightning-stop.7.md +++ b/doc/lightning-stop.7.md @@ -24,8 +24,12 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, the command will return a empty object. Once it has returned, -the daemon has cleaned up completely, and if desired may be restarted. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, returns a single element (string) (always "Shutdown complete") +[comment]: # (GENERATE-FROM-SCHEMA-END) + +Once it has returned, the daemon has cleaned up completely, and if +desired may be restarted immediately. AUTHOR @@ -38,3 +42,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:e0a51d1bacb47191037431841eb36b348554cb40f8a291528f67f5beb718f6cf) diff --git a/doc/lightning-txdiscard.7 b/doc/lightning-txdiscard.7 index fba7c43a8..383048878 100644 --- a/doc/lightning-txdiscard.7 +++ b/doc/lightning-txdiscard.7 @@ -12,14 +12,19 @@ use of the \fItxid\fR from \fBlightning-txprepare\fR(7)\. .SH RETURN VALUE -On success, an object with attributes \fIunsigned_tx\fR and \fItxid\fR will be -returned, exactly as from \fBlightning-txprepare\fR(7)\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBunsigned_tx\fR (hex): the unsigned transaction +.IP \[bu] +\fBtxid\fR (txid): the transaction id of \fIunsigned_tx\fR + +.RE If there is no matching \fItxid\fR, an error is reported\. Note that this may -happen due to incorrect usage (such as \fBtxdiscard\fR or \fBtxsend\fR -already being called for \fItxid\fR) or due to lightningd restarting, which -implicitly calls \fBtxdiscard\fR on all outputs\. +happen due to incorrect usage, such as \fBtxdiscard\fR or \fBtxsend\fR +already being called for \fItxid\fR\. The following error codes may occur: @@ -41,4 +46,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:cd4c671bd56e7afbe224cceb4e454da314e4ac08bb15618780e06da6c12310ed +\" SHA256STAMP:af562e4efa41431ac7692900acd231e8baf91c1fab4884788ee9746242aac8d6 diff --git a/doc/lightning-txdiscard.7.md b/doc/lightning-txdiscard.7.md index 8c58a25c8..aced46201 100644 --- a/doc/lightning-txdiscard.7.md +++ b/doc/lightning-txdiscard.7.md @@ -15,13 +15,15 @@ use of the *txid* from lightning-txprepare(7). RETURN VALUE ------------ -On success, an object with attributes *unsigned\_tx* and *txid* will be -returned, exactly as from lightning-txprepare(7). +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **unsigned_tx** (hex): the unsigned transaction +- **txid** (txid): the transaction id of *unsigned_tx* +[comment]: # (GENERATE-FROM-SCHEMA-END) If there is no matching *txid*, an error is reported. Note that this may -happen due to incorrect usage (such as **txdiscard** or **txsend** -already being called for *txid*) or due to lightningd restarting, which -implicitly calls **txdiscard** on all outputs. +happen due to incorrect usage, such as **txdiscard** or **txsend** +already being called for *txid*. The following error codes may occur: - -1: An unknown *txid*. @@ -41,3 +43,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:116f3262cc632e3a437d6629cd641020549f60b1264ad093e6591d5e5f83a6f0) diff --git a/doc/lightning-txprepare.7 b/doc/lightning-txprepare.7 index 75509576f..1adc79dc9 100644 --- a/doc/lightning-txprepare.7 +++ b/doc/lightning-txprepare.7 @@ -57,15 +57,17 @@ is provided by \fBtxsend\fR\. .SH RETURN VALUE -On success, an object with attributes \fIunsigned_tx\fR, \fIpsbt\fR and \fItxid\fR will be -returned\. You need to hand \fItxid\fR to \fBtxsend\fR or \fBtxdiscard\fR, as the -inputs of this transaction are reserved until then, or until the daemon -restarts\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBpsbt\fR (string): the PSBT representing the unsigned transaction +.IP \[bu] +\fBunsigned_tx\fR (hex): the unsigned transaction +.IP \[bu] +\fBtxid\fR (txid): the transaction id of \fIunsigned_tx\fR; you hand this to \fBlightning-txsend\fR(7) or \fBlightning-txdiscard\fR(7), as the inputs of this transaction are reserved\. -\fIunsigned_tx\fR and \fIpsbt\fR represent the raw bitcoin transaction (not yet signed) -and \fItxid\fR represent the bitcoin transaction id\. - +.RE On failure, an error is reported and the transaction is not created\. @@ -95,4 +97,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:ebbe475ef5a3df39e772789cf3df94757662408758f0f6bb300b120d2abefebc +\" SHA256STAMP:7a2b2f0bbadde70507b72a88355c4c41817a37e9f8e3211db3e9cb5b678c1b20 diff --git a/doc/lightning-txprepare.7.md b/doc/lightning-txprepare.7.md index 26952dd5d..b2c6d56a9 100644 --- a/doc/lightning-txprepare.7.md +++ b/doc/lightning-txprepare.7.md @@ -52,13 +52,12 @@ is provided by **txsend**. RETURN VALUE ------------ -On success, an object with attributes *unsigned\_tx*, *psbt* and *txid* will be -returned. You need to hand *txid* to **txsend** or **txdiscard**, as the -inputs of this transaction are reserved until then, or until the daemon -restarts. - -*unsigned\_tx* and *psbt* represent the raw bitcoin transaction (not yet signed) -and *txid* represent the bitcoin transaction id. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **psbt** (string): the PSBT representing the unsigned transaction +- **unsigned_tx** (hex): the unsigned transaction +- **txid** (txid): the transaction id of *unsigned_tx*; you hand this to lightning-txsend(7) or lightning-txdiscard(7), as the inputs of this transaction are reserved. +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is reported and the transaction is not created. @@ -84,3 +83,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:d9c02d64810b85a3efcaa01c1403948ea4361d8281d46a2c31cc077f7300cd80) diff --git a/doc/lightning-txsend.7 b/doc/lightning-txsend.7 index 44fbd05fe..9fb00b2e6 100644 --- a/doc/lightning-txsend.7 +++ b/doc/lightning-txsend.7 @@ -12,12 +12,17 @@ The \fBtxsend\fR RPC command signs and broadcasts a transaction created by .SH RETURN VALUE -On success, an object with attributes \fItx\fR and \fItxid\fR will be returned\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBpsbt\fR (string): the completed PSBT representing the signed transaction +.IP \[bu] +\fBtx\fR (hex): the fully signed transaction +.IP \[bu] +\fBtxid\fR (txid): the transaction id of \fItx\fR -\fItx\fR represents the fully signed raw bitcoin transaction, and \fItxid\fR is -the same as the \fItxid\fR argument\. - +.RE On failure, an error is reported (from bitcoind), and the inputs from the transaction are unreserved\. @@ -42,4 +47,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:21ece8a91426ad0d60c15f2dd3fcdd7dda33bf66bcbc2d20b09e20fd350566b6 +\" SHA256STAMP:b3d6d0a71241ee5564eb02ecf3bea1b5528dd5868e6607a8acccd1828a80435a diff --git a/doc/lightning-txsend.7.md b/doc/lightning-txsend.7.md index 86156b8d7..90e7759e5 100644 --- a/doc/lightning-txsend.7.md +++ b/doc/lightning-txsend.7.md @@ -15,10 +15,12 @@ The **txsend** RPC command signs and broadcasts a transaction created by RETURN VALUE ------------ -On success, an object with attributes *tx* and *txid* will be returned. - -*tx* represents the fully signed raw bitcoin transaction, and *txid* is -the same as the *txid* argument. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **psbt** (string): the completed PSBT representing the signed transaction +- **tx** (hex): the fully signed transaction +- **txid** (txid): the transaction id of *tx* +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is reported (from bitcoind), and the inputs from the transaction are unreserved. @@ -41,3 +43,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:2fae4915336d7663498f7a221e9894a430a1521fa683deef58f59d71f7b1745d) diff --git a/doc/lightning-unreserveinputs.7 b/doc/lightning-unreserveinputs.7 index d1cf3373c..89f9f0e9f 100644 --- a/doc/lightning-unreserveinputs.7 +++ b/doc/lightning-unreserveinputs.7 @@ -20,20 +20,25 @@ reservation by; default is 72\. .SH RETURN VALUE -On success, an \fIreservations\fR array is returned, with an entry for each input -which was reserved: +On success, an object containing \fBreservations\fR is returned\. It is an array of objects, where each object contains: .RS .IP \[bu] -\fItxid\fR is the input transaction id\. +\fBtxid\fR (txid): the transaction id .IP \[bu] -\fIvout\fR is the input index\. +\fBvout\fR (u32): the output number which was reserved .IP \[bu] -\fIwas_reserved\fR indicates whether the input was already reserved (generally true) +\fBwas_reserved\fR (boolean): whether the input was already reserved (usually \fBtrue\fR) .IP \[bu] -\fIreserved\fR indicates that the input is now reserved (may still be true, if it was previously reserved for a long time)\. +\fBreserved\fR (boolean): whether the input is now reserved (may still be \fBtrue\fR if it was reserved for a long time) + +.RE + +If \fBreserved\fR is \fItrue\fR: + +.RS .IP \[bu] -\fIreserved_to_block\fR (if \fIreserved\fR is still true) indicates what blockheight the reservation will expire\. +\fBreserved_to_block\fR (u32): what blockheight the reservation will expire .RE @@ -59,4 +64,4 @@ niftynei \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d4aa9d3345ce7fa3c91b760633c3dc296d4dd7a7da7cdadc4da31c3b474e680c +\" SHA256STAMP:fb2f73820b1e9b632449b241c7587b5019d5891e0348835a84d435a98fd673e8 diff --git a/doc/lightning-unreserveinputs.7.md b/doc/lightning-unreserveinputs.7.md index d3c8a2816..c4849abcd 100644 --- a/doc/lightning-unreserveinputs.7.md +++ b/doc/lightning-unreserveinputs.7.md @@ -21,14 +21,16 @@ reservation by; default is 72. RETURN VALUE ------------ -On success, an *reservations* array is returned, with an entry for each input -which was reserved: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **reservations** is returned. It is an array of objects, where each object contains: +- **txid** (txid): the transaction id +- **vout** (u32): the output number which was reserved +- **was_reserved** (boolean): whether the input was already reserved (usually `true`) +- **reserved** (boolean): whether the input is now reserved (may still be `true` if it was reserved for a long time) -- *txid* is the input transaction id. -- *vout* is the input index. -- *was_reserved* indicates whether the input was already reserved (generally true) -- *reserved* indicates that the input is now reserved (may still be true, if it was previously reserved for a long time). -- *reserved_to_block* (if *reserved* is still true) indicates what blockheight the reservation will expire. +If **reserved** is *true*: + - **reserved_to_block** (u32): what blockheight the reservation will expire +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is reported and no UTXOs are unreserved. @@ -50,3 +52,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:5032211220b9e82b391eeed37d35e69585e7dbee4a321800d63cc5683be1022c) diff --git a/doc/lightning-utxopsbt.7 b/doc/lightning-utxopsbt.7 index 9193e2abb..4f35a409d 100644 --- a/doc/lightning-utxopsbt.7 +++ b/doc/lightning-utxopsbt.7 @@ -48,6 +48,38 @@ for the excess sats\. .SH RETURN VALUE +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBpsbt\fR (string): Unsigned PSBT which fulfills the parameters given +.IP \[bu] +\fBfeerate_per_kw\fR (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight +.IP \[bu] +\fBestimated_final_weight\fR (u32): The estimated weight of the transaction once fully signed +.IP \[bu] +\fBexcess_msat\fR (msat): The amount above \fIsatoshi\fR which is available\. This could be zero, or dust; it will be zero if \fIchange_outnum\fR is also returned +.IP \[bu] +\fBchange_outnum\fR (u32, optional): The 0-based output number where change was placed (only if parameter \fIexcess_as_change\fR was true and there was sufficient funds) +.IP \[bu] +\fBreservations\fR (array of objects, optional): If \fIreserve\fR was true or a non-zero number, just as per \fBlightning-reserveinputs\fR(7): +.RS +.IP \[bu] +\fBtxid\fR (txid): The txid of the transaction +.IP \[bu] +\fBvout\fR (u32): The 0-based output number +.IP \[bu] +\fBwas_reserved\fR (boolean): Whether this output was previously reserved +.IP \[bu] +\fBreserved\fR (boolean): Whether this output is now reserved (always \fItrue\fR) +.IP \[bu] +\fBreserved_to_block\fR (u32): The blockheight the reservation will expire + +.RE + + +.RE + On success, returns the \fIpsbt\fR it created, containing the inputs, \fIfeerate_per_kw\fR showing the exact numeric feerate it used, \fIestimated_final_weight\fR for the estimated weight of the transaction @@ -92,4 +124,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:fb64856561ee499c033582b483e676354a98fb500136a8d52c857981f33339ea +\" SHA256STAMP:e31bfc3bcc58b62123ec670b9e892675dc8e742b195d7897e148f6142411fe7b diff --git a/doc/lightning-utxopsbt.7.md b/doc/lightning-utxopsbt.7.md index 6fe9c7dd6..f62f4f876 100644 --- a/doc/lightning-utxopsbt.7.md +++ b/doc/lightning-utxopsbt.7.md @@ -44,6 +44,22 @@ for the excess sats. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **psbt** (string): Unsigned PSBT which fulfills the parameters given +- **feerate_per_kw** (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight +- **estimated_final_weight** (u32): The estimated weight of the transaction once fully signed +- **excess_msat** (msat): The amount above *satoshi* which is available. This could be zero, or dust; it will be zero if *change_outnum* is also returned +- **change_outnum** (u32, optional): The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds) +- **reservations** (array of objects, optional): If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7): + - **txid** (txid): The txid of the transaction + - **vout** (u32): The 0-based output number + - **was_reserved** (boolean): Whether this output was previously reserved + - **reserved** (boolean): Whether this output is now reserved (always *true*) + - **reserved_to_block** (u32): The blockheight the reservation will expire +[comment]: # (GENERATE-FROM-SCHEMA-END) + + On success, returns the *psbt* it created, containing the inputs, *feerate_per_kw* showing the exact numeric feerate it used, *estimated_final_weight* for the estimated weight of the transaction @@ -83,3 +99,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:50870aade11499391f94c5384959260ec2525d879c2115226302c368ed6ffeb7) diff --git a/doc/lightning-waitanyinvoice.7 b/doc/lightning-waitanyinvoice.7 index 2c75ddd5e..d4525aea9 100644 --- a/doc/lightning-waitanyinvoice.7 +++ b/doc/lightning-waitanyinvoice.7 @@ -33,9 +33,41 @@ If unspecified, this command will wait indefinitely\. .SH RETURN VALUE -On success, an invoice description will be returned as per -\fBlightning-listinvoice\fR(7): \fIcomplete\fR will always be \fItrue\fR\. +On success, an object is returned, containing: +.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 or expired (one of "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 Possible errors are: @@ -58,4 +90,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:a49771fb6295f38674ecec146881cdc5c8490ad9629310942162519fa166776f +\" SHA256STAMP:c3c48767cf0c14d2cd1b4a9ff0844319798c344b3fdb881ff24897440995284c diff --git a/doc/lightning-waitanyinvoice.7.md b/doc/lightning-waitanyinvoice.7.md index 454de79da..0d3ed170e 100644 --- a/doc/lightning-waitanyinvoice.7.md +++ b/doc/lightning-waitanyinvoice.7.md @@ -33,8 +33,23 @@ If unspecified, this command will wait indefinitely. RETURN VALUE ------------ -On success, an invoice description will be returned as per -lightning-listinvoice(7): *complete* will always be *true*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +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) +- **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 +- **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is) +- **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is) + +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) Possible errors are: @@ -57,3 +72,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:78bf07150eb67148d87187f36937536a44ed7aa489d5f9c410cd9ce7a7d6db89) diff --git a/doc/lightning-waitblockheight.7 b/doc/lightning-waitblockheight.7 index 87b169099..ad3d8678c 100644 --- a/doc/lightning-waitblockheight.7 +++ b/doc/lightning-waitblockheight.7 @@ -17,10 +17,13 @@ command returns immediately\. .SH RETURN VALUE -Once the specified block height has been achieved by the blockchain, -an object with the single field \fIblockheight\fR is returned, which is -the block height at the time the command returns\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBblockheight\fR (u32): The current block height (>= \fIblockheight\fR parameter) + +.RE If \fItimeout\fR seconds is reached without the specified blockheight being reached, this command will fail with a code of \fB2000\fR\. @@ -33,4 +36,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:ac3320b4b9e679d8c407e42c9663540e2fc2aca75143d192f58ce255ca9b3700 +\" SHA256STAMP:38dc35b2a28f0ee342af0fdaba6b4f1f27fb1df973426804d30da0572eb3913d diff --git a/doc/lightning-waitblockheight.7.md b/doc/lightning-waitblockheight.7.md index 8ca4c4aad..d310c9b50 100644 --- a/doc/lightning-waitblockheight.7.md +++ b/doc/lightning-waitblockheight.7.md @@ -19,9 +19,10 @@ command returns immediately. RETURN VALUE ------------ -Once the specified block height has been achieved by the blockchain, -an object with the single field *blockheight* is returned, which is -the block height at the time the command returns. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **blockheight** (u32): The current block height (>= *blockheight* parameter) +[comment]: # (GENERATE-FROM-SCHEMA-END) If *timeout* seconds is reached without the specified blockheight being reached, this command will fail with a code of `2000`. @@ -36,3 +37,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:bd9cd69ae5a66b75b6172d2cd8c7bdb1c896fcd7ed1edf41fc3707c2f1a466dd) diff --git a/doc/lightning-waitinvoice.7 b/doc/lightning-waitinvoice.7 index 9dcd9fe64..a9b2907c1 100644 --- a/doc/lightning-waitinvoice.7 +++ b/doc/lightning-waitinvoice.7 @@ -12,9 +12,41 @@ then returns that single entry as per \fBlistinvoice\fR\. .SH RETURN VALUE -On success, an invoice description will be returned as per -\fBlightning-listinvoice\fR(7)\. The \fIstatus\fR field will be \fIpaid\fR or \fIexpired\fR\. +On success, an object is returned, containing: +.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 or expired (one of "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 On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -42,4 +74,4 @@ responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:afa7ad33136d9bd9a92b9e0c52387c3124f009ca11b045dbac4e840aaa610857 +\" SHA256STAMP:db69e2582b766856b174bf6bee2b9e9dbb398cdd31ba6d0f3e826648d24cee62 diff --git a/doc/lightning-waitinvoice.7.md b/doc/lightning-waitinvoice.7.md index ba5f16066..a9103c2e5 100644 --- a/doc/lightning-waitinvoice.7.md +++ b/doc/lightning-waitinvoice.7.md @@ -15,8 +15,23 @@ then returns that single entry as per **listinvoice**. RETURN VALUE ------------ -On success, an invoice description will be returned as per -lightning-listinvoice(7). The *status* field will be *paid* or *expired*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +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) +- **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 +- **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is) +- **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is) + +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) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -42,3 +57,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:78bf07150eb67148d87187f36937536a44ed7aa489d5f9c410cd9ce7a7d6db89) diff --git a/doc/lightning-waitsendpay.7 b/doc/lightning-waitsendpay.7 index 5d94f14fb..e3c553e06 100644 --- a/doc/lightning-waitsendpay.7 +++ b/doc/lightning-waitsendpay.7 @@ -33,10 +33,41 @@ returns an error\. .SH RETURN VALUE -On success, an object similar to the output of \fBlistsendpays\fR will be -returned\. This object will have a \fIstatus\fR field that is the string -\fI"complete"\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBid\fR (u64): unique ID for this payment attempt +.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): status of the payment (always "complete") +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBamount_sent_msat\fR (msat): The amount sent +.IP \[bu] +\fBamount_msat\fR (msat, optional): The amount delivered to destination (if known) +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment if known +.IP \[bu] +\fBlabel\fR (string, optional): the label, if given to sendpay +.IP \[bu] +\fBpartid\fR (u64, optional): the \fIpartid\fR, if given to sendpay +.IP \[bu] +\fBbolt11\fR (string, optional): the bolt11 string (if pay supplied one) +.IP \[bu] +\fBbolt12\fR (string, optional): the bolt12 string (if supplied for pay: \fBexperimental-offers\fR only)\. + +.RE + +If \fBstatus\fR is "complete": + +.RS +.IP \[bu] +\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters) + +.RE On error, and even if the error occurred from a node other than the final destination, the route table will no longer be updated\. Use the @@ -105,4 +136,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:cb20e509b421b38d12b24dbc5f8b0013977c0d9b3a140d0558864be75d9ba6bf +\" SHA256STAMP:50109bd21f9b8cdd35b0cb5ed2d20064190c6ae841179dc08817610a305c0f10 diff --git a/doc/lightning-waitsendpay.7.md b/doc/lightning-waitsendpay.7.md index ee88a70eb..37347999f 100644 --- a/doc/lightning-waitsendpay.7.md +++ b/doc/lightning-waitsendpay.7.md @@ -32,9 +32,23 @@ returns an error. RETURN VALUE ------------ -On success, an object similar to the output of **listsendpays** will be -returned. This object will have a *status* field that is the string -*"complete"*. +[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) +- **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 +- **amount_msat** (msat, optional): The amount delivered to destination (if known) +- **destination** (pubkey, optional): the final destination of the payment if known +- **label** (string, optional): the label, if given to sendpay +- **partid** (u64, optional): the *partid*, 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). + +If **status** is "complete": + - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters) +[comment]: # (GENERATE-FROM-SCHEMA-END) On error, and even if the error occurred from a node other than the final destination, the route table will no longer be updated. Use the @@ -85,3 +99,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:3efc46e3dc2254ddfb4a82d4b3bb1936ff0a400a3cf19ce4c40a717412f83ee7) diff --git a/doc/lightning-withdraw.7 b/doc/lightning-withdraw.7 index 30c2d5f43..4210c2d24 100644 --- a/doc/lightning-withdraw.7 +++ b/doc/lightning-withdraw.7 @@ -43,12 +43,17 @@ of "txid:vout"\. These must be drawn from the node's available UTXO set\. .SH RETURN VALUE -On success, an object with attributes \fItx\fR, \fItxid\fR and \fIpsbt\fR will be returned\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBtx\fR (hex): the fully signed bitcoin transaction +.IP \[bu] +\fBtxid\fR (txid): the transaction id of \fItx\fR +.IP \[bu] +\fBpsbt\fR (string): the PSBT representing the unsigned transaction -\fItx\fR and \fIpsbt\fR represent the fully signed bitcoin transaction and \fItxid\fR -represents the bitcoin transaction id\. - +.RE On failure, an error is reported and the withdrawal transaction is not created\. @@ -79,4 +84,4 @@ Felix \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:0afffd7ffd7b22415e67816cc43d3be6fdde8deda863a0981f383cdc7ba48513 +\" SHA256STAMP:73c614c0d138af8d355472158960de42ac3f6a5f0bed1dc1e0868ef28a90c8fd diff --git a/doc/lightning-withdraw.7.md b/doc/lightning-withdraw.7.md index c588581e9..6183169ff 100644 --- a/doc/lightning-withdraw.7.md +++ b/doc/lightning-withdraw.7.md @@ -40,10 +40,12 @@ of "txid:vout". These must be drawn from the node's available UTXO set. RETURN VALUE ------------ -On success, an object with attributes *tx*, *txid* and *psbt* will be returned. - -*tx* and *psbt* represent the fully signed bitcoin transaction and *txid* -represents the bitcoin transaction id. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **tx** (hex): the fully signed bitcoin transaction +- **txid** (txid): the transaction id of *tx* +- **psbt** (string): the PSBT representing the unsigned transaction +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is reported and the withdrawal transaction is not created. @@ -70,3 +72,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:e233afb9fefd986fbcba8709f6cce8a221db8772f48c00a481a68fb0326c641d) diff --git a/doc/schemas/checkmessage.schema.json b/doc/schemas/checkmessage.schema.json new file mode 100644 index 000000000..7bc2833bd --- /dev/null +++ b/doc/schemas/checkmessage.schema.json @@ -0,0 +1,56 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "verified" ], + "additionalProperties": true, + "properties": { + "verified": { + "type": "boolean", + "description": "Whether the signature was valid" + } + }, + "allOf": [ + { + "if": { + "properties": { + "verified": { + "type": "boolean", + "enum": [ true ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "pubkey" ], + "properties": { + "verified": { }, + "pubkey": { + "type": "pubkey", + "description": "the *pubkey* parameter, or the pubkey found by looking for known nodes" + } + } + } + }, + { + "if": { + "properties": { + "verified": { + "type": "boolean", + "enum": [ false ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "pubkey" ], + "properties": { + "verified": { }, + "pubkey": { + "type": "pubkey", + "description": "the *pubkey* (if any) which could have signed this; this is usually not useful!" + } + } + } + } + ] +} diff --git a/doc/schemas/dev-sendcustommsg.schema.json b/doc/schemas/dev-sendcustommsg.schema.json new file mode 100644 index 000000000..21ce1eb8b --- /dev/null +++ b/doc/schemas/dev-sendcustommsg.schema.json @@ -0,0 +1,11 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "status" ], + "properties": { + "status": { + "type": "string", + "description": "Information about where message was queued" + } + } +} diff --git a/doc/schemas/fundpsbt.schema.json b/doc/schemas/fundpsbt.schema.json index c93513622..8aac22c6d 100644 --- a/doc/schemas/fundpsbt.schema.json +++ b/doc/schemas/fundpsbt.schema.json @@ -26,7 +26,7 @@ }, "reservations": { "type": "array", - "description": "If the *reserve* was true, just as per lightning-reserveinputs(7)", + "description": "If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7)", "items": { "type": "object", "required": ["txid", "vout", "was_reserved", "reserved", "reserved_to_block" ], diff --git a/doc/schemas/keysend.schema.json b/doc/schemas/keysend.schema.json new file mode 100644 index 000000000..b3bd48ccc --- /dev/null +++ b/doc/schemas/keysend.schema.json @@ -0,0 +1,55 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "payment_preimage", "payment_hash", "created_at", "parts", "amount_msat", "amount_sent_msat", "status" ], + "properties": { + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage* which will prove payment", + "maxLength": 64, + "minLength": 64 + }, + "created_at": { + "type": "number", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "parts": { + "type": "u32", + "description": "how many attempts this took" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "Amount the recipient received" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "Total amount we sent (including fees)" + }, + "warning_partial_completion": { + "type": "string", + "description": "Not all parts of a multi-part payment have completed" + }, + "status": { + "type": "string", + "enum": [ "complete" ], + "description": "status of payment" + } + } +} diff --git a/doc/schemas/listsendpays.schema.json b/doc/schemas/listsendpays.schema.json new file mode 100644 index 000000000..a66ec344b --- /dev/null +++ b/doc/schemas/listsendpays.schema.json @@ -0,0 +1,163 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "payments" ], + "properties": { + "payments": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "id", "payment_hash", "status", "created_at", "amount_sent_msat" ], + "properties": { + "id": { + "type": "u64", + "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 + }, + "status": { + "type": "string", + "enum": [ "pending", "failed", "complete" ], + "description": "status of the payment" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "The amount delivered to destination (if known)" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment if known" + }, + "created_at": { + "type": "u64", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "The amount sent" + }, + "label": { + "type": "string", + "description": "the label, if given to sendpay" + }, + "bolt11": { + "type": "string", + "description": "the bolt11 string (if pay supplied one)" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string (if supplied for pay: **experimental-offers** only)." + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "payment_preimage" ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "failed" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "erroronion": { + "type": "hex", + "description": "the onion message returned" + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "pending" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "bolt11": { }, + "bolt12": { } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/listtransactions.schema.json b/doc/schemas/listtransactions.schema.json new file mode 100644 index 000000000..7539a8921 --- /dev/null +++ b/doc/schemas/listtransactions.schema.json @@ -0,0 +1,121 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "transactions" ], + "properties": { + "transactions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "hash", "rawtx", "blockheight", "txindex", "locktime", "version", "inputs", "outputs" ], + "properties": { + "hash": { + "type": "txid", + "description": "the transaction id" + }, + "rawtx": { + "type": "hex", + "description": "the raw transaction" + }, + "blockheight": { + "type": "u32", + "description": "the block height of this tx" + }, + "txindex": { + "type": "u32", + "description": "the transaction number within the block" + }, + "type": { + "type": "array", + "items": { + "type": "string", + "enum": [ "theirs", "deposit", "withdraw", "channel_funding","channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat" ], + "description": "Reason we care about this transaction (*EXPERIMENTAL_FEATURES* only)" + } + }, + "channel": { + "type": "short_channel_id", + "description": "the channel this transaction is associated with (*EXPERIMENTAL_FEATURES* only)" + }, + "locktime": { + "type": "u32", + "description": "The nLocktime for this tx" + }, + "version": { + "type": "u32", + "description": "The nVersion for this tx" + }, + "inputs": { + "type": "array", + "description": "Each input, in order", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "txid", "index", "sequence" ], + "properties": { + "txid": { + "type": "txid", + "description": "the transaction id spent" + }, + "index": { + "type": "u32", + "description": "the output spent" + }, + "sequence": { + "type": "u32", + "description": "the nSequence value" + }, + "type": { + "type": "string", + "enum": [ "theirs", "deposit", "withdraw", "channel_funding","channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat" ], + "description": "the purpose of this input (*EXPERIMENTAL_FEATURES* only)" + }, + "channel": { + "type": "short_channel_id", + "description": "the channel this input is associated with (*EXPERIMENTAL_FEATURES* only)" + } + } + } + }, + "outputs": { + "type": "array", + "description": "Each output, in order", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "index", "msat" , "scriptPubKey" ], + "properties": { + "index": { + "type": "u32", + "description": "the 0-based output number" + }, + "satoshis": { + "deprecated": true + }, + "msat": { + "type": "msat", + "description": "the amount of the output" + }, + "scriptPubKey": { + "type": "hex", + "description": "the scriptPubKey" + }, + "type": { + "type": "string", + "enum": [ "theirs", "deposit", "withdraw", "channel_funding","channel_mutual_close", "channel_unilateral_close", "channel_sweep", "channel_htlc_success", "channel_htlc_timeout", "channel_penalty", "channel_unilateral_cheat" ], + "description": "the purpose of this output (*EXPERIMENTAL_FEATURES* only)" + }, + "channel": { + "type": "short_channel_id", + "description": "the channel this output is associated with (*EXPERIMENTAL_FEATURES* only)" + } + } + } + } + } + } + } + } +} diff --git a/doc/schemas/multifundchannel.schema.json b/doc/schemas/multifundchannel.schema.json new file mode 100644 index 000000000..5022d32a9 --- /dev/null +++ b/doc/schemas/multifundchannel.schema.json @@ -0,0 +1,83 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "tx", "txid", "channel_ids" ], + "properties": { + "tx": { + "type": "hex", + "description": "The raw transaction which funded the channel" + }, + "txid": { + "type": "txid", + "description": "The txid of the transaction which funded the channel" + }, + "channel_ids": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "id", "channel_id", "outnum" ], + "properties": { + "id": { + "type": "pubkey", + "description": "The peer we opened the channel with" + }, + "outnum": { + "type": "u32", + "description": "The 0-based output index showing which output funded the channel" + }, + "channel_id": { + "type": "hex", + "description": "The channel_id of the resulting channel", + "minLength": 64, + "maxLength": 64 + }, + "close_to": { + "type": "hex", + "description": "The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script`" + } + } + } + }, + "failed": { + "type": "array", + "description": "any peers we failed to open with (if *minchannels* was specified less than the number of destinations)", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "id", "method", "error" ], + "properties": { + "id": { + "type": "pubkey", + "description": "The peer we failed to open the channel with" + }, + "method": { + "type": "string", + "enum": [ "connect", "openchannel_init", "fundchannel_start", "fundchannel_complete" ], + "description": "What stage we failed at" + }, + "error": { + "type": "object", + "additionalProperties": false, + "required": [ "code", "message" ], + "properties": { + "code": { + "type": "integer", + "description": "JSON error code from failing stage" + }, + "message": { + "type": "string", + "description": "Message from stage" + }, + "data": { + "untyped": true, + "description": "Additional error data" + } + } + } + } + } + } + } +} diff --git a/doc/schemas/multiwithdraw.schema.json b/doc/schemas/multiwithdraw.schema.json new file mode 100644 index 000000000..d8095507d --- /dev/null +++ b/doc/schemas/multiwithdraw.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "tx", "txid" ], + "properties": { + "tx": { + "type": "hex", + "description": "The raw transaction which was sent" + }, + "txid": { + "type": "txid", + "description": "The txid of the **tx**" + } + } +} diff --git a/doc/schemas/newaddr.schema.json b/doc/schemas/newaddr.schema.json new file mode 100644 index 000000000..4da493aac --- /dev/null +++ b/doc/schemas/newaddr.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ ], + "properties": { + "bech32": { + "type": "string", + "description": "The bech32 (native segwit) address" + }, + "p2sh-segwit": { + "type": "string", + "description": "The p2sh-wrapped address" + } + } +} diff --git a/doc/schemas/notifications.schema.json b/doc/schemas/notifications.schema.json new file mode 100644 index 000000000..b797a82c2 --- /dev/null +++ b/doc/schemas/notifications.schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "properties": { + } +} diff --git a/doc/schemas/offer.schema.json b/doc/schemas/offer.schema.json new file mode 100644 index 000000000..2c0e70001 --- /dev/null +++ b/doc/schemas/offer.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "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", + "enum": [ true ], + "description": "whether this can still be used" + }, + "single_use": { + "type": "boolean", + "description": "whether this expires as soon as it's paid (reflects the *single_use* parameter)" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 encoding of the offer" + }, + "used": { + "type": "boolean", + "enum": [ false ], + "description": "True if an associated invoice has been paid" + }, + "label": { + "type": "string", + "description": "the (optional) user-specified label" + } + } +} diff --git a/doc/schemas/offerout.schema.json b/doc/schemas/offerout.schema.json new file mode 100644 index 000000000..6c0886772 --- /dev/null +++ b/doc/schemas/offerout.schema.json @@ -0,0 +1,37 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "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", + "enum": [ true ], + "description": "whether this will pay a matching incoming invoice" + }, + "single_use": { + "type": "boolean", + "enum": [ true ], + "description": "whether this expires as soon as it's paid out" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 encoding of the offer" + }, + "used": { + "type": "boolean", + "enum": [ false ], + "description": "True if an incoming invoice has been paid" + }, + "label": { + "type": "string", + "description": "the (optional) user-specified label" + } + } +} diff --git a/doc/schemas/openchannel_abort.schema.json b/doc/schemas/openchannel_abort.schema.json new file mode 100644 index 000000000..0d32cf526 --- /dev/null +++ b/doc/schemas/openchannel_abort.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "cannel_canceled", "reason" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "the channel id of the aborted channel", + "maxLength": 64, + "minLength": 64 + }, + "channel_canceled": { + "type": "boolean", + "description": "whether this is completely canceled (there may be remaining in-flight transactions)" + }, + "reason": { + "type": "string", + "description": "usually \"Abort requested\", but if it happened to fail at the same time it could be different" + } + } +} diff --git a/doc/schemas/openchannel_bump.schema.json b/doc/schemas/openchannel_bump.schema.json new file mode 100644 index 000000000..509a47022 --- /dev/null +++ b/doc/schemas/openchannel_bump.schema.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "psbt", "commitments_secured", "funding_serial" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "the channel id of the channel", + "maxLength": 64, + "minLength": 64 + }, + "psbt": { + "type": "string", + "description": "the (incomplete) PSBT of the RBF transaction" + }, + "commitments_secured": { + "type": "boolean", + "enum": [ false ], + "description": "whether the *psbt* is complete" + }, + "funding_serial": { + "type": "u64", + "description": "the serial_id of the funding output in the *psbt*" + } + } +} diff --git a/doc/schemas/openchannel_init.schema.json b/doc/schemas/openchannel_init.schema.json new file mode 100644 index 000000000..e345e6445 --- /dev/null +++ b/doc/schemas/openchannel_init.schema.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "psbt", "commitments_secured", "funding_serial" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "the channel id of the channel", + "maxLength": 64, + "minLength": 64 + }, + "intiialpsbt": { + "type": "string", + "description": "the (incomplete) PSBT of the funding transaction" + }, + "commitments_secured": { + "type": "boolean", + "enum": [ false ], + "description": "whether the *psbt* is complete" + }, + "funding_serial": { + "type": "u64", + "description": "the serial_id of the funding output in the *psbt*" + } + } +} diff --git a/doc/schemas/openchannel_signed.schema.json b/doc/schemas/openchannel_signed.schema.json new file mode 100644 index 000000000..cb144778e --- /dev/null +++ b/doc/schemas/openchannel_signed.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "tx", "txid" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "the channel id of the channel", + "maxLength": 64, + "minLength": 64 + }, + "tx": { + "type": "hex", + "description": "the funding transaction" + }, + "txid": { + "type": "txid", + "description": "The txid of the **tx**" + } + } +} diff --git a/doc/schemas/openchannel_update.schema.json b/doc/schemas/openchannel_update.schema.json new file mode 100644 index 000000000..c820fc023 --- /dev/null +++ b/doc/schemas/openchannel_update.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "psbt", "commitments_secured" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "the channel id of the channel", + "maxLength": 64, + "minLength": 64 + }, + "psbt": { + "type": "string", + "description": "the PSBT of the funding transaction" + }, + "commitments_secured": { + "type": "boolean", + "description": "whether the *psbt* is complete (if true, sign *psbt* and call `openchannel_signed` to complete the channel open)" + } + } +} diff --git a/doc/schemas/pay.schema.json b/doc/schemas/pay.schema.json new file mode 100644 index 000000000..b3bd48ccc --- /dev/null +++ b/doc/schemas/pay.schema.json @@ -0,0 +1,55 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "payment_preimage", "payment_hash", "created_at", "parts", "amount_msat", "amount_sent_msat", "status" ], + "properties": { + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage* which will prove payment", + "maxLength": 64, + "minLength": 64 + }, + "created_at": { + "type": "number", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "parts": { + "type": "u32", + "description": "how many attempts this took" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "Amount the recipient received" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "Total amount we sent (including fees)" + }, + "warning_partial_completion": { + "type": "string", + "description": "Not all parts of a multi-part payment have completed" + }, + "status": { + "type": "string", + "enum": [ "complete" ], + "description": "status of payment" + } + } +} diff --git a/doc/schemas/ping.schema.json b/doc/schemas/ping.schema.json new file mode 100644 index 000000000..5d0d132e7 --- /dev/null +++ b/doc/schemas/ping.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "totlen" ], + "properties": { + "totlen": { + "type": "u16", + "description": "the answer length of the reply message (including header: 0 means no reply expected)" + } + } +} diff --git a/doc/schemas/plugin.schema.json b/doc/schemas/plugin.schema.json new file mode 100644 index 000000000..fab8966e2 --- /dev/null +++ b/doc/schemas/plugin.schema.json @@ -0,0 +1,71 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": true, + "required": [ "command" ], + "properties": { + "command": { + "type": "string", + "enum": [ "start", "stop", "rescan", "startdir", "list" ], + "description": "the subcommand this is responding to" + } + }, + "allOf": [ + { + "if": { + "properties": { + "command": { + "type": "string", + "enum": [ "start", "startdir", "rescan", "list" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "command", "plugins" ], + "properties": { + "command": { }, + "plugins": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "name", "active" ], + "properties": { + "name": { + "type": "string", + "description": "full pathname of the plugin" + }, + "active": { + "type": "boolean", + "description": "status; since plugins are configured asynchronously, a freshly started plugin may not appear immediately." + } + } + } + } + } + } + }, + { + "if": { + "properties": { + "command": { + "type": "string", + "enum": [ "stop" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "command", "result" ], + "properties": { + "command": { }, + "result": { + "type": "string", + "description": "A message saying it successfully stopped" + } + } + } + } + ] +} diff --git a/doc/schemas/reserveinputs.schema.json b/doc/schemas/reserveinputs.schema.json new file mode 100644 index 000000000..8adcc03d3 --- /dev/null +++ b/doc/schemas/reserveinputs.schema.json @@ -0,0 +1,39 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "reservations" ], + "properties": { + "reservations": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "txid", "vout", "was_reserved", "reserved", "reserved_to_block" ], + "properties": { + "txid": { + "type": "txid", + "description": "the transaction id" + }, + "vout": { + "type": "u32", + "description": "the output number which was reserved" + }, + "was_reserved": { + "type": "boolean", + "description": "whether the input was already reserved" + }, + "reserved": { + "type": "boolean", + "enum": [ true ], + "description": "whether the input is now reserved" + }, + "reserved_to_block": { + "type": "u32", + "description": "what blockheight the reservation will expire" + } + } + } + } + } +} diff --git a/doc/schemas/sendinvoice.schema.json b/doc/schemas/sendinvoice.schema.json new file mode 100644 index 000000000..df21950a6 --- /dev/null +++ b/doc/schemas/sendinvoice.schema.json @@ -0,0 +1,89 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "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" + }, + "bolt12": { + "type": "string", + "description": "the BOLT12 string" + } + }, + "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": { }, + "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 + } + } + } + } + ] +} diff --git a/doc/schemas/sendonion.schema.json b/doc/schemas/sendonion.schema.json new file mode 100644 index 000000000..24ab4f373 --- /dev/null +++ b/doc/schemas/sendonion.schema.json @@ -0,0 +1,125 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": true, + "required": [ "id", "payment_hash", "status", "created_at", "amount_sent_msat" ], + "properties": { + "id": { + "type": "u64", + "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 + }, + "status": { + "type": "string", + "enum": [ "pending", "complete" ], + "description": "status of the payment (could be complete if already sent previously)" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "The amount delivered to destination (if known)" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment if known" + }, + "created_at": { + "type": "u64", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "The amount sent" + }, + "label": { + "type": "string", + "description": "the label, if given to sendpay" + }, + "bolt11": { + "type": "string", + "description": "the bolt11 string (if supplied)" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string (if supplied: **experimental-offers** only)." + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "payment_preimage" ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "pending" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "message": { + "type": "string", + "description": "Monitor status with listpays or waitsendpay" + } + } + } + } + ] +} diff --git a/doc/schemas/sendonionmessage.schema.json b/doc/schemas/sendonionmessage.schema.json new file mode 100644 index 000000000..6354c7d82 --- /dev/null +++ b/doc/schemas/sendonionmessage.schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ ], + "properties": { + } +} diff --git a/doc/schemas/sendpay.schema.json b/doc/schemas/sendpay.schema.json new file mode 100644 index 000000000..64802e628 --- /dev/null +++ b/doc/schemas/sendpay.schema.json @@ -0,0 +1,131 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": true, + "required": [ "id", "payment_hash", "status", "created_at", "amount_sent_msat" ], + "properties": { + "id": { + "type": "u64", + "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 + }, + "status": { + "type": "string", + "enum": [ "pending", "complete" ], + "description": "status of the payment (could be complete if already sent previously)" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "The amount delivered to destination (if known)" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment if known" + }, + "created_at": { + "type": "u64", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "The amount sent" + }, + "label": { + "type": "string", + "description": "the *label*, if given to sendpay" + }, + "partid": { + "type": "u64", + "description": "the *partid*, if given to sendpay" + }, + "bolt11": { + "type": "string", + "description": "the bolt11 string (if supplied)" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string (if supplied: **experimental-offers** only)." + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "payment_preimage" ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "partid": { }, + "bolt11": { }, + "bolt12": { }, + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "pending" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "message" ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "partid": { }, + "bolt11": { }, + "bolt12": { }, + "message": { + "type": "string", + "description": "Monitor status with listpays or waitsendpay" + } + } + } + } + ] +} diff --git a/doc/schemas/sendpsbt.schema.json b/doc/schemas/sendpsbt.schema.json new file mode 100644 index 000000000..d8095507d --- /dev/null +++ b/doc/schemas/sendpsbt.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "tx", "txid" ], + "properties": { + "tx": { + "type": "hex", + "description": "The raw transaction which was sent" + }, + "txid": { + "type": "txid", + "description": "The txid of the **tx**" + } + } +} diff --git a/doc/schemas/setchannelfee.schema.json b/doc/schemas/setchannelfee.schema.json new file mode 100644 index 000000000..fab668c8c --- /dev/null +++ b/doc/schemas/setchannelfee.schema.json @@ -0,0 +1,41 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "base", "ppm", "channels" ], + "properties": { + "base": { + "type": "u32", + "description": "The fee_base_msat value" + }, + "ppm": { + "type": "u32", + "description": "The fee_proportional_millionths value" + }, + "channels": { + "type": "array", + "description": "channel(s) whose rate is now set", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "peer_id", "channel_id" ], + "properties": { + "peer_id": { + "type": "pubkey", + "description": "The node_id of the peer" + }, + "channel_id": { + "type": "hex", + "description": "The channel_id of the channel", + "minLength": 64, + "maxLength": 64 + }, + "short_channel_id": { + "type": "short_channel_id", + "description": "the short_channel_id (if locked in)" + } + } + } + } + } +} diff --git a/doc/schemas/signmessage.schema.json b/doc/schemas/signmessage.schema.json new file mode 100644 index 000000000..4c866e72f --- /dev/null +++ b/doc/schemas/signmessage.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "signature", "recid", "zbase" ], + "properties": { + "signature": { + "type": "hex", + "description": "The signature", + "minLength": 128, + "maxLength": 128 + }, + "recid": { + "type": "hex", + "description": "The recovery id (0, 1, 2 or 3)", + "minLength": 2, + "maxLength": 2 + }, + "zbase": { + "type": "string", + "description": "*signature* and *recid* encoded in a style compatible with **lnd**'s [SignMessageRequest](https://api.lightning.community/#grpc-request-signmessagerequest)" + } + } +} diff --git a/doc/schemas/signpsbt.schema.json b/doc/schemas/signpsbt.schema.json new file mode 100644 index 000000000..f17efe201 --- /dev/null +++ b/doc/schemas/signpsbt.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "signed_psbt" ], + "properties": { + "signed_psbt": { + "type": "string", + "description": "The fully signed PSBT" + } + } +} diff --git a/doc/schemas/stop.schema.json b/doc/schemas/stop.schema.json new file mode 100644 index 000000000..b4110edf9 --- /dev/null +++ b/doc/schemas/stop.schema.json @@ -0,0 +1,5 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "string", + "enum": [ "Shutdown complete" ] +} diff --git a/doc/schemas/txdiscard.schema.json b/doc/schemas/txdiscard.schema.json new file mode 100644 index 000000000..33576f417 --- /dev/null +++ b/doc/schemas/txdiscard.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "unsigned_tx", "txid" ], + "properties": { + "unsigned_tx": { + "type": "hex", + "description": "the unsigned transaction" + }, + "txid": { + "type": "txid", + "description": "the transaction id of *unsigned_tx*" + } + } +} diff --git a/doc/schemas/txprepare.schema.json b/doc/schemas/txprepare.schema.json new file mode 100644 index 000000000..7ee0df8c1 --- /dev/null +++ b/doc/schemas/txprepare.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "psbt", "unsigned_tx", "txid" ], + "properties": { + "psbt": { + "type": "string", + "description": "the PSBT representing the unsigned transaction" + }, + "unsigned_tx": { + "type": "hex", + "description": "the unsigned transaction" + }, + "txid": { + "type": "txid", + "description": "the transaction id of *unsigned_tx*; you hand this to lightning-txsend(7) or lightning-txdiscard(7), as the inputs of this transaction are reserved." + } + } +} diff --git a/doc/schemas/txsend.schema.json b/doc/schemas/txsend.schema.json new file mode 100644 index 000000000..51f87a2e8 --- /dev/null +++ b/doc/schemas/txsend.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "psbt", "tx", "txid" ], + "properties": { + "psbt": { + "type": "string", + "description": "the completed PSBT representing the signed transaction" + }, + "tx": { + "type": "hex", + "description": "the fully signed transaction" + }, + "txid": { + "type": "txid", + "description": "the transaction id of *tx*" + } + } +} diff --git a/doc/schemas/unreserveinputs.schema.json b/doc/schemas/unreserveinputs.schema.json new file mode 100644 index 000000000..b81614034 --- /dev/null +++ b/doc/schemas/unreserveinputs.schema.json @@ -0,0 +1,59 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "reservations" ], + "properties": { + "reservations": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "txid", "vout", "was_reserved", "reserved" ], + "properties": { + "txid": { + "type": "txid", + "description": "the transaction id" + }, + "vout": { + "type": "u32", + "description": "the output number which was reserved" + }, + "was_reserved": { + "type": "boolean", + "description": "whether the input was already reserved (usually `true`)" + }, + "reserved": { + "type": "boolean", + "description": "whether the input is now reserved (may still be `true` if it was reserved for a long time)" + } + }, + "allOf": [ + { + "if": { + "additionalProperties": true, + "properties": { + "reserved": { + "enum": [ true ] + } + } + }, + "then": { + "required": [ "reserved_to_block" ], + "properties": { + "txid": { }, + "vout": { }, + "was_reserved": { }, + "reserved": { }, + "reserved_to_block": { + "type": "u32", + "description": "what blockheight the reservation will expire" + } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/utxopsbt.schema.json b/doc/schemas/utxopsbt.schema.json new file mode 100644 index 000000000..85c150239 --- /dev/null +++ b/doc/schemas/utxopsbt.schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "psbt", "feerate_per_kw", "estimated_final_weight", "excess_msat" ], + "properties": { + "psbt": { + "type": "string", + "description": "Unsigned PSBT which fulfills the parameters given" + }, + "feerate_per_kw": { + "type": "u32", + "description": "The feerate used to create the PSBT, in satoshis-per-kiloweight" + }, + "estimated_final_weight": { + "type": "u32", + "description": "The estimated weight of the transaction once fully signed" + }, + "excess_msat": { + "type": "msat", + "description": "The amount above *satoshi* which is available. This could be zero, or dust; it will be zero if *change_outnum* is also returned" + }, + "change_outnum": { + "type": "u32", + "description": "The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds)" + }, + "reservations": { + "type": "array", + "description": "If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7)", + "items": { + "type": "object", + "required": ["txid", "vout", "was_reserved", "reserved", "reserved_to_block" ], + "additionalProperties": false, + "properties": { + "txid": { + "type": "txid", + "description": "The txid of the transaction" + }, + "vout": { + "type": "u32", + "description": "The 0-based output number" + }, + "was_reserved": { + "type": "boolean", + "description": "Whether this output was previously reserved" + }, + "reserved": { + "type": "boolean", + "enum": [ true ], + "description": "Whether this output is now reserved" + }, + "reserved_to_block": { + "type": "u32", + "description": "The blockheight the reservation will expire" + } + } + } + } + } +} diff --git a/doc/schemas/waitanyinvoice.schema.json b/doc/schemas/waitanyinvoice.schema.json new file mode 100644 index 000000000..85ee1b6e7 --- /dev/null +++ b/doc/schemas/waitanyinvoice.schema.json @@ -0,0 +1,108 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "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": [ "paid", "expired" ], + "description": "Whether it's paid or expired" + }, + "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": { } + } + } + } + ] +} diff --git a/doc/schemas/waitblockheight.schema.json b/doc/schemas/waitblockheight.schema.json new file mode 100644 index 000000000..5b889377e --- /dev/null +++ b/doc/schemas/waitblockheight.schema.json @@ -0,0 +1,11 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "blockheight" ], + "properties": { + "blockheight": { + "type": "u32", + "description": "The current block height (>= *blockheight* parameter)" + } + } +} diff --git a/doc/schemas/waitinvoice.schema.json b/doc/schemas/waitinvoice.schema.json new file mode 100644 index 000000000..85ee1b6e7 --- /dev/null +++ b/doc/schemas/waitinvoice.schema.json @@ -0,0 +1,108 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "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": [ "paid", "expired" ], + "description": "Whether it's paid or expired" + }, + "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": { } + } + } + } + ] +} diff --git a/doc/schemas/waitsendpay.schema.json b/doc/schemas/waitsendpay.schema.json new file mode 100644 index 000000000..1ec0ff4d7 --- /dev/null +++ b/doc/schemas/waitsendpay.schema.json @@ -0,0 +1,98 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": true, + "required": [ "id", "payment_hash", "status", "created_at", "amount_sent_msat" ], + "properties": { + "id": { + "type": "u64", + "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 + }, + "status": { + "type": "string", + "enum": [ "complete" ], + "description": "status of the payment" + }, + "msatoshi": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "The amount delivered to destination (if known)" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment if known" + }, + "created_at": { + "type": "u64", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "msatoshi_sent": { + "deprecated": true + }, + "amount_sent_msat": { + "type": "msat", + "description": "The amount sent" + }, + "label": { + "type": "string", + "description": "the label, if given to sendpay" + }, + "partid": { + "type": "u64", + "description": "the *partid*, if given to sendpay" + }, + "bolt11": { + "type": "string", + "description": "the bolt11 string (if pay supplied one)" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 string (if supplied for pay: **experimental-offers** only)." + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "payment_preimage" ], + "properties": { + "id": { }, + "payment_hash": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "destination": { }, + "created_at": { }, + "msatoshi_sent": { }, + "amount_sent_msat": { }, + "label": { }, + "partid": { }, + "bolt11": { }, + "bolt12": { }, + "payment_preimage": { + "type": "hex", + "description": "the proof of payment: SHA256 of this **payment_hash**", + "maxLength": 64, + "minLength": 64 + } + } + } + } + ] +} diff --git a/doc/schemas/withdraw.schema.json b/doc/schemas/withdraw.schema.json new file mode 100644 index 000000000..3e2dbac42 --- /dev/null +++ b/doc/schemas/withdraw.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "psbt", "tx", "txid" ], + "properties": { + "tx": { + "type": "hex", + "description": "the fully signed bitcoin transaction" + }, + "txid": { + "type": "txid", + "description": "the transaction id of *tx*" + }, + "psbt": { + "type": "string", + "description": "the PSBT representing the unsigned transaction" + } + } +}