From 80927039e07be9248305330e160e00a048df322c Mon Sep 17 00:00:00 2001 From: darosior Date: Sat, 10 Aug 2019 01:54:18 +0200 Subject: [PATCH] doc/manpages: replace asciidoc by markdown --- doc/lightning-autocleaninvoice.7.md | 48 +++ doc/lightning-autocleaninvoice.7.txt | 42 --- doc/lightning-check.7.md | 43 +++ doc/lightning-check.7.txt | 37 --- doc/lightning-cli.1.md | 97 ++++++ doc/lightning-cli.1.txt | 83 ----- doc/lightning-close.7.md | 74 +++++ doc/lightning-close.7.txt | 75 ----- doc/lightning-connect.7.md | 65 ++++ doc/lightning-connect.7.txt | 66 ---- doc/lightning-decodepay.7.md | 67 ++++ doc/lightning-decodepay.7.txt | 61 ---- doc/lightning-delexpiredinvoice.7.md | 41 +++ doc/lightning-delexpiredinvoice.7.txt | 35 --- doc/lightning-delinvoice.7.md | 44 +++ doc/lightning-delinvoice.7.txt | 38 --- doc/lightning-disconnect.7.md | 69 +++++ doc/lightning-disconnect.7.txt | 61 ---- doc/lightning-fundchannel.7.md | 82 +++++ doc/lightning-fundchannel.7.txt | 76 ----- doc/lightning-fundchannel_cancel.7.md | 45 +++ doc/lightning-fundchannel_cancel.7.txt | 37 --- doc/lightning-fundchannel_complete.7.md | 54 ++++ doc/lightning-fundchannel_complete.7.txt | 46 --- doc/lightning-fundchannel_start.7.md | 53 ++++ doc/lightning-fundchannel_start.7.txt | 45 --- doc/lightning-getroute.7.md | 306 ++++++++++++++++++ doc/lightning-getroute.7.txt | 144 --------- doc/lightning-invoice.7.md | 109 +++++++ doc/lightning-invoice.7.txt | 107 ------- doc/lightning-listchannels.7.md | 106 +++++++ doc/lightning-listchannels.7.txt | 95 ------ doc/lightning-listforwards.7.md | 62 ++++ doc/lightning-listforwards.7.txt | 58 ---- doc/lightning-listfunds.7.md | 68 ++++ doc/lightning-listfunds.7.txt | 70 ----- doc/lightning-listinvoices.7.md | 48 +++ doc/lightning-listinvoices.7.txt | 43 --- doc/lightning-listpays.7.md | 67 ++++ doc/lightning-listpays.7.txt | 49 --- doc/lightning-listpeers.7.md | 89 ++++++ doc/lightning-listpeers.7.txt | 79 ----- doc/lightning-listsendpays.7.md | 72 +++++ doc/lightning-listsendpays.7.txt | 50 --- doc/lightning-newaddr.7.md | 58 ++++ doc/lightning-newaddr.7.txt | 48 --- doc/lightning-pay.7.md | 135 ++++++++ doc/lightning-pay.7.txt | 151 --------- doc/lightning-plugin.7.md | 53 ++++ doc/lightning-plugin.7.txt | 48 --- doc/lightning-sendpay.7.md | 107 +++++++ doc/lightning-sendpay.7.txt | 109 ------- doc/lightning-setchannelfee.7.md | 72 +++++ doc/lightning-setchannelfee.7.txt | 61 ---- doc/lightning-txdiscard.7.md | 48 +++ doc/lightning-txdiscard.7.txt | 42 --- doc/lightning-txprepare.7.md | 57 ++++ doc/lightning-txprepare.7.txt | 52 ---- doc/lightning-txsend.7.md | 47 +++ doc/lightning-txsend.7.txt | 43 --- doc/lightning-waitanyinvoice.7.md | 50 +++ doc/lightning-waitanyinvoice.7.txt | 45 --- doc/lightning-waitinvoice.7.md | 48 +++ doc/lightning-waitinvoice.7.txt | 40 --- doc/lightning-waitsendpay.7.md | 89 ++++++ doc/lightning-waitsendpay.7.txt | 89 ------ doc/lightning-withdraw.7.md | 74 +++++ doc/lightning-withdraw.7.txt | 66 ---- doc/lightningd-config.5.md | 376 +++++++++++++++++++++++ doc/lightningd.8.md | 177 +++++++++++ 70 files changed, 3100 insertions(+), 2191 deletions(-) create mode 100644 doc/lightning-autocleaninvoice.7.md delete mode 100644 doc/lightning-autocleaninvoice.7.txt create mode 100644 doc/lightning-check.7.md delete mode 100644 doc/lightning-check.7.txt create mode 100644 doc/lightning-cli.1.md delete mode 100644 doc/lightning-cli.1.txt create mode 100644 doc/lightning-close.7.md delete mode 100644 doc/lightning-close.7.txt create mode 100644 doc/lightning-connect.7.md delete mode 100644 doc/lightning-connect.7.txt create mode 100644 doc/lightning-decodepay.7.md delete mode 100644 doc/lightning-decodepay.7.txt create mode 100644 doc/lightning-delexpiredinvoice.7.md delete mode 100644 doc/lightning-delexpiredinvoice.7.txt create mode 100644 doc/lightning-delinvoice.7.md delete mode 100644 doc/lightning-delinvoice.7.txt create mode 100644 doc/lightning-disconnect.7.md delete mode 100644 doc/lightning-disconnect.7.txt create mode 100644 doc/lightning-fundchannel.7.md delete mode 100644 doc/lightning-fundchannel.7.txt create mode 100644 doc/lightning-fundchannel_cancel.7.md delete mode 100644 doc/lightning-fundchannel_cancel.7.txt create mode 100644 doc/lightning-fundchannel_complete.7.md delete mode 100644 doc/lightning-fundchannel_complete.7.txt create mode 100644 doc/lightning-fundchannel_start.7.md delete mode 100644 doc/lightning-fundchannel_start.7.txt create mode 100644 doc/lightning-getroute.7.md delete mode 100644 doc/lightning-getroute.7.txt create mode 100644 doc/lightning-invoice.7.md delete mode 100644 doc/lightning-invoice.7.txt create mode 100644 doc/lightning-listchannels.7.md delete mode 100644 doc/lightning-listchannels.7.txt create mode 100644 doc/lightning-listforwards.7.md delete mode 100644 doc/lightning-listforwards.7.txt create mode 100644 doc/lightning-listfunds.7.md delete mode 100644 doc/lightning-listfunds.7.txt create mode 100644 doc/lightning-listinvoices.7.md delete mode 100644 doc/lightning-listinvoices.7.txt create mode 100644 doc/lightning-listpays.7.md delete mode 100644 doc/lightning-listpays.7.txt create mode 100644 doc/lightning-listpeers.7.md delete mode 100644 doc/lightning-listpeers.7.txt create mode 100644 doc/lightning-listsendpays.7.md delete mode 100644 doc/lightning-listsendpays.7.txt create mode 100644 doc/lightning-newaddr.7.md delete mode 100644 doc/lightning-newaddr.7.txt create mode 100644 doc/lightning-pay.7.md delete mode 100644 doc/lightning-pay.7.txt create mode 100644 doc/lightning-plugin.7.md delete mode 100644 doc/lightning-plugin.7.txt create mode 100644 doc/lightning-sendpay.7.md delete mode 100644 doc/lightning-sendpay.7.txt create mode 100644 doc/lightning-setchannelfee.7.md delete mode 100644 doc/lightning-setchannelfee.7.txt create mode 100644 doc/lightning-txdiscard.7.md delete mode 100644 doc/lightning-txdiscard.7.txt create mode 100644 doc/lightning-txprepare.7.md delete mode 100644 doc/lightning-txprepare.7.txt create mode 100644 doc/lightning-txsend.7.md delete mode 100644 doc/lightning-txsend.7.txt create mode 100644 doc/lightning-waitanyinvoice.7.md delete mode 100644 doc/lightning-waitanyinvoice.7.txt create mode 100644 doc/lightning-waitinvoice.7.md delete mode 100644 doc/lightning-waitinvoice.7.txt create mode 100644 doc/lightning-waitsendpay.7.md delete mode 100644 doc/lightning-waitsendpay.7.txt create mode 100644 doc/lightning-withdraw.7.md delete mode 100644 doc/lightning-withdraw.7.txt create mode 100644 doc/lightningd-config.5.md create mode 100644 doc/lightningd.8.md diff --git a/doc/lightning-autocleaninvoice.7.md b/doc/lightning-autocleaninvoice.7.md new file mode 100644 index 000000000..93efb51fb --- /dev/null +++ b/doc/lightning-autocleaninvoice.7.md @@ -0,0 +1,48 @@ +LIGHTNING-AUTOCLEANINVOICE(7) Manual Page +========================================= +lightning-autocleaninvoice - Set up auto-delete of expired invoice + +SYNOPSIS +-------- + +**autocleaninvoice** \[*cycle\_seconds*\] \[*expired\_by*\] + +DESCRIPTION +----------- + +The **autocleaninvoice** RPC command sets up automatic cleaning of +expired invoices. + +Autoclean will be done every *cycle\_seconds* seconds. Setting +*cycle\_seconds* to 0 disables autoclean. If not specified, this +defaults to 3600 (one hour). + +Every autoclean cycle, expired invoices, which have already been expired +for at least *expired\_by* seconds, will be deleted. If *expired\_by* is +not specified, this defaults to 86400 (one day). + +On startup of the daemon, no autoclean is set up. + +RETURN VALUE +------------ + +On success, an empty object is returned. + +AUTHOR +------ + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +-------- + +lightning-delexpiredinvoice(7), lightning-delinvoice(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-07 14:23:17 CEST diff --git a/doc/lightning-autocleaninvoice.7.txt b/doc/lightning-autocleaninvoice.7.txt deleted file mode 100644 index c413d48d6..000000000 --- a/doc/lightning-autocleaninvoice.7.txt +++ /dev/null @@ -1,42 +0,0 @@ -LIGHTNING-AUTOCLEANINVOICE(7) -============================= -:doctype: manpage - -NAME ----- -lightning-autocleaninvoice - Set up auto-delete of expired invoice - -SYNOPSIS --------- -*autocleaninvoice* ['cycle_seconds'] ['expired_by'] - -DESCRIPTION ------------ -The *autocleaninvoice* RPC command sets up automatic cleaning of -expired invoices. - -Autoclean will be done every 'cycle_seconds' seconds. -Setting 'cycle_seconds' to 0 disables autoclean. -If not specified, this defaults to 3600 (one hour). - -Every autoclean cycle, expired invoices, which have already -been expired for at least 'expired_by' seconds, will be deleted. -If 'expired_by' is not specified, this defaults to 86400 (one day). - -On startup of the daemon, no autoclean is set up. - -RETURN VALUE ------------- -On success, an empty object is returned. - -AUTHOR ------- -ZmnSCPxj is mainly responsible. - -SEE ALSO --------- -lightning-delexpiredinvoice(7), lightning-delinvoice(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-check.7.md b/doc/lightning-check.7.md new file mode 100644 index 000000000..49e5d77ca --- /dev/null +++ b/doc/lightning-check.7.md @@ -0,0 +1,43 @@ +LIGHTNING-CHECK(7) Manual Page +============================== +lightning-check - Command for verifying parameters + +SYNOPSIS +-------- + +**check** *command\_to\_check* \[*parameters*\] + +DESCRIPTION +----------- + +The **check** RPC command verifies another command’s parameters without +running it. + +The *command\_to\_check* is the name of the relevant command. + +*parameters* is the command’s parameters. + +This does not guarantee successful execution of the command in all +cases. For example, a call to lightning-getroute(7) may still fail to +find a route even if checking the parameters succeeds. + +RETURN VALUE +------------ + +On success, the *command\_to\_check* is returned. On failure, the +relevant RPC error is returned. + +AUTHOR +------ + +Mark Beckwith <> and Rusty Russell +<> are mainly responsible. + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-check.7.txt b/doc/lightning-check.7.txt deleted file mode 100644 index 32a4a2d46..000000000 --- a/doc/lightning-check.7.txt +++ /dev/null @@ -1,37 +0,0 @@ -LIGHTNING-CHECK(7) -================== -:doctype: manpage - -NAME ----- -lightning-check - Command for verifying parameters - -SYNOPSIS --------- -*check* 'command_to_check' ['parameters'] - -DESCRIPTION ------------ -The *check* RPC command verifies another command's parameters without running it. - -The 'command_to_check' is the name of the relevant command. - -'parameters' is the command's parameters. - -This does not guarantee successful execution of the command in all cases. -For example, a call to lightning-getroute(7) may still fail to find a route even if -checking the parameters succeeds. - -RETURN VALUE ------------- -On success, the 'command_to_check' is returned. -On failure, the relevant RPC error is returned. - -AUTHOR ------- -Mark Beckwith and Rusty Russell -are mainly responsible. - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-cli.1.md b/doc/lightning-cli.1.md new file mode 100644 index 000000000..0d350b167 --- /dev/null +++ b/doc/lightning-cli.1.md @@ -0,0 +1,97 @@ +LIGHTNING-CLI(1) Manual Page +============================ +lightning-cli - Control lightning daemon + +SYNOPSIS +-------- + +**lightning-cli** \[*OPTIONS*\] *command*… + +DESCRIPTION +----------- + +**lightning-cli** sends commands to the lightning daemon. + +OPTIONS +------- + + **--lightning-dir**=*DIR* +Set the directory for the lightning daemon we’re talking to; defaults to +*$HOME/.lightning*. + + **--rpc-file**=*FILE* +Named pipe to use to talk to lightning daemon: default is +*lightning-rpc* in the lightning directory. + + **--keywords**/**-k** +Use format *key*=*value* for parameters in any order + + **--order**/**-o** +Follow strictly the order of parameters for the command + + **--json**/**-J** +Return result in JSON format (default unless *help* command) + + **--raw**/**-R** +Return raw JSON directly as lightningd replies + + **--human-readable**/**-H** +Return result in human-readable output (default for *help* command) + + **--help**/**-h** +Print summary of options to standard output and exit. + + **--version**/**-V** +Print version number to standard output and exit. + +COMMANDS +-------- + +*lightning-cli* simply uses the JSON RPC interface to talk to +*lightningd*, and prints the results. Thus the commands available depend +entirely on the lightning daemon itself. + +ARGUMENTS +--------- + +Arguments may be provided positionally or using *key*=*value* after the +command name, based on either **-o** or **-k** option. Arguments may be +integer numbers (composed entirely of digits), floating-point numbers +(has a radix point but otherwise composed of digits), *true*, *false*, +or *null*. Other arguments are treated as strings. + +Some commands have optional arguments. You may use *null* to skip +optional arguments to provide later arguments. + +EXAMPLES +-------- + +Example 1. List commands + +lightning-cli help + +BUGS +---- + +This manpage documents how it should work, not how it does work. The +pretty printing of results isn’t pretty. + +AUTHOR +------ + +Rusty Russell <> is mainly to blame. + +RESOURCES +--------- + +Main web site: + +COPYING +------- + +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:39:53 CEST diff --git a/doc/lightning-cli.1.txt b/doc/lightning-cli.1.txt deleted file mode 100644 index e697fd7e1..000000000 --- a/doc/lightning-cli.1.txt +++ /dev/null @@ -1,83 +0,0 @@ -LIGHTNING-CLI(1) -================== -:doctype: manpage - -NAME ----- -lightning-cli - Control lightning daemon - - -SYNOPSIS --------- -*lightning-cli* ['OPTIONS'] 'command'... - -DESCRIPTION ------------ -*lightning-cli* sends commands to the lightning daemon. - -OPTIONS -------- -*--lightning-dir*='DIR':: - Set the directory for the lightning daemon we're talking to; defaults to - '$HOME/.lightning'. -*--rpc-file*='FILE':: - Named pipe to use to talk to lightning daemon: default is 'lightning-rpc' - in the lightning directory. -*--keywords*/*-k*:: - Use format 'key'='value' for parameters in any order -*--order*/*-o*:: - Follow strictly the order of parameters for the command -*--json*/*-J*:: - Return result in JSON format (default unless 'help' command) -*--raw*/*-R*:: - Return raw JSON directly as lightningd replies -*--human-readable*/*-H*:: - Return result in human-readable output (default for 'help' command) -*--help*/*-h*:: - Print summary of options to standard output and exit. -*--version*/*-V*:: - Print version number to standard output and exit. - -COMMANDS --------- -'lightning-cli' simply uses the JSON RPC interface to talk to 'lightningd', -and prints the results. Thus the commands available depend entirely on the -lightning daemon itself. - -ARGUMENTS ---------- -Arguments may be provided positionally or using 'key'='value' -after the command name, based on either *-o* or *-k* option. -Arguments may be integer numbers (composed entirely of digits), -floating-point numbers (has a radix point but otherwise composed -of digits), 'true', 'false', or 'null'. -Other arguments are treated as strings. - -Some commands have optional arguments. -You may use 'null' to skip optional arguments to provide -later arguments. - -EXAMPLES --------- -.List commands -=================================================================== -lightning-cli help -=================================================================== - -BUGS ----- -This manpage documents how it should work, not how it does work. The -pretty printing of results isn't pretty. - -AUTHOR ------- -Rusty Russell is mainly to blame. - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning - -COPYING -------- -Note: the modules in the ccan/ directory have their own licenses, but -the rest of the code is covered by the BSD-style MIT license. diff --git a/doc/lightning-close.7.md b/doc/lightning-close.7.md new file mode 100644 index 000000000..a25eacd5b --- /dev/null +++ b/doc/lightning-close.7.md @@ -0,0 +1,74 @@ +LIGHTNING-CLOSE(7) Manual Page +============================== +lightning-close - Command for closing channels with direct peers + +SYNOPSIS +-------- + +**close** *id* \[*unilateraltimeout*\] + +DESCRIPTION +----------- + +The **close** RPC command attempts to close the channel cooperatively +with the peer, or unilaterally after *unilateraltimeout*. + +If the given *id* is a peer ID (66 hex digits as a string), then it +applies to the active channel of the direct peer corresponding to the +given peer ID. If the given *id* is a channel ID (64 hex digits as a +string, or the short channel ID *blockheight:txindex:outindex* form), +then it applies to that channel. + +If *unilateraltimeout* is not zero, the **close** command will +unilaterally close the channel when that number of seconds is reached. +If *unilateraltimeout* is zero, then the **close** command will wait +indefinitely until the peer is online and can negotiate a mutual close. +The default is 2 days (172800 seconds). + +The peer needs to be live and connected in order to negotiate a mutual +close. The default of unilaterally closing after 48 hours is usually a +reasonable indication that you can no longer contact the peer. + +NOTES +----- + +Prior to 0.7.2, **close** took two parameters: *force* and *timeout*. +*timeout* was the number of seconds before *force* took effect (default, +30), and *force* determined whether the result was a unilateral close or +an RPC error (default). Even after the timeout, the channel would be +closed if the peer reconnected. + +RETURN VALUE +------------ + +On success, an object with fields *tx* and *txid* containing the closing +transaction are returned. It will also have a field *type* which is +either the JSON string *mutual* or the JSON string *unilateral*. A +*mutual* close means that we could negotiate a close with the peer, +while a *unilateral* close means that the *force* flag was set and we +had to close the channel without waiting for the counterparty. + +A unilateral close may still occur at any time if the peer did not +behave correctly during the close negotiation. + +Unilateral closes will return your funds after a delay. The delay will +vary based on the peer *to\_self\_delay* setting, not your own setting. + +AUTHOR +------ + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +-------- + +lightning-disconnect(7), lightning-fundchannel(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-09 11:12:04 CEST diff --git a/doc/lightning-close.7.txt b/doc/lightning-close.7.txt deleted file mode 100644 index d3d678ad9..000000000 --- a/doc/lightning-close.7.txt +++ /dev/null @@ -1,75 +0,0 @@ -LIGHTNING-CLOSE(7) -================== -:doctype: manpage - -NAME ----- -lightning-close - Command for closing channels with direct peers - -SYNOPSIS --------- -*close* 'id' ['unilateraltimeout'] - -DESCRIPTION ------------ - -The *close* RPC command attempts to close the channel cooperatively -with the peer, or unilaterally after 'unilateraltimeout'. - -If the given 'id' is a peer ID (66 hex digits as a string), then -it applies to the active channel of the direct peer corresponding to -the given peer ID. -If the given 'id' is a channel ID (64 hex digits as a string, or -the short channel ID 'blockheight:txindex:outindex' form), then it -applies to that channel. - -If 'unilateraltimeout' is not zero, the *close* command will -unilaterally close the channel when that number of seconds is reached. -If 'unilateraltimeout' is zero, then the *close* command will wait -indefinitely until the peer is online and can negotiate a mutual -close. The default is 2 days (172800 seconds). - -The peer needs to be live and connected in order to negotiate -a mutual close. The default of unilaterally closing after 48 hours -is usually a reasonable indication that you can no longer -contact the peer. - -NOTES ------ - -Prior to 0.7.2, *close* took two parameters: 'force' and 'timeout'. -'timeout' was the number of seconds before 'force' took effect -(default, 30), and 'force' determined whether the result was a -unilateral close or an RPC error (default). Even after -the timeout, the channel would be closed if the peer reconnected. - -RETURN VALUE ------------- - -On success, an object with fields 'tx' and 'txid' containing the -closing transaction are returned. -It will also have a field 'type' which is either the JSON string -'mutual' or the JSON string 'unilateral'. -A 'mutual' close means that we could negotiate a close with the -peer, while a 'unilateral' close means that the 'force' flag was -set and we had to close the channel without waiting for the -counterparty. - -A unilateral close may still occur at any time if -the peer did not behave correctly during the close negotiation. - -Unilateral closes will return your funds after a delay. -The delay will vary based on the peer 'to_self_delay' setting, not -your own setting. - -AUTHOR ------- -ZmnSCPxj is mainly responsible. - -SEE ALSO --------- -lightning-disconnect(7), lightning-fundchannel(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-connect.7.md b/doc/lightning-connect.7.md new file mode 100644 index 000000000..c3658479a --- /dev/null +++ b/doc/lightning-connect.7.md @@ -0,0 +1,65 @@ +LIGHTNING-CONNECT(7) Manual Page +================================ +lightning-connect - Command for connecting to another lightning node. + +SYNOPSIS +-------- + +**connect** *id* \[*host* *port*\] + +DESCRIPTION +----------- + +The **connect** RPC command establishes a new connection with another +node in the Lightning Network. + +*id* represents the target node’s public key. As a convenience, *id* may +be of the form *id@host* or *id@host:port*. In this case, the *host* and +*port* parameters must be omitted. + +*host* is the peer’s hostname or IP address. + +If not specified, the *port* defaults to 9735. + +If *host* is not specified, the connection will be attempted to an IP +belonging to *id* obtained through gossip with other already connected +peers. + +If *host* begins with a */* it is interpreted as a local path, and the +connection will be made to that local socket (see **bind-addr** in +lightningd-config(5)). + +Connecting to a node is just the first step in opening a channel with +another node. Once the peer is connected a channel can be opened with +lightning-fundchannel(7). + +RETURN VALUE +------------ + +On success the peer *id* is returned. + +The following error codes may occur: +- -1: Catchall nonspecific error. This may occur if the host is not + valid or there are problems communicating with the peer. **connect** + will make up to 10 attempts to connect to the peer before giving up. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. +Felix <> is the original author of this manpage. + +SEE ALSO +-------- + +lightning-fundchannel(7), lightning-listpeers(7), +lightning-listchannels(7), lightning-disconnect(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-01 14:59:36 CEST diff --git a/doc/lightning-connect.7.txt b/doc/lightning-connect.7.txt deleted file mode 100644 index 0e88195d2..000000000 --- a/doc/lightning-connect.7.txt +++ /dev/null @@ -1,66 +0,0 @@ -LIGHTNING-CONNECT(7) -==================== -:doctype: manpage - -NAME ----- -lightning-connect - Command for connecting to another -lightning node. - -SYNOPSIS --------- -*connect* 'id' ['host' 'port'] - -DESCRIPTION ------------ -The *connect* RPC command establishes a new connection -with another node in the Lightning Network. - -'id' represents the target node's public key. -As a convenience, 'id' may be of the form 'id@host' or 'id@host:port'. -In this case, the 'host' and 'port' parameters must be omitted. - -'host' is the peer's hostname or IP address. - -If not specified, the 'port' defaults to 9735. - -If 'host' is not specified, the -connection will be attempted to an IP belonging to -'id' obtained through gossip with other already -connected peers. - -If 'host' begins with a '/' it is interpreted as a local path, -and the connection will be made to that local socket (see *bind-addr* -in lightningd-config(5)). - -Connecting to a node is just the first step in opening -a channel with another node. -Once the peer is connected a channel can be opened with -lightning-fundchannel(7). - - -RETURN VALUE ------------- -On success the peer 'id' is returned. - -The following error codes may occur: - -* -1. Catchall nonspecific error. - This may occur if the host is not valid or there are problems - communicating with the peer. - *connect* will make up to 10 attempts to connect to the peer before - giving up. - -AUTHOR ------- -Rusty Russell is mainly responsible. -Felix is the original author of this manpage. - -SEE ALSO --------- -lightning-fundchannel(7), lightning-listpeers(7), -lightning-listchannels(7), lightning-disconnect(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md new file mode 100644 index 000000000..c7167ba07 --- /dev/null +++ b/doc/lightning-decodepay.7.md @@ -0,0 +1,67 @@ +LIGHTNING-DECODEPAY(7) Manual Page +================================== +lightning-decodepay - Command for decoding a bolt11 string (low-level) + +SYNOPSIS +-------- + +**decodepay** *bolt11* \[*description*\] + +DESCRIPTION +----------- + +The **decodepay** RPC command checks and parses a *bolt11* string as +specified by the BOLT 11 specification. + +RETURN VALUE +------------ + +On success, an object is returned with the following fields, as +specified by BOLT11: +- *currency*: the BIP173 name for the currency. +- *timestamp*: the UNIX-style timestamp of the invoice. +- *expiry*: the number of seconds this is valid after *timestamp*. +- *payee*: the public key of the recipient. +- *payment\_hash*: the payment hash of the request. +- *signature*: the DER-encoded signature. +- *description*: the description of the purpose of the purchase (see + below) + +The following fields are optional: +- *msatoshi*: the number of millisatoshi requested (if any). +- *amount\_msat*: the same as above, with *msat* appended (if any). +- *fallbacks*: array of fallback address object containing a *hex* + string, and both *type* and *addr* if it is recognized as one of + *P2PKH*, *P2SH*, *P2WPKH*, or *P2WSH*. +- *routes*: an array of routes. Each route is an arrays of objects, + each containing *pubkey*, *short\_channel\_id*, *fee\_base\_msat*, + *fee\_proportional\_millionths* and *cltv\_expiry\_delta*. +- *extra*: an array of objects representing unknown fields, each with + one-character *tag* and a *data* bech32 string. + +Technically, the *description* field is optional if a +*description\_hash* field is given, but in this case **decodepay** will +only succeed if the optional *description* field is passed and matches +the *description\_hash*. In practice, these are currently unused. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-pay(7), lightning-getroute(7), lightning-sendpay(7). + +[BOLT +\#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-decodepay.7.txt b/doc/lightning-decodepay.7.txt deleted file mode 100644 index aede33950..000000000 --- a/doc/lightning-decodepay.7.txt +++ /dev/null @@ -1,61 +0,0 @@ -LIGHTNING-DECODEPAY(7) -====================== -:doctype: manpage - -NAME ----- -lightning-decodepay - Command for decoding a bolt11 string (low-level) - - -SYNOPSIS --------- -*decodepay* 'bolt11' ['description'] - -DESCRIPTION ------------ -The *decodepay* RPC command checks and parses a 'bolt11' string as specified -by the BOLT 11 specification. - -RETURN VALUE ------------- - -On success, an object is returned with the following fields, as specified -by BOLT11: - -- 'currency': the BIP173 name for the currency. -- 'timestamp': the UNIX-style timestamp of the invoice. -- 'expiry': the number of seconds this is valid after 'timestamp'. -- 'payee': the public key of the recipient. -- 'payment_hash': the payment hash of the request. -- 'signature': the DER-encoded signature. -- 'description': the description of the purpose of the purchase (see below) - -The following fields are optional: - -- 'msatoshi': the number of millisatoshi requested (if any). -- 'amount_msat': the same as above, with 'msat' appended (if any). -- 'fallbacks': array of fallback address object containing a 'hex' string, and - both 'type' and 'addr' if it is recognized as one of 'P2PKH', 'P2SH', 'P2WPKH', or 'P2WSH'. -- 'routes': an array of routes. Each route is an arrays of objects, each containing 'pubkey', 'short_channel_id', 'fee_base_msat', 'fee_proportional_millionths' and 'cltv_expiry_delta'. -- 'extra': an array of objects representing unknown fields, each with one-character 'tag' and a 'data' bech32 string. - -Technically, the 'description' field is optional if a -'description_hash' field is given, but in this case *decodepay* will -only succeed if the optional 'description' field is passed and matches -the 'description_hash'. In practice, these are currently unused. - -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-pay(7), lightning-getroute(7), lightning-sendpay(7). - -https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md[BOLT #11]. - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md new file mode 100644 index 000000000..99bcfdd37 --- /dev/null +++ b/doc/lightning-delexpiredinvoice.7.md @@ -0,0 +1,41 @@ +LIGHTNING-DELEXPIREDINVOICE(7) Manual Page +========================================== +lightning-delexpiredinvoice - Command for removing expired invoices. + +SYNOPSIS +-------- + +**delexpiredinvoice** \[*maxexpirytime*\] + +DESCRIPTION +----------- + +The **delexpiredinvoice** RPC command removes all invoices that have +expired on or before the given *maxexpirytime*. + +If *maxexpirytime* is not specified then all expired invoices are +deleted. + +RETURN VALUE +------------ + +On success, an empty object is returned. + +AUTHOR +------ + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +-------- + +lightning-delinvoice(7), lightning-autocleaninvoice(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-07 14:23:17 CEST diff --git a/doc/lightning-delexpiredinvoice.7.txt b/doc/lightning-delexpiredinvoice.7.txt deleted file mode 100644 index de8b7b832..000000000 --- a/doc/lightning-delexpiredinvoice.7.txt +++ /dev/null @@ -1,35 +0,0 @@ -LIGHTNING-DELEXPIREDINVOICE(7) -============================== -:doctype: manpage - -NAME ----- -lightning-delexpiredinvoice - Command for removing expired invoices. - -SYNOPSIS --------- -*delexpiredinvoice* ['maxexpirytime'] - -DESCRIPTION ------------ -The *delexpiredinvoice* RPC command removes all invoices that have -expired on or before the given 'maxexpirytime'. - -If 'maxexpirytime' is not specified then all expired invoices are -deleted. - -RETURN VALUE ------------- -On success, an empty object is returned. - -AUTHOR ------- -ZmnSCPxj is mainly responsible. - -SEE ALSO --------- -lightning-delinvoice(7), lightning-autocleaninvoice(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md new file mode 100644 index 000000000..0f85d2665 --- /dev/null +++ b/doc/lightning-delinvoice.7.md @@ -0,0 +1,44 @@ +LIGHTNING-DELINVOICE(7) Manual Page +=================================== +lightning-delinvoice - Command for removing an invoice. + +SYNOPSIS +-------- + +**delinvoice** *label* *status* + +DESCRIPTION +----------- + +The **delinvoice** RPC command removes an invoice with *status* as given +in **listinvoices**. + +The caller should be particularly aware of the error case caused by the +*status* changing just before this command is invoked! + +RETURN VALUE +------------ + +On success, an invoice description will be returned as per +lightning-listinvoice(7). + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listinvoice(7), lightning-waitinvoice(7), +lightning-invoice(7), lightning-delexpiredinvoice(7), +lightning-autocleaninvoice(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-07 14:23:17 CEST diff --git a/doc/lightning-delinvoice.7.txt b/doc/lightning-delinvoice.7.txt deleted file mode 100644 index 06f0b2917..000000000 --- a/doc/lightning-delinvoice.7.txt +++ /dev/null @@ -1,38 +0,0 @@ -LIGHTNING-DELINVOICE(7) -======================= -:doctype: manpage - -NAME ----- -lightning-delinvoice - Command for removing an invoice. - -SYNOPSIS --------- -*delinvoice* 'label' 'status' - -DESCRIPTION ------------ -The *delinvoice* RPC command removes an invoice with 'status' as -given in *listinvoices*. - -The caller should be particularly aware of the error case caused by -the 'status' changing just before this command is invoked! - -RETURN VALUE ------------- -On success, an invoice description will be returned as per lightning-listinvoice(7). - -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-listinvoice(7), lightning-waitinvoice(7), lightning-invoice(7), -lightning-delexpiredinvoice(7), lightning-autocleaninvoice(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md new file mode 100644 index 000000000..aba35da2b --- /dev/null +++ b/doc/lightning-disconnect.7.md @@ -0,0 +1,69 @@ +LIGHTNING-DISCONNECT(7) Manual Page +=================================== +lightning-disconnect - Command for disconnecting from another lightning +node. + +SYNOPSIS +-------- + +**disconnect** *id* \[*force*\] + +DESCRIPTION +----------- + +The disconnect RPC command closes an existing connection to a peer, +identified by *id*, in the Lightning Network, as long as it doesn’t have +an active channel. If *force* is set then it will disconnect even with +an active channel. + +The *id* can be discovered in the output of the listpeers command, which +returns a set of peers: + + { + "peers": [ + { + "id": "0563aea81...", + "connected": true, + ... + } + ] + } + +Passing the *id* attribute of a peer to *disconnect* will terminate the +connection. + +RETURN VALUE +------------ + +On success, an empty object is returned. + +ERRORS +------ + +If *id* is invalid, an error message will be returned: + + { "code" : -1, "message" : "Peer not connected" } + +If the peer has an active channel and *force* is not set, an error +message will be returned: + + { "code" : -1, "message" : "Peer is in state CHANNELD_NORMAL" } + +AUTHOR +------ + +Michael Hawkins <>. + +SEE ALSO +-------- + +lightning-connect(1), lightning-listpeers(1) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:34:18 CEST diff --git a/doc/lightning-disconnect.7.txt b/doc/lightning-disconnect.7.txt deleted file mode 100644 index 7c48551fa..000000000 --- a/doc/lightning-disconnect.7.txt +++ /dev/null @@ -1,61 +0,0 @@ -LIGHTNING-DISCONNECT(7) -======================= -:doctype: manpage - -NAME ----- -lightning-disconnect - Command for disconnecting from another lightning node. - -SYNOPSIS --------- -*disconnect* 'id' ['force'] - -DESCRIPTION ------------ -The disconnect RPC command closes an existing connection to a -peer, identified by 'id', in the Lightning Network, as long as it -doesn't have an active channel. If 'force' is set then it will disconnect -even with an active channel. - -The 'id' can be discovered in the output of the listpeers -command, which returns a set of peers: - - { - "peers": [ - { - "id": "0563aea81...", - "connected": true, - ... - } - ] - } - -Passing the 'id' attribute of a peer to 'disconnect' will terminate -the connection. - -RETURN VALUE ------------- -On success, an empty object is returned. - -ERRORS ------- -If 'id' is invalid, an error message will be returned: - - { "code" : -1, "message" : "Peer not connected" } - -If the peer has an active channel and 'force' is not set, an error message -will be returned: - - { "code" : -1, "message" : "Peer is in state CHANNELD_NORMAL" } - -AUTHOR ------- -Michael Hawkins . - -SEE ALSO --------- -lightning-connect(1), lightning-listpeers(1) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md new file mode 100644 index 000000000..76469de11 --- /dev/null +++ b/doc/lightning-fundchannel.7.md @@ -0,0 +1,82 @@ +LIGHTNING-FUNDCHANNEL(7) Manual Page +==================================== +lightning-fundchannel - Command for establishing a lightning channel. + +SYNOPSIS +-------- + +**fundchannel** *id* *satoshi* \[*feerate* *announce*\] \[*minconf*\] +\[*utxos*\] + +DESCRIPTION +----------- + +The **fundchannel** RPC command opens a payment channel with a peer by +committing a funding transaction to the blockchain as defined in BOLT +\#2. **fundchannel** by itself does not attempt to open a connection. A +connection must first be established using **connect**. Once the +transaction is confirmed, normal channel operations may begin. Readiness +is indicated by **listpeers** reporting a *state* of CHANNELD\_NORMAL +for the channel. + +*id* is the peer id obtained from **connect**. + +*satoshi* is the amount in satoshis taken from the internal wallet to +fund the channel. The string *all* can be used to specify all available +funds (or 16777215 satoshi if more is available). Otherwise, it is in +satoshi precision; it can be a whole number, a whole number ending in +*sat*, a whole number ending in *000msat*, or a number with 1 to 8 +decimal places ending in *btc*. The value cannot be less than the dust +limit, currently set to 546, nor more than 16777215 satoshi. + +*feerate* is an optional feerate used for the opening transaction and as +initial feerate for commitment and HTLC transactions. It can be one of +the strings *urgent* (aim for next block), *normal* (next 4 blocks or +so) or *slow* (next 100 blocks or so) to use lightningd’s internal +estimates: *normal* is the default. + +*announce* is an optional flag that triggers whether to announce this +channel or not. Defaults to `true`. An unannounced channel is considered +private. + +Otherwise, *feerate* is a number, with an optional suffix: *perkw* means +the number is interpreted as satoshi-per-kilosipa (weight), and *perkb* +means it is interpreted bitcoind-style as satoshi-per-kilobyte. Omitting +the suffix is equivalent to *perkb*. + +*minconf* specifies the minimum number of confirmations that used +outputs should have. Default is 1. + +*utxos* specifies the utxos to be used to fund the channel, as an array +of "txid:vout". + +RETURN VALUE +------------ + +On success, the *tx* and *txid* of the transaction is returned, as well +as the *channel\_id* of the newly created channel. On failure, an error +is reported and the channel is not funded. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 300: The maximum allowed funding amount is exceeded. +- 301: There are not enough funds in the internal wallet (including fees) to create the transaction. +- 302: The output amount is too small, and would be considered dust. +- 303: Broadcasting of the funding transaction failed, the internal call to bitcoin-cli returned with an error. + +Failure may also occur if **lightningd** and the peer cannot agree on +channel parameters (funding limits, channel reserves, fees, etc.). + +SEE ALSO +-------- + +lightning-connect(7), lightning-listfunds(), lightning-listpeers(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-12 11:16:20 CEST diff --git a/doc/lightning-fundchannel.7.txt b/doc/lightning-fundchannel.7.txt deleted file mode 100644 index 4ddd115fe..000000000 --- a/doc/lightning-fundchannel.7.txt +++ /dev/null @@ -1,76 +0,0 @@ -LIGHTNING-FUNDCHANNEL(7) -======================== -:doctype: manpage - -NAME ----- -lightning-fundchannel - Command for establishing a lightning channel. - -SYNOPSIS --------- -*fundchannel* 'id' 'satoshi' ['feerate' 'announce'] ['minconf'] ['utxos'] - -DESCRIPTION ------------ -The *fundchannel* RPC command opens a payment channel with a peer by committing -a funding transaction to the blockchain as defined in BOLT #2. -*fundchannel* by itself does not attempt to open a connection. -A connection must first be established using *connect*. -Once the transaction is confirmed, normal channel operations may begin. -Readiness is indicated by *listpeers* reporting a 'state' of CHANNELD_NORMAL -for the channel. - -'id' is the peer id obtained from *connect*. - -'satoshi' is the amount in satoshis taken from the internal wallet to fund the channel. -The string 'all' can be used to specify all available funds (or 16777215 satoshi if more is available). -Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in 'sat', a whole number ending in '000msat', or a number with 1 to 8 decimal places ending in 'btc'. -The value cannot be less than the dust limit, currently set to 546, nor more -than 16777215 satoshi. - -'feerate' is an optional feerate used for the opening transaction and as initial feerate for -commitment and HTLC transactions. It can be one of the strings -'urgent' (aim for next block), 'normal' (next 4 blocks or so) or 'slow' (next -100 blocks or so) to use lightningd's internal estimates: -'normal' is the default. - -'announce' is an optional flag that triggers whether to announce -this channel or not. Defaults to `true`. An unannounced channel -is considered private. - -Otherwise, 'feerate' is a number, with an optional suffix: -'perkw' means the number is interpreted as satoshi-per-kilosipa -(weight), and 'perkb' means it is interpreted bitcoind-style as -satoshi-per-kilobyte. Omitting the suffix is equivalent to 'perkb'. - -'minconf' specifies the minimum number of confirmations that used outputs should have. Default is 1. - -'utxos' specifies the utxos to be used to fund the channel, as an array of "txid:vout". - -RETURN VALUE ------------- -On success, the 'tx' and 'txid' of the transaction is returned, as well as the -'channel_id' of the newly created channel. -On failure, an error is reported and the channel is not funded. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 300. The maximum allowed funding amount is exceeded. -* 301. There are not enough funds in the internal wallet (including fees) to - create the transaction. -* 302. The output amount is too small, and would be considered dust. -* 303. Broadcasting of the funding transaction failed, the internal call to - bitcoin-cli returned with an error. -* 304. We're still syncing with the bitcoin network. Retry later. - -Failure may also occur if *lightningd* and the peer cannot agree on channel -parameters (funding limits, channel reserves, fees, etc.). - -SEE ALSO --------- -lightning-connect(7), lightning-listfunds(), lightning-listpeers(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-fundchannel_cancel.7.md b/doc/lightning-fundchannel_cancel.7.md new file mode 100644 index 000000000..c777d0333 --- /dev/null +++ b/doc/lightning-fundchannel_cancel.7.md @@ -0,0 +1,45 @@ +LIGHTNING-FUNDCHANNEL\_CANCEL(7) Manual Page +============================================ +lightning-fundchannel\_cancel - Command for completing channel +establishment + +SYNOPSIS +-------- + +**fundchannel\_cancel** *id* + +DESCRIPTION +----------- + +`fundchannel_cancel` is a lower level RPC command. It allows a user to +cancel an initiated channel establishment with a connected peer. + +*id* is the node id of the remote peer with which to cancel the + +RETURN VALUE +------------ + +On success, returns confirmation that the channel establishment has been +canceled. + +On failure, returns an error. + +AUTHOR +------ + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +-------- + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-12 11:16:20 CEST diff --git a/doc/lightning-fundchannel_cancel.7.txt b/doc/lightning-fundchannel_cancel.7.txt deleted file mode 100644 index 049414fb6..000000000 --- a/doc/lightning-fundchannel_cancel.7.txt +++ /dev/null @@ -1,37 +0,0 @@ -LIGHTNING-FUNDCHANNEL_CANCEL(7) -=============================== -:doctype: manpage - -NAME ----- -lightning-fundchannel_cancel - Command for completing channel establishment - -SYNOPSIS --------- -*fundchannel_cancel* 'id' - -DESCRIPTION ------------ -`fundchannel_cancel` is a lower level RPC command. It allows a user to cancel an initiated -channel establishment with a connected peer. - -'id' is the node id of the remote peer with which to cancel the - -RETURN VALUE ------------- -On success, returns confirmation that the channel establishment has been canceled. - -On failure, returns an error. - -AUTHOR ------- -Lisa Neigut is mainly responsible. - -SEE ALSO --------- -lightning-connect(7), lightning-fundchannel(7), lightning-fundchannel_start(7), -lightning-fundchannel_complete(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-fundchannel_complete.7.md b/doc/lightning-fundchannel_complete.7.md new file mode 100644 index 000000000..da54d210a --- /dev/null +++ b/doc/lightning-fundchannel_complete.7.md @@ -0,0 +1,54 @@ +LIGHTNING-FUNDCHANNEL\_COMPLETE(7) Manual Page +============================================== +lightning-fundchannel\_complete - Command for completing channel +establishment + +SYNOPSIS +-------- + +**fundchannel\_complete** *id* *txid* *txout* + +DESCRIPTION +----------- + +`fundchannel_complete` is a lower level RPC command. It allows a user to +complete an initiated channel establishment with a connected peer + +*id* is the node id of the remote peer + +*txid* is the hex string of the funding transaction id. + +*txout* is the integer outpoint of the funding output for this channel. + +Note that the funding transaction should not be broadcast until after +channel establishment has been successfully completed, as the commitment +transactions for this channel are not secured until this command +succesfully completes. + +RETURN VALUE +------------ + +On success, returns a confirmation that *commitments\_secured* and the +derived *channel\_id*. + +On failure, returns an error. + +AUTHOR +------ + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +-------- + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_start(7), lightning-fundchannel\_cancel(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-12 11:16:20 CEST diff --git a/doc/lightning-fundchannel_complete.7.txt b/doc/lightning-fundchannel_complete.7.txt deleted file mode 100644 index a3ccb67e7..000000000 --- a/doc/lightning-fundchannel_complete.7.txt +++ /dev/null @@ -1,46 +0,0 @@ -LIGHTNING-FUNDCHANNEL_COMPLETE(7) -================================= -:doctype: manpage - -NAME ----- -lightning-fundchannel_complete - Command for completing channel establishment - -SYNOPSIS --------- -*fundchannel_complete* 'id' 'txid' 'txout' - -DESCRIPTION ------------ -`fundchannel_complete` is a lower level RPC command. It allows a user to complete an initiated -channel establishment with a connected peer - -'id' is the node id of the remote peer - -'txid' is the hex string of the funding transaction id. - -'txout' is the integer outpoint of the funding output for this channel. - -Note that the funding transaction should not be broadcast until after channel -establishment has been successfully completed, as the commitment transactions -for this channel are not secured until this command succesfully completes. - -RETURN VALUE ------------- -On success, returns a confirmation that 'commitments_secured' and the -derived 'channel_id'. - -On failure, returns an error. - -AUTHOR ------- -Lisa Neigut is mainly responsible. - -SEE ALSO --------- -lightning-connect(7), lightning-fundchannel(7), lightning-fundchannel_start(7), -lightning-fundchannel_cancel(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-fundchannel_start.7.md b/doc/lightning-fundchannel_start.7.md new file mode 100644 index 000000000..72481047b --- /dev/null +++ b/doc/lightning-fundchannel_start.7.md @@ -0,0 +1,53 @@ +LIGHTNING-FUNDCHANNEL\_START(7) Manual Page +=========================================== +lightning-fundchannel\_start - Command for initiating channel +establishment for a lightning channel + +SYNOPSIS +-------- + +**fundchannel\_start** *id* *satoshi* \[*feerate* *announce*\] + +DESCRIPTION +----------- + +`fundchannel_start` is a lower level RPC command. It allows a user to +initiate channel establishment with a connected peer. + +*id* is the node id of the remote peer. + +*satoshi* is the satoshi value that the channel will be funded at. This +value MUST be accurate, otherwise the negotiated commitment transactions +will not encompass the correct channel value. + +*feerate* is an optional field. Sets the feerate for subsequent +commitment transactions. + +*announce* whether or not to annouce this channel. + +RETURN VALUE +------------ + +On success, returns the *funding\_address* for the channel. + +On failure, returns an error. + +AUTHOR +------ + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +-------- + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_complete(7), lightning-fundchannel\_cancel(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-12 11:16:20 CEST diff --git a/doc/lightning-fundchannel_start.7.txt b/doc/lightning-fundchannel_start.7.txt deleted file mode 100644 index 4d49f7b7e..000000000 --- a/doc/lightning-fundchannel_start.7.txt +++ /dev/null @@ -1,45 +0,0 @@ -LIGHTNING-FUNDCHANNEL_START(7) -============================== -:doctype: manpage - -NAME ----- -lightning-fundchannel_start - Command for initiating channel establishment for a lightning channel - -SYNOPSIS --------- -*fundchannel_start* 'id' 'satoshi' ['feerate' 'announce'] - -DESCRIPTION ------------ -`fundchannel_start` is a lower level RPC command. It allows a user to initiate channel -establishment with a connected peer. - -'id' is the node id of the remote peer. - -'satoshi' is the satoshi value that the channel will be funded at. This value MUST be -accurate, otherwise the negotiated commitment transactions will not encompass the correct -channel value. - -'feerate' is an optional field. Sets the feerate for subsequent commitment transactions. - -'announce' whether or not to annouce this channel. - -RETURN VALUE ------------- -On success, returns the 'funding_address' for the channel. - -On failure, returns an error. - -AUTHOR ------- -Lisa Neigut is mainly responsible. - -SEE ALSO --------- -lightning-connect(7), lightning-fundchannel(7), lightning-fundchannel_complete(7), -lightning-fundchannel_cancel(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-getroute.7.md b/doc/lightning-getroute.7.md new file mode 100644 index 000000000..13ebf8be7 --- /dev/null +++ b/doc/lightning-getroute.7.md @@ -0,0 +1,306 @@ +LIGHTNING-GETROUTE(7) Manual Page +================================= +lightning-getroute - Command for routing a payment (low-level). + +SYNOPSIS +-------- + +**getroute** *id* *msatoshi* *riskfactor* \[*cltv*\] \[*fromid*\] +\[*fuzzpercent*\] \[*exclude*\] \[*maxhops*\] + +DESCRIPTION +----------- + +The **getroute** RPC command attempts to find the best route for the +payment of *msatoshi* to lightning node *id*, such that the payment will +arrive at *id* with *cltv*-blocks to spare (default 9). + +*msatoshi* is in millisatoshi precision; it can be a whole number, or a +whole number ending in *msat* or *sat*, or a number with three decimal +places ending in *sat*, or a number with 1 to 11 decimal places ending +in *btc*. + +There are two considerations for how good a route is: how low the fees +are, and how long your payment will get stuck in a delayed output if a +node goes down during the process. The *riskfactor* floating-point field +controls this tradeoff; it is the annual cost of your funds being stuck +(as a percentage). + +For example, if you thought the convenience of keeping your funds liquid +(not stuck) was worth 20% per annum interest, *riskfactor* would be 20. + +If you didn’t care about risk, *riskfactor* would be zero. + +*fromid* is the node to start the route from: default is this node. + +The *fuzzpercent* is a positive floating-point number, representing a +percentage of the actual fee. The *fuzzpercent* is used to distort +computed fees along each channel, to provide some randomization to the +route generated. 0.0 means the exact fee of that channel is used, while +100.0 means the fee used might be from 0 to twice the actual fee. The +default is 5.0, or up to 5% fee distortion. + +*exclude* is a JSON array of short-channel-id/direction (e.g. \[ +"564334x877x1/0", "564195x1292x0/1" \]) which should be excluded from +consideration for routing. The default is not to exclude any channels. + +*maxhops* is the maximum number of channels to return; default is 20. + +RISKFACTOR EFFECT ON ROUTING +---------------------------- + +The risk factor is treated as if it were an additional fee on the route, +for the purposes of comparing routes. + +The formula used is the following approximation: + + risk-fee = amount x blocks-timeout x per-block-cost + +We are given a *riskfactor* expressed as a percentage. There are 52596 +blocks per year, thus *per-block-cost* is *riskfactor* divided by +5,259,600. + +The final result is: + + risk-fee = amount x blocks-timeout x riskfactor / 5259600 + +Here are the risk fees in millisatoshis, using various parameters. I +assume a channel charges the default of 1000 millisatoshis plus 1 +part-per-million. Common to\_self\_delay values on the network at 14 and +144 blocks. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Amount (msat)RiskfactorDelayRisk FeeRoute fee

10,000

1

14

0

1001

10,000

10

14

0

1001

10,000

100

14

2

1001

10,000

1000

14

26

1001

1,000,000

1

14

2

1001

1,000,000

10

14

26

1001

1,000,000

100

14

266

1001

1,000,000

1000

14

2661

1001

100,000,000

1

14

266

1100

100,000,000

10

14

2661

1100

100,000,000

100

14

26617

1100

100,000,000

1000

14

266179

1100

10,000

1

144

0

1001

10,000

10

144

2

1001

10,000

100

144

27

1001

10,000

1000

144

273

1001

1,000,000

1

144

27

1001

1,000,000

10

144

273

1001

1,000,000

100

144

2737

1001

1,000,000

1000

144

27378

1001

100,000,000

1

144

2737

1100

100,000,000

10

144

27378

1100

100,000,000

100

144

273785

1100

100,000,000

1000

144

2737850

1100

+ +RECOMMENDED RISKFACTOR VALUES +----------------------------- + +The default *fuzz* factor is 5%, so as you can see from the table above, +that tends to overwhelm the effect of *riskfactor* less than about 5. + +1 is a conservative value for a stable lightning network with very few +failures. + +1000 is an aggressive value for trying to minimize timeouts at all +costs. + +The default for lightning-pay(7) is 10, which starts to become a major +factor for larger amounts, and is basically ignored for tiny ones. + +RETURN VALUE +------------ + +On success, a "route" array is returned. Each array element contains +*id* (the node being routed through), *msatoshi* (the millisatoshis +sent), *amount\_msat* (the same, with *msat* appended), and *delay* (the +number of blocks to timeout at this node). + +The final *id* will be the destination *id* given in the input. The +difference between the first *msatoshi* minus the *msatoshi* given in +the input is the fee. The first *delay* is the very worst case timeout +for the payment failure, in blocks. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-pay(7), lightning-sendpay(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-01 14:59:36 CEST diff --git a/doc/lightning-getroute.7.txt b/doc/lightning-getroute.7.txt deleted file mode 100644 index 9b6597100..000000000 --- a/doc/lightning-getroute.7.txt +++ /dev/null @@ -1,144 +0,0 @@ -LIGHTNING-GETROUTE(7) -===================== -:doctype: manpage - -NAME ----- -lightning-getroute - Command for routing a payment (low-level). - - -SYNOPSIS --------- -*getroute* 'id' 'msatoshi' 'riskfactor' ['cltv'] ['fromid'] ['fuzzpercent'] ['exclude'] ['maxhops'] - -DESCRIPTION ------------ -The *getroute* RPC command attempts to find the best route for the payment -of 'msatoshi' to lightning node 'id', such that the payment will arrive -at 'id' with 'cltv'-blocks to spare (default 9). - -'msatoshi' is in millisatoshi precision; it can be a whole number, or -a whole number ending in 'msat' or 'sat', or a number with three -decimal places ending in 'sat', or a number with 1 to 11 decimal -places ending in 'btc'. - -There are two considerations for how good a route is: how low the -fees are, and how long your payment will get stuck in a delayed output if a node goes down -during the process. The 'riskfactor' floating-point field controls -this tradeoff; it is the annual cost of your funds being stuck (as a -percentage). - -For example, if you thought the convenience of keeping your funds liquid -(not stuck) was worth 20% per annum interest, 'riskfactor' would be 20. - -If you didn't care about risk, 'riskfactor' would be zero. - -'fromid' is the node to start the route from: default is this node. - -The 'fuzzpercent' is a positive floating-point number, representing a percentage of the actual fee. -The 'fuzzpercent' is used to distort computed fees along each channel, -to provide some randomization to the route generated. -0.0 means the exact fee of that channel is used, -while 100.0 means the fee used might be from 0 to twice the actual fee. -The default is 5.0, or up to 5% fee distortion. - -'exclude' is a JSON array of short-channel-id/direction (e.g. [ "564334x877x1/0", "564195x1292x0/1" ]) which should be excluded from consideration for routing. The default is not to exclude any channels. - -'maxhops' is the maximum number of channels to return; default is 20. - -RISKFACTOR EFFECT ON ROUTING ----------------------------- -The risk factor is treated as if it were an additional fee on the route, -for the purposes of comparing routes. - -The formula used is the following approximation: ----- -risk-fee = amount x blocks-timeout x per-block-cost ----- - -We are given a 'riskfactor' expressed as a percentage. There are 52596 blocks -per year, thus 'per-block-cost' is 'riskfactor' divided by 5,259,600. - -The final result is: ----- -risk-fee = amount x blocks-timeout x riskfactor / 5259600 ----- - -Here are the risk fees in millisatoshis, using various parameters. I -assume a channel charges the default of 1000 millisatoshis plus 1 -part-per-million. Common to_self_delay values on the network at 14 and 144 blocks. - -[options="header"] -|======================= -|Amount (msat) |Riskfactor | Delay |Risk Fee |Route fee -|10,000 |1 | 14 |0 |1001 -|10,000 |10 | 14 |0 |1001 -|10,000 |100 | 14 |2 |1001 -|10,000 |1000 | 14 |26 |1001 - -|1,000,000 |1 | 14 |2 |1001 -|1,000,000 |10 | 14 |26 |1001 -|1,000,000 |100 | 14 |266 |1001 -|1,000,000 |1000 | 14 |2661 |1001 - -|100,000,000 |1 | 14 |266 |1100 -|100,000,000 |10 | 14 |2661 |1100 -|100,000,000 |100 | 14 |26617 |1100 -|100,000,000 |1000 | 14 |266179 |1100 - -|10,000 |1 | 144 |0 |1001 -|10,000 |10 | 144 |2 |1001 -|10,000 |100 | 144 |27 |1001 -|10,000 |1000 | 144 |273 |1001 - -|1,000,000 |1 | 144 |27 |1001 -|1,000,000 |10 | 144 |273 |1001 -|1,000,000 |100 | 144 |2737 |1001 -|1,000,000 |1000 | 144 |27378 |1001 - -|100,000,000 |1 | 144 |2737 |1100 -|100,000,000 |10 | 144 |27378 |1100 -|100,000,000 |100 | 144 |273785 |1100 -|100,000,000 |1000 | 144 |2737850 |1100 -|======================= - -RECOMMENDED RISKFACTOR VALUES ------------------------------ -The default 'fuzz' factor is 5%, so as you can see from the table above, -that tends to overwhelm the effect of 'riskfactor' less than about 5. - -1 is a conservative value for a stable lightning network with very few -failures. - -1000 is an aggressive value for trying to minimize timeouts at all -costs. - -The default for lightning-pay(7) is 10, which starts to become a major -factor for larger amounts, and is basically ignored for tiny ones. - -RETURN VALUE ------------- - -On success, a "route" array is returned. -Each array element contains 'id' (the node being routed through), 'msatoshi' -(the millisatoshis sent), 'amount_msat' (the same, with 'msat' appended), and 'delay' (the number of blocks to timeout at this -node). - -The final 'id' will be the destination 'id' given in the input. The -difference between the first 'msatoshi' minus the 'msatoshi' given in -the input is the fee. The first 'delay' is the very worst case -timeout for the payment failure, in blocks. - -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-pay(7), lightning-sendpay(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md new file mode 100644 index 000000000..3ddd1d0b3 --- /dev/null +++ b/doc/lightning-invoice.7.md @@ -0,0 +1,109 @@ +LIGHTNING-INVOICE(7) Manual Page +================================ +lightning-invoice - Command for accepting payments. + +SYNOPSIS +-------- + +**invoice** *msatoshi* *label* *description* \[*expiry*\] +\[*fallbacks*\] \[*preimage*\] \[*exposeprivatechannels*\] + +DESCRIPTION +----------- + +The **invoice** RPC command creates the expectation of a payment of a +given amount of milli-satoshi: it returns a unique token which another +lightning daemon can use to pay this invoice. This token includes a +*route hint* description of an incoming channel with capacity to pay the +invoice, if any exists. + +The *msatoshi* parameter can be the string "any", which creates an +invoice that can be paid with any amount. Otherwise it is in +millisatoshi precision; it can be a whole number, or a whole number +ending in *msat* or *sat*, or a number with three decimal places ending +in *sat*, or a number with 1 to 11 decimal places ending in *btc*. + +The *label* must be a unique string or number (which is treated as a +string, so "01" is different from "1"); it is never revealed to other +nodes on the lightning network, but it can be used to query the status +of this invoice. + +The *description* is a short description of purpose of payment, e.g. *1 +cup of coffee*. This value is encoded into the BOLT11 invoice and is +viewable by any node you send this invoice to. It must be UTF-8, and +cannot use *\\u* JSON escape codes. + +The *expiry* is optionally the time the invoice is valid for; without a +suffix it is interpreted as seconds, otherwise suffixes *s*, *m*, *h*, +*d*, *w* indicate seconds, minutes, hours, days and weeks respectively. +If no value is provided the default of 604800 (1w) is used. + +The *fallbacks* array is one or more fallback addresses to include in +the invoice (in order from most-preferred to least): note that these +arrays are not currently tracked to fulfill the invoice. + +The *preimage* is a 64-digit hex string to be used as payment preimage +for the created invoice. By default, if unspecified, lightningd will +generate a secure pseudorandom preimage seeded from an appropriate +entropy source on your system. **IMPORTANT**: if you specify the +*preimage*, you are responsible, to ensure appropriate care for +generating using a secure pseudorandom generator seeded with sufficient +entropy, and keeping the preimage secret. This parameter is an advanced +feature intended for use with cutting-edge cryptographic protocols and +should not be used unless explicitly needed. + +If specified, *exposeprivatechannels* overrides the default route hint +logic, which will use unpublished channels only if there are no +published channels. If *true* unpublished channels are always considered +as a route hint candidate; if *false*, never. + +The route hint is selected from the set of incoming channels of which: +peer’s balance minus their reserves is at least *msatoshi*, state is +normal, the peer is connected and not a dead end (i.e. has at least one +other public channel). The selection uses some randomness to prevent +probing, but favors channels that become more balanced after the +payment. + +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. + +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 +not. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 900: An invoice with the given *label* already exists. +- 901: An invoice with the given *preimage* already exists. + +One of the following warnings may occur (on success): +- *warning\_offline* if no channel with a currently connected peer has + the incoming capacity to pay this invoice +- *warning\_capacity* if there is no channel that has both sufficient + incoming capacity and has a peer that is publicly connected (i.e. + not a dead end) + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-sendpay(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-02 18:18:10 CEST diff --git a/doc/lightning-invoice.7.txt b/doc/lightning-invoice.7.txt deleted file mode 100644 index 21a6441fd..000000000 --- a/doc/lightning-invoice.7.txt +++ /dev/null @@ -1,107 +0,0 @@ -LIGHTNING-INVOICE(7) -==================== -:doctype: manpage - -NAME ----- -lightning-invoice - Command for accepting payments. - -SYNOPSIS --------- -*invoice* 'msatoshi' 'label' 'description' ['expiry'] ['fallbacks'] ['preimage'] ['exposeprivatechannels'] - -DESCRIPTION ------------ -The *invoice* RPC command creates the expectation of a payment of a -given amount of milli-satoshi: it returns a unique token which another -lightning daemon can use to pay this invoice. This token includes a -'route hint' description of an incoming channel with capacity to pay -the invoice, if any exists. - -The 'msatoshi' parameter can be the string "any", which creates an invoice -that can be paid with any amount. Otherwise it is in millisatoshi -precision; it can be a whole number, or a whole number ending in 'msat' or -'sat', or a number with three decimal places ending in 'sat', or a number -with 1 to 11 decimal places ending in 'btc'. - -The 'label' must be a unique string or number (which is treated as a -string, so "01" is different from "1"); it is never revealed to other -nodes on the lightning network, but it can be used to query the status -of this invoice. - -The 'description' is a short description of purpose of payment, -e.g. '1 cup of coffee'. This value is encoded into the BOLT11 invoice -and is viewable by any node you send this invoice to. It must be -UTF-8, and cannot use '\u' JSON escape codes. - -The 'expiry' is optionally the time the invoice is valid for; without -a suffix it is interpreted as seconds, otherwise suffixes 's', 'm', -'h', 'd', 'w' indicate seconds, minutes, hours, days and weeks -respectively. If no value is provided the default of 604800 (1w) -is used. - -The 'fallbacks' array is one or more fallback addresses to include in -the invoice (in order from most-preferred to least): note that these -arrays are not currently tracked to fulfill the invoice. - -The 'preimage' is a 64-digit hex string to be used as payment preimage -for the created invoice. -By default, if unspecified, lightningd will generate a secure -pseudorandom preimage seeded from an appropriate entropy source on -your system. -*IMPORTANT*: if you specify the 'preimage', you are responsible, to -ensure appropriate care for generating using a secure pseudorandom -generator seeded with sufficient entropy, and keeping the preimage -secret. -This parameter is an advanced feature intended for use with cutting-edge -cryptographic protocols and should not be used unless explicitly needed. - -If specified, 'exposeprivatechannels' overrides the default route hint -logic, which will use unpublished channels only if there are no -published channels. If 'true' unpublished channels are always -considered as a route hint candidate; if 'false', never. - -The route hint is selected from the set of incoming channels of which: -peer's balance minus their reserves is at least 'msatoshi', state is normal, the -peer is connected and not a dead end (i.e. has at least one other public -channel). The selection uses some randomness to prevent probing, but favors -channels that become more balanced after the payment. - -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. - -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 not. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 900. An invoice with the given 'label' already exists. -* 901. An invoice with the given 'preimage' already exists. - -One of the following warnings may occur (on success): - -* 'warning_offline' if no channel with a currently - connected peer has the incoming capacity to pay this invoice -* 'warning_capacity' if there is no channel that has both sufficient incoming - capacity and has a peer that is publicly connected (i.e. not a dead end) - - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-listinvoice(7), lightning-delinvoice(7), -lightning-getroute(7), lightning-sendpay(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md new file mode 100644 index 000000000..e1ca7de6e --- /dev/null +++ b/doc/lightning-listchannels.7.md @@ -0,0 +1,106 @@ +LIGHTNING-LISTCHANNELS(7) Manual Page +===================================== +lightning-listchannels - Command to query active lightning channels in +the entire network. + +SYNOPSIS +-------- + +**listchannels** \[*short\_channel\_id*\] \[*source*\] + +DESCRIPTION +----------- + +The **listchannels** RPC command returns data on channels that are known +to the node. Because channels may be bidirectional, up to 2 objects will +be returned for each channel (one for each direction). + +If *short\_channel\_id* is supplied, then only known channels with a +matching *short\_channel\_id* are returned. + +If *source* is supplied, then only channels leading from that node id +are returned. + +If neither is supplied, data on all lightning channels known to this +node, are returned. These can be local channels or public channels +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 \#2). +- *fee\_per\_millionth* : The amount (in millionths of a satoshi) +charged per transferred satoshi (BOLT \#2). +- *delay* : The number of blocks delay required to wait for on-chain +settlement when unilaterally closing the channel (BOLT \#2). +- *htlc\_minimum\_msat* : The minimum payment which can be send +through this channel. +- *htlc\_maximum\_msat* : The maximum payment which can be send +through this channel. + +If *short\_channel\_id* or *source* is supplied and no matching channels +are found, a "channels" object with an empty list is returned. + +ERRORS +------ + +If *short\_channel\_id* is not a valid short\_channel\_id, an error +message will be returned: + + { "code" : -32602, + "message" : "'short_channel_id' should be a short channel id, not '...'" } + +Similarly if *source* is not a valid pubkey. + +AUTHOR +------ + +Michael Hawkins <>. + +SEE ALSO +-------- + +lightning-fundchannel(7), lightning-listnodes(7) + +RESOURCES +--------- + +Main web site: + +Lightning RFC site + +- BOLT \#2: + + +- BOLT \#7: + + +------------------------------------------------------------------------ + +Last updated 2019-06-12 11:16:20 CEST diff --git a/doc/lightning-listchannels.7.txt b/doc/lightning-listchannels.7.txt deleted file mode 100644 index 7ebac38d5..000000000 --- a/doc/lightning-listchannels.7.txt +++ /dev/null @@ -1,95 +0,0 @@ -LIGHTNING-LISTCHANNELS(7) -======================= -:doctype: manpage - -NAME ----- -lightning-listchannels - Command to query active lightning channels in the entire network. - -SYNOPSIS --------- -*listchannels* ['short_channel_id'] ['source'] - -DESCRIPTION ------------ -The *listchannels* RPC command returns data on channels that are known to the -node. Because channels may be bidirectional, up to 2 objects will be returned -for each channel (one for each direction). - -If 'short_channel_id' is supplied, then only known channels with a -matching 'short_channel_id' are returned. - -If 'source' is supplied, then only channels leading from that node id -are returned. - -If neither is supplied, data on all lightning channels known to this -node, are returned. These can be local channels or public channels -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 #2). -- 'fee_per_millionth' : The amount (in millionths of a satoshi) charged per -transferred satoshi (BOLT #2). -- 'delay' : The number of blocks delay required to wait for on-chain settlement -when unilaterally closing the channel (BOLT #2). -- 'htlc_minimum_msat' : The minimum payment which can be send through this channel. -- 'htlc_maximum_msat' : The maximum payment which can be send through this channel. - -If 'short_channel_id' or 'source' is supplied and no matching channels -are found, a "channels" object with an empty list is returned. - -ERRORS ------- -If 'short_channel_id' is not a valid short_channel_id, an error message will be -returned: - ----- -{ "code" : -32602, - "message" : "'short_channel_id' should be a short channel id, not '...'" } ----- - -Similarly if 'source' is not a valid pubkey. - -AUTHOR ------- -Michael Hawkins . - -SEE ALSO --------- -lightning-fundchannel(7), lightning-listnodes(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning - -Lightning RFC site - -- BOLT #2: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md -- BOLT #7: https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md new file mode 100644 index 000000000..23b287768 --- /dev/null +++ b/doc/lightning-listforwards.7.md @@ -0,0 +1,62 @@ +LIGHTNING-LISTFORWARDS(7) Manual Page +===================================== +lightning-listforwards - Command showing all htlcs and their +information. + +SYNOPSIS +-------- + +**listforwards** + +DESCRIPTION +----------- + +The **listforwards** RPC command displays all htlcs that have been +attempted to be forwarded by the c-lightning node. + +RETURN VALUE +------------ + +On success one array will be returned: *forwards* with htlcs that have +been processed + +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. + +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): + +- *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). + +AUTHOR +------ + +Rene Pickhardt <> is mainly responsible. + +SEE ALSO +-------- + +lightning-getinfo(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-07-23 00:53:16 CEST diff --git a/doc/lightning-listforwards.7.txt b/doc/lightning-listforwards.7.txt deleted file mode 100644 index 8b2128a44..000000000 --- a/doc/lightning-listforwards.7.txt +++ /dev/null @@ -1,58 +0,0 @@ -LIGHTNING-LISTFORWARDS(7) -========================= -:doctype: manpage - -NAME ----- -lightning-listforwards - Command showing all htlcs and their information. - -SYNOPSIS --------- -*listforwards* - -DESCRIPTION ------------ -The *listforwards* RPC command displays all htlcs that have been attempted to be forwarded by the c-lightning node. - -RETURN VALUE ------------- -On success one array will be returned: 'forwards' with htlcs that have been processed - -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, 'failed' if the routing process could not be completed, or 'local_failed' if the node failed the forward itself. - -- 'received_time' - timestamp when incoming htlc was received. - -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): - -- 'fee', 'fee_msat' - fee offered for forwarding the htlc in msatoshi. - -- 'out_channel' - the short_channel_id of to which the outgoing htlc is supposed to be forwarded. - -- '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). - -AUTHOR ------- -Rene Pickhardt is mainly responsible. - -SEE ALSO --------- -lightning-getinfo(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listfunds.7.md b/doc/lightning-listfunds.7.md new file mode 100644 index 000000000..4d4ae62b2 --- /dev/null +++ b/doc/lightning-listfunds.7.md @@ -0,0 +1,68 @@ +LIGHTNING-LISTFUNDS(7) Manual Page +================================== +lightning-listfunds - Command showing all funds currently managed by the +c-lightning node. + +SYNOPSIS +-------- + +**listfunds** + +DESCRIPTION +----------- + +The **listfunds** RPC command displays all funds available, either in +unspent outputs (UTXOs) in the internal wallet or funds locked in +currently open channels. + +RETURN VALUE +------------ + +On success two arrays will be returned: *outputs* with funds currently +locked onchain in UTXOs and *channels* with funds readily spendable in +channels. + +Each entry in *outputs* will include: +- *txid* +- *output* (the index of the output in the transaction) +- *value* (the output value in satoshis) +- *amount\_msat* (the same as *value*, but in millisatoshi with *msat* + appended) +- *address* +- *status* (whether *unconfirmed*, *confirmed*, or *spent*) + +Each entry in *channels* will include: +- *peer\_id* - the peer with which the channel is opened. +- *short\_channel\_id* - as per BOLT 7 (representing the block, + transaction number and output index of the channel funding + transaction). +- *channel\_sat* - available satoshis on our node’s end of the channel + (values rounded down to satoshis as internal storage is in + millisatoshi). +- *our\_amount\_msat* - same as above, but in millisatoshis with + *msat* appended. +- *channel\_total\_sat* - total channel value in satoshi +- *amount\_msat* - same as above, but in millisatoshis with *msat* + appended. +- *funding\_txid* - funding transaction id. +- *funding\_output* - the index of the output in the funding + transaction. + +AUTHOR +------ + +Felix <> is mainly responsible. + +SEE ALSO +-------- + +lightning-newaddr(7), lightning-fundchannel(7), lightning-withdraw(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-07-28 16:25:20 CEST diff --git a/doc/lightning-listfunds.7.txt b/doc/lightning-listfunds.7.txt deleted file mode 100644 index 65409a0a0..000000000 --- a/doc/lightning-listfunds.7.txt +++ /dev/null @@ -1,70 +0,0 @@ -LIGHTNING-LISTFUNDS(7) -====================== -:doctype: manpage - -NAME ----- -lightning-listfunds - Command showing all funds currently managed by -the c-lightning node. - -SYNOPSIS --------- -*listfunds* - -DESCRIPTION ------------ -The *listfunds* RPC command displays all funds available, either in -unspent outputs (UTXOs) in the internal wallet or funds locked in -currently open channels. - -RETURN VALUE ------------- -On success two arrays will be returned: 'outputs' with funds -currently locked onchain in UTXOs and 'channels' with funds -readily spendable in channels. - -Each entry in 'outputs' will include: - -- 'txid' - -- 'output' (the index of the output in the transaction) - -- 'value' (the output value in satoshis) - -- 'amount_msat' (the same as 'value', but in millisatoshi with 'msat' appended) - -- 'address' - -- 'status' (whether 'unconfirmed', 'confirmed', or 'spent') - -Each entry in 'channels' will include: - -- 'peer_id' - the peer with which the channel is opened. - -- 'short_channel_id' - as per BOLT 7 (representing the block, transaction -number and output index of the channel funding transaction). - -- 'channel_sat' - available satoshis on our node's end of the channel -(values rounded down to satoshis as internal storage is in millisatoshi). - -- 'our_amount_msat' - same as above, but in millisatoshis with 'msat' appended. - -- 'channel_total_sat' - total channel value in satoshi - -- 'amount_msat' - same as above, but in millisatoshis with 'msat' appended. - -- 'funding_txid' - funding transaction id. - -- 'funding_output' - the index of the output in the funding transaction. - -AUTHOR ------- -Felix is mainly responsible. - -SEE ALSO --------- -lightning-newaddr(7), lightning-fundchannel(7), lightning-withdraw(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md new file mode 100644 index 000000000..91e74b3c6 --- /dev/null +++ b/doc/lightning-listinvoices.7.md @@ -0,0 +1,48 @@ +LIGHTNING-LISTINVOICES(7) Manual Page +===================================== +lightning-listinvoices - Command for querying invoice status + +SYNOPSIS +-------- + +**listinvoices** \[*label*\] + +DESCRIPTION +----------- + +The **listinvoices** RPC command gets the status of a specific invoice, +if it exists, or the status of all invoices if given no argument. + +RETURN VALUE +------------ + +On success, an array *invoices* of objects is returned. Each object +contains *label*, *payment\_hash*, *status* (one of *unpaid*, *paid* or +*expired*), and *expiry\_time* (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 *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*. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-listinvoices.7.txt b/doc/lightning-listinvoices.7.txt deleted file mode 100644 index 51a7fe058..000000000 --- a/doc/lightning-listinvoices.7.txt +++ /dev/null @@ -1,43 +0,0 @@ -LIGHTNING-LISTINVOICES(7) -========================= -:doctype: manpage - -NAME ----- -lightning-listinvoices - Command for querying invoice status - -SYNOPSIS --------- -*listinvoices* ['label'] - -DESCRIPTION ------------ -The *listinvoices* RPC command gets the status of a specific invoice, if -it exists, or the status of all invoices if given no argument. - -RETURN VALUE ------------- -On success, an array 'invoices' of objects is returned. Each object contains -'label', 'payment_hash', 'status' (one of 'unpaid', 'paid' or 'expired'), and -'expiry_time' (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 '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'. - -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md new file mode 100644 index 000000000..848f3ae9f --- /dev/null +++ b/doc/lightning-listpays.7.md @@ -0,0 +1,67 @@ +LIGHTNING-LISTPAYS(7) Manual Page +================================= +lightning-listpays - Command for querying payment status + +SYNOPSIS +-------- + +**listpays** \[bolt11\] + +DESCRIPTION +----------- + +The **listpay** RPC command gets the status of all *pay* commands, or a +single one if *bolt11* is specified. + +RETURN VALUE +------------ + +On success, an array of objects is returned. Each object contains: + + *bolt11* +the *bolt11* argument given to *pay* (see below for exceptions). + + *status* +one of *complete*, *failed* or *pending*. + + *payment\_preimage* +(if *status* is *complete*) proves payment was received. + + *label* +optional *label*, if provided to *pay*. + + *amount\_sent\_msat* +total amount sent, in "NNNmsat" format. + +For old payments (pre-0.7) we didn’t save the *bolt11* string, so in its +place are three other fields: + + *payment\_hash* +the hash of the *payment\_preimage* which will prove payment. + + *destination* +the final destination of the payment. + + *amount\_msat* +the amount the destination received, in "NNNmsat" format. + +These three can all be extracted from *bolt11*, hence are obsolete. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-pay(7), lightning-paystatus(7), lightning-listsendpays(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-listpays.7.txt b/doc/lightning-listpays.7.txt deleted file mode 100644 index 1da3fa929..000000000 --- a/doc/lightning-listpays.7.txt +++ /dev/null @@ -1,49 +0,0 @@ -LIGHTNING-LISTPAYS(7) -===================== -:doctype: manpage - -NAME ----- -lightning-listpays - Command for querying payment status - -SYNOPSIS --------- -*listpays* [bolt11] - -DESCRIPTION ------------ - -The *listpay* RPC command gets the status of all 'pay' commands, or a single -one if 'bolt11' is specified. - -RETURN VALUE ------------- -On success, an array of objects is returned. Each object contains: - -'bolt11':: the 'bolt11' argument given to 'pay' (see below for exceptions). -'status':: one of 'complete', 'failed' or 'pending'. -'payment_preimage':: (if 'status' is 'complete') proves payment was received. -'label':: optional 'label', if provided to 'pay'. -'amount_sent_msat':: total amount sent, in "NNNmsat" format. - -For old payments (pre-0.7) we didn't save the 'bolt11' string, so in -its place are three other fields: - -'payment_hash':: the hash of the 'payment_preimage' which will prove payment. -'destination':: the final destination of the payment. -'amount_msat':: the amount the destination received, in "NNNmsat" format. - -These three can all be extracted from 'bolt11', hence are obsolete. -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-pay(7), lightning-paystatus(7), lightning-listsendpays(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md new file mode 100644 index 000000000..16f45c2ce --- /dev/null +++ b/doc/lightning-listpeers.7.md @@ -0,0 +1,89 @@ +LIGHTNING-LISTPEERS(7) Manual Page +================================== +lightning-listpeers - Command for returning data on connected lightning +nodes. + +SYNOPSIS +-------- + +**listpeers** \[*id*\] \[*level*\] + +DESCRIPTION +----------- + +The **listpeers** RPC command returns data on nodes that are connected +or are not connected but have open channels with this node. + +Once a connection to another lightning node has been established, using +the **connect** command, data on the node can be returned using +**listpeers** and the *id* that was used with the **connect** command. + +If no *id* is supplied, then data on all lightning nodes that are +connected, or not connected but have open channels with this node, are +returned. + +Supplying *id* will filter the results to only return data on a node +with a matching *id*, if one exists. + +Supplying *level* will show log entries related to that peer at the +given log level. Valid log levels are "io", "debug", "info", and +"unusual". + +If a channel is open with a node and the connection has been lost, then +the node will still appear in the output of the command and the value of +the *connected* attribute of the node will be "false". + +The channel will remain open for a set blocktime, after which if the +connection has not been re-established, the channel will close and the +node will no longer appear in the command output. + +RETURN VALUE +------------ + +On success, an object with a "peers" key is returned containing a list +of 0 or more objects. + +Each object in the list contains the following data: +- *id* : The unique id of the peer +- *connected* : A boolean value showing the connection status +- *netaddr* : A list of network addresses the node is listening on +- *globalfeatures* : Bit flags showing supported global features (BOLT \#9) +- *localfeatures* : Bit flags showing supported local features (BOLT \#9) +- *channels* : An list of channel id’s open on the peer +- *log* : Only present if *level* is set. List logs related to the +peer at the specified *level* + +If *id* is supplied and no matching nodes are found, a "peers" object +with an empty list is returned. + +ERRORS +------ + +If *id* is not a valid public key, an error message will be returned: + + { "code" : -32602, "message" : "'id' should be a pubkey, not '...'" } + +If *level* is not a valid log level, an error message will be returned: + + { "code" : -32602, "message" "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" } + +AUTHOR +------ + +Michael Hawkins <>. + +SEE ALSO +-------- + +lightning-connect(7) + +RESOURCES +--------- + +Main web site: Lightning +RFC site (BOLT \#9): + + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-listpeers.7.txt b/doc/lightning-listpeers.7.txt deleted file mode 100644 index 96bb956ce..000000000 --- a/doc/lightning-listpeers.7.txt +++ /dev/null @@ -1,79 +0,0 @@ -LIGHTNING-LISTPEERS(7) -======================= -:doctype: manpage - -NAME ----- -lightning-listpeers - Command for returning data on connected lightning nodes. - -SYNOPSIS --------- -*listpeers* ['id'] ['level'] - -DESCRIPTION ------------ -The *listpeers* RPC command returns data on nodes that are connected or are not -connected but have open channels with this node. - -Once a connection to another lightning node has been established, using the -*connect* command, data on the node can be returned using *listpeers* and the -'id' that was used with the *connect* command. - -If no 'id' is supplied, then data on all lightning nodes that are connected, -or not connected but have open channels with this node, are returned. - -Supplying 'id' will filter the results to only return data on a node with a -matching 'id', if one exists. - -Supplying 'level' will show log entries related to that peer at the given log -level. Valid log levels are "io", "debug", "info", and "unusual". - -If a channel is open with a node and the connection has been lost, then the -node will still appear in the output of the command and the value of the -'connected' attribute of the node will be "false". - -The channel will remain open for a set blocktime, after which if the connection -has not been re-established, the channel will close and the node will no longer -appear in the command output. - -RETURN VALUE ------------- -On success, an object with a "peers" key is returned containing a list of 0 or -more objects. - -Each object in the list contains the following data: - -- 'id' : The unique id of the peer -- 'connected' : A boolean value showing the connection status -- 'netaddr' : A list of network addresses the node is listening on -- 'globalfeatures' : Bit flags showing supported global features (BOLT #9) -- 'localfeatures' : Bit flags showing supported local features (BOLT #9) -- 'channels' : An list of channel id's open on the peer -- 'log' : Only present if 'level' is set. List logs related to the peer at the -specified 'level' - -If 'id' is supplied and no matching nodes are found, a "peers" object with an -empty list is returned. - -ERRORS ------- -If 'id' is not a valid public key, an error message will be returned: - - { "code" : -32602, "message" : "'id' should be a pubkey, not '...'" } - -If 'level' is not a valid log level, an error message will be returned: - - { "code" : -32602, "message" "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" } - -AUTHOR ------- -Michael Hawkins . - -SEE ALSO --------- -lightning-connect(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning -Lightning RFC site (BOLT #9): https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md new file mode 100644 index 000000000..c21fe4db7 --- /dev/null +++ b/doc/lightning-listsendpays.7.md @@ -0,0 +1,72 @@ +LIGHTNING-LISTSENDPAYS(7) Manual Page +===================================== +lightning-listsendpays - Low-level command for querying sendpay status + +SYNOPSIS +-------- + +**listsendpays** \[*bolt11*\] \[*payment\_hash*\] + +DESCRIPTION +----------- + +The **listsendpays** RPC command gets the status of all *sendpay* +commands (which is also used by the *pay* command), or with *bolt11* or +*payment\_hash* limits results to that specific payment. You cannot +specify both. + +Note that in future there may be more than one concurrent *sendpay* +command per *pay*, so this command should be used with caution. + +RETURN VALUE +------------ + +On success, an array of objects is returned. Each object contains: + + *id* +unique internal value assigned at creation + + *payment\_hash* +the hash of the *payment\_preimage* which will prove payment. + + *destination* +the final destination of the payment. + + *amount\_msat* +the amount the destination received, in "NNNmsat" format. + + *created\_at* +the UNIX timestamp showing when this payment was initiated. + + *status* +one of *complete*, *failed* or *pending*. + + *payment\_preimage* +(if *status* is *complete*) proves payment was received. + + *label* +optional *label*, if provided to *sendpay*. + + *bolt11* +the *bolt11* argument given to *pay* (may be missing for pre-0.7 +payments). + +AUTHOR +------ + +Christian Decker <> is mainly +responsible. + +SEE ALSO +-------- + +lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:12:10 CEST diff --git a/doc/lightning-listsendpays.7.txt b/doc/lightning-listsendpays.7.txt deleted file mode 100644 index d547a8e4e..000000000 --- a/doc/lightning-listsendpays.7.txt +++ /dev/null @@ -1,50 +0,0 @@ -LIGHTNING-LISTSENDPAYS(7) -======================== -:doctype: manpage - -NAME ----- -lightning-listsendpays - Low-level command for querying sendpay status - -SYNOPSIS --------- -*listsendpays* ['bolt11'] ['payment_hash'] - -DESCRIPTION ------------ - -The *listsendpays* RPC command gets the status of all 'sendpay' -commands (which is also used by the 'pay' command), or with 'bolt11' -or 'payment_hash' limits results to that specific payment. You cannot -specify both. - -Note that in future there may be more than one concurrent 'sendpay' -command per 'pay', so this command should be used with caution. - -RETURN VALUE ------------- -On success, an array of objects is returned. Each object contains: - -'id':: unique internal value assigned at creation -'payment_hash':: the hash of the 'payment_preimage' which will prove payment. -'destination':: the final destination of the payment. -'amount_msat':: the amount the destination received, in "NNNmsat" format. -'created_at':: the UNIX timestamp showing when this payment was initiated. -'status':: one of 'complete', 'failed' or 'pending'. -'payment_preimage':: (if 'status' is 'complete') proves payment was received. -'label':: optional 'label', if provided to 'sendpay'. -'bolt11':: the 'bolt11' argument given to 'pay' (may be missing for pre-0.7 payments). - -//FIXME:Enumerate errors - -AUTHOR ------- -Christian Decker is mainly responsible. - -SEE ALSO --------- -lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-newaddr.7.md b/doc/lightning-newaddr.7.md new file mode 100644 index 000000000..003905cd6 --- /dev/null +++ b/doc/lightning-newaddr.7.md @@ -0,0 +1,58 @@ +LIGHTNING-NEWADDR(7) Manual Page +================================ +lightning-newaddr - Command for generating a new address to be used by +c-lightning. + +SYNOPSIS +-------- + +**newaddr** \[ *addresstype* \] + +DESCRIPTION +----------- + +The **newaddr** RPC command generates a new address which can +subsequently be used to fund channels managed by the c-lightning node. + +The funding transaction needs to be confirmed before funds can be used. + +*addresstype* specifies the type of address wanted; i.e. *p2sh-segwit* +(e.g. 2MxaozoqWwiUcuD9KKgUSrLFDafLqimT9Ta on bitcoin testnet or +3MZxzq3jBSKNQ2e7dzneo9hy4FvNzmMmt3 on bitcoin mainnet) or *bech32 ' +(e.g. tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg on bitcoin testnet or +bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej on +bitcoin mainnet). The special value 'all* generates both address types +for the same underlying key. + +If not specified the address generated is bech32. + +RETURN VALUE +------------ + +On success, a *bech32* address and/or a *p2sh-segwit* address will be +returned. + +ERRORS +------ + +If an unrecognized address type is requested an error message will be +returned. + +AUTHOR +------ + +Felix <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listfunds(7), lightning-fundchannel(7), lightning-withdraw(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:34:18 CEST diff --git a/doc/lightning-newaddr.7.txt b/doc/lightning-newaddr.7.txt deleted file mode 100644 index 0cdd21a31..000000000 --- a/doc/lightning-newaddr.7.txt +++ /dev/null @@ -1,48 +0,0 @@ -LIGHTNING-NEWADDR(7) -==================== -:doctype: manpage - -NAME ----- -lightning-newaddr - Command for generating a new address to -be used by c-lightning. - -SYNOPSIS --------- -*newaddr* [ 'addresstype' ] - -DESCRIPTION ------------ -The *newaddr* RPC command generates a new address which can -subsequently be used to fund channels managed by the c-lightning node. - -The funding transaction needs to be confirmed before funds can be used. - -'addresstype' specifies the type of address wanted; i.e. -'p2sh-segwit' (e.g. 2MxaozoqWwiUcuD9KKgUSrLFDafLqimT9Ta on bitcoin testnet -or 3MZxzq3jBSKNQ2e7dzneo9hy4FvNzmMmt3 on bitcoin mainnet) or 'bech32 ' -(e.g. tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg on bitcoin testnet or -bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej on bitcoin mainnet). -The special value 'all' generates both address types for the same underlying key. - -If not specified the address generated is bech32. - -RETURN VALUE ------------- -On success, a 'bech32' address and/or a 'p2sh-segwit' address will be returned. - -ERRORS ------- -If an unrecognized address type is requested an error message will be returned. - -AUTHOR ------- -Felix is mainly responsible. - -SEE ALSO --------- -lightning-listfunds(7), lightning-fundchannel(7), lightning-withdraw(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-pay.7.md b/doc/lightning-pay.7.md new file mode 100644 index 000000000..f57957440 --- /dev/null +++ b/doc/lightning-pay.7.md @@ -0,0 +1,135 @@ +LIGHTNING-PAY(7) Manual Page +============================ +lightning-pay - Command for sending a payment to a BOLT11 invoice + +SYNOPSIS +-------- + +**pay** *bolt11* \[*msatoshi*\] \[*label*\] \[*riskfactor*\] +\[*maxfeepercent*\] \[*retry\_for*\] \[*maxdelay*\] \[*exemptfee*\] + +DESCRIPTION +----------- + +The **pay** RPC command attempts to find a route to the given +destination, and send the funds it asks for. If the *bolt11* does not +contain an amount, *msatoshi* is required, otherwise if it is specified +it must be *null*. *msatoshi* is in millisatoshi precision; it can be a +whole number, or a whole number with suffix *msat* or *sat*, or a three +decimal point number with suffix *sat*, or an 1 to 11 decimal point +number suffixed by *btc*. + +The *label* field is used to attach a label to payments, and is returned +in lightning-listpays(7) and lightning-listsendpays(7). The *riskfactor* +is described in detail in lightning-getroute(7), and defaults to 10. The +*maxfeepercent* limits the money paid in fees, and defaults to 0.5. The +`` maxfeepercent' is a percentage of the amount that is to be paid. The `exemptfee `` +option can be used for tiny payments which would be dominated by the fee +leveraged by forwarding nodes. Setting `exemptfee` allows the +`maxfeepercent` check to be skipped on fees that are smaller than +`exemptfee` (default: 5000 millisatoshi). + +The response will occur when the payment fails or succeeds. Once a +payment has succeeded, calls to **pay** with the same *bolt11* will +succeed immediately. + +Until *retry\_for* seconds passes (default: 60), the command will keep +finding routes and retrying the payment. However, a payment may be +delayed for up to `maxdelay` blocks by another node; clients should be +prepared for this worst case. + +When using *lightning-cli*, you may skip optional parameters by using +*null*. Alternatively, use **-k** option to provide parameters by name. + +RANDOMIZATION +------------- + +To protect user privacy, the payment algorithm performs some +randomization. + +1: Route Randomization + +2: Shadow Route + +Route randomization means the payment algorithm does not always use the +lowest-fee or shortest route. This prevents some highly-connected node +from learning all of the user payments by reducing their fees below the +network average. + +Shadow route means the payment algorithm will virtually extend the time +delays along the route, making it appear to intermediate nodes that the +route is longer than it actually is. This prevents intermediate nodes +from reliably guessing their distance from the payee. + +Route randomization will never exceed *maxfeepercent* of the payment. +Route randomization and shadow routing will not take routes that would +exceed *maxdelay*. + +RETURN VALUE +------------ + +On success, this returns the *payment\_preimage* which hashes to the +*payment\_hash* to prove that the payment was successful. It will also +return, a *getroute\_tries* and a *sendpay\_tries* statistics for the +number of times it internally called **getroute** and **sendpay**. + +You can monitor the progress and retries of a payment using the +lightning-paystatus(7) command. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 201: Already paid with this *hash* using different amount or +destination. +- 203: Permanent failure at destination. The *data* field of the error +will be routing failure object. +- 205: Unable to find a route. +- 206: Route too expensive. Either the fee or the needed total +locktime for the route exceeds your *maxfeepercent* or *maxdelay* +settings, respectively. The *data* field of the error will indicate +the actual *fee* as well as the *feepercent* percentage that the fee +has of the destination payment amount. It will also indicate the +actual *delay* along the route. +- 207: Invoice expired. Payment took too long before expiration, or +already expired at the time you initiated payment. The *data* field +of the error indicates *now* (the current time) and *expiry* (the +invoice expiration) as UNIX epoch time in seconds. +- 210: Payment timed out without a payment in progress. + +Error codes 202 and 204 will only get reported at **sendpay**; in +**pay** we will keep retrying if we would have gotten those errors. + +A routing failure object has the fields below: +- *erring\_index*: The index of the node along the route that reported +the error. 0 for the local node, 1 for the first hop, and so on. +- *erring\_node*: The hex string of the pubkey id of the node that +reported the error. +- *erring\_channel*: The short channel ID of the channel that has the +error, or *0:0:0* if the destination node raised the error. +- *failcode*: The failure code, as per BOLT \#4. +- *channel\_update*. The hex string of the *channel\_update* message +received from the remote node. Only present if error is from the +remote node and the *failcode* has the UPDATE bit set, as per BOLT \#4. + +The *data* field of errors will include statistics *getroute\_tries* and +*sendpay\_tries*. It will also contain a *failures* field with detailed +data about routing errors. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listpays(7), lightning-decodepay(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-getroute(7), lightning-invoice(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-01 14:59:36 CEST diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt deleted file mode 100644 index 92b32f77c..000000000 --- a/doc/lightning-pay.7.txt +++ /dev/null @@ -1,151 +0,0 @@ -LIGHTNING-PAY(7) -================ -:doctype: manpage - -NAME ----- -lightning-pay - Command for sending a payment to a BOLT11 invoice - -SYNOPSIS --------- -*pay* 'bolt11' ['msatoshi'] ['label'] ['riskfactor'] ['maxfeepercent'] ['retry_for'] ['maxdelay'] ['exemptfee'] - -DESCRIPTION ------------ - -The *pay* RPC command attempts to find a route to the given destination, -and send the funds it asks for. If the 'bolt11' does not contain an amount, -'msatoshi' is required, otherwise if it is specified it must be 'null'. -'msatoshi' is in millisatoshi precision; it can be a whole number, or -a whole number with suffix 'msat' or 'sat', or a three decimal -point number with suffix 'sat', or an 1 to 11 decimal point number -suffixed by 'btc'. - -The 'label' field is used to attach a label to payments, and is returned -in lightning-listpays(7) and lightning-listsendpays(7). -The 'riskfactor' is described in detail -in lightning-getroute(7), and defaults to 10. -The 'maxfeepercent' limits the money paid in fees, and defaults to 0.5. -The `maxfeepercent' is a percentage of the amount that is to be -paid. -The `exemptfee` option can be used for tiny payments which would be dominated by -the fee leveraged by forwarding nodes. Setting `exemptfee` allows the -`maxfeepercent` check to be skipped on fees that are smaller than `exemptfee` -(default: 5000 millisatoshi). - -The response will occur when the payment fails or succeeds. Once a -payment has succeeded, calls to *pay* with the same 'bolt11' will -succeed immediately. - -Until 'retry_for' seconds passes (default: 60), the command will keep -finding routes and retrying the payment. However, a payment may be -delayed for up to `maxdelay` blocks by another node; clients should be -prepared for this worst case. - -When using 'lightning-cli', you may skip optional parameters by using -'null'. -Alternatively, use *-k* option to provide parameters by name. - -RANDOMIZATION -------------- - -To protect user privacy, the payment algorithm performs some randomization. - -1. Route Randomization -2. Shadow Route - -Route randomization means the payment algorithm -does not always use the lowest-fee or shortest route. -This prevents some highly-connected node -from learning all of the user payments -by reducing their fees below -the network average. - -Shadow route means the payment algorithm -will virtually extend the time delays -along the route, -making it appear to intermediate nodes -that the route is longer than it actually is. -This prevents intermediate nodes -from reliably guessing their distance -from the payee. - -Route randomization -will never exceed 'maxfeepercent' of the payment. -Route randomization and shadow routing -will not take routes that would exceed 'maxdelay'. - -RETURN VALUE ------------- - -On success, this returns the 'payment_preimage' which hashes to the -'payment_hash' to prove that the payment was successful. -It will also return, a 'getroute_tries' and a 'sendpay_tries' -statistics for the number of times it internally called *getroute* -and *sendpay*. - -You can monitor the progress and retries of a payment using the -lightning-paystatus(7) command. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 201. Already paid with this 'hash' using different amount or - destination. -* 203. Permanent failure at destination. The 'data' field of - the error will be routing failure object. -* 205. Unable to find a route. -* 206. Route too expensive. - Either the fee or the needed total locktime for the route - exceeds your 'maxfeepercent' or 'maxdelay' settings, - respectively. - The 'data' field of the error will indicate the actual 'fee' - as well as the 'feepercent' percentage that the fee has of the - destination payment amount. - It will also indicate the actual 'delay' along the route. -* 207. Invoice expired. Payment took too long before expiration, - or already expired at the time you initiated payment. - The 'data' field of the error indicates 'now' (the current time) - and 'expiry' (the invoice expiration) as UNIX epoch time in - seconds. -* 210. Payment timed out without a payment in progress. - -Error codes 202 and 204 will only get reported at *sendpay*; -in *pay* we will keep retrying if we would have gotten those -errors. - -A routing failure object has the fields below: - -* 'erring_index'. The index of the node along the route that - reported the error. 0 for the local node, 1 for the first - hop, and so on. -* 'erring_node'. The hex string of the pubkey id of the node - that reported the error. -* 'erring_channel'. The short channel ID of the channel that - has the error, or '0:0:0' if the destination node raised - the error. -* 'failcode'. The failure code, as per BOLT #4. -* 'channel_update'. The hex string of the 'channel_update' - message received from the remote node. Only present if - error is from the remote node and the 'failcode' has the - UPDATE bit set, as per BOLT #4. - -The 'data' field of errors will include statistics -'getroute_tries' and 'sendpay_tries'. -It will also contain a 'failures' field with detailed data -about routing errors. - - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-listpays(7), lightning-decodepay(7), -lightning-listinvoice(7), lightning-delinvoice(7), -lightning-getroute(7), lightning-invoice(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md new file mode 100644 index 000000000..2a91fcad7 --- /dev/null +++ b/doc/lightning-plugin.7.md @@ -0,0 +1,53 @@ +LIGHTNING-PLUGIN(7) Manual Page +=============================== +lightning-plugin - Manage plugins with RPC + +SYNOPSIS +-------- + +**plugin** command \[parameter\] \[second\_parameter\] + +DESCRIPTION +----------- + +The **plugin** RPC command allows to manage plugins without having to +restart lightningd. It takes 1 to 3 parameters: a command +(start/stop/startdir/rescan/list) which describes the action to take and +optionally one or two parameters which describes the plugin on which the +action has to be taken. + +The *start* command takes a path as parameter and will load the plugin +available from this path. + +The *stop* command takes a plugin name as parameter and will kill and +unload the specified plugin. + +The *startdir* command takes a directory path as parameter and will load +all plugins this directory contains. + +The *rescan* command starts all not-already-loaded plugins from the +default plugins directory (by default *~/.lightning/plugins*). + +The *list* command will return all the active plugins. + +RETURN VALUE +------------ + +On success, this returns an array *plugins* of objects, one by plugin. +Each object contains the name of the plugin (*name* field) and its +status (*active* boolean field). Since plugins are configured +asynchronously, a freshly started plugin may not appear immediately. + +AUTHOR +------ + +Antoine Poinsot <> is mainly responsible. + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-07-29 12:57:57 CEST diff --git a/doc/lightning-plugin.7.txt b/doc/lightning-plugin.7.txt deleted file mode 100644 index 1e86b922f..000000000 --- a/doc/lightning-plugin.7.txt +++ /dev/null @@ -1,48 +0,0 @@ -LIGHTNING-PLUGIN(7) -=================== -:doctype: manpage - -NAME ----- -lightning-plugin - Manage plugins with RPC - -SYNOPSIS --------- -*plugin* command [parameter] [second_parameter] - -DESCRIPTION ------------ - -The *plugin* RPC command allows to manage plugins without having to restart lightningd. -It takes 1 to 3 parameters: a command (start/stop/startdir/rescan/list) which describes the -action to take and optionally one or two parameters which describes the plugin on which -the action has to be taken. - -The 'start' command takes a path as parameter and will load the plugin available from this -path. - -The 'stop' command takes a plugin name as parameter and will kill and unload the specified -plugin. - -The 'startdir' command takes a directory path as parameter and will load all plugins this -directory contains. - -The 'rescan' command starts all not-already-loaded plugins from the default plugins directory -(by default '~/.lightning/plugins'). - -The 'list' command will return all the active plugins. - -RETURN VALUE ------------- - -On success, this returns an array 'plugins' of objects, one by plugin. Each object contains -the name of the plugin ('name' field) and its status ('active' boolean field). -Since plugins are configured asynchronously, a freshly started plugin may not appear immediately. - -AUTHOR ------- -Antoine Poinsot is mainly responsible. - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-sendpay.7.md b/doc/lightning-sendpay.7.md new file mode 100644 index 000000000..ecf2da57c --- /dev/null +++ b/doc/lightning-sendpay.7.md @@ -0,0 +1,107 @@ +LIGHTNING-SENDPAY(7) Manual Page +================================ +lightning-sendpay - Low-level command for sending a payment via a route. + +SYNOPSIS +-------- + +**sendpay** *route* *payment\_hash* \[*label*\] \[*msatoshi*\] +\[*bolt11*\] + +DESCRIPTION +----------- + +The **sendpay** RPC command attempts to send funds associated with the +given *payment\_hash*, along a route to the final destination in the +route. + +Generally, a client would call lightning-getroute(7) to resolve a route, +then use **sendpay** to send it. If it fails, it would call +lightning-getroute(7) again to retry. + +The response will occur when the payment is on its way to the +destination. The **sendpay** RPC command does not wait for definite +success or definite failure of the payment. Instead, use the +**waitsendpay** RPC command to poll or wait for definite success or +definite failure. + +The *label* and *bolt11* parameters, if provided, will be returned in +*waitsendpay* and *listsendpays* results. + +The *msatoshi* amount, if provided, is the amount that will be recorded +as the target payment value. If not specified, it will be the final +amount to the destination. If specified, then the final amount at the +destination must be from the specified *msatoshi* to twice the specified +*msatoshi*, inclusive. This is intended to obscure payments by +overpaying slightly at the destination; the actual target payment is +what should be specified as the *msatoshi* argument. *msatoshi* is in +millisatoshi precision; it can be a whole number, or a whole number +ending in *msat* or *sat*, or a number with three decimal places ending +in *sat*, or a number with 1 to 11 decimal places ending in *btc*. + +Once a payment has succeeded, calls to **sendpay** with the same +*payment\_hash* but a different *msatoshi* or destination will fail; +this prevents accidental multiple payments. Calls to **sendpay** with +the same *payment\_hash*, *msatoshi*, and destination as a previous +successful payment (even if a different route) will return immediately +with success. + +RETURN VALUE +------------ + +On success, an object similar to the output of **listsendpays** will be +returned. This object will have a *status* field that is typically the +string *"pending"*, but may be *"complete"* if the payment was already +performed successfully. + +On error, if the error occurred from a node other than the final +destination, the route table will be updated so that +lightning-getroute(7) should return an alternate route (if any). An +error from the final destination implies the payment should not be +retried. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 201: Already paid with this *hash* using different amount or + destination. +- 202: Unparseable onion reply. The *data* field of the error will + have an *onionreply* field, a hex string representation of the raw + onion reply. +- 203: Permanent failure at destination. The *data* field of the error + will be routing failure object. +- 204: Failure along route; retry a different route. The *data* field + of the error will be routing failure object. + +A routing failure object has the fields below: +- *erring\_index*. The index of the node along the route that reported + the error. 0 for the local node, 1 for the first hop, and so on. +- *erring\_node*. The hex string of the pubkey id of the node that + reported the error. +- *erring\_channel*. The short channel ID of the channel that has the + error, or *0:0:0* if the destination node raised the error. +- *failcode*. The failure code, as per BOLT \#4. +- *channel\_update*. The hex string of the *channel\_update* message + received from the remote node. Only present if error is from the + remote node and the *failcode* has the UPDATE bit set, as per BOLT + \#4. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-invoice(7), lightning-pay(7), +lightning-waitsendpay(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-08-01 14:59:36 CEST diff --git a/doc/lightning-sendpay.7.txt b/doc/lightning-sendpay.7.txt deleted file mode 100644 index 7835ca89a..000000000 --- a/doc/lightning-sendpay.7.txt +++ /dev/null @@ -1,109 +0,0 @@ -LIGHTNING-SENDPAY(7) -==================== -:doctype: manpage - -NAME ----- -lightning-sendpay - Low-level command for sending a payment via a route. - -SYNOPSIS --------- -*sendpay* 'route' 'payment_hash' ['label'] ['msatoshi'] ['bolt11'] - -DESCRIPTION ------------ - -The *sendpay* RPC command attempts to send funds associated with the -given 'payment_hash', along a route to the final destination in the route. - -Generally, a client would call lightning-getroute(7) to resolve a route, then -use *sendpay* to send it. If it fails, it would call lightning-getroute(7) -again to retry. - -The response will occur when the payment is on its way to the -destination. -The *sendpay* RPC command does not wait for definite success or -definite failure of the payment. -Instead, use the *waitsendpay* RPC command to poll or wait for -definite success or definite failure. - -The 'label' and 'bolt11' parameters, if provided, will be returned in -'waitsendpay' and 'listsendpays' results. - -The 'msatoshi' amount, if provided, is the amount that will be -recorded as the target payment value. -If not specified, it will be the final amount to the destination. -If specified, then the final amount at the destination must be -from the specified 'msatoshi' to twice the specified 'msatoshi', -inclusive. -This is intended to obscure payments by overpaying slightly at -the destination; -the actual target payment is what should be specified as the -'msatoshi' argument. 'msatoshi' is in millisatoshi precision; it can -be a whole number, or a whole number ending in 'msat' or 'sat', or a -number with three decimal places ending in 'sat', or a number with 1 -to 11 decimal places ending in 'btc'. - -Once a payment has succeeded, calls to *sendpay* with the same 'payment_hash' -but a different 'msatoshi' or destination will fail; this prevents -accidental multiple payments. -Calls to *sendpay* with the same 'payment_hash', 'msatoshi', and destination as a -previous successful payment (even if a different route) will return -immediately with success. - -RETURN VALUE ------------- - -On success, an object similar to the output of *listsendpays* will -be returned. -This object will have a 'status' field that is typically the -string '"pending"', but may be '"complete"' if the payment was -already performed successfully. - -On error, if the error occurred from a node other than the final -destination, the route table will be updated so that lightning-getroute(7) -should return an alternate route (if any). An error from the final -destination implies the payment should not be retried. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 201. Already paid with this 'hash' using different amount or - destination. -* 202. Unparseable onion reply. The 'data' field of the error - will have an 'onionreply' field, a hex string representation - of the raw onion reply. -* 203. Permanent failure at destination. The 'data' field of - the error will be routing failure object. -* 204. Failure along route; retry a different route. The 'data' - field of the error will be routing failure object. - -A routing failure object has the fields below: - -* 'erring_index'. The index of the node along the route that - reported the error. 0 for the local node, 1 for the first - hop, and so on. -* 'erring_node'. The hex string of the pubkey id of the node - that reported the error. -* 'erring_channel'. The short channel ID of the channel that - has the error, or '0:0:0' if the destination node raised - the error. -* 'failcode'. The failure code, as per BOLT #4. -* 'channel_update'. The hex string of the 'channel_update' - message received from the remote node. Only present if - error is from the remote node and the 'failcode' has the - UPDATE bit set, as per BOLT #4. - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-listinvoice(7), lightning-delinvoice(7), -lightning-getroute(7), lightning-invoice(7), -lightning-pay(7), lightning-waitsendpay(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-setchannelfee.7.md b/doc/lightning-setchannelfee.7.md new file mode 100644 index 000000000..cd00fdd9a --- /dev/null +++ b/doc/lightning-setchannelfee.7.md @@ -0,0 +1,72 @@ +LIGHTNING-SETCHANNELFEE(7) Manual Page +====================================== +lightning-setchannelfee - Command for setting specific routing fees on a +lightning channel. + +SYNOPSIS +-------- + +**setchannelfee** *id* \[*base*\] \[*ppm*\] + +DESCRIPTION +----------- + +The **setchannelfee** RPC command sets channel specific routing fees as +defined in BOLT \#7. The channel has to be in normal or awaiting state. +This can be checked by **listpeers** reporting a *state* of +CHANNELD\_NORMAL or CHANNELD\_AWAITING\_LOCKIN for the channel. + +*id* is required and should contain a scid (short channel ID), channel +id or peerid (pubkey) of the channel to be modified. If *id* is set to +"all", the fees for all channels are updated that are in state +CHANNELD\_NORMAL or CHANNELD\_AWAITING\_LOCKIN. + +*base* is an optional value in millisatoshi that is added as base fee to +any routed payment. If the parameter is left out, the global config +value fee-base will be used again. It can be a whole number, or a whole +number ending in *msat* or *sat*, or a number with three decimal places +ending in *sat*, or a number with 1 to 11 decimal places ending in +*btc*. + +*ppm* is an optional value that is added proportionally per-millionths +to any routed payment volume in satoshi. For example, if ppm is 1,000 +and 1,000,000 satoshi is being routed trhough the channel, an +proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee. If +the parameter is left out, the global config value will be used again. + +RETURN VALUE +------------ + +On success, an object with the new values *base* and *ppm* along with an +array *channels* which contains objects with fields *peer\_id*, +*channel\_id* and *short\_channel\_id*. + +ERRORS +------ + +The following error codes may occur: +- -1: Channel is in incorrect state, i.e. Catchall nonspecific error. +- -32602: JSONRPC2\_INVALID\_PARAMS, i.e. Given id is not a channel ID +or short channel ID. + +AUTHOR +------ + +Michael Schmoock <> is the author of this +feature. Rusty Russell <> is mainly +responsible for the c-lightning project. + +SEE ALSO +-------- + +lightningd-config(5), lightning-fundchannel(7), +lightning-listchannels(7), lightning-listpeers(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-30 17:34:18 CEST diff --git a/doc/lightning-setchannelfee.7.txt b/doc/lightning-setchannelfee.7.txt deleted file mode 100644 index 51248b6ae..000000000 --- a/doc/lightning-setchannelfee.7.txt +++ /dev/null @@ -1,61 +0,0 @@ -LIGHTNING-SETCHANNELFEE(7) -======================== -:doctype: manpage - -NAME ----- -lightning-setchannelfee - Command for setting specific routing fees on a lightning channel. - -SYNOPSIS --------- -*setchannelfee* 'id' ['base'] ['ppm'] - -DESCRIPTION ------------ -The *setchannelfee* RPC command sets channel specific routing fees as -defined in BOLT #7. The channel has to be in normal or awaiting state. -This can be checked by *listpeers* reporting a 'state' of CHANNELD_NORMAL -or CHANNELD_AWAITING_LOCKIN for the channel. - -'id' is required and should contain a scid (short channel ID), channel id -or peerid (pubkey) of the channel to be modified. If 'id' is set to "all", -the fees for all channels are updated that are in state CHANNELD_NORMAL or -CHANNELD_AWAITING_LOCKIN. - -'base' is an optional value in millisatoshi that is added as base fee to -any routed payment. If the parameter is left out, the global config -value fee-base will be used again. It can be a whole number, or a whole number ending in 'msat' or -'sat', or a number with three decimal places ending in 'sat', or a number -with 1 to 11 decimal places ending in 'btc'. - -'ppm' is an optional value that is added proportionally per-millionths to -any routed payment volume in satoshi. For example, if ppm is 1,000 and -1,000,000 satoshi is being routed trhough the channel, an proportional -fee of 1,000 satoshi is added, resulting in a 0.1% fee. If the parameter -is left out, the global config value will be used again. - -RETURN VALUE ------------- -On success, an object with the new values 'base' and 'ppm' along with an array -'channels' which contains objects with fields 'peer_id', 'channel_id' and -'short_channel_id'. - -ERRORS ------- -The following error codes may occur: - -* -1. Channel is in incorrect state, i.e. Catchall nonspecific error. -* -32602. JSONRPC2_INVALID_PARAMS, i.e. Given id is not a channel ID or short channel ID. - -AUTHOR ------- -Michael Schmoock is the author of this feature. -Rusty Russell is mainly responsible for the c-lightning project. - -SEE ALSO --------- -lightningd-config(5), lightning-fundchannel(7), lightning-listchannels(7), lightning-listpeers(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-txdiscard.7.md b/doc/lightning-txdiscard.7.md new file mode 100644 index 000000000..278c6d82f --- /dev/null +++ b/doc/lightning-txdiscard.7.md @@ -0,0 +1,48 @@ +LIGHTNING-TXDISCARD(7) Manual Page +================================== +lightning-txdiscard - Abandon a transaction from txprepare, release +inputs + +SYNOPSIS +-------- + +**txdiscard** *txid* + +DESCRIPTION +----------- + +The **txdiscard** RPC command releases inputs which were reserved for +use of the *txid* from lightning-txprepare(7). + +RETURN VALUE +------------ + +On success, an object with attributes *unsigned\_tx* and *txid* will be +returned, exactly as from lightning-txprepare(7). + +If there is no matching *txid*, an error is reported. Note that this may +happen due to incorrect usage (such as **txdiscard** or **txsend** +already being called for *txid*) or due to lightningd restarting, which +implicitly calls **txdiscard** on all outputs. + +The following error codes may occur: +- -1: An unknown *txid*. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-txprepare(7), lightning-txsend(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-08 16:03:59 CEST diff --git a/doc/lightning-txdiscard.7.txt b/doc/lightning-txdiscard.7.txt deleted file mode 100644 index 5dc3933d9..000000000 --- a/doc/lightning-txdiscard.7.txt +++ /dev/null @@ -1,42 +0,0 @@ -LIGHTNING-TXDISCARD(7) -====================== -:doctype: manpage - -NAME ----- -lightning-txdiscard - Abandon a transaction from txprepare, release inputs - -SYNOPSIS --------- -*txdiscard* 'txid' - -DESCRIPTION ------------ -The *txdiscard* RPC command releases inputs which were reserved for use -of the 'txid' from lightning-txprepare(7). - -RETURN VALUE ------------- -On success, an object with attributes 'unsigned_tx' and 'txid' will be -returned, exactly as from lightning-txprepare(7). - -If there is no matching 'txid', an error is reported. Note that this -may happen due to incorrect usage (such as *txdiscard* or *txsend* -already being called for 'txid') or due to lightningd restarting, which -implicitly calls *txdiscard* on all outputs. - -The following error codes may occur: - -* -1. An unknown 'txid'. - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-txprepare(7), lightning-txsend(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-txprepare.7.md b/doc/lightning-txprepare.7.md new file mode 100644 index 000000000..9c34d4c33 --- /dev/null +++ b/doc/lightning-txprepare.7.md @@ -0,0 +1,57 @@ +LIGHTNING-TXPREPARE(7) Manual Page +================================== +lightning-txprepare - Command to prepare to withdraw funds from the +internal wallet. + +SYNOPSIS +-------- + +**txprepare** *destination* *satoshi* \[*feerate*\] \[*minconf*\] + +DESCRIPTION +----------- + +The **txprepare** RPC command creates an unsigned transaction which +spends funds from c-lightning’s internal wallet to the address specified +in *destination*. + +Effectively, it is the first part of a **withdraw** command, and uses +the same parameters. The second part is provided by **txsend**. + +RETURN VALUE +------------ + +On success, an object with attributes *unsigned\_tx* and *txid* will be +returned. You need to hand *txid* to **txsend** or **txdiscard**, as the +inputs of this transaction are reserved until then, or until the daemon +restarts. + +*unsigned\_tx* represents the raw bitcoin transaction (not yet signed) +and *txid* represent the bitcoin transaction id. + +On failure, an error is reported and the transaction is not created. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 301: There are not enough funds in the internal wallet (including +fees) to create the transaction. +- 302: The dust limit is not met. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-08 16:03:59 CEST diff --git a/doc/lightning-txprepare.7.txt b/doc/lightning-txprepare.7.txt deleted file mode 100644 index 25408f22e..000000000 --- a/doc/lightning-txprepare.7.txt +++ /dev/null @@ -1,52 +0,0 @@ -LIGHTNING-TXPREPARE(7) -===================== -:doctype: manpage - -NAME ----- -lightning-txprepare - Command to prepare to withdraw funds from the -internal wallet. - -SYNOPSIS --------- -*txprepare* 'destination' 'satoshi' ['feerate'] ['minconf'] - -DESCRIPTION ------------ -The *txprepare* RPC command creates an unsigned transaction which -spends funds from c-lightning's internal wallet to the address -specified in 'destination'. - -Effectively, it is the first part of a *withdraw* command, and uses -the same parameters. The second part is provided by *txsend*. - -RETURN VALUE ------------- -On success, an object with attributes 'unsigned_tx' and 'txid' will be -returned. You need to hand 'txid' to *txsend* or *txdiscard*, as the -inputs of this transaction are reserved until then, or until the -daemon restarts. - -'unsigned_tx' represents the raw bitcoin transaction (not yet signed) -and 'txid' represent the bitcoin transaction id. - -On failure, an error is reported and the transaction is not created. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 301. There are not enough funds in the internal wallet (including fees) to - create the transaction. -* 302. The dust limit is not met. - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-txsend.7.md b/doc/lightning-txsend.7.md new file mode 100644 index 000000000..be672a7a3 --- /dev/null +++ b/doc/lightning-txsend.7.md @@ -0,0 +1,47 @@ +LIGHTNING-TXSEND(7) Manual Page +=============================== +lightning-txsend - Command to sign and send transaction from txprepare + +SYNOPSIS +-------- + +**txsend** *txid* + +DESCRIPTION +----------- + +The **txsend** RPC command signs and broadcasts a transaction created by +**txprepare**. + +RETURN VALUE +------------ + +On success, an object with attributes *tx* and *txid* will be returned. + +*tx* represents the fully signed raw bitcoin transaction, and *txid* is +the same as the *txid* argument. + +On failure, an error is reported (from bitcoind), and the inputs from +the transaction are unreserved. + +The following error codes may occur: +- -1: Catchall nonspecific error. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-txprepare(7), lightning-txdiscard(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-08 16:03:59 CEST diff --git a/doc/lightning-txsend.7.txt b/doc/lightning-txsend.7.txt deleted file mode 100644 index d21ca14e0..000000000 --- a/doc/lightning-txsend.7.txt +++ /dev/null @@ -1,43 +0,0 @@ -LIGHTNING-TXSEND(7) -=================== -:doctype: manpage - -NAME ----- -lightning-txsend - Command to sign and send transaction from txprepare - -SYNOPSIS --------- -*txsend* 'txid' - -DESCRIPTION ------------ -The *txsend* RPC command signs and broadcasts a transaction created by -*txprepare*. - -RETURN VALUE ------------- -On success, an object with attributes 'tx' and 'txid' will be -returned. - -'tx' represents the fully signed raw bitcoin transaction, and 'txid' -is the same as the 'txid' argument. - -On failure, an error is reported (from bitcoind), and the inputs from -the transaction are unreserved. - -The following error codes may occur: - -* -1. Catchall nonspecific error. - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-txprepare(7), lightning-txdiscard(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-waitanyinvoice.7.md b/doc/lightning-waitanyinvoice.7.md new file mode 100644 index 000000000..defe13b0e --- /dev/null +++ b/doc/lightning-waitanyinvoice.7.md @@ -0,0 +1,50 @@ +LIGHTNING-WAITANYINVOICE(7) Manual Page +======================================= +lightning-waitanyinvoice - Command for waiting for payments. + +SYNOPSIS +-------- + +**waitanyinvoice** \[*lastpay\_index*\] + +DESCRIPTION +----------- + +The **waitanyinvoice** RPC command waits until an invoice is paid, then +returns a single entry as per **listinvoice**. It will not return for +any invoices paid prior to or including the *lastpay\_index*. + +This is usually called iteratively: once with no arguments, then +repeatedly with the returned *pay\_index* entry. This ensures that no +paid invoice is missed. + +The *pay\_index* is a monotonically-increasing number assigned to an +invoice when it gets paid. The first valid *pay\_index* is 1; specifying +*lastpay\_index* of 0 equivalent to not specifying a *lastpay\_index*. +Negative *lastpay\_index* is invalid. + +RETURN VALUE +------------ + +On success, an invoice description will be returned as per +lightning-listinvoice(7): *complete* will always be *true*. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-waitinvoice(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-07 14:23:17 CEST diff --git a/doc/lightning-waitanyinvoice.7.txt b/doc/lightning-waitanyinvoice.7.txt deleted file mode 100644 index 4f9945fc5..000000000 --- a/doc/lightning-waitanyinvoice.7.txt +++ /dev/null @@ -1,45 +0,0 @@ -LIGHTNING-WAITANYINVOICE(7) -=========================== -:doctype: manpage - -NAME ----- -lightning-waitanyinvoice - Command for waiting for payments. - -SYNOPSIS --------- -*waitanyinvoice* ['lastpay_index'] - -DESCRIPTION ------------ -The *waitanyinvoice* RPC command waits until an invoice is paid, then -returns a single entry as per *listinvoice*. It will not return for -any invoices paid prior to or including the 'lastpay_index'. - -This is usually called iteratively: once with no arguments, then -repeatedly with the returned 'pay_index' entry. This ensures that no paid -invoice is missed. - -The 'pay_index' is a monotonically-increasing number assigned to an -invoice when it gets paid. The first valid 'pay_index' is 1; specifying -'lastpay_index' of 0 equivalent to not specifying a 'lastpay_index'. -Negative 'lastpay_index' is invalid. - - -RETURN VALUE ------------- -On success, an invoice description will be returned as per lightning-listinvoice(7): 'complete' will always be 'true'. - -//FIXME:Enumerate errors - -AUTHOR ------- -Rusty Russell is mainly responsible. - -SEE ALSO --------- -lightning-waitinvoice(7), lightning-listinvoice(7), lightning-delinvoice(7), lightning-invoice(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-waitinvoice.7.md b/doc/lightning-waitinvoice.7.md new file mode 100644 index 000000000..43543f049 --- /dev/null +++ b/doc/lightning-waitinvoice.7.md @@ -0,0 +1,48 @@ +LIGHTNING-WAITINVOICE(7) Manual Page +==================================== +lightning-waitinvoice - Command for waiting for specific payment. + +SYNOPSIS +-------- + +**waitinvoice** *label* + +DESCRIPTION +----------- + +The **waitinvoice** RPC command waits until a specific invoice is paid, +then returns that single entry as per **listinvoice**. + +RETURN VALUE +------------ + +On success, an invoice description will be returned as per +lightning-listinvoice(7). The *status* field will be *paid*. + +If the invoice is deleted while unpaid, or the invoice does not exist, +this command will return with an error with code -1. + +If the invoice expires before being paid, or is already expired, this +command will return with an error with code -2, with the data being the +invoice data as per **listinvoice**. + +AUTHOR +------ + +Christian Decker <> is mainly +responsible. + +SEE ALSO +-------- + +lightning-waitanyinvoice(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-invoice(7) + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-04-07 14:23:17 CEST diff --git a/doc/lightning-waitinvoice.7.txt b/doc/lightning-waitinvoice.7.txt deleted file mode 100644 index f3238701b..000000000 --- a/doc/lightning-waitinvoice.7.txt +++ /dev/null @@ -1,40 +0,0 @@ -LIGHTNING-WAITINVOICE(7) -======================== -:doctype: manpage - -NAME ----- -lightning-waitinvoice - Command for waiting for specific payment. - -SYNOPSIS --------- -*waitinvoice* 'label' - -DESCRIPTION ------------ -The *waitinvoice* RPC command waits until a specific invoice is paid, -then returns that single entry as per *listinvoice*. - -RETURN VALUE ------------- -On success, an invoice description will be returned as per lightning-listinvoice(7). -The 'status' field will be 'paid'. - -If the invoice is deleted while unpaid, or the invoice does not exist, -this command will return with an error with code -1. - -If the invoice expires before being paid, or is already expired, this -command will return with an error with code -2, with the data being -the invoice data as per *listinvoice*. - -AUTHOR ------- -Christian Decker is mainly responsible. - -SEE ALSO --------- -lightning-waitanyinvoice(7), lightning-listinvoice(7), lightning-delinvoice(7), lightning-invoice(7) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-waitsendpay.7.md b/doc/lightning-waitsendpay.7.md new file mode 100644 index 000000000..1c698e31e --- /dev/null +++ b/doc/lightning-waitsendpay.7.md @@ -0,0 +1,89 @@ +LIGHTNING-WAITSENDPAY(7) Manual Page +==================================== +lightning-waitsendpay - Command for sending a payment via a route. + +SYNOPSIS +-------- + +**waitsendpay** *payment\_hash* \[*timeout*\] + +DESCRIPTION +----------- + +The **waitsendpay** RPC command polls or waits for the status of an +outgoing payment that was initiated by a previous **sendpay** +invocation. + +Optionally the client may provide a *timeout*, an integer in seconds, +for this RPC command to return. If the *timeout* is provided and the +given amount of time passes without the payment definitely succeeding or +definitely failing, this command returns with a 200 error code (payment +still in progress). If *timeout* is not provided this call will wait +indefinitely. + +Indicating a *timeout* of 0 effectively makes this call a pollable query +of the status of the payment. + +If the payment completed with success, this command returns with +success. Otherwise, if the payment completed with failure, this command +returns an error. + +RETURN VALUE +------------ + +On success, an object similar to the output of **listsendpays** will be +returned. This object will have a *status* field that is the string +*"complete"*. + +On error, and even if the error occurred from a node other than the +final destination, the route table will no longer be updated. Use the +*exclude* parameter of the `getroute` command to ignore the failing +route. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 200: Timed out before the payment could complete. +- 202: Unparseable onion reply. The *data* field of the error will + have an *onionreply* field, a hex string representation of the raw + onion reply. +- 203: Permanent failure at destination. The *data* field of the error + will be routing failure object. +- 204: Failure along route; retry a different route. The *data* field + of the error will be routing failure object. +- 208: A payment for *payment\_hash* was never made and there is + nothing to wait for. +- 209: The payment already failed, but the reason for failure was not + stored. This should only occur when querying failed payments on very + old databases. + +A routing failure object has the fields below: +- *erring\_index*: The index of the node along the route that reported + the error. 0 for the local node, 1 for the first hop, and so on. +- *erring\_node*: The hex string of the pubkey id of the node that + reported the error. +- *erring\_channel*: The short channel ID of the channel that has the + error (or the final channel if the destination raised the error). +- *erring\_direction*: The direction of traversing the + *erring\_channel*: +- *failcode*: The failure code, as per BOLT \#4. +- *failcodename*: The human-readable name corresponding to *failcode*, + if known. + +AUTHOR +------ + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +-------- + +lightning-sendpay(7), lightning-pay(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-05-22 16:46:09 CEST diff --git a/doc/lightning-waitsendpay.7.txt b/doc/lightning-waitsendpay.7.txt deleted file mode 100644 index 69c28872a..000000000 --- a/doc/lightning-waitsendpay.7.txt +++ /dev/null @@ -1,89 +0,0 @@ -LIGHTNING-WAITSENDPAY(7) -======================== -:doctype: manpage - -NAME ----- -lightning-waitsendpay - Command for sending a payment via a route. - -SYNOPSIS --------- -*waitsendpay* 'payment_hash' ['timeout'] - -DESCRIPTION ------------ - -The *waitsendpay* RPC command polls or waits for the status of -an outgoing payment that was initiated by a previous *sendpay* -invocation. - -Optionally the client may provide a 'timeout', an integer in -seconds, for this RPC command to return. -If the 'timeout' is provided and the given amount of time -passes without the payment definitely succeeding or definitely -failing, this command returns with a 200 error code (payment -still in progress). -If 'timeout' is not provided this call will wait indefinitely. - -Indicating a 'timeout' of 0 effectively makes this call a -pollable query of the status of the payment. - -If the payment completed with success, this command returns -with success. -Otherwise, if the payment completed with failure, this command -returns an error. - -RETURN VALUE ------------- - -On success, an object similar to the output of *listsendpays* will -be returned. -This object will have a 'status' field that is the -string '"complete"'. - -On error, and even if the error occurred from a node other than the -final destination, the route table will no longer be updated. Use -the 'exclude' parameter of the `getroute` command to ignore the -failing route. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 200. Timed out before the payment could complete. -* 202. Unparseable onion reply. The 'data' field of the error - will have an 'onionreply' field, a hex string representation - of the raw onion reply. -* 203. Permanent failure at destination. The 'data' field of - the error will be routing failure object. -* 204. Failure along route; retry a different route. The 'data' - field of the error will be routing failure object. -* 208. A payment for 'payment_hash' was never made and there is - nothing to wait for. -* 209. The payment already failed, but the reason for failure - was not stored. This should only occur when querying failed - payments on very old databases. - -A routing failure object has the fields below: - -* 'erring_index'. The index of the node along the route that - reported the error. 0 for the local node, 1 for the first - hop, and so on. -* 'erring_node'. The hex string of the pubkey id of the node - that reported the error. -* 'erring_channel'. The short channel ID of the channel that - has the error (or the final channel if the destination raised the error). -* 'erring_direction'. The direction of traversing the 'erring_channel'. -* 'failcode'. The failure code, as per BOLT #4. -* 'failcodename'. The human-readable name corresponding to 'failcode', if known. - -AUTHOR ------- -ZmnSCPxj is mainly responsible. - -SEE ALSO --------- -lightning-sendpay(7), lightning-pay(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-withdraw.7.md b/doc/lightning-withdraw.7.md new file mode 100644 index 000000000..c606afe87 --- /dev/null +++ b/doc/lightning-withdraw.7.md @@ -0,0 +1,74 @@ +LIGHTNING-WITHDRAW(7) Manual Page +================================= +lightning-withdraw - Command for withdrawing funds from the internal +wallet. + +SYNOPSIS +-------- + +**withdraw** *destination* *satoshi* \[*feerate*\] \[*minconf*\] + +DESCRIPTION +----------- + +The **withdraw** RPC command sends funds from c-lightning’s internal +wallet to the address specified in *destination*. + +The address can be of any Bitcoin accepted type, including bech32. + +*satoshi* is the amount to be withdrawn from the internal wallet +(expressed, as name suggests, in satoshi). The string *all* can be used +to specify withdrawal of all available funds. Otherwise, it is in +satoshi precision; it can be a whole number, a whole number ending in +*sat*, a whole number ending in *000msat*, or a number with 1 to 8 +decimal places ending in *btc*. + +*feerate* is an optional feerate to use. It can be one of the strings +*urgent* (aim for next block), *normal* (next 4 blocks or so) or *slow* +(next 100 blocks or so) to use lightningd’s internal estimates: *normal* +is the default. + +Otherwise, *feerate* is a number, with an optional suffix: *perkw* means +the number is interpreted as satoshi-per-kilosipa (weight), and *perkb* +means it is interpreted bitcoind-style as satoshi-per-kilobyte. Omitting +the suffix is equivalent to *perkb*. + +*minconf* specifies the minimum number of confirmations that used +outputs should have. Default is 1. + +RETURN VALUE +------------ + +On success, an object with attributes *tx* and *txid* will be returned. + +*tx* represents the raw bitcoin, fully signed, transaction and *txid* +represent the bitcoin transaction id. + +On failure, an error is reported and the withdrawal transaction is not +created. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 301: There are not enough funds in the internal wallet (including +fees) to create the transaction. +- 302: The dust limit is not met. + +AUTHOR +------ + +Felix <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listfunds(7), lightning-fundchannel(7), lightning-newaddr(7), +lightning-txprepare(7). + +RESOURCES +--------- + +Main web site: + +------------------------------------------------------------------------ + +Last updated 2019-06-08 16:03:59 CEST diff --git a/doc/lightning-withdraw.7.txt b/doc/lightning-withdraw.7.txt deleted file mode 100644 index 6898508c0..000000000 --- a/doc/lightning-withdraw.7.txt +++ /dev/null @@ -1,66 +0,0 @@ -LIGHTNING-WITHDRAW(7) -==================== -:doctype: manpage - -NAME ----- -lightning-withdraw - Command for withdrawing funds from the -internal wallet. - -SYNOPSIS --------- -*withdraw* 'destination' 'satoshi' ['feerate'] ['minconf'] - -DESCRIPTION ------------ -The *withdraw* RPC command sends funds from c-lightning's -internal wallet to the address specified in 'destination'. - -The address can be of any Bitcoin accepted type, -including bech32. - -'satoshi' is the amount to be withdrawn from the internal -wallet (expressed, as name suggests, in satoshi). -The string 'all' can be used to specify withdrawal of all -available funds. Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in 'sat', a whole number ending in '000msat', or a number with 1 to 8 decimal places ending in 'btc'. - -'feerate' is an optional feerate to use. It can be one of the strings -'urgent' (aim for next block), 'normal' (next 4 blocks or so) or 'slow' (next -100 blocks or so) to use lightningd's internal estimates: -'normal' is the default. - -Otherwise, 'feerate' is a number, with an optional suffix: -'perkw' means the number is interpreted as satoshi-per-kilosipa -(weight), and 'perkb' means it is interpreted bitcoind-style as -satoshi-per-kilobyte. Omitting the suffix is equivalent to 'perkb'. - -'minconf' specifies the minimum number of confirmations that used outputs should have. Default is 1. - -RETURN VALUE ------------- -On success, an object with attributes 'tx' and 'txid' will -be returned. - -'tx' represents the raw bitcoin, fully signed, transaction -and 'txid' represent the bitcoin transaction id. - -On failure, an error is reported and the withdrawal transaction is not created. - -The following error codes may occur: - -* -1. Catchall nonspecific error. -* 301. There are not enough funds in the internal wallet (including fees) to - create the transaction. -* 302. The dust limit is not met. - -AUTHOR ------- -Felix is mainly responsible. - -SEE ALSO --------- -lightning-listfunds(7), lightning-fundchannel(7), lightning-newaddr(7), lightning-txprepare(7). - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md new file mode 100644 index 000000000..a60dd3fb0 --- /dev/null +++ b/doc/lightningd-config.5.md @@ -0,0 +1,376 @@ +LIGHTNINGD-CONFIG(5) Manual Page +================================ +lightningd-config - Lightning daemon configuration file + +SYNOPSIS +-------- + +**~/.lightning/config** + +DESCRIPTION +----------- + +When lightningd(8) starts up, it reads a configuration file. By default +that is *config* in the **.lightning** subdirectory of the home +directory (if it exists), but that can be changed by the +*--lightning-dir* or *--conf* options on the lightningd(8) command line. + +Configuration file options are processed first, then command line +options: later options override earlier ones except *addr* options which +accumulate. + +All these options are mirrored as commandline arguments to +lightningd(8), so *--foo* becomes simply *foo* in the configuration +file, and *--foo=bar* becomes *foo=bar* in the configuration file. + +Blank lines and lines beginning with *\#* are ignored. + +DEBUGGING +--------- + +*--help* will show you the defaults for many options; they vary with +network settings so you can specify *--network* before *--help* to see +the defaults for that network. + +The lightning-listconfigs(7) command will output a valid configuration +file using the current settings. + +OPTIONS +------- + +### General options + + **allow-deprecated-apis**=*BOOL* +Enable deprecated options, JSONRPC commands, fields, etc. It defaults to +*true*, but you should set it to *false* when testing to ensure that an +upgrade won’t break your configuration. + + **help** +Print help and exit. Not very useful inside a configuration file, but +fun to put in other’s config files while their computer is unattended. + + **version** +Print version and exit. Also useless inside a configuration file, but +putting this in someone’s config file may convince them to read this man +page. + +Bitcoin control options: + + **network**=*NETWORK* +Select the network parameters (*bitcoin*, *testnet*, or *regtest*). + + **testnet** +Alias for *network=testnet*. + + **signet** +Alias for *network=signet*. + + **mainnet** +Alias for *network=bitcoin*. + + **bitcoin-cli**=*PATH* +The name of *bitcoin-cli* executable to run. + + **bitcoin-datadir**=*DIR* +*-datadir* argument to supply to bitcoin-cli(1). + + **bitcoin-rpcuser**=*USER* +The RPC username for talking to bitcoind(1). + + **bitcoin-rpcpassword**=*PASSWORD* +The RPC password for talking to bitcoind(1). + + **bitcoin-rpcconnect**=*HOST* +The bitcoind(1) RPC host to connect to. + + **bitcoin-rpcport**=*PORT* +The bitcoind(1) RPC port to connect to. + + **bitcoin-retry-timeout**=*SECONDS* +Number of seconds to keep trying a bitcoin-cli(1) command. If the +command keeps failing after this time, exit with a fatal error. + + **rescan**=*BLOCKS* +Number of blocks to rescan from the current head, or absolute +blockheight if negative. This is only needed if something goes badly +wrong. + +### Lightning daemon options + + **lightning-dir**=*DIR* +Sets the working directory. All files (except *--conf* and +*--lightning-dir* on the command line) are relative to this. + + **pid-file**=*PATH* +Specify pid file to write to. + + **log-level**=*LEVEL* +What log level to print out: options are io, debug, info, unusual, +broken. + + **log-prefix**=*PREFIX* +Prefix for log lines: this can be customized if you want to merge logs +with multiple daemons. + + **log-file**=*PATH* +Log to this file instead of stdout. Sending lightningd(8) SIGHUP will +cause it to reopen this file (useful for log rotation). + + **rpc-file**=*PATH* +Set JSON-RPC socket (or /dev/tty), such as for lightning-cli(1). + + **daemon** +Run in the background, suppress stdout and stderr. + + **conf**=*PATH* +Sets configuration file (default: **lightning-dir**/*config* ). If this +is a relative path, it is relative to the starting directory, not +**lightning-dir** (unlike other paths). *PATH* must exist and be +readable (we allow missing files in the default case). Using this inside +a configuration file is meaningless. + +### Lightning node customization options + + **alias**=*RRGGBB* + **rgb**=*RRGGBB* +Your favorite color as a hex code. + +Up to 32 UTF-8 characters to tag your node. Completely silly, since +anyone can call their node anything they want. The default is an +NSA-style codename derived from your public key, but "Peter Todd" and +"VAULTERO" are good options, too. + + **fee-base**=*MILLISATOSHI* +Default: 1000. The base fee to charge for every payment which passes +through. Note that millisatoshis are a very, very small unit! Changing +this value will only affect new channels and not existing ones. If you +want to change fees for existing channels, use the RPC call +lightning-setchannelfee(7). + + **fee-per-satoshi**=*MILLIONTHS* +Default: 10 (0.001%). This is the proportional fee to charge for every +payment which passes through. As percentages are too coarse, it’s in +millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only +affect new channels and not existing ones. If you want to change fees +for existing channels, use the RPC call lightning-setchannelfee(7). + + **min-capacity-sat**=*SATOSHI* +Default: 10000. This value defines the minimal effective channel +capacity in satoshi to accept for channel opening requests. If a peer +tries to open a channel smaller than this, the opening will be rejected. + + **ignore-fee-limits**=*BOOL* +Allow nodes which establish channels to us to set any fee they want. +This may result in a channel which cannot be closed, should fees +increase, but make channels far more reliable since we never close it +due to unreasonable fees. + + **commit-time**='MILLISECONDS +How long to wait before sending commitment messages to the peer: in +theory increasing this would reduce load, but your node would have to be +extremely busy node for you to even notice. + +### Lightning channel and HTLC options + + **watchtime-blocks**=*BLOCKS* +How long we need to spot an outdated close attempt: on opening a channel +we tell our peer that this is how long they’ll have to wait if they +perform a unilateral close. + + **max-locktime-blocks**=*BLOCKS* +The longest our funds can be delayed (ie. the longest +**watchtime-blocks** our peer can ask for, and also the longest HTLC +timeout we will accept). If our peer asks for longer, we’ll refuse to +create a channel, and if an HTLC asks for longer, we’ll refuse it. + + **funding-confirms**=*BLOCKS* +Confirmations required for the funding transaction when the other side +opens a channel before the channel is usable. + + **commit-fee**=*PERCENT* +The percentage of *estimatesmartfee 2* to use for the bitcoin +transaction which funds a channel: can be greater than 100. + + **commit-fee-min**=*PERCENT* + **commit-fee-max**=*PERCENT* +Limits on what onchain fee range we’ll allow when a node opens a channel +with us, as a percentage of *estimatesmartfee 2*. If they’re outside +this range, we abort their opening attempt. Note that **commit-fee-max** +can (should!) be greater than 100. + + **max-concurrent-htlcs**=*INTEGER* +Number of HTLCs one channel can handle concurrently in each direction. +Should be between 1 and 483 (default 30). + + **cltv-delta**=*BLOCKS* +The number of blocks between incoming payments and outgoing payments: +this needs to be enough to make sure that if we have to, we can close +the outgoing payment before the incoming, or redeem the incoming once +the outgoing is redeemed. + + **cltv-final**=*BLOCKS* +The number of blocks to allow for payments we receive: if we have to, we +might need to redeem this on-chain, so this is the number of blocks we +have to do that. + +Invoice control options: + + **autocleaninvoice-cycle**=*SECONDS* +Perform cleanup of expired invoices every *SECONDS* seconds, or disable +if 0. Usually unpaid expired invoices are uninteresting, and just take +up space in the database. + + **autocleaninvoice-expired-by**=*SECONDS* +Control how long invoices must have been expired before they are cleaned +(if *autocleaninvoice-cycle* is non-zero). + +### Networking options + +Note that for simple setups, the implicit *autolisten* option does the +right thing: it will try to bind to port 9735 on IPv4 and IPv6, and will +announce it to peers if it seems like a public address. + +You can instead use *addr* to override this (eg. to change the port), or +precisely control where to bind and what to announce with the +*bind-addr* and *announce-addr* options. These will **disable** the +*autolisten* logic, so you must specifiy exactly what you want! + + **addr**=*\[IPADDRESS\[:PORT\]\]|autotor:TORIPADDRESS\[:TORPORT\]* +Set an IP address (v4 or v6) or automatic Tor address to listen on and +(maybe) announce as our node address. + + An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or + IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 + interfaces, '::' means 'bind to all IPv6 interfaces'. If 'PORT' is + not specified, 9735 is used. If we can determine a public IP + address from the resulting binding, and no other addresses of the + same type are already announced, the address is announced. + + If the argument begins with 'autotor:' then it is followed by the + IPv4 or IPv6 address of the Tor control port (default port 9051), + and this will be used to configure a Tor hidden service for port + 9735. The Tor hidden service will be configured to point to the + first IPv4 or IPv6 address we bind to. + + This option can be used multiple times to add more addresses, and + its use disables autolisten. If necessary, and 'always-use-proxy' + is not specified, a DNS lookup may be done to resolve 'IPADDRESS' + or 'TORIPADDRESS'. + + **bind-addr**=*\[IPADDRESS\[:PORT\]\]|SOCKETPATH* +Set an IP address or UNIX domain socket to listen to, but do not +announce. A UNIX domain socket is distinguished from an IP address by +beginning with a */*. + + An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or + IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 + interfaces, '::' means 'bind to all IPv6 interfaces'. 'PORT' is + not specified, 9735 is used. + + This option can be used multiple times to add more addresses, and + its use disables autolisten. If necessary, and 'always-use-proxy' + is not specified, a DNS lookup may be done to resolve 'IPADDRESS'. + + **announce-addr**=*IPADDRESS\[:PORT\]|TORADDRESS.onion\[:PORT\]* +Set an IP (v4 or v6) address or Tor address to announce; a Tor address +is distinguished by ending in *.onion*. *PORT* defaults to 9735. + + Empty or wildcard IPv4 and IPv6 addresses don't make sense here. + Also, unlike the 'addr' option, there is no checking that your + announced addresses are public (e.g. not localhost). + + This option can be used multiple times to add more addresses, and + its use disables autolisten. The spec says you can't announce + more that one address of the same type (eg. two IPv4 or two IPv6 + addresses) so `lightningd` will refuse if you specify more than one. + + If necessary, and 'always-use-proxy' is not specified, a DNS + lookup may be done to resolve 'IPADDRESS'. + + **offline** +Do not bind to any ports, and do not try to reconnect to any peers. This +can be useful for maintenance and forensics, so is usually specified on +the command line. Overrides all *addr* and *bind-addr* options. + + **autolisten**=*BOOL* +By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if +no *addr*, *bind-addr* or *announce-addr* options are specified. Setting +this to *false* disables that. + + **proxy**=*IPADDRESS\[:PORT\]* +Set a socks proxy to use to connect to Tor nodes (or for all connections +if **always-use-proxy** is set). + + **always-use-proxy**=*BOOL* +Always use the **proxy**, even to connect to normal IP addresses (you +can still connect to Unix domain sockets manually). This also disables +all DNS lookups, to avoid leaking information. + + **disable-dns** +Disable the DNS bootstrapping mechanism to find a node by its node ID. + + **tor-service-password**=*PASSWORD* +Set a Tor control password, which may be needed for *autotor:* to +authenticate to the Tor control port. + +### Lightning Plugins + +lightningd(8) supports plugins, which offer additional configuration +options and JSON-RPC methods, depending on the plugin. Some are supplied +by default (usually located in **libexec/c-lightning/plugins/**). If a +**plugins** directory exists under *lightning-dir* that is searched for +plugins along with any immediate subdirectories). You can specify +additional paths too: + + **plugin**=*PATH* +Specify a plugin to run as part of c-lightning. This can be specified +multiple times to add multiple plugins. + + **plugin-dir**=*DIRECTORY* +Specify a directory to look for plugins; all executable files not +containing punctuation (other than *.*, *-* or *\_) in 'DIRECTORY* are +loaded. *DIRECTORY* must exist; this can be specified multiple times to +add multiple directories. + + **clear-plugins** +This option clears all *plugin* and *plugin-dir* options preceeding it, +including the default built-in plugin directory. You can still add +*plugin-dir* and *plugin* options following this and they will have the +normal effect. + + **disable-plugin**=*PLUGIN* +If *PLUGIN* contains a /, plugins with the same path as *PLUGIN* are +disabled. Otherwise, any plugin with that base name is disabled, +whatever directory it is in. + +BUGS +---- + +You should report bugs on our github issues page, and maybe submit a fix +to gain our eternal gratitude! + +AUTHOR +------ + +Rusty Russell <> wrote this man page, and +much of the configuration language, but many others did the hard work of +actually implementing these options. + +SEE ALSO +-------- + +lightning-listconfigs(7) lightning-setchannelfee(7) lightningd(8) + +RESOURCES +--------- + +Main web site: + +COPYING +------- + +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. + + +Last updated 2019-08-09 11:12:04 CEST diff --git a/doc/lightningd.8.md b/doc/lightningd.8.md new file mode 100644 index 000000000..b903073e7 --- /dev/null +++ b/doc/lightningd.8.md @@ -0,0 +1,177 @@ +LIGHTNINGD(8) Manual Page +========================= +lightningd - Daemon for running a Lightning Network node + +SYNOPSIS + +lightningd \[--conf=<config-file>\] \[*OPTIONS*\]… + +DESCRIPTION + +**lightningd** starts the C-Lightning daemon, which implements a +standards-compliant Lightning Network node. + +CONFIGURATION OPTIONS + + **--conf**=*FILE* +Specify configuration file. If not an absolute path, will be relative +from the lightning-dir location. Defaults to *config*. + + **--lightning-dir**=*DIR* +Set the directory for the C-Lightning daemon. Defaults to +*$HOME/.lightning*. + +MORE OPTIONS + +Command line options are mirrored as configuration options in the +configuration file, so *foo* in the configuration file simply becomes +*--foo* on the command line, and *foo=bar* becomes *--foo=bar*. + +See lightningd-config(5) for a comprehensive list of all available +options. + +LOGGING AND COMMANDING C-LIGHTNING + + By default, C-Lightning will log to the standard output. + To log to a specific file, use '--log-file=PATH'. + Sending SIGHUP will cause C-Lightning to reopen this file, + for example to do log rotation. + + C-Lightning will set up a Unix domain socket for receiving + commands. + By default this will be the file 'lightning-rpc' in your + specified 'lightning-dir'. + You can use lightning-cli(1) to send commands to C-Lightning + once 'lightningd' has started; you need to match the + '--lightning-dir' and '--rpc-file' options between them. + + Commands for C-Lightning are described in various manpages + in section 7, with the common prefix 'lightning-'. + + QUICK START + +First, decide on and create a directory for *lightning-dir*, or just use +the default *$HOME/.lightning*. Then create a *config* file in this +directory containing your configuration. + +Your other main preparation would be to set up a mainnet Bitcoin +fullnode, i.e. run a bitcoind(1) instance. The rest of this quick start +guide will assume you are reckless and want to spend real funds on +Lightning. Indicate *network=bitcoin* in your *config* file explicitly. + +C-Lightning needs to communicate with the Bitcoin Core RPC. You can set +this up using *bitcoin-datadir*, *bitcoin-rpcconnect*, +*bitcoin-rpcport*, *bitcoin-rpcuser*, and *bitcoin-rpcpassword* options +in your *config* file. + +Finally, just to keep yourself sane, decide on a log file name and +indicate it using *log-file=lightningd.log* in your *config* file. You +might be interested in viewing it periodically as you follow along on +this guide. + +Once the **bitcoind** instance is running, start lightningd(8): + + $ lightningd --lightning-dir=$HOME/.lightning --daemon + +This starts **lightningd** in the background due to the *--daemon* +option. + +Check if things are working: + + $ lightning-cli --lightning-dir=%HOME/.lightning help + $ lightning-cli --lightning-dir=%HOME/.lightning getinfo + +The **getinfo** command in particular will return a *blockheight* field, +which indicates the block height to which **lightningd** has been +synchronized to (this is separate from the block height that your +**bitcoind** has been synchronized to, and will always lag behind +**bitcoind**). You will have to wait until the *blockheight* has reached +the actual blockheight of the Bitcoin network. + +Before you can get funds offchain, you need to have some funds onchain +owned by **lightningd** (which has a separate wallet from the +**bitcoind** it connects to). Get an address for **lightningd** via +lightning-newaddr(7) command as below (*--lightning-dir* option has been +elided, specify it if you selected your own *lightning-dir*): + + $ lightning-cli newaddr + +This will provide a native SegWit bech32 address. In case all your money +is in services that do not support native SegWit and have to use +P2SH-wrapped addresses, instead use: + + $ lightning-cli newaddr p2sh-segwit + +Transfer a small amount of onchain funds to the given address. Check the +status of all your funds (onchain and on-Lightning) via +lightning-listfunds(7): + + $ lightning-cli listfunds + +Now you need to look for an arbitrary Lightning node to connect to, +which you can do by using dig(1) and querying *lseed.bitcoinstats.com*: + + $ dig lseed.bitcoinstats.com A + +This will give 25 IPv4 addresses, you can select any one of those. You +will also need to learn the corresponding public key, which you can +determine by searching the IP addrss on . The public +key is a long hex string, like so: +*024772ee4fa461febcef09d5869e1238f932861f57be7a6633048514e3f56644a1*. +(this example public key is not used as of this writing) + +After determining a public key, use lightning-connect(7) to connect to +that public key: + + $ lightning-cli connect $PUBLICKEY + +Then open a channel to that node using lightning-fundchannel(7): + + $ lightning-cli fundchannel $PUBLICKEY $SATOSHI + +This will require that the funding transaction be confirmed before you +can send funds over Lightning. To track this, use lightning-listpeers(7) +and look at the *state* of the channel: + + $ lightning-cli listpeers $PUBLICKEY + +The channel will initially start with a *state* of +*CHANNELD\_AWAITING\_LOCKIN*. You need to wait for the channel *state* +to become *CHANNELD\_NORMAL*, meaning the funding transaction has been +confirmed deeply. + +Once the channel *state* is *CHANNELD\_NORMAL*, you can start paying +merchants over Lightning. Acquire a Lightning invoice from your favorite +merchant, and use lightning-pay(7) to pay it: + + $ lightning-cli pay $INVOICE + +BUGS + +You should report bugs on our github issues page, and maybe submit a fix +to gain our eternal gratitude! + +AUTHOR + +ZmnSCPxj <> wrote the initial version of +this man page, but many others did the hard work of actually +implementing a standards-compliant Lightning Network node +implementation. + +SEE ALSO + +lightning-listconfigs(7), lightning-config(5), lightning-cli(1), +lightning-newaddr(7), lightning-listfunds(7), lightning-connect(7), +lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7) + +RESOURCES + +Main web site: + +COPYING + +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. + + +Last updated 2019-08-09 11:11:48 CEST