mirror of
https://github.com/ACINQ/eclair.git
synced 2025-01-18 21:32:50 +01:00
Convert wiki pages in to files in the docs directory and general docs file cleanups (#2165)
Created new files for pages that were in the wiki, but not already in the docs directory. Also made following fixes to README.md and existing files in the docs directory: * update bolt links to avoid redirect * link to logging guide from logging section (README.md) * fixed typo in Backup section and capitalization of Bitcoin Core (README.md) * Alice does not need trampoline feature enabled (TrampolinePayments.md) * link to 2021 edition of Trampoline PR (TrampolinePayments.md) * fixed API examples and removed quotes from password (API.md) * use --nodeIds for sendtoroute examples (TrampolinePayments.md and MultipartPayments.md) * update CLI example 3 to use jq (Usage.md) * fix typo in docs/FAQ.md * updated Guide.md to point to all pages that are guides
This commit is contained in:
Richard Myers
GitHub
parent
fa31d81d0e
commit
553727cb22
@ -30,7 +30,7 @@ You can also use Github issues for [feature requests](https://github.com/acinq/e
|
||||
- [Lightning Network Whitepaper](https://lightning.network/lightning-network-paper.pdf)
|
||||
- [Deployable Lightning](https://github.com/ElementsProject/lightning/raw/master/doc/deployable-lightning.pdf)
|
||||
- [Understanding the Lightning Network](https://bitcoinmagazine.com/articles/understanding-the-lightning-network-part-building-a-bidirectional-payment-channel-1464710791)
|
||||
- [Lightning Network Specification](https://github.com/lightningnetwork/lightning-rfc)
|
||||
- [Lightning Network Specification](https://github.com/lightning/bolts)
|
||||
- [High Level Lightning Network Specification](https://medium.com/@rusty_lightning/the-bitcoin-lightning-spec-part-1-8-a7720fb1b4da)
|
||||
|
||||
## Recommended Skillset
|
||||
|
||||
38
README.md
38
README.md
@ -6,7 +6,7 @@
|
||||
|
||||
**Eclair** (French for Lightning) is a Scala implementation of the Lightning Network.
|
||||
|
||||
This software follows the [Lightning Network Specifications (BOLTs)](https://github.com/lightningnetwork/lightning-rfc). Other implementations include [c-lightning](https://github.com/ElementsProject/lightning), [lnd](https://github.com/LightningNetwork/lnd), [electrum](https://github.com/spesmilo/electrum/), and [rust-lightning](https://github.com/rust-bitcoin/rust-lightning).
|
||||
This software follows the [Lightning Network Specifications (BOLTs)](https://github.com/lightning/bolts). Other implementations include [c-lightning](https://github.com/ElementsProject/lightning), [lnd](https://github.com/LightningNetwork/lnd), [electrum](https://github.com/spesmilo/electrum/), and [rust-lightning](https://github.com/rust-bitcoin/rust-lightning).
|
||||
|
||||
---
|
||||
|
||||
@ -25,6 +25,7 @@ This software follows the [Lightning Network Specifications (BOLTs)](https://git
|
||||
* [Docker](#docker)
|
||||
* [Plugins](#plugins)
|
||||
* [Testnet usage](#testnet-usage)
|
||||
* [Tools](#tools)
|
||||
* [Resources](#resources)
|
||||
|
||||
---
|
||||
@ -43,10 +44,10 @@ For more information please visit the [API documentation website](https://acinq.
|
||||
|
||||
## Documentation
|
||||
|
||||
Please visit our [docs](./docs) and [wiki](https://github.com/acinq/eclair/wiki) to find detailed instructions on how to configure your
|
||||
node, connect to other nodes, open channels, send and receive payments, and more advanced scenario.
|
||||
Please visit our [docs](./docs) folder to find detailed instructions on how to [configure](./docs/Configure.md) your
|
||||
node, connect to other nodes, open channels, send and receive payments, and help with more advanced scenarios.
|
||||
|
||||
You will find detailed guides and frequently asked questions there.
|
||||
You will also find detailed [guides](./docs/Guides.md) and [frequently asked questions](./docs/FAQ.md) there.
|
||||
|
||||
## Installation
|
||||
|
||||
@ -95,7 +96,7 @@ Then download our latest [release](https://github.com/ACINQ/eclair/releases), un
|
||||
eclair-node-<version>-<commit_id>/bin/eclair-node.sh
|
||||
```
|
||||
|
||||
You can then control your node via the [eclair-cli](https://github.com/ACINQ/eclair/wiki/Usage) or the [API](https://github.com/ACINQ/eclair/wiki/API).
|
||||
You can then control your node via [eclair-cli](./docs/Usage.md) or the [API](./docs/API.md).
|
||||
|
||||
:warning: Be careful when following tutorials/guides that may be outdated or incomplete. You must thoroughly read the official eclair documentation before running your own node.
|
||||
|
||||
@ -168,7 +169,7 @@ eclair-node-<version>-<commit_id>/bin/eclair-node.sh -Declair.datadir=/tmp/node1
|
||||
|
||||
### Logging
|
||||
|
||||
Eclair uses [`logback`](https://logback.qos.ch) for logging. To use a different configuration, and override the internal logback.xml, run:
|
||||
Eclair uses [`logback`](https://logback.qos.ch) for logging. To use a [different configuration](./docs/Logging.md), and override the internal logback.xml, run:
|
||||
|
||||
```shell
|
||||
eclair-node-<version>-<commit_id>/bin/eclair-node.sh -Dlogback.configurationFile=/path/to/logback-custom.xml
|
||||
@ -177,13 +178,13 @@ eclair-node-<version>-<commit_id>/bin/eclair-node.sh -Dlogback.configurationFile
|
||||
### Backup
|
||||
|
||||
You need to backup:
|
||||
- your bitcoin core wallet
|
||||
- your eclair channels
|
||||
- your Bitcoin Core wallet
|
||||
- your Eclair channels
|
||||
|
||||
For bitcoin core, you need to backup the wallet file for the wallet that eclair is using. You only need to this once, when the wallet is
|
||||
created (see https://github.com/bitcoin/bitcoin/blob/master/doc/managing-wallets.md for more information).
|
||||
For Bitcoin Core, you need to backup the wallet file for the wallet that Eclair is using. You only need to do this once, when the wallet is
|
||||
created. See [Managing Wallets](https://github.com/bitcoin/bitcoin/blob/master/doc/managing-wallets.md) in the Bitcoin Core documentation for more information.
|
||||
|
||||
For eclair, the files that you need to backup are located in your data directory. You must backup:
|
||||
For Eclair, the files that you need to backup are located in your data directory. You must backup:
|
||||
|
||||
* your seeds (`node_seed.dat` and `channel_seed.dat`)
|
||||
* your channel database (`eclair.sqlite.bak` under directory `mainnet`, `testnet` or `regtest` depending on which chain you're running on)
|
||||
@ -219,7 +220,7 @@ If you want to persist the data directory, you can make the volume to your host
|
||||
docker run -ti --rm -v "/path_on_host:/data" -e "JAVA_OPTS=-Declair.printToConsole" acinq/eclair
|
||||
```
|
||||
|
||||
If you enabled the API you can check the status of eclair using the command line tool:
|
||||
If you enabled the API you can check the status of Eclair using the command line tool:
|
||||
|
||||
```shell
|
||||
docker exec <container_name> eclair-cli -p foobar getinfo
|
||||
@ -239,14 +240,14 @@ eclair-node-<version>-<commit_id>/bin/eclair-node.sh <plugin1.jar> <plugin2.jar>
|
||||
|
||||
### Non-exhaustive plugins list
|
||||
|
||||
Here are some plugins created by the eclair community.
|
||||
Here are some plugins created by the Eclair community.
|
||||
If you need support for these plugins, head over to their respective github repository.
|
||||
|
||||
* [Telegram Bot for eclair alerts](https://github.com/engenegr/eclair-alarmbot-plugin)
|
||||
* [Telegram Bot for Eclair alerts](https://github.com/engenegr/eclair-alarmbot-plugin)
|
||||
|
||||
## Testnet usage
|
||||
|
||||
Eclair is configured to run on mainnet by default, but you can still run it on testnet (or regtest): start your Bitcoin Node in
|
||||
Eclair is configured to run on mainnet by default, but you can still run it on testnet (or regtest): start your Bitcoin node in
|
||||
testnet mode (add `testnet=1` in `bitcoin.conf` or start with `-testnet`), and change Eclair's chain parameter and Bitcoin RPC port:
|
||||
|
||||
```conf
|
||||
@ -255,7 +256,7 @@ eclair.bitcoind.rpcport=18332
|
||||
```
|
||||
|
||||
You may also want to take advantage of the new configuration sections in `bitcoin.conf` to manage parameters that are network specific,
|
||||
so you can easily run your bitcoin node on both mainnet and testnet. For example you could use:
|
||||
so you can easily run your Bitcoin node on both mainnet and testnet. For example you could use:
|
||||
|
||||
```conf
|
||||
server=1
|
||||
@ -272,6 +273,11 @@ zmqpubhashblock=tcp://127.0.0.1:29001
|
||||
zmqpubrawtx=tcp://127.0.0.1:29001
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
* [Demo Shop](https://starblocks.acinq.co/) - an example testnet Lightning web shop.
|
||||
* [Network Explorer](https://explorer.acinq.co/) - a Lightning network visualization tool.
|
||||
|
||||
## Resources
|
||||
|
||||
* [1] [The Bitcoin Lightning Network: Scalable Off-Chain Instant Payments](https://lightning.network/lightning-network-paper.pdf) by Joseph Poon and Thaddeus Dryja
|
||||
|
||||
43
docs/API.md
Normal file
43
docs/API.md
Normal file
@ -0,0 +1,43 @@
|
||||
# API
|
||||
|
||||
Eclair can setup a JSON API on the `eclair.api.port` port set in the [configuration](./Configure.md). You first need to enable it:
|
||||
|
||||
```
|
||||
eclair.api.enabled=true
|
||||
eclair.api.password=changeit
|
||||
```
|
||||
|
||||
:rotating_light: **Attention:** Eclair's API should NOT be accessible from the outside world (similarly to Bitcoin Core API).
|
||||
|
||||
## Payment notification
|
||||
|
||||
Eclair accepts websocket connection on `ws://localhost:<port>/ws`, and emits a message containing the payment hash of a payment when receiving a payment.
|
||||
|
||||
## API calls
|
||||
|
||||
This API exposes all the necessary methods to read the current state of the node, open/close channels and send/receive payments. For the full documentation please visit https://acinq.github.io/eclair
|
||||
|
||||
#### Example: open a channel
|
||||
|
||||
Your node listens on 8081. You want to open a 140 mBTC channel with `endurance.acinq.co` on Testnet with a 30 mBTC `push`
|
||||
|
||||
1/ connect to the node with the URI:
|
||||
|
||||
```shell
|
||||
curl -X POST \
|
||||
-u :api_password \
|
||||
-F uri="03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134@endurance.acinq.co:9735" \
|
||||
http://127.0.0.1:8081/connect
|
||||
```
|
||||
|
||||
2/ Open a channel with this node
|
||||
|
||||
```shell
|
||||
curl -X POST \
|
||||
-u :api_password \
|
||||
-F nodeId=03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134 \
|
||||
-F fundingSatoshis=14000000 \
|
||||
http://127.0.0.1:8081/open
|
||||
```
|
||||
|
||||
Feeling tired of writing all these `curls`? Good news, a CLI bash file is available. It uses this API to interact with your node. More information about `eclair-cli` is [here](./Usage.md).
|
||||
@ -106,13 +106,13 @@ Here is a high-level view of the hierarchy of some of the main actors in the sys
|
||||
And a short description of each actor's role:
|
||||
|
||||
- Switchboard: creates and deletes peers
|
||||
- Peer: p2p connection to another lightning node (standard lightning messages described in [Bolt 1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md))
|
||||
- Channel: channel with another lightning node ([Bolt 2](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md))
|
||||
- Peer: p2p connection to another lightning node (standard lightning messages described in [Bolt 1](https://github.com/lightning/bolts/blob/master/01-messaging.md))
|
||||
- Channel: channel with another lightning node ([Bolt 2](https://github.com/lightning/bolts/blob/master/02-peer-protocol.md))
|
||||
- Register: maps channel IDs to actors (provides a clean boundary between channel and payment components)
|
||||
- PaymentInitiator: entry point for sending payments
|
||||
- Relayer: entry point for relaying payments
|
||||
- PaymentHandler: entry point for receiving payments
|
||||
- Router: p2p gossip and the network graph ([Bolt 7](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md))
|
||||
- Router: p2p gossip and the network graph ([Bolt 7](https://github.com/lightning/bolts/blob/master/07-routing-gossip.md))
|
||||
|
||||
Actors have two ways of communicating:
|
||||
|
||||
@ -128,7 +128,7 @@ Let's dive into a few payment scenarios to show which actors are involved.
|
||||
When we send a payment:
|
||||
|
||||
- we run a path-finding algorithm (`Router`)
|
||||
- we split the payment into smaller chunks if [MPP](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#basic-multi-part-payments) is used (`MultiPartPaymentLifecycle`)
|
||||
- we split the payment into smaller chunks if [MPP](https://github.com/lightning/bolts/blob/master/04-onion-routing.md#basic-multi-part-payments) is used (`MultiPartPaymentLifecycle`)
|
||||
- we retry with alternative routes in some failure cases and record failing channels/payments (`PaymentLifecycle`)
|
||||
- we add HTLCs to some of our channels
|
||||
|
||||
@ -175,7 +175,7 @@ When we relay a payment:
|
||||
|
||||
- htlcs are forwarded by channels to the relayer
|
||||
- the relayer identifies the type of relay requested and delegates work to a channel relayer or a node relayer
|
||||
- if a node relayer is used ([trampoline payments](https://github.com/lightningnetwork/lightning-rfc/pull/829)):
|
||||
- if a node relayer is used ([trampoline payments](https://github.com/lightning/bolts/pull/829)):
|
||||
- incoming htlcs are validated by a payment handler (similar to the flow to receive payments)
|
||||
- outgoing htlcs are sent out (similar to the flow to send payments)
|
||||
|
||||
|
||||
@ -19,8 +19,7 @@
|
||||
## Configuration file
|
||||
|
||||
The configuration file for eclair is named `eclair.conf`. It is located in the data directory, which is `~/.eclair` by
|
||||
default. Note that eclair won't create a configuration file by itself: if you want to change eclair's configuration, you
|
||||
need to **actually create the configuration file first**. The encoding must be UTF-8.
|
||||
default (on Windows it is `C:\Users\YOUR_NAME\.eclair`). Note that eclair won't create a configuration file by itself: if you want to change eclair's configuration, you need to **actually create the configuration file first**. The encoding must be UTF-8.
|
||||
|
||||
```sh
|
||||
# this is the default data directory, it will be created at eclair first startup
|
||||
|
||||
18
docs/FAQ.md
Normal file
18
docs/FAQ.md
Normal file
@ -0,0 +1,18 @@
|
||||
# FAQ
|
||||
|
||||
## What does it mean for a channel to be "enabled" or "disabled" ?
|
||||
|
||||
A channel is disabled if a `channel_update` message has been broadcast for that channel with the `disable` bit set (see [BOLT 7](https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#the-channel_update-message)). It means that the channel still exists but cannot be used to route payments, until it has been re-enabled.
|
||||
|
||||
Suppose you're A, with the following setup:
|
||||
```
|
||||
A ---ab--> B --bc--> C
|
||||
```
|
||||
And node C goes down. B will publish a channel update for channel `bc` with the `disable` bit set.
|
||||
There are other cases when a channel becomes disabled, for example when its balance goes below reserve...
|
||||
|
||||
Note that you can have multiple channels between the same nodes, and that some of them can be enabled while others are disabled (i.e. enable/disable is channel-specific, not node-specific).
|
||||
|
||||
## How should you stop an Eclair node ?
|
||||
|
||||
To stop your node you just need to kill its process, there is no API command to do this. The JVM handles the quit signal and notifies the node to perform clean-up. For example, there is a hook to cleanly free DB locks when using Postgres.
|
||||
53
docs/Features.md
Normal file
53
docs/Features.md
Normal file
@ -0,0 +1,53 @@
|
||||
# Customize Features
|
||||
|
||||
Eclair ships with a set of features that are activated by default, and some experimental or optional features that can be activated by users.
|
||||
The list of supported features can be found in the [reference configuration](https://github.com/ACINQ/eclair/blob/master/eclair-core/src/main/resources/reference.conf).
|
||||
|
||||
To enable a non-default feature, you simply need to add the following to your `eclair.conf`:
|
||||
|
||||
```conf
|
||||
eclair.features {
|
||||
official_feature_name = optional|mandatory
|
||||
}
|
||||
```
|
||||
|
||||
For example, to activate `option_static_remotekey`:
|
||||
|
||||
```conf
|
||||
eclair.features {
|
||||
option_static_remotekey = optional
|
||||
}
|
||||
```
|
||||
|
||||
Note that you can also disable some default features:
|
||||
|
||||
```conf
|
||||
eclair.features {
|
||||
initial_routing_sync = disabled
|
||||
}
|
||||
```
|
||||
|
||||
It's usually risky to activate non-default features or disable default features: make sure you fully understand a feature (and the current implementation status, detailed in the release notes) before doing so.
|
||||
|
||||
Eclair supports per-peer features. Suppose you are connected to Alice and Bob, you can use a different set of features with Alice than the one you use with Bob. When experimenting with non-default features, we recommend using this to scope the peers you want to experiment with.
|
||||
|
||||
This is done with the `override-features` configuration parameter in your `eclair.conf`:
|
||||
|
||||
```conf
|
||||
eclair.override-features = [
|
||||
{
|
||||
nodeId = "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f"
|
||||
features {
|
||||
initial_routing_sync = disabled
|
||||
option_static_remotekey = optional
|
||||
}
|
||||
},
|
||||
{
|
||||
nodeId = "<another nodeId>"
|
||||
features {
|
||||
option_static_remotekey = optional
|
||||
option_support_large_channel = optional
|
||||
}
|
||||
},
|
||||
]
|
||||
```
|
||||
14
docs/Guides.md
Normal file
14
docs/Guides.md
Normal file
@ -0,0 +1,14 @@
|
||||
# Guides
|
||||
|
||||
This section contains how-to guides for more advanced scenarios:
|
||||
|
||||
* [Customize Logging](./Logging.md)
|
||||
* [Customize Features](./Features.md)
|
||||
* [Use Tor with Eclair](./Tor.md)
|
||||
* [Multipart Payments](./MultipartPayments.md)
|
||||
* [Trampoline Payments](./TrampolinePayments.md)
|
||||
* [Monitoring Eclair](./Monitoring.md)
|
||||
* [PostgreSQL Configuration](./PostgreSQL.md)
|
||||
* [Perform Circular Rebalancing](./CircularRebalancing.md)
|
||||
* [Clusterize your Eclair node](./Cluster.md)
|
||||
* [Architecture of Eclair code](./Architecture.md)
|
||||
60
docs/Logging.md
Normal file
60
docs/Logging.md
Normal file
@ -0,0 +1,60 @@
|
||||
# Logging
|
||||
|
||||
### Customize Logging
|
||||
|
||||
Eclair uses [logback](https://logback.qos.ch/) for logging.
|
||||
By default the logging level is set to `INFO` for the whole application.
|
||||
To use a different configuration, and override the internal `logback.xml`, run:
|
||||
|
||||
```shell
|
||||
eclair-node.sh -Dlogback.configurationFile=/path/to/logback-custom.xml
|
||||
```
|
||||
|
||||
If you want parts of the application to log at the `DEBUG` logging level, you will also need to override `akka.loglevel`:
|
||||
|
||||
```shell
|
||||
eclair-node.sh -Dakka.loglevel=DEBUG -Dlogback.configurationFile=/path/to/logback-custom.xml
|
||||
```
|
||||
|
||||
You can find the default `logback.xml` file [here](https://github.com/ACINQ/eclair/blob/master/eclair-node/src/main/resources/logback.xml). It logs everything more serious than `INFO` to a rolling file.
|
||||
|
||||
If you want to debug an issue, you can change the root logger's log level to `DEBUG`:
|
||||
|
||||
```xml
|
||||
<root level="DEBUG">
|
||||
<appender-ref ref="ROLLING"/>
|
||||
</root>
|
||||
```
|
||||
|
||||
This setting will produce a lot of logs. If you are investigating an issue with payments, you can instead turn on `DEBUG` logging only for payments-related components by adding a new `logger` before the `root`:
|
||||
|
||||
```xml
|
||||
<logger name="fr.acinq.eclair.payment" level="DEBUG"/>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="ROLLING"/>
|
||||
</root>
|
||||
```
|
||||
|
||||
On the contrary, if you want a component to emit less logs, you can set its log level to `WARN` or `ERROR`:
|
||||
|
||||
```xml
|
||||
<logger name="fr.acinq.eclair.router" level="WARN"/>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="ROLLING"/>
|
||||
</root>
|
||||
```
|
||||
|
||||
To figure out the `name` you should use for the `logger` element, you need to look at the hierarchy of the source code in Eclair's [Github repository](https://github.com/ACINQ/eclair). You can even configure loggers for each specific class you're interested in:
|
||||
|
||||
```xml
|
||||
<logger name="fr.acinq.eclair.router" level="WARN"/>
|
||||
<logger name="fr.acinq.eclair.crypto.Sphinx" level="DEBUG"/>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="ROLLING"/>
|
||||
</root>
|
||||
```
|
||||
|
||||
For more advanced use-cases, please see logback's [official documentation](https://logback.qos.ch/documentation.html).
|
||||
80
docs/MultipartPayments.md
Normal file
80
docs/MultipartPayments.md
Normal file
@ -0,0 +1,80 @@
|
||||
# Multipart Payments
|
||||
|
||||
Eclair started supporting [multi-part payments](https://github.com/lightning/bolts/blob/master/04-onion-routing.md#basic-multi-part-payments) in v0.3.3.
|
||||
|
||||
## Receiving multi-part payments
|
||||
|
||||
Once the feature is activated, your eclair node will generate invoices that can be paid using MPP.
|
||||
If the sender also supports MPP, your node will accept the payment.
|
||||
It's as simple as that!
|
||||
|
||||
Here is how you generate an invoice:
|
||||
|
||||
```sh
|
||||
eclair-cli createinvoice --amountMsat=42000000 --description="MPP is #reckless"
|
||||
```
|
||||
|
||||
## Sending multi-part payments
|
||||
|
||||
### With the built-in splitting algorithm
|
||||
|
||||
If you try paying an invoice that supports MPP, eclair will automatically split the payment (if needed).
|
||||
|
||||
You just need to use the `payinvoice` command, nothing complicated here:
|
||||
|
||||
```sh
|
||||
eclair-cli payinvoice --invoice=lnbc11pdkmqhupp5n2e...
|
||||
```
|
||||
|
||||
However, we are still experimenting with various algorithms to efficiently split payments.
|
||||
You may find that the resulting split looks less optimal that what you expected, in which case the next section is for you!
|
||||
|
||||
### With your own splitting algorithm
|
||||
|
||||
The CLI allows you to fully control how your payment is split and sent. This is a good way to start experimenting with MPP.
|
||||
|
||||
Let's imagine that the network looks like this:
|
||||
|
||||
```txt
|
||||
+------- Bob -------+
|
||||
| |
|
||||
Alice Dave
|
||||
| |
|
||||
+------- Carol -----+
|
||||
|
||||
```
|
||||
|
||||
Dave has generated an MPP invoice for 400000 msat: `lntb1500n1pwxx94fp...`.
|
||||
|
||||
You want to send 150000 msat through Bob and 250000 msat through Carol.
|
||||
|
||||
Initiate the payment by sending the first part:
|
||||
|
||||
```sh
|
||||
eclair-cli sendtoroute --amountMsat=150000 --nodeIds=$ALICE_ID,$BOB_ID,$DAVE_ID --finalCltvExpiry=16 --invoice=lntb1500n1pwxx94fp...
|
||||
```
|
||||
|
||||
This will return some identifiers that must be used for the other parts:
|
||||
|
||||
```json
|
||||
{
|
||||
"paymentId": "4e8f2440-dbfd-4e76-bb45-a0647a966b2a",
|
||||
"parentId": "cd083b31-5939-46ac-bf90-8ac5b286a9e2"
|
||||
}
|
||||
```
|
||||
|
||||
The `parentId` is important: this is the identifier used to link the parts together.
|
||||
|
||||
Now that you have those, you can send the second part:
|
||||
|
||||
```sh
|
||||
eclair-cli sendtoroute --parentId=cd083b31-5939-46ac-bf90-8ac5b286a9e2 --amountMsat=250000 --nodeIds=$ALICE_ID,$CAROL_ID,$DAVE_ID --finalCltvExpiry=16 --invoice=lntb1500n1pwxx94fp...
|
||||
```
|
||||
|
||||
You can then check the status of the payment with the `getsentinfo` command:
|
||||
|
||||
```sh
|
||||
eclair-cli getsentinfo --id=cd083b31-5939-46ac-bf90-8ac5b286a9e2
|
||||
```
|
||||
|
||||
Once Dave accepts the HTLCs you should see all the details about the payment success (preimage, route, fees, etc).
|
||||
68
docs/TrampolinePayments.md
Normal file
68
docs/TrampolinePayments.md
Normal file
@ -0,0 +1,68 @@
|
||||
# Trampoline Payments
|
||||
|
||||
Eclair started supporting [trampoline payments](https://github.com/lightning/bolts/pull/829) in v0.3.3.
|
||||
|
||||
It is disabled by default, as it is still being reviewed for spec acceptance. However, if you want to experiment with it, here is what you can do.
|
||||
|
||||
First of all, you need to activate the feature for any node that will act as s trampoline node. Update your `eclair.conf` with the following values:
|
||||
|
||||
```conf
|
||||
eclair.trampoline-payments-enable=true
|
||||
```
|
||||
|
||||
## Sending trampoline payments
|
||||
|
||||
The CLI allows you to fully control how your payment is split and sent. This is a good way to start experimenting with Trampoline.
|
||||
|
||||
Let's imagine that the network looks like this:
|
||||
|
||||
```txt
|
||||
Alice -----> Bob -----> Carol -----> Dave
|
||||
```
|
||||
|
||||
Where Bob is a trampoline node and Alice, Carol and Dave are "normal" nodes.
|
||||
|
||||
Let's imagine that Dave has generated an MPP invoice for 400000 msat: `lntb1500n1pwxx94fp...`.
|
||||
Alice wants to pay that invoice using Bob as a trampoline.
|
||||
To spice things up, Alice will use MPP between Bob and her, splitting the payment in two parts.
|
||||
|
||||
Initiate the payment by sending the first part:
|
||||
|
||||
```sh
|
||||
eclair-cli sendtoroute --amountMsat=150000 --nodeIds=$ALICE_ID,$BOB_ID --trampolineNodes=$BOB_ID,$DAVE_ID --trampolineFeesMsat=100000 --trampolineCltvExpiry=450 --finalCltvExpiry=16 --invoice=lntb1500n1pwxx94fp...
|
||||
```
|
||||
|
||||
Note the `trampolineFeesMsat` and `trampolineCltvExpiry`. At the moment you have to estimate those yourself. If the values you provide are too low, Bob will send an error and you can retry with higher values. In future versions, we will automatically fill those values for you.
|
||||
|
||||
The command will return some identifiers that must be used for the other parts:
|
||||
|
||||
```json
|
||||
{
|
||||
"paymentId": "4e8f2440-dbfd-4e76-bb45-a0647a966b2a",
|
||||
"parentId": "cd083b31-5939-46ac-bf90-8ac5b286a9e2",
|
||||
"trampolineSecret": "9e13d1b602496871bb647b48e8ff8f15a91c07affb0a3599e995d470ac488715"
|
||||
}
|
||||
```
|
||||
|
||||
The `parentId` is important: this is the identifier used to link the MPP parts together.
|
||||
|
||||
The `trampolineSecret` is also important: this is what prevents a malicious trampoline node from stealing money.
|
||||
|
||||
Now that you have those, you can send the second part:
|
||||
|
||||
```sh
|
||||
eclair-cli sendtoroute --amountMsat=250000 --parentId=cd083b31-5939-46ac-bf90-8ac5b286a9e2 --trampolineSecret=9e13d1b602496871bb647b48e8ff8f15a91c07affb0a3599e995d470ac488715 --nodeIds=$ALICE_ID,$BOB_ID --trampolineNodes=$BOB_ID,$DAVE_ID --trampolineFeesMsat=100000 --trampolineCltvExpiry=450 --finalCltvExpiry=16 --invoice=lntb1500n1pwxx94fp...
|
||||
```
|
||||
|
||||
Note that Alice didn't need to know about Carol. Bob will find the route to Dave through Carol on his own. That's the magic of trampoline!
|
||||
|
||||
A couple gotchas: you need to make sure you specify the same `trampolineFeesMsat` and `trampolineCltvExpiry` as the first part. This is something we will improve if our users ask for a better API.
|
||||
|
||||
You can then check the status of the payment with the `getsentinfo` command:
|
||||
|
||||
```sh
|
||||
eclair-cli getsentinfo --id=cd083b31-5939-46ac-bf90-8ac5b286a9e2
|
||||
```
|
||||
|
||||
Once Dave accepts the payment you should see all the details about the payment success (preimage, route, fees, etc).
|
||||
|
||||
90
docs/Usage.md
Normal file
90
docs/Usage.md
Normal file
@ -0,0 +1,90 @@
|
||||
# Usage
|
||||
|
||||
## Command line with eclair-cli
|
||||
|
||||
### Windows user
|
||||
|
||||
On windows, you will have to install Bash first. We recommend installing Git Bash which is packed in the [Git installer from git-scm](https://git-scm.com/downloads).
|
||||
|
||||
Then you'll have to install jq:
|
||||
|
||||
- Get the latest windows version from https://stedolan.github.io/jq/download/
|
||||
- Rename the `jq-win64.exe` file to `jq.exe` and move it to `C:/Users/your_name/bin`
|
||||
|
||||
## eclair-cli installation
|
||||
|
||||
- Download the eclair-cli file from [our sources](https://github.com/ACINQ/eclair/blob/master/eclair-core/eclair-cli)
|
||||
- (optional) Move the file to `~/bin`
|
||||
- Enable the [JSON API](https://github.com/ACINQ/eclair/wiki/API) in your `eclair.conf` settings.
|
||||
|
||||
Run this command to list the available calls:
|
||||
|
||||
```shell
|
||||
./eclair-cli -p <api_password> help
|
||||
```
|
||||
|
||||
ℹ️ **Protip:** you can edit the `eclair-cli` file and save the API password/url so you don't have to set them every time. We will omit them in the examples below.
|
||||
|
||||
Note that you may have to install jq first if it's not already installed on your machine:
|
||||
|
||||
```shell
|
||||
sudo apt-get install jq
|
||||
```
|
||||
|
||||
## Example 1: open a channel with eclair-cli
|
||||
|
||||
Your node listens on 8081. You want to open a 140 mBTC channel with `endurance.acinq.co` on Testnet.
|
||||
|
||||
First connect to the endurance node:
|
||||
|
||||
```shell
|
||||
eclair-cli connect --uri=03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134@endurance.acinq.co:9735
|
||||
```
|
||||
|
||||
Then open a channel with endurance:
|
||||
|
||||
```shell
|
||||
eclair-cli open --nodeId=03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134 --fundingSatoshis=14000000
|
||||
```
|
||||
|
||||
This will broadcast a funding transaction to the bitcoin blockchain.
|
||||
Once that transaction is confirmed, your lightning channel will be ready for off-chain payments.
|
||||
|
||||
:warning: You should NEVER use RBF to bump the fees of that funding transaction, otherwise you won't be able to recover your funds unless your peer cooperates. If the transaction doesn't confirm, you should use CPFP to bump the fees.
|
||||
|
||||
## Example 2: pay an invoice with eclair-cli
|
||||
|
||||
```shell
|
||||
eclair-cli payinvoice --invoice=lntb17u1pdthhsdpp5z5am8.......
|
||||
```
|
||||
|
||||
## Example 3: generate a payment request for 1 mBTC
|
||||
|
||||
```shell
|
||||
eclair-cli createinvoice --amountMsat=100000000 --description="my first invoice" | jq .serialized
|
||||
```
|
||||
|
||||
This command will return a lightning payment request, such as:
|
||||
|
||||
```shell
|
||||
lntb1m1pdthhh0pp5063r8hu6f6hk7tpauhgvl3nnf4ur3xntcnhujcz5w82yq7nhjuysdq6d4ujqenfwfehggrfdemx76trv5xqrrss6uxhewtmjkumpr7w6prkgttku76azfq7l8cx9v74pcv85hzyvs9n23dhu9u354xcqpnzey45ua3g2m4dywuw7udrt2sdsvjf3rawdqcpas9mah
|
||||
```
|
||||
|
||||
You can check this invoice with the `parseinvoice` command:
|
||||
|
||||
```shell
|
||||
eclair-cli parseinvoice --invoice=lntb1m1pdthhh0pp5063r8hu6f6hk7tpauhgvl3nnf4ur3xntcnhujcz5w82yq7nhjuysdq6d4ujqenfwfehggrfdemx76trv5xqrrss6uxhewtmjkumpr7w6prkgttku76azfq7l8cx9v74pcv85hzyvs9n23dhu9u354xcqpnzey45ua3g2m4dywuw7udrt2sdsvjf3rawdqcpas9mah
|
||||
```
|
||||
|
||||
Which will breakdown the invoice in human readable data.
|
||||
|
||||
## Example 4: list local channels in NORMAL state
|
||||
```shell
|
||||
eclair-cli channels | jq '.[] | select(.state == "NORMAL")'
|
||||
```
|
||||
|
||||
## Example 5: compute your total balance across all channels
|
||||
We divide by `1000` because we want satoshis, not millisatoshis.
|
||||
```shell
|
||||
eclair-cli usablebalances | jq 'map(.canSend / 1000) | add'
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user