mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-21 14:24:09 +01:00
Code Issues Projects Releases Wiki Activity

doc/manpages: replace asciidoc by markdown

Browse source
This commit is contained in:
darosior 2019-08-10 01:54:18 +02:00 • committed by Rusty Russell
parent 3f29216f7b
commit 80927039e0
70 changed files with 3100 additions and 2191 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
doc/lightning-autocleaninvoice.7.md Normal file
View file

@ -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 <<ZmnSCPxj@protonmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-delexpiredinvoice(7), lightning-delinvoice(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-07 14:23:17 CEST

42
doc/lightning-autocleaninvoice.7.txt
View file

@ -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 <ZmnSCPxj@protonmail.com> is mainly responsible.
SEE ALSO
--------
lightning-delexpiredinvoice(7), lightning-delinvoice(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

43
doc/lightning-check.7.md Normal file
View file

@ -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 <<wythe@intrig.com>> and Rusty Russell
<<rusty@rustcorp.com.au>> are mainly responsible.
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

37
doc/lightning-check.7.txt
View file

@ -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 <wythe@intrig.com> and Rusty Russell <rusty@rustcorp.com.au>
are mainly responsible.
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

97
doc/lightning-cli.1.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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.
------------------------------------------------------------------------
Last updated 2019-04-30 17:39:53 CEST

83
doc/lightning-cli.1.txt
View file

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

74
doc/lightning-close.7.md Normal file
View file

@ -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 <<ZmnSCPxj@protonmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-disconnect(7), lightning-fundchannel(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-08-09 11:12:04 CEST

75
doc/lightning-close.7.txt
View file

@ -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 <ZmnSCPxj@protonmail.com> is mainly responsible.
SEE ALSO
--------
lightning-disconnect(7), lightning-fundchannel(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

65
doc/lightning-connect.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
Felix <<fixone@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-08-01 14:59:36 CEST

66
doc/lightning-connect.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
Felix <fixone@gmail.com> 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

67
doc/lightning-decodepay.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

61
doc/lightning-decodepay.7.txt
View file

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

41
doc/lightning-delexpiredinvoice.7.md Normal file
View file

@ -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 <<ZmnSCPxj@protonmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-delinvoice(7), lightning-autocleaninvoice(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-07 14:23:17 CEST

35
doc/lightning-delexpiredinvoice.7.txt
View file

@ -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 <ZmnSCPxj@protonmail.com> is mainly responsible.
SEE ALSO
--------
lightning-delinvoice(7), lightning-autocleaninvoice(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

44
doc/lightning-delinvoice.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-04-07 14:23:17 CEST

38
doc/lightning-delinvoice.7.txt
View file

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

69
doc/lightning-disconnect.7.md Normal file
View file

@ -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 <<michael.hawkins@protonmail.com>>.
SEE ALSO
--------
lightning-connect(1), lightning-listpeers(1)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:34:18 CEST

61
doc/lightning-disconnect.7.txt
View file

@ -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 <michael.hawkins@protonmail.com>.
SEE ALSO
--------
lightning-connect(1), lightning-listpeers(1)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

82
doc/lightning-fundchannel.7.md Normal file
View file

@ -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: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-06-12 11:16:20 CEST

76
doc/lightning-fundchannel.7.txt
View file

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

45
doc/lightning-fundchannel_cancel.7.md Normal file
View file

@ -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 <<niftynei@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-06-12 11:16:20 CEST

37
doc/lightning-fundchannel_cancel.7.txt
View file

@ -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 <niftynei@gmail.com> 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

54
doc/lightning-fundchannel_complete.7.md Normal file
View file

@ -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 <<niftynei@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-06-12 11:16:20 CEST

46
doc/lightning-fundchannel_complete.7.txt
View file

@ -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 <niftynei@gmail.com> 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

53
doc/lightning-fundchannel_start.7.md Normal file
View file

@ -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 <<niftynei@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-06-12 11:16:20 CEST

45
doc/lightning-fundchannel_start.7.txt
View file

@ -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 <niftynei@gmail.com> 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

306
doc/lightning-getroute.7.md Normal file
View file

@ -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.
<table>
<colgroup>
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Amount (msat)</th>
<th style="text-align: left;">Riskfactor</th>
<th style="text-align: left;">Delay</th>
<th style="text-align: left;">Risk Fee</th>
<th style="text-align: left;">Route fee</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2661</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2661</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26617</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266179</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27378</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27378</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273785</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737850</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
</tbody>
</table>
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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-pay(7), lightning-sendpay(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-08-01 14:59:36 CEST

144
doc/lightning-getroute.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-pay(7), lightning-sendpay(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

109
doc/lightning-invoice.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-08-02 18:18:10 CEST

107
doc/lightning-invoice.7.txt
View file

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

106
doc/lightning-listchannels.7.md Normal file
View file

@ -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 <<michael.hawkins@protonmail.com>>.
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>
------------------------------------------------------------------------
Last updated 2019-06-12 11:16:20 CEST

95
doc/lightning-listchannels.7.txt
View file

@ -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 <michael.hawkins@protonmail.com>.
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

62
doc/lightning-listforwards.7.md Normal file
View file

@ -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 <<r.pickhardt@gmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-getinfo(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-07-23 00:53:16 CEST

58
doc/lightning-listforwards.7.txt
View file

@ -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 <r.pickhardt@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-getinfo(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

68
doc/lightning-listfunds.7.md Normal file
View file

@ -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 <<fixone@gmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-newaddr(7), lightning-fundchannel(7), lightning-withdraw(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-07-28 16:25:20 CEST

70
doc/lightning-listfunds.7.txt
View file

@ -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 <fixone@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-newaddr(7), lightning-fundchannel(7), lightning-withdraw(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

48
doc/lightning-listinvoices.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

43
doc/lightning-listinvoices.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

67
doc/lightning-listpays.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-pay(7), lightning-paystatus(7), lightning-listsendpays(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

49
doc/lightning-listpays.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-pay(7), lightning-paystatus(7), lightning-listsendpays(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

89
doc/lightning-listpeers.7.md Normal file
View file

@ -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 <<michael.hawkins@protonmail.com>>.
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>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

79
doc/lightning-listpeers.7.txt
View file

@ -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 <michael.hawkins@protonmail.com>.
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

72
doc/lightning-listsendpays.7.md Normal file
View file

@ -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 <<decker.christian@gmail.com>> is mainly
responsible.
SEE ALSO
--------
lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:12:10 CEST

50
doc/lightning-listsendpays.7.txt
View file

@ -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 <decker.christian@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

58
doc/lightning-newaddr.7.md Normal file
View file

@ -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 <<fixone@gmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-listfunds(7), lightning-fundchannel(7), lightning-withdraw(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-04-30 17:34:18 CEST

48
doc/lightning-newaddr.7.txt
View file

@ -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 <fixone@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-listfunds(7), lightning-fundchannel(7), lightning-withdraw(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

135
doc/lightning-pay.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-08-01 14:59:36 CEST

151
doc/lightning-pay.7.txt
View file

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

53
doc/lightning-plugin.7.md Normal file
View file

@ -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 <<darosior@protonmail.com>> is mainly responsible.
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-07-29 12:57:57 CEST

48
doc/lightning-plugin.7.txt
View file

@ -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 <darosior@protonmail.com> is mainly responsible.
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

107
doc/lightning-sendpay.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-08-01 14:59:36 CEST

109
doc/lightning-sendpay.7.txt
View file

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

72
doc/lightning-setchannelfee.7.md Normal file
View file

@ -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 <<michael@schmoock.net>> is the author of this
feature. Rusty Russell <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-04-30 17:34:18 CEST

61
doc/lightning-setchannelfee.7.txt
View file

@ -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 <michael@schmoock.net> is the author of this feature.
Rusty Russell <rusty@rustcorp.com.au> 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

48
doc/lightning-txdiscard.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-txprepare(7), lightning-txsend(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-06-08 16:03:59 CEST

42
doc/lightning-txdiscard.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-txprepare(7), lightning-txsend(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

57
doc/lightning-txprepare.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-06-08 16:03:59 CEST

52
doc/lightning-txprepare.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

47
doc/lightning-txsend.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-txprepare(7), lightning-txdiscard(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-06-08 16:03:59 CEST

43
doc/lightning-txsend.7.txt
View file

@ -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 <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
--------
lightning-txprepare(7), lightning-txdiscard(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

50
doc/lightning-waitanyinvoice.7.md Normal file
View file

@ -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 <<rusty@rustcorp.com.au>> 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>
------------------------------------------------------------------------
Last updated 2019-04-07 14:23:17 CEST

45
doc/lightning-waitanyinvoice.7.txt
View file

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

48
doc/lightning-waitinvoice.7.md Normal file
View file

@ -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 <<decker.christian@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-04-07 14:23:17 CEST

40
doc/lightning-waitinvoice.7.txt
View file

@ -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 <decker.christian@gmail.com> 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

89
doc/lightning-waitsendpay.7.md Normal file
View file

@ -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 <<ZmnSCPxj@protonmail.com>> is mainly responsible.
SEE ALSO
--------
lightning-sendpay(7), lightning-pay(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
------------------------------------------------------------------------
Last updated 2019-05-22 16:46:09 CEST

89
doc/lightning-waitsendpay.7.txt
View file

@ -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 <ZmnSCPxj@protonmail.com> is mainly responsible.
SEE ALSO
--------
lightning-sendpay(7), lightning-pay(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning

74
doc/lightning-withdraw.7.md Normal file
View file

@ -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 <<fixone@gmail.com>> 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>
------------------------------------------------------------------------
Last updated 2019-06-08 16:03:59 CEST

66
doc/lightning-withdraw.7.txt
View file

@ -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 <fixone@gmail.com> 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

376
doc/lightningd-config.5.md Normal file
View file

@ -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 &lt;<rusty@rustcorp.com.au>&gt; 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: <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.
Last updated 2019-08-09 11:12:04 CEST

177
doc/lightningd.8.md Normal file
View file

@ -0,0 +1,177 @@
LIGHTNINGD(8) Manual Page
=========================
lightningd - Daemon for running a Lightning Network node
SYNOPSIS
lightningd \[--conf=&lt;config-file&gt;\] \[*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 <https://1ml.com/> . 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 &lt;<ZmnSCPxj@protonmail.com>&gt; 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: <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.
Last updated 2019-08-09 11:11:48 CEST