lnbook/02_getting_started.asciidoc

[[getting-started]]
== Getting Started

In this chapter, we will start where most people start when encountering the Lightning Network for the first time - choosing software. We will examine the choices of two users who represent a common use-case for the Lightning Network and learn by example. Alice, a coffee shop customer, will be using a LN wallet on her mobile device to buy coffee from Bob's Cafe. Bob, a merchant, will be using a LN node and wallet to run a point-of-sale system at his cafe so he can accept payment over the Lightning Network.

=== Lightning Nodes

The Lightning Network is accessed via software applications that can speak the Lightning Network protocol. A _Lightning Network Node_ (or simply "node") is a software application that has three important characteristics. First, nodes must communicate on a peer-to-peer basis with other LN nodes. This communication forms the Lightning _Network_ itself. Nodes also include "wallet" functionality, so they can send and receive payments over the Lightning Network and on the Bitcoin network. Finally, LN nodes also need access to the Bitcoin blockchain (or other blockchains for other cryptocurrencies).

Users have the highest degree of control by running their own Bitcoin node and LN node. However, LN nodes can also use a lightweight Bitcoin client (commonly referred to as Simplified Payment Verification (SPV)) to partially validate the correctness of their blockchain.

////
but there is no "SPV" functionality in the LN peer to peer communication right? they have to have full funcionality?
////

=== Lightning Wallets

The term "Lightning Wallet" is somewhat ambiguous, as it can describe a broad variety of components combined with some user interface. The most common components of lightning wallet software include:

* A keystore that securely holds secrets, such as private keys.
* A Lightning Network node that communicates on the Peer-to-Peer network, as described previously.
* A Bitcoin node that stores blockchain data and communicates with other Bitcoin nodes.
* A channel data store with data about channels on the Lightning Network.
* A channel manager that can open and close Lightning Network channels.
* A path-finding system that can identify a path of connected channels from payment source to payment destination.

A lightning wallet may contain all of these functions, acting as a "full" wallet, with no reliance on any third-party services. Or, one or more of these components may rely (partially or entirely) on third-party services that mediate those functions.

A key distinction (pun intended), is whether the keystore function is internal or outsourced. In blockchains, control of keys determines custody of funds, as memorialized by the phrase "your keys, your coins; not your keys, not your coins". Any wallet that outsources management of keys is called a "custodial" wallet, because a third party (custodian) has control of the user's funds, not the user themselves. A "non-custodial" or "self-custody" wallet, by comparison, is one where the keystore is part of the wallet, and keys are controlled directly by the user.

Blockchains, especially open blockchains like Bitcoin, attempt to minimize or eliminate trust in third parties and empower users. This is often called a "trustless" model, though "trust-minimized" is a better term. In such systems, the user trusts the software rules, not third parties. Therefore, the issue of control over keys is a principal consideration when choosing a lightning wallet.

Every other component of a lightning wallet brings similar considerations of trust. If all the components are under the control of the user, then the amount of trust in third parties is minimized, bringing maximum power to the user. Of course, this is a direct trade-off, as with that power comes the responsibility to manage complex software.

Every user must consider their own technical skills before deciding what type of lightning wallet to use. Those with strong technical skills should use a lightning wallet that puts all of the components under the direct control of the user. Those with less technical skill but a desire to control their funds, should choose a _non-custodial_ lightning wallet, even if some of the components (other than the keystore) rely on some trusted third parties.

Finally, those seeking simplicity and convenience, even at the expense of control and security, may choose a custodial lightning wallet. This is the least challenging option, but it _undermines the trust model of cryptocurrency_ and should, therefore, be considered only as a stepping stone towards more control and self-reliance.

In <<lnwallet-categories>> we see the three broad categories of lightning wallets and the relative degree of control they offer to the user.

[[lnwallet-categories]]
.Broad Categories of "LN Wallets"
|===
| Wallet Type          | LN Node        | Keystore/Custody | Technical Skill
| Full Node & Wallet   | Full Node      | Non-Custodial | High
| Non-Custodial Wallet | 3rd-party node | Non-Custodial | Medium
| Custodial Wallet     | 3rd-party node | Custodial     | Low
|===

Lightning wallets can be installed on a variety of devices, including laptops, servers, and mobile devices. To run an LN node and a Bitcoin node, you will need to use a server or desktop computer, as mobile devices and laptops are usually not powerful enough in terms of capacity, processing, battery life, and connectivity.

In <<lnwallet-examples>> we see some examples of currently popular LN node and wallet applications for different types of devices.

// TODO: Add a lot more wallet/node examples, confirm the details for correctness
[[lnwallet-examples]]
.Examples of Popular LN Wallets
|===
| Application   | Device  | LN Node     | Bitcoin Node          | Keystore
| lnd           | Server  | Full Node   | Bitcoin Core/btcd     | User Control
| c-lightning   | Server  | Full Node   | Bitcoin Core          | User Control
| Eclair Server | Server  | Full Node   | Bitcoin Core/Electrum | User Control
| Zap Desktop   | Desktop | Full Node   | Bitcoin Core/btcd     | User Control
| Eclair Mobile | Mobile  | Lightweight | Electrum              | User Control
| Breez Wallet | Mobile   | Full Node   | Bitcoin Core/btcd    | User Control
| Phoenix Wallet | Mobile | ??  | ??  | User Control
| Blue Wallet | Mobile | None | None | Custodial
|===

=== Balancing complexity and control

Lightning wallets have to strike a careful balance between complexity and user control. Those that give the user the most control over their funds, the highest degree of privacy and the greatest independence from third party services are necessarily more complex and difficult to operate. As the technology advances, some of these trade-offs will become less stark and users may be able to get more control without more complexity. However, for now, different companies and projects are exploring different positions along this control-complexity spectrum and hoping to find the "sweet spot" for the users they are targeting.

When selecting a wallet keep in mind that even if you don't see these trade-offs they still exist. For example, many wallets are attempting to remove the burden of channel management from users. To do so, they are introducing central "hub" nodes that their wallets all connect to automatically. While this trade-off simplifies the user interface and user experience, it introduces a Single Point of Failure (SPoF) and a potential privacy compromise, as these "hub nodes" become both indispensable and can see all the user's transactions.

In the next section we will introduce our first user and walk through their first LN wallet setup. We have chosen a wallet that not the easier to use custodial wallet model. This is because we want to show some of the underlying complexity and introduce some of the inner workings of the wallet during our example. You may find that your first ideal wallet is further towards "ease of use", by accepting some of the control and privacy trade-offs. Or perhaps you are more of a "power user" and want to run your own LN and Bitcoin nodes as part of your wallet solution.

=== Alice's First LN Wallet

Alice is a long time Bitcoin user. We first met Alice in Chapter 1 of _"Mastering Bitcoin"_ footnote:["Mastering Bitcoin 2nd Edition, Chapter 1" Andreas M. Antonopoulos (https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch01.asciidoc).], when she bought a cup of coffee from Bob's cafe, using a bitcoin transaction. Now, Alice is eager to learn about and experiment with the Lightning Network. First, she has to select an LN wallet that meets her needs.

Alice does not want to entrust custody of her bitcoin to third parties. She has learned enough about cryptocurrency to know how to use a wallet. She also wants a mobile wallet so that she can use it for small payments on-the-go, so she chooses the _Eclair_ wallet, a popular non-custodial mobile LN wallet.

==== Downloading and Installing an LN Wallet

When looking for a new cryptocurrency wallet, you must be very careful to select a secure source for the software.

Unfortunately, there are many fake wallet applications that will steal your money, and some of these even find their way onto reputable and supposedly vetted software sites, like the Apple and Google application stores. Whether you are installing your first or your tenth wallet, always exercise extreme caution. A rogue app can not only steal money any money you entrust it with, it might also be able to steal keys and passwords from other applications by compromising your mobile device operating system.

Alice uses an Android device, and will use the Google Play Store to download and install the Eclair wallet. Searching on Google Play, she finds an entry for "Eclair Mobile", as shown in <<eclair-playstore>>.

[[eclair-playstore]]
.Eclair Mobile in the Google Play Store
image:images/eclair-playstore.png["Eclair wallet in the Google Play Store"]

Alice notices a few different elements on this page, that help her ascertain that this is, most likely, the correct "Eclair Mobile" wallet she is looking for. Firstly, the organization "ACINQ" footnote:[ACINQ: Developers of the Eclair Mobile LN wallet (https://acinq.io/).] is listed as the developer of this mobile wallet, which Alice knows from her research is the correct developer. Secondly, the wallet has been installed "10,000+" times and has more than 320 positive reviews. It is unlikely this is a rogue app that has snuck into the Play Store. Satisfied by these findings, Alice installs the Eclair app on her mobile device.

[WARNING]
====
Always exercise great care when installing software on any device. There are many fake cryptocurrency wallets that will not only steal your money but might also compromise all other applications on your device.
====

=== Creating a New Wallet

When Alice opens the Eclair Mobile app for the first time, she is presented with a choice, to "Create a New Wallet" or to "Import an Existing Wallet". Alice will create a new wallet, but let's first discuss why these options are presented here and what it means to "import an existing wallet".

==== Responsibility with Key Custody

As we mentioned in the beginning of this section, Eclair is a _non-custodial_ wallet, meaning that Alice has sole custody of the keys used to control her bitcoin. This also means that Alice is responsible for protecting and backing up those keys. If Alice loses the keys, no one can help her recover the bitcoin and it will be lost forever.

[WARNING]
====
With the Eclair Mobile wallet, Alice has custody and control of the keys and therefore full responsibility to keep the keys safe and backed up. If she loses the keys, she loses the bitcoin and no one can help her recover from that loss!
====

==== Mnemonic Words

Similar to most Bitcoin wallets, Eclair Mobile provides a _mnemonic phrase_ for Alice to back up. The mnemonic phrase consists of 24 English words, selected randomly by the software, and used as the basis for the keys that are generated by the wallet. The mnemonic phrase can be used by Alice to restore all the transactions and funds in the Eclair Mobile wallet in the case of a loss, for example because of a lost mobile device, software bug, or memory corruption.

[TIP]
====
The _mnemonic phrase_ is often mistakenly called a "seed". In fact, a seed is constructed _from the mnemonic_ and is something different.
====

When Alice chooses to "Create a New Wallet", she will be shown a screen with her mnemonic phrase, which looks like the screenshot in <<eclair-mnemonic>>.

[[eclair-mnemonic]]
.New Wallet Mnemonic Phrase
image:images/eclair-mnemonic.png["New Wallet Mnemonic Phrase"]

In <<eclair-mnemonic>> we have purposely obscured part of the mnemonic phrase to prevent readers of this book from reusing the mnemonic.

[[mnemonic-storage]]
==== Storing the Mnemonic Safely

Alice needs to be careful to store the mnemonic phrase in a way that balances the need to prevent theft and accidental loss. The recommended way to properly balance these risks is to write two copies of the mnemonic phrase on paper, with each of the words numbered (the order matters!).

Once Alice has recorded the mnemonic phrase, after touching "OK GOT IT" on her screen she will be presented with a _quiz_ to make sure that she correctly recorded the mnemonic. The quiz will ask for three or four of the words at random. Alice wasn't expecting a quiz, but since she recorded the mnemonic correctly she passes without any difficulty.

Once Alice has recorded the mnemonic phrase, and passed the quiz, she should store each copy in a separate secure location such as a locked desk drawer, or a fireproof safe.

[WARNING]
====
Never attempt a "DIY" security scheme that deviates in any way from the best practice recommendation in <<mnemonic-storage>>. Do not cut your mnemonic in half, make screenshots, store on USB drives or cloud drives, encrypt it, or try any other non-standard method. You will tip the balance in such a way as to risk permanent loss or theft. Many people have lost funds, not from theft, but because they tried a non-standard solution without having the expertise to balance the risks involved. The best practice recommendation is carefully balanced by experts and suitable for the vast majority of users.
====

After Alice initializes her Eclair Mobile wallet, she will see a brief tutorial which highlights the various elements of the user interface. We won't replicate the tutorial here, but we will explore all of those elements as we follow Alice's attempt to buy a cup of coffee!

=== Loading Bitcoin Into the Wallet

Alice now has an LN wallet. But, it's empty! She now faces one of the more challenging aspects of this experiment: she has to find a way to acquire some bitcoin and load it onto her Eclair wallet.

[[acquiring-bitcoin]]
==== Acquiring Bitcoin

There are several ways Alice can acquire bitcoin:

* She can exchange some of her national currency (eg. USD) at a crypto-currency exchange
* She can buy some from a friend, or an acquaintance from a Bitcoin Meetup, in exchange for cash
* She can find a _Bitcoin ATM_ in her area, which acts as a vending machine, selling bitcoin for cash
* She can offer her skills or a product she sells and accept payment in bitcoin
* She can ask her employer or clients to pay her in bitcoin

All of these methods have varying degrees of difficulty and many will involve paying a fee. Some will also require Alice to provide identification documents to comply with local banking regulations. However, with all these methods, Alice will be able to receive bitcoin directly into her Eclair wallet.

==== Receiving Bitcoin

Let's assume Alice has found a local Bitcoin ATM and has decided to buy some bitcoin in exchange for cash. An example of a Bitcoin ATM, one built by the Lamassu company, is shown in <<bitcoin-atm>>. A Bitcoin ATM like this one accepts national currency (cash) through a cash slot and send bitcoin to a Bitcoin Address scanned from a user's wallet using a built-in camera.

[[bitcoin-atm]]
.A Lamassu Bitcoin ATM
image:images/bitcoin-atm.png[]

To receive the bitcoin in her Eclair LN wallet, Alice will need to present a _Bitcoin Address_ from the Eclair LN wallet to the ATM. The ATM can then send Alice's newly acquired bitcoin to this bitcoin address.

On the Eclair wallet, to see a Bitcoin Address Alice must swipe to the left column titled "YOUR BITCOIN ADDRESS" (see <<eclair-receive>>), where she will see a square bardcode (called a _QR code_) and a string of letters and numbers below.

[[eclair-receive]]
.Alice's bitcoin address, shown in Eclair
image:images/eclair-receive.png[]

The QR code contains the same string of letters and numbers as shown below it, in an easy to scan format. This way, Alice doesn't have to type the Bitcoin Address. In the screenshot <<eclair-receive>>, we have purposely blurred both, to prevent readers from inadvertently sending bitcoin to this address.

[NOTE]
====
Both Bitcoin addresses and QR codes contain error detection information that prevents any typing or scanning errors from producing a "wrong" Bitcoin address. If there is a mistake in the address, any Bitcoin wallet will notice the error and refuse to accept the Bitcoin Address as valid.
====

Alice can take her mobile device to the ATM and show it to the built-in camera, as shown in <<bitcoin-atm-receive>>. After inserting some cash into the slot, she will receive bitcoin in Eclair!

[[bitcoin-atm-receive]]
.Bitcoin ATM scans the QR code
image:images/bitcoin-atm-receive.png[]

Alice will see the transaction from the ATM in the "TRANSACTION HISTORY" tab of the Eclair wallet. While the bitcoin transaction will be detected by Eclair in just a few seconds, it will take approximately one hour for the bitcoin transaction to be "confirmed" on the Bitcoin Blockchain. As you can see in <<eclair-tx1>>, Alice's Eclair wallet shows "6+ conf" below the transaction, indicating that the transaction has received the required six confirmations and her funds are ready to use.

[[eclair-tx1]]
.Alice receives bitcoin
image:images/eclair-tx1-btc.png[]

While in this example Alice used an ATM to acquire her first bitcoin, the same basic concepts would apply even if she used one of the other methods in <<acquiring-bitcoin>>. For example, if Alice wanted to sell a product or provide a professional service in exchange for bitcoin, her customers could scan the Bitcoin Address with their own wallets and pay her in bitcoin.

Similarly, if she billed a client for a service offered over the Internet, Alice could send an email or instant message with the Bitcoin Address or the QR code (or both) to her client and they could scan or paste the information into a Bitcoin wallet to pay her.

Alice could even print the QR code and affix it to a sign and display it to receive tips. A singer who receives bitcoin tips has a QR code printed and affixed to their guitar while performing!

Finally, if Alice bought bitcoin from a crypto-currency exchange, she could (and should!) then "withdraw" the bitcoin by pasting her Bitcoin Address into the exchange website. The exchange will then send the bitcoin to her address directly.

=== From Bitcoin to Lightning Network

Alice's bitcoin is now controlled by her Eclair wallet and has been recorded on the Bitcoin Blockchain. At this point, Alice's bitcoin is "on-chain", meaning that she has completed a regular Bitcoin transaction, broadcast to the entire Bitcoin network, verified by all Bitcoin nodes and "mined" (recorded) onto the Bitcoin blockchain.

So far, the Eclair Mobile wallet has behaved only as a Bitcoin wallet and Alice hasn't used the Lightning Network features of Eclair. As is the case with many LN wallets, Eclair bridges Bitcoin and the Lightning Network by acting as both a Bitcoin wallet and a Lightning wallet.

Now, Alice is ready to start using the Lightning Network by taking her bitcoin "off-chain", so she can take advantage of the fast, cheap and private payments that LN offers.

==== Lightning Network Channels

Swiping right, Alice accesses the "LIGHTNING CHANNELS" section of Eclair. Here she can manage the LN channels that will connect her wallet to the Lightning Network.

Let's review the definition of a "Lightning Network Channel" at this point, to make things a bit more clear. Firstly, the word "channel" is a metaphor for a _financial relationship_ between Alice's LN wallet and another LN wallet. We call it a channel because it is a means for Alice's wallet and this other wallet to exchange many payments with each other on the Lightning Network (off-chain), without committing transactions to the Bitcoin Blockchain (on-chain).

The wallet or _node_ that Alice opens a channel to, is called her _channel peer_. Once "opened", a channel can be used to send many payments back and forth between Alice's wallet and her channel peer.

Furthermore, Alice's channel peer can _forward_ payments via other channels further into the Lightning Network. This way, Alice can _route_ a payment to any wallet (eg. Bob's LN wallet) as long as Alice's wallet can find a _path_ made by hoping from channel to channel, all the way to Bob's wallet.

All this to say: Alice needs one or more channels that connect her to one or more other nodes on the Lightning Network. She doesn't need a channel to connect her wallet directly to Bob's Cafe in order to send Bob a payment, though she can choose to open a direct channel too. Any well-connected node in the Lightning Network can be used for Alice's first channel. In this example, since we want to also demonstrate payment routing, we won't have Alice open a channel directly to Bob's wallet. Instead we will have Alice open a channel to a well-connected node and then later use that node to forward her payment, routing it through any other nodes, as necessary to reach Bob.

At first, there are no open channel, so as we see in <<eclair-tutorial2.png>>, the "LIGHTNING CHANNELS" tab displays an empty list. If you notice, on the bottom right corner there is a plus symbol (+), which is a button to open a new channel.

[[eclair-channels]]
.Lightning Channels Tab
image:images/eclair-tutorial2.png["Lightning Channels Tab"]

Alice presses the plus symbol and is presented with four possible ways to open a channel:

* Paste a node URI
* Scan a node URI
* Random node
* ACINQ node

A "node URI" is a Universal Resource Identifier (URI) that identifies a specific LN node. Alice can either paste such a URI from her clipboard, or scan a QR code containing that same information. An example of a node URI is shown as a QR code in <<node-URI-QR>> and below it as a text string:

[[node-URI-QR]]
.node URI as a QR code
image:images/node-URI-QR.png[width=120]

[[node-URI-example]]
.node URI
++++
0237fefbe8626bf888de0cad8c73630e32746a22a2c4faa91c1d9877a3826e1174@1.ln.aantonop.com:9735
++++

While Alice could select a specific LN node, or use the "Random node" option to have the Eclair wallet select a node at random, she will select the "ACINQ Node" option to connect to one of ACINQ's well-connected LN nodes.

Choosing the ACINQ node will slightly reduce Alice's privacy, as it will give ACINQ the ability to see all of Alice's transactions. It will also create a Single Point of Failure, since Alice will only have one channel and if the ACINQ node is not available, Alice will not be able to make payments. To keep things simple at first, we will accept these trade-offs. In subsequent chapters will gradually learn how to gain more independence and make fewer trade-offs!

Alice touches "ACINQ Node" and is ready to open her first LN channel.

==== Opening an LN Channel

When Alice selects a node to open a new channel, she is asked to select how much money she wants allocated to this channel. In subsequent chapters we will discuss the implications of these choices, but for now Alice will allocate almost all her funds to the channel. Since she will have to pay transaction fees to open the channel, she will select an amount a few dollars (or a few thousandths of a bitcoin) less than her total balance.

Alice allocates 0.018BTC of her 0.020 total to her channel and accepts the default fee rate, as shown in <<eclair-open-channel>>.

[[eclair-open-channel]]
.Opening an LN Channel
image:images/eclair-open-channel-detail.png[]

Once she clicks "OPEN", her wallet constructs the special Bitcoin transaction that opens an LN channel, known as the _funding transaction_. The funding transaction is sent to the Bitcoin Network for confirmation.

Alice now has to wait, again (see <<eclair-channel-waiting>>), for the transaction to be recorded in the Bitcoin Blockchain. As with the initial Bitcoin transaction that she used to acquire her bitcoin, she has to wait for six or more confirmations (approximately one hour).

[[eclair-channel-waiting]]
.Waiting for the Funding Transaction to Open the Channel
image:images/eclair-channel-waiting.png["Waiting for the Funding Transaction to Open the Channel"]

Once the funding transaction is confirmed, Alice's channel to the ACINQ node is open and ready, as shown in <<eclair-channel-open>>:

[[eclair-channel-open]]
.Channel is Open
image:images/eclair-channel-open.png["Channel is Open"]

[TIP]
====
Did you notice that the channel amount seems to have changed? It hasn't: the channel contains 0.018 BTC, but in the time between screenshots the BTC exchange rate changed, so the USD value is different. You can choose to show balances in BTC or USD, but keep in mind that USD values are calculated in real time and may change!
====

=== Buying a Cup of Coffee

Alice now has everything ready to start using the Lightning Network. As you can see it took a bit of work and a bit of waiting for confirmations. But now things get very fast and easy. The Lightning Network enables payments with having to wait for confirmations, as funds are settled in seconds.

Alice grabs her mobile device and runs to Bob's Cafe in her neighborhood. She is excited to try her new LN wallet and use it to buy something!

==== Bob's Cafe

Bob has a simple Point-of-Sale (PoS) application for the use of any customer who wants to pay with bitcoin over the Lightning Network. As we will see in the next chapter, Bob uses the popular open source platform _BTCPay Server_ which contains all the necessary components for an e-commerce or retail solution, such as:

* A Bitcoin Node using the Bitcoin Core software
* A Lightning Node using the c-lightning software
* A simple PoS application for a tablet

BTCPay Server makes it very simple to install all the necessary software, upload pictures and product prices and launch a store very quickly.

On the counter at Bob's Cafe, there is a tablet device showing <<bob-cafe-posapp>>:

[[bob-cafe-posapp]]
.Bob's Point-of-Sale Application
image:images/bob-cafe-posapp.png[]

==== A Lightning Invoice

Alice selects the "Cafe Latte" option from the screen and is presented with a _Lightning Invoice_, as shown in <<bob-cafe-invoice>>

[[bob-cafe-invoice]]
.LN Invoice for Alice's latte
image:images/bob-cafe-invoice.png[]

To pay the invoice, Alice opens her Eclair wallet and selects the "Send" button (which looks like a right facing arrow) under the "TRANSACTION HISTORY" tab, as shown in <<alice-send-start>>.

[[alice-send-start]]
.Alice Send
image:images/alice-send-start.png[width=300]

Alice selects the option to "scan a payment request" and scans the QR code displayed on the screen of the tablet (see <<bob-cafe-invoice>>), and is prompted to confirm her payment, as shown in <<alice-send-detail>>:

[[alice-send-detail]]
.Alice's Send Confirmation
image:images/alice-send-detail.png[width=300]

Alice presses "PAY", and a second later, Bob's tablet shows a successful payment. Alice has completed her first Lightning Network payment. It was fast, inexpensive and easy! Now she can enjoy her latte, which was purchased using the most advanced payment technology in the world.

=== Conclusion

In this chapter, we followed Alice as she downloaded and installed her first LN wallet, acquired and transferred some bitcoin, opened her first LN channel and bought a cup of coffee by making her first payment on the Lightning Network. In the following chapters will we look "under the covers" at how each component in the Lightning Network works, and how Alice's payment reached Bob's Cafe.