diff --git a/contrib/pyln-testing/pyln/testing/fixtures.py b/contrib/pyln-testing/pyln/testing/fixtures.py index d4e25ffaf066..53eafd99d6ed 100644 --- a/contrib/pyln-testing/pyln/testing/fixtures.py +++ b/contrib/pyln-testing/pyln/testing/fixtures.py @@ -232,6 +232,12 @@ def is_u16(checker, instance): return False return instance >= 0 and instance < 2**16 + def is_u8(checker, instance): + """8-bit integer""" + if not checker.is_type(instance, "integer"): + return False + return instance >= 0 and instance < 2**8 + def is_short_channel_id(checker, instance): """Short channel id""" if not checker.is_type(instance, "string"): @@ -307,6 +313,7 @@ def is_txid(checker, instance): "u64": is_u64, "u32": is_u32, "u16": is_u16, + "u8": is_u8, "pubkey": is_pubkey, "msat": is_msat, "txid": is_txid, diff --git a/doc/Makefile b/doc/Makefile index 30f4804d7168..db8267983de9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -137,10 +137,15 @@ clean: doc-clean check: check-manpages # This needs plugins, too. -check-manpages: all-programs +check-manpages: all-programs check-config-docs @tools/check-manpage.sh cli/lightning-cli doc/lightning-cli.1.md @tools/check-manpage.sh "lightningd/lightningd --lightning-dir=/tmp/" doc/lightningd-config.5.md +# Makes sure that fields mentioned in schema are in man page, and vice versa. +check-config-docs: + @for c in `sed -n 's/^ "\(.*\)": {/\1/p' doc/schemas/listconfigs.schema.json | grep -v '^# version$$' | grep -v '^plugins$$' | grep -v '^important-plugins$$'`; do if ! grep -q "^ \*\*$$c\*\*" doc/lightningd-config.5.md; then echo "$$c undocumented!"; exit 1; fi; done + @for c in `grep -v '\[plugin ' doc/lightningd-config.5.md | sed -n 's/^ \*\*\([^*]*\)\*\*.*/\1/p' | grep -v '^\(help\|version\|mainnet\|testnet\|signet\|plugin\|important-plugin\|plugin-dir\|clear-plugins\)$$'`; do if ! grep -q '^ "'"$$c"'"' doc/schemas/listconfigs.schema.json; then echo "$$c documented but not in schema!"; exit 1; fi; done + doc-maintainer-clean: $(RM) $(MANPAGES) diff --git a/doc/STYLE.md b/doc/STYLE.md index 06c9ddd61caf..bab3a2b4dc4e 100644 --- a/doc/STYLE.md +++ b/doc/STYLE.md @@ -194,6 +194,12 @@ All `warning` fields should have unique names which start with `warning_`, the value of which should be an explanation. This allows for programs to deal with them sanely, and also perform translations. +### Documenting JSON APIs + +We use JSON schemas to validate that JSON-RPC returns are in the +correct form, and also to generate documentation. See +[doc/schemas/WRITING_SCHEMAS.md](WRITING_SCHEMAS.md). + ## Changing JSON APIs All JSON API changes need a Changelog line (see below). diff --git a/doc/lightning-addgossip.7 b/doc/lightning-addgossip.7 index a050c3b3eb43..a97aca523451 100644 --- a/doc/lightning-addgossip.7 +++ b/doc/lightning-addgossip.7 @@ -35,4 +35,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:dd8b1fd2ffcf7c57629a042f44f2fbc526d8892a2c933de6e82511721a8ffdea +\" SHA256STAMP:cf8eccccfb5e26329100122ce2ed8a0dde4892aab91761c18b935a62fba73eeb diff --git a/doc/lightning-addgossip.7.md b/doc/lightning-addgossip.7.md index 2bac1588465a..25e9c6c41f64 100644 --- a/doc/lightning-addgossip.7.md +++ b/doc/lightning-addgossip.7.md @@ -41,4 +41,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff) +[comment]: # ( SHA256STAMP:f807f98a54c194fab710f8a3393e96685fdbd0efa5e178cca54507a70a7a5c20) diff --git a/doc/lightning-autocleaninvoice.7 b/doc/lightning-autocleaninvoice.7 index 0c9dfead0e36..ab792ae1e0da 100644 --- a/doc/lightning-autocleaninvoice.7 +++ b/doc/lightning-autocleaninvoice.7 @@ -54,4 +54,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:dd3f512e81f45ab6084b608bc05fba5679b1d20d493aad98d422bdf593182604 +\" SHA256STAMP:607f888f8c0228257fbeeb382262be93191f1da2be1fdebcf619b500889e349a diff --git a/doc/lightning-autocleaninvoice.7.md b/doc/lightning-autocleaninvoice.7.md index 6e649ee2fd36..08e0ad2bece5 100644 --- a/doc/lightning-autocleaninvoice.7.md +++ b/doc/lightning-autocleaninvoice.7.md @@ -49,4 +49,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:2accf7788133af97ae097f7e4e8a80b35bbb431eb7e787e5ae12dd5c7d2c296d) +[comment]: # ( SHA256STAMP:b03847eff3fac04edb72f6ef86b31a2d05c077a8771845717a26f463ebed4ae7) diff --git a/doc/lightning-check.7 b/doc/lightning-check.7 index 27dd0e436690..905a4f86ce63 100644 --- a/doc/lightning-check.7 +++ b/doc/lightning-check.7 @@ -39,4 +39,4 @@ Mark Beckwith \fI and Rusty Russell Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:9e78651117d3546edaf5150621630ee5dc4ccefd6e6a17b52b9dc8f86e8ba0c9 +\" SHA256STAMP:23dcfd6ce780b46a9d700cee5cdf7221702ea2a8c587461b92982172e79ee836 diff --git a/doc/lightning-check.7.md b/doc/lightning-check.7.md index 67bd9ecec8da..8ee63f418e4c 100644 --- a/doc/lightning-check.7.md +++ b/doc/lightning-check.7.md @@ -39,4 +39,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:5b399ee88a5fb6b7eac0e1ac349a68a8715154f8c6468aedf446c703c91ac165) +[comment]: # ( SHA256STAMP:3dd679aceebf5dca6daabc1b28a0f95c413daa9a689bf55270b38b57f0b17957) diff --git a/doc/lightning-checkmessage.7 b/doc/lightning-checkmessage.7 index 59582143085f..2636c9df3940 100644 --- a/doc/lightning-checkmessage.7 +++ b/doc/lightning-checkmessage.7 @@ -21,20 +21,29 @@ efficiently than trying each one, so performance is not a concern\. .SH RETURN VALUE -On correct usage, an object with attribute \fIverified\fR will be -returned\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBverified\fR (boolean): Whether the signature was valid -If \fIverified\fR is true, the signature was generated by the returned -\fIpubkey\fR for that given message\. \fIpubkey\fR is the one specified as -input, or if none was specified, the known node which must have -produced this signature\. +.RE +If \fBverified\fR is \fItrue\fR: -If \fIverified\fR is false, the signature is meaningless\. \fIpubkey\fR may -also be returned, which is they \fIpubkey\fR (if any) for which this -signature would be valid\. This is usually not useful\. +.RS +.IP \[bu] +\fBpubkey\fR (pubkey): the \fIpubkey\fR parameter, or the pubkey found by looking for known nodes +.RE + +If \fBverified\fR is \fIfalse\fR: + +.RS +.IP \[bu] +\fBpubkey\fR (pubkey): the \fIpubkey\fR (if any) which could have signed this; this is usually not useful! + +.RE .SH AUTHOR Rusty Russell \fI is mainly responsible\. @@ -47,4 +56,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:f270fa8137eb25480c7300d106db5e0bc49c2511397cfc0eb80b9529d3a358fb +\" SHA256STAMP:db4d5955a5e6a9c11ba8ea7717598e867131243c2ccf249eb2b50c803fc5e085 diff --git a/doc/lightning-checkmessage.7.md b/doc/lightning-checkmessage.7.md index 8e55b30c08b6..cd689b072452 100644 --- a/doc/lightning-checkmessage.7.md +++ b/doc/lightning-checkmessage.7.md @@ -23,17 +23,16 @@ efficiently than trying each one, so performance is not a concern. RETURN VALUE ------------ -On correct usage, an object with attribute *verified* will be -returned. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **verified** (boolean): Whether the signature was valid -If *verified* is true, the signature was generated by the returned -*pubkey* for that given message. *pubkey* is the one specified as -input, or if none was specified, the known node which must have -produced this signature. +If **verified** is *true*: + - **pubkey** (pubkey): the *pubkey* parameter, or the pubkey found by looking for known nodes -If *verified* is false, the signature is meaningless. *pubkey* may -also be returned, which is they *pubkey* (if any) for which this -signature would be valid. This is usually not useful. +If **verified** is *false*: + - **pubkey** (pubkey): the *pubkey* (if any) which could have signed this; this is usually not useful! +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -50,3 +49,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:7c0607f4a7d11de4c9d4cac0e56df8475c0a14e9f1ce70d7fc49322a5b184901) diff --git a/doc/lightning-close.7 b/doc/lightning-close.7 index 5255b73a81a9..40a770203762 100644 --- a/doc/lightning-close.7 +++ b/doc/lightning-close.7 @@ -123,4 +123,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:17f5bb362d8501b04314756c4134e3d5d20f8729dd55f5f3cfa0b5e111b104a1 +\" SHA256STAMP:03f1e6937a88aad4bdcd29d010da9ced148e3498ea19b388e8cbfde25276482d diff --git a/doc/lightning-close.7.md b/doc/lightning-close.7.md index 067ec8df1ddf..2e42891015a0 100644 --- a/doc/lightning-close.7.md +++ b/doc/lightning-close.7.md @@ -107,4 +107,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:9159304cd705d8135c32e12bd029c0e95baff0d495e6f9092a75888dab2f5fb3) +[comment]: # ( SHA256STAMP:d590b312dff1e1fb4e0bf5540d04bfa4925f6cba51bef6664a642e382ec257d9) diff --git a/doc/lightning-connect.7 b/doc/lightning-connect.7 index 4bafbaf8a3ee..01afe1b708c9 100644 --- a/doc/lightning-connect.7 +++ b/doc/lightning-connect.7 @@ -130,4 +130,4 @@ Felix \fI is the original author of this manpage\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:ff422184feb295e6d3e17e88c0305405edcb24eac59482a43caf750ef281e0ed +\" SHA256STAMP:47e5ec1e2d3cca8a40bd9b93faff9fd226b4fd481ab4c3c81d67f15dc6f8b839 diff --git a/doc/lightning-connect.7.md b/doc/lightning-connect.7.md index be1df3d74914..4c7770460bed 100644 --- a/doc/lightning-connect.7.md +++ b/doc/lightning-connect.7.md @@ -88,4 +88,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:5b168e7998d3db6a842eabf92bcbb74352fe831726ea42a801e39ff5c3f812ca) +[comment]: # ( SHA256STAMP:973f366e2f87becdece4ba3b71f9a5156529d7c155bb8fcac0d2b6662a9e467d) diff --git a/doc/lightning-createinvoice.7 b/doc/lightning-createinvoice.7 index 499537c23fcf..233f9ebe71fc 100644 --- a/doc/lightning-createinvoice.7 +++ b/doc/lightning-createinvoice.7 @@ -91,4 +91,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:2d654675f966516a0fb0553f66e5bacd3ab96482d20cd9701a84e15ae49a4d92 +\" SHA256STAMP:fd9275c58b67eca68aafee27cb79a558669b12b8cda56872f1db798637006278 diff --git a/doc/lightning-createinvoice.7.md b/doc/lightning-createinvoice.7.md index 99f5ce7ac859..03184ba303bf 100644 --- a/doc/lightning-createinvoice.7.md +++ b/doc/lightning-createinvoice.7.md @@ -72,4 +72,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:95a2fbf9c94fa1e01a322658035473c694bfb93e02d32c2cefafe6ef5b676695) +[comment]: # ( SHA256STAMP:948d344d5f589050127bd5181689882c6fad036799fa6ff039a83194ff5fd098) diff --git a/doc/lightning-createonion.7 b/doc/lightning-createonion.7 index 2f075852f805..de9325b2ab81 100644 --- a/doc/lightning-createonion.7 +++ b/doc/lightning-createonion.7 @@ -153,4 +153,4 @@ Christian Decker \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:c21aa197637bea17068072cd5907ad3302b48586067a8a5a8d748fd8e7e0a668 +\" SHA256STAMP:cf1acef3ea6f29fc4fb98ee418693d8ffb1b35b4f22345c9e2ce45a91f3efd4d diff --git a/doc/lightning-createonion.7.md b/doc/lightning-createonion.7.md index b10ecfce8dd0..292ae471b85e 100644 --- a/doc/lightning-createonion.7.md +++ b/doc/lightning-createonion.7.md @@ -135,4 +135,4 @@ RESOURCES Main web site: [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md -[comment]: # ( SHA256STAMP:a5a64325f4232f27bccbbe1c9fc62bfb602ba60c81f46a1ef2df25b06dac807e) +[comment]: # ( SHA256STAMP:68e54caa71beb0445389b61d8b384e40ec91e7569d4e2f2de05ed7612713ee64) diff --git a/doc/lightning-decode.7 b/doc/lightning-decode.7 index a497de756f0b..1ce806d5018d 100644 --- a/doc/lightning-decode.7 +++ b/doc/lightning-decode.7 @@ -414,4 +414,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:403b7cf3cadd8b260b8b2b02746c76d7d21a8319fe386b4174f4f58b3e5dcdbd +\" SHA256STAMP:045cd00ad893483df132bdffd913049bfe43acb152a511accc9f17f87ba06a8d diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md index 356162493914..7d1f28aa5638 100644 --- a/doc/lightning-decode.7.md +++ b/doc/lightning-decode.7.md @@ -183,4 +183,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:733d22404e5230882682b846ace92451d8988cf028fa903d735f61b7c61f1c08) +[comment]: # ( SHA256STAMP:f0adee97f3b5776059252703efee1b8e244c1141f9f3dd5fe73e3d7ed4d59ab4) diff --git a/doc/lightning-decodepay.7 b/doc/lightning-decodepay.7 index e491f7348cf5..2b824642e49f 100644 --- a/doc/lightning-decodepay.7 +++ b/doc/lightning-decodepay.7 @@ -107,4 +107,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:1b0e5c34291b3c252c651e952109f57fe68a90770fecaa0eeebf9070ed8c2dad +\" SHA256STAMP:38fe5fd558271a8c5d34f3a4dd114d83389545b38b92b89ec0b16da70b73539a diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md index 786a692ef76a..1231ca951f67 100644 --- a/doc/lightning-decodepay.7.md +++ b/doc/lightning-decodepay.7.md @@ -68,4 +68,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:33a160a1d9e56690e59b71c4d9d3e141bf7604c111cd5a5624bda692b85c9026) +[comment]: # ( SHA256STAMP:435b2a155971979a75be7e9aefc5a686795c3ab210b94af72cf069bd5f3bcefc) diff --git a/doc/lightning-delexpiredinvoice.7 b/doc/lightning-delexpiredinvoice.7 index 680de0f1210f..d999c694d871 100644 --- a/doc/lightning-delexpiredinvoice.7 +++ b/doc/lightning-delexpiredinvoice.7 @@ -30,4 +30,4 @@ ZmnSCPxj \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:a47d47609d9b39bbe6c0f0c61e28d255ceb496a49ad306db22ef23011c6f8cb8 +\" SHA256STAMP:dfb82c8bfb0c1891ac29d98f9eddaf05fb1ae8a9529893003371581e4343e72c diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md index 0f12ecbb8680..2a6c49dfbf46 100644 --- a/doc/lightning-delexpiredinvoice.7.md +++ b/doc/lightning-delexpiredinvoice.7.md @@ -37,4 +37,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:f267fd509a5e3e55e2322ddc8b233eb820638ed5f50f606e3e6c8ae17f1c8421) +[comment]: # ( SHA256STAMP:644749218693cab4f48f6557a908aba66ae32f6b769576345f66ad62a6c7e7e0) diff --git a/doc/lightning-delinvoice.7 b/doc/lightning-delinvoice.7 index ef620be23636..17911a8a317b 100644 --- a/doc/lightning-delinvoice.7 +++ b/doc/lightning-delinvoice.7 @@ -25,6 +25,8 @@ On success, an object is returned, containing: .IP \[bu] \fBlabel\fR (string): Unique label given at creation time .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): State of invoice (one of "paid", "expired", "unpaid") .IP \[bu] \fBexpires_at\fR (u64): UNIX timestamp when invoice expires (or expired) @@ -32,6 +34,10 @@ On success, an object is returned, containing: \fBbolt11\fR (string, optional): BOLT11 string .IP \[bu] \fBbolt12\fR (string, optional): BOLT12 string +.IP \[bu] +\fBamount_msat\fR (msat, optional): the amount required to pay this invoice +.IP \[bu] +\fBdescription\fR (string, optional): description used in the invoice .RE @@ -87,4 +93,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:28d1e97fe8e8925008b20815c55db569b7ed8dad33d958c0914945c71fb9d654 +\" SHA256STAMP:ff36afbf0c8f27efd0c6e82f32ba783e511f53f5978342b210ba78038c1934bf diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md index c699bc7de2fb..98cc088f1da3 100644 --- a/doc/lightning-delinvoice.7.md +++ b/doc/lightning-delinvoice.7.md @@ -23,10 +23,13 @@ Note: The return is the same as an object from lightning-listinvoice(7). [comment]: # (GENERATE-FROM-SCHEMA-START) On success, an object is returned, containing: - **label** (string): Unique label given at creation time +- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters) - **status** (string): State of invoice (one of "paid", "expired", "unpaid") - **expires_at** (u64): UNIX timestamp when invoice expires (or expired) - **bolt11** (string, optional): BOLT11 string - **bolt12** (string, optional): BOLT12 string +- **amount_msat** (msat, optional): the amount required to pay this invoice +- **description** (string, optional): description used in the invoice If **bolt12** is present: - **local_offer_id** (hex, optional): offer for which this invoice was created @@ -68,4 +71,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:8cd84ec57d229dacb6d6c52510334da87846f1c8eea7db286063a2513e8318cb) +[comment]: # ( SHA256STAMP:6435d88007d1b21e97c969cc202e240ed57df572a3312a6b77ea66ed3a8d512a) diff --git a/doc/lightning-delpay.7 b/doc/lightning-delpay.7 index 2a20c2445c68..423134b2c353 100644 --- a/doc/lightning-delpay.7 +++ b/doc/lightning-delpay.7 @@ -120,4 +120,4 @@ Vincenzo Palazzo \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:520f0b56c7288ed46509a0ab90be0959b3b1489b56b7e94f223de19cf7028758 +\" SHA256STAMP:143436ad1fe8687300cb5ccb433630905a56af81aaf3aa61abfa7b1548af9177 diff --git a/doc/lightning-delpay.7.md b/doc/lightning-delpay.7.md index d3c7094a45fe..4e33a9e2a573 100644 --- a/doc/lightning-delpay.7.md +++ b/doc/lightning-delpay.7.md @@ -99,4 +99,4 @@ RESOURCES --------- Main web site: -[comment]: # ( SHA256STAMP:26e293e5b3de31a95572763a6d7c360c0f9f78112b3fcef12c639d001b0fa9b5) +[comment]: # ( SHA256STAMP:c3a603b1e43a370ff38a3d9eebe63f8acf26447b024cf5e4bd6f93fe41632529) diff --git a/doc/lightning-dev-sendcustommsg.7 b/doc/lightning-dev-sendcustommsg.7 index d8efec500117..6546402263dd 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 d4b73f34953e..1b78a156cb29 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-disableoffer.7 b/doc/lightning-disableoffer.7 index 88f923c77d86..df88f5921b65 100644 --- a/doc/lightning-disableoffer.7 +++ b/doc/lightning-disableoffer.7 @@ -78,4 +78,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:33b8cddae4a830e710906268c1d0d301442bc7ab0711e1d6ce670f86c77ae320 +\" SHA256STAMP:03b1a12409ad02eca1543d99bafdfbd2d7d2c869e182fba513e3f93fb48a7664 diff --git a/doc/lightning-disableoffer.7.md b/doc/lightning-disableoffer.7.md index 201cd99c5f91..32f6fb66d2b9 100644 --- a/doc/lightning-disableoffer.7.md +++ b/doc/lightning-disableoffer.7.md @@ -72,4 +72,4 @@ RESOURCES --------- Main web site: -[comment]: # ( SHA256STAMP:6b0ae21e38a83742735f38e9c022b33ed4a436cacc746ff22e63d7b00779e4d0) +[comment]: # ( SHA256STAMP:abf340bf35dcefd42fba609b3ae95adb2f74bb5766c68e174a9b8f9114c80202) diff --git a/doc/lightning-disconnect.7 b/doc/lightning-disconnect.7 index 5110a38014c2..e9bc6fbfc121 100644 --- a/doc/lightning-disconnect.7 +++ b/doc/lightning-disconnect.7 @@ -63,4 +63,4 @@ Michael Hawkins \fI\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:7efc0fbbb7397d3767ea170ba091b5bc00f4efaf8e1283c7b7ed1aaaccfd3c4d +\" SHA256STAMP:ce9e367309c8e5cabc9d4ac8dfd878f893dd3b9235c0c4b1a2bb0e431cf5b5f6 diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md index 30571804aa24..c4802c873cf6 100644 --- a/doc/lightning-disconnect.7.md +++ b/doc/lightning-disconnect.7.md @@ -58,4 +58,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff) +[comment]: # ( SHA256STAMP:f807f98a54c194fab710f8a3393e96685fdbd0efa5e178cca54507a70a7a5c20) diff --git a/doc/lightning-feerates.7 b/doc/lightning-feerates.7 index 294aeaf2fc46..d5b281cbcdfe 100644 --- a/doc/lightning-feerates.7 +++ b/doc/lightning-feerates.7 @@ -169,4 +169,4 @@ manpage\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:6e1ae2f26676a76231461ac1f696066e538edabfab00ec9480550a5c6bc6981e +\" SHA256STAMP:4c54ce8e279cf43b55ad0dffea21df46bfb5698d49833013da9e4df4c1475ee4 diff --git a/doc/lightning-feerates.7.md b/doc/lightning-feerates.7.md index 79ae753e669e..76e87e3f9cc8 100644 --- a/doc/lightning-feerates.7.md +++ b/doc/lightning-feerates.7.md @@ -118,4 +118,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:e16ae963e528995f1e01c80b4ed4e9b0d6c457a559928e98ab6cf32624557894) +[comment]: # ( SHA256STAMP:b7efbc2380ce39e1d8f244a9c16203f034d53b84f8396f4c4fc06973d24cefe4) diff --git a/doc/lightning-fetchinvoice.7 b/doc/lightning-fetchinvoice.7 index 753f4c66ec18..e6636076cabc 100644 --- a/doc/lightning-fetchinvoice.7 +++ b/doc/lightning-fetchinvoice.7 @@ -114,4 +114,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:23be8c105314c109fa0f7c532c3eebf9b2cbe47f520d600d3d2159765def3cbd +\" SHA256STAMP:532248cb5adbadb10367fdbddc2da7af0eeac50b29709abec2e1e8b178197b7c diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md index 46de11de5c81..213168fb475a 100644 --- a/doc/lightning-fetchinvoice.7.md +++ b/doc/lightning-fetchinvoice.7.md @@ -81,4 +81,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:e2b81ad7a61dd6a6d55e21c5367c3286aaf00cee734b2719a8e38bc87f7ac8aa) +[comment]: # ( SHA256STAMP:c98a6dd644a23fb336aa2ce190e15ae602da8b4142afbed28e4243114f679e90) diff --git a/doc/lightning-fundchannel.7 b/doc/lightning-fundchannel.7 index 69944ba73735..51dc7de65543 100644 --- a/doc/lightning-fundchannel.7 +++ b/doc/lightning-fundchannel.7 @@ -130,4 +130,4 @@ channel parameters (funding limits, channel reserves, fees, etc\.)\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:ee8d7d247d9d4f263f8bbed936a2ba4b61d4afc5c48580f462a0d6142c13dbbd +\" SHA256STAMP:d25fc36b745b6f58556f7f4b06f23ff83b466d4a00911f7ffdc9d86572902954 diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index deaa3904e8c8..770efa4ea827 100644 --- a/doc/lightning-fundchannel.7.md +++ b/doc/lightning-fundchannel.7.md @@ -103,4 +103,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:5b17c334b90f840a986750f9fcdb6a6bfa79bd1a3da11319a1957ba87bc4b0a7) +[comment]: # ( SHA256STAMP:6c8f18b20d695e0b4dba0786f9fc70042a6cc9970aeb7cca2ad1c8fc4c406244) diff --git a/doc/lightning-fundchannel_cancel.7 b/doc/lightning-fundchannel_cancel.7 index 663e39ccdd80..db815007326d 100644 --- a/doc/lightning-fundchannel_cancel.7 +++ b/doc/lightning-fundchannel_cancel.7 @@ -64,4 +64,4 @@ lightning-openchannel_\fBsigned\fR(7), lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d9006c6b2519f1ae2009a683e3e8131af6e182929d8f0025e451155e4e7d6fe6 +\" SHA256STAMP:b7e57e7a5eec165705d41d34205ac47ce1fe540c0bb9e4b6e36ae2da51322d67 diff --git a/doc/lightning-fundchannel_cancel.7.md b/doc/lightning-fundchannel_cancel.7.md index 80f24c3794f5..4ca7764e2059 100644 --- a/doc/lightning-fundchannel_cancel.7.md +++ b/doc/lightning-fundchannel_cancel.7.md @@ -58,4 +58,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:f639e58991b8a9b58b181e9f4bd325fb24368af5cb76f94a94ca21675421829b) +[comment]: # ( SHA256STAMP:61df28ebb6211155b8be8810c09e7d238b4a6857d5f1c558f30c63df19c2fd4d) diff --git a/doc/lightning-fundchannel_complete.7 b/doc/lightning-fundchannel_complete.7 index 566fabe0d92b..1cc95d228c3b 100644 --- a/doc/lightning-fundchannel_complete.7 +++ b/doc/lightning-fundchannel_complete.7 @@ -68,4 +68,4 @@ lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:72b7e8826beb42061bf53e59b72c35c4fba6cdb421e491ffe6bf07dc51412342 +\" SHA256STAMP:51894a500920df4510ca85db038527f8ef7138fba3afcea0cb1326ac1142f567 diff --git a/doc/lightning-fundchannel_complete.7.md b/doc/lightning-fundchannel_complete.7.md index 8a2a95957032..80138c2f3b1c 100644 --- a/doc/lightning-fundchannel_complete.7.md +++ b/doc/lightning-fundchannel_complete.7.md @@ -60,4 +60,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:7cb52658d81c5834e34a6011c04283bf740fe6e5feedb0208778abad5fddc519) +[comment]: # ( SHA256STAMP:5d6a53a68f16ec338c75e26e0e7ffbc4390afb771ca636eed4206cb8fdd56943) diff --git a/doc/lightning-fundchannel_start.7 b/doc/lightning-fundchannel_start.7 index fa212251fff1..16131a5e7578 100644 --- a/doc/lightning-fundchannel_start.7 +++ b/doc/lightning-fundchannel_start.7 @@ -93,4 +93,4 @@ lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:959e97d593fb77f9403e8c5024d5582a2ae81b5cffae1799a285e0a26281b770 +\" SHA256STAMP:2eeea3afea8c76e2cc9d5f449d43f1dbfe8e68edcc4e1ee33cb88d024e5f03de diff --git a/doc/lightning-fundchannel_start.7.md b/doc/lightning-fundchannel_start.7.md index 5f34431b6d42..c5246b3cba19 100644 --- a/doc/lightning-fundchannel_start.7.md +++ b/doc/lightning-fundchannel_start.7.md @@ -78,4 +78,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:9417a2d8d48b69f3557b08984d6b362e20cf20eeefcbef168fdc84b6f1de6411) +[comment]: # ( SHA256STAMP:164e9d5c0adfe28e392e0d7e5401ca301ce1f0fafeb944b56836f0be91754e2f) diff --git a/doc/lightning-fundpsbt.7 b/doc/lightning-fundpsbt.7 index b7c12cc51030..0a001fad42d1 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 ae5bde3896f1..d97e101a9867 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-getinfo.7 b/doc/lightning-getinfo.7 index 402fc691badb..1cd7b924908b 100644 --- a/doc/lightning-getinfo.7 +++ b/doc/lightning-getinfo.7 @@ -147,4 +147,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:637babe08b35ca524666bc51f1d0191e2006064af2b4c22997fbbe49cc7f935c +\" SHA256STAMP:3e1c0f27024c64e02c2a84c093f9de3dbec882c4dacb3fd45b7bc3f4eb98fc5e diff --git a/doc/lightning-getinfo.7.md b/doc/lightning-getinfo.7.md index 3419953eaac6..4edc00ba7e74 100644 --- a/doc/lightning-getinfo.7.md +++ b/doc/lightning-getinfo.7.md @@ -114,4 +114,4 @@ RESOURCES --------- Main web site: -[comment]: # ( SHA256STAMP:2aa0f0cf9de7b2d373bdce8b337535a0197ad8cb1df2cdb0e043ba49c3704816) +[comment]: # ( SHA256STAMP:50348a6798a89537bd7a15b1725c479e13f890fe77cbf6d8f0722e91c05eadd1) diff --git a/doc/lightning-getlog.7 b/doc/lightning-getlog.7 index 2fe16a77e5a2..08cb97c23d51 100644 --- a/doc/lightning-getlog.7 +++ b/doc/lightning-getlog.7 @@ -127,4 +127,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:13e3ab43fb6811bff8bee102ba85e7d4cb8eb97d11bb0720ae5c0c576ba021ec +\" SHA256STAMP:2503c2177e9d87f2d00338f2844f041dceec9458604d228732dade6e38fdf26e diff --git a/doc/lightning-getlog.7.md b/doc/lightning-getlog.7.md index 4fffb2d8d1be..df1f41762180 100644 --- a/doc/lightning-getlog.7.md +++ b/doc/lightning-getlog.7.md @@ -89,4 +89,4 @@ RESOURCES --------- Main web site: -[comment]: # ( SHA256STAMP:db99eeb155bb44ebda8b77afdc1fad773e82fa8892e1df6afd61c60a1f4b7ec3) +[comment]: # ( SHA256STAMP:4336a649aa44151ac41b408fea9e3c68c76a6b3b981925fb79c0e7b0ca73a543) diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 index 3d2d9c88caf4..31cf5b44ef25 100644 --- a/doc/lightning-getroute.7 +++ b/doc/lightning-getroute.7 @@ -147,4 +147,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:aaf1dab77352de52f8bf8a5c3e4a6449769b5dbfa51bdbf9b1a06575c8ae37fe +\" SHA256STAMP:313ccec881c876d2383b65f9fe0e6f95cfc8bebf3b5739cd5aa439530a98bb53 diff --git a/doc/lightning-getroute.7.md b/doc/lightning-getroute.7.md index 1c84d58fc819..9a7c4e62151f 100644 --- a/doc/lightning-getroute.7.md +++ b/doc/lightning-getroute.7.md @@ -308,4 +308,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:c15c56751270e8a3df25f3e3f72fbe8ea56366e5fe1157a8485b85cec1878982) +[comment]: # ( SHA256STAMP:a65836437a8dd19873cb9ff09a7fcbb2cee5e90f6bf61cabc1215c6dc41e01c3) diff --git a/doc/lightning-getsharedsecret.7 b/doc/lightning-getsharedsecret.7 index 3c4e32902d54..b3a75561bd91 100644 --- a/doc/lightning-getsharedsecret.7 +++ b/doc/lightning-getsharedsecret.7 @@ -14,13 +14,13 @@ key DER-encoding of the SECP256K1 point\. .SH RETURN VALUE -On success, \fBgetsharedsecret\fR returns a field \fIshared_secret\fR, -which is a hexadecimal string of the 256-bit SHA-2 of the -compressed public key DER-encoding of the SECP256K1 point -that is the shared secret generated using the -Elliptic Curve Diffie-Hellman algorithm\. -This field is 32 bytes (64 hexadecimal characters in a string)\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBshared_secret\fR (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters) + +.RE This command may fail if communications with the HSM has a problem; @@ -94,4 +94,4 @@ SECG SEC-1 ECIES: \fIhttps://secg.org/sec1-v2.pdf\fR Main web site: \fIhttps://github.com/ElementsProject/lightning\fR .RE -\" SHA256STAMP:695c9ea03a16c6698806f3b288c0b7163a112b19791fd81bf7b3f9b032804ca3 +\" SHA256STAMP:15ae6db73b5935de65901d6507c99c15c6dd847965555963c6fcf7cd7a64c74b diff --git a/doc/lightning-getsharedsecret.7.md b/doc/lightning-getsharedsecret.7.md index 13f3ea314eca..14dd56dd2d23 100644 --- a/doc/lightning-getsharedsecret.7.md +++ b/doc/lightning-getsharedsecret.7.md @@ -17,12 +17,10 @@ key DER-encoding of the SECP256K1 point. RETURN VALUE ------------ -On success, **getsharedsecret** returns a field *shared\_secret*, -which is a hexadecimal string of the 256-bit SHA-2 of the -compressed public key DER-encoding of the SECP256K1 point -that is the shared secret generated using the -Elliptic Curve Diffie-Hellman algorithm. -This field is 32 bytes (64 hexadecimal characters in a string). +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **shared_secret** (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters) +[comment]: # (GENERATE-FROM-SCHEMA-END) This command may fail if communications with the HSM has a problem; @@ -92,3 +90,4 @@ RESOURCES * Main web site: +[comment]: # ( SHA256STAMP:e7542ba319a25191968aacaa577e0bc29928f6069156eff286c7892444691c74) diff --git a/doc/lightning-help.7 b/doc/lightning-help.7 index b7c3bf8ec118..1701fa2adb8b 100644 --- a/doc/lightning-help.7 +++ b/doc/lightning-help.7 @@ -27,17 +27,23 @@ page is not found\. .fi .SH RETURN VALUE -On success, a object will be return with the following proprieties: +On success, an object is returned, containing: .RS .IP \[bu] -\fIcommand\fR: A string that represents the stucture of the command\. +\fBhelp\fR (array of objects): +.RS +.IP \[bu] +\fBcommand\fR (string): the command .IP \[bu] -\fIcategory\fR: A string that represents the category\. +\fBcategory\fR (string): the category for this command (useful for grouping) .IP \[bu] -\fIdescription\fR: A string that represents the description\. +\fBdescription\fR (string): a one-line description of the purpose of this command .IP \[bu] -\fIverbose\fR: A string that represents the verbode description\. +\fBverbose\fR (string): a full description of this command (including whether it's deprecated) + +.RE + .RE @@ -72,4 +78,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:cbd027bd9117d2e71167ab1c9d95a63c90b8e9c556dd75e951d4913a2891cb37 +\" SHA256STAMP:69bc1cd80da8ce53c2f258fdcd5b8d0909478629d1d3ceeead0d6a3052484f2e diff --git a/doc/lightning-help.7.md b/doc/lightning-help.7.md index 31626b39af05..d9d361673d84 100644 --- a/doc/lightning-help.7.md +++ b/doc/lightning-help.7.md @@ -28,12 +28,14 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, a object will be return with the following proprieties: - -- *command*: A string that represents the stucture of the command. -- *category*: A string that represents the category. -- *description*: A string that represents the description. -- *verbose*: A string that represents the verbode description. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **help** (array of objects): + - **command** (string): the command + - **category** (string): the category for this command (useful for grouping) + - **description** (string): a one-line description of the purpose of this command + - **verbose** (string): a full description of this command (including whether it's deprecated) +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -64,3 +66,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:89fb5e6d1f3127f8a4331fb00756871565c10e874a24554c60fa1a0e26ca5c8f) diff --git a/doc/lightning-invoice.7 b/doc/lightning-invoice.7 index d640a134ffcd..7037717367a0 100644 --- a/doc/lightning-invoice.7 +++ b/doc/lightning-invoice.7 @@ -77,45 +77,51 @@ Otherwise, it's set to the parameter \fBcltv-final\fR\. .SH RETURN VALUE -On success, a hash is returned as \fIpayment_hash\fR to be given to the -payer, and the \fIexpiry_time\fR as a UNIX timestamp\. It also returns a -BOLT11 invoice as \fIbolt11\fR to be given to the payer\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBbolt11\fR (string): the bolt11 string +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters) +.IP \[bu] +\fBexpires_at\fR (u64): UNIX timestamp of when invoice expires -On failure, an error is returned and no invoice is created\. If the -lightning process fails before responding, the caller should use -\fBlightning-listinvoice\fR(7) to query whether this invoice was created or -not\. - +.RE -The following error codes may occur: +The following warnings may also be returned: .RS .IP \[bu] --1: Catchall nonspecific error\. +\fBwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\. .IP \[bu] -900: An invoice with the given \fIlabel\fR already exists\. +\fBwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\. .IP \[bu] -901: An invoice with the given \fIpreimage\fR already exists\. +\fBwarning_deadends\fR: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't\. .IP \[bu] -902: None of the specified \fIexposeprivatechannels\fR were usable\. +\fBwarning_private_unused\fR: there would be enough incoming capacity, but some channels are unannounced and \fIexposeprivatechannels\fR is \fIfalse\fR, so there isn't\. +.IP \[bu] +\fBwarning_mpp\fR: there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments\. .RE -One of the following warnings may occur (on success): +On failure, an error is returned and no invoice is created\. If the +lightning process fails before responding, the caller should use +\fBlightning-listinvoices\fR(7) to query whether this invoice was created or +not\. + + +The following error codes may occur: .RS .IP \[bu] -\fIwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\. -.IP \[bu] -\fIwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\. +-1: Catchall nonspecific error\. .IP \[bu] -\fIwarning_deadends\fR: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't\. +900: An invoice with the given \fIlabel\fR already exists\. .IP \[bu] -\fIwarning_private_unused\fR: there would be enough incoming capacity, but some channels are unannounced and \fIexposeprivatechannels\fR is \fIfalse\fR, so there isn't\. +901: An invoice with the given \fIpreimage\fR already exists\. .IP \[bu] -\fIwarning_mpp\fR if there is sufficient capacity, but not in a single channel, - so the payer will have to use multi-part payments\. +902: None of the specified \fIexposeprivatechannels\fR were usable\. .RE .SH AUTHOR @@ -124,11 +130,10 @@ Rusty Russell \fI is mainly responsible\. .SH SEE ALSO -\fBlightning-listinvoice\fR(7), \fBlightning-delinvoice\fR(7), -\fBlightning-getroute\fR(7), \fBlightning-sendpay\fR(7)\. +\fBlightning-listinvoices\fR(7), \fBlightning-delinvoice\fR(7), \fBlightning-pay\fR(7)\. .SH RESOURCES Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d53ec67cd81a41c7218e282c3d7662933868b25190334e9322de8a90ab99d603 +\" SHA256STAMP:f27f015d8d612d280a8abca6930dbd42ef37fdac00bff1b114d1fd9138b15097 diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md index d48246c6855f..6ffab01acc1a 100644 --- a/doc/lightning-invoice.7.md +++ b/doc/lightning-invoice.7.md @@ -71,13 +71,23 @@ Otherwise, it's set to the parameter **cltv-final**. RETURN VALUE ------------ -On success, a hash is returned as *payment\_hash* to be given to the -payer, and the *expiry\_time* as a UNIX timestamp. It also returns a -BOLT11 invoice as *bolt11* to be given to the payer. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **bolt11** (string): the bolt11 string +- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters) +- **expires_at** (u64): UNIX timestamp of when invoice expires + +The following warnings may also be returned: +- **warning_capacity**: even using all possible channels, there's not enough incoming capacity to pay this invoice. +- **warning_offline**: there would be enough incoming capacity, but some channels are offline, so there isn't. +- **warning_deadends**: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't. +- **warning_private_unused**: there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't. +- **warning_mpp**: there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments. +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is returned and no invoice is created. If the lightning process fails before responding, the caller should use -lightning-listinvoice(7) to query whether this invoice was created or +lightning-listinvoices(7) to query whether this invoice was created or not. The following error codes may occur: @@ -86,14 +96,6 @@ The following error codes may occur: - 901: An invoice with the given *preimage* already exists. - 902: None of the specified *exposeprivatechannels* were usable. -One of the following warnings may occur (on success): -- *warning_capacity*: even using all possible channels, there's not enough incoming capacity to pay this invoice. -- *warning_offline*: there would be enough incoming capacity, but some channels are offline, so there isn't. -- *warning_deadends*: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't. -- *warning_private_unused*: there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't. -- *warning_mpp* if there is sufficient capacity, but not in a single channel, - so the payer will have to use multi-part payments. - AUTHOR ------ @@ -102,11 +104,11 @@ Rusty Russell <> is mainly responsible. SEE ALSO -------- -lightning-listinvoice(7), lightning-delinvoice(7), -lightning-getroute(7), lightning-sendpay(7). +lightning-listinvoices(7), lightning-delinvoice(7), lightning-pay(7). RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:e63e87b91a14b8ae823ae67fc25315bc31b15a14378c05f4c972830bf3515af1) diff --git a/doc/lightning-keysend.7 b/doc/lightning-keysend.7 index 8a54be1cd6f5..479be55961f9 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 e2a54df5dad3..aee67662ecb4 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-listchannels.7 b/doc/lightning-listchannels.7 index b6ef5f6a1e5c..98927e25595b 100644 --- a/doc/lightning-listchannels.7 +++ b/doc/lightning-listchannels.7 @@ -26,61 +26,37 @@ broadcast on the gossip network\. .SH RETURN VALUE -On success, an object with a "channels" key is returned containing a -list of 0 or more objects\. - - -Each object in the list contains the following data: +On success, an object containing \fBchannels\fR is returned\. It is an array of objects, where each object contains: .RS .IP \[bu] -\fIsource\fR : The node providing entry to the channel, specifying the -fees charged for using the channel in that direction\. -.IP \[bu] -\fIdestination\fR : The node providing the exit point for the channel\. +\fBsource\fR (pubkey): the source node .IP \[bu] -\fIshort_channel_id\fR : The channel identifier\. +\fBdestination\fR (pubkey): the destination node .IP \[bu] -\fIpublic\fR : Boolean value, is publicly available\. Non-local channels -will only ever have this value set to true\. Local channels are -side-loaded by this node, rather than obtained through the gossip -network, and so may have this value set to false\. +\fBpublic\fR (boolean): true if this is announced (otherwise it must be our channel) .IP \[bu] -\fIsatoshis\fR : Funds available in the channel\. +\fBamount_msat\fR (msat): the total capacity of this channel (always a whole number of satoshis) .IP \[bu] -\fIamount_sat\fR : Same as above, but ending in \fIsat\fR\. +\fBmessage_flags\fR (u8): as defined by BOLT #7 .IP \[bu] -\fImessage_flags\fR : Bitfield showing the presence of optional fields -in the \fIchannel_update\fR message (BOLT #7)\. +\fBchannel_flags\fR (u8): as defined by BOLT #7 .IP \[bu] -\fIchannel_flags\fR : Bitfields indicating the direction of the channel -and signaling various options concerning the channel\. (BOLT #7)\. +\fBactive\fR (boolean): true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing .IP \[bu] -\fIactive\fR : Boolean value, is available for routing\. This is linked -to the channel flags data, where if the second bit is set, signals a -channels temporary unavailability (due to loss of connectivity) OR -permanent unavailability where the channel has been closed but not -settlement on-chain\. +\fBlast_update\fR (u32): UNIX timestamp on the last channel_update from \fIsource\fR .IP \[bu] -\fIlast_update\fR : Unix timestamp (seconds) showing when the last -channel_update message was received\. +\fBbase_fee_millisatoshi\fR (u32): Base fee changed by \fIsource\fR to use this channel .IP \[bu] -\fIbase_fee_millisatoshi\fR : The base fee (in millisatoshi) charged -for the HTLC (BOLT #7; equivalent to \fBfee_base_msat\fR)\. +\fBfee_per_millionth\fR (u32): Proportional fee changed by \fIsource\fR to use this channel, in parts-per-million .IP \[bu] -\fIfee_per_millionth\fR : The amount (in millionths of a satoshi) -charged per transferred satoshi (BOLT #7; equivalent to -\fBfee_proportional_millionths\fR)\. +\fBdelay\fR (u32): The number of blocks delay required by \fIsource\fR to use this channel .IP \[bu] -\fIdelay\fR : The number of blocks of additional delay required when -forwarding an HTLC in this direction\. (BOLT #7; equivalent to -\fBcltv_expiry_delta\fR)\. +\fBhtlc_minimum_msat\fR (msat): The smallest payment \fIsource\fR will allow via this channel .IP \[bu] -\fIhtlc_minimum_msat\fR : The minimum payment which can be sent -through this channel\. +\fBfeatures\fR (hex): BOLT #9 features bitmap for this channel .IP \[bu] -\fIhtlc_maximum_msat\fR : The maximum payment which can be sent -through this channel\. +\fBhtlc_maximum_msat\fR (msat, optional): The largest payment \fIsource\fR will allow via this channel .RE @@ -117,4 +93,4 @@ BOLT #7: \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md\fR .RE -\" SHA256STAMP:c7c5d846dc08733728bbc358394da54c2d90b0d31633bdd2df48e89d46c359c0 +\" SHA256STAMP:e228d4a2553ac8fc052fd0c3acfac32cdce6f0cfd37f1bb238a87de2fa99e553 diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md index 4ba7aa2dcb4a..3b4835d444a7 100644 --- a/doc/lightning-listchannels.7.md +++ b/doc/lightning-listchannels.7.md @@ -26,43 +26,23 @@ broadcast on the gossip network. RETURN VALUE ------------ -On success, an object with a "channels" key is returned containing a -list of 0 or more objects. - -Each object in the list contains the following data: -- *source* : The node providing entry to the channel, specifying the -fees charged for using the channel in that direction. -- *destination* : The node providing the exit point for the channel. -- *short\_channel\_id* : The channel identifier. -- *public* : Boolean value, is publicly available. Non-local channels -will only ever have this value set to true. Local channels are -side-loaded by this node, rather than obtained through the gossip -network, and so may have this value set to false. -- *satoshis* : Funds available in the channel. -- *amount\_sat* : Same as above, but ending in *sat*. -- *message\_flags* : Bitfield showing the presence of optional fields -in the *channel\_update* message (BOLT \#7). -- *channel\_flags* : Bitfields indicating the direction of the channel -and signaling various options concerning the channel. (BOLT \#7). -- *active* : Boolean value, is available for routing. This is linked -to the channel flags data, where if the second bit is set, signals a -channels temporary unavailability (due to loss of connectivity) OR -permanent unavailability where the channel has been closed but not -settlement on-chain. -- *last\_update* : Unix timestamp (seconds) showing when the last -channel\_update message was received. -- *base\_fee\_millisatoshi* : The base fee (in millisatoshi) charged -for the HTLC (BOLT \#7; equivalent to `fee_base_msat`). -- *fee\_per\_millionth* : The amount (in millionths of a satoshi) -charged per transferred satoshi (BOLT \#7; equivalent to -`fee_proportional_millionths`). -- *delay* : The number of blocks of additional delay required when -forwarding an HTLC in this direction. (BOLT \#7; equivalent to -`cltv_expiry_delta`). -- *htlc\_minimum\_msat* : The minimum payment which can be sent -through this channel. -- *htlc\_maximum\_msat* : The maximum payment which can be sent -through this channel. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **channels** is returned. It is an array of objects, where each object contains: +- **source** (pubkey): the source node +- **destination** (pubkey): the destination node +- **public** (boolean): true if this is announced (otherwise it must be our channel) +- **amount_msat** (msat): the total capacity of this channel (always a whole number of satoshis) +- **message_flags** (u8): as defined by BOLT #7 +- **channel_flags** (u8): as defined by BOLT #7 +- **active** (boolean): true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing +- **last_update** (u32): UNIX timestamp on the last channel_update from *source* +- **base_fee_millisatoshi** (u32): Base fee changed by *source* to use this channel +- **fee_per_millionth** (u32): Proportional fee changed by *source* to use this channel, in parts-per-million +- **delay** (u32): The number of blocks delay required by *source* to use this channel +- **htlc_minimum_msat** (msat): The smallest payment *source* will allow via this channel +- **features** (hex): BOLT #9 features bitmap for this channel +- **htlc_maximum_msat** (msat, optional): The largest payment *source* will allow via this channel +[comment]: # (GENERATE-FROM-SCHEMA-END) If *short\_channel\_id* or *source* is supplied and no matching channels are found, a "channels" object with an empty list is returned. @@ -92,3 +72,4 @@ Lightning RFC site - BOLT \#7: +[comment]: # ( SHA256STAMP:b24b9cef75bf6809a85ee5ff9b821ffad68d012dc58b514844675c63c469488e) diff --git a/doc/lightning-listconfigs.7 b/doc/lightning-listconfigs.7 index 771a04504ca7..851004c8bdd0 100644 --- a/doc/lightning-listconfigs.7 +++ b/doc/lightning-listconfigs.7 @@ -9,6 +9,10 @@ lightning-listconfigs - Command to list all configuration options\. The \fBlistconfigs\fR RPC command to list all configuration options, or with \fIconfig\fR, just that one\. + +The returned values reflect the current configuration, including +showing default values (\fBdev-\fR options are not shown)\. + .SH EXAMPLE JSON REQUEST .nf .RS @@ -24,30 +28,129 @@ The \fBlistconfigs\fR RPC command to list all configuration options, or with \fI .fi .SH RETURN VALUE -On success, an object is returned with members reflecting the -corresponding \fBlightningd-config\fR(5) options which were specified in -the configuration file(s) and command line\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fB# version\fR (string, optional): Special field indicating the current version +.IP \[bu] +\fBplugins\fR (array of objects, optional): +.RS +.IP \[bu] +\fBpath\fR (string): Full path of the plugin +.IP \[bu] +\fBname\fR (string): short name of the plugin +.IP \[bu] +\fBoptions\fR (object, optional): Specific options set for this plugin: -Additional members include: +.RE +.IP \[bu] +\fBimportant-plugins\fR (array of objects, optional): .RS .IP \[bu] -\fI# version\fR: A string that represents the version of node\. +\fBpath\fR (string): Full path of the plugin .IP \[bu] -\fIplugins\fR: A array that represents the non-important plugin registered\. Each object contains the following members: -.RS +\fBname\fR (string): short name of the plugin .IP \[bu] -\fIpath\fR: A string that represents the path of plugin\. +\fBoptions\fR (object, optional): Specific options set for this plugin: + +.RE + .IP \[bu] -\fIname\fR: A string that represents the name of plugin\. +\fBconf\fR (string, optional): \fBconf\fR field from cmdline, or default .IP \[bu] -\fIoptions\fR: A object that contains all options accepted from command line or configuration file, if the plugin has opitions +\fBlightning-dir\fR (string, optional): \fBlightning-dir\fR field from config or cmdline, or default +.IP \[bu] +\fBnetwork\fR (string, optional): \fBnetwork\fR field from config or cmdline, or default +.IP \[bu] +\fBallow-deprecated-apis\fR (boolean, optional): \fBallow-deprecated-apis\fR field from config or cmdline, or default +.IP \[bu] +\fBrpc-file\fR (string, optional): \fBrpc-file\fR field from config or cmdline, or default +.IP \[bu] +\fBdisable-plugin\fR (array of strings, optional): +.RS +.IP \[bu] +\fBdisable-plugin\fR field from config or cmdline .RE .IP \[bu] -\fIimportant-plugins\fR: An array that represents all important plugins registered to the node\. Each object contains the same members as the \fIplugin\fR array\. +\fBalways-use-proxy\fR (boolean, optional): \fBalways-use-proxy\fR field from config or cmdline, or default +.IP \[bu] +\fBdaemon\fR (boolean, optional): \fBdaemon\fR field from config or cmdline, or default +.IP \[bu] +\fBwallet\fR (string, optional): \fBwallet\fR field from config or cmdline, or default +.IP \[bu] +\fBlarge-channels\fR (boolean, optional): \fBlarge-channels\fR field from config or cmdline, or default +.IP \[bu] +\fBexperimental-dual-fund\fR (boolean, optional): \fBexperimental-dual-fund\fR field from config or cmdline, or default +.IP \[bu] +\fBexperimental-onion-messages\fR (boolean, optional): \fBexperimental-onion-messages\fR field from config or cmdline, or default +.IP \[bu] +\fBexperimental-offers\fR (boolean, optional): \fBexperimental-offers\fR field from config or cmdline, or default +.IP \[bu] +\fBexperimental-shutdown-wrong-funding\fR (boolean, optional): \fBexperimental-shutdown-wrong-funding\fR field from config or cmdline, or default +.IP \[bu] +\fBrgb\fR (hex, optional): \fBrgb\fR field from config or cmdline, or default (always 6 characters) +.IP \[bu] +\fBalias\fR (string, optional): \fBalias\fR field from config or cmdline, or default +.IP \[bu] +\fBpid-file\fR (string, optional): \fBpid-file\fR field from config or cmdline, or default +.IP \[bu] +\fBignore-fee-limits\fR (boolean, optional): \fBignore-fee-limits\fR field from config or cmdline, or default +.IP \[bu] +\fBwatchtime-blocks\fR (u32, optional): \fBwatchtime-blocks\fR field from config or cmdline, or default +.IP \[bu] +\fBmax-locktime-blocks\fR (u32, optional): \fBmax-locktime-blocks\fR field from config or cmdline, or default +.IP \[bu] +\fBfunding-confirms\fR (u32, optional): \fBfunding-confirms\fR field from config or cmdline, or default +.IP \[bu] +\fBcltv-delta\fR (u32, optional): \fBcltv-delta\fR field from config or cmdline, or default +.IP \[bu] +\fBcltv-final\fR (u32, optional): \fBcltv-final\fR field from config or cmdline, or default +.IP \[bu] +\fBcommit-time\fR (u32, optional): \fBcommit-time\fR field from config or cmdline, or default +.IP \[bu] +\fBfee-base\fR (u32, optional): \fBfee-base\fR field from config or cmdline, or default +.IP \[bu] +\fBrescan\fR (integer, optional): \fBrescan\fR field from config or cmdline, or default +.IP \[bu] +\fBfee-per-satoshi\fR (u32, optional): \fBfee-per-satoshi\fR field from config or cmdline, or default +.IP \[bu] +\fBmax-concurrent-htlcs\fR (u32, optional): \fBmax-concurrent-htlcs\fR field from config or cmdline, or default +.IP \[bu] +\fBmin-capacity-sat\fR (u64, optional): \fBmin-capacity-sat\fR field from config or cmdline, or default +.IP \[bu] +\fBaddr\fR (string, optional): \fBaddr\fR field from config or cmdline (can be more than one) +.IP \[bu] +\fBannounce-addr\fR (string, optional): \fBannounce-addr\fR field from config or cmdline (can be more than one) +.IP \[bu] +\fBbind-addr\fR (string, optional): \fBbind-addr\fR field from config or cmdline (can be more than one) +.IP \[bu] +\fBoffline\fR (boolean, optional): \fBtrue\fR if \fBoffline\fR was set in config or cmdline +.IP \[bu] +\fBautolisten\fR (boolean, optional): \fBautolisten\fR field from config or cmdline, or default +.IP \[bu] +\fBproxy\fR (string, optional): \fBproxy\fR field from config or cmdline, or default +.IP \[bu] +\fBdisable-dns\fR (boolean, optional): \fBtrue\fR if \fBdisable-dns\fR was set in config or cmdline +.IP \[bu] +\fBencrypted-hsm\fR (boolean, optional): \fBtrue\fR if \fBencrypted-hsm\fR was set in config or cmdline +.IP \[bu] +\fBrpc-file-mode\fR (string, optional): \fBrpc-file-mode\fR field from config or cmdline, or default +.IP \[bu] +\fBlog-level\fR (string, optional): \fBlog-level\fR field from config or cmdline, or default +.IP \[bu] +\fBlog-prefix\fR (string, optional): \fBlog-prefix\fR field from config or cmdline, or default +.IP \[bu] +\fBlog-file\fR (string, optional): \fBlog-file\fR field from config or cmdline, or default +.IP \[bu] +\fBlog-timestamps\fR (boolean, optional): \fBlog-timestamps\fR field from config or cmdline, or default +.IP \[bu] +\fBsubdaemon\fR (string, optional): \fBsubdaemon\fR fields from config or cmdline if any (can be more than one) +.IP \[bu] +\fBtor-service-password\fR (string, optional): \fBtor-service-password\fR field from config or cmdline, if any .RE @@ -165,4 +268,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:19542af1d9c13e31ec6fada46f85a080433c2c7a863779a8b9e3ac86a5903b48 +\" SHA256STAMP:f813a777c6e074907980797dafd798a48633469a59e1ac526e2581e2b1a14c83 diff --git a/doc/lightning-listconfigs.7.md b/doc/lightning-listconfigs.7.md index 1f01658f2e32..a3351bdd72cd 100644 --- a/doc/lightning-listconfigs.7.md +++ b/doc/lightning-listconfigs.7.md @@ -11,6 +11,9 @@ DESCRIPTION The **listconfigs** RPC command to list all configuration options, or with *config*, just that one. +The returned values reflect the current configuration, including +showing default values (`dev-` options are not shown). + EXAMPLE JSON REQUEST -------------------- @@ -27,18 +30,64 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, an object is returned with members reflecting the -corresponding lightningd-config(5) options which were specified in -the configuration file(s) and command line. - -Additional members include: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **# version** (string, optional): Special field indicating the current version +- **plugins** (array of objects, optional): + - **path** (string): Full path of the plugin + - **name** (string): short name of the plugin + - **options** (object, optional): Specific options set for this plugin: +- **important-plugins** (array of objects, optional): + - **path** (string): Full path of the plugin + - **name** (string): short name of the plugin + - **options** (object, optional): Specific options set for this plugin: +- **conf** (string, optional): `conf` field from cmdline, or default +- **lightning-dir** (string, optional): `lightning-dir` field from config or cmdline, or default +- **network** (string, optional): `network` field from config or cmdline, or default +- **allow-deprecated-apis** (boolean, optional): `allow-deprecated-apis` field from config or cmdline, or default +- **rpc-file** (string, optional): `rpc-file` field from config or cmdline, or default +- **disable-plugin** (array of strings, optional): + - `disable-plugin` field from config or cmdline +- **always-use-proxy** (boolean, optional): `always-use-proxy` field from config or cmdline, or default +- **daemon** (boolean, optional): `daemon` field from config or cmdline, or default +- **wallet** (string, optional): `wallet` field from config or cmdline, or default +- **large-channels** (boolean, optional): `large-channels` field from config or cmdline, or default +- **experimental-dual-fund** (boolean, optional): `experimental-dual-fund` field from config or cmdline, or default +- **experimental-onion-messages** (boolean, optional): `experimental-onion-messages` field from config or cmdline, or default +- **experimental-offers** (boolean, optional): `experimental-offers` field from config or cmdline, or default +- **experimental-shutdown-wrong-funding** (boolean, optional): `experimental-shutdown-wrong-funding` field from config or cmdline, or default +- **rgb** (hex, optional): `rgb` field from config or cmdline, or default (always 6 characters) +- **alias** (string, optional): `alias` field from config or cmdline, or default +- **pid-file** (string, optional): `pid-file` field from config or cmdline, or default +- **ignore-fee-limits** (boolean, optional): `ignore-fee-limits` field from config or cmdline, or default +- **watchtime-blocks** (u32, optional): `watchtime-blocks` field from config or cmdline, or default +- **max-locktime-blocks** (u32, optional): `max-locktime-blocks` field from config or cmdline, or default +- **funding-confirms** (u32, optional): `funding-confirms` field from config or cmdline, or default +- **cltv-delta** (u32, optional): `cltv-delta` field from config or cmdline, or default +- **cltv-final** (u32, optional): `cltv-final` field from config or cmdline, or default +- **commit-time** (u32, optional): `commit-time` field from config or cmdline, or default +- **fee-base** (u32, optional): `fee-base` field from config or cmdline, or default +- **rescan** (integer, optional): `rescan` field from config or cmdline, or default +- **fee-per-satoshi** (u32, optional): `fee-per-satoshi` field from config or cmdline, or default +- **max-concurrent-htlcs** (u32, optional): `max-concurrent-htlcs` field from config or cmdline, or default +- **min-capacity-sat** (u64, optional): `min-capacity-sat` field from config or cmdline, or default +- **addr** (string, optional): `addr` field from config or cmdline (can be more than one) +- **announce-addr** (string, optional): `announce-addr` field from config or cmdline (can be more than one) +- **bind-addr** (string, optional): `bind-addr` field from config or cmdline (can be more than one) +- **offline** (boolean, optional): `true` if `offline` was set in config or cmdline +- **autolisten** (boolean, optional): `autolisten` field from config or cmdline, or default +- **proxy** (string, optional): `proxy` field from config or cmdline, or default +- **disable-dns** (boolean, optional): `true` if `disable-dns` was set in config or cmdline +- **encrypted-hsm** (boolean, optional): `true` if `encrypted-hsm` was set in config or cmdline +- **rpc-file-mode** (string, optional): `rpc-file-mode` field from config or cmdline, or default +- **log-level** (string, optional): `log-level` field from config or cmdline, or default +- **log-prefix** (string, optional): `log-prefix` field from config or cmdline, or default +- **log-file** (string, optional): `log-file` field from config or cmdline, or default +- **log-timestamps** (boolean, optional): `log-timestamps` field from config or cmdline, or default +- **subdaemon** (string, optional): `subdaemon` fields from config or cmdline if any (can be more than one) +- **tor-service-password** (string, optional): `tor-service-password` field from config or cmdline, if any +[comment]: # (GENERATE-FROM-SCHEMA-END) -- *# version*: A string that represents the version of node. -- *plugins*: A array that represents the non-important plugin registered. Each object contains the following members: - - *path*: A string that represents the path of plugin. - - *name*: A string that represents the name of plugin. - - *options*: A object that contains all options accepted from command line or configuration file, if the plugin has opitions -- *important-plugins*: An array that represents all important plugins registered to the node. Each object contains the same members as the *plugin* array. On failure, one of the following error codes may be returned: @@ -154,3 +203,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:3c3f2cd354ef5b33ad34febd29b04b1861c62d545c6a5b9181eb2b2b3880258f) diff --git a/doc/lightning-listforwards.7 b/doc/lightning-listforwards.7 index 93a8b346c28b..795e5249adf9 100644 --- a/doc/lightning-listforwards.7 +++ b/doc/lightning-listforwards.7 @@ -20,51 +20,49 @@ on the given in/out channel are returned\. .SH RETURN VALUE -On success one array will be returned: \fIforwards\fR with htlcs that have -been processed - - -Each entry in \fIforwards\fR will include: +On success, an object containing \fBforwards\fR is returned\. It is an array of objects, where each object contains: .RS .IP \[bu] -\fIin_channel\fR: the short_channel_id of the channel that recieved the incoming htlc\. +\fBin_channel\fR (short_channel_id): the channel that received the HTLC +.IP \[bu] +\fBin_msat\fR (msat): the value of the incoming HTLC .IP \[bu] -\fIin_msatoshi\fR, \fIin_msat\fR - amount of msatoshis that are forwarded to this node\. +\fBstatus\fR (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed") .IP \[bu] -\fIstatus\fR: status can be either \fIoffered\fR if the routing process is still ongoing, -\fIsettled\fR if the routing process is completed or \fIfailed\fR if the routing process could not be completed\. +\fBreceived_time\fR (number): the UNIX timestamp when this was received .IP \[bu] -\fIreceived_time\fR: timestamp when incoming htlc was received\. +\fBout_channel\fR (short_channel_id, optional): the channel that the HTLC was forwarded to +.IP \[bu] +\fBpayment_hash\fR (hex, optional): payment hash sought by HTLC (always 64 characters) .RE -The following additional fields are usually present, but will not be for some -variants of status \fIlocal_failed\fR (if it failed before we determined these): +If \fBout_channel\fR is present: .RS .IP \[bu] -\fIout_channel\fR: the short_channel_id of to which the outgoing htlc is supposed to be forwarded\. -.IP \[bu] -\fIfee\fR, \fIfee_msat\fR: fee offered for forwarding the htlc in msatoshi\. +\fBfee_msat\fR (msat): the amount this paid in fees .IP \[bu] -\fIout_msatoshi\fR, \fIout_msat\fR - amount of msatoshis to be forwarded\. +\fBout_msat\fR (msat): the amount we sent out the \fIout_channel\fR .RE -The following fields may be offered, but for old forgotten HTLCs they will be omitted: +If \fBstatus\fR is "settled" or "failed": .RS .IP \[bu] -\fIpayment_hash\fR - the payment_hash belonging to the HTLC\. +\fBresolved_time\fR (number): the UNIX timestamp when this was resolved .RE -If the status is not 'offered', the following additional fields are present: +If \fBstatus\fR is "local_failed" or "failed": .RS .IP \[bu] -\fIresolved_time\fR - timestamp when htlc was resolved (settled or failed)\. +\fBfailcode\fR (u32, optional): the numeric onion code returned +.IP \[bu] +\fBfailreason\fR (string, optional): the name of the onion code returned .RE .SH AUTHOR @@ -79,4 +77,4 @@ Rene Pickhardt \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:b374dbf5f639ad8782b4ad2ff515f25b22a4407ef77f2e0904c975d1a7ccfbe4 +\" SHA256STAMP:d4a2dabe17b640041d019e82549c8cd5492e9c00ccec544b9bf80ff0f2c68ad0 diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md index 83f362ef201b..f69fc04cf53e 100644 --- a/doc/lightning-listforwards.7.md +++ b/doc/lightning-listforwards.7.md @@ -21,30 +21,26 @@ on the given in/out channel are returned. RETURN VALUE ------------ -On success one array will be returned: *forwards* with htlcs that have -been processed - -Each entry in *forwards* will include: -- *in\_channel*: the short\_channel\_id of the channel that recieved the incoming htlc. -- *in\_msatoshi*, *in\_msat* - amount of msatoshis that are forwarded to this node. -- *status*: status can be either *offered* if the routing process is still ongoing, -*settled* if the routing process is completed or *failed* if the routing process could not be completed. -- *received\_time*: timestamp when incoming htlc was received. - -The following additional fields are usually present, but will not be for some -variants of status *local\_failed* (if it failed before we determined these): - -- *out\_channel*: the short\_channel\_id of to which the outgoing htlc is supposed to be forwarded. -- *fee*, *fee\_msat*: fee offered for forwarding the htlc in msatoshi. -- *out\_msatoshi*, *out\_msat* - amount of msatoshis to be forwarded. - -The following fields may be offered, but for old forgotten HTLCs they will be omitted: - -- *payment\_hash* - the payment_hash belonging to the HTLC. - -If the status is not 'offered', the following additional fields are present: - -- *resolved\_time* - timestamp when htlc was resolved (settled or failed). +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **forwards** is returned. It is an array of objects, where each object contains: +- **in_channel** (short_channel_id): the channel that received the HTLC +- **in_msat** (msat): the value of the incoming HTLC +- **status** (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed") +- **received_time** (number): the UNIX timestamp when this was received +- **out_channel** (short_channel_id, optional): the channel that the HTLC was forwarded to +- **payment_hash** (hex, optional): payment hash sought by HTLC (always 64 characters) + +If **out_channel** is present: + - **fee_msat** (msat): the amount this paid in fees + - **out_msat** (msat): the amount we sent out the *out_channel* + +If **status** is "settled" or "failed": + - **resolved_time** (number): the UNIX timestamp when this was resolved + +If **status** is "local_failed" or "failed": + - **failcode** (u32, optional): the numeric onion code returned + - **failreason** (string, optional): the name of the onion code returned +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -61,3 +57,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:d2fe60f5039f5ad4682c88ce88d513c0ad74d8d4967dd233b399a19e27aac2ee) diff --git a/doc/lightning-listfunds.7 b/doc/lightning-listfunds.7 index 7d4972294c4a..1c3b0822bf1d 100644 --- a/doc/lightning-listfunds.7 +++ b/doc/lightning-listfunds.7 @@ -17,69 +17,85 @@ in addition to the unspent ones\. Default is false\. .SH RETURN VALUE -On success two arrays will be returned: \fIoutputs\fR with funds currently -locked onchain in UTXOs and \fIchannels\fR with funds readily spendable in -channels\. +On success, an object is returned, containing: +.RS +.IP \[bu] -Each entry in \fIoutputs\fR will include: +\fBoutputs\fR (array of objects): .RS .IP \[bu] -\fItxid\fR -.IP \[bu] -\fIoutput\fR (the index of the output in the transaction) -.IP \[bu] -\fIvalue\fR (the output value in satoshis) +\fBtxid\fR (txid): the ID of the spendable transaction .IP \[bu] -\fIamount_msat\fR (the same as \fIvalue\fR, but in millisatoshi with \fImsat\fR -appended) +\fBoutput\fR (u32): the index within \fItxid\fR .IP \[bu] -\fIaddress\fR +\fBamount_msat\fR (msat): the amount of the output .IP \[bu] -\fIscriptpubkey\fR (the ScriptPubkey of the output, in hex) +\fBscriptpubkey\fR (hex): the scriptPubkey of the output .IP \[bu] -\fIredeemscript\fR (the redeemscript of the output, in hex, only if it's p2sh-wrapped) +\fBstatus\fR (string) (one of "unconfirmed", "confirmed", "spent") .IP \[bu] -\fIstatus\fR (whether \fIunconfirmed\fR, \fIconfirmed\fR, or \fIspent\fR) +\fBaddress\fR (string, optional): the bitcoin address of the output .IP \[bu] -\fIreserved\fR (whether this is UTXO is currently reserved for an in-flight tx) +\fBredeemscript\fR (hex, optional): the redeemscript, only if it's p2sh-wrapped + +.RE + +If \fBstatus\fR is "confirmed": + +.RS .IP \[bu] -\fIreserved_to_block\fR (when reservation expires, if \fIreserved\fR is true) +\fBblockheight\fR (u32): Block height where it was confirmed .RE -Each entry in \fIchannels\fR will include: +If \fBreserved\fR is "true": .RS .IP \[bu] -\fIpeer_id\fR - the peer with which the channel is opened\. +\fBreserved_to_block\fR (u32): Block height where reservation will expire + +.RE + .IP \[bu] -\fIshort_channel_id\fR - as per BOLT 7 (representing the block, -transaction number and output index of the channel funding -transaction)\. + +\fBchannels\fR (array of objects): + +.RS .IP \[bu] -\fIchannel_sat\fR - available satoshis on our node’s end of the channel -(values rounded down to satoshis as internal storage is in -millisatoshi)\. +\fBpeer_id\fR (pubkey): the peer with which the channel is opened .IP \[bu] -\fIour_amount_msat\fR - same as above, but in millisatoshis with -\fImsat\fR appended\. +\fBour_amount_msat\fR (msat): available satoshis on our node’s end of the channel .IP \[bu] -\fIchannel_total_sat\fR - total channel value in satoshi +\fBamount_msat\fR (msat): total channel value .IP \[bu] -\fIamount_msat\fR - same as above, but in millisatoshis with \fImsat\fR -appended\. +\fBfunding_txid\fR (txid): funding transaction id .IP \[bu] -\fIfunding_txid\fR - funding transaction id\. +\fBfunding_output\fR (u32): the 0-based index of the output in the funding transaction .IP \[bu] -\fIfunding_output\fR - the index of the output in the funding -transaction\. +\fBconnected\fR (boolean): whether the channel peer is connected .IP \[bu] -\fIconnected\fR - whether the channel peer is connected\. +\fBstate\fR (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + +.RE + +If \fBstate\fR is "CHANNELD_NORMAL": + +.RS +.IP \[bu] +\fBshort_channel_id\fR (short_channel_id): short channel id of channel + +.RE + +If \fBstate\fR is "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN" or "ONCHAIN": + +.RS .IP \[bu] -\fIstate\fR - the channel state, in particular \fICHANNELD_NORMAL\fR means the -channel can be used normally\. +\fBshort_channel_id\fR (short_channel_id, optional): short channel id of channel (only if funding reached lockin depth before closing) + +.RE + .RE .SH AUTHOR @@ -94,4 +110,4 @@ Felix \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d1566362ec4c99ec904f03569ccc99306a42414dc682fd88ca1a3dcb8616de53 +\" SHA256STAMP:0df04d09e7e7d3344a64f0ecd03186d1499014346d4c37c0d08390328f1f8f04 diff --git a/doc/lightning-listfunds.7.md b/doc/lightning-listfunds.7.md index 73e788d959f2..50f4d5f8e480 100644 --- a/doc/lightning-listfunds.7.md +++ b/doc/lightning-listfunds.7.md @@ -19,42 +19,37 @@ in addition to the unspent ones. Default is false. RETURN VALUE ------------ -On success two arrays will be returned: *outputs* with funds currently -locked onchain in UTXOs and *channels* with funds readily spendable in -channels. - -Each entry in *outputs* will include: -- *txid* -- *output* (the index of the output in the transaction) -- *value* (the output value in satoshis) -- *amount\_msat* (the same as *value*, but in millisatoshi with *msat* - appended) -- *address* -- *scriptpubkey* (the ScriptPubkey of the output, in hex) -- *redeemscript* (the redeemscript of the output, in hex, only if it's p2sh-wrapped) -- *status* (whether *unconfirmed*, *confirmed*, or *spent*) -- *reserved* (whether this is UTXO is currently reserved for an in-flight tx) -- *reserved_to_block* (when reservation expires, if *reserved* is true) - -Each entry in *channels* will include: -- *peer\_id* - the peer with which the channel is opened. -- *short\_channel\_id* - as per BOLT 7 (representing the block, - transaction number and output index of the channel funding - transaction). -- *channel\_sat* - available satoshis on our node’s end of the channel - (values rounded down to satoshis as internal storage is in - millisatoshi). -- *our\_amount\_msat* - same as above, but in millisatoshis with - *msat* appended. -- *channel\_total\_sat* - total channel value in satoshi -- *amount\_msat* - same as above, but in millisatoshis with *msat* - appended. -- *funding\_txid* - funding transaction id. -- *funding\_output* - the index of the output in the funding - transaction. -- *connected* - whether the channel peer is connected. -- *state* - the channel state, in particular *CHANNELD_NORMAL* means the - channel can be used normally. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **outputs** (array of objects): + - **txid** (txid): the ID of the spendable transaction + - **output** (u32): the index within *txid* + - **amount_msat** (msat): the amount of the output + - **scriptpubkey** (hex): the scriptPubkey of the output + - **status** (string) (one of "unconfirmed", "confirmed", "spent") + - **address** (string, optional): the bitcoin address of the output + - **redeemscript** (hex, optional): the redeemscript, only if it's p2sh-wrapped + + If **status** is "confirmed": + - **blockheight** (u32): Block height where it was confirmed + + If **reserved** is "true": + - **reserved_to_block** (u32): Block height where reservation will expire +- **channels** (array of objects): + - **peer_id** (pubkey): the peer with which the channel is opened + - **our_amount_msat** (msat): available satoshis on our node’s end of the channel + - **amount_msat** (msat): total channel value + - **funding_txid** (txid): funding transaction id + - **funding_output** (u32): the 0-based index of the output in the funding transaction + - **connected** (boolean): whether the channel peer is connected + - **state** (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + + If **state** is "CHANNELD_NORMAL": + - **short_channel_id** (short_channel_id): short channel id of channel + + If **state** is "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN" or "ONCHAIN": + - **short_channel_id** (short_channel_id, optional): short channel id of channel (only if funding reached lockin depth before closing) +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -71,3 +66,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:878fab92cc95fdb4680c13f3a2d791e9bbaac3ea732608ece65e684428f7705a) diff --git a/doc/lightning-listinvoices.7 b/doc/lightning-listinvoices.7 index 45ef8486dd4d..8e5c03519518 100644 --- a/doc/lightning-listinvoices.7 +++ b/doc/lightning-listinvoices.7 @@ -18,19 +18,41 @@ query parameters can be used at once\. .SH RETURN VALUE -On success, an array \fIinvoices\fR of objects is returned\. Each object contains -\fIlabel\fR, \fIdescription\fR, \fIpayment_hash\fR, \fIstatus\fR (one of \fIunpaid\fR, \fIpaid\fR or \fIexpired\fR), -\fIpayment_preimage\fR (for paid invoices), and \fIexpires_at\fR (a UNIX -timestamp)\. If the \fImsatoshi\fR argument to \fBlightning-invoice\fR(7) was not "any", -there will be an \fImsatoshi\fR field as a number, and \fIamount_msat\fR as the same -number ending in \fImsat\fR\. If the invoice was created with a bolt11 string, -there will be a \fIbolt11\fR field\. -If the invoice \fIstatus\fR is \fIpaid\fR, there will be a -\fIpay_index\fR field and an \fImsatoshi_received\fR field (which may be slightly -greater than \fImsatoshi\fR as some overpaying is permitted to allow clients to -obscure payment paths); there will also be an \fIamount_received_msat\fR field -with the same number as \fImsatoshi_received\fR but ending in \fImsat\fR\. +On success, an object containing \fBinvoices\fR is returned\. It is an array of objects, where each object contains: +.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] +\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 .SH AUTHOR Rusty Russell \fI is mainly responsible\. @@ -43,4 +65,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:3d3cef4fa52635fa5c515959718e017173c3fffdc32ca7066fea3b82cf93758d +\" SHA256STAMP:1ac6fb88dc05d683e81dc951a593d88027310b9c62dd81c57e134238994b0562 diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md index e78aa40ce3c8..5f772cddac9c 100644 --- a/doc/lightning-listinvoices.7.md +++ b/doc/lightning-listinvoices.7.md @@ -20,18 +20,23 @@ query parameters can be used at once. RETURN VALUE ------------ -On success, an array *invoices* of objects is returned. Each object contains -*label*, *description*, *payment\_hash*, *status* (one of *unpaid*, *paid* or *expired*), -*payment\_preimage* (for paid invoices), and *expires\_at* (a UNIX -timestamp). If the *msatoshi* argument to lightning-invoice(7) was not "any", -there will be an *msatoshi* field as a number, and *amount\_msat* as the same -number ending in *msat*. If the invoice was created with a bolt11 string, -there will be a *bolt11* field. -If the invoice *status* is *paid*, there will be a -*pay\_index* field and an *msatoshi\_received* field (which may be slightly -greater than *msatoshi* as some overpaying is permitted to allow clients to -obscure payment paths); there will also be an *amount\_received\_msat* field -with the same number as *msatoshi\_received* but ending in *msat*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **invoices** is returned. It is an array of objects, where each object contains: +- **label** (string): unique label supplied at invoice creation +- **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 +- **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) AUTHOR ------ @@ -48,3 +53,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:67ff5d9aa945301f23d6694304e4b657a37f0b3f80cc1c13c2ff23a55fe51d4b) diff --git a/doc/lightning-listnodes.7 b/doc/lightning-listnodes.7 index a80ef7b13715..a7bd42638bad 100644 --- a/doc/lightning-listnodes.7 +++ b/doc/lightning-listnodes.7 @@ -24,35 +24,34 @@ The \fBlistnodes\fR command returns nodes the node has learned about via gossip .fi .SH RETURN VALUE -On success, the command will return a list of nodes, each object represents a node, with the following details: +On success, an object containing \fBnodes\fR is returned\. It is an array of objects, where each object contains: .RS .IP \[bu] -\fInodeid\fR: A string that represents the node id\. +\fBnodeid\fR (pubkey): the public key of the node +.IP \[bu] +\fBlast_update\fR (u32, optional): A node_announcement has been received for this node (UNIX timestamp) .RE -For nodes which have sent a node_announcement message, the following -are also returned: +If \fBlast_update\fR is present: .RS .IP \[bu] -\fIalias\fR: A string that represents alias of the node on the network\. -.IP \[bu] -\fIcolor\fR: A string that represents the personal color of the node\. +\fBalias\fR (string): The fun alias this node advertized (up to 32 characters) .IP \[bu] -\fIlast_timestamp\fR: An integer that represents the timestamp of the last-received node_announcement message\. +\fBcolor\fR (hex): The favorite RGB color this node advertized (always 6 characters) .IP \[bu] -\fIfeatures\fR: A string that represents the features value\. +\fBfeatures\fR (hex): BOLT #9 features bitmap this node advertized .IP \[bu] -\fIaddresses\fR: An array that represents the addreses avaible\. Each address is represented with an object with the following properties: +\fBaddresses\fR (array of objects): The addresses this node advertized: .RS .IP \[bu] -\fItype\fR: A string that represents the address type (ipv4 or ipv6)\. +\fBtype\fR (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3") .IP \[bu] -\fIaddress\fR: A string that represents the address value\. +\fBaddress\fR (string): address in expected format for \fItype\fR .IP \[bu] -\fIport\fR: An integer that represents the port number where the node are listening\. +\fBport\fR (u16): port number .RE @@ -102,4 +101,4 @@ FIXME: Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:901b147ccbfe0a18310a44ca848b623e83fa3c68912dacadefd045d4a2095523 +\" SHA256STAMP:4366d5c238bccc06cfafc4c2d375dd417049b0b6224f13b2dcc9f25139587649 diff --git a/doc/lightning-listnodes.7.md b/doc/lightning-listnodes.7.md index 333f3f3abc68..356043a1e31d 100644 --- a/doc/lightning-listnodes.7.md +++ b/doc/lightning-listnodes.7.md @@ -26,21 +26,20 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, the command will return a list of nodes, each object represents a node, with the following details: - -- *nodeid*: A string that represents the node id. - -For nodes which have sent a node_announcement message, the following -are also returned: - -- *alias*: A string that represents alias of the node on the network. -- *color*: A string that represents the personal color of the node. -- *last_timestamp*: An integer that represents the timestamp of the last-received node_announcement message. -- *features*: A string that represents the features value. -- *addresses*: An array that represents the addreses avaible. Each address is represented with an object with the following properties: - - *type*: A string that represents the address type (ipv4 or ipv6). - - *address*: A string that represents the address value. - - *port*: An integer that represents the port number where the node are listening. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **nodes** is returned. It is an array of objects, where each object contains: +- **nodeid** (pubkey): the public key of the node +- **last_update** (u32, optional): A node_announcement has been received for this node (UNIX timestamp) + +If **last_update** is present: + - **alias** (string): The fun alias this node advertized (up to 32 characters) + - **color** (hex): The favorite RGB color this node advertized (always 6 characters) + - **features** (hex): BOLT #9 features bitmap this node advertized + - **addresses** (array of objects): The addresses this node advertized: + - **type** (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3") + - **address** (string): address in expected format for *type* + - **port** (u16): port number +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -84,3 +83,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:2f644d55512f5c03e3894341fb039fc1b7d2ebc5f210547fdb324d2f23689b37) diff --git a/doc/lightning-listoffers.7 b/doc/lightning-listoffers.7 index 8f9d2da3409c..383c855cc70e 100644 --- a/doc/lightning-listoffers.7 +++ b/doc/lightning-listoffers.7 @@ -29,27 +29,21 @@ set and is true, only offers with \fBactive\fR true are returned\. .fi .SH RETURN VALUE -On success, an array \fIoffers\fR of objects is returned\. Each object contains: +On success, an object containing \fBoffers\fR is returned\. It is an array of objects, where each object contains: .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 can still be used .IP \[bu] -\fIsingle_use\fR: true if \fIsingle_use\fR was specified\. +\fBsingle_use\fR (boolean): whether this expires as soon as it's paid .IP \[bu] -\fIbolt12\fR: the bolt12 offer, starting with "lno1" +\fBbolt12\fR (string): the bolt12 encoding of the offer .IP \[bu] -\fIused\fR: true if an associated invoice has been paid\. - -.RE - -Optionally: - -.RS +\fBused\fR (boolean): True if an associated invoice has been paid .IP \[bu] -\fIlabel\fR: the user-specified label\. +\fBlabel\fR (string, optional): the (optional) user-specified label .RE .SH EXAMPLE JSON RESPONSE @@ -88,4 +82,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:bc4abe90e5475a272c61af45e4f00be9f3fab89d3adca767b577b46d70d33726 +\" SHA256STAMP:7e359219084e648a629b0d43774db17bbfbe693074b817fa5890b7c8bccd1429 diff --git a/doc/lightning-listoffers.7.md b/doc/lightning-listoffers.7.md index c04536228b4f..b772fb6f4aa8 100644 --- a/doc/lightning-listoffers.7.md +++ b/doc/lightning-listoffers.7.md @@ -29,17 +29,15 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, an array *offers* of objects is returned. Each object contains: - -* *offer_id*: the hash of the offer. -* *active*: true -* *single_use*: true if *single_use* was specified. -* *bolt12*: the bolt12 offer, starting with "lno1" -* *used*: true if an associated invoice has been paid. - -Optionally: -* *label*: the user-specified label. - +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **offers** is returned. It is an array of objects, where each object contains: +- **offer_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) +- **active** (boolean): whether this can still be used +- **single_use** (boolean): whether this expires as soon as it's paid +- **bolt12** (string): the bolt12 encoding of the offer +- **used** (boolean): True if an associated invoice has been paid +- **label** (string, optional): the (optional) user-specified label +[comment]: # (GENERATE-FROM-SCHEMA-END) EXAMPLE JSON RESPONSE ----- @@ -80,3 +78,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:58e9f5aa5808e19e3be151b1c1f1215ec23953b60ab294418aa57426c5bcbd46) diff --git a/doc/lightning-listpays.7 b/doc/lightning-listpays.7 index 672918f16167..4d1eaf8e84a5 100644 --- a/doc/lightning-listpays.7 +++ b/doc/lightning-listpays.7 @@ -74,4 +74,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:4037a4dd9746b5dfc91ef2f5b4fa9000a334689157d9ac86dc4dba5c82628cfe +\" SHA256STAMP:9b593ed02c10b34ae6f36f91963da0a244df0c3963aaa990e7477008fd3af18d diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md index aab53b6c0b1d..788570ba086e 100644 --- a/doc/lightning-listpays.7.md +++ b/doc/lightning-listpays.7.md @@ -54,4 +54,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:12e7b91fc59ee65b61d9aba4e8586fda8fbb524a7e548ffa36862e204952c46b) +[comment]: # ( SHA256STAMP:22b3a2437901da705b706792b9e263ab65e002835ad3f5735895f8d971699c3b) diff --git a/doc/lightning-listpeers.7 b/doc/lightning-listpeers.7 index 04ace1236a24..03d142e8cd7b 100644 --- a/doc/lightning-listpeers.7 +++ b/doc/lightning-listpeers.7 @@ -41,6 +41,302 @@ node will no longer appear in the command output\. .SH RETURN VALUE +On success, an object containing \fBpeers\fR is returned\. It is an array of objects, where each object contains: + +.RS +.IP \[bu] +\fBid\fR (pubkey): the public key of the peer +.IP \[bu] +\fBconnected\fR (boolean): True if the peer is currently connected +.IP \[bu] + +\fBchannels\fR (array of objects): + +.RS +.IP \[bu] +\fBstate\fR (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBopener\fR (string): Who initiated the channel (one of "local", "remote") +.IP \[bu] +\fBfeatures\fR (array of strings): +.RS +.IP \[bu] +BOLT #9 features which apply to this channel (one of "option_static_remotekey", "option_anchor_outputs") + +.RE + +.IP \[bu] +\fBscratch_txid\fR (txid, optional): The txid we would use if we went onchain now +.IP \[bu] +\fBfeerate\fR (object, optional): Feerates for the current tx: +.RS +.IP \[bu] +\fBperkw\fR (u32): Feerate per 1000 weight (i\.e kSipa) +.IP \[bu] +\fBperkb\fR (u32): Feerate per 1000 virtual bytes + +.RE + +.IP \[bu] +\fBowner\fR (string, optional): The current subdaemon controlling this connection +.IP \[bu] +\fBshort_channel_id\fR (short_channel_id, optional): The short_channel_id (once locked in) +.IP \[bu] +\fBchannel_id\fR (hex, optional): The full channel_id (always 64 characters) +.IP \[bu] +\fBfunding_txid\fR (txid, optional): ID of the funding transaction +.IP \[bu] +\fBinflight\fR (array of objects, optional): Current candidate funding transactions (only for dual-funding): +.RS +.IP \[bu] +\fBfunding_txid\fR (txid): ID of the funding transaction +.IP \[bu] +\fBfunding_outnum\fR (u32): The 0-based output number of the funding transaction which opens the channel +.IP \[bu] +\fBfeerate\fR (string): The feerate for this funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBtotal_funding_msat\fR (msat): total amount in the channel +.IP \[bu] +\fBour_funding_msat\fR (msat): amount we have in the channel +.IP \[bu] +\fBscratch_txid\fR (txid): The commitment transaction txid we would use if we went onchain now + +.RE + +.IP \[bu] +\fBclose_to\fR (hex, optional): scriptPubkey which we have to close to if we mutual close +.IP \[bu] +\fBprivate\fR (boolean, optional): if False, we will not announce this channel +.IP \[bu] +\fBcloser\fR (string, optional): Who initiated the channel close (\fBnull\fR is deprecated!) (one of "local", "remote", \fInull\fR) +.IP \[bu] +\fBfunding\fR (object, optional): +.RS +.IP \[bu] +\fBlocal_msat\fR (msat): Amount of channel we funded +.IP \[bu] +\fBremote_msat\fR (msat): Amount of channel they funded + +.RE + +.IP \[bu] +\fBto_us_msat\fR (msat, optional): how much of channel is owed to us +.IP \[bu] +\fBmin_to_us_msat\fR (msat, optional): least amount owed to us ever +.IP \[bu] +\fBmax_to_us_msat\fR (msat, optional): most amount owed to us ever +.IP \[bu] +\fBtotal_msat\fR (msat, optional): total amount in the channel +.IP \[bu] +\fBfee_base_msat\fR (msat, optional): amount we charge to use the channel +.IP \[bu] +\fBfee_proportional_millionths\fR (u32, optional): amount we charge to use the channel in parts-per-million +.IP \[bu] +\fBdust_limit_msat\fR (msat, optional): minimum amount for an output on the channel transactions +.IP \[bu] +\fBmax_total_htlc_in_msat\fR (msat, optional): max amount accept in a single payment +.IP \[bu] +\fBtheir_reserve_msat\fR (msat, optional): minimum we insist they keep in channel +.IP \[bu] +\fBour_reserve_msat\fR (msat, optional): minimum they insist we keep in channel +.IP \[bu] +\fBspendable_msat\fR (msat, optional): total we could send through channel +.IP \[bu] +\fBreceivable_msat\fR (msat, optional): total peer could send through channel +.IP \[bu] +\fBminimum_htlc_in_msat\fR (msat, optional): the minimum amount HTLC we accept +.IP \[bu] +\fBtheir_to_self_delay\fR (u32, optional): the number of blocks before they can take their funds if they unilateral close +.IP \[bu] +\fBour_to_self_delay\fR (u32, optional): the number of blocks before we can take our funds if we unilateral close +.IP \[bu] +\fBmax_accepted_htlcs\fR (u32, optional): Maximum number of incoming HTLC we will accept at once +.IP \[bu] +\fBstate_changes\fR (array of objects, optional): Prior state changes: +.RS +.IP \[bu] +\fBtimestamp\fR (string): UTC timestamp of form YYYY-mm-ddTHH:MM:SS\.%03dZ +.IP \[bu] +\fBold_state\fR (string): Previous state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBnew_state\fR (string): New state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBcause\fR (string): What caused the change (one of "unknown", "local", "user", "remote", "protocol", "onchain") +.IP \[bu] +\fBmessage\fR (string): Human-readable explanation + +.RE + +.IP \[bu] +\fBstatus\fR (array of strings, optional): +.RS +.IP \[bu] +Billboard log of significant changes + +.RE + +.IP \[bu] +\fBin_payments_offered\fR (u64, optional): Number of incoming payment attempts +.IP \[bu] +\fBin_offered_msat\fR (msat, optional): Total amount of incoming payment attempts +.IP \[bu] +\fBin_payments_fulfilled\fR (u64, optional): Number of successful incoming payment attempts +.IP \[bu] +\fBin_fulfilled_msat\fR (msat, optional): Total amount of successful incoming payment attempts +.IP \[bu] +\fBout_payments_offered\fR (u64, optional): Number of outgoing payment attempts +.IP \[bu] +\fBout_offered_msat\fR (msat, optional): Total amount of outgoing payment attempts +.IP \[bu] +\fBout_payments_fulfilled\fR (u64, optional): Number of successful outgoing payment attempts +.IP \[bu] +\fBout_fulfilled_msat\fR (msat, optional): Total amount of successful outgoing payment attempts +.IP \[bu] + +\fBhtlcs\fR (array of objects, optional): current HTLCs in this channel: + +.RS +.IP \[bu] +\fBdirection\fR (string): Whether it came from peer, or is going to peer (one of "in", "out") +.IP \[bu] +\fBid\fR (u64): Unique ID for this htlc on this channel in this direction +.IP \[bu] +\fBamount_msat\fR (msat): Amount send/received for this HTLC +.IP \[bu] +\fBexpiry\fR (u32): Block this HTLC expires at +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the payment_preimage which will prove payment (always 64 characters) +.IP \[bu] +\fBlocal_trimmed\fR (boolean, optional): if this is too small to enforce onchain (always \fItrue\fR) +.IP \[bu] +\fBstatus\fR (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin) + +.RE + +If \fBdirection\fR is "out": + +.RS +.IP \[bu] +\fBstate\fR (string): Status of the HTLC (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION") + +.RE + +If \fBdirection\fR is "in": + +.RS +.IP \[bu] +\fBstate\fR (string): Status of the HTLC (one of "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION") + +.RE + + +.RE + +If \fBclose_to\fR is present: + +.RS +.IP \[bu] +\fBclose_to_addr\fR (string, optional): The bitcoin address we will close to + +.RE + +If \fBscratch_txid\fR is present: + +.RS +.IP \[bu] +\fBlast_tx_fee_msat\fR (msat): fee attached to this the current tx + +.RE + +If \fBshort_channel_id\fR is present: + +.RS +.IP \[bu] +\fBdirection\fR (u32): 0 if we're the lesser node_id, 1 if we're the greater + +.RE + +If \fBinflight\fR is present: + +.RS +.IP \[bu] +\fBinitial_feerate\fR (string): The feerate for the initial funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBlast_feerate\fR (string): The feerate for the latest funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBnext_feerate\fR (string): The minimum feerate for the next funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBnext_feestep\fR (u32, optional): The number of fee steps so far, plus one + +.RE + +.IP \[bu] + +\fBlog\fR (array of objects, optional): if \fIlevel\fR is specified, logs for this peer: + +.RS +.IP \[bu] +\fBtype\fR (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") + +.RE + +If \fBtype\fR is "SKIPPED": + +.RS +.IP \[bu] +\fBnum_skipped\fR (u32): number of deleted/omitted entries + +.RE + +If \fBtype\fR is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + +.RS +.IP \[bu] +\fBtime\fR (string): UNIX timestamp with 9 decimal places +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The actual log message +.IP \[bu] +\fBnode_id\fR (pubkey): The peer this is associated with + +.RE + +If \fBtype\fR is "IO_IN" or "IO_OUT": + +.RS +.IP \[bu] +\fBtime\fR (string): UNIX timestamp with 9 decimal places +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The actual log message +.IP \[bu] +\fBnode_id\fR (pubkey): The peer this is associated with +.IP \[bu] +\fBdata\fR (hex): The IO which occurred + +.RE + + +.RE + +If \fBconnected\fR is \fItrue\fR: + +.RS +.IP \[bu] +\fBnetaddr\fR (array of strings): A single entry array: +.RS +.IP \[bu] +address, e\.g\. 1\.2\.3\.4:1234 + +.RE + +.IP \[bu] +\fBfeatures\fR (hex): bitmap of BOLT #9 features from peer's INIT message + +.RE + On success, an object with a "peers" key is returned containing a list of 0 or more objects\. @@ -342,4 +638,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Lightning RFC site (BOLT #9): \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md\fR -\" SHA256STAMP:1163bde5a9f836ba7bd142559cd3bab893ab3159a99041a88ac8b31556b67905 +\" SHA256STAMP:840f7597143789d88d7e3ef1c3e8a1e50dbee44b4b471f0608433fd60077248e diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md index e97f534a196f..281141a008fc 100644 --- a/doc/lightning-listpeers.7.md +++ b/doc/lightning-listpeers.7.md @@ -38,6 +38,122 @@ node will no longer appear in the command output. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **peers** is returned. It is an array of objects, where each object contains: +- **id** (pubkey): the public key of the peer +- **connected** (boolean): True if the peer is currently connected +- **channels** (array of objects): + - **state** (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **opener** (string): Who initiated the channel (one of "local", "remote") + - **features** (array of strings): + - BOLT #9 features which apply to this channel (one of "option_static_remotekey", "option_anchor_outputs") + - **scratch_txid** (txid, optional): The txid we would use if we went onchain now + - **feerate** (object, optional): Feerates for the current tx: + - **perkw** (u32): Feerate per 1000 weight (i.e kSipa) + - **perkb** (u32): Feerate per 1000 virtual bytes + - **owner** (string, optional): The current subdaemon controlling this connection + - **short_channel_id** (short_channel_id, optional): The short_channel_id (once locked in) + - **channel_id** (hex, optional): The full channel_id (always 64 characters) + - **funding_txid** (txid, optional): ID of the funding transaction + - **inflight** (array of objects, optional): Current candidate funding transactions (only for dual-funding): + - **funding_txid** (txid): ID of the funding transaction + - **funding_outnum** (u32): The 0-based output number of the funding transaction which opens the channel + - **feerate** (string): The feerate for this funding transaction in per-1000-weight, with "kpw" appended + - **total_funding_msat** (msat): total amount in the channel + - **our_funding_msat** (msat): amount we have in the channel + - **scratch_txid** (txid): The commitment transaction txid we would use if we went onchain now + - **close_to** (hex, optional): scriptPubkey which we have to close to if we mutual close + - **private** (boolean, optional): if False, we will not announce this channel + - **closer** (string, optional): Who initiated the channel close (`null` is deprecated!) (one of "local", "remote", *null*) + - **funding** (object, optional): + - **local_msat** (msat): Amount of channel we funded + - **remote_msat** (msat): Amount of channel they funded + - **to_us_msat** (msat, optional): how much of channel is owed to us + - **min_to_us_msat** (msat, optional): least amount owed to us ever + - **max_to_us_msat** (msat, optional): most amount owed to us ever + - **total_msat** (msat, optional): total amount in the channel + - **fee_base_msat** (msat, optional): amount we charge to use the channel + - **fee_proportional_millionths** (u32, optional): amount we charge to use the channel in parts-per-million + - **dust_limit_msat** (msat, optional): minimum amount for an output on the channel transactions + - **max_total_htlc_in_msat** (msat, optional): max amount accept in a single payment + - **their_reserve_msat** (msat, optional): minimum we insist they keep in channel + - **our_reserve_msat** (msat, optional): minimum they insist we keep in channel + - **spendable_msat** (msat, optional): total we could send through channel + - **receivable_msat** (msat, optional): total peer could send through channel + - **minimum_htlc_in_msat** (msat, optional): the minimum amount HTLC we accept + - **their_to_self_delay** (u32, optional): the number of blocks before they can take their funds if they unilateral close + - **our_to_self_delay** (u32, optional): the number of blocks before we can take our funds if we unilateral close + - **max_accepted_htlcs** (u32, optional): Maximum number of incoming HTLC we will accept at once + - **state_changes** (array of objects, optional): Prior state changes: + - **timestamp** (string): UTC timestamp of form YYYY-mm-ddTHH:MM:SS.%03dZ + - **old_state** (string): Previous state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **new_state** (string): New state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **cause** (string): What caused the change (one of "unknown", "local", "user", "remote", "protocol", "onchain") + - **message** (string): Human-readable explanation + - **status** (array of strings, optional): + - Billboard log of significant changes + - **in_payments_offered** (u64, optional): Number of incoming payment attempts + - **in_offered_msat** (msat, optional): Total amount of incoming payment attempts + - **in_payments_fulfilled** (u64, optional): Number of successful incoming payment attempts + - **in_fulfilled_msat** (msat, optional): Total amount of successful incoming payment attempts + - **out_payments_offered** (u64, optional): Number of outgoing payment attempts + - **out_offered_msat** (msat, optional): Total amount of outgoing payment attempts + - **out_payments_fulfilled** (u64, optional): Number of successful outgoing payment attempts + - **out_fulfilled_msat** (msat, optional): Total amount of successful outgoing payment attempts + - **htlcs** (array of objects, optional): current HTLCs in this channel: + - **direction** (string): Whether it came from peer, or is going to peer (one of "in", "out") + - **id** (u64): Unique ID for this htlc on this channel in this direction + - **amount_msat** (msat): Amount send/received for this HTLC + - **expiry** (u32): Block this HTLC expires at + - **payment_hash** (hex): the hash of the payment_preimage which will prove payment (always 64 characters) + - **local_trimmed** (boolean, optional): if this is too small to enforce onchain (always *true*) + - **status** (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin) + + If **direction** is "out": + - **state** (string): Status of the HTLC (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION") + + If **direction** is "in": + - **state** (string): Status of the HTLC (one of "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION") + + If **close_to** is present: + - **close_to_addr** (string, optional): The bitcoin address we will close to + + If **scratch_txid** is present: + - **last_tx_fee_msat** (msat): fee attached to this the current tx + + If **short_channel_id** is present: + - **direction** (u32): 0 if we're the lesser node_id, 1 if we're the greater + + If **inflight** is present: + - **initial_feerate** (string): The feerate for the initial funding transaction in per-1000-weight, with "kpw" appended + - **last_feerate** (string): The feerate for the latest funding transaction in per-1000-weight, with "kpw" appended + - **next_feerate** (string): The minimum feerate for the next funding transaction in per-1000-weight, with "kpw" appended + - **next_feestep** (u32, optional): The number of fee steps so far, plus one +- **log** (array of objects, optional): if *level* is specified, logs for this peer: + - **type** (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") + + If **type** is "SKIPPED": + - **num_skipped** (u32): number of deleted/omitted entries + + If **type** is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + - **time** (string): UNIX timestamp with 9 decimal places + - **source** (string): The particular logbook this was found in + - **log** (string): The actual log message + - **node_id** (pubkey): The peer this is associated with + + If **type** is "IO_IN" or "IO_OUT": + - **time** (string): UNIX timestamp with 9 decimal places + - **source** (string): The particular logbook this was found in + - **log** (string): The actual log message + - **node_id** (pubkey): The peer this is associated with + - **data** (hex): The IO which occurred + +If **connected** is *true*: + - **netaddr** (array of strings): A single entry array: + - address, e.g. 1.2.3.4:1234 + - **features** (hex): bitmap of BOLT #9 features from peer's INIT message +[comment]: # (GENERATE-FROM-SCHEMA-END) + On success, an object with a "peers" key is returned containing a list of 0 or more objects. @@ -256,3 +372,4 @@ Main web site: Lightning RFC site (BOLT \#9): +[comment]: # ( SHA256STAMP:61071f726dbf0ac566607035239841ec19695688d4a1fd9f94f3c22ade6548d0) diff --git a/doc/lightning-listsendpays.7 b/doc/lightning-listsendpays.7 index 8f594c82cf26..93b9834fbd6b 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: - - - \fIid\fR -unique internal value assigned at creation - - - \fIpayment_hash\fR -the hash of the \fIpayment_preimage\fR which will prove payment\. - - - \fIdestination\fR -the final destination of the payment\. - - - \fIamount_msat\fR -the amount the destination received, in "NNNmsat" format\. - - - \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\. - +Note that the returned array is ordered by increasing \fIid\fR\. + + +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)\. + +.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 "failed": + +.RS +.IP \[bu] +\fBerroronion\fR (hex, optional): the onion message returned + +.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 7752b7e73591..bf0960f1cae1 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: - - *id* -unique internal value assigned at creation - - *payment\_hash* -the hash of the *payment\_preimage* which will prove payment. - - *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*. +Note that the returned array is ordered by increasing *id*. + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **payments** is returned. It is an array of objects, where each object contains: +- **id** (u64): unique ID for this payment attempt +- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters) +- **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). + +If **status** is "complete": + - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters) + +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 f87ff7b9c438..128e33732a26 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] +\fBmsat\fR (msat): the amount of the output .IP \[bu] -\fIsatoshis\fR: A string that represents the amount in millisatoshi\. +\fBscriptPubKey\fR (hex): the scriptPubKey .IP \[bu] -\fIscriptPubKey\fR: A string that contains the lock script in hexadecimal dump form\. +\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 cf8b47d2024e..b0c7bfdcd03e 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 a626ef63f926..7c1e7e23fcd0 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,22 +107,51 @@ 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 -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 +.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 + + +.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 07b7307c8ade..4f6c43b1ef05 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 85cab4c42e83..c674ebbe6ccf 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 9425aec05c0d..a8d85a603597 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 dd6493f79521..76a01c5a4450 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 63dc74020bd5..c099ab4e9b72 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 704682c523a4..252abf628853 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 02086d3900a0..776be84bbcd0 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 a09f6d0aabd1..eae6ebb78869 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 1de0fb6adfd2..b223c8130b1a 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 edc2ec9c92c7..ec78232341bd 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] +\fBused\fR (boolean): True if an incoming invoice has been paid (always \fIfalse\fR) .IP \[bu] -\fIlabel\fR: the user-specified label\. +\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 8b7266a60505..aa3c1439db63 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 7dd3d105a8d4..32be871a1927 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 cbca56165f5d..ab7b602e52e9 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 fc3dd74c50ea..6af9927cb64b 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 9f8646802085..d2a29363f00f 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 a92edbb7b4e0..0e236b7a9053 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 0385e1acb530..7bb95f95cd3f 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 d32063dfabcb..c428e3ffa878 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 d16ba23183eb..049fd1b31046 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 7e702ec7fe79..18c2aec4d10c 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 db52d39640ba..ed09a5f1e94a 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 b7acf0b6bb77..ddc3e8e8a24c 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 03f746a67d8d..e7a0c52723d5 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 aca80e7b2561..4988cf586054 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 9f2e0bf306ac..9081e22183e9 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 de27fddeefcb..01a696f7fecd 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 e0b91426e32f..d4b26ae21882 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 7a80c59ab5fa..21bca837068a 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 d8b1b7b69b18..425fc25c3f5c 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 d636395d71b1..c00d1e107f23 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 64561f3f7090..df5727e3fd0d 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 da3f8fe4ae75..232d6b1da43a 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 29c26d9a1e46..3ea2095790c1 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 089eab8279ea..c27dade8500d 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 7fa4b8785865..f5599f9abfe4 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 05d77098aa61..943bfa689002 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 d1b20ae313e1..7ee8cdd2c6fe 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 cd78284daa46..053d9ed65a8c 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 448be84b88b6..ca4e12b6ad91 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 721186d95d64..c4da7b927ebe 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 04dff47c5988..abbdcbf17e67 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 7b09bce18bad..6fd837094485 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 3ba01d9ab99c..c453d38d91ab 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 0f5641c9f68e..2ef29c351977 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 7c3ae9490d2d..9dcd86629df9 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 c5a1f905388c..0c2060ff70ae 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 36b64adf9293..16996fcacdb2 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 fba7c43a82d2..38304887808b 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 8c58a25c81ca..aced46201df1 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 75509576f610..1adc79dc917c 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 26952dd5dc53..b2c6d56a99bc 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 44fbd05fec76..9fb00b2e6d6e 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 86156b8d7e55..90e7759e5ac5 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 d1cf3373c820..89f9f0e9f2ab 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 d3c8a28167e5..c4849abcdb5e 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 9193e2abb9ee..4f35a409d3d9 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 6fe9c7dd6f81..f62f4f876f4a 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 2c75ddd5efc8..d4525aea9cad 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 454de79da167..0d3ed170e42c 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 87b1690993d2..ad3d8678c6f8 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 8ca4c4aadc10..d310c9b5012f 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 9dcd9fe643ba..a9b2907c1f94 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 ba5f160661c7..a9103c2e5420 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 5d94f14fb0e5..e3c553e061cc 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 ee88a70eb932..37347999fd22 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 30c2d5f43674..4210c2d24b6b 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 c588581e9723..6183169ffb79 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/lightningd-config.5 b/doc/lightningd-config.5 index c86991a259a4..595759ada013 100644 --- a/doc/lightningd-config.5 +++ b/doc/lightningd-config.5 @@ -80,31 +80,31 @@ Alias for \fInetwork=testnet\fR\. Alias for \fInetwork=signet\fR\. - \fBbitcoin-cli\fR=\fIPATH\fR + \fBbitcoin-cli\fR=\fIPATH\fR [plugin \fBbcli\fR] The name of \fIbitcoin-cli\fR executable to run\. - \fBbitcoin-datadir\fR=\fIDIR\fR + \fBbitcoin-datadir\fR=\fIDIR\fR [plugin \fBbcli\fR] \fI-datadir\fR argument to supply to \fBbitcoin-cli\fR(1)\. - \fBbitcoin-rpcuser\fR=\fIUSER\fR + \fBbitcoin-rpcuser\fR=\fIUSER\fR [plugin \fBbcli\fR] The RPC username for talking to \fBbitcoind\fR(1)\. - \fBbitcoin-rpcpassword\fR=\fIPASSWORD\fR + \fBbitcoin-rpcpassword\fR=\fIPASSWORD\fR [plugin \fBbcli\fR] The RPC password for talking to \fBbitcoind\fR(1)\. - \fBbitcoin-rpcconnect\fR=\fIHOST\fR + \fBbitcoin-rpcconnect\fR=\fIHOST\fR [plugin \fBbcli\fR] The \fBbitcoind\fR(1) RPC host to connect to\. - \fBbitcoin-rpcport\fR=\fIPORT\fR + \fBbitcoin-rpcport\fR=\fIPORT\fR [plugin \fBbcli\fR] The \fBbitcoind\fR(1) RPC port to connect to\. - \fBbitcoin-retry-timeout\fR=\fISECONDS\fR + \fBbitcoin-retry-timeout\fR=\fISECONDS\fR [plugin \fBbcli\fR] Number of seconds to keep trying a \fBbitcoin-cli\fR(1) command\. If the command keeps failing after this time, exit with a fatal error\. @@ -197,7 +197,7 @@ Log to this file instead of stdout\. Sending \fBlightningd\fR(8) SIGHUP will cause it to reopen this file (useful for log rotation)\. - \fBlog-timetamps\fR=\fIBOOL\fR + \fBlog-timestamps\fR=\fIBOOL\fR Set this to false to turn off timestamp prefixes (they will still appear in crash log files)\. @@ -344,7 +344,7 @@ Confirmations required for the funding transaction when the other side opens a channel before the channel is usable\. - \fBcommit-fee\fR=\fIPERCENT\fR + \fBcommit-fee\fR=\fIPERCENT\fR [plugin \fBbcli\fR] The percentage of \fIestimatesmartfee 2/CONSERVATIVE\fR to use for the commitment transactions: default is 100\. @@ -370,13 +370,13 @@ have to do that\. Invoice control options: - \fBautocleaninvoice-cycle\fR=\fISECONDS\fR + \fBautocleaninvoice-cycle\fR=\fISECONDS\fR [plugin \fBautoclean\fR] Perform cleanup of expired invoices every \fISECONDS\fR seconds, or disable if 0\. Usually unpaid expired invoices are uninteresting, and just take up space in the database\. - \fBautocleaninvoice-expired-by\fR=\fISECONDS\fR + \fBautocleaninvoice-expired-by\fR=\fISECONDS\fR [plugin \fBautoclean\fR] Control how long invoices must have been expired before they are cleaned (if \fIautocleaninvoice-cycle\fR is non-zero)\. @@ -384,7 +384,7 @@ Control how long invoices must have been expired before they are cleaned Payment control options: - \fBdisable-mpp\fR + \fBdisable-mpp\fR [plugin \fBpay\fR] Disable the multi-part payment sending support in the \fBpay\fR plugin\. By default the MPP support is enabled, but it can be desirable to disable in situations in which each payment should result in a single HTLC being forwarded in the @@ -628,4 +628,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license\. -\" SHA256STAMP:0010662a69870c935bdd6d701a254bfc116435797bbe026d8ca0c0de078c6492 +\" SHA256STAMP:bfe9e4072bd1a50f5c8553290240eb942298bfdcd823202d1c75d05d66401820 diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md index 652f5b8f7fb5..f99eed15b28a 100644 --- a/doc/lightningd-config.5.md +++ b/doc/lightningd-config.5.md @@ -72,25 +72,25 @@ Alias for *network=testnet*. **signet** Alias for *network=signet*. - **bitcoin-cli**=*PATH* + **bitcoin-cli**=*PATH* [plugin `bcli`] The name of *bitcoin-cli* executable to run. - **bitcoin-datadir**=*DIR* + **bitcoin-datadir**=*DIR* [plugin `bcli`] *-datadir* argument to supply to bitcoin-cli(1). - **bitcoin-rpcuser**=*USER* + **bitcoin-rpcuser**=*USER* [plugin `bcli`] The RPC username for talking to bitcoind(1). - **bitcoin-rpcpassword**=*PASSWORD* + **bitcoin-rpcpassword**=*PASSWORD* [plugin `bcli`] The RPC password for talking to bitcoind(1). - **bitcoin-rpcconnect**=*HOST* + **bitcoin-rpcconnect**=*HOST* [plugin `bcli`] The bitcoind(1) RPC host to connect to. - **bitcoin-rpcport**=*PORT* + **bitcoin-rpcport**=*PORT* [plugin `bcli`] The bitcoind(1) RPC port to connect to. - **bitcoin-retry-timeout**=*SECONDS* + **bitcoin-retry-timeout**=*SECONDS* [plugin `bcli`] Number of seconds to keep trying a bitcoin-cli(1) command. If the command keeps failing after this time, exit with a fatal error. @@ -157,7 +157,7 @@ with multiple daemons. Log to this file instead of stdout. Sending lightningd(8) SIGHUP will cause it to reopen this file (useful for log rotation). - **log-timetamps**=*BOOL* + **log-timestamps**=*BOOL* Set this to false to turn off timestamp prefixes (they will still appear in crash log files). @@ -281,7 +281,7 @@ create a channel, and if an HTLC asks for longer, we’ll refuse it. Confirmations required for the funding transaction when the other side opens a channel before the channel is usable. - **commit-fee**=*PERCENT* + **commit-fee**=*PERCENT* [plugin `bcli`] The percentage of *estimatesmartfee 2/CONSERVATIVE* to use for the commitment transactions: default is 100. @@ -302,18 +302,18 @@ have to do that. Invoice control options: - **autocleaninvoice-cycle**=*SECONDS* + **autocleaninvoice-cycle**=*SECONDS* [plugin `autoclean`] Perform cleanup of expired invoices every *SECONDS* seconds, or disable if 0. Usually unpaid expired invoices are uninteresting, and just take up space in the database. - **autocleaninvoice-expired-by**=*SECONDS* + **autocleaninvoice-expired-by**=*SECONDS* [plugin `autoclean`] Control how long invoices must have been expired before they are cleaned (if *autocleaninvoice-cycle* is non-zero). Payment control options: - **disable-mpp** + **disable-mpp** [plugin `pay`] Disable the multi-part payment sending support in the `pay` plugin. By default the MPP support is enabled, but it can be desirable to disable in situations in which each payment should result in a single HTLC being forwarded in the diff --git a/doc/schemas/WRITING_SCHEMAS.md b/doc/schemas/WRITING_SCHEMAS.md new file mode 100644 index 000000000000..eaf45fb55c5a --- /dev/null +++ b/doc/schemas/WRITING_SCHEMAS.md @@ -0,0 +1,77 @@ +# Writing JSON Schemas + +A JSON Schema is a JSON file which defines what a structure should +look like; in our case we use it in our testsuite to check that they +match command responses, and also use it to generate our +documentation. + +Yes, schemas are horrible to write, but they're damn useful. We can +only use a subset of the full [https://json-schema.org/](JSON Schema +Specification), but if you find that limiting it's probably a sign +that you should simplify your JSON output. + +## How to Write a Schema + +Name the schema doc/schemas/`command`.schema.json: the testsuite should +pick it up and check all invocations of that command against it. + +I recommend copying an existing one to start. + +You will need to put the magic lines in the manual page so `make doc-all` +will fill it in for you: + +``` +[comment]: # (GENERATE-FROM-SCHEMA-START) +[comment]: # (GENERATE-FROM-SCHEMA-END) +``` + +If something goes wrong, try tools/fromscheme.py +doc/schemas/`command`.schema.json to see how far it got before it died. + +You should always use `"additionalProperties": false`, otherwise +your schema might not be covering everything. Deprecated fields +simply have `"deprecated": true` in their properties, so they +are allowed by omitted from the documentation. + +You should always list all fields which are *always* present in +`"required"`. + +We extend the basic types; see +[contrib/pyln-testing/pyln/testing/fixtures.py](fixtures.py). + + +### Using Conditional Fields + +Sometimes one field is only sometimes present; if you can, you should make +the schema know when it should (and should not!) be there. + +There are two kinds of conditional fields expressable: fields which +are only present if another field is present, or fields only present +if another field has certain values. + +To add conditional fields: + +1. Do *not* mention them in the main "properties" section. +2. Set `"additionalProperties": true` for the main "properties" section. +3. Add an `"allOf": [` array at the same height as `"properties"'`. Inside + this place one `if`/`then` for each conditional field. +4. If a field simply requires another field to be present, use the pattern + `"required": [ "field" ]` inside the "if". +5. If a field requires another field value, use the pattern + `"properties": { "field": { "enum": [ "val1", "val2" ] } }` inside + the "if". +6. Inside the "then", use `"additionalProperties": false` and place + empty `{}` for all the other possible properties. +7. If you haven't covered all the possibilties with `if` statements, + add an `else` with `"additionalProperties": false` which simply + mentions every allowable property. This ensures that the fields + can *only* be present when conditions are met. + +### JSON Drinking Game! + +1. Sip whenever you have an additional comma at the end of a sequence. +2. Sip whenever you omit a comma in a sequence because you cut & paste. +3. Skull whenever you wish JSON had comments. + +Good luck! +Rusty. diff --git a/doc/schemas/checkmessage.schema.json b/doc/schemas/checkmessage.schema.json new file mode 100644 index 000000000000..7bc2833bd142 --- /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/delinvoice.schema.json b/doc/schemas/delinvoice.schema.json index 846237a30951..f5482206a5c5 100644 --- a/doc/schemas/delinvoice.schema.json +++ b/doc/schemas/delinvoice.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", - "required": [ "label", "payment_hash", "amount_msat", "status", "expires_at" ], + "required": [ "label", "payment_hash", "status", "expires_at" ], "additionalProperties": true, "properties": { "label": { @@ -16,6 +16,23 @@ "type": "string", "description": "BOLT12 string" }, + "msatoshi": { + "deprecated": "true" + }, + "amount_msat": { + "type": "msat", + "description": "the amount required to pay this invoice" + }, + "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", "description": "State of invoice", @@ -32,13 +49,44 @@ "required": [ "bolt12" ] }, "then": { - "required": [ ], + "required": [ ], + "additionalProperties": false, "properties": { + "label": { }, + "bolt12": { }, + "status": { }, + "expires_at": { }, + "msatoshi": { }, + "amount_msat": { }, + "description": { }, + "payment_hash": { }, + "pay_index": { }, + "amount_received_msat": { }, + "paid_at": { }, + "payment_preimage": { }, "local_offer_id": { "type": "hex", "description": "offer for which this invoice was created" } } + }, + "else": { + "required": [ "bolt11" ], + "additionalProperties": false, + "properties": { + "label": { }, + "bolt11": { }, + "status": { }, + "expires_at": { }, + "msatoshi": { }, + "amount_msat": { }, + "description": { }, + "payment_hash": { }, + "pay_index": { }, + "amount_received_msat": { }, + "paid_at": { }, + "payment_preimage": { } + } } }, { @@ -54,6 +102,15 @@ "additionalProperties": false, "required": [ "pay_index", "amount_received_msat", "paid_at", "payment_preimage" ], "properties": { + "label": { }, + "bolt11": { }, + "bolt12": { }, + "status": { }, + "expires_at": { }, + "msatoshi": { }, + "amount_msat": { }, + "description": { }, + "payment_hash": { }, "pay_index": { "type": "u64", "description": "unique index for this invoice payment" @@ -73,6 +130,22 @@ "minLength": 64 } } + }, + "else": { + "additionalProperties": false, + "properties": { + "label": { }, + "bolt11": { }, + "bolt12": { }, + "status": { }, + "msatoshi": { }, + "amount_msat": { }, + "description": { }, + "payment_hash": { }, + "expires_at": { }, + "pay_index": { }, + "local_offer_id": { } + } } } ] diff --git a/doc/schemas/delpay.schema.json b/doc/schemas/delpay.schema.json index 3a1ed1ba633e..a2e0c9c94e60 100644 --- a/doc/schemas/delpay.schema.json +++ b/doc/schemas/delpay.schema.json @@ -8,7 +8,7 @@ "type": "array", "items": { "type": "object", - "additionalProperties": true, + "additionalProperties": false, "required": [ "id", "payment_hash", "status", "amount_sent_msat", "created_at" ], "properties": { "id": { @@ -26,6 +26,9 @@ "enum": [ "pending", "failed", "complete" ], "description": "status of the payment" }, + "msatoshi_sent": { + "deprecated": true + }, "amount_sent_msat": { "type": "msat", "description": "the amount we actually sent, including fees" @@ -38,6 +41,9 @@ "type": "pubkey", "description": "the final destination of the payment if known" }, + "msatoshi": { + "deprecated": true + }, "amount_msat": { "type": "msat", "description": "the amount the destination received, if known" diff --git a/doc/schemas/dev-sendcustommsg.schema.json b/doc/schemas/dev-sendcustommsg.schema.json new file mode 100644 index 000000000000..21ce1eb8b250 --- /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 c935136224c0..8aac22c6d46c 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/getsharedsecret.schema.json b/doc/schemas/getsharedsecret.schema.json new file mode 100644 index 000000000000..143d0e87cda3 --- /dev/null +++ b/doc/schemas/getsharedsecret.schema.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": true, + "required": [ "shared_secret" ], + "properties": { + "shared_secret": { + "type": "hex", + "description": "the SHA-2 of the compressed encoding of the shared secp256k1 point", + "maxLength": 64, + "minLength": 64 + } + } +} diff --git a/doc/schemas/help.schema.json b/doc/schemas/help.schema.json new file mode 100644 index 000000000000..37c9ce150d1d --- /dev/null +++ b/doc/schemas/help.schema.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "help" ], + "properties": { + "help": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "command", "category", "description", "verbose" ], + "properties": { + "command": { + "type": "string", + "description": "the command" + }, + "category": { + "type": "string", + "description": "the category for this command (useful for grouping)" + }, + "description": { + "type": "string", + "description": "a one-line description of the purpose of this command" + }, + "verbose": { + "type": "string", + "description": "a full description of this command (including whether it's deprecated)" + } + } + } + }, + "format-hint": { } + } +} diff --git a/doc/schemas/invoice.schema.json b/doc/schemas/invoice.schema.json new file mode 100644 index 000000000000..b4f6284959cd --- /dev/null +++ b/doc/schemas/invoice.schema.json @@ -0,0 +1,42 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "payment_hash", "expires_at", "bolt11" ], + "properties": { + "bolt11": { + "type": "string", + "description": "the bolt11 string" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage* which will prove payment", + "maxLength": 64, + "minLength": 64 + }, + "expires_at": { + "type": "u64", + "description": "UNIX timestamp of when invoice expires" + }, + "warning_capacity": { + "type": "string", + "description": "even using all possible channels, there's not enough incoming capacity to pay this invoice." + }, + "warning_offline": { + "type": "string", + "description": "there would be enough incoming capacity, but some channels are offline, so there isn't." + }, + "warning_deadends": { + "type": "string", + "description": "there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't." + }, + "warning_private_unused": { + "type": "string", + "description": "there would be enough incoming capacity, but some channels are unannounced and *exposeprivatechannels* is *false*, so there isn't." + }, + "warning_mpp": { + "type": "string", + "description": "there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments." + } + } +} diff --git a/doc/schemas/keysend.schema.json b/doc/schemas/keysend.schema.json new file mode 100644 index 000000000000..b3bd48ccc092 --- /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/listchannels.schema.json b/doc/schemas/listchannels.schema.json new file mode 100644 index 000000000000..bd1ab36b764c --- /dev/null +++ b/doc/schemas/listchannels.schema.json @@ -0,0 +1,77 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channels" ], + "properties": { + "channels": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "source", "destination", "short_channel_id", "public", "amount_msat", "message_flags", "channel_flags", "active", "last_update", "base_fee_millisatoshi", "fee_per_millionth", "delay", "htlc_minimum_msat", "features" ], + "properties": { + "source": { + "type": "pubkey", + "description": "the source node" + }, + "destination": { + "type": "pubkey", + "description": "the destination node" + }, + "public": { + "type": "boolean", + "description": "true if this is announced (otherwise it must be our channel)" + }, + "amount_msat": { + "type": "msat", + "description": "the total capacity of this channel (always a whole number of satoshis)" + }, + "message_flags": { + "type": "u8", + "description": "as defined by BOLT #7" + }, + "channel_flags": { + "type": "u8", + "description": "as defined by BOLT #7" + }, + "active": { + "type": "boolean", + "description": "true unless source has disabled it, or it's a local channel and the peer is disconnected or it's still opening or closing" + }, + "last_update": { + "type": "u32", + "description": "UNIX timestamp on the last channel_update from *source*" + }, + "base_fee_millisatoshi": { + "type": "u32", + "description": "Base fee changed by *source* to use this channel" + }, + "fee_per_millionth": { + "type": "u32", + "description": "Proportional fee changed by *source* to use this channel, in parts-per-million" + }, + "delay": { + "type": "u32", + "description": "The number of blocks delay required by *source* to use this channel" + }, + "htlc_minimum_msat": { + "type": "msat", + "description": "The smallest payment *source* will allow via this channel" + }, + "satoshis": { + "deprecated": true + }, + "htlc_maximum_msat": { + "type": "msat", + "description": "The largest payment *source* will allow via this channel" + }, + "features": { + "type": "hex", + "description": "BOLT #9 features bitmap for this channel" + } + } + } + } + } +} diff --git a/doc/schemas/listconfigs.schema.json b/doc/schemas/listconfigs.schema.json new file mode 100644 index 000000000000..d0844021995a --- /dev/null +++ b/doc/schemas/listconfigs.schema.json @@ -0,0 +1,247 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ ], + "properties": { + "# version": { + "type": "string", + "description": "Special field indicating the current version" + }, + "plugins": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "path", "name" ], + "description": "`plugin` field from config or cmdline", + "properties": { + "path": { + "type": "string", + "description": "Full path of the plugin" + }, + "name": { + "type": "string", + "description": "short name of the plugin" + }, + "options": { + "type": "object", + "additionalProperties": true, + "required": [ ], + "description": "Specific options set for this plugin", + "properties": { + } + } + } + } + }, + "important-plugins": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "path", "name" ], + "description": "`important-plugin` field from config or cmdline, or built-in", + "properties": { + "path": { + "type": "string", + "description": "Full path of the plugin" + }, + "name": { + "type": "string", + "description": "short name of the plugin" + }, + "options": { + "type": "object", + "additionalProperties": true, + "required": [ ], + "description": "Specific options set for this plugin", + "properties": { + } + } + } + } + }, + "conf": { + "type": "string", + "description": "`conf` field from cmdline, or default" + }, + "lightning-dir": { + "type": "string", + "description": "`lightning-dir` field from config or cmdline, or default" + }, + "network": { + "type": "string", + "description": "`network` field from config or cmdline, or default" + }, + "allow-deprecated-apis": { + "type": "boolean", + "description": "`allow-deprecated-apis` field from config or cmdline, or default" + }, + "rpc-file": { + "type": "string", + "description": "`rpc-file` field from config or cmdline, or default" + }, + "disable-plugin": { + "type": "array", + "items": { + "type": "string", + "description": "`disable-plugin` field from config or cmdline" + } + }, + "always-use-proxy": { + "type": "boolean", + "description": "`always-use-proxy` field from config or cmdline, or default" + }, + "daemon": { + "type": "boolean", + "description": "`daemon` field from config or cmdline, or default" + }, + "wallet": { + "type": "string", + "description": "`wallet` field from config or cmdline, or default" + }, + "large-channels": { + "type": "boolean", + "description": "`large-channels` field from config or cmdline, or default" + }, + "experimental-dual-fund": { + "type": "boolean", + "description": "`experimental-dual-fund` field from config or cmdline, or default" + }, + "experimental-onion-messages": { + "type": "boolean", + "description": "`experimental-onion-messages` field from config or cmdline, or default" + }, + "experimental-offers": { + "type": "boolean", + "description": "`experimental-offers` field from config or cmdline, or default" + }, + "experimental-shutdown-wrong-funding": { + "type": "boolean", + "description": "`experimental-shutdown-wrong-funding` field from config or cmdline, or default" + }, + "rgb": { + "type": "hex", + "description": "`rgb` field from config or cmdline, or default", + "maxLength": 6, + "minLength": 6 + }, + "alias": { + "type": "string", + "description": "`alias` field from config or cmdline, or default" + }, + "pid-file": { + "type": "string", + "description": "`pid-file` field from config or cmdline, or default" + }, + "ignore-fee-limits": { + "type": "boolean", + "description": "`ignore-fee-limits` field from config or cmdline, or default" + }, + "watchtime-blocks": { + "type": "u32", + "description": "`watchtime-blocks` field from config or cmdline, or default" + }, + "max-locktime-blocks": { + "type": "u32", + "description": "`max-locktime-blocks` field from config or cmdline, or default" + }, + "funding-confirms": { + "type": "u32", + "description": "`funding-confirms` field from config or cmdline, or default" + }, + "cltv-delta": { + "type": "u32", + "description": "`cltv-delta` field from config or cmdline, or default" + }, + "cltv-final": { + "type": "u32", + "description": "`cltv-final` field from config or cmdline, or default" + }, + "commit-time": { + "type": "u32", + "description": "`commit-time` field from config or cmdline, or default" + }, + "fee-base": { + "type": "u32", + "description": "`fee-base` field from config or cmdline, or default" + }, + "rescan": { + "type": "integer", + "description": "`rescan` field from config or cmdline, or default" + }, + "fee-per-satoshi": { + "type": "u32", + "description": "`fee-per-satoshi` field from config or cmdline, or default" + }, + "max-concurrent-htlcs": { + "type": "u32", + "description": "`max-concurrent-htlcs` field from config or cmdline, or default" + }, + "min-capacity-sat": { + "type": "u64", + "description": "`min-capacity-sat` field from config or cmdline, or default" + }, + "addr": { + "type": "string", + "description": "`addr` field from config or cmdline (can be more than one)" + }, + "announce-addr": { + "type": "string", + "description": "`announce-addr` field from config or cmdline (can be more than one)" + }, + "bind-addr": { + "type": "string", + "description": "`bind-addr` field from config or cmdline (can be more than one)" + }, + "offline": { + "type": "boolean", + "description": "`true` if `offline` was set in config or cmdline" + }, + "autolisten": { + "type": "boolean", + "description": "`autolisten` field from config or cmdline, or default" + }, + "proxy": { + "type": "string", + "description": "`proxy` field from config or cmdline, or default" + }, + "disable-dns": { + "type": "boolean", + "description": "`true` if `disable-dns` was set in config or cmdline" + }, + "encrypted-hsm": { + "type": "boolean", + "description": "`true` if `encrypted-hsm` was set in config or cmdline" + }, + "rpc-file-mode": { + "type": "string", + "description": "`rpc-file-mode` field from config or cmdline, or default" + }, + "log-level": { + "type": "string", + "description": "`log-level` field from config or cmdline, or default" + }, + "log-prefix": { + "type": "string", + "description": "`log-prefix` field from config or cmdline, or default" + }, + "log-file": { + "type": "string", + "description": "`log-file` field from config or cmdline, or default" + }, + "log-timestamps": { + "type": "boolean", + "description": "`log-timestamps` field from config or cmdline, or default" + }, + "subdaemon": { + "type": "string", + "description": "`subdaemon` fields from config or cmdline if any (can be more than one)" + }, + "tor-service-password": { + "type": "string", + "description": "`tor-service-password` field from config or cmdline, if any" + } + } +} diff --git a/doc/schemas/listforwards.schema.json b/doc/schemas/listforwards.schema.json new file mode 100644 index 000000000000..f52b10ee05d1 --- /dev/null +++ b/doc/schemas/listforwards.schema.json @@ -0,0 +1,205 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "forwards" ], + "properties": { + "forwards": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "in_channel", "in_msat", "status", "received_time" ], + "properties": { + "in_channel": { + "type": "short_channel_id", + "description": "the channel that received the HTLC" + }, + "in_msatoshi": { + "deprecated": true + }, + "in_msat": { + "type": "msat", + "description": "the value of the incoming HTLC" + }, + "status": { + "type": "string", + "enum": [ "offered", "settled", "local_failed", "failed" ], + "description": "still ongoing, completed, failed locally, or failed after forwarding" + }, + "received_time": { + "type": "number", + "description": "the UNIX timestamp when this was received" + }, + "out_channel": { + "type": "short_channel_id", + "description": "the channel that the HTLC was forwarded to" + }, + "payment_hash": { + "type": "hex", + "description": "payment hash sought by HTLC", + "maxLength": 64, + "minLength": 64 + } + }, + "allOf": [ + { + "if": { + "required": [ "out_channel" ] + }, + "then": { + "additionalProperties": false, + "required": [ "fee_msat", "out_msat" ], + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "resolved_time": { }, + "out_channel": { }, + "payment_hash": { }, + "failcode": { }, + "failreason": { }, + "fee": { + "deprecated": true + }, + "fee_msat": { + "type": "msat", + "description": "the amount this paid in fees" + }, + "out_msatoshi": { + "deprecated": true + }, + "out_msat": { + "type": "msat", + "description": "the amount we sent out the *out_channel*" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ ], + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "resolved_time": { }, + "payment_hash": { }, + "failcode": { }, + "failreason": { } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "settled", "failed" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "resolved_time" ], + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "out_channel": { }, + "payment_hash": { }, + "fee": { }, + "fee_msat": { }, + "out_msatoshi": { }, + "out_msat": { }, + "failcode": { }, + "failreason": { }, + "resolved_time": { + "type": "number", + "description": "the UNIX timestamp when this was resolved" + } + } + }, + "else": { + "additionalProperties": false, + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "out_channel": { }, + "payment_hash": { }, + "fee": { }, + "fee_msat": { }, + "failcode": { }, + "failreason": { }, + "out_msatoshi": { }, + "out_msat": { } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "local_failed", "failed" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "out_channel": { }, + "payment_hash": { }, + "fee": { }, + "fee_msat": { }, + "out_msatoshi": { }, + "out_msat": { }, + "resolved_time": { }, + "failcode": { + "type": "u32", + "description": "the numeric onion code returned" + }, + "failreason": { + "type": "string", + "description": "the name of the onion code returned" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ ], + "properties": { + "in_channel": { }, + "in_msatoshi": { }, + "in_msat": { }, + "status": { }, + "received_time": { }, + "out_channel": { }, + "payment_hash": { }, + "fee": { }, + "fee_msat": { }, + "out_msatoshi": { }, + "out_msat": { }, + "resolved_time": { } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/listfunds.schema.json b/doc/schemas/listfunds.schema.json new file mode 100644 index 000000000000..84172c855c95 --- /dev/null +++ b/doc/schemas/listfunds.schema.json @@ -0,0 +1,217 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "outputs", "channels" ], + "properties": { + "outputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "txid", "output", "amount_msat", "scriptpubkey", "status", "reserved" ], + "properties": { + "txid": { + "type": "txid", + "description": "the ID of the spendable transaction" + }, + "output": { + "type": "u32", + "description": "the index within *txid*" + }, + "amount_msat": { + "type": "msat", + "description": "the amount of the output" + }, + "value": { + "type": "u64", + "deprecated": true + }, + "scriptpubkey": { + "type": "hex", + "description": "the scriptPubkey of the output" + }, + "address": { + "type": "string", + "description": "the bitcoin address of the output" + }, + "redeemscript": { + "type": "hex", + "description": "the redeemscript, only if it's p2sh-wrapped" + }, + "status": { + "type": "string", + "enum": [ "unconfirmed", "confirmed", "spent" ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "confirmed" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "blockheight" ], + "properties": { + "txid": { }, + "output": { }, + "amount_msat": { }, + "scriptpubkey": { }, + "address": { }, + "value": { }, + "redeemscript": { }, + "status": { }, + "reserved": { }, + "reserved_to_block": { }, + "blockheight": { + "type": "u32", + "description": "Block height where it was confirmed" + } + } + } + }, + { + "if": { + "properties": { + "reserved": { + "type": "boolean", + "enum": [ "true" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "reserved_to_block" ], + "properties": { + "txid": { }, + "output": { }, + "amount_msat": { }, + "scriptpubkey": { }, + "address": { }, + "value": { }, + "redeemscript": { }, + "status": { }, + "blockheight": { }, + "reserved": { }, + "reserved_to_block": { + "type": "u32", + "description": "Block height where reservation will expire" + } + } + } + } + ] + } + }, + "channels": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "peer_id", "our_amount_msat", "amount_msat", "funding_txid", "funding_output", "connected", "state" ], + "properties": { + "peer_id": { + "type": "pubkey", + "description": "the peer with which the channel is opened" + }, + "our_amount_msat": { + "type": "msat", + "description": "available satoshis on our node’s end of the channel" + }, + "channel_sat": { + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "total channel value" + }, + "channel_total_sat": { + "deprecated": true + }, + "funding_txid": { + "type": "txid", + "description": "funding transaction id" + }, + "funding_output": { + "type": "u32", + "description": "the 0-based index of the output in the funding transaction" + }, + "connected": { + "type": "boolean", + "description": "whether the channel peer is connected" + }, + "state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "the channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally" + } + }, + "allOf": [ + { + "if": { + "properties": { + "state": { + "type": "string", + "enum": [ "CHANNELD_NORMAL" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "short_channel_id" ], + "properties": { + "peer_id": { }, + "our_amount_msat": { }, + "channel_sat": { }, + "amount_msat": { }, + "channel_total_sat": { }, + "funding_txid": { }, + "funding_output": { }, + "connected": { }, + "state": { }, + "short_channel_id": { + "type": "short_channel_id", + "description": "short channel id of channel" + } + } + } + }, + { + "if": { + "properties": { + "state": { + "type": "string", + "enum": [ "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "peer_id": { }, + "our_amount_msat": { }, + "channel_sat": { }, + "amount_msat": { }, + "channel_total_sat": { }, + "funding_txid": { }, + "funding_output": { }, + "connected": { }, + "state": { }, + "short_channel_id": { + "type": "short_channel_id", + "description": "short channel id of channel (only if funding reached lockin depth before closing)" + } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/listinvoices.schema.json b/doc/schemas/listinvoices.schema.json new file mode 100644 index 000000000000..6c5ffa654e50 --- /dev/null +++ b/doc/schemas/listinvoices.schema.json @@ -0,0 +1,118 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "invoices" ], + "properties": { + "invoices": { + "type": "array", + "items": { + "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" + }, + "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/listnodes.schema.json b/doc/schemas/listnodes.schema.json new file mode 100644 index 000000000000..eb210fe8740d --- /dev/null +++ b/doc/schemas/listnodes.schema.json @@ -0,0 +1,79 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "nodes" ], + "properties": { + "nodes": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "nodeid" ], + "properties": { + "nodeid": { + "type": "pubkey", + "description": "the public key of the node" + }, + "last_update": { + "type": "u32", + "description": "A node_announcement has been received for this node (UNIX timestamp)" + } + }, + "allOf": [ + { + "if": { + "required": [ "last_update" ] + }, + "then": { + "additionalProperties": false, + "required": [ "last_update", "alias", "color", "features", "addresses" ], + "properties": { + "last_update": { }, + "alias": { + "type": "string", + "description": "The fun alias this node advertized", + "maxLength": 32 + }, + "color": { + "type": "hex", + "description": "The favorite RGB color this node advertized", + "minLength": 6, + "maxLength": 6 + }, + "features": { + "type": "hex", + "description": "BOLT #9 features bitmap this node advertized" + }, + "addresses": { + "type": "array", + "description": "The addresses this node advertized", + "items": { + "type": "object", + "required": [ "type", "address", "port" ], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": [ "ipv4", "ipv6", "torv2", "torv3" ], + "description": "Type of connection" + }, + "address": { + "type": "string", + "description": "address in expected format for *type*" + }, + "port": { + "type": "u16", + "description": "port number" + } + } + } + } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/listoffers.schema.json b/doc/schemas/listoffers.schema.json new file mode 100644 index 000000000000..9c6caa101711 --- /dev/null +++ b/doc/schemas/listoffers.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "offers" ], + "properties": { + "offers": { + "type": "array", + "items": { + "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", + "description": "whether this can still be used" + }, + "single_use": { + "type": "boolean", + "description": "whether this expires as soon as it's paid" + }, + "bolt12": { + "type": "string", + "description": "the bolt12 encoding of the offer" + }, + "used": { + "type": "boolean", + "description": "True if an associated invoice has been paid" + }, + "label": { + "type": "string", + "description": "the (optional) user-specified label" + } + } + } + } + } +} diff --git a/doc/schemas/listpeers.schema.json b/doc/schemas/listpeers.schema.json new file mode 100644 index 000000000000..e992bf98dc77 --- /dev/null +++ b/doc/schemas/listpeers.schema.json @@ -0,0 +1,936 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "peers" ], + "properties": { + "peers": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "id", "connected", "channels" ], + "properties": { + "id": { + "type": "pubkey", + "description": "the public key of the peer" + }, + "connected": { + "type": "boolean", + "description": "True if the peer is currently connected" + }, + "log": { + "type": "array", + "description": "if *level* is specified, logs for this peer", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "type" ], + "properties": { + "type": { + "type": "string", + "enum": [ "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT" ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "enum": [ "SKIPPED" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "num_skipped" ], + "properties": { + "type": { }, + "num_skipped": { + "type": "u32", + "description": "number of deleted/omitted entries" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "enum": [ "BROKEN", "UNUSUAL", "INFO", "DEBUG" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "time", "source", "log", "node_id" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The actual log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "enum": [ "IO_IN", "IO_OUT" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "time", "source", "log", "node_id", "data" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The actual log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + }, + "data": { + "type": "hex", + "description": "The IO which occurred" + } + } + } + } + ] + } + }, + "channels": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "state", "opener", "features" ], + "properties": { + "state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "the channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally" + }, + "scratch_txid": { + "type": "txid", + "description": "The txid we would use if we went onchain now" + }, + "feerate": { + "type": "object", + "description": "Feerates for the current tx", + "additionalProperties": false, + "required": [ "perkw", "perkb" ], + "properties": { + "perkw": { + "type": "u32", + "description": "Feerate per 1000 weight (i.e kSipa)" + }, + "perkb": { + "type": "u32", + "description": "Feerate per 1000 virtual bytes" + } + } + }, + "owner": { + "type": "string", + "description": "The current subdaemon controlling this connection" + }, + "short_channel_id": { + "type": "short_channel_id", + "description": "The short_channel_id (once locked in)" + }, + "channel_id": { + "type": "hex", + "description": "The full channel_id", + "minLength": 64, + "maxLength": 64 + }, + "funding_txid": { + "type": "txid", + "description": "ID of the funding transaction" + }, + "inflight": { + "type": "array", + "description": "Current candidate funding transactions (only for dual-funding)", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "funding_txid", "funding_outnum", "feerate", "total_funding_msat", "our_funding_msat", "scratch_txid" ], + "properties": { + "funding_txid": { + "type": "txid", + "description": "ID of the funding transaction" + }, + "funding_outnum": { + "type": "u32", + "description": "The 0-based output number of the funding transaction which opens the channel" + }, + "feerate": { + "type": "string", + "description": "The feerate for this funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "total_funding_msat": { + "type": "msat", + "description": "total amount in the channel" + }, + "our_funding_msat": { + "type": "msat", + "description": "amount we have in the channel" + }, + "scratch_txid": { + "type": "txid", + "description": "The commitment transaction txid we would use if we went onchain now" + } + } + } + }, + "close_to": { + "type": "hex", + "description": "scriptPubkey which we have to close to if we mutual close" + }, + "private": { + "type": "boolean", + "description": "if False, we will not announce this channel" + }, + "opener": { + "type": "string", + "enum": [ "local", "remote" ], + "description": "Who initiated the channel" + }, + "closer": { + "FIXME": "deprecated_apis turns off null!", + "type": [ "string", "null" ], + "enum": [ "local", "remote", null ], + "description": "Who initiated the channel close (`null` is deprecated!)" + }, + "features": { + "type": "array", + "items": { + "type": "string", + "enum": [ "option_static_remotekey", "option_anchor_outputs" ], + "description": "BOLT #9 features which apply to this channel" + } + }, + "funding": { + "type": "object", + "additionalProperties": false, + "required": [ "local_msat", "remote_msat" ], + "properties": { + "local_msat": { + "type": "msat", + "description": "Amount of channel we funded" + }, + "remote_msat": { + "type": "msat", + "description": "Amount of channel they funded" + } + } + }, + "funding_allocation_msat": { + "deprecated": true + }, + "funding_msat": { + "deprecated": true + }, + "to_us_msat": { + "type": "msat", + "description": "how much of channel is owed to us" + }, + "min_to_us_msat": { + "type": "msat", + "description": "least amount owed to us ever" + }, + "max_to_us_msat": { + "type": "msat", + "description": "most amount owed to us ever" + }, + "total_msat": { + "type": "msat", + "description": "total amount in the channel" + }, + "fee_base_msat": { + "type": "msat", + "description": "amount we charge to use the channel" + }, + "fee_proportional_millionths": { + "type": "u32", + "description": "amount we charge to use the channel in parts-per-million" + }, + "dust_limit_msat": { + "type": "msat", + "description": "minimum amount for an output on the channel transactions" + }, + "max_total_htlc_in_msat": { + "type": "msat", + "description": "max amount accept in a single payment" + }, + "their_reserve_msat": { + "type": "msat", + "description": "minimum we insist they keep in channel" + }, + "our_reserve_msat": { + "type": "msat", + "description": "minimum they insist we keep in channel" + }, + "spendable_msat": { + "type": "msat", + "description": "total we could send through channel" + }, + "receivable_msat": { + "type": "msat", + "description": "total peer could send through channel" + }, + "minimum_htlc_in_msat": { + "type": "msat", + "description": "the minimum amount HTLC we accept" + }, + "their_to_self_delay": { + "type": "u32", + "description": "the number of blocks before they can take their funds if they unilateral close" + }, + "our_to_self_delay": { + "type": "u32", + "description": "the number of blocks before we can take our funds if we unilateral close" + }, + "max_accepted_htlcs": { + "type": "u32", + "description": "Maximum number of incoming HTLC we will accept at once" + }, + "msatoshi_to_us": { + "deprecated": true + }, + "msatoshi_to_us_min": { + "deprecated": true + }, + "msatoshi_to_us_max": { + "deprecated": true + }, + "msatoshi_total": { + "deprecated": true + }, + "dust_limit_satoshis": { + "deprecated": true + }, + "max_htlc_value_in_flight_msat": { + "deprecated": true + }, + "our_channel_reserve_satoshis": { + "deprecated": true + }, + "their_channel_reserve_satoshis": { + "deprecated": true + }, + "spendable_msatoshi": { + "deprecated": true + }, + "receivable_msatoshi": { + "deprecated": true + }, + "htlc_minimum_msat": { + "deprecated": true + }, + "state_changes": { + "type": "array", + "description": "Prior state changes", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "timestamp", "old_state", "new_state", "cause", "message" ], + "properties": { + "timestamp": { + "type": "string", + "description": "UTC timestamp of form YYYY-mm-ddTHH:MM:SS.%03dZ" + }, + "old_state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "Previous state" + }, + "new_state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "New state" + }, + "cause": { + "type": "string", + "enum": [ "unknown", "local", "user", "remote", "protocol", "onchain" ], + "description": "What caused the change" + }, + "message": { + "type": "string", + "description": "Human-readable explanation" + } + } + } + }, + "status": { + "type": "array", + "items": { + "type": "string", + "description": "Billboard log of significant changes" + } + }, + "in_payments_offered": { + "type": "u64", + "description": "Number of incoming payment attempts" + }, + "in_offered_msat": { + "type": "msat", + "description": "Total amount of incoming payment attempts" + }, + "in_msatoshi_offered": { + "deprecated": true + }, + "in_payments_fulfilled": { + "type": "u64", + "description": "Number of successful incoming payment attempts" + }, + "in_fulfilled_msat": { + "type": "msat", + "description": "Total amount of successful incoming payment attempts" + }, + "in_msatoshi_fulfilled": { + "deprecated": true + }, + "out_payments_offered": { + "type": "u64", + "description": "Number of outgoing payment attempts" + }, + "out_offered_msat": { + "type": "msat", + "description": "Total amount of outgoing payment attempts" + }, + "out_msatoshi_offered": { + "deprecated": true + }, + "out_payments_fulfilled": { + "type": "u64", + "description": "Number of successful outgoing payment attempts" + }, + "out_fulfilled_msat": { + "type": "msat", + "description": "Total amount of successful outgoing payment attempts" + }, + "out_msatoshi_fulfilled": { + "deprecated": true + }, + "htlcs": { + "type": "array", + "description": "current HTLCs in this channel", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "direction", "id", "amount_msat", "expiry", "payment_hash", "state" ], + "properties": { + "direction": { + "type": "string", + "enum": [ "in", "out" ], + "description": "Whether it came from peer, or is going to peer" + }, + "id": { + "type": "u64", + "description": "Unique ID for this htlc on this channel in this direction" + }, + "amount_msat": { + "type": "msat", + "description": "Amount send/received for this HTLC" + }, + "msatoshi": { + "deprecated": true + }, + "expiry": { + "type": "u32", + "description": "Block this HTLC expires at" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the payment_preimage which will prove payment", + "maxLength": 64, + "minLength": 64 + }, + "local_trimmed": { + "type": "boolean", + "enum": [ true ], + "description": "if this is too small to enforce onchain" + }, + "status": { + "type": "string", + "description": "set if this HTLC is currently waiting on a hook (and shows what plugin)" + } + }, + "allOf": [ + { + "if": { + "properties": { + "direction": { + "enum": [ "out" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "state" ], + "properties": { + "direction": { }, + "id": { }, + "amount_msat": { }, + "msatoshi": { }, + "expiry": { }, + "payment_hash": { }, + "local_trimmed": { }, + "status": { }, + "state": { + "type": "string", + "enum": [ "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION" ], + "description": "Status of the HTLC" + } + } + } + }, + { + "if": { + "properties": { + "direction": { + "enum": [ "in" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "state" ], + "properties": { + "direction": { }, + "id": { }, + "amount_msat": { }, + "msatoshi": { }, + "expiry": { }, + "payment_hash": { }, + "local_trimmed": { }, + "status": { }, + "state": { + "type": "string", + "enum": [ "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION" ], + "description": "Status of the HTLC" + } + } + } + } + ] + } + } + }, + "allOf": [ + { + "if": { + "required": [ "close_to" ] + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "direction": { }, + "close_to_addr": { + "type": "string", + "description": "The bitcoin address we will close to" + } + } + } + }, + { + "if": { + "required": [ "scratch_txid" ] + }, + "then": { + "additionalProperties": false, + "required": [ "last_tx_fee_msat" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "close_to_addr": { }, + "initial_feerate": { }, + "last_feerate": { }, + "next_feerate": { }, + "next_feestep": { }, + "direction": { }, + "last_tx_fee": { + "deprecated": true + }, + "last_tx_fee_msat": { + "type": "msat", + "description": "fee attached to this the current tx" + } + } + } + }, + { + "if": { + "required": [ "short_channel_id" ] + }, + "then": { + "additionalProperties": false, + "required": [ "direction" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "close_to_addr": { }, + "initial_feerate": { }, + "last_feerate": { }, + "next_feerate": { }, + "next_feestep": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "direction": { + "type": "u32", + "description": "0 if we're the lesser node_id, 1 if we're the greater" + } + } + } + }, + { + "if": { + "required": [ "inflight" ] + }, + "then": { + "additionalProperties": false, + "required": [ "initial_feerate", "last_feerate", "next_feerate", "next_fee_step" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "close_to_addr": { }, + "direction": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "initial_feerate": { + "type": "string", + "description": "The feerate for the initial funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "last_feerate": { + "type": "string", + "description": "The feerate for the latest funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "next_feerate": { + "type": "string", + "description": "The minimum feerate for the next funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "next_feestep": { + "type": "u32", + "description": "The number of fee steps so far, plus one" + } + } + } + } + ] + } + } + }, + "allOf": [ + { + "if": { + "additionalProperties": true, + "properties": { + "connected": { + "enum": [ true ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "netaddr", "features" ], + "properties": { + "id": { }, + "channels": { }, + "connected": { }, + "htlcs": { }, + "log": { }, + "last_tx_fee": { }, + "netaddr": { + "type": "array", + "minItems": 1, + "maxItems": 1, + "description": "A single entry array", + "items": { + "type": "string", + "description": "address, e.g. 1.2.3.4:1234" + } + }, + "features": { + "type": "hex", + "description": "bitmap of BOLT #9 features from peer's INIT message" } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/listsendpays.schema.json b/doc/schemas/listsendpays.schema.json new file mode 100644 index 000000000000..a66ec344b17b --- /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 000000000000..7539a892168d --- /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 000000000000..5022d32a9eda --- /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 000000000000..d8095507d2d6 --- /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 000000000000..4da493aacde5 --- /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 000000000000..b797a82c2f6f --- /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 000000000000..2c0e7000132d --- /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 000000000000..6c0886772f9d --- /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 000000000000..0d32cf526452 --- /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 000000000000..509a47022012 --- /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 000000000000..e345e6445cc1 --- /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 000000000000..cb144778e845 --- /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 000000000000..c820fc0234b1 --- /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 000000000000..b3bd48ccc092 --- /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 000000000000..5d0d132e787a --- /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 000000000000..fab8966e27ba --- /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 000000000000..8adcc03d3db6 --- /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 000000000000..df21950a697a --- /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 000000000000..24ab4f3732d4 --- /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 000000000000..6354c7d8208f --- /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 000000000000..64802e62852a --- /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 000000000000..d8095507d2d6 --- /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 000000000000..fab668c8ca00 --- /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 000000000000..4c866e72f751 --- /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 000000000000..f17efe20165b --- /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 000000000000..b4110edf934a --- /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 000000000000..33576f4179f9 --- /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 000000000000..7ee0df8c1ab6 --- /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 000000000000..51f87a2e89ef --- /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 000000000000..b816140344de --- /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 000000000000..85c150239ffd --- /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 000000000000..85ee1b6e7127 --- /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 000000000000..5b889377ea5f --- /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 000000000000..85ee1b6e7127 --- /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 000000000000..1ec0ff4d7d9e --- /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 000000000000..3e2dbac42cc2 --- /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" + } + } +} diff --git a/lightningd/opening_control.c b/lightningd/opening_control.c index 394b64525cf4..dc2432be9bc6 100644 --- a/lightningd/opening_control.c +++ b/lightningd/opening_control.c @@ -51,7 +51,7 @@ void json_add_uncommitted_channel(struct json_stream *response, json_object_start(response, NULL); json_add_string(response, "state", "OPENINGD"); json_add_string(response, "owner", "lightning_openingd"); - json_add_string(response, "funding", "LOCAL"); + json_add_string(response, "opener", "local"); if (uc->transient_billboard) { json_array_start(response, "status"); json_add_string(response, NULL, uc->transient_billboard); diff --git a/lightningd/options.c b/lightningd/options.c index e5d2cc1e812c..669355991542 100644 --- a/lightningd/options.c +++ b/lightningd/options.c @@ -962,7 +962,7 @@ static void register_opts(struct lightningd *ld) if (deprecated_apis) opt_register_noarg("--enable-autotor-v2-mode", opt_set_invbool, &ld->config.use_v3_autotor, - "Try to get a v2 onion address from the Tor service call, default is v3"); + opt_hidden); opt_register_noarg("--encrypted-hsm", opt_set_hsm_password, ld, "Set the password to encrypt hsm_secret with. If no password is passed through command line, " @@ -1265,6 +1265,13 @@ static void add_config(struct lightningd *ld, const char *answer = NULL; char buf[OPT_SHOW_LEN + sizeof("...")]; +#if DEVELOPER + if (strstarts(name0, "dev-")) { + /* Ignore dev settings */ + return; + } +#endif + if (opt->type & OPT_NOARG) { if (opt->desc == opt_hidden) { /* Ignore hidden options (deprecated) */ @@ -1278,18 +1285,16 @@ static void add_config(struct lightningd *ld, /* These are not important */ } else if (opt->cb == (void *)opt_set_bool) { const bool *b = opt->u.carg; - answer = tal_fmt(name0, "%s", *b ? "true" : "false"); + json_add_bool(response, name0, *b); } else if (opt->cb == (void *)opt_set_invbool) { const bool *b = opt->u.carg; - answer = tal_fmt(name0, "%s", !*b ? "true" : "false"); + json_add_bool(response, name0, !*b); } else if (opt->cb == (void *)opt_set_offline) { - answer = tal_fmt(name0, "%s", - (!ld->reconnect && !ld->listen) - ? "true" : "false"); + json_add_bool(response, name0, + !ld->reconnect && !ld->listen); } else if (opt->cb == (void *)opt_start_daemon) { - answer = tal_fmt(name0, "%s", - ld->daemon_parent_fd == -1 - ? "false" : "true"); + json_add_bool(response, name0, + ld->daemon_parent_fd != -1); } else if (opt->cb == (void *)opt_set_hsm_password) { json_add_bool(response, "encrypted-hsm", ld->encrypted_hsm); } else if (opt->cb == (void *)opt_set_wumbo) { @@ -1396,10 +1401,6 @@ static void add_config(struct lightningd *ld, || opt->cb_arg == (void *)plugin_opt_flag_set) { /* FIXME: We actually treat it as if they specified * --plugin for each one, so ignore these */ -#if DEVELOPER - } else if (strstarts(name, "dev-")) { - /* Ignore dev settings */ -#endif } else { /* Insert more decodes here! */ abort(); diff --git a/lightningd/peer_control.c b/lightningd/peer_control.c index 47957c1ab7aa..769557cc71f2 100644 --- a/lightningd/peer_control.c +++ b/lightningd/peer_control.c @@ -498,7 +498,7 @@ static void json_add_htlcs(struct lightningd *ld, json_add_u64(response, "id", hin->key.id); json_add_amount_msat_compat(response, hin->msat, "msatoshi", "amount_msat"); - json_add_u64(response, "expiry", hin->cltv_expiry); + json_add_u32(response, "expiry", hin->cltv_expiry); json_add_sha256(response, "payment_hash", &hin->payment_hash); json_add_string(response, "state", htlc_state_name(hin->hstate)); @@ -744,7 +744,10 @@ static void json_add_channel(struct lightningd *ld, bitcoin_txid(channel->last_tx, &txid); json_add_txid(response, "scratch_txid", &txid); - json_add_amount_sat_only(response, "last_tx_fee", + if (deprecated_apis) + json_add_amount_sat_only(response, "last_tx_fee", + bitcoin_tx_compute_fee(channel->last_tx)); + json_add_amount_sat_only(response, "last_tx_fee_msat", bitcoin_tx_compute_fee(channel->last_tx)); } @@ -847,7 +850,7 @@ static void json_add_channel(struct lightningd *ld, if (channel->closer != NUM_SIDES) json_add_string(response, "closer", channel->closer == LOCAL ? "local" : "remote"); - else + else if (deprecated_apis) json_add_null(response, "closer"); json_array_start(response, "features"); @@ -882,20 +885,27 @@ static void json_add_channel(struct lightningd *ld, our_msats = AMOUNT_MSAT(0); } - json_object_start(response, "funding_allocation_msat"); - json_add_u64(response, node_id_to_hexstr(tmpctx, &p->id), - peer_msats.millisatoshis); /* Raw: JSON field */ - json_add_u64(response, node_id_to_hexstr(tmpctx, &ld->id), - our_msats.millisatoshis); /* Raw: JSON field */ - json_object_end(response); + if (deprecated_apis) { + json_object_start(response, "funding_allocation_msat"); + json_add_u64(response, node_id_to_hexstr(tmpctx, &p->id), + peer_msats.millisatoshis); /* Raw: JSON field */ + json_add_u64(response, node_id_to_hexstr(tmpctx, &ld->id), + our_msats.millisatoshis); /* Raw: JSON field */ + json_object_end(response); + + json_object_start(response, "funding_msat"); + json_add_sat_only(response, + node_id_to_hexstr(tmpctx, &p->id), + peer_funded_sats); + json_add_sat_only(response, + node_id_to_hexstr(tmpctx, &ld->id), + channel->our_funds); + json_object_end(response); + } - json_object_start(response, "funding_msat"); - json_add_sat_only(response, - node_id_to_hexstr(tmpctx, &p->id), - peer_funded_sats); - json_add_sat_only(response, - node_id_to_hexstr(tmpctx, &ld->id), - channel->our_funds); + json_object_start(response, "funding"); + json_add_sat_only(response, "local_msat", channel->our_funds); + json_add_sat_only(response, "remote_msat", peer_funded_sats); json_object_end(response); if (!amount_sat_to_msat(&funding_msat, channel->funding)) { diff --git a/lightningd/plugin.c b/lightningd/plugin.c index 5c32c72e0757..ab53674655f2 100644 --- a/lightningd/plugin.c +++ b/lightningd/plugin.c @@ -74,7 +74,7 @@ struct plugins *plugins_new(const tal_t *ctx, struct log_book *log_book, p->log = new_log(p, log_book, NULL, "plugin-manager"); p->ld = ld; p->startup = true; - p->json_cmds = tal_arr(p, struct command *, 0); + p->plugin_cmds = tal_arr(p, struct plugin_command *, 0); p->blacklist = tal_arr(p, const char *, 0); p->shutdown = false; p->plugin_idx = 0; @@ -154,27 +154,27 @@ static void check_plugins_manifests(struct plugins *plugins) static void check_plugins_initted(struct plugins *plugins) { - struct command **json_cmds; + struct plugin_command **plugin_cmds; if (!plugins_all_in_state(plugins, INIT_COMPLETE)) return; /* Clear commands first, in case callbacks add new ones. * Paranoia, but wouldn't that be a nasty bug to find? */ - json_cmds = plugins->json_cmds; - plugins->json_cmds = tal_arr(plugins, struct command *, 0); - for (size_t i = 0; i < tal_count(json_cmds); i++) - plugin_cmd_all_complete(plugins, json_cmds[i]); - tal_free(json_cmds); + plugin_cmds = plugins->plugin_cmds; + plugins->plugin_cmds = tal_arr(plugins, struct plugin_command *, 0); + for (size_t i = 0; i < tal_count(plugin_cmds); i++) + plugin_cmd_all_complete(plugins, plugin_cmds[i]); + tal_free(plugin_cmds); } struct command_result *plugin_register_all_complete(struct lightningd *ld, - struct command *cmd) + struct plugin_command *pcmd) { if (plugins_all_in_state(ld->plugins, INIT_COMPLETE)) - return plugin_cmd_all_complete(ld->plugins, cmd); + return plugin_cmd_all_complete(ld->plugins, pcmd); - tal_arr_expand(&ld->plugins->json_cmds, cmd); + tal_arr_expand(&ld->plugins->plugin_cmds, pcmd); return NULL; } @@ -216,7 +216,7 @@ static void destroy_plugin(struct plugin *p) } struct plugin *plugin_register(struct plugins *plugins, const char* path TAKES, - struct command *start_cmd, bool important, + struct plugin_command *start_cmd, bool important, const char *parambuf STEALS, const jsmntok_t *params STEALS) { diff --git a/lightningd/plugin.h b/lightningd/plugin.h index 9fae129cf649..207ee3d42945 100644 --- a/lightningd/plugin.h +++ b/lightningd/plugin.h @@ -51,8 +51,9 @@ struct plugin { struct io_conn *stdin_conn, *stdout_conn; struct plugins *plugins; const char **plugin_path; + /* If there's a json command which ordered this to start */ - struct command *start_cmd; + struct plugin_command *start_cmd; enum plugin_state plugin_state; @@ -122,7 +123,7 @@ struct plugins { const char *default_dir; /* If there are json commands waiting for plugin resolutions. */ - struct command **json_cmds; + struct plugin_command **plugin_cmds; /* Blacklist of plugins from --disable-plugin */ const char **blacklist; @@ -222,7 +223,7 @@ void plugins_free(struct plugins *plugins); */ struct plugin *plugin_register(struct plugins *plugins, const char* path TAKES, - struct command *start_cmd, + struct plugin_command *start_cmd, bool important, const char *parambuf STEALS, const jsmntok_t *params STEALS); @@ -283,7 +284,7 @@ struct plugin *find_plugin_for_command(struct lightningd *ld, * plugin_cmd_all_complete(). */ struct command_result *plugin_register_all_complete(struct lightningd *ld, - struct command *cmd); + struct plugin_command *pcmd); /** * Send the configure message to all plugins. diff --git a/lightningd/plugin_control.c b/lightningd/plugin_control.c index f70ee71793a5..06aaf3f42570 100644 --- a/lightningd/plugin_control.c +++ b/lightningd/plugin_control.c @@ -6,21 +6,22 @@ #include /* A dummy structure used to give multiple arguments to callbacks. */ -struct dynamic_plugin { - struct plugin *plugin; +struct plugin_command { struct command *cmd; + const char *subcmd; }; /** * Returned by all subcommands on success. */ -static struct command_result *plugin_dynamic_list_plugins(struct command *cmd, +static struct command_result *plugin_dynamic_list_plugins(struct plugin_command *pcmd, const struct plugins *plugins) { struct json_stream *response; const struct plugin *p; - response = json_stream_success(cmd); + response = json_stream_success(pcmd->cmd); + json_add_string(response, "command", pcmd->subcmd); json_array_start(response, "plugins"); list_for_each(&plugins->plugins, p, list) { json_object_start(response, NULL); @@ -30,25 +31,25 @@ static struct command_result *plugin_dynamic_list_plugins(struct command *cmd, json_object_end(response); } json_array_end(response); - return command_success(cmd, response); + return command_success(pcmd->cmd, response); } -struct command_result *plugin_cmd_killed(struct command *cmd, +struct command_result *plugin_cmd_killed(struct plugin_command *pcmd, struct plugin *plugin, const char *msg) { - return command_fail(cmd, PLUGIN_ERROR, "%s: %s", plugin->cmd, msg); + return command_fail(pcmd->cmd, PLUGIN_ERROR, "%s: %s", plugin->cmd, msg); } -struct command_result *plugin_cmd_succeeded(struct command *cmd, +struct command_result *plugin_cmd_succeeded(struct plugin_command *pcmd, struct plugin *plugin) { - return plugin_dynamic_list_plugins(cmd, plugin->plugins); + return plugin_dynamic_list_plugins(pcmd, plugin->plugins); } struct command_result *plugin_cmd_all_complete(struct plugins *plugins, - struct command *cmd) + struct plugin_command *pcmd) { - return plugin_dynamic_list_plugins(cmd, plugins); + return plugin_dynamic_list_plugins(pcmd, plugins); } /** @@ -56,25 +57,25 @@ struct command_result *plugin_cmd_all_complete(struct plugins *plugins, * will give a result 60 seconds later at the most (once init completes). */ static struct command_result * -plugin_dynamic_start(struct command *cmd, const char *plugin_path, +plugin_dynamic_start(struct plugin_command *pcmd, const char *plugin_path, const char *buffer, const jsmntok_t *params) { - struct plugin *p = plugin_register(cmd->ld->plugins, plugin_path, cmd, false, buffer, params); + struct plugin *p = plugin_register(pcmd->cmd->ld->plugins, plugin_path, pcmd, false, buffer, params); const char *err; if (!p) - return command_fail(cmd, JSONRPC2_INVALID_PARAMS, + return command_fail(pcmd->cmd, JSONRPC2_INVALID_PARAMS, "%s: already registered", plugin_path); /* This will come back via plugin_cmd_killed or plugin_cmd_succeeded */ err = plugin_send_getmanifest(p); if (err) - return command_fail(cmd, PLUGIN_ERROR, + return command_fail(pcmd->cmd, PLUGIN_ERROR, "%s: %s", plugin_path, err); - return command_still_pending(cmd); + return command_still_pending(pcmd->cmd); } /** @@ -82,22 +83,22 @@ plugin_dynamic_start(struct command *cmd, const char *plugin_path, * all contained plugins recursively and then starts them. */ static struct command_result * -plugin_dynamic_startdir(struct command *cmd, const char *dir_path) +plugin_dynamic_startdir(struct plugin_command *pcmd, const char *dir_path) { const char *err; struct command_result *res; - err = add_plugin_dir(cmd->ld->plugins, dir_path, false); + err = add_plugin_dir(pcmd->cmd->ld->plugins, dir_path, false); if (err) - return command_fail(cmd, JSONRPC2_INVALID_PARAMS, "%s", err); + return command_fail(pcmd->cmd, JSONRPC2_INVALID_PARAMS, "%s", err); /* If none added, this calls plugin_cmd_all_complete immediately */ - res = plugin_register_all_complete(cmd->ld, cmd); + res = plugin_register_all_complete(pcmd->cmd->ld, pcmd); if (res) return res; - plugins_send_getmanifest(cmd->ld->plugins); - return command_still_pending(cmd); + plugins_send_getmanifest(pcmd->cmd->ld->plugins); + return command_still_pending(pcmd->cmd); } static struct command_result * @@ -116,6 +117,7 @@ plugin_dynamic_stop(struct command *cmd, const char *plugin_name) plugin_kill(p, LOG_INFORM, "stopped by lightningd via RPC"); response = json_stream_success(cmd); + json_add_string(response, "command", "stop"); json_add_string(response, "result", take(tal_fmt(NULL, "Successfully stopped %s.", plugin_name))); @@ -131,20 +133,20 @@ plugin_dynamic_stop(struct command *cmd, const char *plugin_name) * Look for additions in the default plugin directory. */ static struct command_result * -plugin_dynamic_rescan_plugins(struct command *cmd) +plugin_dynamic_rescan_plugins(struct plugin_command *pcmd) { struct command_result *res; /* This will not fail on "already registered" error. */ - plugins_add_default_dir(cmd->ld->plugins); + plugins_add_default_dir(pcmd->cmd->ld->plugins); /* If none added, this calls plugin_cmd_all_complete immediately */ - res = plugin_register_all_complete(cmd->ld, cmd); + res = plugin_register_all_complete(pcmd->cmd->ld, pcmd); if (res) return res; - plugins_send_getmanifest(cmd->ld->plugins); - return command_still_pending(cmd); + plugins_send_getmanifest(pcmd->cmd->ld->plugins); + return command_still_pending(pcmd->cmd); } /** @@ -156,6 +158,7 @@ static struct command_result *json_plugin_control(struct command *cmd, const jsmntok_t *obj UNNEEDED, const jsmntok_t *params) { + struct plugin_command *pcmd; const char *subcmd; subcmd = param_subcommand(cmd, buffer, params, "start", "stop", "startdir", @@ -163,6 +166,10 @@ static struct command_result *json_plugin_control(struct command *cmd, if (!subcmd) return command_param_failed(); + pcmd = tal(cmd, struct plugin_command); + pcmd->cmd = cmd; + pcmd->subcmd = subcmd; + if (streq(subcmd, "stop")) { const char *plugin_name; @@ -202,7 +209,7 @@ static struct command_result *json_plugin_control(struct command *cmd, "plugin") - 1, 1); } if (access(plugin_path, X_OK) == 0) - return plugin_dynamic_start(cmd, plugin_path, + return plugin_dynamic_start(pcmd, plugin_path, buffer, mod_params); else return command_fail(cmd, JSONRPC2_INVALID_PARAMS, @@ -218,7 +225,7 @@ static struct command_result *json_plugin_control(struct command *cmd, return command_param_failed(); if (access(dir_path, F_OK) == 0) - return plugin_dynamic_startdir(cmd, dir_path); + return plugin_dynamic_startdir(pcmd, dir_path); else return command_fail(cmd, JSONRPC2_INVALID_PARAMS, "Could not open %s", dir_path); @@ -228,14 +235,14 @@ static struct command_result *json_plugin_control(struct command *cmd, NULL)) return command_param_failed(); - return plugin_dynamic_rescan_plugins(cmd); + return plugin_dynamic_rescan_plugins(pcmd); } else if (streq(subcmd, "list")) { if (!param(cmd, buffer, params, p_req("subcommand", param_ignore, cmd), NULL)) return command_param_failed(); - return plugin_dynamic_list_plugins(cmd, cmd->ld->plugins); + return plugin_dynamic_list_plugins(pcmd, cmd->ld->plugins); } /* subcmd must be one of the above: param_subcommand checked it! */ diff --git a/lightningd/plugin_control.h b/lightningd/plugin_control.h index 8d1e6ffbf9a8..655149081ec3 100644 --- a/lightningd/plugin_control.h +++ b/lightningd/plugin_control.h @@ -3,16 +3,18 @@ #include "config.h" #include +struct plugin_command; + /* Plugin startup failed */ -struct command_result *plugin_cmd_killed(struct command *cmd, +struct command_result *plugin_cmd_killed(struct plugin_command *pcmd, struct plugin *plugin, const char *msg); /* Plugin startup succeeded */ -struct command_result *plugin_cmd_succeeded(struct command *cmd, +struct command_result *plugin_cmd_succeeded(struct plugin_command *pcmd, struct plugin *plugin); /* All plugins succeeded/failed */ struct command_result *plugin_cmd_all_complete(struct plugins *plugins, - struct command *cmd); + struct plugin_command *pcmd); #endif /* LIGHTNING_LIGHTNINGD_PLUGIN_CONTROL_H */ diff --git a/tests/test_connection.py b/tests/test_connection.py index ecadb4b208a5..413055014556 100644 --- a/tests/test_connection.py +++ b/tests/test_connection.py @@ -1895,7 +1895,7 @@ def _connect_str(node): assert only_one(only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'])['feerate']['perkw'] == commitment_tx_feerate_int assert only_one(only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'])['feerate']['perkb'] == commitment_tx_feerate_int * 4 - txfee = only_one(only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'])['last_tx_fee'] + txfee = only_one(only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'])['last_tx_fee_msat'] # We get the expected close txid, force close the channel, then fish # the details about the transaction out of the mempoool entry @@ -1923,7 +1923,7 @@ def _connect_str(node): expected_fee += 330 assert expected_fee == entry['fees']['base'] * 10 ** 8 - assert Millisatoshi(str(expected_fee) + 'sat') == Millisatoshi(txfee) + assert Millisatoshi(str(expected_fee) + 'sat') == txfee def test_multifunding_param_failures(node_factory): @@ -3326,8 +3326,8 @@ def test_wumbo_channels(node_factory, bitcoind): wait_for(lambda: 'CHANNELD_NORMAL' in [c['state'] for c in only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels']]) # Exact amount depends on fees, but it will be wumbo! - amount = [c['funding_msat'][l1.info['id']] for c in only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'] if c['state'] == 'CHANNELD_NORMAL'][0] - assert Millisatoshi(amount) > Millisatoshi(str((1 << 24) - 1) + "sat") + amount = [c['funding']['local_msat'] for c in only_one(l1.rpc.listpeers(l2.info['id'])['peers'])['channels'] if c['state'] == 'CHANNELD_NORMAL'][0] + assert amount > Millisatoshi(str((1 << 24) - 1) + "sat") @pytest.mark.openchannel('v1') diff --git a/tests/test_plugin.py b/tests/test_plugin.py index a86d66298242..01f4760cd353 100644 --- a/tests/test_plugin.py +++ b/tests/test_plugin.py @@ -720,9 +720,9 @@ def wait_for_event(node): # check channel 'opener' and 'closer' within this testcase ... assert(l1.rpc.listpeers()['peers'][0]['channels'][0]['opener'] == 'local') assert(l2.rpc.listpeers()['peers'][0]['channels'][0]['opener'] == 'remote') - # the 'closer' should be null initially - assert(l2.rpc.listpeers()['peers'][0]['channels'][0]['closer'] is None) - assert(l2.rpc.listpeers()['peers'][0]['channels'][0]['closer'] is None) + # the 'closer' should be missing initially + assert 'closer' not in l1.rpc.listpeers()['peers'][0]['channels'][0] + assert 'closer' not in l2.rpc.listpeers()['peers'][0]['channels'][0] event1 = wait_for_event(l1) event2 = wait_for_event(l2) @@ -1385,6 +1385,9 @@ def test_rpc_command_hook(node_factory): assert decoded["description"] == "rpc_command_1 modified this description" l1.daemon.wait_for_log("rpc_command hook 'invoice' already modified, ignoring.") + # Disable schema checking here! + schemas = l1.rpc.jsonschemas + l1.rpc.jsonschemas = {} # rpc_command_1 plugin sends a custom response to "listfunds" funds = l1.rpc.listfunds() assert funds[0] == "Custom rpc_command_1 result" @@ -1404,6 +1407,8 @@ def test_rpc_command_hook(node_factory): l1.rpc.plugin_stop('rpc_command_1.py') l1.rpc.plugin_stop('rpc_command_2.py') + l1.rpc.jsonschemas = schemas + def test_libplugin(node_factory): """Sanity checks for plugins made with libplugin""" diff --git a/tests/test_wallet.py b/tests/test_wallet.py index d7c809da8d8b..aca6c9ce5c2d 100644 --- a/tests/test_wallet.py +++ b/tests/test_wallet.py @@ -937,7 +937,7 @@ def test_transaction_annotations(node_factory, bitcoind): assert(len(txs) == 1) tx = txs[0] output = tx['outputs'][idx] - assert(output['type'] == 'deposit' and output['satoshis'] == '1000000000msat') + assert(output['type'] == 'deposit' and output['msat'] == Millisatoshi(1000000000)) # ... and all other output should be change, and have no annotations types = [] diff --git a/tools/fromschema.py b/tools/fromschema.py index a4d655336809..b15141b0d3bd 100755 --- a/tools/fromschema.py +++ b/tools/fromschema.py @@ -14,6 +14,8 @@ def json_value(obj): return '*false*' if type(obj) is str: return '"' + obj + '"' + if obj is None: + return '*null*' assert False @@ -28,7 +30,11 @@ def output(line): def output_type(properties, is_optional): - typename = properties['type'] + # FIXME: there's a horrible hack for listpeers' closer which can be NULL + if type(properties['type']) is list: + typename = properties['type'][0] + else: + typename = properties['type'] if typename == 'array': typename += ' of {}s'.format(properties['items']['type']) if is_optional: @@ -63,10 +69,17 @@ def output_range(properties): output(' (one of {})'.format(', '.join([json_value(p) for p in properties['enum']]))) -def output_member(propname, properties, is_optional, indent, print_type=True): +def output_member(propname, properties, is_optional, indent, print_type=True, prefix=None): """Generate description line(s) for this member""" - output(indent + '- **{}**'.format(propname)) - if print_type: + + if prefix is None: + prefix = '- **{}**'.format(propname) + output(indent + prefix) + + # We make them explicitly note if they don't want a type! + is_untyped = 'untyped' in properties + + if not is_untyped and print_type: output_type(properties, is_optional) if 'description' in properties: @@ -74,10 +87,10 @@ def output_member(propname, properties, is_optional, indent, print_type=True): output_range(properties) - if properties['type'] == 'object': + if not is_untyped and properties['type'] == 'object': output(':\n') output_members(properties, indent + ' ') - elif properties['type'] == 'array': + elif not is_untyped and properties['type'] == 'array': output(':\n') output_array(properties['items'], indent + ' ') else: @@ -97,6 +110,17 @@ def output_array(items, indent): output('\n') +def has_members(sub): + """Does this sub have any properties to print?""" + for p in list(sub['properties'].keys()): + if len(sub['properties'][p]) == 0: + continue + if 'deprecated' in sub['properties'][p]: + continue + return True + return False + + def output_members(sub, indent=''): """Generate lines for these properties""" warnings = [] @@ -161,15 +185,20 @@ def output_members(sub, indent=''): conditions.append(cond) sentence = indent + "If " + ", and ".join(conditions) + ":\n" - # Prefix with blank line. - outputs(['\n', sentence]) - output_members(ifclause['then'], indent + ' ') + if has_members(ifclause['then']): + # Prefix with blank line. + outputs(['\n', sentence]) + + output_members(ifclause['then'], indent + ' ') def generate_from_schema(schema): """This is not general, but works for us""" - assert schema['type'] == 'object' + if schema['type'] != 'object': + # 'stop' returns a single string! + output_member(None, schema, False, '', prefix='On success, returns a single element') + return toplevels = [] warnings = [] diff --git a/wallet/walletrpc.c b/wallet/walletrpc.c index 8bf0f6ccea0c..96f33e7cb41e 100644 --- a/wallet/walletrpc.c +++ b/wallet/walletrpc.c @@ -506,7 +506,7 @@ static void json_transaction_details(struct json_stream *response, json_object_start(response, NULL); json_add_txid(response, "hash", &tx->id); json_add_hex_talarr(response, "rawtx", tx->rawtx); - json_add_u64(response, "blockheight", tx->blockheight); + json_add_num(response, "blockheight", tx->blockheight); json_add_num(response, "txindex", tx->txindex); #if EXPERIMENTAL_FEATURES if (tx->annotation.type != 0) @@ -556,7 +556,9 @@ static void json_transaction_details(struct json_stream *response, json_object_start(response, NULL); json_add_u32(response, "index", i); - json_add_amount_sat_only(response, "satoshis", sat); + if (deprecated_apis) + json_add_amount_sat_only(response, "satoshis", sat); + json_add_amount_sat_only(response, "msat", sat); #if EXPERIMENTAL_FEATURES struct tx_annotation *ann = &tx->output_annotations[i];