diff --git a/doc/Makefile b/doc/Makefile index abc5bd35c..30f4804d7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -86,12 +86,23 @@ MANPAGES := doc/lightning-cli.1 \ doc-all: $(MANPAGES) doc/index.rst +# Some manpages use a schema, so need that added. +MARKDOWN_WITH_SCHEMA := $(shell grep -l GENERATE-FROM-SCHEMA $(MANPAGES:=.md)) + +# These are hard to use in $(call) functions. +LBRACKET=( +RBRACKET=) + +$(MARKDOWN_WITH_SCHEMA): doc/lightning-%.7.md: doc/schemas/%.schema.json tools/fromschema.py + @if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "fromschema $@", tools/fromschema.py --markdownfile=$@ doc/schemas/$*.schema.json > $@.tmp && grep -v SHA256STAMP: $@.tmp > $@ && rm -f $@.tmp && $(call SHA256STAMP,[comment]: # $(LBRACKET),$(RBRACKET))); else touch $@; fi + # mrkd doesn't format nested lists properly, so we fixup with sed (see doc/lightning-connect.7 # and https://github.com/refi64/mrkd/issues/4 $(MANPAGES): doc/%: doc/%.md @if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "mrkd $<", mrkd $< $@.tmp && sed -e 's/\(.\)\.RS$$/\1\n.RS/' < $@.tmp > $@ && rm $@.tmp && $(call SHA256STAMP,\\\",)); else touch $@; fi $(MANPAGES): $(FORCE) +$(MARKDOWN_WITH_SCHEMA): $(FORCE) doc/protocol-%.svg: test/test_protocol test/test_protocol --svg < test/commits/$*.script > $@ diff --git a/doc/lightning-listpays.7 b/doc/lightning-listpays.7 index 8d0f0a0aa..0d2c828a1 100644 --- a/doc/lightning-listpays.7 +++ b/doc/lightning-listpays.7 @@ -12,56 +12,53 @@ single one if either \fIbolt11\fR or \fIpayment_hash\fR was specified\. .SH RETURN VALUE -On success, an array of objects is returned\. Each object contains: +On success, an object containing \fBpays\fR is returned\. It is an array of objects, where each object contains: +.RS +.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] +\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)\. - \fIbolt11\fR -the \fIbolt11\fR invoice if provided to \fBpay\fR\. +.RE +If \fBstatus\fR is "pending" or "complete": - \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\. +.RS +.IP \[bu] +\fBamount_sent_msat\fR (msat): the amount we actually sent, including fees +.IP \[bu] +\fBamount_msat\fR (msat, optional): the amount the destination received, if known +.RE - \fIpayment_hash\fR -the \fIpayment_hash\fR of the payment\. +If \fBstatus\fR is "complete": +.RS +.IP \[bu] +\fBpreimage\fR (hex): proof of payment (always 64 characters) +.IP \[bu] +\fBnumber_of_parts\fR (u64, optional): the number of parts for a successful payment (only if more than one)\. - \fIstatus\fR -one of \fIcomplete\fR, \fIfailed\fR or \fIpending\fR\. +.RE +If \fBstatus\fR is "failed": - \fIpayment_preimage\fR -if \fIstatus\fR is \fIcomplete\fR\. - - - \fIlabel\fR -optional \fIlabel\fR, if provided to \fIpay\fR or \fIsendonion\fR\. - - - \fIamount_sent_msat\fR -total amount sent, in "NNNmsat" format\. - - -For old payments (pre-0\.7) we didn’t save the \fIbolt11\fR string, so in its -place are three other fields: - - - \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\. - - -These three can all be extracted from \fIbolt11\fR, hence are obsolete\. +.RS +.IP \[bu] +\fBerroronion\fR (hex, optional): the error onion returned on failure, if any\. +.RE .SH AUTHOR Rusty Russell \fI is mainly responsible\. @@ -74,4 +71,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:5a0e016e18f52ce18484d064c3e659aca2687eeafca4b4365e3037faa1fba53f +\" SHA256STAMP:e27d57394bef9bdaf9b99ae0d9050c9044c194ab66f6c94c43b532a86e1a0031 diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md index 87cab6a68..0ade89123 100644 --- a/doc/lightning-listpays.7.md +++ b/doc/lightning-listpays.7.md @@ -15,43 +15,27 @@ single one if either *bolt11* or *payment_hash* was specified. RETURN VALUE ------------ -On success, an array of objects is returned. Each object contains: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **pays** is returned. It is an array of objects, where each object contains: +- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters) +- **status** (string): status of the payment (one of "pending", "failed", "complete") +- **created_at** (u64): the UNIX timestamp showing when this payment was initiated +- **destination** (pubkey, optional): the final destination of the payment if known +- **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). - *bolt11* -the *bolt11* invoice if provided to `pay`. +If **status** is "pending" or "complete": + - **amount_sent_msat** (msat): the amount we actually sent, including fees + - **amount_msat** (msat, optional): the amount the destination received, if known - *bolt12* -if **experimental-offers** is enabled, and `pay` was a given a bolt12 -invoice, this field will appear instead of *bolt11*. +If **status** is "complete": + - **preimage** (hex): proof of payment (always 64 characters) + - **number_of_parts** (u64, optional): the number of parts for a successful payment (only if more than one). - *payment_hash* -the *payment_hash* of the payment. - - *status* -one of *complete*, *failed* or *pending*. - - *payment\_preimage* -if *status* is *complete*. - - *label* -optional *label*, if provided to *pay* or *sendonion*. - - *amount\_sent\_msat* -total amount sent, in "NNNmsat" format. - -For old payments (pre-0.7) we didn’t save the *bolt11* string, so in its -place are three other fields: - - *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. - -These three can all be extracted from *bolt11*, hence are obsolete. +If **status** is "failed": + - **erroronion** (hex, optional): the error onion returned on failure, if any. +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -68,3 +52,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:12e7b91fc59ee65b61d9aba4e8586fda8fbb524a7e548ffa36862e204952c46b) diff --git a/doc/schemas/listpays.schema.json b/doc/schemas/listpays.schema.json index 15d0e685b..82c9e4548 100644 --- a/doc/schemas/listpays.schema.json +++ b/doc/schemas/listpays.schema.json @@ -2,12 +2,14 @@ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "additionalProperties": false, + "required": [ "pays" ], "properties": { "pays": { "type": "array", "items": { "type": "object", - "additionalProperties": false, + "additionalProperties": true, + "required": [ "payment_hash", "status", "created_at" ], "properties": { "payment_hash": { "type": "hex", @@ -24,25 +26,10 @@ "type": "pubkey", "description": "the final destination of the payment if known" }, - "amount_msat": { - "type": "msat", - "description": "the amount the destination received, if known (**status** *complete* or *pending*)" - }, - "amount_sent_msat": { - "type": "msat", - "description": "the amount we actually sent, including fees (**status** *complete* or *pending*)" - }, "created_at": { "type": "u64", "description": "the UNIX timestamp showing when this payment was initiated" }, - "preimage": { - "type": "hex", - "description": "proof of payment, only if (and always if) **status** is *complete*", - "FIXME": "we should enforce the status/payment_preimage relation in the schema!", - "maxLength": 64, - "minLength": 64 - }, "label": { "type": "string", "description": "the label, if given to sendpay" @@ -54,19 +41,106 @@ "bolt12": { "type": "string", "description": "the bolt12 string (if supplied for pay: **experimental-offers** only)." - }, - "erroronion": { - "type": "hex", - "description": "the error onion returned on failure, if any." - }, - "number_of_parts": { - "type": "u64", - "description": "the number of parts for a successful payment (only if more than one, and **status** is *complete*)." } }, - "required": [ "payment_hash", "status", "created_at" ] + "allOf": [ + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "pending", "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "amount_sent_msat" ], + "properties": { + "payment_hash": { }, + "status": { }, + "destination": { }, + "created_at": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "preimage": { }, + "number_of_parts": { }, + "amount_msat": { + "type": "msat", + "description": "the amount the destination received, if known" + }, + "amount_sent_msat": { + "type": "msat", + "description": "the amount we actually sent, including fees" + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "complete" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "preimage" ], + "properties": { + "payment_hash": { }, + "status": { }, + "destination": { }, + "created_at": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "amount_msat": { }, + "amount_sent_msat": { }, + "preimage": { + "type": "hex", + "description": "proof of payment", + "maxLength": 64, + "minLength": 64 + }, + "number_of_parts": { + "type": "u64", + "description": "the number of parts for a successful payment (only if more than one)." + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "failed" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "payment_hash": { }, + "status": { }, + "destination": { }, + "created_at": { }, + "label": { }, + "bolt11": { }, + "bolt12": { }, + "erroronion": { + "type": "hex", + "description": "the error onion returned on failure, if any." + } + } + } + } + ] } } - }, - "required": [ "pays" ] + } }