Archives/lnbook
2
0
Fork 0
mirror of https://github.com/lnbook/lnbook synced 2024-11-15 00:15:05 +00:00
Code Issues Projects Releases Wiki Activity

Edited 02_getting_started.asciidoc with Atlas code editor

Browse Source
This commit is contained in:
kristen@oreilly.com 2021-11-10 07:27:29 -08:00
parent 183047f44f
commit 835de376e1
1 changed files with 452 additions and 452 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

904
02_getting_started.asciidoc
View File

@ -1,452 +1,452 @@
[[getting-started]]
== Getting Started
((("Lightning Network (generally)","example", id="ix_02_getting_started-asciidoc0", range="startofrange")))In this chapter, we will begin where most people start when encountering the Lightning Network for the first time—choosing software to participate in the LN economy. 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 Lightning wallet on her mobile device to buy coffee from Bob's Cafe. Bob, a merchant, will be using a Lightning node and wallet to run a point-of-sale system at his cafe, so he can accept payments over the Lightning Network.
=== Alice's First Lightning Wallet
((("Lightning Network (generally)","Lightning wallet")))((("Lightning wallet")))Alice is a longtime Bitcoin user. We first met Alice in Chapter 1 of _"Mastering Bitcoin,"_ footnote:[_Mastering Bitcoin_, 2nd Edition, https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch01.asciidoc[Chapter 1] (O'Reilly) by Andreas M. Antonopoulos] when she bought a cup of coffee from Bob's cafe using a Bitcoin transaction. If you are not yet familiar with how Bitcoin transactions work or need a refresher, please read _Mastering Bitcoin_ or the summary in <<bitcoin_fundamentals_review>>.
Alice recently learned that Bob's Cafe just started accepting LN payments! Alice is eager to learn about and experiment with the Lightning Network; she wants to be one of Bob's first LN customers. To do this, first, Alice has to select a Lightning 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 noncustodial mobile Lightning wallet. Let's learn more about how and why she's made these choices.
=== Lightning Nodes
((("Lightning node operation")))The Lightning Network is accessed via software applications that can speak the LN protocol. A _Lightning Network node_ (LN node or simply node) is a software application that has three important characteristics. First, Lightning nodes are wallets so they send and receive payments over the Lightning Network as well as on the Bitcoin network. Second, nodes must communicate on a peer-to-peer basis with other Lightning nodes creating the network. Finally, Lightning nodes also need access to the Bitcoin blockchain (or other blockchains for other cryptocurrencies) to secure the funds used for payments.
Users have the highest degree of control by running their own Bitcoin node and Lightning node. However, ((("simplified payment verification (SPV)")))((("SPV (simplified payment verification)")))Lightning nodes can also use a lightweight Bitcoin client, commonly referred to as simplified payment verification (SPV), to interact with the Bitcoin blockchain.
[[ln_explorer]]
=== Lightning Explorers
((("Lightning explorers")))LN explorers are useful tools to show the statistics of nodes, channels, and network capacity.
Following is an inexhaustive list (in alphanumerical order):
* https://1ml.com/1ML[Lightning explorer]
* https://explorer.acinq.co/[ACINQ's Lightning explorer], with fancy visualization
* https://amboss.space/[Amboss Space Lightning explorer], with community metrics and intuitive visualizations
* https://ln.bigsun.xyz/[Fiatjaf's Lightning explorer] with many diagrams
* https://hashxp.org/lightning/node/[hashXP Lightning explorer]
[TIP]
====
Note that when using Lightning explorers, just like with other block explorers, privacy can be a concern.
If users are careless, the website may track their IP addresses and collect their behavior records (for example, the nodes users are interested in).
Also, it should be noted that because there is no global consensus of the current Lightning graph or the current state of any existing channel policy, users should never rely on Lightning explorers to retrieve the most current information.
Furthermore, as users open, close, and update channels, the graph will change and individual Lightning explorers may not be up to date.
Use Lightning explorers to visualize the network or gather information, but not as an authoritative source of what is happening on the Lightning Network.
To have an authoritative view of the Lightning Network, run your own Lightning node that will build a channel graph and collect various statistics, which you can view with a web-based interface.
====
=== Lightning Wallets
((("Lightning wallet","basics", id="ix_02_getting_started-asciidoc1", range="startofrange")))The term _Lightning wallet_ is somewhat ambiguous because 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 holds secrets, such as private keys
* A LN node (Lightning 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 database "map" of nodes and channels that are announced on the Lightning Network
* A channel manager that can open and close LN channels
* A close up system that can find 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." ((("custodial wallet")))Any wallet that outsources management of keys is called a _custodial_ wallet because a third party acting as custodian has control of the user's funds, not the user. ((("noncustodial wallet")))A _noncustodial_ or ((("self-custody wallet")))_self-custody_ wallet, by comparison, is one where the keystore is part of the wallet, and keys are controlled directly by the user. The term noncustodial wallet just implies that the keystore is local and under the user's control. However, one or more of the other wallet components may or may not be outsourced and rely on trusted third parties.
Blockchains, especially open blockchains like Bitcoin, attempt to minimize or eliminate trust in third parties and empower users. ((("trustless systems","blockchains as")))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 brings a direct trade-off because with that power comes the corresponding 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 fewer technical skills, but with a desire to control their funds, should choose a noncustodial Lightning wallet.
Often the trust in these cases relates to privacy.
If users decide to outsource some functionality to a third party, they usually give up some privacy as the third party will learn some information about them.
Finally, those seeking simplicity and convenience, even at the expense of control and security, may choose a custodial Lightning wallet. This is the least technically challenging option, but it _undermines the trust model of cryptocurrency_ and should therefore be considered only as a stepping stone toward more control and self-reliance.
There are many ways wallets can be characterized or categorized.
The most important questions to ask about a specific wallet are:
. Does this Lightning wallet have a full Lightning node or does it use a third-party Lightning node?
. Does this Lightning wallet have a full Bitcoin node or does it use a third-party Bitcoin node?
. Does this Lightning wallet store its own keys under user control (self-custody) or are the keys held by a third-party custodian?
[TIP]
====
If a Lightning wallet uses a third-party Lightning node, it is this third-party Lightning node that decides how to communicate with Bitcoin. Hence, using a third-party Lightning node implies that you are also using a third-party Bitcoin node. Only when the Lightning wallet uses its own Lightning node does the choice between full Bitcoin node and third-party Bitcoin node exist.
====
At the highest level of abstraction, Questions 1 and 3 are the most elementary ones.
From these two questions, we can derive four possible categories.
We can place these four categories into a quadrant as seen in <<lnwallet-categories>>.
But remember that this is just one way of categorizing Lightning wallets.
[[lnwallet-categories]]
.Lightning wallets quadrant
[options="header"]
|===
| | *Full Lightning node* | *3rd-party Lightning node*
| *Self-Custody* | Q1: High technical skill, least trust in 3rd parties, most permissionless | Q2: Below medium technical skills, below medium trust in 3rd parties, requires some permissions
| *Custodial* | Q3: Above medium technical skills, above medium trust in 3rd parties, requires some permissions | Q4: Low technical skills, high trust in 3rd parties, least permissionless
|===
Quadrant 3 (Q3), where a full Lightning node is used, but the keys are held by a custodian, is currently not common.
Future wallets from that quadrant may let a user worry about the operational aspects of their node, but then delegate access to the keys to a third party which primarily uses cold storage.
Lightning wallets can be installed on a variety of devices, including laptops, servers, and mobile devices. To run a full Lightning node you will need to use a server or desktop computer because mobile devices and laptops are usually not powerful enough in terms of capacity, processing, battery life, and connectivity.
The category third-party Lightning nodes can again be subdivided:
Lightweight::
This means that the wallet does not operate a Lightning node and thus needs to obtain information about the Lightning Network over the internet from someone else's Lightning node.
None::
This means that not only is the Lightning node operated by a third party, but most of the wallet is operated by a third party in the cloud. This is a custodial wallet where someone else controls custody of the funds.
These subcategories are used in <<lnwallet-examples>>.
Other terms that need explanation in <<lnwallet-examples>> in the column "Bitcoin node" are:
Neutrino::
This wallet does not operate a Bitcoin node. Instead, a Bitcoin node operated by someone else (a third party) is accessed via the Neutrino Protocol.
Electrum::
This wallet does not operate a Bitcoin node. Instead, a Bitcoin node operated by someone else (a third party) is accessed via the Electrum protocol.
Bitcoin Core::
This is an implementation of a Bitcoin node.
btcd::
This is another implementation of a Bitcoin node.
In <<lnwallet-examples>>, we see some examples of currently popular Lightning node and wallet applications for different types of device. The list is sorted first by device type and then alphabetically.
[[lnwallet-examples]]
.Examples of popular Lightning wallets
[options="header"]
|===
| Application | Device | Lightning node | Bitcoin node | Keystore
| Blue Wallet | Mobile | None | None | Custodial
| Breez Wallet | Mobile | Full node | Neutrino | Self-Custody
| Eclair Mobile | Mobile | Lightweight | Electrum | Self-Custody
| lntxbot | Mobile | None | None | Custodial
| Muun | Mobile | Lightweight | Neutrino | Self-Custody
| Phoenix Wallet | Mobile | Lightweight | Electrum | Self-Custody
| Zeus | Mobile | Full node | Bitcoin Core/btcd | Self-Custody
| Electrum | Desktop | Full node | Bitcoin Core/Electrum | Self-Custody
| Zap Desktop | Desktop | Full node | Neutrino | Self-Custody
| c-lightning | Server | Full node | Bitcoin Core | Self-Custody
| Eclair Server | Server | Full node | Bitcoin Core/Electrum | Self-Custody
| lnd | Server | Full node | Bitcoin Core/btcd | Self-Custody
|===
[[testnet-bitcoin]]
==== Testnet Bitcoin
((("Lightning wallet","testnet bitcoin and")))((("testnet bitcoin (TBTC)")))The Bitcoin system offers an alternative chain for testing purposes called _testnet_, in contrast with the "normal" Bitcoin chain which is referred to as _mainnet_. On testnet, the currency is _testnet bitcoin_ (_TBTC_), which is a worthless copy of bitcoin used exclusively for testing. Every function of Bitcoin is replicated exactly, but the money is worth nothing, so you literally have nothing to lose!
Some Lightning wallets can also operate on testnet, allowing you to make Lightning payments with testnet bitcoin, without risking real funds. This is a great way to experiment with Lightning safely. Eclair Mobile, which Alice uses in this chapter, is one example of a Lightning wallet that supports testnet operation.
You can get some TBTC to play with from a _testnet bitcoin faucet_, which gives out free TBTC on demand. Here are a few testnet faucets:
++++
<ul class="simplelist">
<li><a href="https://coinfaucet.eu/en/btc-testnet/"><em>https://coinfaucet.eu/en/btc-testnet</em></a></li>
<li><a href="https://testnet-faucet.mempool.co/"><em>https://testnet-faucet.mempool.co/</em></a></li>
<li><a href="https://bitcoinfaucet.uo1.net/"><em>https://bitcoinfaucet.uo1.net/</em></a></li>
<li><a href="https://testnet.help/en/btcfaucet/testnet"><em>https://testnet.help/en/btcfaucet/testnet</em></a></li>
</ul>
++++
All of the examples in this book can be replicated exactly on testnet with TBTC, so you can follow along if you want without risking real money.(((range="endofrange", startref="ix_02_getting_started-asciidoc1")))
=== Balancing Complexity and Control
((("Lightning wallet","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 will attempt to remove the burden of channel management from their users. To do so, they introduce central _hub nodes_ that all their wallets connect to automatically. While this trade-off simplifies the user interface and user experience, it introduces a single point of failure (SPoF) as these hub nodes become indispensable for the wallet's operation. Furthermore, relying on a "hub" like this can reduce user privacy since the hub knows the sender and potentially (if constructing the payment route on behalf of the user) also the recipient of each payment made by the user's wallet.
In the next section, we will return to our first user and walk through her first Lightning wallet setup. She has chosen a wallet that is more sophisticated than the easier custodial wallets. This allows us to show some of the underlying complexity and introduce some of the inner workings of an advanced wallet. You may find that your first ideal wallet is oriented toward ease of use, accepting some of the control and privacy trade-offs. Or perhaps you are more of a power user and want to run your own Lightning and Bitcoin nodes as part of your wallet solution.
=== Downloading and Installing a Lightning Wallet
((("Lightning wallet","downloading/installing")))When looking for a new cryptocurrency wallet, you must be very careful to select a secure source for the software.
Unfortunately, many fake wallet applications 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 may not just steal any money you entrust it with, but it might also be able to steal keys and passwords from other applications by compromising your mobile device operating system.
((("Eclair wallet, downloading/installing")))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/mtln_0201.png["Eclair wallet in the Google Play Store"]
[TIP]
====
It is possible to experiment and test all Bitcoin-type software with zero risk (except for your own time) by using testnet bitcoins. You can also download Eclair testnet wallet to try Lightning (on testnet) by going to 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 ACINQfootnote:[ACINQ: Developers of the Eclair Mobile Lightning wallet (https://acinq.co/).] 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 Google Play Store. As a third step, she goes to the https://acinq.co[ACINQ website]. She verifies that the web page is secure by checking that the address begins with https, or prefixed by a padlock in some browsers. On the website she goes to the Download section or looks for the link to the Google App Store. She finds the link and clicks it. She compares that this link brings her to the very same app in the Google App 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
((("Lightning wallet","creating a new wallet", id="ix_02_getting_started-asciidoc2", range="startofrange")))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
((("keys","Lightning wallet and")))((("Lightning wallet","responsibility with key custody")))As we mentioned at the beginning of this section, Eclair is a _noncustodial_ 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 they 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
((("Lightning wallet","mnemonic phrase")))((("mnemonic phrase")))((("seed (mnemonic) phrase")))Similar to most Bitcoin wallets, Eclair Mobile provides a _mnemonic phrase_ (also sometimes called a "seed" or "seed 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 an event such as a lost mobile device, a software bug, or memory corruption.
[TIP]
====
The correct term for these backup words is "mnemonic phrase." We avoid the use of the term "seed" to refer to a mnemonic phrase because even though its use is common, it is incorrect.
====
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/mtln_0202.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
((("Lightning wallet","mnemonic phrase storage")))Alice needs to be careful to store the mnemonic phrase in a way that prevents theft but also avoids 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&#x2014;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 nonstandard method. You will tip the balance in such a way as to risk permanent loss. Many people have lost funds, not from theft, but because they tried a nonstandard solution without having the expertise to balance the risks involved. The best practice recommendation is carefully considered by experts and suitable for the vast majority of users.
====
After Alice initializes her Eclair Mobile wallet, she will see a brief tutorial that 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!(((range="endofrange", startref="ix_02_getting_started-asciidoc2")))
=== Loading Bitcoin Onto the Wallet
((("bitcoin (currency)","loading onto Lightning wallet", id="ix_02_getting_started-asciidoc3", range="startofrange")))((("Lightning wallet","loading bitcoin onto", id="ix_02_getting_started-asciidoc4", range="startofrange")))Alice now has a Lightning 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.
[TIP]
====
If Alice already has bitcoin in another wallet, she could choose to send that bitcoin to her Eclair wallet instead of acquiring new bitcoin to load onto her new wallet.
====
[[acquiring-bitcoin]]
==== Acquiring Bitcoin
((("bitcoin (currency)","acquiring for Lightning wallet")))((("Lightning wallet","acquiring bitcoin for")))There are several ways Alice can acquire bitcoin:
* She can exchange some of her national currency (e.g., USD) on a cryptocurrency 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.
==== Receiving Bitcoin
((("bitcoin (currency)","receiving for Lightning wallet", id="ix_02_getting_started-asciidoc5", range="startofrange")))((("Bitcoin ATM", id="ix_02_getting_started-asciidoc6", range="startofrange")))((("Lightning wallet","receiving bitcoin", id="ix_02_getting_started-asciidoc7", range="startofrange")))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>>. Such Bitcoin ATMs accept 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/mtln_0203.png["Lamassu Bitcoin ATM"]
To receive the bitcoin in her Eclair Lightning wallet, Alice will need to present a Bitcoin address from the Eclair Lightning wallet to the ATM. The ATM can then send Alice's newly acquired bitcoin to this Bitcoin address.
To see a Bitcoin address on the Eclair wallet, Alice must swipe to the left column titled YOUR BITCOIN ADDRESS (see <<eclair-receive>>), where she will see a square barcode (called a _QR code_) and a string of letters and numbers below that.
[[eclair-receive]]
.Alice's bitcoin address, shown in Eclair
image::images/mtln_0204.png["Eclair bitcoin address QR code"]
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/mtln_0205.png["Bitcoin ATM scans the QR code"]
Alice will see the transaction from the ATM in the TRANSACTION HISTORY tab of the Eclair wallet. Although Eclair will detect the bitcoin transaction 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 minimum of six confirmations, and her funds are now ready to use.
[TIP]
====
The number of confirmations on a transaction is the number of blocks mined since (and inclusive of) the block that contained that transaction. Six confirmations is best practice, but different Lightning wallets can consider a channel open after any number of confirmations. Some wallets even scale up the number of expected confirmations by the monetary value of the channel.
====
[[eclair-tx1]]
.Alice receives bitcoin
image::images/mtln_0206.png["Bitcoin transaction received"]
Although 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 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 to her client, and they could paste or scan 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 publicly to receive tips. For example, she could have a QR code affixed to her guitar and receive tips while performing on the street!footnote:[It is generally not advisable to reuse the same Bitcoin address for multiple payments because all Bitcoin transactions are public.
A nosy person passing by could scan Alice's QR code and see how many tips Alice has already received to this address on the Bitcoin blockchain.
Fortunately, the Lightning Network offers more private solutions to this, discussed later in the book!]
Finally, if Alice bought bitcoin from a cryptocurrency exchange, she could (and should) "withdraw" the bitcoin by pasting her Bitcoin address into the exchange website. The exchange will then send the bitcoin to her address directly(((range="endofrange", startref="ix_02_getting_started-asciidoc7")))(((range="endofrange", startref="ix_02_getting_started-asciidoc6")))(((range="endofrange", startref="ix_02_getting_started-asciidoc5"))).(((range="endofrange", startref="ix_02_getting_started-asciidoc4")))(((range="endofrange", startref="ix_02_getting_started-asciidoc3")))
=== From Bitcoin to Lightning Network
((("Lightning wallet","bridging of Bitcoin and Lightning networks", id="ix_02_getting_started-asciidoc8", range="startofrange")))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 the transaction has been 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 Lightning 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 to take advantage of the fast, cheap, and private payments that the Lightning Network offers.
==== Lightning Network Channels
((("Lightning Network channels","basics", id="ix_02_getting_started-asciidoc9", range="startofrange")))((("Lightning Network channels","opening a channel", id="ix_02_getting_started-asciidoc10", range="startofrange")))((("Lightning wallet","LN channels and", id="ix_02_getting_started-asciidoc11", range="startofrange")))Swiping right, Alice accesses the LIGHTNING CHANNELS section of Eclair. Here she can manage the channels that will connect her wallet to the Lightning Network.
Let's review the definition of an LN channel at this point, to make things a bit clearer. Firstly, the word "channel" is a metaphor for a _financial relationship_ between Alice's Lightning wallet and another Lightning 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).
((("channel peer")))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 (e.g., Bob's Lightning wallet) as long as Alice's wallet can find a viable _path_ made by hopping from channel to channel, all the way to Bob's wallet.
[TIP]
====
Not all channel peers are _good_ peers for routing payments. Well-connected peers will be able to route payments over shorter paths to the destination, increasing the chance of success. Channel peers with ample funds will be able to route larger payments.
====
In other words, Alice needs one or more channels that connects 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 node in the Lightning Network can be used for Alice's first channel. The more well-connected a node is, the more people Alice can reach. 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 channels, so as we see in <<eclair-channels>>, 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/mtln_0207.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 Lightning 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 then as a text string.
[[node-URI-QR]]
.Node URI as a QR code
image::images/mtln_0208.png["Lightning node URI QR code",width=120]
[[node-URI-example]]
.node URI
----
0237fefbe8626bf888de0cad8c73630e32746a22a2c4faa91c1d9877a3826e1174@1.ln.aantonop.com:9735
----
While Alice could select a specific Lightning 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 Lightning nodes.
Choosing the ACINQ node will slightly reduce Alice's privacy, because 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, we will gradually learn how to gain more independence and make fewer trade-offs!
Alice selects ACINQ Node and is ready to open her first channel on the Lightning Network.(((range="endofrange", startref="ix_02_getting_started-asciidoc11")))(((range="endofrange", startref="ix_02_getting_started-asciidoc10")))(((range="endofrange", startref="ix_02_getting_started-asciidoc9")))
==== Opening a Lightning Channel
((("Lightning wallet","opening a Lightning channel", id="ix_02_getting_started-asciidoc12", range="startofrange")))When Alice selects a node to open a new channel, she is asked to select how much bitcoin she wants to allocate 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 slightly less than her total balance footnote:[The Eclair wallet doesn't offer an option to automatically calculate the necessary fees and allocate the maximum amount of funds to a channel, so Alice has to calculate this herself.]
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 a Lightning channel
image::images/mtln_0209.png["Opening a Lightning Channel"]
Once she clicks OPEN, her wallet constructs the special Bitcoin transaction that ((("funding transaction")))opens a Lightning channel, known as the _funding transaction_. The on-chain 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 on 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/mtln_0210.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, funded, and ready, as shown in <<eclair-channel-open>>.
[[eclair-channel-open]]
.Channel is open
image::images/mtln_0211.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 will change(((range="endofrange", startref="ix_02_getting_started-asciidoc12")))!(((range="endofrange", startref="ix_02_getting_started-asciidoc8")))
====
=== Buying a Cup of Coffee Using Lightning Network
((("Lightning Network (generally)","example: buying a cup of coffee", id="ix_02_getting_started-asciidoc13", range="startofrange")))((("Lightning wallet","example: buying a cup of coffee", id="ix_02_getting_started-asciidoc14", range="startofrange")))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 time waiting for confirmations. However, now subsequent actions are fast and easy. The Lightning Network enables payments without having to wait for confirmations, as funds get settled in seconds.
Alice grabs her mobile device and runs to Bob's Cafe in her neighborhood. She is excited to try her new Lightning 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 ecommerce 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 simple to install all the necessary software, upload pictures and product prices, and launch a store 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/mtln_0212.png["Bob's Point-of-Sale Application"]
==== A Lightning Invoice
((("Lightning invoices", id="ix_02_getting_started-asciidoc15", range="startofrange")))((("Lightning wallet","invoices", id="ix_02_getting_started-asciidoc16", range="startofrange")))Alice selects the Cafe Latte option from the screen and is presented with a _Lightning invoice_ (also known as a "payment request") as shown in <<bob-cafe-invoice>>.
[[bob-cafe-invoice]]
.Lightning invoice for Alice's latte
image::images/mtln_0213.png["BTCPay Server Lightning invoice"]
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/mtln_0214.png["Lightning transaction send",width=300]
[TIP]
====
The term "payment request" can refer to a Bitcoin payment request or a Lightning invoice, and the terms "invoice" and "payment request" are often used interchangeably. The correct technical term is "Lightning invoice," regardless of how it is named in the wallet.
====
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/mtln_0215.png["Lightning transaction send confirmation",width=300]
Alice presses PAY, and a second later, Bob's tablet shows a successful payment. Alice has completed her first LN payment! It was fast, inexpensive, and easy. Now she can enjoy her latte which was purchased using bitcoin through a payment system that is fast, cheap, and decentralized. From now on, Alice can simply select an item on Bob's tablet screen, scan the QR code with her cell phone, click pay, and will be served a coffee, all within seconds and all without an on-chain transaction.
Lightning payments are better for Bob too. He's confident that he will be paid for Alice's latte without waiting for an on-chain confirmation. In the future, whenever Alice feels like drinking a coffee at Bob's Cafe she can choose to pay with bitcoin on the Bitcoin network or the Lightning Network. Which one do you think she will choose(((range="endofrange", startref="ix_02_getting_started-asciidoc16")))(((range="endofrange", startref="ix_02_getting_started-asciidoc15")))?(((range="endofrange", startref="ix_02_getting_started-asciidoc14")))(((range="endofrange", startref="ix_02_getting_started-asciidoc13")))
=== Conclusion
In this chapter, we followed Alice as she downloaded and installed her first Lightning wallet, acquired and transferred some bitcoin, opened her first Lightning channel, and bought a cup of coffee by making her first payment on the Lightning Network.(((range="endofrange", startref="ix_02_getting_started-asciidoc0"))) In the following chapters, we will look "under the covers" at how each component in the Lightning Network works and how Alice's payment reached Bob's Cafe.
[[getting-started]]
== Getting Started
((("Lightning Network (generally)","example", id="ix_02_getting_started-asciidoc0", range="startofrange")))In this chapter, we will begin where most people start when encountering the Lightning Network for the first time&#x2014;choosing software to participate in the LN economy. 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 Lightning wallet on her mobile device to buy coffee from Bob's Cafe. Bob, a merchant, will be using a Lightning node and wallet to run a point-of-sale system at his cafe, so he can accept payments over the Lightning Network.
=== Alice's First Lightning Wallet
((("Lightning Network (generally)","Lightning wallet")))((("Lightning wallet")))Alice is a longtime Bitcoin user. We first met Alice in Chapter 1 of _Mastering Bitcoin_,footnote:[Andreas M. Antonopoulos, _Mastering Bitcoin_, 2nd Edition, https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch01.asciidoc[Chapter 1] (O'Reilly)] when she bought a cup of coffee from Bob's cafe using a Bitcoin transaction. If you are not yet familiar with how Bitcoin transactions work or need a refresher, please read _Mastering Bitcoin_ or the summary in <<bitcoin_fundamentals_review>>.
Alice recently learned that Bob's Cafe just started accepting LN payments! Alice is eager to learn about and experiment with the Lightning Network; she wants to be one of Bob's first LN customers. To do this, first, Alice has to select a Lightning 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 noncustodial mobile Lightning wallet. Let's learn more about how and why she's made these choices.
=== Lightning Nodes
((("Lightning node operation")))The Lightning Network is accessed via software applications that can speak the LN protocol. A _Lightning Network node_ (LN node or simply node) is a software application that has three important characteristics. First, Lightning nodes are wallets, so they send and receive payments over the Lightning Network as well as on the Bitcoin network. Second, nodes must communicate on a peer-to-peer basis with other Lightning nodes creating the network. Finally, Lightning nodes also need access to the Bitcoin blockchain (or other blockchains for other cryptocurrencies) to secure the funds used for payments.
Users have the highest degree of control by running their own Bitcoin node and Lightning node. However, ((("simplified payment verification (SPV)")))((("SPV (simplified payment verification)")))Lightning nodes can also use a lightweight Bitcoin client, commonly referred to as simplified payment verification (SPV), to interact with the Bitcoin blockchain.
[[ln_explorer]]
=== Lightning Explorers
((("Lightning explorers")))LN explorers are useful tools to show the statistics of nodes, channels, and network capacity.
Following is an inexhaustive list:
* https://1ml.com/1ML[Lightning explorer]
* https://explorer.acinq.co[ACINQ's Lightning explorer], with fancy visualization
* https://amboss.space[Amboss Space Lightning explorer], with community metrics and intuitive visualizations
* https://ln.bigsun.xyz[Fiatjaf's Lightning explorer] with many diagrams
* https://hashxp.org/lightning/node[hashXP Lightning explorer]
[TIP]
====
Note that when using Lightning explorers, just like with other block explorers, privacy can be a concern.
If users are careless, the website may track their IP addresses and collect their behavior records (for example, the nodes users are interested in).
Also, it should be noted that because there is no global consensus of the current Lightning graph or the current state of any existing channel policy, users should never rely on Lightning explorers to retrieve the most current information.
Furthermore, as users open, close, and update channels, the graph will change and individual Lightning explorers may not be up to date.
Use Lightning explorers to visualize the network or gather information, but not as an authoritative source of what is happening on the Lightning Network.
To have an authoritative view of the Lightning Network, run your own Lightning node that will build a channel graph and collect various statistics, which you can view with a web-based interface.
====
=== Lightning Wallets
((("Lightning wallet","basics", id="ix_02_getting_started-asciidoc1", range="startofrange")))The term _Lightning wallet_ is somewhat ambiguous because 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 holds secrets, such as private keys
* An LN node (Lightning 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 database "map" of nodes and channels that are announced on the Lightning Network
* A channel manager that can open and close LN channels
* A close-up system that can find 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." ((("custodial wallet")))Any wallet that outsources management of keys is called a _custodial_ wallet because a third party acting as custodian has control of the user's funds, not the user. ((("noncustodial wallet")))A _noncustodial_ or ((("self-custody wallet")))_self-custody_ wallet, by comparison, is one where the keystore is part of the wallet, and keys are controlled directly by the user. The term noncustodial wallet just implies that the keystore is local and under the user's control. However, one or more of the other wallet components may or may not be outsourced and rely on trusted third parties.
Blockchains, especially open blockchains like Bitcoin, attempt to minimize or eliminate trust in third parties and empower users. ((("trustless systems","blockchains as")))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 brings a direct trade-off because with that power comes the corresponding 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 fewer technical skills, but with a desire to control their funds, should choose a noncustodial Lightning wallet.
Often the trust in these cases relates to privacy.
If users decide to outsource some functionality to a third party, they usually give up some privacy as the third party will learn some information about them.
Finally, those seeking simplicity and convenience, even at the expense of control and security, may choose a custodial Lightning wallet. This is the least technically challenging option, but it _undermines the trust model of cryptocurrency_ and should therefore be considered only as a stepping stone toward more control and self-reliance.
There are many ways wallets can be characterized or categorized.
The most important questions to ask about a specific wallet are:
. Does this Lightning wallet have a full Lightning node or does it use a third-party Lightning node?
. Does this Lightning wallet have a full Bitcoin node or does it use a third-party Bitcoin node?
. Does this Lightning wallet store its own keys under user control (self-custody) or are the keys held by a third-party custodian?
[TIP]
====
If a Lightning wallet uses a third-party Lightning node, it is this third-party Lightning node that decides how to communicate with Bitcoin. Hence, using a third-party Lightning node implies that you are also using a third-party Bitcoin node. Only when the Lightning wallet uses its own Lightning node does the choice between full Bitcoin node and third-party Bitcoin node exist.
====
At the highest level of abstraction, Questions 1 and 3 are the most elementary ones.
From these two questions, we can derive four possible categories.
We can place these four categories into a quadrant, as seen in <<lnwallet-categories>>.
But remember that this is just one way of categorizing Lightning wallets.
[[lnwallet-categories]]
.Lightning wallets quadrant
[options="header"]
|===
| | *Full Lightning node* | *Third-party Lightning node*
| *Self-custody* | Q1: High technical skill, least trust in third parties, most permissionless | Q2: Below medium technical skills, below medium trust in third parties, requires some permissions
| *Custodial* | Q3: Above medium technical skills, above medium trust in third parties, requires some permissions | Q4: Low technical skills, high trust in third parties, least permissionless
|===
Quadrant 3 (Q3), where a full Lightning node is used, but the keys are held by a custodian, is currently not common.
Future wallets from that quadrant may let a user worry about the operational aspects of their node, but then delegate access to the keys to a third party which primarily uses cold storage.
Lightning wallets can be installed on a variety of devices, including laptops, servers, and mobile devices. To run a full Lightning node, you will need to use a server or desktop computer, because mobile devices and laptops are usually not powerful enough in terms of capacity, processing, battery life, and connectivity.
The category third-party Lightning nodes can again be subdivided:
Lightweight::
This means that the wallet does not operate a Lightning node and thus needs to obtain information about the Lightning Network over the internet from someone else's Lightning node.
None::
This means that not only is the Lightning node operated by a third party, but most of the wallet is operated by a third party in the cloud. This is a custodial wallet where someone else controls custody of the funds.
These subcategories are used in <<lnwallet-examples>>.
Other terms that need explanation in <<lnwallet-examples>> in the column "Bitcoin node" are:
Neutrino::
This wallet does not operate a Bitcoin node. Instead, a Bitcoin node operated by someone else (a third party) is accessed via the Neutrino Protocol.
Electrum::
This wallet does not operate a Bitcoin node. Instead, a Bitcoin node operated by someone else (a third party) is accessed via the Electrum Protocol.
Bitcoin Core::
This is an implementation of a Bitcoin node.
btcd::
This is another implementation of a Bitcoin node.
In <<lnwallet-examples>>, we see some examples of currently popular Lightning node and wallet applications for different types of devices. The list is sorted first by device type and then alphabetically.
[[lnwallet-examples]]
.Examples of popular Lightning wallets
[options="header"]
|===
| Application | Device | Lightning node | Bitcoin node | Keystore
| Blue Wallet | Mobile | None | None | Custodial
| Breez Wallet | Mobile | Full node | Neutrino | Self-custody
| Eclair Mobile | Mobile | Lightweight | Electrum | Self-custody
| lntxbot | Mobile | None | None | Custodial
| Muun | Mobile | Lightweight | Neutrino | Self-custody
| Phoenix Wallet | Mobile | Lightweight | Electrum | Self-custody
| Zeus | Mobile | Full node | Bitcoin Core/btcd | Self-custody
| Electrum | Desktop | Full node | Bitcoin Core/Electrum | Self-custody
| Zap Desktop | Desktop | Full node | Neutrino | Self-custody
| c-lightning | Server | Full node | Bitcoin Core | Self-custody
| Eclair Server | Server | Full node | Bitcoin Core/Electrum | Self-custody
| lnd | Server | Full node | Bitcoin Core/btcd | Self-custody
|===
[[testnet-bitcoin]]
==== Testnet Bitcoin
((("Lightning wallet","testnet bitcoin and")))((("testnet bitcoin (tBTC)")))The Bitcoin system offers an alternative chain for testing purposes called _testnet_, in contrast with the "normal" Bitcoin chain which is referred to as _mainnet_. On testnet, the currency is _testnet bitcoin_ (_tBTC_), which is a worthless copy of bitcoin used exclusively for testing. Every function of Bitcoin is replicated exactly, but the money is worth nothing, so you literally have nothing to lose!
Some Lightning wallets can also operate on testnet, allowing you to make Lightning payments with testnet bitcoin, without risking real funds. This is a great way to experiment with Lightning safely. Eclair Mobile, which Alice uses in this chapter, is one example of a Lightning wallet that supports testnet operation.
You can get some tBTC to play with from a _testnet bitcoin faucet_, which gives out free tBTC on demand. Here are a few testnet faucets:
++++
<ul class="simplelist">
<li><a href="https://coinfaucet.eu/en/btc-testnet/"><em>https://coinfaucet.eu/en/btc-testnet</em></a></li>
<li><a href="https://testnet-faucet.mempool.co/"><em>https://testnet-faucet.mempool.co/</em></a></li>
<li><a href="https://bitcoinfaucet.uo1.net/"><em>https://bitcoinfaucet.uo1.net/</em></a></li>
<li><a href="https://testnet.help/en/btcfaucet/testnet"><em>https://testnet.help/en/btcfaucet/testnet</em></a></li>
</ul>
++++
All of the examples in this book can be replicated exactly on testnet with tBTC, so you can follow along if you want without risking real money.(((range="endofrange", startref="ix_02_getting_started-asciidoc1")))
=== Balancing Complexity and Control
((("Lightning wallet","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, 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 will attempt to remove the burden of channel management from their users. To do so, they introduce central _hub nodes_ that all their wallets connect to automatically. While this trade-off simplifies the user interface and user experience, it introduces a single point of failure (SPoF) as these hub nodes become indispensable for the wallet's operation. Furthermore, relying on a "hub" like this can reduce user privacy since the hub knows the sender and potentially (if constructing the payment route on behalf of the user) also the recipient of each payment made by the user's wallet.
In the next section, we will return to our first user and walk through her first Lightning wallet setup. She has chosen a wallet that is more sophisticated than the easier custodial wallets. This allows us to show some of the underlying complexity and introduce some of the inner workings of an advanced wallet. You may find that your first ideal wallet is oriented toward ease of use, accepting some of the control and privacy trade-offs. Or perhaps you are more of a power user and want to run your own Lightning and Bitcoin nodes as part of your wallet solution.
=== Downloading and Installing a Lightning Wallet
((("Lightning wallet","downloading/installing")))When looking for a new cryptocurrency wallet, you must be very careful to select a secure source for the software.
Unfortunately, many fake wallet applications 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 may not just steal any money you entrust it with, but it might also be able to steal keys and passwords from other applications by compromising your mobile device operating system.
((("Eclair wallet, downloading/installing")))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/mtln_0201.png["Eclair wallet in the Google Play Store"]
[TIP]
====
It is possible to experiment and test all Bitcoin-type software with zero risk (except for your own time) by using testnet bitcoins. You can also download the Eclair testnet wallet to try Lightning (on testnet) by going to 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 ACINQfootnote:[ACINQ: Developers of the Eclair Mobile Lightning wallet (https://acinq.co/).] 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 that this is a rogue app that has snuck into the Google Play Store. As a third step, she goes to the https://acinq.co[ACINQ website]. She verifies that the web page is secure by checking that the address begins with https, or prefixed by a padlock in some browsers. On the website, she goes to the Download section or looks for the link to the Google App Store. She finds the link and clicks it. She compares that this link brings her to the very same app in the Google App 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
((("Lightning wallet","creating a new wallet", id="ix_02_getting_started-asciidoc2", range="startofrange")))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
((("keys","Lightning wallet and")))((("Lightning wallet","responsibility with key custody")))As we mentioned at the beginning of this section, Eclair is a _noncustodial_ 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 they 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
((("Lightning wallet","mnemonic phrase")))((("mnemonic phrase")))((("seed (mnemonic) phrase")))Similar to most Bitcoin wallets, Eclair Mobile provides a _mnemonic phrase_ (also sometimes called a "seed" or "seed 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. Alice can use the mnemonic phrase to restore all the transactions and funds in the Eclair Mobile wallet in the case of a lost mobile device, a software bug, or memory corruption.
[TIP]
====
The correct term for these backup words is "mnemonic phrase." We avoid the use of the term "seed" to refer to a mnemonic phrase because even though its use is common, it is incorrect.
====
When Alice chooses to create a new wallet, she will see a screen with her mnemonic phrase, which looks like the screenshot in <<eclair-mnemonic>>.
[[eclair-mnemonic]]
.New wallet mnemonic phrase
image::images/mtln_0202.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
((("Lightning wallet","mnemonic phrase storage")))Alice needs to be careful to store the mnemonic phrase in a way that prevents theft but also avoids 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&#x2014;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 isn'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 it on USB drives or cloud drives, encrypt it, or try any other nonstandard method. You will tip the balance in such a way as to risk permanent loss. Many people have lost funds, not from theft, but because they tried a nonstandard solution without having the expertise to balance the risks involved. The best practice recommendation is carefully considered by experts and suitable for the vast majority of users.
====
After Alice initializes her Eclair Mobile wallet, she will see a brief tutorial that 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!(((range="endofrange", startref="ix_02_getting_started-asciidoc2")))
=== Loading Bitcoin onto the Wallet
((("bitcoin (currency)","loading onto Lightning wallet", id="ix_02_getting_started-asciidoc3", range="startofrange")))((("Lightning wallet","loading bitcoin onto", id="ix_02_getting_started-asciidoc4", range="startofrange")))Alice now has a Lightning 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.
[TIP]
====
If Alice already has bitcoin in another wallet, she could choose to send that bitcoin to her Eclair wallet instead of acquiring new bitcoin to load onto her new wallet.
====
[[acquiring-bitcoin]]
==== Acquiring Bitcoin
((("bitcoin (currency)","acquiring for Lightning wallet")))((("Lightning wallet","acquiring bitcoin for")))There are several ways Alice can acquire bitcoin:
* She can exchange some of her national currency (e.g., USD) on a cryptocurrency 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.
==== Receiving Bitcoin
((("bitcoin (currency)","receiving for Lightning wallet", id="ix_02_getting_started-asciidoc5", range="startofrange")))((("Bitcoin ATM", id="ix_02_getting_started-asciidoc6", range="startofrange")))((("Lightning wallet","receiving bitcoin", id="ix_02_getting_started-asciidoc7", range="startofrange")))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>>. Such Bitcoin ATMs accept 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/mtln_0203.png["Lamassu Bitcoin ATM"]
To receive the bitcoin in her Eclair Lightning wallet, Alice will need to present a Bitcoin address from the Eclair Lightning wallet to the ATM. The ATM can then send Alice's newly acquired bitcoin to this Bitcoin address.
To see a Bitcoin address on the Eclair wallet, Alice must swipe to the left column titled YOUR BITCOIN ADDRESS (see <<eclair-receive>>), where she will see a square barcode (called a _QR code_) and a string of letters and numbers below that.
[[eclair-receive]]
.Alice's bitcoin address, shown in Eclair
image::images/mtln_0204.png["Eclair bitcoin address QR code"]
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/mtln_0205.png["Bitcoin ATM scans the QR code"]
Alice will see the transaction from the ATM in the TRANSACTION HISTORY tab of the Eclair wallet. Although Eclair will detect the bitcoin transaction 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 minimum of six confirmations, and her funds are now ready to use.
[TIP]
====
The number of confirmations on a transaction is the number of blocks mined since (and inclusive of) the block that contained that transaction. Six confirmations is best practice, but different Lightning wallets can consider a channel open after any number of confirmations. Some wallets even scale up the number of expected confirmations by the monetary value of the channel.
====
[[eclair-tx1]]
.Alice receives bitcoin
image::images/mtln_0206.png["Bitcoin transaction received"]
Although 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 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 to her client, and they could paste or scan 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 publicly to receive tips. For example, she could have a QR code affixed to her guitar and receive tips while performing on the street!footnote:[It is generally not advisable to reuse the same Bitcoin address for multiple payments because all Bitcoin transactions are public.
A nosy person passing by could scan Alice's QR code and see how many tips Alice has already received to this address on the Bitcoin blockchain.
Fortunately, the Lightning Network offers more private solutions to this, discussed later in the book!]
Finally, if Alice bought bitcoin from a cryptocurrency exchange, she could (and should) "withdraw" the bitcoin by pasting her Bitcoin address into the exchange website. The exchange will then send the bitcoin to her address directly(((range="endofrange", startref="ix_02_getting_started-asciidoc7")))(((range="endofrange", startref="ix_02_getting_started-asciidoc6")))(((range="endofrange", startref="ix_02_getting_started-asciidoc5"))).(((range="endofrange", startref="ix_02_getting_started-asciidoc4")))(((range="endofrange", startref="ix_02_getting_started-asciidoc3")))
=== From Bitcoin to Lightning Network
((("Lightning wallet","bridging of Bitcoin and Lightning networks", id="ix_02_getting_started-asciidoc8", range="startofrange")))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 the transaction has been 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 Lightning 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 to take advantage of the fast, cheap, and private payments that the Lightning Network offers.
==== Lightning Network Channels
((("Lightning Network channels","basics", id="ix_02_getting_started-asciidoc9", range="startofrange")))((("Lightning Network channels","opening a channel", id="ix_02_getting_started-asciidoc10", range="startofrange")))((("Lightning wallet","LN channels and", id="ix_02_getting_started-asciidoc11", range="startofrange")))Swiping right, Alice accesses the LIGHTNING CHANNELS section of Eclair. Here she can manage the channels that will connect her wallet to the Lightning Network.
Let's review the definition of an LN channel at this point, to make things a bit clearer. Firstly, the word "channel" is a metaphor for a _financial relationship_ between Alice's Lightning wallet and another Lightning 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).
((("channel peer")))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 (e.g., Bob's Lightning wallet) as long as Alice's wallet can find a viable _path_ made by hopping from channel to channel, all the way to Bob's wallet.
[TIP]
====
Not all channel peers are _good_ peers for routing payments. Well-connected peers will be able to route payments over shorter paths to the destination, increasing the chance of success. Channel peers with ample funds will be able to route larger payments.
====
In other words, 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 node in the Lightning Network can be used for Alice's first channel. The more well-connected a node is, the more people Alice can reach. 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 channels, so as we see in <<eclair-channels>>, the LIGHTNING CHANNELS tab displays an empty list. If you notice, in 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/mtln_0207.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 Lightning 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 then as a text string.
[[node-URI-QR]]
.Node URI as a QR code
image::images/mtln_0208.png["Lightning node URI QR code",width=120]
[[node-URI-example]]
.node URI
----
0237fefbe8626bf888de0cad8c73630e32746a22a2c4faa91c1d9877a3826e1174@1.ln.aantonop.com:9735
----
While Alice could select a specific Lightning 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 Lightning nodes.
Choosing the ACINQ node will slightly reduce Alice's privacy, because 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, we will gradually learn how to gain more independence and make fewer trade-offs!
Alice selects ACINQ Node and is ready to open her first channel on the Lightning Network.(((range="endofrange", startref="ix_02_getting_started-asciidoc11")))(((range="endofrange", startref="ix_02_getting_started-asciidoc10")))(((range="endofrange", startref="ix_02_getting_started-asciidoc9")))
==== Opening a Lightning Channel
((("Lightning wallet","opening a Lightning channel", id="ix_02_getting_started-asciidoc12", range="startofrange")))When Alice selects a node to open a new channel, she is asked to select how much bitcoin she wants to allocate 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 slightly less than her total balance.footnote:[The Eclair wallet doesn't offer an option to automatically calculate the necessary fees and allocate the maximum amount of funds to a channel, so Alice has to calculate this herself.]
Alice allocates 0.018 BTC of her 0.020 BTC total to her channel and accepts the default fee rate, as shown in <<eclair-open-channel>>.
[[eclair-open-channel]]
.Opening a Lightning channel
image::images/mtln_0209.png["Opening a Lightning Channel"]
Once she clicks OPEN, her wallet constructs the special Bitcoin transaction that ((("funding transaction")))opens a Lightning channel, known as the _funding transaction_. The on-chain 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 on 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/mtln_0210.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, funded, and ready, as shown in <<eclair-channel-open>>.
[[eclair-channel-open]]
.Channel is open
image::images/mtln_0211.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 will change(((range="endofrange", startref="ix_02_getting_started-asciidoc12")))!(((range="endofrange", startref="ix_02_getting_started-asciidoc8")))
====
=== Buying a Cup of Coffee Using the Lightning Network
((("Lightning Network (generally)","example: buying a cup of coffee", id="ix_02_getting_started-asciidoc13", range="startofrange")))((("Lightning wallet","example: buying a cup of coffee", id="ix_02_getting_started-asciidoc14", range="startofrange")))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 time waiting for confirmations. However, now subsequent actions are fast and easy. The Lightning Network enables payments without having to wait for confirmations, as funds get settled in seconds.
Alice grabs her mobile device and runs to Bob's Cafe in her neighborhood. She is excited to try her new Lightning 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 ecommerce 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 simple to install all the necessary software, upload pictures and product prices, and launch a store quickly.
On the counter at Bob's Cafe, there is a tablet device showing what you see in <<bob-cafe-posapp>>.
[[bob-cafe-posapp]]
.Bob's point-of-sale application
image::images/mtln_0212.png["Bob's Point-of-Sale Application"]
==== A Lightning Invoice
((("Lightning invoices", id="ix_02_getting_started-asciidoc15", range="startofrange")))((("Lightning wallet","invoices", id="ix_02_getting_started-asciidoc16", range="startofrange")))Alice selects the Cafe Latte option from the screen and is presented with a _Lightning invoice_ (also known as a "payment request"), as shown in <<bob-cafe-invoice>>.
[[bob-cafe-invoice]]
.Lightning invoice for Alice's latte
image::images/mtln_0213.png["BTCPay Server Lightning invoice"]
To pay the invoice, Alice opens her Eclair wallet and selects the Send button (which looks like an up-facing arrow) under the TRANSACTION HISTORY tab, as shown in <<alice-send-start>>.
[[alice-send-start]]
.Alice selecting Send
image::images/mtln_0214.png["Lightning transaction send",width=300]
[TIP]
====
The term "payment request" can refer to a Bitcoin payment request or a Lightning invoice, and the terms "invoice" and "payment request" are often used interchangeably. The correct technical term is "Lightning invoice," regardless of how it is named in the wallet.
====
Alice selects the option to "scan a payment request," 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/mtln_0215.png["Lightning transaction send confirmation",width=300]
Alice presses PAY, and a second later, Bob's tablet shows a successful payment. Alice has completed her first LN payment! It was fast, inexpensive, and easy. Now she can enjoy her latte which was purchased using bitcoin through a payment system that is fast, cheap, and decentralized. From now on, Alice can simply select an item on Bob's tablet screen, scan the QR code with her cell phone, click PAY, and be served a coffee, all within seconds and all without an on-chain transaction.
Lightning payments are better for Bob, too. He's confident that he will be paid for Alice's latte without waiting for an on-chain confirmation. In the future, whenever Alice feels like drinking a coffee at Bob's Cafe, she can choose to pay with bitcoin on the Bitcoin network or the Lightning Network. Which one do you think she will choose(((range="endofrange", startref="ix_02_getting_started-asciidoc16")))(((range="endofrange", startref="ix_02_getting_started-asciidoc15")))?(((range="endofrange", startref="ix_02_getting_started-asciidoc14")))(((range="endofrange", startref="ix_02_getting_started-asciidoc13")))
=== Conclusion
In this chapter, we followed Alice as she downloaded and installed her first Lightning wallet, acquired and transferred some bitcoin, opened her first Lightning channel, and bought a cup of coffee by making her first payment on the Lightning Network.(((range="endofrange", startref="ix_02_getting_started-asciidoc0"))) In the following chapters, we will look "under the covers" at how each component in the Lightning Network works and how Alice's payment reached Bob's Cafe.