Skip to content

Commit 1543451

Browse files
authored
Update 02_getting_started (bitcoin#648)
Moved Alice introduction paragraph to the beginning Added TODO for link to bitcoin basics guide / fundamentals Moved Testnet Bitcoin section to wallets Added tip about Alice being able to transfer bitcoin she already owns to her new Eclair wallet Fixed typo Added language about Bob's perspective just before conclusion
1 parent 80cc432 commit 1543451

File tree

1 file changed

+39
-30
lines changed

1 file changed

+39
-30
lines changed

02_getting_started.asciidoc

Lines changed: 39 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,16 @@
33

44
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 Lightning Network 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.
55

6+
=== Alice's First Lightning Wallet
7+
8+
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. If you are not yet familiar with how Bitcoin transactions work, please read before moving on.
9+
10+
// TODO: add language to reference bitcoin basics guide
11+
12+
Alice recently learned that Bob's Cafe just started accepting Lightning Network payments! Alice is eager to learn about and experiment with the Lightning Network, she wants to be one of Bob's first Lightning Network customers. In order to do this, first, Alice has to select a Lightning wallet that meets her needs.
13+
14+
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 Lightning wallet. Let's learn more about how and why she's made these choices.
15+
616
=== Lightning Nodes
717

818
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, 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.
@@ -124,6 +134,25 @@ In <<lnwallet-examples>> we see some examples of currently popular Lightning nod
124134
| Eclair Server | Server | Full Node | Bitcoin Core/Electrum | Self-Custody
125135
|===
126136

137+
[[testnet-bitcoin]]
138+
==== Testnet Bitcoin
139+
140+
The Bitcoin system offers an alternative chain for testing purposes called a _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!
141+
142+
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.
143+
144+
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:
145+
146+
https://coinfaucet.eu/en/btc-testnet/
147+
148+
https://testnet-faucet.mempool.co/
149+
150+
https://bitcoinfaucet.uo1.net/
151+
152+
https://testnet.help/en/btcfaucet/testnet
153+
154+
All of the examples in this book can be replicated exactly on testnet with TBTC, so you can try and follow along if you want without risking real money.
155+
127156
=== Balancing complexity and control
128157

129158
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.
@@ -132,13 +161,7 @@ When selecting a wallet, keep in mind that even if you don't see these trade-off
132161

133162
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 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 Lightning and Bitcoin nodes as part of your wallet solution.
134163

135-
=== Alice's First Lightning Wallet
136-
137-
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 a Lightning wallet that meets her needs.
138-
139-
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 Lightning wallet.
140-
141-
==== Downloading and Installing a Lightning Wallet
164+
=== Downloading and Installing a Lightning Wallet
142165

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

@@ -213,6 +236,11 @@ After Alice initializes her Eclair Mobile wallet, she will see a brief tutorial
213236

214237
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.
215238

239+
[TIP]
240+
====
241+
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.
242+
====
243+
216244
[[acquiring-bitcoin]]
217245
==== Acquiring Bitcoin
218246

@@ -221,31 +249,11 @@ There are several ways Alice can acquire bitcoin:
221249
* She can exchange some of her national currency (e.g. USD) at a cryptocurrency exchange
222250
* She can buy some from a friend, or an acquaintance from a Bitcoin Meetup, in exchange for cash
223251
* She can find a _Bitcoin ATM_ in her area, which acts as a vending machine, selling bitcoin for cash
224-
* She can offer her skills or a product she sells and accepts payment in bitcoin
252+
* She can offer her skills or a product she sells and accept payment in bitcoin
225253
* She can ask her employer or clients to pay her in bitcoin
226254

227-
228255
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.
229256

230-
[[testnet-bitcoin]]
231-
==== Testnet Bitcoin
232-
233-
The Bitcoin system offers an alternative chain for testing purposes called a _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!
234-
235-
Somme 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.
236-
237-
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:
238-
239-
https://coinfaucet.eu/en/btc-testnet/
240-
241-
https://testnet-faucet.mempool.co/
242-
243-
https://bitcoinfaucet.uo1.net/
244-
245-
https://testnet.help/en/btcfaucet/testnet
246-
247-
All of the examples in this book can be replicated exactly on testnet with TBTC, so you can try and follow along if you want without risking real money.
248-
249257
==== Receiving Bitcoin
250258

251259
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.
@@ -383,7 +391,7 @@ image::images/eclair-channel-open.png["Channel is Open"]
383391
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!
384392
====
385393

386-
=== Buying a Cup of Coffee
394+
=== Buying a Cup of Coffee using LN
387395

388396
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.
389397

@@ -430,8 +438,9 @@ Alice selects the option to "scan a payment request" and scans the QR code displ
430438
.Alice's Send Confirmation
431439
image::images/alice-send-detail.png["Lightning transaction send confirmation",width=300]
432440

433-
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 a payment system that is fast, cheap and decentralized. And from now on, whenever Alice feels like drinking a coffee at Bob's Cafe she selects an item on Bob's tablet screen, scans the QR code with her cell phone, clicks pay, and is served a coffee, all within seconds and all without an "on-chain" transaction.
441+
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 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.
434442

443+
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?
435444

436445
=== Conclusion
437446

0 commit comments

Comments
 (0)