mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-20 13:54:36 +01:00
Code Issues Projects Releases Wiki Activity

doc: Markdown cleanup

Browse source 
This commit will remove parameter descriptions from RPC markdown but we will fix it in next commits by reading these descriptions directly from json.

- Removing parameter description text
- Adding/removing newlines for cleaner formatting
- Adding ERRORS title wherever needed
- Updating titles for consistency
- Adding resources links
This commit is contained in:
ShahanaFarooqui 2024-02-02 15:20:25 +10:30 • committed by Rusty Russell
parent fdc2dbdbc3
commit b0da807700
113 changed files with 355 additions and 1403 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
doc/lightning-addpsbtoutput.7.md
View file

@ -15,19 +15,6 @@ by adding a single output of amount *satoshi*.
This is used to receive funds into the on-chain wallet interactively
using PSBTs.
*satoshi* is the satoshi value of the output. 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*.
*initialpsbt* is a PSBT to add the output to. If not speciifed, a PSBT
will be created automatically.
*locktime* is an optional locktime: if not set, it is set to a recent
block height (if no initial psbt is specified).
If *destination* is not set, an internal address is generated.
EXAMPLE USAGE
-------------
@ -53,7 +40,7 @@ On success, an object is returned, containing:
AUTHOR
------
@dusty\_daemon
Dusty <<@dusty_daemon>> is mainly responsible.
SEE ALSO
--------

11
doc/lightning-autoclean-once.7.md
View file

@ -14,17 +14,6 @@ single sweep to delete old entries. This is a manual alternative (or
addition) to the various `autoclean-...-age` parameters which
cause autoclean to run once per hour: see lightningd-config(5).
The *subsystem*s currently supported are:
* `failedforwards`: routed payments which did not succeed (`failed` or `local_failed` in listforwards `status`).
* `succeededforwards`: routed payments which succeeded (`settled` in listforwards `status`).
* `failedpays`: payment attempts which did not succeed (`failed` in listpays `status`).
* `succededpays`: payment attempts which succeeded (`complete` in listpays `status`).
* `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`).
* `paidinvoices`: invoices which were paid (`paid` in listinvoices `status).
*age* is a non-zero number in seconds.
RETURN VALUE
------------

9
doc/lightning-autoclean-status.7.md
View file

@ -12,15 +12,6 @@ DESCRIPTION
The **autoclean-status** RPC command tells you about the status of
the autclean plugin, optionally for only one subsystem.
The subsystems currently supported are:
* `failedforwards`: routed payments which did not succeed (`failed` or `local_failed` in listforwards `status`).
* `succeededforwards`: routed payments which succeeded (`settled` in listforwards `status`).
* `failedpays`: payment attempts which did not succeed (`failed` in listpays `status`).
* `succededpays`: payment attempts which succeeded (`complete` in listpays `status`).
* `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`).
* `paidinvoices`: invoices which were paid (`paid` in listinvoices `status).
RETURN VALUE
------------

7
doc/lightning-batching.7.md
View file

@ -16,11 +16,9 @@ which case it can offer a performance improvement (the cost being that if
there is a crash, it's unclear how many of the commands will have been
persisted).
*enable* is *true* to enable batching, *false* to disable it (the
default).
EXAMPLE JSON REQUEST
--------------------
```json
{
"id": 82,
@ -39,6 +37,9 @@ On success, an empty object is returned.
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.

5
doc/lightning-bkpr-channelsapy.7.md
View file

@ -12,11 +12,6 @@ DESCRIPTION
The **bkpr-channelsapy** RPC command lists stats on routing income, leasing income,
and various calculated APYs for channel routed funds.
The **start\_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end\_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------

17
doc/lightning-bkpr-dumpincomecsv.7.md
View file

@ -12,23 +12,6 @@ DESCRIPTION
The **bkpr-dumpincomcsv** RPC command writes a CSV file to disk at *csv\_file*
location. This is a formatted output of the **listincome** RPC command.
**csv\_format** is which CSV format to use. See RETURN VALUE for options.
**csv\_file** is the on-disk destination of the generated CSV file.
If **consolidate\_fees** is true, we emit a single, consolidated event for
any onchain-fees for a txid and account. Otherwise, events for every update to
the onchain fee calculation for this account and txid will be printed.
Defaults to true. Note that this means that the events emitted are
non-stable, i.e. calling **dumpincomecsv** twice may result in different
onchain fee events being emitted, depending on how much information we've
logged for that transaction.
The **start\_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end\_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------

1
doc/lightning-bkpr-listaccountevents.7.md
View file

@ -18,7 +18,6 @@ Note that the type **onchain\_fees** that are emitted are of opposite credit/deb
produce the same list of events -- no previously emitted event will be
subsequently updated, rather we add a new event to the list.
RETURN VALUE
------------

6
doc/lightning-bkpr-listbalances.7.md
View file

@ -9,11 +9,9 @@ SYNOPSIS
DESCRIPTION
-----------
The **bkpr-listbalances** RPC command is a list of all current and historical account balances. An account is either the on-chain *wallet* or a channel balance.
Any funds sent to an *external* account will not be accounted for here.
The **bkpr-listbalances** RPC command is a list of all current and historical account balances. An account is either the on-chain *wallet* or a channel balance. Any funds sent to an *external* account will not be accounted for here.
Note that any channel that was recorded will be listed. Closed channel balances
will be 0msat.
Note that any channel that was recorded will be listed. Closed channel balances will be 0msat.
RETURN VALUE
------------

11
doc/lightning-bkpr-listincome.7.md
View file

@ -11,17 +11,6 @@ DESCRIPTION
The **bkpr-listincome** RPC command is a list of all income impacting events that the bookkeeper plugin has recorded for this node.
If **consolidate\_fees** is true, we emit a single, consolidated event for
any onchain-fees for a txid and account. Otherwise, events for every update to
the onchain fee calculation for this account and txid will be printed. Defaults to true. Note that this means that the events emitted are non-stable,
i.e. calling **listincome** twice may result in different onchain fee events
being emitted, depending on how much information we've logged for that
transaction.
The **start\_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end\_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------

4
doc/lightning-check.7.md
View file

@ -12,10 +12,6 @@ DESCRIPTION
The **check** RPC command verifies another command without actually
making any changes.
The *command\_to\_check* is the name of the relevant command.
*parameters* is the command's parameters.
This is guaranteed to be safe, and will do all checks up to the point
where something in the system would need to be altered (such as checking
that channels are in the right state, peers connected, etc).

15
doc/lightning-checkmessage.7.md
View file

@ -17,14 +17,9 @@ secret).
As a special case, if *pubkey* is not specified, we will try every
known node key (as per *listnodes*), and verification succeeds if it
matches for any one of them. Note: this is implemented far more
matches for any one of them. Note: this is implemented far more
efficiently than trying each one, so performance is not a concern.
On failure, an error is returned and core lightning exit with the following error code:
- -32602: Parameter missed or malformed;
- 1301: *pubkey* not found in the graph.
RETURN VALUE
------------
@ -36,6 +31,14 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned and core lightning exit with the following error code:
- -32602: Parameter missed or malformed;
- 1301: *pubkey* not found in the graph.
AUTHOR
------

7
doc/lightning-checkrune.7.md
View file

@ -25,6 +25,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- RUNE\_NOT\_AUTHORIZED (1501): rune is not for this node (or perhaps completely invalid)
@ -34,8 +37,7 @@ The following error codes may occur:
AUTHOR
------
Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible
for consolidating logic from commando.
Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible for consolidating logic from commando.
SEE ALSO
--------
@ -46,4 +48,5 @@ RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:72ed36d7c47cf43b39c149da7d251c8bd40531b59591a50c4745f5d7aef5854e)

4
doc/lightning-cli.1.md
View file

@ -117,8 +117,8 @@ raw JSON and are passed through. Other arguments are treated as strings.
Some commands have optional arguments. You may use *null* to skip
optional arguments to provide later arguments, although this is not encouraged.
EXAMPLES
--------
EXAMPLE USAGE
-------------
1. List commands:

63
doc/lightning-close.7.md
View file

@ -4,7 +4,7 @@ lightning-close -- Command for closing channels with direct peers
SYNOPSIS
--------
**close** *id* [*unilateraltimeout*] [*destination*] [*fee\_negotiation\_step*] [*wrong\_funding*] [*force\_lease\_closed*] [\*feerange\*]
**close** *id* [*unilateraltimeout*] [*destination*] [*fee\_negotiation\_step*] [*wrong\_funding*] [*force\_lease\_closed*] [*feerange*]
DESCRIPTION
-----------
@ -13,66 +13,6 @@ The **close** RPC command attempts to close the channel cooperatively
with the peer, or unilaterally after *unilateraltimeout*, and the
to-local output will be sent to the address specified in *destination*.
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 *destination* can be of any Bitcoin bech32 type.
If it isn't specified, the default is a Core Lightning wallet address. If
the peer hasn't offered the `option_shutdown_anysegwit` feature, then
taproot addresses (or other v1+ segwit) are not allowed. Tell your
friends to upgrade!
The *fee\_negotiation\_step* parameter controls how closing fee
negotiation is performed assuming the peer proposes a fee that is
different than our estimate. (Note that modern peers use the quick-close protocol which does not allow negotiation: see *feerange* instead).
On every negotiation step we must give up
some amount from our proposal towards the peer's proposal. This parameter
can be an integer in which case it is interpreted as number of satoshis
to step at a time. Or it can be an integer followed by "%" to designate
a percentage of the interval to give up. A few examples, assuming the peer
proposes a closing fee of 3000 satoshi and our estimate shows it must be 4000:
- "10": our next proposal will be 4000-10=3990.
- "10%": our next proposal will be 4000-(10% of (4000-3000))=3900.
- "1": our next proposal will be 3999. This is the most extreme case when we
insist on our fee as much as possible.
- "100%": our next proposal will be 3000. This is the most relaxed case when
we quickly accept the peer's proposal.
The default is "50%".
*wrong\_funding* can only be specified if both sides have offered
the "shutdown\_wrong\_funding" feature (enabled by the
**experimental-shutdown-wrong-funding** option): it must be a
transaction id followed by a colon then the output number. Instead of
negotiating a shutdown to spend the expected funding transaction, the
shutdown transaction will spend this output instead. This is only
allowed if this peer opened the channel and the channel is unused: it
can rescue openings which have been manually miscreated.
*force\_lease\_closed* if the channel has funds leased to the peer
(option\_will\_fund), we prevent initiation of a mutual close
unless this flag is passed in. Defaults to false.
*feerange* is an optional array [ *min*, *max* ], indicating the
minimum and maximum feerates to offer: the peer will obey these if it
supports the quick-close protocol. *slow* and *unilateral\_close* are
the defaults. See NOTES in lightning-feerates(7) for possible values.
Note that the maximum fee will be capped at the final commitment
transaction fee (unless the experimental anchor-outputs option is
negotiated).
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.
@ -88,6 +28,7 @@ closed if the peer reconnected.
NOTIFICATIONS
-------------
Notifications may be returned indicating what is going on, especially
if the peer is offline and we are waiting.

4
doc/lightning-commando-rune.7.md
View file

@ -58,8 +58,8 @@ to form valid JSON:
* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.
Every other operator except `#` fails if *name* does not exist!
EXAMPLES
--------
EXAMPLE USAGE
-------------
This creates a fresh rune which can do anything:

3
doc/lightning-commando.7.md
View file

@ -20,6 +20,9 @@ RETURN VALUE
On success, the return depends on the *method* invoked.
ERRORS
------
On failure, one of the following error codes may be returned:
- -32600: Usually means peer is not connected

25
doc/lightning-connect.7.md
View file

@ -12,31 +12,6 @@ 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* depends on the current network:
- bitcoin **mainnet**: 9735.
- bitcoin **testnet**: 19735.
- bitcoin **signet**: 39735.
- bitcoin **regtest**: 19846.
If *host* is not specified (or doesn't work), the connection will be attempted to an IP
belonging to *id* obtained through gossip with other already connected
peers.
This can fail if your C-lightning node is a fresh install that has not
connected to any peers yet (your node has no gossip yet),
or if the target *id* is a fresh install that has no channels yet
(nobody will gossip about a node until it has one published channel).
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).

16
doc/lightning-createinvoice.7.md
View file

@ -12,19 +12,6 @@ DESCRIPTION
The **createinvoice** RPC command signs and saves an invoice into the
database.
The *invstring* parameter is of bolt11 form, but the final signature
is ignored. Minimal sanity checks are done. (Note: if
**experimental-offers** is enabled, *invstring* can actually be an
unsigned bolt12 invoice).
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 *preimage* is the preimage to supply upon successful payment of
the invoice.
RETURN VALUE
------------
@ -54,6 +41,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned and no invoice is created. If the
lightning process fails before responding, the caller should use
lightning-listinvoices(7) to query whether this invoice was created or

30
doc/lightning-createonion.7.md
View file

@ -13,8 +13,11 @@ The **createonion** RPC command allows the caller to create a custom onion
with custom payloads at each hop in the route. A custom onion can be used to
implement protocol extensions that are not supported by Core Lightning directly.
The *hops* parameter is a JSON list of dicts, each specifying a node and the
payload destined for that node. The following is an example of a 3 hop onion:
EXAMPLE USAGE
-------------
The following is an example of a 3 hop onion:
```json
[
@ -68,22 +71,7 @@ which the above *hops* parameter was generated:
payload in `createonion` corresponds to the 2nd set of values from `getroute`.
- The final payload is a copy of the last payload sans `channel`
These rules are directly derived from the onion construction. Please refer
[BOLT 04](https://github.com/lightning/bolts/blob/master/04-onion-routing.md) for details and rationale.
The *assocdata* parameter specifies the associated data that the onion should
commit to. If the onion is to be used to send a payment later it MUST match
the `payment_hash` of the payment in order to be valid.
The optional *session\_key* parameter can be used to specify a secret that is
used to generate the shared secrets used to encrypt the onion for each hop. It
should only be used for testing or if a specific shared secret is
important. If not specified it will be securely generated internally, and the
shared secrets will be returned.
The optional *onion\_size* parameter specifies a size different from the default
payment onion (1300 bytes). May be used for custom protocols like trampoline
routing.
These rules are directly derived from the onion construction. Please refer BOLT 04 for details and rationale.
RETURN VALUE
------------
@ -97,8 +85,8 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
EXAMPLE
-------
EXAMPLE JSON RESPONSE
---------------------
The following example is the result of calling *createonion* with the
above hops parameter:
@ -132,4 +120,6 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[BOLT 04](https://github.com/lightning/bolts/blob/master/04-onion-routing.md)
[comment]: # ( SHA256STAMP:faac7539bd94fe5e561350f36002895ad2f3d4539f8bb4688027b6a81ec6f70c)

4
doc/lightning-createrune.7.md
View file

@ -62,8 +62,8 @@ to form valid JSON:
* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.
Every other operator except `#` fails if *name* does not exist!
EXAMPLES
--------
EXAMPLE USAGE
-------------
This creates a fresh rune which can do anything:

20
doc/lightning-datastore.7.md
View file

@ -12,23 +12,6 @@ DESCRIPTION
The **datastore** RPC command allows plugins to store data in the
Core Lightning database, for later retrieval.
*key* is an array of values (though a single value is treated as a
one-element array), to form a hierarchy. Using the first element of
the key as the plugin name (e.g. `[ "summary" ]`) is recommended.
A key can either have children or a value, never both: parents are
created and removed automatically.
*mode* is one of "must-create" (default, fails if it already exists),
"must-replace" (fails if it doesn't already exist),
"create-or-replace" (never fails), "must-append" (must already exist,
append this to what's already there) or "create-or-append" (append if
anything is there, otherwise create).
*generation*, if specified, means that the update will fail if the
previously-existing data is not exactly that generation. This allows
for simple atomicity. This is only legal with *mode* "must-replace"
or "must-append".
RETURN VALUE
------------
@ -43,6 +26,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- 1202: The key already exists (and mode said it must not)

1
doc/lightning-datastoreusage.7.md
View file

@ -14,6 +14,7 @@ total bytes that are stored under a certain *key* (or from the root),
including the size of the *key*.
All descendants of the *key* (or root) are taken into account.
RETURN VALUE
------------

19
doc/lightning-decode.7.md
View file

@ -9,17 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
The **decode** RPC command checks and parses:
- a *bolt11* or *bolt12* string (optionally prefixed by `lightning:`
or `LIGHTNING:`) as specified by the BOLT 11 and BOLT 12
specifications.
- a *rune* as created by lightning-commando-rune(7).
- an *emergency\_recover* string generated by hsmtool like
`lightning-hsmtool getemergencyrecover <path/to/emergency.recover>`.
It holds `emergency.recover` contents and starts with `clnemerg1`.
It may decode other formats in future.
The **decode** RPC command checks and parses `bolt11`, `bolt12`, `rune` or `emergency\_recover`. It may decode other formats in future.
RETURN VALUE
------------
@ -300,14 +290,13 @@ SEE ALSO
lightning-pay(7), lightning-offer(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7)
RESOURCES
---------
[BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
[BOLT #12](https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md) (experimental, [bolt](https://github.com/lightning/bolts) #798)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:59bcc38bf3c4b2aa6f4258c1327d16171c4ba37276ac3a96528a2f12a2ef3ad5)

5
doc/lightning-decodepay.7.md
View file

@ -63,12 +63,11 @@ SEE ALSO
lightning-pay(7), lightning-getroute(7), lightning-sendpay(7).
[BOLT
\#11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md).
RESOURCES
---------
[BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:a5939424a8e93fc4e79a702753b58fa3da4e4c5efa00571d46dd35c9a68ea38e)

3
doc/lightning-deldatastore.7.md
View file

@ -29,6 +29,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- 1200: the key does not exist

3
doc/lightning-delexpiredinvoice.7.md
View file

@ -12,9 +12,6 @@ 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
------------

8
doc/lightning-delforward.7.md
View file

@ -17,14 +17,6 @@ This command is mainly used by the *autoclean* plugin (see lightningd-config(7))
As these database entries are only kept for your own analysis, removing them
has no effect on the running of your node.
You cannot delete forwards which have status *offered* (i.e. are
currently active).
Note: for **listforwards** entries without an *in\_htlc\_id* entry (no
longer created in v22.11, but can exist from older versions), a value
of 18446744073709551615 can be used, but then it will delete *all*
entries without *in\_htlc\_id* for this *in\_channel* and *status*.
RETURN VALUE
------------

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

@ -12,13 +12,6 @@ DESCRIPTION
The **delinvoice** RPC command removes an invoice with *status* as given
in **listinvoices**, or with *desconly* set, removes its description.
The caller should be particularly aware of the error case caused by the
*status* changing just before this command is invoked!
If *desconly* is set, the invoice is not deleted, but has its
description removed (this can save space with very large descriptions,
as would be used with lightning-invoice(7) *deschashonly*.
RETURN VALUE
------------

15
doc/lightning-delpay.7.md
View file

@ -9,17 +9,11 @@ SYNOPSIS
DESCRIPTION
-----------
The **delpay** RPC command deletes a payment with the given `payment_hash` if its status is either `complete` or `failed`. Deleting a `pending` payment is an error. If *partid* and *groupid* are not specified, all payment parts with matchin status are deleted.
- *payment\_hash*: The unique identifier of a payment.
- *status*: Expected status of the payment.
- *partid*: Specific partid to delete (must be paired with *groupid*)
- *groupid*: Specific groupid to delete (must be paired with *partid*)
Only deletes if the payment status matches.
The **delpay** RPC command deletes a payment with the given `payment_hash` if its status is either `complete` or `failed`. If *partid* and *groupid* are not specified, all payment parts with matchin status are deleted.
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -31,6 +25,7 @@ EXAMPLE JSON REQUEST
}
```
RETURN VALUE
------------
@ -61,6 +56,9 @@ On success, an object containing **payments** is returned. It is an array of ob
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned. If the lightning process fails before responding, the
caller should use lightning-listsentpays(7) or lightning-listpays(7) to query whether this payment was deleted or not.
@ -72,6 +70,7 @@ The following error codes may occur:
EXAMPLE JSON RESPONSE
-----
```json
{
"payments": [

2
doc/lightning-disableinvoicerequest.7.md
View file

@ -3,6 +3,7 @@ lightning-disableinvoicerequest -- Command for removing an invoice request
SYNOPSIS
--------
**(WARNING: experimental-offers only)**
**disableinvoicerequest** *invreq\_id*
@ -18,7 +19,6 @@ We currently don't support deletion of invoice\_requests, so they are
not forgotten entirely (there may be payments which refer to this
invoice\_request).
RETURN VALUE
------------

4
doc/lightning-disableoffer.7.md
View file

@ -3,6 +3,7 @@ lightning-disableoffer -- Command for removing an offer
SYNOPSIS
--------
**(WARNING: experimental-offers only)**
**disableoffer** *offer\_id*
@ -18,6 +19,7 @@ forgotten entirely (there may be invoices which refer to this offer).
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -47,6 +49,7 @@ On success, an object is returned, containing:
EXAMPLE JSON RESPONSE
-----
```json
{
"offer_id": "053a5c566fbea2681a5ff9c05a913da23e45b95d09ef5bd25d7d408f23da7084",
@ -58,7 +61,6 @@ EXAMPLE JSON RESPONSE
```
AUTHOR
------

20
doc/lightning-disconnect.7.md
View file

@ -11,25 +11,8 @@ 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
------------
@ -38,6 +21,9 @@ On success, an empty object is returned.
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

5
doc/lightning-feerates.7.md
View file

@ -15,11 +15,6 @@ The backend may fail to provide estimates, but if it was able to provide
estimates in the past, CLN will continue to use those for a while.
CLN will also smoothen feerate estimations from the backend.
*style* is either of the two strings:
* *perkw* - provide feerate in units of satoshis per 1000 weight (e.g. the minimum fee is usually `253perkw`)
* *perkb* - provide feerate in units of satoshis per 1000 virtual bytes (eg. the minimum fee is usually `1000perkb`)
Explorers often present fees in "sat/vB": 4 sat/vB is `4000perkb` or
`1000perkw`.

29
doc/lightning-fetchinvoice.7.md
View file

@ -19,32 +19,6 @@ If **fetchinvoice-noconnect** is not specified in the configuation, it
will connect to the destination in the (currently common!) case where it
cannot find a route which supports `option_onion_messages`.
*amount\_msat* is required if the *offer* does not specify an amount
at all, otherwise it is optional (but presumably if you set it to less
than the offer, you will get an error from the issuer).
*quantity* is is required if the *offer* specifies
*quantity\_max*, otherwise it is not allowed.
*recurrence\_counter* is required if the *offer*
specifies *recurrence*, otherwise it is not allowed.
*recurrence\_counter* should first be set to 0, and incremented for
each successive invoice in a given series.
*recurrence\_start* is required if the *offer*
specifies *recurrence\_base* with *start\_any\_period* set, otherwise it
is not allowed. It indicates what period number to start at.
*recurrence\_label* is required if *recurrence\_counter* is set, and
otherwise is not allowed. It must be the same as prior fetchinvoice
calls for the same recurrence, as it is used to link them together.
*timeout* is an optional timeout; if we don't get a reply before this
we fail (default, 60 seconds).
*payer\_note* is an optional payer note to ask the issuer to include
in the fetched invoice.
RETURN VALUE
------------
@ -67,6 +41,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- -1: Catchall nonspecific error.

31
doc/lightning-fundchannel.7.md
View file

@ -11,29 +11,15 @@ SYNOPSIS
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.
If not already connected, **fundchannel** will automatically attempt
to connect if C-lightning knows a way to contact the node (either from
normal gossip, or from a previous **connect** call).
This auto-connection can fail if C-lightning does not know how to contact
the target node; see lightning-connect(7).
Once the
transaction is confirmed, normal channel operations may begin. Readiness
is indicated by **listpeers** reporting a *state* of `CHANNELD_NORMAL`
for the channel.
The **fundchannel** RPC command opens a payment channel with a peer by committing a
funding transaction to the blockchain as defined in BOLT #2.
*id* is the peer id obtained from **connect**.
If not already connected, **fundchannel** will automatically attempt to connect if
Core Lightning knows a way to contact the node (either from normal gossip, or from
a previous **connect** call).
*amount* is the amount in satoshis taken from the internal wallet to
fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available
funds (or 16777215 satoshi if more is available and large channels were not negotiated with the peer). 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 (unless large
channels were negotiated with the peer).
This auto-connection can fail if Core Lightning does not know how to contact the
target node; see lightning-connect(7).
*feerate* is an optional feerate used for the opening transaction and
(unless *option\_anchors\_zero\_fee\_htlc\_tx* is negotiated), as initial feerate
@ -117,6 +103,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
-------
The following error codes may occur:
- -1: Catchall nonspecific error.

5
doc/lightning-fundchannel_cancel.7.md
View file

@ -12,8 +12,6 @@ DESCRIPTION
`fundchannel_cancel` is a lower level RPC command. It allows channel opener
to cancel a channel before funding broadcast with a connected peer.
*id* is the node id of the remote peer with which to cancel.
Note that the funding transaction MUST NOT be broadcast before
`fundchannel_cancel`. Broadcasting transaction before `fundchannel_cancel`
WILL lead to unrecoverable loss of funds.
@ -32,6 +30,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

8
doc/lightning-fundchannel_complete.7.md
View file

@ -12,11 +12,6 @@ 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.
*psbt* is the transaction to use for funding (does not need to be
signed but must be otherwise complete).
Note that the funding transaction MUST NOT be broadcast until after
channel establishment has been successfully completed, as the commitment
transactions for this channel are not secured until this command
@ -34,6 +29,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

49
doc/lightning-fundchannel_start.7.md
View file

@ -12,52 +12,6 @@ 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.
*amount* 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: see **fundchannel**. Note that this is ignored
for channels with *option\_anchors\_zero\_fee\_htlc\_tx* (we always use a low
commitment fee for these).
*announce* whether or not to announce this channel.
*close\_to* is a Bitcoin address to which the channel funds should be sent to
on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`.
Returns `close_to` set to closing script iff is negotiated.
*push\_msat* is the amount of millisatoshis to push to the channel peer at
open. Note that this is a gift to the peer -- these satoshis are
added to the initial balance of the peer at channel start and are largely
unrecoverable once pushed.
*channel\_type* *(added v24.02)* is an array of bit numbers, representing the explicit
channel type to request. BOLT 2 defines the following value types:
```
The currently defined basic types are:
- no features (no bits set) `[]`
- `option_static_remotekey` (`[12]`)
- `option_anchor_outputs` and `option_static_remotekey` (`[20, 12]`)
- `option_anchors_zero_fee_htlc_tx` and `option_static_remotekey` ([22, 12])
Each basic type has the following variations allowed:
- `option_scid_alias` ([46])
- `option_zeroconf` ([50])
```
*mindepth* is the number of confirmations before we accept the channel as
active.
*reserve* is the amount we want the peer to maintain on its side of the channel.
Default is 1% of the funding amount. 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*.
Note that the funding transaction MUST NOT be broadcast until after
channel establishment has been successfully completed by running
`fundchannel_complete`, as the commitment transactions for this channel
@ -85,6 +39,9 @@ The following warnings may also be returned:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

93
doc/lightning-funderupdate.7.md
View file

@ -6,100 +6,17 @@ SYNOPSIS
**funderupdate** [*policy*] [*policy\_mod*] [*leases\_only*] [*min\_their\_funding\_msat*] [*max\_their\_funding\_msat*] [*per\_channel\_min\_msat*] [*per\_channel\_max\_msat*] [*reserve\_tank\_msat*] [*fuzz\_percent*] [*fund\_probability*] [*lease\_fee\_base\_msat*] [*lease\_fee\_basis*] [*funding\_weight*] [*channel\_fee\_max\_base\_msat*] [*channel\_fee\_max\_proportional\_thousandths*] [*compact\_lease*]
NOTE: Must have --experimental-dual-fund enabled for these settings to take effect.
DESCRIPTION
-----------
For channel open requests using
NOTE: Must have --experimental-dual-fund enabled for these settings to take effect.
*policy*, *policy\_mod* is the policy the funder plugin will use to decide
how much capital to commit to a v2 open channel request. There are three
policy options, detailed below: `match`, `available`, and `fixed`.
The *policy\_mod* is the number or 'modification' to apply to the policy.
Default is (fixed, 0sats).
* `match` -- Contribute *policy\_mod* percent of their requested funds.
Valid *policy\_mod* values are 0 to 200. If this is a channel lease
request, we match based on their requested funds. If it is not a
channel lease request (and *lease\_only* is false), then we match
their funding amount. Note: any lease match less than 100 will
likely fail, as clients will not accept a lease less than their request.
* `available` -- Contribute *policy\_mod* percent of our available
node wallet funds. Valid *policy\_mod* values are 0 to 100.
* `fixed` -- Contributes a fixed *policy\_mod* sats to v2 channel open requests.
For channel open requests using dual funding.
Note: to maximize channel leases, best policy setting is (match, 100).
*leases\_only* will only contribute funds to `option_will_fund` requests
which pay to lease funds. Defaults to false, will fund any v2 open request
using *policy* even if it's they're not seeking to lease funds. Note that
`option_will_fund` commits funds for 4032 blocks (~1mo). Must also set
*lease\_fee\_base\_msat*, *lease\_fee\_basis*, *funding\_weight*,
*channel\_fee\_max\_base\_msat*, and *channel\_fee\_max\_proportional\_thousandths*
to advertise available channel leases.
*min\_their\_funding\_msat* is the minimum funding sats that we require in order
to activate our contribution policy to the v2 open. Defaults to 10k sats.
*max\_their\_funding\_msat* is the maximum funding sats that we will consider
to activate our contribution policy to the v2 open. Any channel open above this
will not be funded. Defaults to no max (`UINT_MAX`).
*per\_channel\_min\_msat* is the minimum amount that we will contribute to a
channel open. Defaults to 10k sats.
*per\_channel\_max\_msat* is the maximum amount that we will contribute to a
channel open. Defaults to no max (`UINT_MAX`).
*reserve\_tank\_msat* is the amount of sats to leave available in the node wallet.
Defaults to zero sats.
*fuzz\_percent* is a percentage to fuzz the resulting contribution amount by.
Valid values are 0 to 100. Note that turning this on with (match, 100) policy
will randomly fail `option_will_fund` leases, as most clients
expect an exact or greater match of their `requested_funds`.
Defaults to 0% (no fuzz).
*fund\_probability* is the percent of v2 channel open requests to apply our
policy to. Valid values are integers from 0 (fund 0% of all open requests)
to 100 (fund every request). Useful for randomizing opens that receive funds.
Defaults to 100.
Setting any of the next 5 options will activate channel leases for this node,
and advertise these values via the lightning gossip network. If any one is set,
the other values will be the default.
*lease\_fee\_base\_msat* is the flat fee for a channel lease. Node will
receive this much extra added to their channel balance, paid by the opening
node. Defaults to 2k sats. Note that the minimum is 1sat.
*lease\_fee\_basis* is a basis fee that's calculated as 1/10k of the total
requested funds the peer is asking for. Node will receive the total of
*lease\_fee\_basis* times requested funds / 10k satoshis added to their channel
balance, paid by the opening node. Default is 0.65% (65 basis points)
*funding\_weight* is used to calculate the fee the peer will compensate your
node for its contributing inputs to the funding transaction. The total fee
is calculated as the `open_channel2`.`funding_feerate_perkw` times this
*funding\_weight* divided by 1000. Node will have this funding fee added
to their channel balance, paid by the opening node. Default is
2 inputs + 1 P2WPKH output.
*channel\_fee\_max\_base\_msat* is a commitment to a maximum
`channel_fee_base_msat` that your node will charge for routing payments
over this leased channel during the lease duration. Default is 5k sats.
*channel\_fee\_max\_proportional\_thousandths* is a commitment to a maximum
`channel_fee_proportional_millionths` that your node will charge for
routing payments over this leased channel during the lease duration.
Note that it's denominated in 'thousandths'. A setting of `1` is equal
to 1k ppm; `5` is 5k ppm, etc. Default is 100 (100k ppm).
*compact\_lease* is a compact description of the channel lease params. When
opening a channel, passed in to `fundchannel` to indicate the terms we
expect from the peer.
Setting any of the 5 options from *lease_fee_base_msat*, *lease_fee_basis*, *funding_weight*, *channel_fee_max_base_msat* and, *channel_fee_max_proportional_thousandths* will activate channel leases for this node, and advertise these values via the lightning gossip network. If any one is set, the other values will be the default.
RETURN VALUE
------------
@ -127,6 +44,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error code may occur:
- -32602: If the given parameters are invalid.
@ -141,7 +61,6 @@ SEE ALSO
lightning-fundchannel(7), lightning-listfunds(7)
RESOURCES
---------

35
doc/lightning-fundpsbt.7.md
View file

@ -12,38 +12,6 @@ DESCRIPTION
`fundpsbt` is a low-level RPC command which creates a PSBT using unreserved
inputs in the wallet, optionally reserving them as well.
*satoshi* is the minimum satoshi value of the output(s) needed (or the
string "all" meaning use all unreserved inputs). If a value, 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: see NOTES in lightning-feerates(7)
for possible values. The default is *normal*.
*startweight* is the weight of the transaction before *fundpsbt* has
added any inputs.
*minconf* specifies the minimum number of confirmations that used
outputs should have. Default is 1.
If *reserve* if not zero, then *reserveinputs* is called (successfully, with
*exclusive* true) on the returned PSBT for this number of blocks (default
72 blocks if unspecified).
*locktime* is an optional locktime: if not set, it is set to a recent
block height.
*min\_witness\_weight* is an optional minimum weight to use for a UTXO's
witness. If the actual witness weight is greater than the provided minimum,
the actual witness weight will be used.
*excess\_as\_change* is an optional boolean to flag to add a change output
for the excess sats.
*nonwrapped* is an optional boolean to signal to filter out any p2sh-wrapped
inputs from funding this PSBT.
EXAMPLE USAGE
-------------
@ -90,6 +58,9 @@ added to the PSBT for the excess amount. The *excess\_msat* will
be zero. A *change\_outnum* will be returned with the index of
the change output.
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

5
doc/lightning-getinfo.7.md
View file

@ -14,6 +14,7 @@ The **getinfo** gives a summary of the current running node.
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -72,12 +73,16 @@ The following warnings may also be returned:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters or some error happened during the command process.
EXAMPLE JSON RESPONSE
-----
```json
{
"id": "02bf811f7571754f0b51e6d41a8885f5561041a7b14fac093e4cffb95749de1a8d",

6
doc/lightning-getlog.7.md
View file

@ -11,10 +11,9 @@ DESCRIPTION
The **getlog** the RPC command to show logs, with optional log *level*.
- *level*: A string that represents the log level (*broken*, *unusual*, *info*, *debug*, or *io*). The default is *info*.
EXAMPLE JSON REQUEST
--------------------
```json
{
"id": 82,
@ -58,6 +57,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.

31
doc/lightning-getroute.7.md
View file

@ -12,38 +12,11 @@ DESCRIPTION
The **getroute** RPC command attempts to find the best route for the
payment of *amount\_msat* to lightning node *id*, such that the payment will
arrive at *id* with *cltv*-blocks to spare (default 9).
*amount\_msat* 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 0 value is special: it ignores any *htlc\_minimum\_msat*
setting on channels, and simply returns a possible route (if any) which
is useful for simple probing.
arrive at *id* with *cltv*.
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* non-negative
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.
*fuzzpercent* was used to distort fees to provide some randomization to the
route generated, but it was not properly implemented and is ignored.
*exclude* is a JSON array of short-channel-id/direction (e.g. [
"564334x877x1/0", "564195x1292x0/1" ]) or node-id which should be excluded
from consideration for routing. The default is not to exclude any channels
or nodes. Note if the source or destination is excluded, the command result
is undefined.
*maxhops* is the maximum number of channels to return; default is 20.
node goes down during the process.
RISKFACTOR EFFECT ON ROUTING
----------------------------

4
doc/lightning-help.7.md
View file

@ -17,6 +17,7 @@ page is not found.
EXAMPLE JSON REQUEST
--------------------
```json
{
"id": 82,
@ -39,6 +40,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.

2
doc/lightning-hsmtool.8.md
View file

@ -3,6 +3,7 @@ lightning-hsmtool -- Tool for working with software HSM secrets of lightningd
SYNOPSIS
--------
```bash
lightning-hsmtool method [ARGUMENTS]...
```
@ -92,6 +93,7 @@ to gain our eternal gratitude!
AUTHOR
------
ZmnSCPxj <<ZmnSCPxj@protonmail.com>> wrote the initial version of
this man page, but many others did the hard work of actually implementing
**lightning-hsmtool**.

59
doc/lightning-invoice.7.md
View file

@ -16,62 +16,6 @@ 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 *amount\_msat* parameter can be the string "any", which creates an
invoice that can be paid with any amount. Otherwise it is a positive value 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 (unless *deschashonly* is
true as described below). It must be UTF-8, and cannot use *\\u* JSON
escape codes.
The *expiry* is optionally the time the invoice is valid for, in seconds.
If no value is provided the default of 604800 (1 week) 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. If it is a short channel id
(e.g. *1x1x3*) or array of short channel ids (or a remote alias), only those specific channels
will be considered candidates, even if they are public or dead-ends.
The route hint is selected from the set of incoming channels of which:
peer's balance minus their reserves is at least *amount\_msat*, 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.
If specified, *cltv* sets the *min\_final\_cltv\_expiry* for the invoice.
Otherwise, it's set to the parameter **cltv-final**.
If *deschashonly* is true (default false), then the bolt11 returned
contains a hash of the *description*, rather than the *description*
itself: this allows much longer descriptions, but they must be
communicated via some other mechanism.
RETURN VALUE
------------
@ -94,6 +38,9 @@ The following warnings may also be returned:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned and no invoice is created. If the
lightning process fails before responding, the caller should use
lightning-listinvoices(7) to query whether this invoice was created or

30
doc/lightning-invoicerequest.7.md
View file

@ -17,33 +17,6 @@ invoice, and payment of it. The reader of the resulting
`invoice_request` can use lightning-sendinvoice(7) to collect their
payment.
The *amount* parameter can be a positive value 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 *description* is a short description of purpose of the payment,
e.g. *ATM withdrawl*. This value is encoded into the resulting
`invoice_request` and is viewable by anyone you expose it to. It must
be UTF-8, and cannot use *\\u* JSON escape codes.
The *issuer* is another (optional) field exposed in the
`invoice_request`, and reflects who is issuing it (i.e. you) if
appropriate.
The *label* field is an internal-use name for the offer, which can
be any UTF-8 string.
The *absolute\_expiry* is optionally the time the offer is valid
until, in seconds since the first day of 1970 UTC. If not set, the
`invoice_request` remains valid (though it can be deactivated by the
issuer of course). This is encoded in the `invoice_request`.
*single\_use* (default true) indicates that the `invoice_request` is
only valid once; we may attempt multiple payments, but as soon as one
is successful no more invoices are accepted (i.e. only one person can
take the money).
RETURN VALUE
------------
@ -59,6 +32,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned and no `invoice_request` is
created. If the lightning process fails before responding, the caller
should use lightning-listinvoicerequests(7) to query whether it was

19
doc/lightning-keysend.7.md
View file

@ -22,22 +22,6 @@ generated on the destination, and the only way sender could have it is by
sending a payment. Please ensure that this matches your use-case when using
`keysend`.
`destination` is the 33 byte, hex-encoded, node ID of the node that the payment should go to.
`amount\_msat` 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 `maxfeepercent` limits the money paid in fees as percentage of the total amount that is to be transferred, and defaults to *0.5*.
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.
Unlike lightning-pay(7), issuing the same `keysend` commands multiple times will result in multiple payments being sent.
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.
*extratlvs* is an optional dictionary of additional fields to insert into the final tlv. The format is 'fieldnumber': 'hexstring'.
When using *lightning-cli*, you may skip optional parameters by using
*null*. Alternatively, use **-k** option to provide parameters by name.
@ -87,6 +71,9 @@ The following warnings may also be returned:
You can monitor the progress and retries of a payment using the lightning-paystatus(7) command.
ERRORS
------
The following error codes may occur:
- `-1`: Catchall nonspecific error.

15
doc/lightning-listchannels.7.md
View file

@ -13,18 +13,6 @@ 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).
Note that for local channels, listpeerchannels(7) gives much more detailed
information: **listchannels** only shows public gossip information (previously it merged local information, but that was deprecated in *v24.02*).
If *short\_channel\_id* is a short channel id, then only known channels with a
matching *short\_channel\_id* are returned. Otherwise, it must be null.
If *source* is a node id, then only channels leading from that node id
are returned.
If *destination* is a node id, then only channels leading to that node id
are returned.
Only one of *short\_channel\_id*, *source* or *destination* can be supplied.
If nothing is supplied, data on all lightning channels known to this
node, are returned. These can be local channels or public channels
@ -58,6 +46,9 @@ On success, an object containing **channels** is returned. It is an array of ob
If one of *short\_channel\_id*, *source* or *destination* is supplied and no
matching channels are found, a "channels" object with an empty list is returned.
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

7
doc/lightning-listclosedchannels.7.md
View file

@ -13,10 +13,6 @@ The **listclosedchannels** RPC command returns data on channels which
are otherwise forgotten (more than 100 blocks after they're completely
resolved onchain).
If no *id* is supplied, then channel data on all historical channels are given.
Supplying *id* will filter the results to only match channels to that peer. Note that prior to v23.05, old peers were forgotten.
RETURN VALUE
------------
@ -55,7 +51,8 @@ On success, an object containing **closedchannels** is returned. It is an array
- **last\_commitment\_fee\_msat** (msat, optional): The fee on `last_commitment_txid`
- **last\_stable\_connection** (u64, optional): Last time we reestablished the open channel and stayed connected for 1 minute *(added v24.02)*
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

4
doc/lightning-listconfigs.7.md
View file

@ -9,8 +9,6 @@ SYNOPSIS
DESCRIPTION
-----------
*config* (optional) is a configuration option name to restrict return.
The **listconfigs** RPC command to list all configuration options, or with *config* only one.
The returned values reflect the current configuration, including
@ -365,6 +363,8 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:

6
doc/lightning-listdatastore.7.md
View file

@ -12,9 +12,6 @@ DESCRIPTION
The **listdatastore** RPC command allows plugins to fetch data which was
stored in the Core Lightning database.
All immediate children of the *key* (or root children) are returned:
a *key* with children won't have a *hex* or *generation* entry.
RETURN VALUE
------------
@ -29,6 +26,9 @@ On success, an object containing **datastore** is returned. It is an array of o
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- -32602: invalid parameters.

12
doc/lightning-listforwards.7.md
View file

@ -12,18 +12,6 @@ DESCRIPTION
The **listforwards** RPC command displays all htlcs that have been
attempted to be forwarded by the Core Lightning node.
If *status* is specified, then only the forwards with the given status are returned.
*status* can be either *offered* or *settled* or *failed* or *local\_failed*
If *in\_channel* or *out\_channel* is specified, then only the matching forwards
on the given in/out channel are returned.
If neither *in\_channel* or *out\_channel* is specified,
`index` controls ordering, by `created` (default) or `updated`. If
`index` is specified, `start` may be specified to start from that
value, which is generally returned from lightning-wait(7), and `limit`
can be used to specify the maximum number of entries to return.
RETURN VALUE
------------

3
doc/lightning-listfunds.7.md
View file

@ -13,9 +13,6 @@ The **listfunds** RPC command displays all funds available, either in
unspent outputs (UTXOs) in the internal wallet or funds locked in
currently open channels.
*spent* is a boolean: if true, then the *outputs* will include spent outputs
in addition to the unspent ones. Default is false.
RETURN VALUE
------------

4
doc/lightning-listhtlcs.7.md
View file

@ -11,9 +11,7 @@ DESCRIPTION
The **listhtlcs** RPC command gets all HTLCs (which, generally, we
remember for as long as a channel is open, even if they've completed
long ago). If given a short channel id (e.g. 1x2x3) or full 64-byte
hex channel id, it will only list htlcs for that channel (which
must be known).
long ago).
RETURN VALUE
------------

5
doc/lightning-listinvoicerequests.7.md
View file

@ -12,11 +12,6 @@ DESCRIPTION
The **listinvoicerequests** RPC command gets the status of a specific `invoice_request`,
if it exists, or the status of all `invoice_requests` if given no argument.
A specific invoice can be queried by providing the `invreq_id`, which
is presented by lightning-invoicerequest(7), or can be calculated from
a bolt12 invoice. If `active_only` is `true` (default is `false`) then
only active invoice\_requests are returned.
RETURN VALUE
------------

10
doc/lightning-listinvoices.7.md
View file

@ -12,15 +12,7 @@ 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.
A specific invoice can be queried by providing either the `label`
provided when creating the invoice, the `invstring` string representing
the invoice, the `payment_hash` of the invoice, or the local `offer_id`
this invoice was issued for. Only one of the query parameters can be used at once.
`index` controls ordering, by `created` (default) or `updated`. If
`index` is specified, `start` may be specified to start from that
value, which is generally returned from lightning-wait(7), and `limit`
can be used to specify the maximum number of entries to return.
Only one of the query parameters can be used from *label*, *invstring*, *payment_hash*, or *offer_id*
RETURN VALUE
------------

8
doc/lightning-listnodes.7.md
View file

@ -13,6 +13,7 @@ The **listnodes** command returns nodes the node has learned about via gossip me
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -57,12 +58,16 @@ If **option\_will\_fund** is present:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.
EXAMPLE JSON RESPONSE
-----
```json
{
"nodes": [
@ -84,7 +89,6 @@ EXAMPLE JSON RESPONSE
}
```
AUTHOR
------
@ -93,7 +97,7 @@ Vincenzo Palazzo <<vincenzo.palazzo@protonmail.com>> wrote the initial version o
SEE ALSO
--------
FIXME:
lightning-listchannels(7)
RESOURCES
---------

6
doc/lightning-listoffers.7.md
View file

@ -3,6 +3,7 @@ lightning-listoffers -- Command for listing offers
SYNOPSIS
--------
**(WARNING: experimental-offers only)**
**listoffers** [*offer\_id*] [*active\_only*]
@ -11,11 +12,11 @@ DESCRIPTION
-----------
The **listoffers** RPC command list all offers, or with `offer_id`,
only the offer with that offer\_id (if it exists). If `active_only` is
set and is true, only offers with `active` true are returned.
only the offer with that offer\_id (if it exists).
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -43,6 +44,7 @@ On success, an object containing **offers** is returned. It is an array of obje
EXAMPLE JSON RESPONSE
-----
```json
{
"offers": [

1
doc/lightning-listpays.7.md
View file

@ -11,7 +11,6 @@ DESCRIPTION
The **listpay** RPC command gets the status of all *pay* commands, or a
single one if either *bolt11* or *payment\_hash* was specified.
It is possible filter the payments also by *status*.
RETURN VALUE
------------

9
doc/lightning-listpeerchannels.7.md
View file

@ -15,9 +15,6 @@ If no *id* is supplied, then channel 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 channel data that match *id*,
if one exists.
RETURN VALUE
------------
@ -198,6 +195,9 @@ The *state* field values (and *old\_state* / *new\_state*) are worth describing
know what happened (i.e. if it was a proper unilateral close by the
peer, or a theft attempt).
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:
@ -211,8 +211,7 @@ Michael Hawkins <<michael.hawkins@protonmail.com>>.
SEE ALSO
--------
lightning-connect(7), lightning-fundchannel\_start(7),
lightning-setchannelfee(7)
lightning-connect(7), lightning-fundchannel\_start(7)
RESOURCES
---------

10
doc/lightning-listpeers.7.md
View file

@ -20,13 +20,6 @@ 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".
@ -377,6 +370,9 @@ Objects in the *htlcs* array will contain these fields:
Generally true if the HTLC is below the *dust\_limit\_msat* for the
channel.
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

8
doc/lightning-listsendpays.7.md
View file

@ -12,17 +12,11 @@ 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. It is possible filter the payments also by *status*.
specify both. It is possible to filter the payments also by *status*.
Note that there may be more than one concurrent *sendpay*
command per *pay*, so this command should be used with caution.
If neither *bolt11* or *payment\_hash* is specified,
`index` controls ordering, by `created` (default) or `updated`. If
`index` is specified, `start` may be specified to start from that
value, which is generally returned from lightning-wait(7), and `limit`
can be used to specify the maximum number of entries to return.
RETURN VALUE
------------

2
doc/lightning-listsqlschemas.7.md
View file

@ -19,6 +19,7 @@ all tables are listed.
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -31,6 +32,7 @@ EXAMPLE JSON REQUEST
EXAMPLE JSON RESPONSE
-----
```json
{
"schemas": [

5
doc/lightning-listtransactions.7.md
View file

@ -13,6 +13,7 @@ The **listtransactions** command returns transactions tracked in the wallet. Thi
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -44,12 +45,16 @@ On success, an object containing **transactions** is returned. It is an array o
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.
EXAMPLE JSON RESPONSE
-----
```json
{
"transactions": [

5
doc/lightning-makesecret.7.md
View file

@ -11,9 +11,6 @@ DESCRIPTION
The **makesecret** RPC command derives a secret key from the HSM\_secret.
One of *hex* or *string* must be specified: *hex* can be any hex data,
*string* is a UTF-8 string interpreted literally.
RETURN VALUE
------------
@ -24,6 +21,8 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:

88
doc/lightning-multifundchannel.7.md
View file

@ -22,87 +22,6 @@ Once the transaction is confirmed, normal channel operations may begin.
Readiness is indicated by **listpeers** reporting a *state* of
`CHANNELD_NORMAL` for the channel.
*destinations* is an array of objects, with the fields:
* *id* is the node ID, with an optional *@host:port* appended to it
in a manner understood by **connect**; see lightning-connect(7).
Each entry in the *destinations* array must have a unique node *id*.
* *amount* is the amount in satoshis taken from the internal wallet
to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change).
The string *all* can be used to specify all available funds
(or 16,777,215 satoshi if more is available and large channels were
not negotiated with the peer).
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 546 satoshi
as of this writing, nor more than 16,777,215 satoshi
(unless large channels were negotiated with the peer).
* *announce* is an optional flag that indicates whether to announce
the channel with this, default `true`.
If set to `false`, the channel is unpublished.
* *push\_msat* is the amount of millisatoshis to outright give to the
node.
This is a gift to the peer, and you do not get a proof-of-payment
out of this.
* *close\_to* is a Bitcoin address to which the channel funds should be sent to
on close. Only valid if both peers have negotiated
`option_upfront_shutdown_script`. Returns `close_to` set to
closing script iff is negotiated.
* *request\_amt* is the amount of liquidity you'd like to lease from peer.
If peer supports `option_will_fund`, indicates to them to include this
much liquidity into the channel. Must also pass in *compact\_lease*.
* *compact\_lease* is a compact represenation of the peer's expected
channel lease terms. If the peer's terms don't match this set, we will
fail to open the channel to this destination.
* *reserve* is the amount we want the peer to maintain on its side of the
channel. Default is 1% of the funding amount. 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*.
There must be at least one entry in *destinations*;
it cannot be an empty array.
*feerate* is an optional feerate used for the opening transaction, and
if *commitment\_feerate* is not set, as initial feerate for commitment
and HTLC transactions. See NOTES in lightning-feerates(7) for possible
values. The default is *normal*.
*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".
*minchannels*, if specified, will re-attempt funding as long as at least
this many peers remain (must not be zero).
The **multifundchannel** command will only fail if too many peers fail
the funding process.
*commitment\_feerate* is the initial feerate for commitment and HTLC
transactions. See *feerate* for valid values.
*channel\_type* *(added v24.02)* is an array of bit numbers, representing the explicit
channel type to request. BOLT 2 defines the following value types:
```
*channel\_type* *(added v24.02)* is an array of bit numbers, representing the explicit
channel type to request. BOLT 2 defines the following value types:
```
The currently defined basic types are:
- no features (no bits set) `[]`
- `option_static_remotekey` (`[12]`)
- `option_anchor_outputs` and `option_static_remotekey` (`[20, 12]`)
- `option_anchors_zero_fee_htlc_tx` and `option_static_remotekey` ([22, 12])
Each basic type has the following variations allowed:
- `option_scid_alias` ([46])
- `option_zeroconf` ([50])
```
RETURN VALUE
------------
@ -140,6 +59,9 @@ On success, an object is returned, containing:
On failure, none of the channels are created.
ERRORS
------
The following error codes may occur:
* -1: Catchall nonspecific error.
@ -167,8 +89,8 @@ Doing a **connect** with the peers separately, and waiting for a
few seconds, should help clear this hurdle;
running **multifundchannel** a third time would also clear this.
EXAMPLE
-------
EXAMPLE USAGE
-------------
This example opens three channels at once, with amounts 200,000 sats, 3,000,000 sats and the final channel using all remaining funds (actually, capped at 16,777,215 sats because large-channels is not enabled):

25
doc/lightning-multiwithdraw.7.md
View file

@ -4,31 +4,13 @@ lightning-multiwithdraw -- Command for withdrawing to multiple addresses
SYNOPSIS
--------
**multiwithdraw** *outputs* [*feerate*] [*minconf*] [*utxos*]
**multiwithdraw** *outputs* [*feerate*] [*minconf*] [*utxos*]
DESCRIPTION
-----------
The **multiwithdraw** RPC command sends funds from Core Lightning's internal
wallet to the addresses specified in *outputs*,
which is an array containing objects of the form `{address: amount}`.
The `amount` may be the string *"all"*, indicating that all onchain funds
be sent to the specified address.
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: see NOTES in lightning-feerates(7)
for possible values. The default is *normal*.
*minconf* specifies the minimum number of confirmations that used
outputs should have. Default is 1.
*utxos* specifies the utxos to be used to be withdrawn from, as an array
of "txid:vout". These must be drawn from the node's available UTXO set.
wallet to the addresses specified in *outputs*.
RETURN VALUE
------------
@ -41,6 +23,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is reported and the withdrawal transaction is not
created.

10
doc/lightning-newaddr.7.md
View file

@ -14,15 +14,7 @@ subsequently be used to fund channels managed by the Core Lightning node.
The funding transaction needs to be confirmed before funds can be used.
*addresstype* specifies the type of address wanted; currently *bech32*
(e.g. `tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg` on bitcoin testnet
or `bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej` on
bitcoin mainnet), or *p2tr* taproot addresses. The special value *all*
generates all known address types for the same underlying key.
If no *addresstype* is specified the address generated is a *bech32* address.
To send an on-chain payment _from_ the Core Lightning node wallet, use `withdraw`.
To send an on-chain payment from the Core Lightning node wallet, use `withdraw`.
RETURN VALUE
------------

10
doc/lightning-notifications.7.md
View file

@ -16,10 +16,9 @@ disabled.
Various commands, especially complex and slow ones, offer
notifications which indicate their progress.
- *enable*: *true* to enable notifications, *false* to disable them.
EXAMPLE JSON REQUEST
--------------------
```json
{
"id": 82,
@ -60,12 +59,15 @@ On success, an empty object is returned.
On success, if *enable* was *true*, notifications will be forwarded
from then on.
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters.
EXAMPLE NOTIFICATIONS
---------------------
EXAMPLE JSON NOTIFICATIONS
--------------------------
```json
{

3
doc/lightning-offer.7.md
View file

@ -106,6 +106,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned and no offer is created. If the
lightning process fails before responding, the caller should use
lightning-listoffers(7) to query whether this offer was created or

6
doc/lightning-openchannel_abort.7.md
View file

@ -13,9 +13,6 @@ DESCRIPTION
open with a specified peer. It uses the openchannel protocol
which allows for interactive transaction construction.
*channel\_id* is id of this channel.
RETURN VALUE
------------
@ -28,6 +25,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

20
doc/lightning-openchannel_bump.7.md
View file

@ -13,23 +13,6 @@ DESCRIPTION
RBF (Replace-By-Fee) for the specified channel. It uses the openchannel protocol
which allows for interactive transaction construction.
*id* is the id of the channel to RBF.
*amount* is the satoshi value that we will contribute to the channel.
This value will be _added_ to the provided PSBT in the output which is
encumbered by the 2-of-2 script for this channel.
*initialpsbt* is the funded, incomplete PSBT that specifies the UTXOs and
change output for our channel contribution. It can be updated,
see `openchannel_update`; *initialpsbt* must have at least one input.
Must have the Non-Witness UTXO (PSBT\_IN\_NON\_WITNESS\_UTXO) set for
every input. An error (code 309) will be returned if this requirement
is not met.
*funding\_feerate* is an optional field. Sets the feerate for the
funding transaction. Defaults to 1/64th greater than the last
feerate used for this channel.
Warning: bumping a leased channel will lose the lease.
RETURN VALUE
@ -57,6 +40,9 @@ will return an error.
If the channel is not in a state that is eligible for RBF, this command
will return an error.
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

51
doc/lightning-openchannel_init.7.md
View file

@ -13,54 +13,6 @@ DESCRIPTION
open with a specified peer. It uses the openchannel protocol
which allows for interactive transaction construction.
*id* is the node id of the remote peer.
*amount* is the satoshi value that we will contribute to the channel.
This value will be _added_ to the provided PSBT in the output which is
encumbered by the 2-of-2 script for this channel.
*initialpsbt* is the funded, incomplete PSBT that specifies the UTXOs and
change output for our channel contribution. It can be updated,
see `openchannel_update`; *initialpsbt* must have at least one input.
Must have the Non-Witness UTXO (PSBT\_IN\_NON\_WITNESS\_UTXO) set for
every input. An error (code 309) will be returned if this requirement
is not met.
*commitment\_feerate* is an optional field. Sets the feerate for
commitment transactions for non-anchor channels: see **fundchannel**.
For anchor channels, it is ignored.
*funding\_feerate* is an optional field. Sets the feerate for the
funding transaction. Defaults to 'opening' feerate.
*announce* is an optional field. Whether or not to announce this channel.
*close\_to* is a Bitcoin address to which the channel funds should be
sent on close. Only valid if both peers have negotiated
`option_upfront_shutdown_script`.
*request\_amt* is an amount of liquidity you'd like to lease from the peer.
If peer supports `option_will_fund`, indicates to them to include this
much liquidity into the channel. Must also pass in *compact\_lease*.
*compact\_lease* is a compact represenation of the peer's expected
channel lease terms. If the peer's terms don't match this set, we will
fail to open the channel.
*channel\_type* *(added v24.02)* is an array of bit numbers, representing the explicit
channel type to request. BOLT 2 defines the following value types:
The currently defined basic types are:
- no features (no bits set) `[]`
- `option_static_remotekey` (`[12]`)
- `option_anchor_outputs` and `option_static_remotekey` (`[20, 12]`)
- `option_anchors_zero_fee_htlc_tx` and `option_static_remotekey` ([22, 12])
Each basic type has the following variations allowed:
- `option_scid_alias` ([46])
- `option_zeroconf` ([50])
```
RETURN VALUE
------------
@ -91,6 +43,9 @@ updated rate card for the lease fee (*lease\_fee\_proportional\_basis*,
be added to the lease fee at a rate of *funding\_feerate* * *weight\_charge*
/ 1000.
ERRORS
------
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:

10
doc/lightning-openchannel_signed.7.md
View file

@ -19,13 +19,6 @@ This command should be called after `openchannel_update` returns
This command will broadcast the finalized funding transaction,
if we receive valid signatures from the peer.
*channel\_id* is the id of the channel.
*signed\_psbt* is the PSBT returned from `openchannel_update` (where
*commitments\_secured* was true) with partial signatures or finalized
witness stacks included for every input that we contributed to the
PSBT.
RETURN VALUE
------------
@ -38,6 +31,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error, the returned object will contain `code` and `message` properties,
with `code` being one of the following:

7
doc/lightning-openchannel_update.7.md
View file

@ -20,10 +20,6 @@ Must be called until *commitments\_secured* is returned as true, at which point
`openchannel_signed` should be called with a signed version of the PSBT
returned by the last call to `openchannel_update`.
*channel\_id* is the id of the channel.
*psbt* is the updated PSBT to be sent to the peer. May be identical to
the PSBT last returned by either `openchannel_init` or `openchannel_update`.
RETURN VALUE
------------
@ -53,6 +49,9 @@ If *commitments\_secured* is true, will also return:
- The *funding\_outnum*, the index of the funding output for this channel
in the funding transaction.
ERRORS
------
On error, the returned object will contain `code` and `message` properties,
with `code` being one of the following:

50
doc/lightning-pay.7.md
View file

@ -12,57 +12,12 @@ 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, *amount\_msat* is required, otherwise if it is specified
it must be *null*. *amount\_msat* 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*.
(Note: if **experimental-offers** is enabled, *bolt11* can actually be
a bolt12 invoice, such as one received from lightningd-fetchinvoice(7)).
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).
`localinvreqid` is used by offers to link a payment attempt to a local
`invoice_request` offer created by lightningd-invoicerequest(7). This ensures
that we only make a single payment for an offer, and that the offer is
marked `used` once paid.
*maxfee* overrides both *maxfeepercent* and *exemptfee* defaults (and
if you specify *maxfee* you cannot specify either of those), and
creates an absolute limit on what fee we will pay. This allows you to
implement your own heuristics rather than the primitive ones used
here.
*description* is only required for bolt11 invoices which do not
contain a description themselves, but contain a description hash:
in this case *description* is required.
*description* is then checked against the hash inside the invoice
before it will be paid.
destination, and send the funds it asks for.
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.
*exclude* is a JSON array of short-channel-id/direction (e.g. [
"564334x877x1/0", "564195x1292x0/1" ]) or node-id which should be excluded
from consideration for routing. The default is not to exclude any channels
or nodes.
When using *lightning-cli*, you may skip optional parameters by using
*null*. Alternatively, use **-k** option to provide parameters by name.
@ -114,6 +69,9 @@ The following warnings may also be returned:
You can monitor the progress and retries of a payment using the
lightning-paystatus(7) command.
ERRORS
------
The following error codes may occur:
- -1: Catchall nonspecific error.

12
doc/lightning-ping.7.md
View file

@ -12,15 +12,9 @@ DESCRIPTION
The **ping** command checks if the node with *id* is ready to talk.
It currently only works for peers we have a channel with.
It accepts the following parameters:
- *id*: A string that represents the node id;
- *len*: A integer that represents the length of the ping (default 128);
- *pongbytes*: An integer that represents the length of the reply (default 128).
A value of 65532 to 65535 means "don't reply".
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -42,12 +36,16 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters or we're already waiting for a ping response from peer.
EXAMPLE JSON RESPONSE
-----
```json
{
"totlen": 132

16
doc/lightning-plugin.7.md
View file

@ -10,18 +10,9 @@ SYNOPSIS
DESCRIPTION
-----------
The **plugin** RPC command command can be used to control dynamic plugins,
The **plugin** RPC command can be used to control dynamic plugins,
i.e. plugins that declared themself "dynamic" (in getmanifest).
*subcommand* can be **start**, **stop**, **startdir**, **rescan** or **list** and
determines what action is taken
*plugin* is the *path* or *name* of a plugin executable to start or stop
*directory* is the *path* of a directory containing plugins
*options* are optional *keyword=value* options passed to plugin, can be repeated
*subcommand* **start** takes a *path* to an executable as argument and starts it as plugin.
*path* may be an absolute path or a path relative to the plugins directory (default *~/.lightning/plugins*).
If the plugin is already running and the executable (checksum) has changed, the plugin is
@ -71,11 +62,15 @@ If **command** is "stop":
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On error, the reason why the action could not be taken upon the
plugin is returned.
SEE ALSO
--------
lightning-cli(1), lightning-listconfigs(1), [writing plugins][writing plugins]
AUTHOR
@ -89,4 +84,5 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[writing plugins]: PLUGINS.md
[comment]: # ( SHA256STAMP:83b40cc97b040fc0d7d47ebfda887c7c7ab0f305330978cd8426b6eed01737d2)

9
doc/lightning-preapprovekeysend.7.md
View file

@ -13,15 +13,6 @@ The **preapprovekeysend** RPC command submits the *destination*, *payment\_hash*
and *amount\_msat* parameters to the HSM to check that they are approved as a
keysend payment.
*destination* is a 33 byte, hex-encoded, node ID of the node that the payment should go to.
*payment\_hash* is the unique identifier of a payment.
*amount\_msat* is the amount to send 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`.
Generally the **preapprovekeysend** request does not need to be made
explicitly, it is automatically generated as part of a **keysend** request.

39
doc/lightning-renepay.7.md
View file

@ -7,7 +7,6 @@ SYNOPSIS
**renepay** *invstring* [*amount\_msat*] [*maxfee*] [*maxdelay*]
[*retry\_for*] [*description*] [*label*]
DESCRIPTION
-----------
@ -15,43 +14,13 @@ DESCRIPTION
method for Multi-Path-Payments. This implementation has not been thoroughly
tested and it should be used with caution.
The **renepay** RPC command attempts to pay the invoice specified
as *invstring*. Currently, **renepay** supports bolt11 invoices only.
The response will occur when the payment fails or succeeds. Once a
payment has succeeded, calls to **renepay** with the same *invstring*
will not lead to a new payment attempt, but instead it will succeed immediately.
If the *invstring* does not contain an amount,
*amount\_msat* is required, otherwise if it is specified
it must be *null*. *amount\_msat* 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*.
*maxfee* limits how much is paid fees and it is measured in millisatoshi
by default, but also in this case the unit can be specified with a suffix: *msat*, *sat* or *btc*.
The default value is 5 sats or 0.5% whichever is higher.
*maxdelay* overrides the value of `max-locktime-blocks` for this payment.
It serves to limit the locktime of funds in the payment HTLC measured in blocks.
*retry\_for* measured in seconds (default: 60) specifies how much time it is
allowed for the command to keep retrying the payment.
*description* is only required for bolt11 invoices which do not
contain a description themselves, but contain a description hash:
in this case *description* is required.
*description* is then checked against the hash inside the invoice
before it will be paid.
The *label* field is used to attach a label to payments, and is returned
in lightning-listpays(7) and lightning-listsendpays(7).
When using *lightning-cli*, you may skip optional parameters by using
*null*. Alternatively, use **-k** option to provide parameters by name.
OPTIMALITY
----------
@ -114,6 +83,9 @@ On success, an object is returned, containing:
You can monitor the progress and retries of a payment using the
lightning-renepaystatus(7) command.
ERRORS
------
The following error codes may occur:
- -1: Catchall nonspecific error.
@ -140,6 +112,7 @@ RESOURCES
---------
- Main web site: <https://github.com/ElementsProject/lightning>
- Pickhardt R. and Richter S., *Optimally Reliable & Cheap Payment Flows on the Lightning Network*
<https://arxiv.org/abs/2107.05322>
- Pickhardt R. and Richter S., *Optimally Reliable & Cheap Payment Flows on the Lightning Network* <https://arxiv.org/abs/2107.05322>
[comment]: # ( SHA256STAMP:946ad2fc9ef6bb6dbab6613b9cb55d34ed5a15dd876efcaeaa41174f0bdc40b0)

3
doc/lightning-renepaystatus.7.md
View file

@ -12,8 +12,7 @@ DESCRIPTION
The **renepaystatus** RPC command queries the payment plugin **renepay**
for the status of previous payment attempts.
If *invstring* is specified, the command will return a list of payment attempts
whose invoice matches *invstring*, otherwise all payments with be listed.
This command always succeeds.
RETURN VALUE

9
doc/lightning-reserveinputs.7.md
View file

@ -15,11 +15,7 @@ with an error if any of the inputs are known to be spent, and ignore inputs
which are unknown.
Normally the command will fail (with no reservations made) if an input
is already reserved. If *exclusive* is set to *False*, then existing
reservations are simply extended, rather than causing failure.
By default, reservations are for the next 72 blocks (approximately 6
hours), but this can be changed by setting *reserve*.
is already reserved.
RETURN VALUE
------------
@ -44,6 +40,9 @@ which was reserved:
- *reserved* indicates that the input is now reserved (i.e. true).
- *reserved\_to\_block* indicates what blockheight the reservation will expire.
ERRORS
------
On failure, an error is reported and no UTXOs are reserved.
The following error codes may occur:

21
doc/lightning-sendcustommsg.7.md
View file

@ -14,24 +14,9 @@ into the communication with the peer with the given `node_id`. This is
intended as a low-level interface to implement custom protocol extensions on
top, not for direct use by end-users.
The message must be a hex encoded well-formed message, including the 2-byte
type prefix, but excluding the length prefix which will be added by the RPC
method. The message types may not be one of the internally handled
types, since that may cause issues with the internal state tracking of
Core Lightning. We do (as of *v23.11*) allow sending of even types, but note that peers (as per the spec) will disconnect on receiving unknown even types.
The node specified by `node_id` must be a peer, i.e., it must have a direct
connection with the node receiving the RPC call, and the connection must be
established. For a method to send arbitrary messages over multiple hops,
including hops that do not understand the custom message, see the
`createonion` and `sendonion` RPC methods. Messages can only be injected if
the connection is handled by `openingd` or `channeld`. Messages cannot be
injected when the peer is handled by `onchaind` or `closingd` since these do
not have a connection, or are synchronous daemons that do not handle
spontaneous messages.
On the reveiving end a plugin may implement the `custommsg` plugin hook and
get notified about incoming messages, and allow additional unknown even types in their getmanifest response.
On the receiving end a plugin may implement the `custommsg` plugin hook and
get notified about incoming messages, and allow additional unknown even types
in their getmanifest response.
RETURN VALUE
------------

19
doc/lightning-sendinvoice.7.md
View file

@ -18,22 +18,6 @@ If **fetchinvoice-noconnect** is not specified in the configuation, it
will connect to the destination in the (currently common!) case where it
cannot find a route which supports `option_onion_messages`.
*invreq* is the bolt12 invoice\_request string beginning with "lnr1".
*label* is the unique label to use for this invoice.
*amount\_msat* is optional: it is required if the *offer* does not specify
an amount at all, or specifies it in a different currency. Otherwise
you may set it (e.g. to provide a tip), and if not it defaults to the
amount contained in the offer (multiplied by *quantity* if any).
*timeout* is how many seconds to wait for the offering node to pay the
invoice or return an error, default 90 seconds. This will also be the
timeout on the invoice that is sent.
*quantity* is optional: it is required if the *offer* specifies
*quantity\_max*, otherwise it is not allowed.
RETURN VALUE
------------
@ -59,6 +43,9 @@ If **status** is "paid":
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
The following error codes may occur:
- -1: Catchall nonspecific error.

71
doc/lightning-sendonion.7.md
View file

@ -18,51 +18,9 @@ of the payment for the final hop. However, it is possible to add arbitrary
information for hops in the custom onion, allowing for custom extensions that
are not directly supported by Core Lightning.
The onion is specific to the route that is being used and the *payment\_hash*
used to construct, and therefore cannot be reused for other payments or to
attempt a separate route. The custom onion can generally be created using the
`devtools/onion` CLI tool, or the **createonion** RPC command.
The *onion* parameter is a hex-encoded 1366 bytes long blob that was returned
by either of the tools that can generate onions. It contains the payloads
destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for
further details.
The *first\_hop* parameter instructs Core Lightning which peer to send the onion
to. It is a JSON dictionary that corresponds to the first element of the route
array returned by *getroute*. The following is a minimal example telling
Core Lightning to use any available channel to `022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59`
to add an HTLC for 1002 millisatoshis and a delay of 21 blocks on top of the current blockheight:
```json
{
"id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
"amount_msat": "1002msat",
"delay": 21,
}
```
If the first element of *route* does not have "channel" set, a
suitable channel (if any) will be chosen, otherwise that specific
short-channel-id is used.
The *payment\_hash* parameter specifies the 32 byte hex-encoded hash to use as
a challenge to the HTLC that we are sending. It is specific to the onion and
has to match the one the onion was created with.
The *label* parameter can be used to provide a human readable reference to
retrieve the payment at a later time.
The *shared\_secrets* parameter is a JSON list of 32 byte hex-encoded secrets
that were used when creating the onion. Core Lightning can send a payment with a
custom onion without the knowledge of these secrets, however it will not be
able to parse an eventual error message since that is encrypted with the
shared secrets used in the onion. If *shared\_secrets* is provided Core Lightning
will decrypt the error, act accordingly, e.g., add a `channel_update` included
in the error to its network view, and set the details in *listsendpays*
correctly. If it is not provided Core Lightning will store the encrypted onion,
and expose it in *listsendpays* allowing the caller to decrypt it
externally. The following is an example of a 3 hop onion:
short-channel-id is used. The following is an example of a 3 hop onion:
```json
[
@ -72,21 +30,6 @@ externally. The following is an example of a 3 hop onion:
]
```
If *shared\_secrets* is not provided the Core Lightning node does not know how
long the route is, which channels or nodes are involved, and what an eventual
error could have been. It can therefore be used for oblivious payments.
The *partid* value, if provided and non-zero, allows for multiple parallel
partial payments with the same *payment\_hash*.
The *bolt11* parameter, if provided, will be returned in
*waitsendpay* and *listsendpays* results.
The *destination* parameter, if provided, will be returned in **listpays** result.
The *amount\_msat* parameter is used to annotate the payment, and is returned by
*waitsendpay* and *listsendpays*.
RETURN VALUE
------------
@ -117,9 +60,14 @@ If **status** is "pending":
[comment]: # (GENERATE-FROM-SCHEMA-END)
If *shared\_secrets* was provided and an error was returned by one of the
intermediate nodes the error details are decrypted and presented
here. Otherwise the error code is 202 for an unparseable onion.
ERRORS
------
The following error codes may occur:
- 202: an parseable onion
- the error details are decrypted and presented here, if *shared\_secrets* was provided and an error was returned by one of the
intermediate nodes
AUTHOR
------
@ -137,4 +85,5 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[bolt04]: https://github.com/lightning/bolts/blob/master/04-onion-routing.md
[comment]: # ( SHA256STAMP:eb3725c7a47c32298ca9e13ad6ef3fc90a818354b21fc0b17abd16d8e9515a24)

5
doc/lightning-sendonionmessage.7.md
View file

@ -12,12 +12,9 @@ DESCRIPTION
-----------
The **sendonionmessage** RPC command can be used to send a message via
the lightning network. These are currently used by *offers* to request
the lightning network. These are currently used by *offers* to request
and receive invoices.
*hops* is an array of json objects: *id* as a public key of the node,
and *tlv* contains a hexidecimal TLV to include.
RETURN VALUE
------------

34
doc/lightning-sendpay.7.md
View file

@ -17,7 +17,7 @@ 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. If the route is empty, a payment-to-self is attempted.
lightning-getroute(7) again to retry. If the route is empty, a payment-to-self is attempted.
The response will occur when the payment is on its way to the
destination. The **sendpay** RPC command does not wait for definite
@ -26,35 +26,6 @@ payments, or to-self payments). 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 *amount\_msat* amount must be provided if *partid* is non-zero, or the payment is to-self, otherwise
it must be equal to the final
amount to the destination. By default 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 *payment\_secret* is the value that the final recipient requires to
accept the payment, as defined by the `payment_data` field in BOLT 4
and the `s` field in the BOLT 11 invoice format. It is required if
*partid* is non-zero.
The *partid* value must not be provided for self-payments. If provided and non-zero, allows for multiple parallel
partial payments with the same *payment\_hash*. The *amount\_msat* amount
(which must be provided) for each **sendpay** with matching
*payment\_hash* must be equal, and **sendpay** will fail if there are differing values given.
The *localinvreqid* value indicates that this payment is being made for a local
invoice\_request: this ensures that we only send a payment for a single-use
invoice\_request once.
*groupid* allows you to attach a number which appears in **listsendpays** so
payments can be identified as part of a logical group. The *pay* plugin uses
this to identify one attempt at a MPP payment, for example.
*payment\_metadata* is placed in the final onion hop TLV.
Once a payment has succeeded, calls to **sendpay** with the same
*payment\_hash* but a different *amount\_msat* or destination will fail;
this prevents accidental multiple payments. Calls to **sendpay** with
@ -94,6 +65,9 @@ If **status** is "pending":
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
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

10
doc/lightning-sendpsbt.7.md
View file

@ -11,8 +11,8 @@ DESCRIPTION
The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT.
- *psbt*: A string that represents psbt value.
- *reserve*: an optional number of blocks to increase reservation of any of our inputs by; default is 72.
- **psbt** (string): the fully signed psbt to be sent
- **reserve** (u32, optional): number of blocks to increase reservation of any of our inputs by. Default is 72
EXAMPLE JSON REQUEST
--------------------
@ -30,13 +30,13 @@ EXAMPLE JSON REQUEST
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
- **tx** (hex): The raw transaction which was sent
- **txid** (txid): The txid of the **tx**
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
@ -67,4 +67,4 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:ba123ea4052af7850655f99ee85ed42c0254d7c15ba3861df0574fd58e4d8355)
[comment]: # ( SHA256STAMP:e1ba1085f321e876c047232a3923fe3340481010c8c7dcf1d1dddaa723589134)

52
doc/lightning-setchannel.7.md
View file

@ -11,7 +11,7 @@ DESCRIPTION
The **setchannel** RPC command sets channel specific routing fees, and
`htlc_minimum_msat` or `htlc_maximum_msat` as defined in BOLT \#7. The channel has to be in
normal or awaiting state. This can be checked by **listpeers**
normal or awaiting state. This can be checked by **listpeers**
reporting a *state* of CHANNELD\_NORMAL or CHANNELD\_AWAITING\_LOCKIN
for the channel.
@ -19,56 +19,6 @@ These changes (for a public channel) will be broadcast to the rest of
the network (though many nodes limit the rate of such changes they
will accept: we allow 2 a day, with a few extra occasionally).
*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 updates are applied to all channels in states
CHANNELD\_NORMAL CHANNELD\_AWAITING\_LOCKIN or DUALOPEND\_AWAITING\_LOCKIN.
If *id* is a peerid, all channels with the +peer in those states are
changed.
*feebase* is an optional value in millisatoshi that is added as base fee to
any routed payment: if omitted, it is unchanged. 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*.
*feeppm* 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 through the channel, an
proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee.
*htlcmin* is an optional value that limits how small an HTLC we will
forward: if omitted, it is unchanged (the default is no lower limit). 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*. Note that the peer also enforces a
minimum for the channel: setting it below that will simply set it to
that value with a warning. Also note that *htlcmin* only applies to forwarded
HTLCs: we can still send smaller payments ourselves.
*htlcmax* is an optional value that limits how large an HTLC we will
forward: if omitted, it is unchanged (the default is no effective
limit). 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*. Note that *htlcmax*
only applies to forwarded HTLCs: we can still send larger payments ourselves.
*enforcedelay* is the number of seconds to delay before enforcing the
new fees/htlc max (default 600, which is ten minutes). This gives the
network a chance to catch up with the new rates and avoids rejecting
HTLCs before they do. This only has an effect if rates are increased
(we always allow users to overpay fees) or *htlcmax* is decreased, and
only applied to a single rate increase per channel (we don't remember
an arbitrary number of prior feerates) and if the node is restarted
the updated configuration is enforced immediately.
*ignorefeelimits* set to True means to allow the peer to set the commitment
transaction fees (or closing transaction fees) to any value they want. This is dangerous: they could
set an exorbitant fee (so HTLCs are unenforcable), or a tiny fee (so that
commitment transactions cannot be relayed), but avoids channel breakage
in case of feerate disagreements. (Note: the global `ignore_fee_limits`
setting overrides this).
RETURN VALUE
------------

5
doc/lightning-setconfig.7.md
View file

@ -13,14 +13,13 @@ The **setconfig** RPC command allows you set the (dynamic) configuration option
This new value will *also* be written at the end of the config file, for persistence across restarts (and any old value commented out).
You can see what options are dynamically adjustable using lightning-listconfigs(7). Note that you can also adjust existing options for stopped plugins; they will have an effect when the plugin is restarted.
You can see what options are dynamically adjustable using lightning-listconfigs(7). Note that you can also adjust existing options for stopped plugins; they will have an effect when the plugin is restarted.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **config** is returned. It is an object containing:
On success, an object containing **config** is returned. It is an object containing:
- **config** (string): name of the config variable which was set
- **source** (string): source of configuration setting (`file`:`linenum`)

11
doc/lightning-setpsbtversion.7.md
View file

@ -11,11 +11,9 @@ DESCRIPTION
The **setpsbtversion** RPC command converts the provided PSBT to the given version, and returns the base64 result of the conversion. Returns an error if version is invalid.
- *psbt*: The PSBT to change versions.
- *version*: The version to set.
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,
@ -32,21 +30,22 @@ RETURN VALUE
If successful the command returns a converted PSBT of the requested version.
On failure, an error is returned.
ERRORS
------
The following error codes may occur:
- -32602: Parameter missed or malformed;
- 32602: Parameter missed or malformed.
EXAMPLE JSON RESPONSE
-----
```json
{
"psbt": "cHNidP8BAgQCAAAAAQQBAAEFAQABBgEDAfsEAgAAAAA="
}
```
AUTHOR
------

8
doc/lightning-signinvoice.7.md
View file

@ -9,13 +9,10 @@ SYNOPSIS
DESCRIPTION
-----------
The **signinvoice** RPC command signs an invoice. Unlike
The **signinvoice** RPC command signs an invoice. Unlike
**createinvoice** it does not save the invoice into the database and
thus does not require the preimage.
The *invstring* parameter is of bolt11 form, but the final signature
is ignored. Minimal sanity checks are done.
RETURN VALUE
------------
@ -26,6 +23,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, an error is returned.
The following error codes may occur:

7
doc/lightning-signmessage.7.md
View file

@ -10,14 +10,13 @@ DESCRIPTION
-----------
The **signmessage** RPC command creates a digital signature of
*message* using this node's secret key. A receiver who knows your
*message* using this node's secret key. A receiver who knows your
node's *id* and the *message* can be sure that the resulting signature could
only be created by something with access to this node's secret key.
*message* must be less that 65536 characters.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
@ -42,4 +41,6 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[SignMessageRequest](https://api.lightning.community/#grpc-request-signmessagerequest)
[comment]: # ( SHA256STAMP:485db85e3822babcb397b55f251e6797528c3b9e14743d2823e890e2b22432c0)

8
doc/lightning-signpsbt.7.md
View file

@ -12,9 +12,6 @@ DESCRIPTION
**signpsbt** is a low-level RPC command which signs a PSBT as defined by
BIP-174.
- *psbt*: A string that represents the PSBT value.
- *signonly*: An optional array of input numbers to sign.
By default, all known inputs are signed, and others ignored: with
*signonly*, only those inputs are signed, and an error is returned if
one of them cannot be signed.
@ -22,9 +19,9 @@ one of them cannot be signed.
Note that the command will fail if there are no inputs to sign, or
if the inputs to be signed were not previously reserved.
EXAMPLE JSON REQUEST
--------------------
```json
{
"id": 82,
@ -45,6 +42,9 @@ On success, an object is returned, containing:
[comment]: # (GENERATE-FROM-SCHEMA-END)
ERRORS
------
On failure, one of the following error codes may be returned:
- -32602: Error in given parameters, or there aren't wallet's inputs to sign, or we couldn't sign all of *signonly*, or inputs are not reserved.

21
doc/lightning-splice_init.7.md
View file

@ -3,6 +3,7 @@ lightning-splice\_init -- Command to initiate a channel to a peer
SYNOPSIS
--------
**(WARNING: experimental-splicing only)**
**splice\_init** *channel\_id* *relative\_amount* [*initalpsbt*] [*feerate\_per\_kw*] [*force\_feerate*]
@ -13,22 +14,6 @@ DESCRIPTION
`splice_init` is a low level RPC command which initiates a channel splice for a
given channel specified by `channel_id`.
*channel\_id* is the channel id of the channel to be spliced.
*relative\_amount* is a positive or negative amount of satoshis to add or
subtract from the channel.
*initalpsbt* is the (optional) base 64 encoded PSBT to begin with. If not
specified, one will be generated automatically.
*feerate\_per\_kw* is the miner fee we promise our peer to pay for our side of
the splice transaction. It is calculated by `feerate_per_kw` *
our\_bytes\_in\_splice\_tx / 1000.
*force\_feerate* is a boolean flag. By default splices will fail if the fee
provided looks too high. This is to protect against accidentally setting your
fee higher than intended. Set `force_feerate` to true to skip this saftey check.
Note you may need to add a double dash (\-\-) after splice\_init if using a negative
*relative\_amount* so it is not interpretted as a command modifier. For example:
```shell
@ -100,10 +85,12 @@ On success, an object is returned, containing:
SEE ALSO
--------
lightning-splice_signed(7), lightning-splice_update(7)
AUTHOR
------
@dusty\_daemon
Dusty <<@dusty_daemon>> is mainly responsible.
RESOURCES
---------

14
doc/lightning-splice_signed.7.md
View file

@ -3,6 +3,7 @@ lightning-splice\_signed -- Command to initiate a channel to a peer
SYNOPSIS
--------
**(WARNING: experimental-splicing only)**
**splice\_signed** *channel\_id* *psbt* [*sign\_first*]
@ -13,15 +14,6 @@ DESCRIPTION
`splice_signed` is a low level RPC command which finishes the active channel
splice associated with `channel_id`.
*channel\_id* is the channel id of the channel being spliced.
*psbt* is the final version of the psbt to complete the splice with.
*sign\_first* is a flag that makes our node offer the final splice signature
first (defaults to false). When false, the node will calculate who should
sign first based off who is adding inputting the least sats to the splice as per
spec.
The *psbt* must have all signatures attached to all inputs that you have added
to it or it will fail.
@ -82,10 +74,12 @@ On success, an object is returned, containing:
SEE ALSO
--------
lightning-splice_init(7), lightning-splice_update(7)
AUTHOR
------
@dusty\_daemon
Dusty <<@dusty_daemon>> is mainly responsible.
RESOURCES
---------

10
doc/lightning-splice_update.7.md
View file

@ -3,6 +3,7 @@ lightning-splice\_update -- Command to initiate a channel to a peer
SYNOPSIS
--------
**(WARNING: experimental-splicing only)**
**splice\_update** *channel\_id* *psbt*
@ -13,11 +14,6 @@ DESCRIPTION
`splice_update` is a low level RPC command which updates the active channel
splice associated with `channel_id`.
*channel\_id* is the channel id of the channel being spliced.
*psbt* is the base 64 encoded PSBT returned from `splice_init` with any changes
added by the user.
`splice_update` must be called repeatidly until the result `commitments_secured`
is `true`. Each time `splice_update` is called, it will return a new PSBT that
may have changes. In the simplest case, you take the returned `psbt` and pass
@ -95,10 +91,12 @@ On success, an object is returned, containing:
SEE ALSO
--------
lightning-splice_init(7), lightning-splice_signed(7)
AUTHOR
------
@dusty\_daemon
Dusty <<@dusty_daemon>> is mainly responsible.
RESOURCES
---------

32
doc/lightning-sql.7.md
View file

@ -26,38 +26,39 @@ TREATMENT OF TYPES
------------------
The following types are supported in schemas, and this shows how they
are presented in the database. This matters: a JSON boolean is
are presented in the database. This matters: a JSON boolean is
represented as an integer in the database, so a query will return 0 or
1, not true or false.
* *hex*. A hex string.
* *hex*. A hex string.
* JSON: a string
* sqlite3: BLOB
* *hash*/*secret*/*pubkey*/*txid*: just like *hex*.
* *msat*/*integer*/*u64*/*u32*/*u16*/*u8*. Normal numbers.
* *msat*/*integer*/*u64*/*u32*/*u16*/*u8*. Normal numbers.
* JSON: an unsigned integer
* sqlite3: INTEGER
* *boolean*. True or false.
* *boolean*. True or false.
* JSON: literal **true** or **false**
* sqlite3: INTEGER
* *number*. A floating point number (used for times in some places).
* *number*. A floating point number (used for times in some places).
* JSON: number
* sqlite3: REAL
* *string*. Text.
* *string*. Text.
* JSON: string
* sqlite3: TEXT
* *short\_channel\_id*. A short-channel-id of form 1x2x3.
* *short\_channel\_id*. A short-channel-id of form 1x2x3.
* JSON: string
* sqlite3: TEXT
PERMITTED SQLITE3 FUNCTIONS
---------------------------
Writing to the database is not permitted, and limits are placed
on various other query parameters.
@ -80,9 +81,10 @@ Additionally, only the following functions are allowed:
TABLES
------
Note that the first column of every table is a unique integer called
`rowid`: this is used for related tables to refer to specific rows in
their parent. sqlite3 usually has this as an implicit column, but we
their parent. sqlite3 usually has this as an implicit column, but we
make it explicit as the implicit version is not allowed to be used as
a foreign key.
@ -416,15 +418,19 @@ RETURN VALUE
------------
[comment]: # (FIXME: we don't handle this schema in fromschema.py)
On success, an object containing **rows** is returned. It is an array. Each array entry contains an array of values, each an integer, real number, string or *null*, depending on the sqlite3 type.
On success, an object containing **rows** is returned. It is an array. Each array entry contains an array of values, each an integer, real number, string or *null*, depending on the sqlite3 type.
The object may contain **warning\_db\_failure** if the database fails partway through its operation.
ERRORS
------
On failure, an error is returned.
EXAMPLES
--------
Here are some example using lightning-cli. Note that you may need to
EXAMPLE USAGE
-------------
Here are some example using lightning-cli. Note that you may need to
use `-o` if you use queries which contain `=` (which make
lightning-cli(1) default to keyword style):
@ -506,7 +512,7 @@ $ lightning-cli sql -o "SELECT nodeid, alias, nodes_addresses.type, nodes_addres
}
```
Simple function usage, in this case COUNT. Strings inside arrays need
Simple function usage, in this case COUNT. Strings inside arrays need
", and ' to protect them from the shell:
```

1
doc/lightning-stop.7.md
View file

@ -13,6 +13,7 @@ The **stop** is a RPC command to shut off the Core Lightning node.
EXAMPLE JSON REQUEST
------------
```json
{
"id": 82,

Some files were not shown because too many files have changed in this diff Show more