mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-01-18 05:12:45 +01:00
Code Issues Projects Releases Wiki Activity

doc/schemas: getsharedsecret, help, invoice, listchannels, listforwards

Browse Source 
And a new "u8" type.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2021-06-16 10:35:17 +09:30
parent a9f49b5326
commit 74eeaa8213
16 changed files with 529 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
contrib/pyln-testing/pyln/testing/fixtures.py
View File

@ -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,

14
doc/lightning-getsharedsecret.7 generated
View File

@ -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

11
doc/lightning-getsharedsecret.7.md
View File

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:23508d8a2af693bf5a6b4de2a3d2c4527b3fb8502fb775f06cfe84bf3a5aedbe)

18
doc/lightning-help.7 generated
View File

@ -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<vincenzo.palazzo@protonmail.com\fR> wrote the initial versi
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:cbd027bd9117d2e71167ab1c9d95a63c90b8e9c556dd75e951d4913a2891cb37
\" SHA256STAMP:e162d82c81f6a121839d2dfa1658014867f058fe52a100a885956f566a211a8e

15
doc/lightning-help.7.md
View File

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:29119344d1800c7020c96a10ed94bfbf3c57491cc30e9b1f847facbdf0249aba)

53
doc/lightning-invoice.7 generated
View File

@ -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<rusty@rustcorp.com.au\fR> 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

30
doc/lightning-invoice.7.md
View File

@ -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 <<rusty@rustcorp.com.au>> 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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:71eeaa119c355874d52c511e09816291e296b0709dc6acb6cefd5614bdc20fd2)

56
doc/lightning-listchannels.7 generated
View File

@ -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

55
doc/lightning-listchannels.7.md
View File

@ -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:
<https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md>
[comment]: # ( SHA256STAMP:b14e060fc39b569657050d5bb894c22c0dc575593804248746323b803053b57b)

40
doc/lightning-listforwards.7 generated
View File

@ -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<r.pickhardt@gmail.com\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:b374dbf5f639ad8782b4ad2ff515f25b22a4407ef77f2e0904c975d1a7ccfbe4
\" SHA256STAMP:c2fd8db0d86c538202c27c14bbfbbca7319d1664d22290d6ac7605d1b3160cb9

39
doc/lightning-listforwards.7.md
View File

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:4d4179b29525707c4c1a22aa56dc46c0875562a43f5bc7d2b7d3838b32b5bad0)

14
doc/schemas/getsharedsecret.schema.json Normal file
View File

@ -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
}
}
}

35
doc/schemas/help.schema.json Normal file
View File

@ -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": { }
}
}

42
doc/schemas/invoice.schema.json Normal file
View File

@ -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."
}
}
}

77
doc/schemas/listchannels.schema.json Normal file
View File

@ -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"
}
}
}
}
}
}

205
doc/schemas/listforwards.schema.json Normal file
View File

@ -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": { }
}
}
}
]
}
}
}
}