diff --git a/doc/lightning-listinvoices.7 b/doc/lightning-listinvoices.7 index 45ef8486d..f9385b9b8 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:9567c510a5ab2fd47149c7f6e213c65eaa0ab5f29adbe649838986d70049b56b diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md index e78aa40ce..3a3531f26 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:912e82238ba0d47bae3ce8f8e16f22cf5f2c62936efb150092f17766abdb4455) diff --git a/doc/lightning-listnodes.7 b/doc/lightning-listnodes.7 index a80ef7b13..bd9af3606 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\. +\fBalias\fR (string): The fun alias this node advertized (up to 32 characters) .IP \[bu] -\fIcolor\fR: A string that represents the personal color of the node\. +\fBcolor\fR (hex): The favorite RGB color this node advertized (always 6 characters) .IP \[bu] -\fIlast_timestamp\fR: An integer that represents the timestamp of the last-received node_announcement message\. +\fBfeatures\fR (hex): BOLT #9 features bitmap this node advertized .IP \[bu] -\fIfeatures\fR: A string that represents the features value\. -.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:ab3ff8fd9153e01f861080fade794a4899397fbcca65d0c3af69b9bb5f1144fb diff --git a/doc/lightning-listnodes.7.md b/doc/lightning-listnodes.7.md index 333f3f3ab..e903eec6e 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: +[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) -- *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. +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:8c35b13edbb60a3403da9317b3177c0a5b9826cf0f06077424e94b1ddb7f1697) diff --git a/doc/lightning-listoffers.7 b/doc/lightning-listoffers.7 index 8f9d2da34..5247feb0c 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:919c848c1d8fa62be1d6c9453c90073306bc168a6969afd836a00861b61b0367 diff --git a/doc/lightning-listoffers.7.md b/doc/lightning-listoffers.7.md index c04536228..6bdf17322 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:94ee9c8562d592be0a15805fb3883ffff44d7e3319f58537fdeb30e5c3d5b9e7) diff --git a/doc/schemas/listinvoices.schema.json b/doc/schemas/listinvoices.schema.json new file mode 100644 index 000000000..6c5ffa654 --- /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 000000000..eb210fe87 --- /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 000000000..9c6caa101 --- /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/tests/test_plugin.py b/tests/test_plugin.py index 9a714fd8f..01f4760cd 100644 --- a/tests/test_plugin.py +++ b/tests/test_plugin.py @@ -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"""