Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: change c-lightning to core lightning #597

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion 01_0_Introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The ways that we make payments for goods and services has been changing dramatic

These centralization risks were some of the prime catalysts behind the creation of cryptocurrencies, the first and most successful of which is Bitcoin. Bitcoin offers pseudonymity; it makes it difficult to correlate transactions; and it makes censorship by individual entities all but impossible. These advantages have made it one of the quickest growing currencies in the world. That growth in turn has made Bitcoin into a going concern among entrepreneurs and developers, eager to create new services for the Bitcoin community.

If you're one of those entrepreneurs or developers, then this course is for you, because it's all about learning to program Bitcoin. It's an introductory course that explains all the nuances and features of Bitcoin as it goes. It also takes a very specific tack, by offering lessons in how to work _directly_ with Bitcoin Core and with the c-lightning server using their RPC interfaces.
If you're one of those entrepreneurs or developers, then this course is for you, because it's all about learning to program Bitcoin. It's an introductory course that explains all the nuances and features of Bitcoin as it goes. It also takes a very specific tack, by offering lessons in how to work _directly_ with Bitcoin Core and with the core lightning server using their RPC interfaces.

Why not use some of the more fully featured libraries found in various programming languages? Why not create your own from scratch? It's because working with cryptocurrency is dangerous. There are no safety nets. If you accidentally overpay your fees or lose a signing key or create an invalid transaction or make any number of potential mistakes, then your cryptocurrency will be gone forever. Much of that responsibility will, of course, lie with you as a cryptocurrency programmer, but it can be minimized by working with the most robust, secure, and safe cryptocurrency interfaces around, the ones created by the cryptocurrency programming teams themselves: ``bitcoind`` and ``lightningd``.

Expand Down
2 changes: 1 addition & 1 deletion 01_1_Introducing_Bitcoin.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Lightning is a layer-2 protocol that interacts with Bitcoin to allow users to ex

Lightning is also the secondary focus of this tutorial. Though it's mostly about interacting directly with Bitcoin (and the `bitcoind`), it pays some attention to Lightning because it's an upcoming technology that is likely to become a popular alternative to Bitcoin in the near future. This book takes the same approach to Lightning as to Bitcoin: it teaches how to interact directly with a trusted Lightning daemon from the command line.

Unlike with Bitcoin, there are actually several variants of Lightning. This tutorial uses the standard-compliant [c-lightning](https://github.com/ElementsProject/lightning) implementation as its trusted Lightning server.
Unlike with Bitcoin, there are actually several variants of Lightning. This tutorial uses the standard-compliant [core lightning](https://github.com/ElementsProject/lightning) implementation as its trusted Lightning server.

**_What is a Layer-2 Protocol?_** A layer-2 Bitcoin protocol works on top of Bitcoin. In this case, Lightning works atop Bitcoin, interacting with it through smart contracts.

Expand Down
8 changes: 4 additions & 4 deletions 19_0_Understanding_Your_Lightning_Setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

> :information_source: **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.

The previous chapter concluded our work with Bitcoin proper, through CLI, scripting, and programming languages. However, there are many other utilities within the Bitcoin ecosystem: this chapter and the next cover what may be the biggest and most important: the Lightning Network. Here you'll begin work with the `lightning-cli` command-line interface, understanding a c-lightning setup and its features, including some examples and basic configuration.
The previous chapter concluded our work with Bitcoin proper, through CLI, scripting, and programming languages. However, there are many other utilities within the Bitcoin ecosystem: this chapter and the next cover what may be the biggest and most important: the Lightning Network. Here you'll begin work with the `lightning-cli` command-line interface, understanding a core lightning setup and its features, including some examples and basic configuration.

## Objectives for This Chapter

After working through this chapter, a developer will be able to:

* Assess that a c-lightning Node is Installed and Up-to-date
* Assess that a core lightning Node is Installed and Up-to-date
* Perform Basic Lightning Wallet Commands
* Create a LIghtning Channel

Expand All @@ -20,7 +20,7 @@ Supporting objectives include the ability to:

## Table of Contents

* [Section One: Verifying Your c-lightning Setup](19_1_Verifying_Your_Lightning_Setup.md)
* [Section Two: Knowing Your c-lightning Setup](19_2_Knowing_Your_lightning_Setup.md)
* [Section One: Verifying Your core lightning Setup](19_1_Verifying_Your_Lightning_Setup.md)
* [Section Two: Knowing Your core lightning Setup](19_2_Knowing_Your_lightning_Setup.md)
* [Interlude: Accessing a Second Lightning Node](19_2__Interlude_Accessing_a_Second_Lightning_Node.md)
* [Section Three: Creating a Lightning Channel](19_3_Setting_Up_a_Channel.md)
26 changes: 13 additions & 13 deletions 19_1_Verifying_Your_Lightning_Setup.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# 19.1: Creating a c-lightning Setup
# 19.1: Creating a core lightning Setup

> :information_source: **NOTE:** This section has been recently added to the course and is an early draft that may still be awaiting review. Caveat reader.

In this section, you'll install and verify c-lightning, your utility for accessing the Lightning Network.
In this section, you'll install and verify core lightning, your utility for accessing the Lightning Network.

> :book: ***What is the Lightning Network?*** The Lightning Network is a decentralized network that uses the smart contract functionality of the Bitcoin blockchain to enable instant payments across a network of participants. Lightning is built as a layer-2 protocol that interacts with Bitcoin to allow users to exchange their bitcoins "off-chain".

> :book: ***What is a layer-2 protocol?*** Layer 2 refers to a secondary protocol built on top of the Bitcoin blockchain system. The main goal of these protocols is to solve the transaction speed and scaling difficulties that are present in Bitcoin: Bitcoin is not able to process thousands of transactions per second (TPS), so layer-2 protocols have been created to solve the blockchain scalability problem. These solutions are also known as "off-chain" scaling solutions.

## Install C-Lightning
## Install core Lightning

If you used the [Bitcoin Standup Scripts](https://github.com/BlockchainCommons/Bitcoin-Standup-Scripts), you may have already installed Lightning at the beginning of this course. You can test this by seeing if `lightningd` is running:
```
Expand All @@ -27,15 +27,15 @@ standup 32072 0.0 0.0 6208 888 pts/0 S+ 15:50 0:00 grep -i lightni
```
If not, you'll need to install it now. Unfortunately, if you're using Debian you'll need to install it by hand, by compiling the source code — but it should still be pretty simple if you follow these instructions. If you happen to be on a standard Ubuntu system, instead try [Installing from Ubuntu ppa](#variant-install-from-ubuntu-ppa), and you can always attempt [Installing Pre-compiled Binaries](#variant-install-pre-compiled-binaries).

> :book: ***What is c-lightning?*** There are three different implementations of Lightning at present: c-lightning, LND, and Eclair. They should all be functionally compatible, based on the same [BOLT RFCs](https://github.com/lightningnetwork/lightning-rfc/blob/master/00-introduction.md), but their implementation details may be different. We've chosen c-lightning as the basis of our course because it's also part of the same [Elements Project](https://github.com/ElementsProject) that also contains Libwally.
> :book: ***What is core lightning?*** There are three different implementations of Lightning at present: core lightning, LND, and Eclair. They should all be functionally compatible, based on the same [BOLT RFCs](https://github.com/lightningnetwork/lightning-rfc/blob/master/00-introduction.md), but their implementation details may be different. We've chosen core lightning as the basis of our course because it's also part of the same [Elements Project](https://github.com/ElementsProject) that also contains Libwally.

### Compile the c-lightning Source Code
### Compile the core lightning Source Code

Installing Lightning from source code should actually be pretty simple if you follow these instructions.

You _probably_ want to do this on an unpruned node, as working with pruned nodes on Lightning may cause issues with installation and usage. If you set up your node way back at the start of this course to be pruned, you may wish to replace it with an unpruned node now. (If you're using testnet, you should be able to use the same type of machine as you did for your pruned node.)

> :warning: **WARNING:** You actually can run c-lightning on a pruned node. However, as the [Lightning repo](https://github.com/ElementsProject/lightning#pruning) notes, there may be issues. To make it work you have to ensure that your Lightning node is only ever trying to update info on blocks that your Bitcoin node has not pruned. To do so you must make sure (1) that your Bitcoin node is fully up to date before you start your Lightning node for the first time; and (2) that your Lightning node never falls too far behind your Bitcoin node (for a standard 550-block pruning, it can never be turned off for 4 or more days). So, you can do it, but it does introduce some danger, which isn't a good idea if you're running a production service.
> :warning: **WARNING:** You actually can run core lightning on a pruned node. However, as the [Lightning repo](https://github.com/ElementsProject/lightning#pruning) notes, there may be issues. To make it work you have to ensure that your Lightning node is only ever trying to update info on blocks that your Bitcoin node has not pruned. To do so you must make sure (1) that your Bitcoin node is fully up to date before you start your Lightning node for the first time; and (2) that your Lightning node never falls too far behind your Bitcoin node (for a standard 550-block pruning, it can never be turned off for 4 or more days). So, you can do it, but it does introduce some danger, which isn't a good idea if you're running a production service.

With that, you're ready to install Lightning:

Expand Down Expand Up @@ -95,7 +95,7 @@ A bitcoin lightning daemon (default values shown for network: testnet).

You'll begin your exploration of the Lightning network with the `lightning-cli` command. However,`lightningd` _must_ be running to use `lightning-cli`, as `lightning-cli` sends JSON-RPC commands to the `lightningd` (all just as with `bitcoin-cli` and `bitcoind`).

If you installed `c-lightning` by hand, you'll now need to start it:
If you installed `core lightning` by hand, you'll now need to start it:
```
$ nohup lightningd --testnet &
```
Expand Down Expand Up @@ -228,22 +228,22 @@ bitcoin-cli -testnet getblock 0000000000000559febee77ab6e0be1b8d0bef0f971c7a4bee

## Create Aliases

We suggest creating some aliases to make it easier to use c-lightning.
We suggest creating some aliases to make it easier to use core lightning.

You can do so by putting them in your `.bash_profile`.
```
cat >> ~/.bash_profile <<EOF
alias lndir="cd ~/.lightning/" #linux default c-lightning path
alias lndir="cd ~/.lightning/" #linux default core lightning path
alias lnc="lightning-cli"
alias lnd="lightningd"
alias lninfo='lightning-cli getinfo'
EOF
```
After you enter these aliases you can either `source ~/.bash_profile` to input them or just log out and back in.

Note that these aliases include shortcuts for running `lightning-cli`, for running `lightningd`, and for going to the c-lightning directory. These aliases are mainly meant to make your life easier. We suggest you create other aliases to ease your use of frequent commands (and arguments) and to minimize errors. Aliases of this sort can be even more useful if you have a complex setup where you regularly run commands associated with Mainnet, with Testnet, _and_ with Regtest, as explained further below.
Note that these aliases include shortcuts for running `lightning-cli`, for running `lightningd`, and for going to the core lightning directory. These aliases are mainly meant to make your life easier. We suggest you create other aliases to ease your use of frequent commands (and arguments) and to minimize errors. Aliases of this sort can be even more useful if you have a complex setup where you regularly run commands associated with Mainnet, with Testnet, _and_ with Regtest, as explained further below.

With that said, use of these aliases in _this_ document might accidentally obscure the core lessons being taught about c-lightning, so we'll continue to show the full commands; adjust for your own use as appropriate.
With that said, use of these aliases in _this_ document might accidentally obscure the core lessons being taught about core lightning, so we'll continue to show the full commands; adjust for your own use as appropriate.

## Optional: Modify Your Server Types

Expand All @@ -257,7 +257,7 @@ When lightningd starts up, it usually reads a configuration file whose location
```
There is also a general configuration file (default: `~/.lightning/config`). If you want to run several different sorts of nodes simultaneously, you must leave the testnet (or regtest) flag out of this configuration file. You should then choose whether you're using the mainnet, the testnet, or your regtest every time you run `lightningd` or `lightning-cli`.

Your setup may not actually have any config files: c-lightning will run with a good default setup without them.
Your setup may not actually have any config files: core lightning will run with a good default setup without them.

## Summary: Verifying your Lightning setup

Expand All @@ -269,7 +269,7 @@ Continue "Understanding Your Lightning Setup" with [§19.2: Knowing Your Lightni

## Variant: Install from Ubuntu ppa

If you are using a Ubuntu version other than Debian, you can install c-lightning using [Ubuntu ppa](https://launchpad.net/~lightningnetwork/+archive/ubuntu/ppa):
If you are using a Ubuntu version other than Debian, you can install core lightning using [Ubuntu ppa](https://launchpad.net/~lightningnetwork/+archive/ubuntu/ppa):

```
$ sudo apt-get install -y software-properties-common
Expand Down
6 changes: 3 additions & 3 deletions 19_2_Knowing_Your_lightning_Setup.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# 19.2: Knowing Your c-lightning Setup
# 19.2: Knowing Your core lightning Setup

> :information_source: **NOTE:** This section has been recently added to the course and is an early draft that may still be awaiting review. Caveat reader.

Before you begin accessing the Lightning Network, you should come to a better understanding of your setup.

## Know Your c-lightning Directory
## Know Your core lightning Directory

When using c-lightning, everything is kept in the `~/.lightning` directory.
When using core lightning, everything is kept in the `~/.lightning` directory.

The main directory just contains directories for whichever networks are configured, in this case testnet:
```
Expand Down
14 changes: 7 additions & 7 deletions 19_2__Interlude_Accessing_a_Second_Lightning_Node.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ There are four ways to do so (the first three of which are possible for your fir

If someone else already has a Lightning node on the network of your choice, just ask them for their ID.

If they are are running c-lightning, they just need to use the `getinfo` command:
If they are are running core lightning, they just need to use the `getinfo` command:
```
$ lightning-cli getinfo
lightning-cli: WARNING: default network changing in 2020: please set network=testnet in config!
Expand Down Expand Up @@ -50,9 +50,9 @@ lightning-cli: WARNING: default network changing in 2020: please set network=tes
```
They can then tell you their `id` (`03240a4878a9a64aea6c3921a434e573845267b86e89ab19003b0c910a86d17687`). They will also need to tell you their IP address (`74.207.240.32`) and port (`9735`).

## Create a New c-lightning Node
## Create a New core lightning Node

However, for testing purposes, you probably want to have a second node under you own control. The easiest way to do so is to create a second c-lightning node on a new machine, using either Bitcoin Standup, per [§2.1](02_1_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md) or compiling it by hand, per [§19.1](19_1_Verifying_Your_Lightning_Setup.md).
However, for testing purposes, you probably want to have a second node under you own control. The easiest way to do so is to create a second core lightning node on a new machine, using either Bitcoin Standup, per [§2.1](02_1_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md) or compiling it by hand, per [§19.1](19_1_Verifying_Your_Lightning_Setup.md).

Once you have your node running, you can run `getinfo` to retrieve your information, as shown above.

Expand Down Expand Up @@ -109,7 +109,7 @@ $ sudo cp $GOPATH/bin/lnd $GOPATH/bin/lncli /usr/bin

### Create an LND Config File

Unlike with c-lightning, you will need to create a default config file for LND.
Unlike with core lightning, you will need to create a default config file for LND.

However first, you need to enable ZMQ on your Bitcoind, if you didn't already in [§16.3](16_3_Receiving_Bitcoind_Notifications_with_C.md).

Expand Down Expand Up @@ -212,7 +212,7 @@ $ sudo systemctl start lnd

### Enable Remote Connections

Just as with c-lightning, you're going to need to make LND accessible to other nodes. Here's how to do so if you use `ufw`, as per the Bitcoin Standup setups:
Just as with core lightning, you're going to need to make LND accessible to other nodes. Here's how to do so if you use `ufw`, as per the Bitcoin Standup setups:
```
$ sudo ufw allow 9735
```
Expand Down Expand Up @@ -316,10 +316,10 @@ However, that definitely won't be the case for your first interaction with the L

## Summary: Accessing a Second Lightning Node

You always need two Lightning nodes to form a channel. If you don't have someone else who is testing things out with you, you're going to need to create a second one, either using c-lightning or (as we will in our examples) LND.
You always need two Lightning nodes to form a channel. If you don't have someone else who is testing things out with you, you're going to need to create a second one, either using core lightning or (as we will in our examples) LND.

## What's Next?

Though you've possibly created an LND, c-lightning will remain the heart of our examples until we need to start using both of them, in [Chapter 19](19_0_Understanding_Your_Lightning_Setup.md).
Though you've possibly created an LND, core lightning will remain the heart of our examples until we need to start using both of them, in [Chapter 19](19_0_Understanding_Your_Lightning_Setup.md).

Continue "Understanding Your Lightning Setup" with [§19.3: Setting Up_a_Channel](19_3_Setting_Up_a_Channel.md).
Loading