Offers

.github/workflows/docker-image.yml

@@ -3,8 +3,6 @@ name: Docker Image CI
 on:
   push:
     branches: [ master ]
-  pull_request:
-    branches: [ master ]
 
 jobs:
 

.github/workflows/latest-bitcoind.yml

@@ -5,6 +5,9 @@ on:
     # Run at midnight on Sunday and Wednesday.
     - cron: '0 0 * * 0,3'
 
+permissions:
+  contents: read
+
 jobs:
 
   regression-tests:
@@ -18,7 +21,7 @@ jobs:
           path: bitcoin
 
       - name: Install bitcoind dependencies
-        run: sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 libssl-dev libevent-dev libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-test-dev libboost-thread-dev libminiupnpc-dev libzmq3-dev libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler git libsqlite3-dev ccache
+        run: sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 libevent-dev libboost-dev                                                                                          libminiupnpc-dev libnatpmp-dev    libzmq3-dev                                        libsqlite3-dev            systemtap-sdt-dev
         working-directory: ./bitcoin
 
       - name: Autogen bitcoind

.github/workflows/main.yml

@@ -10,7 +10,7 @@ jobs:
 
   build:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
 
     steps:
     - uses: actions/checkout@v2

CONTRIBUTING.md

@@ -30,8 +30,9 @@ 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)
+- [t-bast's in-depth articles about the Lightning Network](https://github.com/t-bast/lightning-docs/)
 
 ## Recommended Skillset
 
@@ -82,6 +83,12 @@ The reason for this is two fold: it makes it easier for the reviewer to see what
 made between versions (since Github doesn't easily show prior versions) and it makes it easier on
 the PR author as they can set it to auto-squash the fixup commits on rebase.
 
+When you have addressed a pull request comment, you should respond to it and point the reviewer
+to the commit where you fixed it. A simple "This is fixed in <link_to_commit>" is enough. Do not
+mark the comment as resolved: let the reviewer verify your commit, they will mark the comment
+resolved if they agree with the fix. This makes it easier for reviewers to check that all their
+comments have been addressed.
+
 It's recommended to take great care in writing tests and ensuring the entire test suite has a
 stable successful outcome; eclair uses continuous integration techniques and having a stable build
 helps the reviewers with their job.
@@ -140,6 +147,14 @@ If your contribution is adding a new dependency, please detail:
 Contributions that add new dependencies may take longer to approve because a detailed audit of the
 dependency may be required.
 
+### Testing
+
+Your code should be tested. We use ScalaTest as a testing framework.
+
+ScalaTest's approach is to parallelize on test suites rather than individual tests, therefore it is
+recommended to keep the execution time of each test suite under one minute and split tests across
+multiple smaller suites if needed.
+
 ### IntelliJ Tips
 
 If you're using [IntelliJ](https://www.jetbrains.com/idea/), here are some useful commands:

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,15 +169,22 @@ 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
 ```
 
 ### Backup
 
-The files that you need to backup are located in your data directory. You must backup:
+You need to backup:
+- 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 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:
 
 * 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)
@@ -198,7 +206,8 @@ before copying that file to your final backup location.
 
 ## Docker
 
-A [Dockerfile](Dockerfile) image is built on each commit on [docker hub](https://hub.docker.com/r/acinq/eclair) for running a dockerized eclair-node.
+A [Dockerfile](Dockerfile) x86_64 image is built on each commit on [docker hub](https://hub.docker.com/r/acinq/eclair) for running a dockerized eclair-node.
+For arm64 platforms you can use an [arm64 Dockerfile](contrib/arm64v8.Dockerfile) to build your own arm64 container. 
 
 You can use the `JAVA_OPTS` environment variable to set arguments to `eclair-node`.
 
@@ -212,7 +221,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
@@ -232,14 +241,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
@@ -248,7 +257,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
@@ -265,6 +274,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

contrib/arm64v8.Dockerfile

@@ -0,0 +1,65 @@
+FROM eclipse-temurin:11-jdk-jammy as BUILD
+
+# Setup maven, we don't use https://hub.docker.com/_/maven/ as it declare .m2 as volume, we loose all mvn cache
+# We can alternatively do as proposed by https://github.com/carlossg/docker-maven#packaging-a-local-repository-with-the-image
+# this was meant to make the image smaller, but we use multi-stage build so we don't care
+RUN apt update && apt install -y curl tar bash
+
+ARG MAVEN_VERSION=3.6.3
+ARG USER_HOME_DIR="/root"
+ARG SHA=c35a1803a6e70a126e80b2b3ae33eed961f83ed74d18fcd16909b2d44d7dada3203f1ffe726c17ef8dcca2dcaa9fca676987befeadc9b9f759967a8cb77181c0
+ARG BASE_URL=https://apache.osuosl.org/maven/maven-3/${MAVEN_VERSION}/binaries
+
+RUN mkdir -p /usr/share/maven /usr/share/maven/ref \
+  && curl -fsSL -o /tmp/apache-maven.tar.gz ${BASE_URL}/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
+  && echo "${SHA}  /tmp/apache-maven.tar.gz" | sha512sum -c - \
+  && tar -xzf /tmp/apache-maven.tar.gz -C /usr/share/maven --strip-components=1 \
+  && rm -f /tmp/apache-maven.tar.gz \
+  && ln -s /usr/share/maven/bin/mvn /usr/bin/mvn
+
+ENV MAVEN_HOME /usr/share/maven
+ENV MAVEN_CONFIG "$USER_HOME_DIR/.m2"
+
+# Let's fetch eclair dependencies, so that Docker can cache them
+# This way we won't have to fetch dependencies again if only the source code changes
+# The easiest way to reliably get dependencies is to build the project with no sources
+WORKDIR /usr/src
+COPY pom.xml pom.xml
+COPY eclair-core/pom.xml eclair-core/pom.xml
+COPY eclair-front/pom.xml eclair-front/pom.xml
+COPY eclair-node/pom.xml eclair-node/pom.xml
+COPY eclair-node/modules/assembly.xml eclair-node/modules/assembly.xml
+RUN mkdir -p eclair-core/src/main/scala && touch eclair-core/src/main/scala/empty.scala
+# Blank build. We only care about eclair-node, and we use install because eclair-node depends on eclair-core
+RUN mvn install -pl eclair-node -am
+RUN mvn clean
+
+# Only then do we copy the sources
+COPY . .
+
+# And this time we can build in offline mode, specifying 'notag' instead of git commit
+RUN mvn package -pl eclair-node -am -DskipTests -Dgit.commit.id=notag -Dgit.commit.id.abbrev=notag -o
+# It might be good idea to run the tests here, so that the docker build fail if the code is bugged
+
+# We currently use a debian image for runtime because of some jni-related issue with sqlite
+FROM openjdk:11.0.4-jre-slim
+WORKDIR /app
+
+# install jq for eclair-cli
+RUN apt-get update && apt-get install -y bash jq curl unzip
+
+# copy and install eclair-cli executable
+COPY --from=BUILD /usr/src/eclair-core/eclair-cli .
+RUN chmod +x eclair-cli && mv eclair-cli /sbin/eclair-cli
+
+# we only need the eclair-node.zip to run
+COPY --from=BUILD /usr/src/eclair-node/target/eclair-node-*.zip ./eclair-node.zip
+RUN unzip eclair-node.zip && mv eclair-node-* eclair-node && chmod +x eclair-node/bin/eclair-node.sh
+
+ENV ECLAIR_DATADIR=/data
+ENV JAVA_OPTS=
+
+RUN mkdir -p "$ECLAIR_DATADIR"
+VOLUME [ "/data" ]
+
+ENTRYPOINT JAVA_OPTS="${JAVA_OPTS}" eclair-node/bin/eclair-node.sh "-Declair.datadir=${ECLAIR_DATADIR}"

docs/API.md

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

docs/Architecture.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)