From fbc26720746bd818f51020eee122a00b45d8f68e Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 26 May 2021 15:25:01 +0930 Subject: [PATCH] doc/schemas: delexpiredinvoice, delinvoice, delpay. Signed-off-by: Rusty Russell --- doc/lightning-delexpiredinvoice.7 | 2 +- doc/lightning-delexpiredinvoice.7.md | 3 + doc/lightning-delinvoice.7 | 43 +++++++++++- doc/lightning-delinvoice.7.md | 22 ++++++- doc/lightning-delpay.7 | 39 ++++++++++- doc/lightning-delpay.7.md | 23 ++++++- doc/schemas/delexpiredinvoice.schema.json | 8 +++ doc/schemas/delinvoice.schema.json | 79 +++++++++++++++++++++++ doc/schemas/delpay.schema.json | 75 +++++++++++++++++++++ 9 files changed, 283 insertions(+), 11 deletions(-) create mode 100644 doc/schemas/delexpiredinvoice.schema.json create mode 100644 doc/schemas/delinvoice.schema.json create mode 100644 doc/schemas/delpay.schema.json diff --git a/doc/lightning-delexpiredinvoice.7 b/doc/lightning-delexpiredinvoice.7 index a71442906..680de0f12 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:f7cd68f4d2ef071b45ee705da17a1180775096a2cc64c370822c8c610d1a3979 +\" SHA256STAMP:a47d47609d9b39bbe6c0f0c61e28d255ceb496a49ad306db22ef23011c6f8cb8 diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md index ecf22b3cc..0f12ecbb8 100644 --- a/doc/lightning-delexpiredinvoice.7.md +++ b/doc/lightning-delexpiredinvoice.7.md @@ -18,7 +18,9 @@ deleted. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) On success, an empty object is returned. +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -35,3 +37,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:f267fd509a5e3e55e2322ddc8b233eb820638ed5f50f606e3e6c8ae17f1c8421) diff --git a/doc/lightning-delinvoice.7 b/doc/lightning-delinvoice.7 index 876fbde1a..ef620be23 100644 --- a/doc/lightning-delinvoice.7 +++ b/doc/lightning-delinvoice.7 @@ -16,9 +16,46 @@ The caller should be particularly aware of the error case caused by the .SH RETURN VALUE -On success, an invoice description will be returned as per -\fBlightning-listinvoice\fR(7)\. +Note: The return is the same as an object from \fBlightning-listinvoice\fR(7)\. + +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBlabel\fR (string): Unique label given at creation time +.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) +.IP \[bu] +\fBbolt11\fR (string, optional): BOLT11 string +.IP \[bu] +\fBbolt12\fR (string, optional): BOLT12 string + +.RE + +If \fBbolt12\fR is present: + +.RS +.IP \[bu] +\fBlocal_offer_id\fR (hex, optional): offer for which this invoice was created + +.RE + +If \fBstatus\fR is "paid": + +.RS +.IP \[bu] +\fBpay_index\fR (u64): unique index for this invoice payment +.IP \[bu] +\fBamount_received_msat\fR (msat): how much was actually received +.IP \[bu] +\fBpaid_at\fR (u64): UNIX timestamp of when payment was received +.IP \[bu] +\fBpayment_preimage\fR (hex): SHA256 of this is the \fIpayment_hash\fR offered in the invoice (always 64 characters) + +.RE .SH ERRORS The following errors may be reported: @@ -50,4 +87,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:92ad4501574b253334bb570960d1835c8bd84483e318ea058e6b565d34109832 +\" SHA256STAMP:28d1e97fe8e8925008b20815c55db569b7ed8dad33d958c0914945c71fb9d654 diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md index 96feb506d..c699bc7de 100644 --- a/doc/lightning-delinvoice.7.md +++ b/doc/lightning-delinvoice.7.md @@ -18,8 +18,25 @@ The caller should be particularly aware of the error case caused by the RETURN VALUE ------------ -On success, an invoice description will be returned as per -lightning-listinvoice(7). +Note: The return is the same as an object from lightning-listinvoice(7). + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **label** (string): Unique label given at creation time +- **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 + +If **bolt12** is present: + - **local_offer_id** (hex, optional): offer for which this invoice was created + +If **status** is "paid": + - **pay_index** (u64): unique index for this invoice payment + - **amount_received_msat** (msat): how much was actually received + - **paid_at** (u64): UNIX timestamp of when payment was received + - **payment_preimage** (hex): SHA256 of this is the *payment_hash* offered in the invoice (always 64 characters) +[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -51,3 +68,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:8cd84ec57d229dacb6d6c52510334da87846f1c8eea7db286063a2513e8318cb) diff --git a/doc/lightning-delpay.7 b/doc/lightning-delpay.7 index 356bf9862..2a20c2445 100644 --- a/doc/lightning-delpay.7 +++ b/doc/lightning-delpay.7 @@ -33,10 +33,43 @@ Only deletes if the payment status matches\. .fi .SH RETURN VALUE -If successful the command returns a payment object, in the same format as \fBlistsendpays\fR\. If the payment is a multi-part payment (MPP) the command return a list of -payments will be return -- one payment object for each partid\. +The returned format is the same as \fBlightning-listsendpays\fR(7)\. If the +payment is a multi-part payment (MPP) the command return a list of +payments will be returned -- one payment object for each partid\. +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] +\fBamount_sent_msat\fR (msat): the amount we actually sent, including fees +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated +.IP \[bu] +\fBpartid\fR (u64, optional): unique ID within this (multi-part) payment +.IP \[bu] +\fBdestination\fR (pubkey, optional): the final destination of the payment if known +.IP \[bu] +\fBamount_msat\fR (msat, optional): the amount the destination received, if known +.IP \[bu] +\fBpayment_preimage\fR (hex, optional): proof of payment (always 64 characters) +.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)\. +.IP \[bu] +\fBerroronion\fR (hex, optional): the error onion returned on failure, if any\. + +.RE + On failure, an error is returned\. If the lightning process fails before responding, the caller should use \fBlightning-listsentpays\fR(7) or \fBlightning-listpays\fR(7) to query whether this payment was deleted or not\. @@ -87,4 +120,4 @@ Vincenzo Palazzo \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:b10dd430aaace8b9f3607e72c871e2a883934f9a51d5bc0068a024df5ef1d6ee +\" SHA256STAMP:520f0b56c7288ed46509a0ab90be0959b3b1489b56b7e94f223de19cf7028758 diff --git a/doc/lightning-delpay.7.md b/doc/lightning-delpay.7.md index 8c9a78f27..d3c7094a4 100644 --- a/doc/lightning-delpay.7.md +++ b/doc/lightning-delpay.7.md @@ -31,8 +31,26 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -If successful the command returns a payment object, in the same format as **listsendpays**. If the payment is a multi-part payment (MPP) the command return a list of -payments will be return -- one payment object for each partid. +The returned format is the same as lightning-listsendpays(7). If the +payment is a multi-part payment (MPP) the command return a list of +payments will be returned -- one payment object for each partid. + +[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") +- **amount_sent_msat** (msat): the amount we actually sent, including fees +- **created_at** (u64): the UNIX timestamp showing when this payment was initiated +- **partid** (u64, optional): unique ID within this (multi-part) payment +- **destination** (pubkey, optional): the final destination of the payment if known +- **amount_msat** (msat, optional): the amount the destination received, if known +- **payment_preimage** (hex, optional): proof of payment (always 64 characters) +- **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). +- **erroronion** (hex, optional): the error onion returned on failure, if any. +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, an error is returned. If the lightning process fails before responding, the caller should use lightning-listsentpays(7) or lightning-listpays(7) to query whether this payment was deleted or not. @@ -81,3 +99,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:26e293e5b3de31a95572763a6d7c360c0f9f78112b3fcef12c639d001b0fa9b5) diff --git a/doc/schemas/delexpiredinvoice.schema.json b/doc/schemas/delexpiredinvoice.schema.json new file mode 100644 index 000000000..3f3efd17a --- /dev/null +++ b/doc/schemas/delexpiredinvoice.schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ ], + "additionalProperties": false, + "properties": { + } +} diff --git a/doc/schemas/delinvoice.schema.json b/doc/schemas/delinvoice.schema.json new file mode 100644 index 000000000..846237a30 --- /dev/null +++ b/doc/schemas/delinvoice.schema.json @@ -0,0 +1,79 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "label", "payment_hash", "amount_msat", "status", "expires_at" ], + "additionalProperties": true, + "properties": { + "label": { + "type": "string", + "description": "Unique label given at creation time" + }, + "bolt11": { + "type": "string", + "description": "BOLT11 string" + }, + "bolt12": { + "type": "string", + "description": "BOLT12 string" + }, + "status": { + "type": "string", + "description": "State of invoice", + "enum": [ "paid", "expired", "unpaid" ] + }, + "expires_at": { + "type": "u64", + "description": "UNIX timestamp when invoice expires (or expired)" + } + }, + "allOf": [ + { + "if": { + "required": [ "bolt12" ] + }, + "then": { + "required": [ ], + "properties": { + "local_offer_id": { + "type": "hex", + "description": "offer for which this invoice was created" + } + } + } + }, + { + "if": { + "properties": { + "status": { + "type": "string", + "enum": [ "paid" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "pay_index", "amount_received_msat", "paid_at", "payment_preimage" ], + "properties": { + "pay_index": { + "type": "u64", + "description": "unique index for this invoice payment" + }, + "amount_received_msat": { + "type": "msat", + "description": "how much was actually received" + }, + "paid_at": { + "type": "u64", + "description": "UNIX timestamp of when payment was received" + }, + "payment_preimage": { + "type": "hex", + "description": "SHA256 of this is the *payment_hash* offered in the invoice", + "maxLength": 64, + "minLength": 64 + } + } + } + } + ] +} diff --git a/doc/schemas/delpay.schema.json b/doc/schemas/delpay.schema.json new file mode 100644 index 000000000..3a1ed1ba6 --- /dev/null +++ b/doc/schemas/delpay.schema.json @@ -0,0 +1,75 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "payments" ], + "additionalProperties": false, + "properties": { + "payments": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "id", "payment_hash", "status", "amount_sent_msat", "created_at" ], + "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" + }, + "amount_sent_msat": { + "type": "msat", + "description": "the amount we actually sent, including fees" + }, + "partid": { + "type": "u64", + "description": "unique ID within this (multi-part) payment" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment if known" + }, + "amount_msat": { + "type": "msat", + "description": "the amount the destination received, if known" + }, + "created_at": { + "type": "u64", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "payment_preimage": { + "type": "hex", + "description": "proof of payment", + "maxLength": 64, + "minLength": 64 + }, + "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)." + }, + "erroronion": { + "type": "hex", + "description": "the error onion returned on failure, if any." + } + } + } + } + } +}