diff --git a/doc/index.rst b/doc/index.rst index 475084763ff0..d0059921ecd3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,3 +22,44 @@ c-lightning Documentation Coding Style Guideline MAKING-RELEASES.md CHANGELOG.md + +.. toctree:: + :maxdepth: 1 + :caption: Manpages + + doc/lightning-autocleaninvoice.7.md + doc/lightning-check.7.md + doc/lightning-cli.1.md + doc/lightning-close.7.md + doc/lightning-connect.7.md + doc/lightningd-config.5.md + doc/lightning-decodepay.7.md + doc/lightning-delexpiredinvoice.7.md + doc/lightning-delinvoice.7.md + doc/lightning-disconnect.7.md + doc/lightning-fundchannel.7.md + doc/lightning-fundchannel_cancel.7.md + doc/lightning-fundchannel_complete.7.md + doc/lightning-fundchannel_start.7.md + doc/lightning-getroute.7.md + doc/lightning-invoice.7.md + doc/lightning-listchannels.7.md + doc/lightning-listforwards.7.md + doc/lightning-listfunds.7.md + doc/lightning-listinvoices.7.md + doc/lightning-listpays.7.md + doc/lightning-listpeers.7.md + doc/lightning-listsendpays.7.md + doc/lightning-newaddr.7.md + doc/lightning-pay.7.md + doc/lightning-plugin.7.md + doc/lightning-sendpay.7.md + doc/lightning-setchannelfee.7.md + doc/lightning-txdiscard.7.md + doc/lightning-txprepare.7.md + doc/lightning-txsend.7.md + doc/lightning-waitanyinvoice.7.md + doc/lightning-waitinvoice.7.md + doc/lightning-waitsendpay.7.md + doc/lightning-withdraw.7.md + diff --git a/doc/lightning-autocleaninvoice.7.md b/doc/lightning-autocleaninvoice.7.md new file mode 100644 index 000000000000..59e5b826cadd --- /dev/null +++ b/doc/lightning-autocleaninvoice.7.md @@ -0,0 +1,45 @@ +lightning-autocleaninvoice + +7 + +lightning-autocleaninvoice + +Set up auto-delete of expired invoice + +**autocleaninvoice** \[*cycle\_seconds*\] \[*expired\_by*\] + +DESCRIPTION +=========== + +The **autocleaninvoice** RPC command sets up automatic cleaning of +expired invoices. + +Autoclean will be done every *cycle\_seconds* seconds. Setting +*cycle\_seconds* to 0 disables autoclean. If not specified, this +defaults to 3600 (one hour). + +Every autoclean cycle, expired invoices, which have already been expired +for at least *expired\_by* seconds, will be deleted. If *expired\_by* is +not specified, this defaults to 86400 (one day). + +On startup of the daemon, no autoclean is set up. + +RETURN VALUE +============ + +On success, an empty object is returned. + +AUTHOR +====== + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +======== + +lightning-delexpiredinvoice(7), lightning-delinvoice(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-check.7.md b/doc/lightning-check.7.md new file mode 100644 index 000000000000..cf5431ea2f2b --- /dev/null +++ b/doc/lightning-check.7.md @@ -0,0 +1,40 @@ +lightning-check + +7 + +lightning-check + +Command for verifying parameters + +**check** *command\_to\_check* \[*parameters*\] + +DESCRIPTION +=========== + +The **check** RPC command verifies another command’s parameters without +running it. + +The *command\_to\_check* is the name of the relevant command. + +*parameters* is the command’s parameters. + +This does not guarantee successful execution of the command in all +cases. For example, a call to lightning-getroute(7) may still fail to +find a route even if checking the parameters succeeds. + +RETURN VALUE +============ + +On success, the *command\_to\_check* is returned. On failure, the +relevant RPC error is returned. + +AUTHOR +====== + +Mark Beckwith <> and Rusty Russell +<> are mainly responsible. + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-cli.1.md b/doc/lightning-cli.1.md new file mode 100644 index 000000000000..56b481cc22e8 --- /dev/null +++ b/doc/lightning-cli.1.md @@ -0,0 +1,92 @@ +lightning-cli + +1 + +lightning-cli + +Control lightning daemon + +**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 +======== + +lightning-cli help + +BUGS +==== + +This manpage documents how it should work, not how it does work. The +pretty printing of results isn’t pretty. + +AUTHOR +====== + +Rusty Russell <> is mainly to blame. + +RESOURCES +========= + +Main web site: + +COPYING +======= + +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. diff --git a/doc/lightning-close.7.md b/doc/lightning-close.7.md new file mode 100644 index 000000000000..98b8dd9d93c2 --- /dev/null +++ b/doc/lightning-close.7.md @@ -0,0 +1,66 @@ +lightning-close + +7 + +lightning-close + +Command for closing channels with direct peers + +**close** *id* \[*force*\] \[*timeout*\] + +DESCRIPTION +=========== + +The **close** RPC command attempts to close the channel cooperatively +with the peer. 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. + +The **close** command will time out and return with an error when the +number of seconds specified in *timeout* is reached. If unspecified, it +times out in 30 seconds. + +The *force* argument, if the JSON value *true*, will cause the channel +to be unilaterally closed when the timeout is reached. If so, timeout +will not cause an error, but instead cause the channel to be failed and +put onchain unilaterally. Unilateral closes will lead to your funds +getting locked according to the *to\_self\_delay* parameter of the peer. + +Normally the peer needs to be live and connected in order to negotiate a +mutual close. Forcing a unilateral close can be used if you suspect you +can no longer contact the peer. + +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 with *force* set to *false* 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. + +On failure, if **close** failed due to timing out with *force* argument +*false*, the channel will still eventually close once we have contacted +the peer. + +AUTHOR +====== + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +======== + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-connect.7.md b/doc/lightning-connect.7.md new file mode 100644 index 000000000000..39455108c2d3 --- /dev/null +++ b/doc/lightning-connect.7.md @@ -0,0 +1,63 @@ +lightning-connect + +7 + +lightning-connect + +Command for connecting to another lightning node. + +**connect** *id* \[*host* *port*\] + +DESCRIPTION +=========== + +The **connect** RPC command establishes a new connection with another +node in the Lightning Network. + +*id* represents the target node’s public key. As a convenience, *id* may +be of the form *id@host* or *id@host:port*. In this case, the *host* and +*port* parameters must be omitted. + +*host* is the peer’s hostname or IP address. + +If not specified, the *port* defaults to 9735. + +If *host* is not specified, the connection will be attempted to an IP +belonging to *id* obtained through gossip with other already connected +peers. + +If *host* begins with a */* it is interpreted as a local path, and the +connection will be made to that local socket (see **bind-addr** in +lightningd-config(5)). + +Connecting to a node is just the first step in opening a channel with +another node. Once the peer is connected a channel can be opened with +lightning-fundchannel(7). + +RETURN VALUE +============ + +On success the peer *id* is returned. + +The following error codes may occur: + +- -1. Catchall nonspecific error. This may occur if the host is not + valid or there are problems communicating with the peer. **connect** + will make up to 10 attempts to connect to the peer before giving up. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. +Felix <> is the original author of this manpage. + +SEE ALSO +======== + +lightning-fundchannel(7), lightning-listpeers(7), +lightning-listchannels(7), lightning-disconnect(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md new file mode 100644 index 000000000000..0c90ca644a4e --- /dev/null +++ b/doc/lightning-decodepay.7.md @@ -0,0 +1,76 @@ +lightning-decodepay + +7 + +lightning-decodepay + +Command for decoding a bolt11 string (low-level) + +**decodepay** *bolt11* \[*description*\] + +DESCRIPTION +=========== + +The **decodepay** RPC command checks and parses a *bolt11* string as +specified by the BOLT 11 specification. + +RETURN VALUE +============ + +On success, an object is returned with the following fields, as +specified by BOLT11: + +- *currency*: the BIP173 name for the currency. + +- *timestamp*: the UNIX-style timestamp of the invoice. + +- *expiry*: the number of seconds this is valid after *timestamp*. + +- *payee*: the public key of the recipient. + +- *payment\_hash*: the payment hash of the request. + +- *signature*: the DER-encoded signature. + +- *description*: the description of the purpose of the purchase (see + below) + +The following fields are optional: + +- *msatoshi*: the number of millisatoshi requested (if any). + +- *amount\_msat*: the same as above, with *msat* appended (if any). + +- *fallbacks*: array of fallback address object containing a *hex* + string, and both *type* and *addr* if it is recognized as one of + *P2PKH*, *P2SH*, *P2WPKH*, or *P2WSH*. + +- *routes*: an array of routes. Each route is an arrays of objects, + each containing *pubkey*, *short\_channel\_id*, *fee\_base\_msat*, + *fee\_proportional\_millionths* and *cltv\_expiry\_delta*. + +- *extra*: an array of objects representing unknown fields, each with + one-character *tag* and a *data* bech32 string. + +Technically, the *description* field is optional if a +*description\_hash* field is given, but in this case **decodepay** will +only succeed if the optional *description* field is passed and matches +the *description\_hash*. In practice, these are currently unused. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-pay(7), lightning-getroute(7), lightning-sendpay(7). + +[BOLT +\#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md new file mode 100644 index 000000000000..4ae18128106e --- /dev/null +++ b/doc/lightning-delexpiredinvoice.7.md @@ -0,0 +1,38 @@ +lightning-delexpiredinvoice + +7 + +lightning-delexpiredinvoice + +Command for removing expired invoices. + +**delexpiredinvoice** \[*maxexpirytime*\] + +DESCRIPTION +=========== + +The **delexpiredinvoice** RPC command removes all invoices that have +expired on or before the given *maxexpirytime*. + +If *maxexpirytime* is not specified then all expired invoices are +deleted. + +RETURN VALUE +============ + +On success, an empty object is returned. + +AUTHOR +====== + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +======== + +lightning-delinvoice(7), lightning-autocleaninvoice(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md new file mode 100644 index 000000000000..3d864bed0ec5 --- /dev/null +++ b/doc/lightning-delinvoice.7.md @@ -0,0 +1,41 @@ +lightning-delinvoice + +7 + +lightning-delinvoice + +Command for removing an invoice. + +**delinvoice** *label* *status* + +DESCRIPTION +=========== + +The **delinvoice** RPC command removes an invoice with *status* as given +in **listinvoices**. + +The caller should be particularly aware of the error case caused by the +*status* changing just before this command is invoked! + +RETURN VALUE +============ + +On success, an invoice description will be returned as per +lightning-listinvoice(7). + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-listinvoice(7), lightning-waitinvoice(7), +lightning-invoice(7), lightning-delexpiredinvoice(7), +lightning-autocleaninvoice(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md new file mode 100644 index 000000000000..f8b759bdf047 --- /dev/null +++ b/doc/lightning-disconnect.7.md @@ -0,0 +1,65 @@ +lightning-disconnect + +7 + +lightning-disconnect + +Command for disconnecting from another lightning node. + +**disconnect** *id* \[*force*\] + +DESCRIPTION +=========== + +The disconnect RPC command closes an existing connection to a peer, +identified by *id*, in the Lightning Network, as long as it doesn’t have +an active channel. If *force* is set then it will disconnect even with +an active channel. + +The *id* can be discovered in the output of the listpeers command, which +returns a set of peers: + + { + "peers": [ + { + "id": "0563aea81...", + "connected": true, + ... + } + ] + } + +Passing the *id* attribute of a peer to *disconnect* will terminate the +connection. + +RETURN VALUE +============ + +On success, an empty object is returned. + +ERRORS +====== + +If *id* is invalid, an error message will be returned: + + { "code" : -1, "message" : "Peer not connected" } + +If the peer has an active channel and *force* is not set, an error +message will be returned: + + { "code" : -1, "message" : "Peer is in state CHANNELD_NORMAL" } + +AUTHOR +====== + +Michael Hawkins <>. + +SEE ALSO +======== + +lightning-connect(1), lightning-listpeers(1) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md new file mode 100644 index 000000000000..a4c22e37466b --- /dev/null +++ b/doc/lightning-fundchannel.7.md @@ -0,0 +1,86 @@ +lightning-fundchannel + +7 + +lightning-fundchannel + +Command for establishing a lightning channel. + +**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: diff --git a/doc/lightning-fundchannel_cancel.7.md b/doc/lightning-fundchannel_cancel.7.md new file mode 100644 index 000000000000..446d307d3a16 --- /dev/null +++ b/doc/lightning-fundchannel_cancel.7.md @@ -0,0 +1,41 @@ +lightning-fundchannel\_cancel + +7 + +lightning-fundchannel\_cancel + +Command for completing channel establishment + +**fundchannel\_cancel** *id* + +DESCRIPTION +=========== + +`fundchannel_cancel` is a lower level RPC command. It allows a user to +cancel an initiated channel establishment with a connected peer. + +*id* is the node id of the remote peer with which to cancel the + +RETURN VALUE +============ + +On success, returns confirmation that the channel establishment has been +canceled. + +On failure, returns an error. + +AUTHOR +====== + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +======== + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_start(7), lightning-fundchannel\_complete(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-fundchannel_complete.7.md b/doc/lightning-fundchannel_complete.7.md new file mode 100644 index 000000000000..44ae136a27ce --- /dev/null +++ b/doc/lightning-fundchannel_complete.7.md @@ -0,0 +1,50 @@ +lightning-fundchannel\_complete + +7 + +lightning-fundchannel\_complete + +Command for completing channel establishment + +**fundchannel\_complete** *id* *txid* *txout* + +DESCRIPTION +=========== + +`fundchannel_complete` is a lower level RPC command. It allows a user to +complete an initiated channel establishment with a connected peer + +*id* is the node id of the remote peer + +*txid* is the hex string of the funding transaction id. + +*txout* is the integer outpoint of the funding output for this channel. + +Note that the funding transaction should not be broadcast until after +channel establishment has been successfully completed, as the commitment +transactions for this channel are not secured until this command +succesfully completes. + +RETURN VALUE +============ + +On success, returns a confirmation that *commitments\_secured* and the +derived *channel\_id*. + +On failure, returns an error. + +AUTHOR +====== + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +======== + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_start(7), lightning-fundchannel\_cancel(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-fundchannel_start.7.md b/doc/lightning-fundchannel_start.7.md new file mode 100644 index 000000000000..40a24f4cca81 --- /dev/null +++ b/doc/lightning-fundchannel_start.7.md @@ -0,0 +1,49 @@ +lightning-fundchannel\_start + +7 + +lightning-fundchannel\_start + +Command for initiating channel establishment for a lightning channel + +**fundchannel\_start** *id* *satoshi* \[*feerate* *announce*\] + +DESCRIPTION +=========== + +`fundchannel_start` is a lower level RPC command. It allows a user to +initiate channel establishment with a connected peer. + +*id* is the node id of the remote peer. + +*satoshi* is the satoshi value that the channel will be funded at. This +value MUST be accurate, otherwise the negotiated commitment transactions +will not encompass the correct channel value. + +*feerate* is an optional field. Sets the feerate for subsequent +commitment transactions. + +*announce* whether or not to annouce this channel. + +RETURN VALUE +============ + +On success, returns the *funding\_address* for the channel. + +On failure, returns an error. + +AUTHOR +====== + +Lisa Neigut <> is mainly responsible. + +SEE ALSO +======== + +lightning-connect(7), lightning-fundchannel(7), +lightning-fundchannel\_complete(7), lightning-fundchannel\_cancel(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-getroute.7.md b/doc/lightning-getroute.7.md new file mode 100644 index 000000000000..abcc615f2dde --- /dev/null +++ b/doc/lightning-getroute.7.md @@ -0,0 +1,303 @@ +lightning-getroute + +7 + +lightning-getroute + +Command for routing a payment (low-level). + +**getroute** *id* *msatoshi* *riskfactor* \[*cltv*\] \[*fromid*\] +\[*fuzzpercent*\] \[*exclude*\] \[*maxhops*\] + +DESCRIPTION +=========== + +The **getroute** RPC command attempts to find the best route for the +payment of *msatoshi* to lightning node *id*, such that the payment will +arrive at *id* with *cltv*-blocks to spare (default 9). + +*msatoshi* is in millisatoshi precision; it can be a whole number, or a +whole number ending in *msat* or *sat*, or a number with three decimal +places ending in *sat*, or a number with 1 to 11 decimal places ending +in *btc*. + +There are two considerations for how good a route is: how low the fees +are, and how long your payment will get stuck in a delayed output if a +node goes down during the process. The *riskfactor* floating-point field +controls this tradeoff; it is the annual cost of your funds being stuck +(as a percentage). + +For example, if you thought the convenience of keeping your funds liquid +(not stuck) was worth 20% per annum interest, *riskfactor* would be 20. + +If you didn’t care about risk, *riskfactor* would be zero. + +*fromid* is the node to start the route from: default is this node. + +The *fuzzpercent* is a positive floating-point number, representing a +percentage of the actual fee. The *fuzzpercent* is used to distort +computed fees along each channel, to provide some randomization to the +route generated. 0.0 means the exact fee of that channel is used, while +100.0 means the fee used might be from 0 to twice the actual fee. The +default is 5.0, or up to 5% fee distortion. + +*exclude* is a JSON array of short-channel-id/direction (e.g. \[ +"564334x877x1/0", "564195x1292x0/1" \]) which should be excluded from +consideration for routing. The default is not to exclude any channels. + +*maxhops* is the maximum number of channels to return; default is 20. + +RISKFACTOR EFFECT ON ROUTING +============================ + +The risk factor is treated as if it were an additional fee on the route, +for the purposes of comparing routes. + +The formula used is the following approximation: + + risk-fee = amount x blocks-timeout x per-block-cost + +We are given a *riskfactor* expressed as a percentage. There are 52596 +blocks per year, thus *per-block-cost* is *riskfactor* divided by +5,259,600. + +The final result is: + + risk-fee = amount x blocks-timeout x riskfactor / 5259600 + +Here are the risk fees in millisatoshis, using various parameters. I +assume a channel charges the default of 1000 millisatoshis plus 1 +part-per-million. Common to\_self\_delay values on the network at 14 and +144 blocks. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Amount (msat)RiskfactorDelayRisk FeeRoute fee

10,000

1

14

0

1001

10,000

10

14

0

1001

10,000

100

14

2

1001

10,000

1000

14

26

1001

1,000,000

1

14

2

1001

1,000,000

10

14

26

1001

1,000,000

100

14

266

1001

1,000,000

1000

14

2661

1001

100,000,000

1

14

266

1100

100,000,000

10

14

2661

1100

100,000,000

100

14

26617

1100

100,000,000

1000

14

266179

1100

10,000

1

144

0

1001

10,000

10

144

2

1001

10,000

100

144

27

1001

10,000

1000

144

273

1001

1,000,000

1

144

27

1001

1,000,000

10

144

273

1001

1,000,000

100

144

2737

1001

1,000,000

1000

144

27378

1001

100,000,000

1

144

2737

1100

100,000,000

10

144

27378

1100

100,000,000

100

144

273785

1100

100,000,000

1000

144

2737850

1100

+ +RECOMMENDED RISKFACTOR VALUES +============================= + +The default *fuzz* factor is 5%, so as you can see from the table above, +that tends to overwhelm the effect of *riskfactor* less than about 5. + +1 is a conservative value for a stable lightning network with very few +failures. + +1000 is an aggressive value for trying to minimize timeouts at all +costs. + +The default for lightning-pay(7) is 10, which starts to become a major +factor for larger amounts, and is basically ignored for tiny ones. + +RETURN VALUE +============ + +On success, a "route" array is returned. Each array element contains +*id* (the node being routed through), *msatoshi* (the millisatoshis +sent), *amount\_msat* (the same, with *msat* appended), and *delay* (the +number of blocks to timeout at this node). + +The final *id* will be the destination *id* given in the input. The +difference between the first *msatoshi* minus the *msatoshi* given in +the input is the fee. The first *delay* is the very worst case timeout +for the payment failure, in blocks. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-pay(7), lightning-sendpay(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md new file mode 100644 index 000000000000..51e7a1dde4e4 --- /dev/null +++ b/doc/lightning-invoice.7.md @@ -0,0 +1,111 @@ +lightning-invoice + +7 + +lightning-invoice + +Command for accepting payments. + +**invoice** *msatoshi* *label* *description* \[*expiry*\] +\[*fallbacks*\] \[*preimage*\] \[*exposeprivatechannels*\] + +DESCRIPTION +=========== + +The **invoice** RPC command creates the expectation of a payment of a +given amount of milli-satoshi: it returns a unique token which another +lightning daemon can use to pay this invoice. This token includes a +*route hint* description of an incoming channel with capacity to pay the +invoice, if any exists. + +The *msatoshi* parameter can be the string "any", which creates an +invoice that can be paid with any amount. Otherwise it is in +millisatoshi precision; it can be a whole number, or a whole number +ending in *msat* or *sat*, or a number with three decimal places ending +in *sat*, or a number with 1 to 11 decimal places ending in *btc*. + +The *label* must be a unique string or number (which is treated as a +string, so "01" is different from "1"); it is never revealed to other +nodes on the lightning network, but it can be used to query the status +of this invoice. + +The *description* is a short description of purpose of payment, e.g. *1 +cup of coffee*. This value is encoded into the BOLT11 invoice and is +viewable by any node you send this invoice to. It must be UTF-8, and +cannot use *\\u* JSON escape codes. + +The *expiry* is optionally the time the invoice is valid for; without a +suffix it is interpreted as seconds, otherwise suffixes *s*, *m*, *h*, +*d*, *w* indicate seconds, minutes, hours, days and weeks respectively. +If no value is provided the default of 604800 (1w) is used. + +The *fallbacks* array is one or more fallback addresses to include in +the invoice (in order from most-preferred to least): note that these +arrays are not currently tracked to fulfill the invoice. + +The *preimage* is a 64-digit hex string to be used as payment preimage +for the created invoice. By default, if unspecified, lightningd will +generate a secure pseudorandom preimage seeded from an appropriate +entropy source on your system. **IMPORTANT**: if you specify the +*preimage*, you are responsible, to ensure appropriate care for +generating using a secure pseudorandom generator seeded with sufficient +entropy, and keeping the preimage secret. This parameter is an advanced +feature intended for use with cutting-edge cryptographic protocols and +should not be used unless explicitly needed. + +If specified, *exposeprivatechannels* overrides the default route hint +logic, which will use unpublished channels only if there are no +published channels. If *true* unpublished channels are always considered +as a route hint candidate; if *false*, never. + +The route hint is selected from the set of incoming channels of which: +peer’s balance minus their reserves is at least *msatoshi*, state is +normal, the peer is connected and not a dead end (i.e. has at least one +other public channel). The selection uses some randomness to prevent +probing, but favors channels that become more balanced after the +payment. + +RETURN VALUE +============ + +On success, a hash is returned as *payment\_hash* to be given to the +payer, and the *expiry\_time* as a UNIX timestamp. It also returns a +BOLT11 invoice as *bolt11* to be given to the payer. + +On failure, an error is returned and no invoice is created. If the +lightning process fails before responding, the caller should use +lightning-listinvoice(7) to query whether this invoice was created or +not. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 900. An invoice with the given *label* already exists. + +- 901. An invoice with the given *preimage* already exists. + +One of the following warnings may occur (on success): + +- *warning\_offline* if no channel with a currently connected peer has + the incoming capacity to pay this invoice + +- *warning\_capacity* if there is no channel that has both sufficient + incoming capacity and has a peer that is publicly connected (i.e. + not a dead end) + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-sendpay(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md new file mode 100644 index 000000000000..f3f3efb6ef5e --- /dev/null +++ b/doc/lightning-listchannels.7.md @@ -0,0 +1,117 @@ +lightning-listchannels + +7 + +lightning-listchannels + +Command to query active lightning channels in the entire network. + +**listchannels** \[*short\_channel\_id*\] \[*source*\] + +DESCRIPTION +=========== + +The **listchannels** RPC command returns data on channels that are known +to the node. Because channels may be bidirectional, up to 2 objects will +be returned for each channel (one for each direction). + +If *short\_channel\_id* is supplied, then only known channels with a +matching *short\_channel\_id* are returned. + +If *source* is supplied, then only channels leading from that node id +are returned. + +If neither is supplied, data on all lightning channels known to this +node, are returned. These can be local channels or public channels +broadcast on the gossip network. + +RETURN VALUE +============ + +On success, an object with a "channels" key is returned containing a +list of 0 or more objects. + +Each object in the list contains the following data: + +- *source* : The node providing entry to the channel, specifying the + fees charged for using the channel in that direction. + +- *destination* : The node providing the exit point for the channel. + +- *short\_channel\_id* : The channel identifier. + +- *public* : Boolean value, is publicly available. Non-local channels + will only ever have this value set to true. Local channels are + side-loaded by this node, rather than obtained through the gossip + network, and so may have this value set to false. + +- *satoshis* : Funds available in the channel. + +- *amount\_sat* : Same as above, but ending in *sat*. + +- *message\_flags* : Bitfield showing the presence of optional fields + in the *channel\_update* message (BOLT \#7). + +- *channel\_flags* : Bitfields indicating the direction of the channel + and signaling various options concerning the channel. (BOLT \#7). + +- *active* : Boolean value, is available for routing. This is linked + to the channel flags data, where if the second bit is set, signals a + channels temporary unavailability (due to loss of connectivity) OR + permanent unavailability where the channel has been closed but not + settlement on-chain. + +- *last\_update* : Unix timestamp (seconds) showing when the last + channel\_update message was received. + +- *base\_fee\_millisatoshi* : The base fee (in millisatoshi) charged + for the HTLC (BOLT \#2). + +- *fee\_per\_millionth* : The amount (in millionths of a satoshi) + charged per transferred satoshi (BOLT \#2). + +- *delay* : The number of blocks delay required to wait for on-chain + settlement when unilaterally closing the channel (BOLT \#2). + +- *htlc\_minimum\_msat* : The minimum payment which can be send + through this channel. + +- *htlc\_maximum\_msat* : The maximum payment which can be send + through this channel. + +If *short\_channel\_id* or *source* is supplied and no matching channels +are found, a "channels" object with an empty list is returned. + +ERRORS +====== + +If *short\_channel\_id* is not a valid short\_channel\_id, an error +message will be returned: + + { "code" : -32602, + "message" : "'short_channel_id' should be a short channel id, not '...'" } + +Similarly if *source* is not a valid pubkey. + +AUTHOR +====== + +Michael Hawkins <>. + +SEE ALSO +======== + +lightning-fundchannel(7), lightning-listnodes(7) + +RESOURCES +========= + +Main web site: + +Lightning RFC site + +- BOLT \#2: + + +- BOLT \#7: + diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md new file mode 100644 index 000000000000..089c46f1b80b --- /dev/null +++ b/doc/lightning-listforwards.7.md @@ -0,0 +1,61 @@ +lightning-listforwards + +7 + +lightning-listforwards + +Command showing all htlcs and their information. + +**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. + +- *out\_channel* - the short\_channel\_id of to which the outgoing + htlc is supposed to be forwarded. + +- *in\_msatoshi*, *in\_msat* - amount of msatoshis that are forwarded + to this node. + +- *out\_msatoshi*, *out\_msat* - amount of msatoshis to be forwarded. + +- *fee*, *fee\_msat* - fee offered for forwarding the htlc in + msatoshi. + +- *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. + +- *resolved\_time* - timestamp when htlc was resolved (settled or + failed). + +AUTHOR +====== + +Rene Pickhardt <> is mainly responsible. + +SEE ALSO +======== + +lightning-getinfo(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-listfunds.7.md b/doc/lightning-listfunds.7.md new file mode 100644 index 000000000000..c01f5d94cc87 --- /dev/null +++ b/doc/lightning-listfunds.7.md @@ -0,0 +1,78 @@ +lightning-listfunds + +7 + +lightning-listfunds + +Command showing all funds currently managed by the c-lightning node. + +**listfunds** + +DESCRIPTION +=========== + +The **listfunds** RPC command displays all funds available, either in +unspent outputs (UTXOs) in the internal wallet or funds locked in +currently open channels. + +RETURN VALUE +============ + +On success two arrays will be returned: *outputs* with funds currently +locked onchain in UTXOs and *channels* with funds readily spendable in +channels. + +Each entry in *outputs* will include: + +- *txid* + +- *output* (the index of the output in the transaction) + +- *value* (the output value in satoshis) + +- *amount\_msat* (the same as *value*, but in millisatoshi with *msat* + appended) + +- *address* + +- *status* (whether *unconfirmed*, *confirmed*, or *spent*) + +Each entry in *channels* will include: + +- *peer\_id* - the peer with which the channel is opened. + +- *short\_channel\_id* - as per BOLT 7 (representing the block, + transaction number and output index of the channel funding + transaction). + +- *channel\_sat* - available satoshis on our node’s end of the channel + (values rounded down to satoshis as internal storage is in + millisatoshi). + +- *our\_amount\_msat* - same as above, but in millisatoshis with + *msat* appended. + +- *channel\_total\_sat* - total channel value in satoshi + +- *amount\_msat* - same as above, but in millisatoshis with *msat* + appended. + +- *funding\_txid* - funding transaction id. + +- *funding\_output* - the index of the output in the funding + transaction. + +AUTHOR +====== + +Felix <> is mainly responsible. + +SEE ALSO +======== + +lightning-newaddr(7), lightning-fundchannel(7), lightning-withdraw(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md new file mode 100644 index 000000000000..40993b495c06 --- /dev/null +++ b/doc/lightning-listinvoices.7.md @@ -0,0 +1,45 @@ +lightning-listinvoices + +7 + +lightning-listinvoices + +Command for querying invoice status + +**listinvoices** \[*label*\] + +DESCRIPTION +=========== + +The **listinvoices** RPC command gets the status of a specific invoice, +if it exists, or the status of all invoices if given no argument. + +RETURN VALUE +============ + +On success, an array *invoices* of objects is returned. Each object +contains *label*, *payment\_hash*, *status* (one of *unpaid*, *paid* or +*expired*), and *expiry\_time* (a UNIX timestamp). If the *msatoshi* +argument to lightning-invoice(7) was not "any", there will be an +*msatoshi* field as a number, and *amount\_msat* as the same number +ending in *msat*. If the invoice *status* is *paid*, there will be a +*pay\_index* field and an *msatoshi\_received* field (which may be +slightly greater than *msatoshi* as some overpaying is permitted to +allow clients to obscure payment paths); there will also be an +*amount\_received\_msat* field with the same number as +*msatoshi\_received* but ending in *msat*. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md new file mode 100644 index 000000000000..5db250a21db0 --- /dev/null +++ b/doc/lightning-listpays.7.md @@ -0,0 +1,64 @@ +lightning-listpays + +7 + +lightning-listpays + +Command for querying payment status + +**listpays** \[bolt11\] + +DESCRIPTION +=========== + +The **listpay** RPC command gets the status of all *pay* commands, or a +single one if *bolt11* is specified. + +RETURN VALUE +============ + +On success, an array of objects is returned. Each object contains: + +*bolt11* +the *bolt11* argument given to *pay* (see below for exceptions). + +*status* +one of *complete*, *failed* or *pending*. + +*payment\_preimage* +(if *status* is *complete*) proves payment was received. + +*label* +optional *label*, if provided to *pay*. + +*amount\_sent\_msat* +total amount sent, in "NNNmsat" format. + +For old payments (pre-0.7) we didn’t save the *bolt11* string, so in its +place are three other fields: + +*payment\_hash* +the hash of the *payment\_preimage* which will prove payment. + +*destination* +the final destination of the payment. + +*amount\_msat* +the amount the destination received, in "NNNmsat" format. + +These three can all be extracted from *bolt11*, hence are obsolete. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-pay(7), lightning-paystatus(7), lightning-listsendpays(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md new file mode 100644 index 000000000000..e7224219919c --- /dev/null +++ b/doc/lightning-listpeers.7.md @@ -0,0 +1,94 @@ +lightning-listpeers + +7 + +lightning-listpeers + +Command for returning data on connected lightning nodes. + +**listpeers** \[*id*\] \[*level*\] + +DESCRIPTION +=========== + +The **listpeers** RPC command returns data on nodes that are connected +or are not connected but have open channels with this node. + +Once a connection to another lightning node has been established, using +the **connect** command, data on the node can be returned using +**listpeers** and the *id* that was used with the **connect** command. + +If no *id* is supplied, then data on all lightning nodes that are +connected, or not connected but have open channels with this node, are +returned. + +Supplying *id* will filter the results to only return data on a node +with a matching *id*, if one exists. + +Supplying *level* will show log entries related to that peer at the +given log level. Valid log levels are "io", "debug", "info", and +"unusual". + +If a channel is open with a node and the connection has been lost, then +the node will still appear in the output of the command and the value of +the *connected* attribute of the node will be "false". + +The channel will remain open for a set blocktime, after which if the +connection has not been re-established, the channel will close and the +node will no longer appear in the command output. + +RETURN VALUE +============ + +On success, an object with a "peers" key is returned containing a list +of 0 or more objects. + +Each object in the list contains the following data: + +- *id* : The unique id of the peer + +- *connected* : A boolean value showing the connection status + +- *netaddr* : A list of network addresses the node is listening on + +- *globalfeatures* : Bit flags showing supported global features (BOLT + \#9) + +- *localfeatures* : Bit flags showing supported local features (BOLT + \#9) + +- *channels* : An list of channel id’s open on the peer + +- *log* : Only present if *level* is set. List logs related to the + peer at the specified *level* + +If *id* is supplied and no matching nodes are found, a "peers" object +with an empty list is returned. + +ERRORS +====== + +If *id* is not a valid public key, an error message will be returned: + + { "code" : -32602, "message" : "'id' should be a pubkey, not '...'" } + +If *level* is not a valid log level, an error message will be returned: + + { "code" : -32602, "message" "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" } + +AUTHOR +====== + +Michael Hawkins <>. + +SEE ALSO +======== + +lightning-connect(7) + +RESOURCES +========= + +Main web site: Lightning +RFC site (BOLT \#9): + diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md new file mode 100644 index 000000000000..07858629566f --- /dev/null +++ b/doc/lightning-listsendpays.7.md @@ -0,0 +1,69 @@ +lightning-listsendpays + +7 + +lightning-listsendpays + +Low-level command for querying sendpay status + +**listsendpays** \[*bolt11*\] \[*payment\_hash*\] + +DESCRIPTION +=========== + +The **listsendpays** RPC command gets the status of all *sendpay* +commands (which is also used by the *pay* command), or with *bolt11* or +*payment\_hash* limits results to that specific payment. You cannot +specify both. + +Note that in future there may be more than one concurrent *sendpay* +command per *pay*, so this command should be used with caution. + +RETURN VALUE +============ + +On success, an array of objects is returned. Each object contains: + +*id* +unique internal value assigned at creation + +*payment\_hash* +the hash of the *payment\_preimage* which will prove payment. + +*destination* +the final destination of the payment. + +*amount\_msat* +the amount the destination received, in "NNNmsat" format. + +*created\_at* +the UNIX timestamp showing when this payment was initiated. + +*status* +one of *complete*, *failed* or *pending*. + +*payment\_preimage* +(if *status* is *complete*) proves payment was received. + +*label* +optional *label*, if provided to *sendpay*. + +*bolt11* +the *bolt11* argument given to *pay* (may be missing for pre-0.7 +payments). + +AUTHOR +====== + +Christian Decker <> is mainly +responsible. + +SEE ALSO +======== + +lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-newaddr.7.md b/doc/lightning-newaddr.7.md new file mode 100644 index 000000000000..3bec7a4cb06e --- /dev/null +++ b/doc/lightning-newaddr.7.md @@ -0,0 +1,54 @@ +lightning-newaddr + +7 + +lightning-newaddr + +Command for generating a new address to be used by c-lightning. + +**newaddr** \[ *addresstype* \] + +DESCRIPTION +=========== + +The **newaddr** RPC command generates a new address which can +subsequently be used to fund channels managed by the c-lightning node. + +The funding transaction needs to be confirmed before funds can be used. + +*addresstype* specifies the type of address wanted; i.e. *p2sh-segwit* +(e.g. 2MxaozoqWwiUcuD9KKgUSrLFDafLqimT9Ta on bitcoin testnet or +3MZxzq3jBSKNQ2e7dzneo9hy4FvNzmMmt3 on bitcoin mainnet) or *bech32 ' +(e.g. tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg on bitcoin testnet or +bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej on +bitcoin mainnet). The special value 'all* generates both address types +for the same underlying key. + +If not specified the address generated is bech32. + +RETURN VALUE +============ + +On success, a *bech32* address and/or a *p2sh-segwit* address will be +returned. + +ERRORS +====== + +If an unrecognized address type is requested an error message will be +returned. + +AUTHOR +====== + +Felix <> is mainly responsible. + +SEE ALSO +======== + +lightning-listfunds(7), lightning-fundchannel(7), lightning-withdraw(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-pay.7.md b/doc/lightning-pay.7.md new file mode 100644 index 000000000000..f1bc371e6ec6 --- /dev/null +++ b/doc/lightning-pay.7.md @@ -0,0 +1,146 @@ +lightning-pay + +7 + +lightning-pay + +Command for sending a payment to a BOLT11 invoice + +**pay** *bolt11* \[*msatoshi*\] \[*label*\] \[*riskfactor*\] +\[*maxfeepercent*\] \[*retry\_for*\] \[*maxdelay*\] \[*exemptfee*\] + +DESCRIPTION +=========== + +The **pay** RPC command attempts to find a route to the given +destination, and send the funds it asks for. If the *bolt11* does not +contain an amount, *msatoshi* is required, otherwise if it is specified +it must be *null*. *msatoshi* is in millisatoshi precision; it can be a +whole number, or a whole number with suffix *msat* or *sat*, or a three +decimal point number with suffix *sat*, or an 1 to 11 decimal point +number suffixed by *btc*. + +The *label* field is used to attach a label to payments, and is returned +in lightning-listpays(7) and lightning-listsendpays(7). The *riskfactor* +is described in detail in lightning-getroute(7), and defaults to 10. The +*maxfeepercent* limits the money paid in fees, and defaults to 0.5. The +`` maxfeepercent' is a percentage of the amount that is to be +paid. +The `exemptfee `` option can be used for tiny payments which would be +dominated by the fee leveraged by forwarding nodes. Setting `exemptfee` +allows the `maxfeepercent` check to be skipped on fees that are smaller +than `exemptfee` (default: 5000 millisatoshi). + +The response will occur when the payment fails or succeeds. Once a +payment has succeeded, calls to **pay** with the same *bolt11* will +succeed immediately. + +Until *retry\_for* seconds passes (default: 60), the command will keep +finding routes and retrying the payment. However, a payment may be +delayed for up to `maxdelay` blocks by another node; clients should be +prepared for this worst case. + +When using *lightning-cli*, you may skip optional parameters by using +*null*. Alternatively, use **-k** option to provide parameters by name. + +RANDOMIZATION +============= + +To protect user privacy, the payment algorithm performs some +randomization. + +1. Route Randomization + +2. Shadow Route + +Route randomization means the payment algorithm does not always use the +lowest-fee or shortest route. This prevents some highly-connected node +from learning all of the user payments by reducing their fees below the +network average. + +Shadow route means the payment algorithm will virtually extend the time +delays along the route, making it appear to intermediate nodes that the +route is longer than it actually is. This prevents intermediate nodes +from reliably guessing their distance from the payee. + +Route randomization will never exceed *maxfeepercent* of the payment. +Route randomization and shadow routing will not take routes that would +exceed *maxdelay*. + +RETURN VALUE +============ + +On success, this returns the *payment\_preimage* which hashes to the +*payment\_hash* to prove that the payment was successful. It will also +return, a *getroute\_tries* and a *sendpay\_tries* statistics for the +number of times it internally called **getroute** and **sendpay**. + +You can monitor the progress and retries of a payment using the +lightning-paystatus(7) command. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 201. Already paid with this *hash* using different amount or + destination. + +- 203. Permanent failure at destination. The *data* field of the error + will be routing failure object. + +- 205. Unable to find a route. + +- 206. Route too expensive. Either the fee or the needed total + locktime for the route exceeds your *maxfeepercent* or *maxdelay* + settings, respectively. The *data* field of the error will indicate + the actual *fee* as well as the *feepercent* percentage that the fee + has of the destination payment amount. It will also indicate the + actual *delay* along the route. + +- 207. Invoice expired. Payment took too long before expiration, or + already expired at the time you initiated payment. The *data* field + of the error indicates *now* (the current time) and *expiry* (the + invoice expiration) as UNIX epoch time in seconds. + +- 210. Payment timed out without a payment in progress. + +Error codes 202 and 204 will only get reported at **sendpay**; in +**pay** we will keep retrying if we would have gotten those errors. + +A routing failure object has the fields below: + +- *erring\_index*. The index of the node along the route that reported + the error. 0 for the local node, 1 for the first hop, and so on. + +- *erring\_node*. The hex string of the pubkey id of the node that + reported the error. + +- *erring\_channel*. The short channel ID of the channel that has the + error, or *0:0:0* if the destination node raised the error. + +- *failcode*. The failure code, as per BOLT \#4. + +- *channel\_update*. The hex string of the *channel\_update* message + received from the remote node. Only present if error is from the + remote node and the *failcode* has the UPDATE bit set, as per BOLT + \#4. + +The *data* field of errors will include statistics *getroute\_tries* and +*sendpay\_tries*. It will also contain a *failures* field with detailed +data about routing errors. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-listpays(7), lightning-decodepay(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-getroute(7), lightning-invoice(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md new file mode 100644 index 000000000000..a43567c11bdf --- /dev/null +++ b/doc/lightning-plugin.7.md @@ -0,0 +1,50 @@ +lightning-plugin + +7 + +lightning-plugin + +Manage plugins with RPC + +**plugin** command \[parameter\] \[second\_parameter\] + +DESCRIPTION +=========== + +The **plugin** RPC command allows to manage plugins without having to +restart lightningd. It takes 1 to 3 parameters: a command +(start/stop/startdir/rescan/list) which describes the action to take and +optionally one or two parameters which describes the plugin on which the +action has to be taken. + +The *start* command takes a path as parameter and will load the plugin +available from this path. + +The *stop* command takes a plugin name as parameter and will kill and +unload the specified plugin. + +The *startdir* command takes a directory path as parameter and will load +all plugins this directory contains. + +The *rescan* command starts all not-already-loaded plugins from the +default plugins directory (by default *~/.lightning/plugins*). + +The *list* command will return all the active plugins. + +RETURN VALUE +============ + +On success, this returns an array *plugins* of objects, one by plugin. +Each object contains the name of the plugin (*name* field) and its +status (*active* boolean field). Since plugins are configured +asynchronously, a freshly started plugin may not appear immediately. + +AUTHOR +====== + +Antoine Poinsot <> is mainly responsible. + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-sendpay.7.md b/doc/lightning-sendpay.7.md new file mode 100644 index 000000000000..fcccdb97a0da --- /dev/null +++ b/doc/lightning-sendpay.7.md @@ -0,0 +1,114 @@ +lightning-sendpay + +7 + +lightning-sendpay + +Low-level command for sending a payment via a route. + +**sendpay** *route* *payment\_hash* \[*label*\] \[*msatoshi*\] +\[*bolt11*\] + +DESCRIPTION +=========== + +The **sendpay** RPC command attempts to send funds associated with the +given *payment\_hash*, along a route to the final destination in the +route. + +Generally, a client would call lightning-getroute(7) to resolve a route, +then use **sendpay** to send it. If it fails, it would call +lightning-getroute(7) again to retry. + +The response will occur when the payment is on its way to the +destination. The **sendpay** RPC command does not wait for definite +success or definite failure of the payment. Instead, use the +**waitsendpay** RPC command to poll or wait for definite success or +definite failure. + +The *label* and *bolt11* parameters, if provided, will be returned in +*waitsendpay* and *listsendpays* results. + +The *msatoshi* amount, if provided, is the amount that will be recorded +as the target payment value. If not specified, it will be the final +amount to the destination. If specified, then the final amount at the +destination must be from the specified *msatoshi* to twice the specified +*msatoshi*, inclusive. This is intended to obscure payments by +overpaying slightly at the destination; the actual target payment is +what should be specified as the *msatoshi* argument. *msatoshi* is in +millisatoshi precision; it can be a whole number, or a whole number +ending in *msat* or *sat*, or a number with three decimal places ending +in *sat*, or a number with 1 to 11 decimal places ending in *btc*. + +Once a payment has succeeded, calls to **sendpay** with the same +*payment\_hash* but a different *msatoshi* or destination will fail; +this prevents accidental multiple payments. Calls to **sendpay** with +the same *payment\_hash*, *msatoshi*, and destination as a previous +successful payment (even if a different route) will return immediately +with success. + +RETURN VALUE +============ + +On success, an object similar to the output of **listsendpays** will be +returned. This object will have a *status* field that is typically the +string *"pending"*, but may be *"complete"* if the payment was already +performed successfully. + +On error, if the error occurred from a node other than the final +destination, the route table will be updated so that +lightning-getroute(7) should return an alternate route (if any). An +error from the final destination implies the payment should not be +retried. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 201. Already paid with this *hash* using different amount or + destination. + +- 202. Unparseable onion reply. The *data* field of the error will + have an *onionreply* field, a hex string representation of the raw + onion reply. + +- 203. Permanent failure at destination. The *data* field of the error + will be routing failure object. + +- 204. Failure along route; retry a different route. The *data* field + of the error will be routing failure object. + +A routing failure object has the fields below: + +- *erring\_index*. The index of the node along the route that reported + the error. 0 for the local node, 1 for the first hop, and so on. + +- *erring\_node*. The hex string of the pubkey id of the node that + reported the error. + +- *erring\_channel*. The short channel ID of the channel that has the + error, or *0:0:0* if the destination node raised the error. + +- *failcode*. The failure code, as per BOLT \#4. + +- *channel\_update*. The hex string of the *channel\_update* message + received from the remote node. Only present if error is from the + remote node and the *failcode* has the UPDATE bit set, as per BOLT + \#4. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-invoice(7), lightning-pay(7), +lightning-waitsendpay(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-setchannelfee.7.md b/doc/lightning-setchannelfee.7.md new file mode 100644 index 000000000000..3c0df8802fc8 --- /dev/null +++ b/doc/lightning-setchannelfee.7.md @@ -0,0 +1,70 @@ +lightning-setchannelfee + +7 + +lightning-setchannelfee + +Command for setting specific routing fees on a lightning channel. + +**setchannelfee** *id* \[*base*\] \[*ppm*\] + +DESCRIPTION +=========== + +The **setchannelfee** RPC command sets channel specific routing fees as +defined in BOLT \#7. The channel has to be in normal or awaiting state. +This can be checked by **listpeers** reporting a *state* of +CHANNELD\_NORMAL or CHANNELD\_AWAITING\_LOCKIN for the channel. + +*id* is required and should contain a scid (short channel ID), channel +id or peerid (pubkey) of the channel to be modified. If *id* is set to +"all", the fees for all channels are updated that are in state +CHANNELD\_NORMAL or CHANNELD\_AWAITING\_LOCKIN. + +*base* is an optional value in millisatoshi that is added as base fee to +any routed payment. If the parameter is left out, the global config +value fee-base will be used again. It can be a whole number, or a whole +number ending in *msat* or *sat*, or a number with three decimal places +ending in *sat*, or a number with 1 to 11 decimal places ending in +*btc*. + +*ppm* is an optional value that is added proportionally per-millionths +to any routed payment volume in satoshi. For example, if ppm is 1,000 +and 1,000,000 satoshi is being routed trhough the channel, an +proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee. If +the parameter is left out, the global config value will be used again. + +RETURN VALUE +============ + +On success, an object with the new values *base* and *ppm* along with an +array *channels* which contains objects with fields *peer\_id*, +*channel\_id* and *short\_channel\_id*. + +ERRORS +====== + +The following error codes may occur: + +- -1. Channel is in incorrect state, i.e. Catchall nonspecific error. + +- -32602. JSONRPC2\_INVALID\_PARAMS, i.e. Given id is not a channel ID + or short channel ID. + +AUTHOR +====== + +Michael Schmoock <> is the author of this +feature. Rusty Russell <> is mainly +responsible for the c-lightning project. + +SEE ALSO +======== + +lightningd-config(5), lightning-fundchannel(7), +lightning-listchannels(7), lightning-listpeers(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-txdiscard.7.md b/doc/lightning-txdiscard.7.md new file mode 100644 index 000000000000..cf0104e24786 --- /dev/null +++ b/doc/lightning-txdiscard.7.md @@ -0,0 +1,45 @@ +lightning-txdiscard + +7 + +lightning-txdiscard + +Abandon a transaction from txprepare, release inputs + +**txdiscard** *txid* + +DESCRIPTION +=========== + +The **txdiscard** RPC command releases inputs which were reserved for +use of the *txid* from lightning-txprepare(7). + +RETURN VALUE +============ + +On success, an object with attributes *unsigned\_tx* and *txid* will be +returned, exactly as from lightning-txprepare(7). + +If there is no matching *txid*, an error is reported. Note that this may +happen due to incorrect usage (such as **txdiscard** or **txsend** +already being called for *txid*) or due to lightningd restarting, which +implicitly calls **txdiscard** on all outputs. + +The following error codes may occur: + +- -1. An unknown *txid*. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-txprepare(7), lightning-txsend(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-txprepare.7.md b/doc/lightning-txprepare.7.md new file mode 100644 index 000000000000..aa9dba588f29 --- /dev/null +++ b/doc/lightning-txprepare.7.md @@ -0,0 +1,56 @@ +lightning-txprepare + +7 + +lightning-txprepare + +Command to prepare to withdraw funds from the internal wallet. + +**txprepare** *destination* *satoshi* \[*feerate*\] \[*minconf*\] + +DESCRIPTION +=========== + +The **txprepare** RPC command creates an unsigned transaction which +spends funds from c-lightning’s internal wallet to the address specified +in *destination*. + +Effectively, it is the first part of a **withdraw** command, and uses +the same parameters. The second part is provided by **txsend**. + +RETURN VALUE +============ + +On success, an object with attributes *unsigned\_tx* and *txid* will be +returned. You need to hand *txid* to **txsend** or **txdiscard**, as the +inputs of this transaction are reserved until then, or until the daemon +restarts. + +*unsigned\_tx* represents the raw bitcoin transaction (not yet signed) +and *txid* represent the bitcoin transaction id. + +On failure, an error is reported and the transaction is not created. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 301. There are not enough funds in the internal wallet (including + fees) to create the transaction. + +- 302. The dust limit is not met. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-txsend.7.md b/doc/lightning-txsend.7.md new file mode 100644 index 000000000000..0e918358daa8 --- /dev/null +++ b/doc/lightning-txsend.7.md @@ -0,0 +1,45 @@ +lightning-txsend + +7 + +lightning-txsend + +Command to sign and send transaction from txprepare + +**txsend** *txid* + +DESCRIPTION +=========== + +The **txsend** RPC command signs and broadcasts a transaction created by +**txprepare**. + +RETURN VALUE +============ + +On success, an object with attributes *tx* and *txid* will be returned. + +*tx* represents the fully signed raw bitcoin transaction, and *txid* is +the same as the *txid* argument. + +On failure, an error is reported (from bitcoind), and the inputs from +the transaction are unreserved. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-txprepare(7), lightning-txdiscard(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-waitanyinvoice.7.md b/doc/lightning-waitanyinvoice.7.md new file mode 100644 index 000000000000..264c54620e37 --- /dev/null +++ b/doc/lightning-waitanyinvoice.7.md @@ -0,0 +1,47 @@ +lightning-waitanyinvoice + +7 + +lightning-waitanyinvoice + +Command for waiting for payments. + +**waitanyinvoice** \[*lastpay\_index*\] + +DESCRIPTION +=========== + +The **waitanyinvoice** RPC command waits until an invoice is paid, then +returns a single entry as per **listinvoice**. It will not return for +any invoices paid prior to or including the *lastpay\_index*. + +This is usually called iteratively: once with no arguments, then +repeatedly with the returned *pay\_index* entry. This ensures that no +paid invoice is missed. + +The *pay\_index* is a monotonically-increasing number assigned to an +invoice when it gets paid. The first valid *pay\_index* is 1; specifying +*lastpay\_index* of 0 equivalent to not specifying a *lastpay\_index*. +Negative *lastpay\_index* is invalid. + +RETURN VALUE +============ + +On success, an invoice description will be returned as per +lightning-listinvoice(7): *complete* will always be *true*. + +AUTHOR +====== + +Rusty Russell <> is mainly responsible. + +SEE ALSO +======== + +lightning-waitinvoice(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-waitinvoice.7.md b/doc/lightning-waitinvoice.7.md new file mode 100644 index 000000000000..75a3a6bc28e8 --- /dev/null +++ b/doc/lightning-waitinvoice.7.md @@ -0,0 +1,45 @@ +lightning-waitinvoice + +7 + +lightning-waitinvoice + +Command for waiting for specific payment. + +**waitinvoice** *label* + +DESCRIPTION +=========== + +The **waitinvoice** RPC command waits until a specific invoice is paid, +then returns that single entry as per **listinvoice**. + +RETURN VALUE +============ + +On success, an invoice description will be returned as per +lightning-listinvoice(7). The *status* field will be *paid*. + +If the invoice is deleted while unpaid, or the invoice does not exist, +this command will return with an error with code -1. + +If the invoice expires before being paid, or is already expired, this +command will return with an error with code -2, with the data being the +invoice data as per **listinvoice**. + +AUTHOR +====== + +Christian Decker <> is mainly +responsible. + +SEE ALSO +======== + +lightning-waitanyinvoice(7), lightning-listinvoice(7), +lightning-delinvoice(7), lightning-invoice(7) + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-waitsendpay.7.md b/doc/lightning-waitsendpay.7.md new file mode 100644 index 000000000000..15ad79ee699c --- /dev/null +++ b/doc/lightning-waitsendpay.7.md @@ -0,0 +1,99 @@ +lightning-waitsendpay + +7 + +lightning-waitsendpay + +Command for sending a payment via a route. + +**waitsendpay** *payment\_hash* \[*timeout*\] + +DESCRIPTION +=========== + +The **waitsendpay** RPC command polls or waits for the status of an +outgoing payment that was initiated by a previous **sendpay** +invocation. + +Optionally the client may provide a *timeout*, an integer in seconds, +for this RPC command to return. If the *timeout* is provided and the +given amount of time passes without the payment definitely succeeding or +definitely failing, this command returns with a 200 error code (payment +still in progress). If *timeout* is not provided this call will wait +indefinitely. + +Indicating a *timeout* of 0 effectively makes this call a pollable query +of the status of the payment. + +If the payment completed with success, this command returns with +success. Otherwise, if the payment completed with failure, this command +returns an error. + +RETURN VALUE +============ + +On success, an object similar to the output of **listsendpays** will be +returned. This object will have a *status* field that is the string +*"complete"*. + +On error, and even if the error occurred from a node other than the +final destination, the route table will no longer be updated. Use the +*exclude* parameter of the `getroute` command to ignore the failing +route. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 200. Timed out before the payment could complete. + +- 202. Unparseable onion reply. The *data* field of the error will + have an *onionreply* field, a hex string representation of the raw + onion reply. + +- 203. Permanent failure at destination. The *data* field of the error + will be routing failure object. + +- 204. Failure along route; retry a different route. The *data* field + of the error will be routing failure object. + +- 208. A payment for *payment\_hash* was never made and there is + nothing to wait for. + +- 209. The payment already failed, but the reason for failure was not + stored. This should only occur when querying failed payments on very + old databases. + +A routing failure object has the fields below: + +- *erring\_index*. The index of the node along the route that reported + the error. 0 for the local node, 1 for the first hop, and so on. + +- *erring\_node*. The hex string of the pubkey id of the node that + reported the error. + +- *erring\_channel*. The short channel ID of the channel that has the + error (or the final channel if the destination raised the error). + +- *erring\_direction*. The direction of traversing the + *erring\_channel*. + +- *failcode*. The failure code, as per BOLT \#4. + +- *failcodename*. The human-readable name corresponding to *failcode*, + if known. + +AUTHOR +====== + +ZmnSCPxj <> is mainly responsible. + +SEE ALSO +======== + +lightning-sendpay(7), lightning-pay(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightning-withdraw.7.md b/doc/lightning-withdraw.7.md new file mode 100644 index 000000000000..3c7b3f40d2ca --- /dev/null +++ b/doc/lightning-withdraw.7.md @@ -0,0 +1,73 @@ +lightning-withdraw + +7 + +lightning-withdraw + +Command for withdrawing funds from the internal wallet. + +**withdraw** *destination* *satoshi* \[*feerate*\] \[*minconf*\] + +DESCRIPTION +=========== + +The **withdraw** RPC command sends funds from c-lightning’s internal +wallet to the address specified in *destination*. + +The address can be of any Bitcoin accepted type, including bech32. + +*satoshi* is the amount to be withdrawn from the internal wallet +(expressed, as name suggests, in satoshi). The string *all* can be used +to specify withdrawal of all available funds. Otherwise, it is in +satoshi precision; it can be a whole number, a whole number ending in +*sat*, a whole number ending in *000msat*, or a number with 1 to 8 +decimal places ending in *btc*. + +*feerate* is an optional feerate to use. It can be one of the strings +*urgent* (aim for next block), *normal* (next 4 blocks or so) or *slow* +(next 100 blocks or so) to use lightningd’s internal estimates: *normal* +is the default. + +Otherwise, *feerate* is a number, with an optional suffix: *perkw* means +the number is interpreted as satoshi-per-kilosipa (weight), and *perkb* +means it is interpreted bitcoind-style as satoshi-per-kilobyte. Omitting +the suffix is equivalent to *perkb*. + +*minconf* specifies the minimum number of confirmations that used +outputs should have. Default is 1. + +RETURN VALUE +============ + +On success, an object with attributes *tx* and *txid* will be returned. + +*tx* represents the raw bitcoin, fully signed, transaction and *txid* +represent the bitcoin transaction id. + +On failure, an error is reported and the withdrawal transaction is not +created. + +The following error codes may occur: + +- -1. Catchall nonspecific error. + +- 301. There are not enough funds in the internal wallet (including + fees) to create the transaction. + +- 302. The dust limit is not met. + +AUTHOR +====== + +Felix <> is mainly responsible. + +SEE ALSO +======== + +lightning-listfunds(7), lightning-fundchannel(7), lightning-newaddr(7), +lightning-txprepare(7). + +RESOURCES +========= + +Main web site: diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md new file mode 100644 index 000000000000..2a738b21df0d --- /dev/null +++ b/doc/lightningd-config.5.md @@ -0,0 +1,375 @@ +lightningd-config + +5 + +lightningd-config + +Lightning daemon configuration file + +**~/.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(1) 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 +------------------------------------ + +**rgb**=*RRGGBB* +Your favorite color as a hex code. + +**alias**=*NAME* +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 +lightningd-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 lightningd-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. + +**cltv-delta**=*BLOCKS* +The number of blocks between incoming payments and outgoing payments: +this needs to be enough to make sure that if we have to, we can close +the outgoing payment before the incoming, or redeem the incoming once +the outgoing is redeemed. + +**cltv-final**=*BLOCKS* +The number of blocks to allow for payments we receive: if we have to, we +might need to redeem this on-chain, so this is the number of blocks we +have to do that. + +Invoice control options: + +**autocleaninvoice-cycle**=*SECONDS* +Perform cleanup of expired invoices every *SECONDS* seconds, or disable +if 0. Usually unpaid expired invoices are uninteresting, and just take +up space in the database. + +**autocleaninvoice-expired-by**=*SECONDS* +Control how long invoices must have been expired before they are cleaned +(if *autocleaninvoice-cycle* is non-zero). + +Networking options +------------------ + +Note that for simple setups, the implicit *autolisten* option does the +right thing: it will try to bind to port 9735 on IPv4 and IPv6, and will +announce it to peers if it seems like a public address. + +You can instead use *addr* to override this (eg. to change the port), or +precisely control where to bind and what to announce with the +*bind-addr* and *announce-addr* options. These will **disable** the +*autolisten* logic, so you must specifiy exactly what you want! + +**addr**=*\[IPADDRESS\[:PORT\]\]|autotor:TORIPADDRESS\[:TORPORT\]* +Set an IP address (v4 or v6) or automatic Tor address to listen on and +(maybe) announce as our node address. + + An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or + IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 + interfaces, '::' means 'bind to all IPv6 interfaces'. If 'PORT' is + not specified, 9735 is used. If we can determine a public IP + address from the resulting binding, and no other addresses of the + same type are already announced, the address is announced. + + If the argument begins with 'autotor:' then it is followed by the + IPv4 or IPv6 address of the Tor control port (default port 9051), + and this will be used to configure a Tor hidden service for port + 9735. The Tor hidden service will be configured to point to the + first IPv4 or IPv6 address we bind to. + + This option can be used multiple times to add more addresses, and + its use disables autolisten. If necessary, and 'always-use-proxy' + is not specified, a DNS lookup may be done to resolve 'IPADDRESS' + or 'TORIPADDRESS'. + +**bind-addr**=*\[IPADDRESS\[:PORT\]\]|SOCKETPATH* +Set an IP address or UNIX domain socket to listen to, but do not +announce. A UNIX domain socket is distinguished from an IP address by +beginning with a */*. + + An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or + IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 + interfaces, '::' means 'bind to all IPv6 interfaces'. 'PORT' is + not specified, 9735 is used. + + This option can be used multiple times to add more addresses, and + its use disables autolisten. If necessary, and 'always-use-proxy' + is not specified, a DNS lookup may be done to resolve 'IPADDRESS'. + +**announce-addr**=*IPADDRESS\[:PORT\]|TORADDRESS.onion\[:PORT\]* +Set an IP (v4 or v6) address or Tor address to announce; a Tor address +is distinguished by ending in *.onion*. *PORT* defaults to 9735. + + Empty or wildcard IPv4 and IPv6 addresses don't make sense here. + Also, unlike the 'addr' option, there is no checking that your + announced addresses are public (e.g. not localhost). + + This option can be used multiple times to add more addresses, and + its use disables autolisten. The spec says you can't announce + more that one address of the same type (eg. two IPv4 or two IPv6 + addresses) so `lightningd` will refuse if you specify more than one. + + If necessary, and 'always-use-proxy' is not specified, a DNS + lookup may be done to resolve 'IPADDRESS'. + +**offline** +Do not bind to any ports, and do not try to reconnect to any peers. This +can be useful for maintenance and forensics, so is usually specified on +the command line. Overrides all *addr* and *bind-addr* options. + +**autolisten**=*BOOL* +By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if +no *addr*, *bind-addr* or *announce-addr* options are specified. Setting +this to *false* disables that. + +**proxy**=*IPADDRESS\[:PORT\]* +Set a socks proxy to use to connect to Tor nodes (or for all connections +if **always-use-proxy** is set). + +**always-use-proxy**=*BOOL* +Always use the **proxy**, even to connect to normal IP addresses (you +can still connect to Unix domain sockets manually). This also disables +all DNS lookups, to avoid leaking information. + +**disable-dns** +Disable the DNS bootstrapping mechanism to find a node by its node ID. + +**tor-service-password**=*PASSWORD* +Set a Tor control password, which may be needed for *autotor:* to +authenticate to the Tor control port. + +Lightning Plugins +----------------- + +lightningd(8) supports plugins, which offer additional configuration +options and JSON-RPC methods, depending on the plugin. Some are supplied +by default (usually located in **libexec/c-lightning/plugins/**). If a +**plugins** directory exists under *lightning-dir* that is searched for +plugins along with any immediate subdirectories). You can specify +additional paths too: + +**plugin**=*PATH* +Specify a plugin to run as part of c-lightning. This can be specified +multiple times to add multiple plugins. + +**plugin-dir**=*DIRECTORY* +Specify a directory to look for plugins; all executable files not +containing punctuation (other than *.*, *-* or *\_) in 'DIRECTORY* are +loaded. *DIRECTORY* must exist; this can be specified multiple times to +add multiple directories. + +**clear-plugins** +This option clears all *plugin* and *plugin-dir* options preceeding it, +including the default built-in plugin directory. You can still add +*plugin-dir* and *plugin* options following this and they will have the +normal effect. + +**disable-plugin**=*PLUGIN* +If *PLUGIN* contains a /, plugins with the same path as *PLUGIN* are +disabled. Otherwise, any plugin with that base name is disabled, +whatever directory it is in. + +BUGS +==== + +You should report bugs on our github issues page, and maybe submit a fix +to gain our eternal gratitude! + +AUTHOR +====== + +Rusty Russell <> wrote this man page, and +much of the configuration language, but many others did the hard work of +actually implementing these options. + +SEE ALSO +======== + +lightning-listconfigs(7) lightningd-setchannelfee(7) + +RESOURCES +========= + +Main web site: + +COPYING +======= + +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. diff --git a/tools/manpage2md.sh b/tools/manpage2md.sh new file mode 100755 index 000000000000..700d9a70a52d --- /dev/null +++ b/tools/manpage2md.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env sh +set -e + +MANPAGES=$(ls doc/*.[0-9].txt | sed 's/\.txt$//') +# If there are md manpages not on the readthedoc rst yet +NEW_PAGES="\\n\\n" + +for m in $MANPAGES; do + asciidoc -b docbook "$m.txt" + pandoc -f docbook -t markdown_strict "$m.xml" -o "$m.md" + # We don't care about docbook files + rm "$m.xml" + grep "$m.md" doc/index.rst || NEW_PAGES="$NEW_PAGES $(echo "$m".md | sed 's/\//\\\//')\\n" + cat doc/index.rst +done + +if [ ! "$NEW_PAGES" = "\\n\\n" ]; then + sed -i "s/:caption: Manpages/:caption: Manpages$NEW_PAGES/" doc/index.rst +fi