mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
40fe893172
`"deprecated": true` is obsolete; we don't document them anyway. Where it would have otherwise changed the GRPC wrappers, I actually put the version number in. We allow "listchannels" to have "satoshis" since we have some tests that run in deprecated-api mode. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
122 lines
5.9 KiB
Markdown
122 lines
5.9 KiB
Markdown
lightning-keysend -- Send funds to a node without an invoice
|
|
============================================================
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
**keysend** *destination* *amount\_msat* [*label*] [*maxfeepercent*] [*retry\_for*] [*maxdelay*] [*exemptfee*] [*extratlvs*]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The **keysend** RPC command attempts to find a route to the given destination,
|
|
and send the specified amount to it. Unlike the `pay` RPC command the
|
|
`keysend` command does not require an invoice, instead it uses the
|
|
`destination` node ID, and `amount` to find a route to the specified node.
|
|
|
|
In order for the destination to be able to claim the payment, the
|
|
`payment_key` is randomly generated by the sender and included in the
|
|
encrypted payload for the destination. As a consequence there is not
|
|
proof-of-payment, like there is with an invoice where the `payment_key` is
|
|
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.
|
|
|
|
RANDOMIZATION
|
|
-------------
|
|
|
|
To protect user privacy, the payment algorithm performs some randomization.
|
|
|
|
1: Route Randomization
|
|
|
|
Route randomization means the payment algorithm does not always use the
|
|
lowest-fee or shortest route. This prevents some highly-connected node
|
|
from learning all of the user payments by reducing their fees below the
|
|
network average.
|
|
|
|
2: Shadow Route
|
|
|
|
Shadow route means the payment algorithm will virtually extend the route
|
|
by adding delays and fees along it, making it appear to intermediate nodes
|
|
that the route is longer than it actually is. This prevents intermediate
|
|
nodes from reliably guessing their distance from the payee.
|
|
|
|
Route randomization will never exceed *maxfeepercent* of the payment.
|
|
Route randomization and shadow routing will not take routes that would
|
|
exceed *maxdelay*.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
[comment]: # (GENERATE-FROM-SCHEMA-START)
|
|
On success, an object is returned, containing:
|
|
|
|
- **payment\_preimage** (secret): the proof of payment: SHA256 of this **payment\_hash**
|
|
- **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
|
|
- **created\_at** (number): the UNIX timestamp showing when this payment was initiated
|
|
- **parts** (u32): how many attempts this took
|
|
- **amount\_msat** (msat): Amount the recipient received
|
|
- **amount\_sent\_msat** (msat): Total amount we sent (including fees)
|
|
- **status** (string): status of payment (always "complete")
|
|
- **destination** (pubkey, optional): the final destination of the payment
|
|
|
|
The following warnings may also be returned:
|
|
|
|
- **warning\_partial\_completion**: Not all parts of a multi-part payment have completed
|
|
|
|
[comment]: # (GENERATE-FROM-SCHEMA-END)
|
|
|
|
You can monitor the progress and retries of a payment using the lightning-paystatus(7) command.
|
|
|
|
The following error codes may occur:
|
|
- `-1`: Catchall nonspecific error.
|
|
- `203`: Permanent failure at destination. The *data* field of the error will be routing failure object.
|
|
- `205`: Unable to find a route.
|
|
- `206`: Route too expensive. Either the fee or the needed total locktime for the route exceeds your *maxfeepercent* or *maxdelay* settings, respectively. The *data* field of the error will indicate the actual *fee* as well as the *feepercent* percentage that the fee has of the destination payment amount. It will also indicate the actual *delay* along the route.
|
|
- `210`: Payment timed out without a payment in progress.
|
|
|
|
A routing failure object has the fields below:
|
|
- `erring_index`: The index of the node along the route that reported the error. 0 for the local node, 1 for the first hop, and so on.
|
|
- `erring_node`: The hex string of the pubkey id of the node that reported the error.
|
|
- `erring_channel`: The short channel ID of the channel that has the error, or *0:0:0* if the destination node raised the error.
|
|
- `failcode`: The failure code, as per BOLT \#4.
|
|
- `channel_update`. The hex string of the *channel\_update* message received from the remote node. Only present if error is from the remote node and the *failcode* has the `UPDATE` bit set, as per BOLT \#4.
|
|
|
|
|
|
AUTHOR
|
|
------
|
|
|
|
Christian Decker <<decker@blockstream.com>> is mainly responsible.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
lightning-listpays(7), lightning-decodepay(7), lightning-listinvoice(7),
|
|
lightning-delinvoice(7), lightning-getroute(7), lightning-invoice(7).
|
|
|
|
RESOURCES
|
|
---------
|
|
|
|
Main web site: <https://github.com/ElementsProject/lightning>
|
|
|
|
[comment]: # ( SHA256STAMP:326cebe5519961ab09dfc2892aa67932b6c3365394317a630d94b4e10082203e)
|