diff --git a/contrib/pyln-testing/pyln/testing/fixtures.py b/contrib/pyln-testing/pyln/testing/fixtures.py index d4e25ffaf..53eafd99d 100644 --- a/contrib/pyln-testing/pyln/testing/fixtures.py +++ b/contrib/pyln-testing/pyln/testing/fixtures.py @@ -232,6 +232,12 @@ def _extra_validator(): 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 _extra_validator(): "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/lightning-getsharedsecret.7 b/doc/lightning-getsharedsecret.7 index 3c4e32902..7327d67dc 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:c0cd7eab8f5114c3b7532b68861767df729757a1af9331330134d956db23e0a4 diff --git a/doc/lightning-getsharedsecret.7.md b/doc/lightning-getsharedsecret.7.md index 13f3ea314..8df55643a 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:23508d8a2af693bf5a6b4de2a3d2c4527b3fb8502fb775f06cfe84bf3a5aedbe) diff --git a/doc/lightning-help.7 b/doc/lightning-help.7 index b7c3bf8ec..3673b6e1c 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] -\fIcategory\fR: A string that represents the category\. +\fBcommand\fR (string): the command .IP \[bu] -\fIdescription\fR: A string that represents the description\. +\fBcategory\fR (string): the category for this command (useful for grouping) .IP \[bu] -\fIverbose\fR: A string that represents the verbode description\. +\fBdescription\fR (string): a one-line description of the purpose of this command +.IP \[bu] +\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:e162d82c81f6a121839d2dfa1658014867f058fe52a100a885956f566a211a8e diff --git a/doc/lightning-help.7.md b/doc/lightning-help.7.md index 31626b39a..353346e9f 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:29119344d1800c7020c96a10ed94bfbf3c57491cc30e9b1f847facbdf0249aba) diff --git a/doc/lightning-invoice.7 b/doc/lightning-invoice.7 index d640a134f..ae184e621 100644 --- a/doc/lightning-invoice.7 +++ b/doc/lightning-invoice.7 @@ -77,14 +77,37 @@ 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 + +.RE + +The following warnings may also be returned: + +.RS +.IP \[bu] +\fBwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\. +.IP \[bu] +\fBwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\. +.IP \[bu] +\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] +\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 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 +\fBlightning-listinvoices\fR(7) to query whether this invoice was created or not\. @@ -100,23 +123,6 @@ The following error codes may occur: .IP \[bu] 902: None of the specified \fIexposeprivatechannels\fR were usable\. -.RE - -One of the following warnings may occur (on success): - -.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\. -.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\. -.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\. -.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\. - .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:69f1d573c0f7afe0cd63e2975d4a8e33d8a1acd2aabb6922b878d55c58731d72 diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md index d48246c68..483948f2e 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:71eeaa119c355874d52c511e09816291e296b0709dc6acb6cefd5614bdc20fd2) diff --git a/doc/lightning-listchannels.7 b/doc/lightning-listchannels.7 index b6ef5f6a1..e96570495 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\. +\fBsource\fR (pubkey): the source node .IP \[bu] -\fIdestination\fR : The node providing the exit point for the channel\. +\fBdestination\fR (pubkey): the destination node .IP \[bu] -\fIshort_channel_id\fR : The channel identifier\. +\fBpublic\fR (boolean): true if this is announced (otherwise it must be our channel) .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\. +\fBamount_msat\fR (msat): the total capacity of this channel (always a whole number of satoshis) .IP \[bu] -\fIsatoshis\fR : Funds available in the channel\. +\fBmessage_flags\fR (u8): as defined by BOLT #7 .IP \[bu] -\fIamount_sat\fR : Same as above, but ending in \fIsat\fR\. +\fBchannel_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)\. +\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] -\fIchannel_flags\fR : Bitfields indicating the direction of the channel -and signaling various options concerning the channel\. (BOLT #7)\. +\fBlast_update\fR (u32): UNIX timestamp on the last channel_update from \fIsource\fR .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\. +\fBbase_fee_millisatoshi\fR (u32): Base fee changed by \fIsource\fR to use this channel .IP \[bu] -\fIlast_update\fR : Unix timestamp (seconds) showing when the last -channel_update message was received\. +\fBfee_per_millionth\fR (u32): Proportional fee changed by \fIsource\fR to use this channel, in parts-per-million .IP \[bu] -\fIbase_fee_millisatoshi\fR : The base fee (in millisatoshi) charged -for the HTLC (BOLT #7; equivalent to \fBfee_base_msat\fR)\. +\fBdelay\fR (u32): The number of blocks delay required by \fIsource\fR to use this channel .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)\. +\fBhtlc_minimum_msat\fR (msat): The smallest payment \fIsource\fR will allow via 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)\. +\fBfeatures\fR (hex): BOLT #9 features bitmap for this channel .IP \[bu] -\fIhtlc_minimum_msat\fR : The minimum payment which can be sent -through 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:4f6181982e495f601d20c33f827a48f6f80c7f268f30b8e73b0a3e9ae2790838 diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md index 4ba7aa2dc..e738ddbdb 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:b14e060fc39b569657050d5bb894c22c0dc575593804248746323b803053b57b) diff --git a/doc/lightning-listforwards.7 b/doc/lightning-listforwards.7 index 93a8b346c..a4f6a3fc6 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] -\fIin_msatoshi\fR, \fIin_msat\fR - amount of msatoshis that are forwarded to this node\. +\fBin_msat\fR (msat): the value of the incoming HTLC .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\. +\fBstatus\fR (string): still ongoing, completed, failed locally, or failed after forwarding (one of "offered", "settled", "local_failed", "failed") .IP \[bu] -\fIreceived_time\fR: timestamp when incoming htlc was received\. +\fBreceived_time\fR (number): the UNIX timestamp when this was received +.IP \[bu] +\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\. +\fBfee_msat\fR (msat): the amount this paid in fees .IP \[bu] -\fIfee\fR, \fIfee_msat\fR: fee offered for forwarding the htlc in msatoshi\. -.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:c2fd8db0d86c538202c27c14bbfbbca7319d1664d22290d6ac7605d1b3160cb9 diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md index 83f362ef2..6f564623f 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 +[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) -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. +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* -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): +If **status** is "settled" or "failed": + - **resolved_time** (number): the UNIX timestamp when this was resolved -- *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). +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:4d4179b29525707c4c1a22aa56dc46c0875562a43f5bc7d2b7d3838b32b5bad0) diff --git a/doc/schemas/getsharedsecret.schema.json b/doc/schemas/getsharedsecret.schema.json new file mode 100644 index 000000000..143d0e87c --- /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 000000000..37c9ce150 --- /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 000000000..b4f628495 --- /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/listchannels.schema.json b/doc/schemas/listchannels.schema.json new file mode 100644 index 000000000..bd1ab36b7 --- /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/listforwards.schema.json b/doc/schemas/listforwards.schema.json new file mode 100644 index 000000000..f52b10ee0 --- /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": { } + } + } + } + ] + } + } + } +}